tmux_client/error.rs
1//! Errors returned by the library.
2
3use std::io;
4use std::time::Duration;
5
6use thiserror::Error;
7
8use crate::{CommandResult, CommandSummary, ReleaseVersion, TmuxVersion};
9
10/// A result returned by `tmux-client`.
11pub type Result<T> = std::result::Result<T, Error>;
12
13/// The kind of tmux object involved in an error.
14#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
15pub enum ObjectKind {
16 /// A server.
17 Server,
18 /// A session.
19 Session,
20 /// A window.
21 Window,
22 /// A pane.
23 Pane,
24 /// A client.
25 Client,
26 /// A buffer.
27 Buffer,
28}
29
30impl std::fmt::Display for ObjectKind {
31 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
32 formatter.write_str(match self {
33 Self::Server => "server",
34 Self::Session => "session",
35 Self::Window => "window",
36 Self::Pane => "pane",
37 Self::Client => "client",
38 Self::Buffer => "buffer",
39 })
40 }
41}
42
43/// A category of option parsing or mutation failure.
44#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
45pub enum OptionErrorKind {
46 /// An option value could not be parsed.
47 Parse,
48 /// An option value had an unsupported representation.
49 Unsupported,
50 /// An indexed option was malformed.
51 SparseIndex,
52}
53
54impl std::fmt::Display for OptionErrorKind {
55 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56 formatter.write_str(match self {
57 Self::Parse => "parse",
58 Self::Unsupported => "unsupported",
59 Self::SparseIndex => "sparse-index",
60 })
61 }
62}
63
64/// A non-exhaustive error produced by configuration, execution, or parsing.
65#[derive(Debug, Error)]
66#[non_exhaustive]
67pub enum Error {
68 /// The configured tmux executable was not found.
69 #[error("tmux executable {executable:?} was not found")]
70 ExecutableNotFound {
71 /// The configured executable path.
72 executable: std::path::PathBuf,
73 },
74
75 /// A process or file operation failed.
76 #[error("{operation} failed: {source}")]
77 Io {
78 /// A static operation name.
79 operation: &'static str,
80 /// The underlying operating-system error.
81 #[source]
82 source: io::Error,
83 },
84
85 /// A command exceeded the configured timeout.
86 #[error("tmux command `{summary}` timed out after {timeout:?}")]
87 Timeout {
88 /// The redacted command description.
89 summary: CommandSummary,
90 /// The configured timeout.
91 timeout: Duration,
92 },
93
94 /// tmux returned a non-zero status for a typed operation.
95 #[error("tmux {operation} failed: {result:?}")]
96 CommandFailed {
97 /// The attempted high-level operation.
98 operation: &'static str,
99 /// The complete byte-preserving result.
100 result: Box<CommandResult>,
101 },
102
103 /// No tmux server was available on the requested socket.
104 #[error("no tmux server is available: {message}")]
105 ServerUnavailable {
106 /// Diagnostic text returned by tmux.
107 message: String,
108 },
109
110 /// A requested tmux object did not exist.
111 #[error("{kind} {target} was not found")]
112 ObjectNotFound {
113 /// The expected object kind.
114 kind: ObjectKind,
115 /// The target used for lookup.
116 target: String,
117 },
118
119 /// A lookup that expected one object returned multiple objects.
120 #[error("query `{query}` matched {count} {kind} objects")]
121 MultipleObjects {
122 /// The object kind.
123 kind: ObjectKind,
124 /// The number of matches.
125 count: usize,
126 /// A redacted query description.
127 query: String,
128 },
129
130 /// An ID did not use the required prefix and numeric suffix.
131 #[error("invalid {kind} ID `{value}`")]
132 InvalidId {
133 /// The ID kind.
134 kind: &'static str,
135 /// The invalid representation.
136 value: String,
137 },
138
139 /// A session name used tmux-reserved target punctuation.
140 #[error("invalid tmux session name `{0}`")]
141 InvalidSessionName(String),
142
143 /// A public argument did not satisfy its contract.
144 #[error("invalid {argument}: {message}")]
145 InvalidArgument {
146 /// The argument name.
147 argument: &'static str,
148 /// The validation failure.
149 message: String,
150 },
151
152 /// tmux returned an unrecognized version.
153 #[error("invalid tmux version `{0}`")]
154 InvalidVersion(String),
155
156 /// The connected tmux version lacks a requested capability.
157 #[error("{capability} requires tmux {required} or newer, found {found}")]
158 Unsupported {
159 /// The requested operation or field.
160 capability: &'static str,
161 /// The minimum release.
162 required: ReleaseVersion,
163 /// The actual connected version.
164 found: TmuxVersion,
165 },
166
167 /// Structured tmux output could not be decoded.
168 #[error("could not decode {context}: {message}")]
169 Decode {
170 /// The output family being decoded.
171 context: &'static str,
172 /// A safe explanation without untrusted output interpolation.
173 message: String,
174 },
175
176 /// An option value or index was invalid.
177 #[error("option {kind} error: {message}")]
178 Option {
179 /// The failure category.
180 kind: OptionErrorKind,
181 /// The failure description.
182 message: String,
183 },
184
185 /// An operation required being inside an attached tmux client.
186 #[error("the operation requires an attached tmux client")]
187 NotInsideTmux,
188
189 /// A wait condition expired before it was satisfied.
190 #[error("timed out waiting for {condition}")]
191 WaitTimeout {
192 /// A description of the condition.
193 condition: String,
194 },
195
196 /// The main operation succeeded but deterministic cleanup failed.
197 #[error("cleanup after {operation} failed: {source}")]
198 Cleanup {
199 /// The operation whose scope was being cleaned up.
200 operation: &'static str,
201 /// The cleanup error.
202 #[source]
203 source: Box<Error>,
204 },
205}