#[cfg(feature = "desktop")]
mod desktop;
mod image;
pub use image::{ImageError, MAX_IMAGE_PIXELS, RgbaImage, decode_png, encode_png};
#[cfg(feature = "desktop")]
pub use desktop::ArboardClipboard;
pub trait Clipboard: Send {
fn read_text(&mut self) -> Result<Option<String>, ClipboardError>;
fn write_text(&mut self, text: &str) -> Result<(), ClipboardError>;
fn read_image(&mut self) -> Result<Option<RgbaImage>, ClipboardError> {
Ok(None)
}
fn write_image(&mut self, image: &RgbaImage) -> Result<(), ClipboardError> {
let _ = image;
Err(ClipboardError::Unavailable(
"this clipboard does not support images".to_owned(),
))
}
}
pub fn read_payload(
clipboard: &mut dyn Clipboard,
images: bool,
) -> Result<(Option<String>, Option<RgbaImage>), ClipboardError> {
let text = clipboard.read_text()?.filter(|text| !text.contains('\0'));
let is_content = text
.as_deref()
.is_some_and(|text| !text.trim().is_empty() && !refers_to_image(text));
if is_content || !images {
return Ok((text, None));
}
match clipboard.read_image()? {
Some(image) => Ok((None, Some(image))),
None => Ok((text, None)),
}
}
pub fn refers_to_image(text: &str) -> bool {
let text = text.trim();
let lines: Vec<&str> = text
.lines()
.map(str::trim)
.filter(|line| !line.is_empty())
.collect();
let is_link = |line: &str| {
let lower = line.to_ascii_lowercase();
["http://", "https://", "file://"]
.iter()
.any(|scheme| lower.starts_with(scheme))
&& !line.contains(char::is_whitespace)
};
if lines.len() <= 2 && lines.first().is_some_and(|line| is_link(line)) {
return true;
}
let mut html = text.to_ascii_lowercase();
while let Some(rest) = html.trim_start().strip_prefix("<meta") {
match rest.find('>') {
Some(end) => html = rest[end + 1..].to_owned(),
None => return false,
}
}
let html = html.trim();
html.starts_with("<img")
&& html
.find('>')
.is_some_and(|end| html[end + 1..].trim().is_empty())
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ClipboardError {
#[error("clipboard unavailable: {0}")]
Unavailable(String),
#[error("clipboard error: {0}")]
Other(String),
}
#[cfg(test)]
mod tests {
use super::*;
use crate::testing::MockClipboard;
#[test]
fn mock_serves_scripted_reads_then_the_current_text() {
let mock = MockClipboard::new().with_reads([None, Some("a"), Some("b")]);
let mut clip: Box<dyn Clipboard> = Box::new(mock.clone());
assert_eq!(clip.read_text().unwrap(), None);
assert_eq!(clip.read_text().unwrap().as_deref(), Some("a"));
assert_eq!(clip.read_text().unwrap().as_deref(), Some("b"));
assert_eq!(
clip.read_text().unwrap().as_deref(),
Some("b"),
"script exhausted: current text"
);
}
#[test]
fn mock_records_writes_and_shares_state_between_clones() {
let mock = MockClipboard::with_text("start");
let mut clip = mock.clone();
assert_eq!(clip.read_text().unwrap().as_deref(), Some("start"));
clip.write_text("one").unwrap();
clip.write_text("two").unwrap();
assert_eq!(mock.writes(), ["one", "two"]);
assert_eq!(mock.current().as_deref(), Some("two"));
assert_eq!(clip.read_text().unwrap().as_deref(), Some("two"));
}
#[test]
fn mock_injects_errors() {
let mock = MockClipboard::new();
let mut clip = mock.clone();
mock.push_read_error(ClipboardError::Unavailable("no display".into()));
assert_eq!(
clip.read_text().unwrap_err(),
ClipboardError::Unavailable("no display".into())
);
assert_eq!(clip.read_text().unwrap(), None);
mock.fail_writes(true);
assert!(clip.write_text("x").is_err());
assert!(mock.writes().is_empty());
}
#[test]
fn errors_describe_themselves() {
assert_eq!(
ClipboardError::Unavailable("no display".into()).to_string(),
"clipboard unavailable: no display"
);
assert_eq!(
ClipboardError::Other("busy".into()).to_string(),
"clipboard error: busy"
);
}
struct TextOnly;
impl Clipboard for TextOnly {
fn read_text(&mut self) -> Result<Option<String>, ClipboardError> {
Ok(None)
}
fn write_text(&mut self, _: &str) -> Result<(), ClipboardError> {
Ok(())
}
}
#[test]
fn text_only_clipboards_have_no_images() {
let mut clip = TextOnly;
assert_eq!(clip.read_image().unwrap(), None);
let image = RgbaImage::new(1, 1, vec![1, 2, 3, 4]).unwrap();
assert!(matches!(
clip.write_image(&image),
Err(ClipboardError::Unavailable(_))
));
}
#[test]
fn the_mock_keeps_either_text_or_an_image_like_a_real_clipboard() {
let image = RgbaImage::new(1, 1, vec![1, 2, 3, 4]).unwrap();
let other = RgbaImage::new(1, 1, vec![5, 6, 7, 8]).unwrap();
let mock = MockClipboard::with_image(image.clone());
let mut clip = mock.clone();
assert_eq!(clip.read_text().unwrap(), None);
assert_eq!(clip.read_image().unwrap(), Some(image.clone()));
clip.write_text("words").unwrap();
assert_eq!(clip.read_image().unwrap(), None, "text replaces the image");
clip.write_image(&other).unwrap();
assert_eq!(
clip.read_text().unwrap(),
None,
"an image replaces the text"
);
assert_eq!(mock.image_writes(), std::slice::from_ref(&other));
assert_eq!(mock.current_image(), Some(other.clone()));
let scripted = MockClipboard::new().with_image_reads([Some(image.clone()), None]);
let mut clip = scripted.clone();
assert_eq!(clip.read_image().unwrap(), Some(image.clone()));
assert_eq!(clip.read_image().unwrap(), None);
}
#[cfg(feature = "desktop")]
static DESKTOP_CLIPBOARD: std::sync::Mutex<()> = std::sync::Mutex::new(());
#[cfg(feature = "desktop")]
#[test]
#[ignore = "needs a desktop session with a clipboard"]
fn desktop_clipboard_round_trip() {
let _clipboard = DESKTOP_CLIPBOARD.lock().unwrap_or_else(|e| e.into_inner());
let mut clip = ArboardClipboard::new().unwrap();
clip.write_text("passalong desktop test").unwrap();
assert_eq!(
clip.read_text().unwrap().as_deref(),
Some("passalong desktop test")
);
}
#[cfg(feature = "desktop")]
#[test]
#[ignore = "needs a desktop session with a clipboard"]
fn desktop_image_round_trip() {
let _clipboard = DESKTOP_CLIPBOARD.lock().unwrap_or_else(|e| e.into_inner());
let rgba: Vec<u8> = (0..4 * 3 * 4)
.map(|i| {
if i % 4 == 3 {
255
} else {
(i * 19 % 256) as u8
}
})
.collect();
let image = RgbaImage::new(4, 3, rgba).unwrap();
let mut clip = ArboardClipboard::new().unwrap();
clip.write_image(&image).unwrap();
assert_eq!(clip.read_image().unwrap(), Some(image));
}
#[cfg(feature = "desktop")]
#[test]
#[ignore = "needs a desktop session with a clipboard"]
fn desktop_held_text_outlives_the_writer_until_replaced() {
let _clipboard = DESKTOP_CLIPBOARD.lock().unwrap_or_else(|e| e.into_inner());
let (done_tx, done_rx) = std::sync::mpsc::channel();
std::thread::spawn(move || {
let result = ArboardClipboard::new()
.unwrap()
.hold_text("held by passalong");
done_tx.send(result.is_ok()).unwrap();
});
std::thread::sleep(std::time::Duration::from_millis(500));
let mut reader = ArboardClipboard::new().unwrap();
assert_eq!(
reader.read_text().unwrap().as_deref(),
Some("held by passalong")
);
reader.write_text("replacement").unwrap();
let released = done_rx
.recv_timeout(std::time::Duration::from_secs(10))
.expect("holder returns once replaced");
assert!(released);
}
fn utf16_as_text(text: &str) -> String {
let bytes: Vec<u8> = text.encode_utf16().flat_map(u16::to_le_bytes).collect();
String::from_utf8(bytes).unwrap()
}
fn picture() -> RgbaImage {
RgbaImage::new(1, 1, vec![1, 2, 3, 255]).unwrap()
}
#[test]
fn links_and_image_tags_refer_to_an_image() {
for text in [
"https://cdn.example.com/a.webp?v=1",
"https://cdn.example.com/a.webp\nPage title",
" http://x/y.png ",
"file:///home/u/a.png",
"<meta charset='utf-8'><img src=\"https://x/a.png\">",
"<IMG SRC=a.png>",
] {
assert!(refers_to_image(text), "{text:?}");
}
for text in [
"hello",
"see https://x.com for details",
"https://a\nline two\nline three",
"<p>hi</p><img src=a.png>",
"",
] {
assert!(!refers_to_image(text), "{text:?}");
}
}
#[test]
fn the_image_wins_over_a_link_to_it() {
let mut clip = MockClipboard::with_text("https://cdn.example.com/a.webp")
.with_image_reads([Some(picture())]);
assert_eq!(
read_payload(&mut clip, true).unwrap(),
(None, Some(picture()))
);
}
#[test]
fn utf16_link_text_is_never_text() {
let text = utf16_as_text("https://cdn.example.com/a.webp\nPage title");
let mut clip = MockClipboard::with_text(&text).with_image_reads([Some(picture())]);
assert_eq!(
read_payload(&mut clip, true).unwrap(),
(None, Some(picture()))
);
let mut clip = MockClipboard::with_text(&text);
assert_eq!(
read_payload(&mut clip, true).unwrap(),
(None, None),
"garbled text is dropped"
);
}
#[test]
fn real_text_still_wins_and_links_without_an_image_stay_text() {
let mut clip = MockClipboard::with_text("words").with_image_reads([Some(picture())]);
assert_eq!(
read_payload(&mut clip, true).unwrap(),
(Some("words".to_owned()), None)
);
let mut clip = MockClipboard::with_text("https://example.com/page");
assert_eq!(
read_payload(&mut clip, true).unwrap(),
(Some("https://example.com/page".to_owned()), None)
);
let mut clip = MockClipboard::with_text("https://cdn.example.com/a.webp")
.with_image_reads([Some(picture())]);
assert_eq!(
read_payload(&mut clip, false).unwrap(),
(Some("https://cdn.example.com/a.webp".to_owned()), None),
"with images off, the link is the content"
);
}
}