cli_clipboard/
lib.rs

1/*
2Copyright 2016 Avraham Weinstock
3
4Licensed under the Apache License, Version 2.0 (the "License");
5you may not use this file except in compliance with the License.
6You may obtain a copy of the License at
7
8   http://www.apache.org/licenses/LICENSE-2.0
9
10Unless required by applicable law or agreed to in writing, software
11distributed under the License is distributed on an "AS IS" BASIS,
12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13See the License for the specific language governing permissions and
14limitations under the License.
15*/
16
17//! # CLI Clipboard
18//!
19//! cli-clipboard is a fork of
20//! [rust-clipboard](https://github.com/aweinstock314/rust-clipboard) that
21//! adds wayland support for terminal and window-less applications via
22//! [wl-clipboard-rs](https://github.com/YaLTeR/wl-clipboard-rs). For terminal
23//! applications it supports copy and paste for both wayland and X11 linux
24//! environments, macOS and windows.
25//!
26//! Also adds convenience functions for [get_contents](fn.get_contents.html) and
27//! [set_contents](fn.set_contents.html).
28//!
29//! On Linux it will first attempt to setup a Wayland clipboard provider.  If that
30//! fails it will then fallback to the X11 clipboard provider.
31//!
32//! ## Examples
33//!
34//! Using ClipboardContext to create a clipboard provider:
35//!
36//! ```
37//! use cli_clipboard::{ClipboardContext, ClipboardProvider};
38//!
39//! let mut ctx = ClipboardContext::new().unwrap();
40//! let the_string = "Hello, world!";
41//! ctx.set_contents(the_string.to_owned()).unwrap();
42//! assert_eq!(ctx.get_contents().unwrap(), the_string);
43//! ctx.clear();
44//! // clearing the clipboard causes get_contents to return Err on macos and windows
45//! if cfg!(any(windows, target_os = "macos")) {
46//!    if ctx.get_contents().is_ok() {
47//!        panic!("Should be Err");
48//!    }
49//! } else {
50//!    assert_eq!(ctx.get_contents().unwrap(), "");
51//! }
52//! ```
53//!
54//! Using the helper functions:
55//!
56//! ```
57//! use cli_clipboard;
58//!
59//! let the_string = "Hello, world!";
60//! cli_clipboard::set_contents(the_string.to_owned()).unwrap();
61//! assert_eq!(cli_clipboard::get_contents().unwrap(), the_string);
62//! ```
63
64#[cfg(all(
65    unix,
66    not(any(target_os = "macos", target_os = "android", target_os = "emscripten"))
67))]
68extern crate x11_clipboard as x11_clipboard_crate;
69
70#[cfg(target_os = "macos")]
71#[macro_use]
72extern crate objc;
73
74type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
75
76mod common;
77pub use common::ClipboardProvider;
78
79#[cfg(all(
80    unix,
81    not(any(target_os = "macos", target_os = "android", target_os = "emscripten"))
82))]
83pub mod wayland_clipboard;
84
85#[cfg(all(
86    unix,
87    not(any(target_os = "macos", target_os = "android", target_os = "emscripten"))
88))]
89pub mod x11_clipboard;
90
91#[cfg(all(
92    unix,
93    not(any(target_os = "macos", target_os = "android", target_os = "emscripten"))
94))]
95pub mod linux_clipboard;
96
97#[cfg(windows)]
98pub mod windows_clipboard;
99
100#[cfg(target_os = "macos")]
101pub mod macos_clipboard;
102
103#[cfg(all(
104    unix,
105    not(any(target_os = "macos", target_os = "android", target_os = "emscripten"))
106))]
107pub type ClipboardContext = linux_clipboard::LinuxClipboardContext;
108
109#[cfg(windows)]
110pub type ClipboardContext = windows_clipboard::WindowsClipboardContext;
111
112#[cfg(target_os = "macos")]
113pub type ClipboardContext = macos_clipboard::MacOSClipboardContext;
114
115/// Get the current clipboard contents
116///
117/// # Example
118/// ```
119/// cli_clipboard::set_contents("testing".to_owned()).unwrap();
120/// assert_eq!(cli_clipboard::get_contents().unwrap(), "testing");
121/// ```
122pub fn get_contents() -> Result<String> {
123    let mut ctx = ClipboardContext::new()?;
124    ctx.get_contents()
125}
126
127/// Write a string to the clipboard
128///
129/// This uses the platform default behavior for setting clipboard contents.
130/// Other users of the Wayland or X11 clipboard will only see the contents
131/// copied to the clipboard so long as the process copying to the
132/// clipboard exists.
133/// MacOS and Windows clipboard contents will stick around after your
134/// application exits.
135///
136/// # Example
137/// ```
138/// cli_clipboard::set_contents("testing".to_owned()).unwrap();
139/// assert_eq!(cli_clipboard::get_contents().unwrap(), "testing");
140/// ```
141pub fn set_contents(data: String) -> Result<()> {
142    let mut ctx = ClipboardContext::new()?;
143    ctx.set_contents(data)?;
144    Ok(())
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn test_clipboard() {
153        let mut ctx = ClipboardContext::new().unwrap();
154        ctx.set_contents("some string".to_owned()).unwrap();
155        assert_eq!(ctx.get_contents().unwrap(), "some string");
156    }
157}
cli_clipboard/lib.rs

cli_clipboard/
lib.rs
