//! Putting text on the clipboard of whatever terminal is drawing the board. //! //! OSC 52, written by hand, and the reasoning is in AGENTS.md under The Copy Key. The //! short of it: the board is often being read over ssh, and an escape sequence is the //! only one of the three ways that crosses the connection. crossterm 0.28 is what //! ratatui 0.29 pins and it ships no clipboard command, so the sequence and the base64 //! it carries are written here rather than pulled in. //! //! The honest limit is that a terminal which ignores OSC 52 ignores it silently: what //! this reports is whether the sequence was written, not whether it was honoured. use std::io::Write; use anyhow::{Context, Result}; /// Ask the terminal to put `text` on the system clipboard. /// /// `52;c` is the clipboard proper rather than `p`, the X11 primary selection, because /// this is for pasting into a command line with ctrl-shift-v or cmd-v. Terminated with /// BEL rather than ST: both are accepted, and BEL is what tmux's `set-clipboard` /// documents and what every emulator that implements this at all takes. /// /// Written straight to stdout, which is where ratatui's own frames go, and flushed /// before returning so a failure belongs to this call rather than to the next draw. pub fn copy(text: &str) -> Result<()> { let mut out = std::io::stdout(); write!(out, "\x1b]52;c;{}\x07", base64(text.as_bytes())) .and_then(|()| out.flush()) .context("could not write to the terminal") } /// Standard base64, the alphabet OSC 52 requires, padding included. /// /// Twenty lines against a dependency: the only thing encoded here is a seven-character /// id, and the crate would be carried for its own sake. fn base64(bytes: &[u8]) -> String { const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"; let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4); for chunk in bytes.chunks(3) { // The missing bytes of a short chunk read as zero, and the characters they // would have produced are the ones that become padding below. let triple = chunk .iter() .chain([0u8; 2].iter()) .take(3) .fold(0u32, |acc, byte| (acc << 8) | u32::from(*byte)); for slot in 0..4 { match slot <= chunk.len() { true => out.push(char::from(ALPHABET[(triple >> (18 - 6 * slot) & 0x3f) as usize])), false => out.push('='), } } } out } #[cfg(test)] mod tests { use super::*; /// The vectors from RFC 4648, which is what a terminal decodes with. Every chunk /// length is in here, so the padding is covered in both of its forms. #[test] fn base64_encodes_the_rfc_vectors() { assert_eq!(base64(b""), ""); assert_eq!(base64(b"f"), "Zg=="); assert_eq!(base64(b"fo"), "Zm8="); assert_eq!(base64(b"foo"), "Zm9v"); assert_eq!(base64(b"foob"), "Zm9vYg=="); assert_eq!(base64(b"fooba"), "Zm9vYmE="); assert_eq!(base64(b"foobar"), "Zm9vYmFy"); } /// What actually goes on the wire for a short id, which is the whole use. #[test] fn base64_encodes_a_short_id() { assert_eq!(base64(b"0546fc5"), "MDU0NmZjNQ=="); } /// The high bits reach the end of the alphabet, which an off-by-one in the shift /// would miss entirely on ascii input. #[test] fn base64_reaches_the_whole_alphabet() { assert_eq!(base64(&[0xff, 0xff, 0xff]), "////"); assert_eq!(base64(&[0xfb, 0xff, 0xfe]), "+//+"); assert_eq!(base64(&[0x00, 0x00, 0x00]), "AAAA"); } }