Add copying to clipboard using OSC52

Many terminal emulators support copying text to clipboard using
ANSI OSC Ps; PT ST with Ps = 5 2, see
https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

This enables copying even through SSH and terminal multiplexers.

Author: Naseschwarz

Cargo.toml

@@ -47,7 +47,11 @@ use-dev-tty = ["filedescriptor", "rustix/process"]
 ## Enables `is_*` helper functions for event enums.
 derive-more = ["dep:derive_more"]
 
+## Enables interacting with a host clipboard via [`clipboard`](clipboard/index.html)
+clipboard = ["dep:base64"]
+
 [dependencies]
+base64 = { version = "0.22", optional = true }
 bitflags = { version = "2.3" }
 derive_more = { version = "1.0.0", features = ["is_variant"], optional = true }
 document-features = "0.2.10"
@@ -112,3 +116,7 @@ required-features = ["events"]
 [[example]]
 name = "key-display"
 required-features = ["events"]
+
+[[example]]
+name = "copy"
+required-features = ["clipboard"]

README.md

@@ -154,6 +154,7 @@ features = ["event-stream"]
 | `events`        | Reading input/system events (enabled by default) |
 | `filedescriptor` | Use raw filedescriptor for all events rather then mio dependency |
 | `derive-more`  | Adds `is_*` helper functions for event types |
+| `clipboard`    | Enables crossterm::clipboard                 |
 
 
 To use crossterm as a very thin layer you can disable the `events` feature or use `filedescriptor` feature. 
@@ -172,6 +173,7 @@ This can disable `mio` / `signal-hook` / `signal-hook-mio` dependencies.
 | `futures-core` | For async stream of events                                                       | only with `event-stream` feature flag |
 | `serde`        | ***ser***ializing and ***de***serializing of events                              | only with `serde` feature flag        |
 | `derive_more`  | Adds `is_*` helper functions for event types                                     | optional (`derive-more` feature), included by default |
+| `base64`       | Encoding clipboard data for OSC52 sequences in crossterm::clipboard              | only with `clipboard` feature flag    |
 
 ### Other Resources
 

examples/copy.rs

@@ -0,0 +1,46 @@
+//! Demonstrates copying a string to clipboard
+//!
+//! This example uses OSC control sequence `Pr = 5 2` (See
+//! <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands)>
+//! to copy data to the terminal host clipboard.
+//!
+//! This only works if it is enabled on the respective terminal emulator. If a terminal multiplexer
+//! is used, the multiplexer will likely need to support it, too.
+//!
+//! ```no_run
+//! cargo run --example copy -- --clipboard "Some String"
+//! cargo run --example copy -- --primary "Some String"
+//! cargo run --example copy -- "Some String"
+//! ```
+
+use std::io;
+
+use crossterm::clipboard;
+use crossterm::execute;
+
+fn main() -> io::Result<()> {
+    let mut stdout = io::stdout();
+    let mut args = std::env::args();
+    args.next(); // Skip to first argument
+
+    let default_text = String::from("Example text");
+    let (text, dest) = match args.next().as_deref() {
+        Some("--clipboard") => (
+            args.next().unwrap_or(default_text),
+            clipboard::ClipboardType::Clipboard,
+        ),
+        Some("--primary") => (
+            args.next().unwrap_or(default_text),
+            clipboard::ClipboardType::Primary,
+        ),
+        Some(text) => (text.to_owned(), clipboard::ClipboardType::Clipboard),
+        None => (default_text, clipboard::ClipboardType::Clipboard),
+    };
+    execute!(
+        stdout,
+        clipboard::CopyToClipboard {
+            content: text,
+            destination: clipboard::ClipboardSelection(vec![dest])
+        }
+    )
+}

src/clipboard.rs

@@ -0,0 +1,294 @@
+//! # Clipboard
+//!
+//! The `clipboard` module provides functionality to work with a host clipboard.
+//!
+//! ## Implemented operations:
+//!
+//! - Copy: [`CopyToClipboard`](struct.CopyToClipboard.html)
+use base64::prelude::{Engine, BASE64_STANDARD};
+
+use std::fmt;
+use std::str::FromStr;
+
+#[doc(no_inline)]
+use crate::{osc, Command};
+
+/// Different clipboard types
+///
+/// See <https://specifications.freedesktop.org/clipboard-spec/latest/> for more info
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ClipboardType {
+    /// Default clipboard when using Ctrl+C or Ctrl+V
+    Clipboard,
+
+    /// Clipboard on Linux/X/Wayland when using selection and middle mouse button
+    Primary,
+
+    /// Other clipboard type not explicitly supported by crossterm
+    /// See
+    /// [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands)
+    /// for potential values.
+    ///
+    /// Note that support for these in terminal emulators is very limited.
+    Other(char),
+}
+
+impl Into<char> for &ClipboardType {
+    fn into(self) -> char {
+        match self {
+            ClipboardType::Clipboard => 'c',
+            ClipboardType::Primary => 'p',
+            ClipboardType::Other(other) => *other,
+        }
+    }
+}
+
+impl From<char> for ClipboardType {
+    fn from(value: char) -> Self {
+        match value {
+            'c' => ClipboardType::Clipboard,
+            'p' => ClipboardType::Primary,
+            other => ClipboardType::Other(other),
+        }
+    }
+}
+
+/// A sequence of clipboard types
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClipboardSelection(
+    /// This being an ordered sequence is important due to deviations from the
+    /// [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands)
+    /// reference. Some terminal emulators may only interpret the first
+    /// character of this parameter.
+    /// For differences, see [`CopyToClipboard` (Terminal Support)](struct.CopyToClipboard.html#terminal-support).
+    pub Vec<ClipboardType>,
+);
+
+impl ToString for ClipboardSelection {
+    fn to_string(&self) -> String {
+        self.0.iter().map(Into::<char>::into).collect()
+    }
+}
+
+impl FromStr for ClipboardSelection {
+    type Err = ();
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(ClipboardSelection(
+            s.chars().map(From::<char>::from).collect(),
+        ))
+    }
+}
+
+/// A command that copies to clipboard
+///
+/// # Notes
+///
+/// This command uses OSC control sequence `Pr = 5 2` (See
+/// [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) )
+/// to copy data to the terminal host clipboard.
+///
+/// This only works if it is enabled on the respective terminal emulator. If a terminal multiplexer
+/// is used, the multiplexer will likely need to support it, too.
+///
+/// Commands must be executed/queued for execution otherwise they do nothing.
+///
+/// # Examples
+///
+/// ```no_run
+/// use crossterm::execute;
+/// use crossterm::clipboard::CopyToClipboard;
+/// // Copy foo to clipboard
+/// execute!(std::io::stdout(), CopyToClipboard::into_clipboard_from("foo"));
+/// // Copy bar to primary
+/// execute!(std::io::stdout(), CopyToClipboard::into_primary_from("bar"));
+/// ```
+///
+/// See also examples/copy.rs.
+///
+/// # Terminal Support
+///
+/// The following table shows what destinations are filled by different terminal emulators when
+/// asked to copy to different destination sequences.
+///
+/// | Terminal (Version)  | Test System | Copy to ''  | Copy to 'c'  | Copy to 'p' | Copy to 'cp'       | Copy to 'pc'       |
+/// | ------------------- | ----------- | ----------- | ------------ | ----------- | ------------------ | ------------------ |
+/// | xterm (397)         | 1           | primary     | clipboard    | primary     | clipboard, primary | clipboard, primary |
+/// | Alacritty (0.15.1)  | 1           | clipboard   | clipboard    | primary     | clipboard          | primary            |
+/// | Wezterm (*1)        | 1           | clipboard   | clipboard    | primary     | clipboard          | clipboard          |
+/// | Konsole (24.12.3)   | 1           | clipboard   | clipboard    | primary     | clipboard, primary | clipboard, primary |
+/// | Kitty (0.40.0)      | 1           | clipboard   | clipboard    | primary     | clipboard          | clipboard          |
+/// | foot (1.20.2)       | 1           | clipboard   | clipboard    | primary     | clipboard, primary | clipboard, primary |
+/// | tmux (3.5a)         | 1, *2       | primary     | clipboard    | primary     | clipboard, primary | clipboard, primary |
+///
+/// Test systems were the following:
+/// 1. Wayland with [primary selection protocol](https://wayland.app/protocols/primary-selection-unstable-v1) enabled.
+///
+/// Asterisks:
+/// 1. 20240203-110809-5046fc22
+/// 2. set-clipboard set to external, i.e. this is OSC52 pass-through
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CopyToClipboard<T> {
+    /// Content to be copied
+    pub content: T,
+    /// Sequence of copy destinations
+    ///
+    /// Not all sequences are equally supported by terminal emulators. See
+    /// [`CopyToClipboard` (Terminal Support)](struct.CopyToClipboard.html#terminal-support).
+    pub destination: ClipboardSelection,
+}
+
+impl<T: AsRef<[u8]>> Command for CopyToClipboard<T> {
+    fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
+        write!(
+            f,
+            osc!("52;{destination};{encoded_text}"),
+            destination = self.destination.to_string(),
+            encoded_text = BASE64_STANDARD.encode(&self.content)
+        )
+    }
+
+    #[cfg(windows)]
+    fn execute_winapi(&self) -> std::io::Result<()> {
+        use std::io;
+
+        Err(io::Error::new(
+            io::ErrorKind::Unsupported,
+            "Copying is not implemented for the Windows API.",
+        ))
+    }
+}
+
+impl<T: AsRef<[u8]>> CopyToClipboard<T> {
+    /// Construct a [`CopyToClipboard`] that writes content into the
+    /// "clipboard" (or 'c') clipboard selection.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use crossterm::{execute, Command};
+    /// use crossterm::clipboard::CopyToClipboard;
+    /// execute!(std::io::stdout(), CopyToClipboard::into_clipboard_from("foo"));
+    /// ```
+    pub fn into_clipboard_from(content: T) -> CopyToClipboard<T> {
+        CopyToClipboard {
+            content,
+            destination: ClipboardSelection(vec![ClipboardType::Clipboard]),
+        }
+    }
+
+    /// Construct a [`CopyToClipboard`] that writes content into the "primary"
+    /// (or 'p') clipboard selection.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use crossterm::execute;
+    /// use crossterm::clipboard::CopyToClipboard;
+    /// execute!(std::io::stdout(), CopyToClipboard::into_primary_from("foo"));
+    /// ```
+    pub fn into_primary_from(content: T) -> CopyToClipboard<T> {
+        CopyToClipboard {
+            content,
+            destination: ClipboardSelection(vec![ClipboardType::Primary]),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_clipboard_string_to_selection() {
+        assert_eq!(
+            ClipboardSelection::from_str("p").unwrap(),
+            ClipboardSelection(vec![ClipboardType::Primary])
+        );
+        assert_eq!(
+            ClipboardSelection::from_str("").unwrap(),
+            ClipboardSelection(vec![])
+        );
+        assert_eq!(
+            ClipboardSelection::from_str("cp").unwrap(),
+            ClipboardSelection(vec![ClipboardType::Clipboard, ClipboardType::Primary])
+        );
+    }
+    #[test]
+    fn test_clipboard_selection_to_string() {
+        assert_eq!(ClipboardSelection(vec![]).to_string(), "");
+        assert_eq!(
+            ClipboardSelection(vec![ClipboardType::Clipboard]).to_string(),
+            "c"
+        );
+        assert_eq!(
+            ClipboardSelection(vec![ClipboardType::Primary]).to_string(),
+            "p"
+        );
+        assert_eq!(
+            ClipboardSelection(vec![ClipboardType::Primary, ClipboardType::Clipboard]).to_string(),
+            "pc"
+        );
+        assert_eq!(
+            ClipboardSelection(vec![ClipboardType::Clipboard, ClipboardType::Primary]).to_string(),
+            "cp"
+        );
+        assert_eq!(
+            ClipboardSelection(vec![ClipboardType::Other('s')]).to_string(),
+            "s"
+        );
+    }
+
+    #[test]
+    fn test_clipboard_copy_string_osc52() {
+        let mut buffer = String::new();
+        super::CopyToClipboard {
+            content: "foo",
+            destination: ClipboardSelection(vec![ClipboardType::Clipboard]),
+        }
+        .write_ansi(&mut buffer)
+        .unwrap();
+        assert_eq!(buffer, "\x1b]52;c;Zm9v\x1b\\");
+
+        buffer.clear();
+        super::CopyToClipboard {
+            content: "foo",
+            destination: ClipboardSelection(vec![ClipboardType::Primary]),
+        }
+        .write_ansi(&mut buffer)
+        .unwrap();
+        assert_eq!(buffer, "\x1b]52;p;Zm9v\x1b\\");
+
+        buffer.clear();
+        super::CopyToClipboard {
+            content: "foo",
+            destination: ClipboardSelection(vec![ClipboardType::Primary, ClipboardType::Clipboard]),
+        }
+        .write_ansi(&mut buffer)
+        .unwrap();
+        assert_eq!(buffer, "\x1b]52;pc;Zm9v\x1b\\");
+
+        buffer.clear();
+        super::CopyToClipboard {
+            content: "foo",
+            destination: ClipboardSelection(vec![]),
+        }
+        .write_ansi(&mut buffer)
+        .unwrap();
+        assert_eq!(buffer, "\x1b]52;;Zm9v\x1b\\");
+    }
+
+    #[test]
+    fn test_clipboard_copy_string_osc52_constructor() {
+        let mut buffer = String::new();
+        super::CopyToClipboard::into_clipboard_from("foo")
+            .write_ansi(&mut buffer)
+            .unwrap();
+        assert_eq!(buffer, "\x1b]52;c;Zm9v\x1b\\");
+
+        let mut buffer = String::new();
+        super::CopyToClipboard::into_primary_from("foo")
+            .write_ansi(&mut buffer)
+            .unwrap();
+        assert_eq!(buffer, "\x1b]52;p;Zm9v\x1b\\");
+    }
+}

src/lib.rs

@@ -66,6 +66,9 @@
 //!     [`EnableLineWrap`](terminal/struct.EnableLineWrap.html)
 //!   - Alternate screen - [`EnterAlternateScreen`](terminal/struct.EnterAlternateScreen.html),
 //!     [`LeaveAlternateScreen`](terminal/struct.LeaveAlternateScreen.html)
+//! - Module [`clipboard`](clipboard/index.html) (requires
+//!     [`feature = "clipboard"`](#optional-features))
+//!   - Clipboard - [`CopyToClipboard`](clipboard/struct.CopyToClipboard.html)
 //!
 //! ### Command Execution
 //!
@@ -246,6 +249,10 @@ pub mod terminal;
 /// A module to query if the current instance is a tty.
 pub mod tty;
 
+/// A module for clipboard interaction
+#[cfg(feature = "clipboard")]
+pub mod clipboard;
+
 #[cfg(windows)]
 /// A module that exposes one function to check if the current terminal supports ANSI sequences.
 pub mod ansi_support;