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 copying to terminal via the CopyToClipboard command
+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"]

examples/copy.rs

@@ -0,0 +1,40 @@
+//! 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.
+//!
+//! 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::execute;
+use crossterm::terminal::{ClipboardDestination, CopyToClipboard};
+
+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),
+            ClipboardDestination::Clipboard,
+        ),
+        Some("--primary") => (
+            args.next().unwrap_or(default_text),
+            ClipboardDestination::Primary,
+        ),
+        Some(text) => (text.to_owned(), ClipboardDestination::Clipboard),
+        None => (default_text, ClipboardDestination::Clipboard),
+    };
+    execute!(stdout, CopyToClipboard(text, dest))
+}

src/lib.rs

@@ -63,7 +63,8 @@
 //!     [`SetSize`](terminal/struct.SetSize.html),
 //!     [`SetTitle`](terminal/struct.SetTitle.html),
 //!     [`DisableLineWrap`](terminal/struct.DisableLineWrap.html),
-//!     [`EnableLineWrap`](terminal/struct.EnableLineWrap.html)
+//!     [`EnableLineWrap`](terminal/struct.EnableLineWrap.html),
+//!     [`CopyToClipboard`](terminal/struct.CopyToClipboard.html)
 //!   - Alternate screen - [`EnterAlternateScreen`](terminal/struct.EnterAlternateScreen.html),
 //!     [`LeaveAlternateScreen`](terminal/struct.LeaveAlternateScreen.html)
 //!

src/macros.rs

@@ -1,10 +1,18 @@
-/// Append a the first few characters of an ANSI escape code to the given string.
+/// Concatenate string literals while prepending a ANSI control sequence introducer (`"\x1b["`)
 #[macro_export]
 #[doc(hidden)]
 macro_rules! csi {
     ($( $l:expr ),*) => { concat!("\x1B[", $( $l ),*) };
 }
 
+/// Concatenate string literals while prepending a xterm Operating System Commands (OSC)
+/// introducer (`"\x1b]"`) and appending a BEL (`"\x07"`).
+#[macro_export]
+#[doc(hidden)]
+macro_rules! osc {
+    ($( $l:expr ),*) => { concat!("\x1B]", $( $l ),*, "\x07") };
+}
+
 /// Queues one or more command(s) for further execution.
 ///
 /// Queued commands must be flushed to the underlying device to be executed.

src/terminal.rs

@@ -85,13 +85,17 @@
 
 use std::{fmt, io};
 
+#[cfg(feature = "clipboard")]
+use base64::prelude::{Engine, BASE64_STANDARD};
 #[cfg(windows)]
 use crossterm_winapi::{ConsoleMode, Handle, ScreenBuffer};
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 #[cfg(windows)]
 use winapi::um::wincon::ENABLE_WRAP_AT_EOL_OUTPUT;
 
+#[cfg(feature = "clipboard")]
+use crate::osc;
 #[doc(no_inline)]
 use crate::Command;
 use crate::{csi, impl_display};
@@ -396,6 +400,63 @@ impl<T: fmt::Display> Command for SetTitle<T> {
     }
 }
 
+/// Different clipboard classes
+#[cfg(feature = "clipboard")]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClipboardDestination {
+    /// Default clipboard when using Ctrl+C or Ctrl+V
+    Clipboard,
+
+    /// Clipboard on Linux/X/Wayland when using selection and middle mouse button
+    Primary,
+}
+
+/// 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
+///
+/// See examples/copy.rs for a working example.
+#[cfg(feature = "clipboard")]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CopyToClipboard<T>(pub T, pub ClipboardDestination);
+
+#[cfg(feature = "clipboard")]
+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 = match self.1 {
+                ClipboardDestination::Clipboard => 'c',
+                ClipboardDestination::Primary => 'p',
+            },
+            encoded_text = BASE64_STANDARD.encode(&self.0)
+        )
+    }
+
+    #[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.",
+        ))
+    }
+
+}
+
 /// A command that instructs the terminal emulator to begin a synchronized frame.
 ///
 /// # Notes
@@ -565,4 +626,20 @@ mod tests {
         // check we're back to normal mode
         assert!(!is_raw_mode_enabled().unwrap());
     }
+
+    #[test]
+    #[cfg(feature = "clipboard")]
+    fn test_copy_string_osc52() {
+        let mut buffer = String::new();
+        super::CopyToClipboard("foo", ClipboardDestination::Clipboard)
+            .write_ansi(&mut buffer)
+            .unwrap();
+        assert_eq!(buffer, "\x1b]52;c;Zm9v\x07");
+
+        buffer.clear();
+        super::CopyToClipboard("foo", ClipboardDestination::Primary)
+            .write_ansi(&mut buffer)
+            .unwrap();
+        assert_eq!(buffer, "\x1b]52;p;Zm9v\x07");
+    }
 }