term_transcript/
types.rs

1//! Core type definitions.
2
3use std::{borrow::Cow, fmt, io};
4
5use styled_str::{AnsiError, StyledString};
6
7pub(crate) type BoxedError = Box<dyn std::error::Error + Send + Sync>;
8
9/// Errors that can occur when processing terminal output.
10#[derive(Debug)]
11#[non_exhaustive]
12pub enum TermError {
13    /// Ansi escape sequence parsing error.
14    Ansi(AnsiError),
15    /// IO error.
16    Io(io::Error),
17    /// Font embedding error.
18    FontEmbedding(BoxedError),
19}
20
21impl fmt::Display for TermError {
22    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
23        match self {
24            Self::Ansi(err) => write!(formatter, "ANSI escape sequence parsing error: {err}"),
25            Self::Io(err) => write!(formatter, "I/O error: {err}"),
26            Self::FontEmbedding(err) => write!(formatter, "font embedding error: {err}"),
27        }
28    }
29}
30
31impl std::error::Error for TermError {
32    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
33        match self {
34            Self::Ansi(err) => Some(err),
35            Self::Io(err) => Some(err),
36            _ => None,
37        }
38    }
39}
40
41/// Transcript of a user interacting with the terminal.
42#[derive(Debug, Clone, Default)]
43pub struct Transcript {
44    interactions: Vec<Interaction>,
45}
46
47impl Transcript {
48    /// Creates an empty transcript.
49    pub fn new() -> Self {
50        Self::default()
51    }
52
53    /// Returns interactions in this transcript.
54    pub fn interactions(&self) -> &[Interaction] {
55        &self.interactions
56    }
57
58    /// Returns a mutable reference to interactions in this transcript.
59    pub fn interactions_mut(&mut self) -> &mut [Interaction] {
60        &mut self.interactions
61    }
62}
63
64impl Transcript {
65    /// Manually adds a new interaction to the end of this transcript.
66    ///
67    /// This method allows capturing interactions that are difficult or impossible to capture
68    /// using more high-level methods: [`Self::from_inputs()`] or [`Self::capture_output()`].
69    /// The resulting transcript will [render](crate::svg) just fine, but there could be issues
70    /// with [testing](crate::test) it.
71    pub fn add_existing_interaction(&mut self, interaction: Interaction) -> &mut Self {
72        self.interactions.push(interaction);
73        self
74    }
75
76    /// Manually adds a new interaction to the end of this transcript.
77    ///
78    /// This is a shortcut for calling [`Self::add_existing_interaction()`].
79    pub fn add_interaction(
80        &mut self,
81        input: impl Into<UserInput>,
82        output: StyledString,
83    ) -> &mut Self {
84        self.add_existing_interaction(Interaction::new(input, output))
85    }
86}
87
88/// Portable, platform-independent version of [`ExitStatus`] from the standard library.
89///
90/// # Capturing `ExitStatus`
91///
92/// Some shells have means to check whether the input command was executed successfully.
93/// For example, in `sh`-like shells, one can compare the value of `$?` to 0, and
94/// in PowerShell to `True`. The exit status can be captured when creating a [`Transcript`]
95/// by setting a *checker* in [`ShellOptions::with_status_check()`](crate::ShellOptions::with_status_check()):
96///
97/// # Examples
98///
99/// ```
100/// # use term_transcript::{ExitStatus, ShellOptions, Transcript, UserInput};
101/// # fn test_wrapper() -> anyhow::Result<()> {
102/// let options = ShellOptions::default();
103/// let mut options = options.with_status_check("echo $?", |captured| {
104///     // Get the plain text from the styled string. This transform
105///     // is especially important in transcripts captured from PTY
106///     // since they can contain a *wild* amount of escape sequences.
107///     let captured = captured.text();
108///     let code: i32 = captured.trim().parse().ok()?;
109///     Some(ExitStatus(code))
110/// });
111///
112/// let transcript = Transcript::from_inputs(&mut options, [
113///     UserInput::command("echo \"Hello world\""),
114///     UserInput::command("some-non-existing-command"),
115/// ])?;
116/// let status = transcript.interactions()[0].exit_status();
117/// assert!(status.unwrap().is_success());
118/// // The assertion above is equivalent to:
119/// assert_eq!(status, Some(ExitStatus(0)));
120///
121/// let status = transcript.interactions()[1].exit_status();
122/// assert!(!status.unwrap().is_success());
123/// # Ok(())
124/// # }
125/// # // We can compile test in any case, but it successfully executes only on *nix.
126/// # #[cfg(unix)] fn main() { test_wrapper().unwrap() }
127/// # #[cfg(not(unix))] fn main() { }
128/// ```
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
130pub struct ExitStatus(pub i32);
131
132impl ExitStatus {
133    /// Checks if this is the successful status.
134    pub fn is_success(self) -> bool {
135        self.0 == 0
136    }
137}
138
139/// One-time interaction with the terminal.
140#[derive(Debug, Clone)]
141pub struct Interaction {
142    input: UserInput,
143    output: StyledString,
144    exit_status: Option<ExitStatus>,
145}
146
147impl Interaction {
148    /// Creates a new interaction.
149    ///
150    /// Any newlines at the end of the output will be trimmed.
151    pub fn new(input: impl Into<UserInput>, mut output: StyledString) -> Self {
152        while output.text().ends_with('\n') {
153            output.pop();
154        }
155
156        Self {
157            input: input.into(),
158            output,
159            exit_status: None,
160        }
161    }
162
163    /// Sets an exit status for this interaction.
164    pub fn set_exit_status(&mut self, exit_status: Option<ExitStatus>) {
165        self.exit_status = exit_status;
166    }
167
168    /// Assigns an exit status to this interaction.
169    #[must_use]
170    pub fn with_exit_status(mut self, exit_status: ExitStatus) -> Self {
171        self.exit_status = Some(exit_status);
172        self
173    }
174}
175
176impl Interaction {
177    /// Input provided by the user.
178    pub fn input(&self) -> &UserInput {
179        &self.input
180    }
181
182    /// Output to the terminal.
183    pub fn output(&self) -> &StyledString {
184        &self.output
185    }
186
187    /// Sets the output for this interaction.
188    pub fn set_output(&mut self, mut output: StyledString) {
189        while output.text().ends_with('\n') {
190            output.pop();
191        }
192        self.output = output;
193    }
194
195    /// Returns exit status of the interaction, if available.
196    pub fn exit_status(&self) -> Option<ExitStatus> {
197        self.exit_status
198    }
199}
200
201/// User input during interaction with a terminal.
202#[derive(Debug, Clone, PartialEq, Eq)]
203#[cfg_attr(feature = "svg", derive(serde::Serialize))]
204pub struct UserInput {
205    text: String,
206    prompt: Option<Cow<'static, str>>,
207    hidden: bool,
208}
209
210impl UserInput {
211    #[cfg(feature = "test")]
212    pub(crate) const EMPTY: Self = Self {
213        text: String::new(),
214        prompt: None,
215        hidden: false,
216    };
217
218    #[cfg(feature = "test")]
219    pub(crate) fn new(text: String) -> Self {
220        Self {
221            prompt: None,
222            text,
223            hidden: false,
224        }
225    }
226
227    #[cfg(feature = "test")]
228    #[must_use]
229    pub(crate) fn with_prompt(mut self, prompt: Option<String>) -> Self {
230        self.prompt = prompt.map(|prompt| match prompt.as_str() {
231            "$" => Cow::Borrowed("$"),
232            ">>>" => Cow::Borrowed(">>>"),
233            "..." => Cow::Borrowed("..."),
234            _ => Cow::Owned(prompt),
235        });
236        self
237    }
238
239    /// Creates a command input.
240    pub fn command(text: impl Into<String>) -> Self {
241        Self {
242            text: text.into(),
243            prompt: Some(Cow::Borrowed("$")),
244            hidden: false,
245        }
246    }
247
248    /// Creates a standalone / starting REPL command input with the `>>>` prompt.
249    pub fn repl(text: impl Into<String>) -> Self {
250        Self {
251            text: text.into(),
252            prompt: Some(Cow::Borrowed(">>>")),
253            hidden: false,
254        }
255    }
256
257    /// Creates a REPL command continuation input with the `...` prompt.
258    pub fn repl_continuation(text: impl Into<String>) -> Self {
259        Self {
260            text: text.into(),
261            prompt: Some(Cow::Borrowed("...")),
262            hidden: false,
263        }
264    }
265
266    /// Returns the prompt part of this input.
267    pub fn prompt(&self) -> Option<&str> {
268        self.prompt.as_deref()
269    }
270
271    /// Marks this input as hidden (one that should not be displayed in the rendered transcript).
272    #[must_use]
273    pub fn hide(mut self) -> Self {
274        self.hidden = true;
275        self
276    }
277
278    /// Checks whether this input is hidden.
279    pub fn is_hidden(&self) -> bool {
280        self.hidden
281    }
282}
283
284/// Returns the command part of the input without the prompt.
285impl AsRef<str> for UserInput {
286    fn as_ref(&self) -> &str {
287        &self.text
288    }
289}
290
291/// Calls [`Self::command()`] on the provided string reference.
292impl From<&str> for UserInput {
293    fn from(command: &str) -> Self {
294        Self::command(command)
295    }
296}
term_transcript/types.rs

term_transcript/
types.rs
