Skip to main content

tmux_client/
buffer.rs

1//! Paste-buffer discovery and byte-preserving operations.
2
3use std::collections::BTreeMap;
4use std::ffi::OsString;
5use std::fmt;
6use std::path::Path;
7
8use crate::{Command, Error, FormatScope, NativeFilter, ObjectKind, Result, Server, TmuxText};
9
10/// A validated tmux paste-buffer name.
11#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
12pub struct BufferName(TmuxText);
13
14impl BufferName {
15    /// Creates a non-empty buffer name.
16    pub fn new(value: impl Into<TmuxText>) -> Result<Self> {
17        let value = value.into();
18        if value.is_empty() || value.as_bytes().contains(&b'\0') {
19            return Err(Error::InvalidArgument {
20                argument: "buffer name",
21                message: "must be non-empty and contain no NUL byte".to_owned(),
22            });
23        }
24        Ok(Self(value))
25    }
26
27    /// Returns the byte-preserving name.
28    #[must_use]
29    pub const fn as_text(&self) -> &TmuxText {
30        &self.0
31    }
32
33    pub(crate) fn to_os_string(&self) -> OsString {
34        self.0.to_os_string()
35    }
36}
37
38impl fmt::Display for BufferName {
39    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
40        self.0.fmt(formatter)
41    }
42}
43
44/// An owned snapshot of a tmux paste buffer.
45#[derive(Clone, Debug)]
46pub struct Buffer {
47    server: Server,
48    name: BufferName,
49    size: u64,
50    sample: TmuxText,
51}
52
53impl Buffer {
54    fn from_row(server: Server, row: &BTreeMap<&'static str, TmuxText>) -> Result<Self> {
55        let name = row
56            .get("buffer_name")
57            .cloned()
58            .ok_or_else(|| Error::Decode {
59                context: "buffer row",
60                message: "buffer_name was absent".to_owned(),
61            })?;
62        let size = row
63            .get("buffer_size")
64            .ok_or_else(|| Error::Decode {
65                context: "buffer row",
66                message: "buffer_size was absent".to_owned(),
67            })?
68            .to_str()
69            .map_err(|source| Error::Decode {
70                context: "buffer size",
71                message: source.to_string(),
72            })?
73            .parse()
74            .map_err(|source: std::num::ParseIntError| Error::Decode {
75                context: "buffer size",
76                message: source.to_string(),
77            })?;
78        let sample = row.get("buffer_sample").cloned().unwrap_or_default();
79        Ok(Self {
80            server,
81            name: BufferName::new(name)?,
82            size,
83            sample,
84        })
85    }
86
87    /// Returns the buffer name.
88    #[must_use]
89    pub const fn name(&self) -> &BufferName {
90        &self.name
91    }
92
93    /// Returns the byte size reported by tmux.
94    #[must_use]
95    pub const fn size(&self) -> u64 {
96        self.size
97    }
98
99    /// Returns tmux's listing sample.
100    #[must_use]
101    pub const fn sample(&self) -> &TmuxText {
102        &self.sample
103    }
104
105    /// Returns the server handle.
106    #[must_use]
107    pub const fn server(&self) -> &Server {
108        &self.server
109    }
110
111    /// Refreshes this named buffer.
112    pub async fn refresh(&mut self) -> Result<()> {
113        *self = self.server.buffer(&self.name).await?;
114        Ok(())
115    }
116
117    /// Reads the complete buffer contents.
118    pub async fn show(&self) -> Result<TmuxText> {
119        self.server.show_buffer(Some(&self.name)).await
120    }
121
122    /// Deletes the named buffer.
123    pub async fn delete(&self) -> Result<()> {
124        self.server.delete_buffer(Some(&self.name)).await
125    }
126
127    /// Saves the buffer to a file through tmux.
128    pub async fn save(&self, path: impl AsRef<Path>, append: bool) -> Result<()> {
129        self.server.save_buffer(&self.name, path, append).await
130    }
131}
132
133impl PartialEq for Buffer {
134    fn eq(&self, other: &Self) -> bool {
135        self.name == other.name && self.server.config() == other.server.config()
136    }
137}
138
139impl Eq for Buffer {}
140
141impl Server {
142    /// Lists paste buffers.
143    pub async fn buffers(&self) -> Result<Vec<Buffer>> {
144        self.list_rows("list-buffers", &[FormatScope::Buffer], [], None)
145            .await?
146            .into_iter()
147            .map(|row| Buffer::from_row(self.clone(), &row))
148            .collect()
149    }
150
151    /// Lists buffers with a raw output format and optional native filter.
152    pub async fn list_buffers(
153        &self,
154        format: Option<&str>,
155        filter: Option<&NativeFilter>,
156    ) -> Result<Vec<TmuxText>> {
157        let mut command = Command::new("list-buffers");
158        if let Some(format) = format {
159            command = command.arg("-F").arg(format);
160        }
161        if let Some(filter) = filter {
162            command = command.arg("-f").arg(filter.as_str());
163        }
164        Ok(self
165            .checked("list buffers", command)
166            .await?
167            .stdout_lines()
168            .collect())
169    }
170
171    /// Lists buffers, returning an empty collection on failure.
172    pub async fn buffers_or_empty(&self) -> Vec<Buffer> {
173        self.buffers().await.unwrap_or_default()
174    }
175
176    /// Resolves an exact buffer name.
177    pub async fn buffer(&self, name: &BufferName) -> Result<Buffer> {
178        self.buffers()
179            .await?
180            .into_iter()
181            .find(|buffer| buffer.name == *name)
182            .ok_or_else(|| Error::ObjectNotFound {
183                kind: ObjectKind::Buffer,
184                target: name.to_string(),
185            })
186    }
187
188    /// Loads byte-preserving data through stdin and returns its resulting buffer.
189    pub async fn load_buffer(
190        &self,
191        name: Option<&BufferName>,
192        data: impl Into<TmuxText>,
193    ) -> Result<Buffer> {
194        let mut command = Command::new("load-buffer");
195        if let Some(name) = name {
196            command = command.arg("-b").arg(name.to_os_string());
197        }
198        command = command.arg("-").sensitive_input(data);
199        self.checked("load buffer", command).await?;
200        if let Some(name) = name {
201            return self.buffer(name).await;
202        }
203        self.buffers()
204            .await?
205            .into_iter()
206            .next()
207            .ok_or_else(|| Error::ObjectNotFound {
208                kind: ObjectKind::Buffer,
209                target: "most recent buffer".to_owned(),
210            })
211    }
212
213    /// Loads a filesystem path into a named or automatic tmux buffer.
214    pub async fn load_buffer_file(
215        &self,
216        name: Option<&BufferName>,
217        path: impl AsRef<Path>,
218    ) -> Result<Buffer> {
219        let mut command = Command::new("load-buffer");
220        if let Some(name) = name {
221            command = command.arg("-b").arg(name.to_os_string());
222        }
223        self.checked("load buffer file", command.arg(path.as_ref()))
224            .await?;
225        if let Some(name) = name {
226            return self.buffer(name).await;
227        }
228        self.buffers()
229            .await?
230            .into_iter()
231            .next()
232            .ok_or_else(|| Error::ObjectNotFound {
233                kind: ObjectKind::Buffer,
234                target: "most recent buffer".to_owned(),
235            })
236    }
237
238    /// Sets text using `set-buffer`. Prefer [`Self::load_buffer`] for arbitrary bytes.
239    pub async fn set_buffer(
240        &self,
241        name: Option<&BufferName>,
242        data: impl Into<TmuxText>,
243        append: bool,
244    ) -> Result<Buffer> {
245        let data = data.into();
246        if data.as_bytes().contains(&b'\0') {
247            return self.load_buffer(name, data).await;
248        }
249        let mut command = Command::new("set-buffer");
250        if append {
251            command = command.arg("-a");
252        }
253        if let Some(name) = name {
254            command = command.arg("-b").arg(name.to_os_string());
255        }
256        command = command.sensitive_arg(data.to_os_string());
257        self.checked("set buffer", command).await?;
258        if let Some(name) = name {
259            return self.buffer(name).await;
260        }
261        self.buffers()
262            .await?
263            .into_iter()
264            .next()
265            .ok_or_else(|| Error::ObjectNotFound {
266                kind: ObjectKind::Buffer,
267                target: "most recent buffer".to_owned(),
268            })
269    }
270
271    /// Reads a named buffer or tmux's most recent buffer.
272    pub async fn show_buffer(&self, name: Option<&BufferName>) -> Result<TmuxText> {
273        let mut command = Command::new("show-buffer");
274        if let Some(name) = name {
275            command = command.arg("-b").arg(name.to_os_string());
276        }
277        self.checked("show buffer", command)
278            .await
279            .map(|result| result.stdout().clone())
280    }
281
282    /// Deletes a named buffer or tmux's most recent buffer.
283    pub async fn delete_buffer(&self, name: Option<&BufferName>) -> Result<()> {
284        let mut command = Command::new("delete-buffer");
285        if let Some(name) = name {
286            command = command.arg("-b").arg(name.to_os_string());
287        }
288        self.checked("delete buffer", command).await.map(|_| ())
289    }
290
291    /// Saves a buffer to a filesystem path through tmux.
292    pub async fn save_buffer(
293        &self,
294        name: &BufferName,
295        path: impl AsRef<Path>,
296        append: bool,
297    ) -> Result<()> {
298        let mut command = Command::new("save-buffer")
299            .arg("-b")
300            .arg(name.to_os_string());
301        if append {
302            command = command.arg("-a");
303        }
304        self.checked("save buffer", command.arg(path.as_ref()))
305            .await
306            .map(|_| ())
307    }
308}