Add copying to clipboard using OSC52 (crossterm-rs#974)

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.

Co-authored-by: Naseschwarz <naseschwarz@0x53a.de>

Author: naseschwarz

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+## Added ⭐
+
+- Copy to clipboard using OSC52 (#974)
+
 # Version 0.28.1
 
 ## Fixed 🐛

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)
+osc52 = ["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-to-clipboard"
+required-features = ["osc52"]

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 |
+| `osc52`        | 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 `osc52` feature flag        |
 
 ### Other Resources
 

examples/copy-to-clipboard.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-to-clipboard -- --clipboard "Some String"
+//! cargo run --example copy-to-clipboard -- --primary "Some String"
+//! cargo run --example copy-to-clipboard -- "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])
+        }
+    )
+}