term_transcript/test/parser/
mod.rs

1//! SVG parsing logic.
2
3use std::{
4    borrow::Cow,
5    error::Error as StdError,
6    fmt,
7    io::{self, BufRead},
8    mem,
9    num::ParseIntError,
10    ops,
11    str::{self},
12};
13
14use quick_xml::{
15    Reader as XmlReader,
16    events::{Event, attributes::Attributes},
17};
18use styled_str::StyledString;
19
20use self::text::TextReadingState;
21use crate::{ExitStatus, Interaction, Transcript, UserInput};
22
23#[cfg(test)]
24mod tests;
25mod text;
26
27/// Converts this parsed fragment into text for `UserInput`. This takes into account
28/// that while the first space after prompt is inserted automatically, the further whitespace
29/// may be significant.
30fn into_input_text(text: String) -> String {
31    let mut text = if let Some(stripped) = text.strip_prefix(' ') {
32        stripped.to_owned()
33    } else {
34        text
35    };
36
37    if text.ends_with('\n') {
38        text.pop();
39    }
40    text
41}
42
43impl Transcript {
44    /// Parses a transcript from the provided `reader`, which should point to an SVG XML tree
45    /// produced by [`Template::render()`] (possibly within a larger document).
46    ///
47    /// # Errors
48    ///
49    /// - Returns an error if the input cannot be parsed, usually because it was not produced
50    ///   by `Template::render()`.
51    ///
52    /// [`Template::render()`]: crate::svg::Template::render()
53    #[cfg_attr(feature = "tracing", tracing::instrument(skip_all, err))]
54    pub fn from_svg<R: BufRead>(reader: R) -> Result<Self, LocatedParseError> {
55        let mut reader = XmlReader::from_reader(reader);
56        let mut buffer = vec![];
57        let mut state = ParserState::Initialized;
58        let mut transcript = Self::new();
59        let mut open_tags = 0;
60
61        #[allow(clippy::cast_possible_truncation)] // Truncation shouldn't happen in practice
62        loop {
63            let prev_position = reader.buffer_position() as usize;
64            let event = reader
65                .read_event_into(&mut buffer)
66                .map_err(|err| LocatedParseError::new(err.into(), prev_position..prev_position))?;
67            let event_position = prev_position..reader.buffer_position() as usize;
68            match &event {
69                Event::Start(_) => {
70                    open_tags += 1;
71                }
72                Event::End(_) => {
73                    open_tags -= 1;
74                    if open_tags == 0 {
75                        break;
76                    }
77                }
78                Event::Eof => break,
79                _ => { /* Do nothing. */ }
80            }
81
82            let maybe_interaction = state
83                .process(event, event_position.clone())
84                .map_err(|err| LocatedParseError::new(err, event_position))?;
85            if let Some(interaction) = maybe_interaction {
86                #[cfg(feature = "tracing")]
87                tracing::debug!(
88                    input = ?interaction.input(),
89                    output = interaction.output().text(),
90                    exit_status = ?interaction.exit_status(),
91                    "parsed interaction"
92                );
93                transcript.add_existing_interaction(interaction);
94            }
95        }
96
97        match state {
98            ParserState::EncounteredContainer => Ok(transcript),
99            ParserState::EncounteredUserInput(interaction) => {
100                transcript.add_existing_interaction(interaction.with_empty_output());
101                Ok(transcript)
102            }
103            #[allow(clippy::cast_possible_truncation)] // Shouldn't happen in practice
104            _ => {
105                let pos = reader.buffer_position() as usize;
106                Err(LocatedParseError::new(ParseError::UnexpectedEof, pos..pos))
107            }
108        }
109    }
110}
111
112fn parse_classes(attributes: Attributes<'_>) -> Result<Cow<'_, str>, ParseError> {
113    let mut class = None;
114    for attr in attributes {
115        let attr = attr.map_err(quick_xml::Error::InvalidAttr)?;
116        if attr.key.as_ref() == "class" {
117            class = Some(attr.value);
118        }
119    }
120    Ok(class.unwrap_or(Cow::Borrowed("")))
121}
122
123fn extract_base_class(classes: &str) -> &str {
124    let space_idx = classes.bytes().position(|ch| ch == b' ');
125    space_idx.map_or(classes.as_ref(), |idx| &classes[..idx])
126}
127
128fn parse_exit_status(attributes: Attributes<'_>) -> Result<Option<ExitStatus>, ParseError> {
129    let mut exit_status = None;
130    for attr in attributes {
131        let attr = attr.map_err(quick_xml::Error::InvalidAttr)?;
132        if attr.key.as_ref() == "data-exit-status" {
133            let status = attr.value.as_ref();
134            let status = status.parse().map_err(ParseError::InvalidExitStatus)?;
135            exit_status = Some(ExitStatus(status));
136        }
137    }
138    Ok(exit_status)
139}
140
141/// Errors that can occur during parsing SVG transcripts.
142#[derive(Debug)]
143#[non_exhaustive]
144pub enum ParseError {
145    /// Unexpected root XML tag; must be `<svg>`.
146    UnexpectedRoot(String),
147    /// Invalid transcript container.
148    InvalidContainer,
149    /// Invalid recorded exit status of an executed command.
150    InvalidExitStatus(ParseIntError),
151    /// Unexpected end of file.
152    UnexpectedEof,
153    /// Invalid hard line break.
154    InvalidHardBreak,
155    /// Error parsing XML.
156    Xml(quick_xml::Error),
157}
158
159impl From<quick_xml::Error> for ParseError {
160    fn from(err: quick_xml::Error) -> Self {
161        Self::Xml(err)
162    }
163}
164
165impl From<io::Error> for ParseError {
166    fn from(err: io::Error) -> Self {
167        Self::Xml(err.into())
168    }
169}
170
171impl fmt::Display for ParseError {
172    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
173        match self {
174            Self::UnexpectedRoot(tag_name) => write!(
175                formatter,
176                "unexpected root XML tag: <{tag_name}>; expected <svg>"
177            ),
178            Self::InvalidContainer => formatter.write_str("invalid transcript container"),
179            Self::InvalidExitStatus(err) => write!(formatter, "invalid exit status: {err}"),
180            Self::UnexpectedEof => formatter.write_str("unexpected EOF"),
181            Self::InvalidHardBreak => formatter.write_str("invalid hard line break"),
182            Self::Xml(err) => write!(formatter, "error parsing XML: {err}"),
183        }
184    }
185}
186
187impl StdError for ParseError {
188    fn source(&self) -> Option<&(dyn StdError + 'static)> {
189        match self {
190            Self::Xml(err) => Some(err),
191            Self::InvalidExitStatus(err) => Some(err),
192            _ => None,
193        }
194    }
195}
196
197/// [`ParseError`] together with its location in the XML input.
198#[derive(Debug)]
199pub struct LocatedParseError {
200    inner: ParseError,
201    location: ops::Range<usize>,
202}
203
204impl LocatedParseError {
205    fn new(inner: ParseError, location: ops::Range<usize>) -> Self {
206        Self { inner, location }
207    }
208
209    /// Returns a reference to the contained [`ParseError`].
210    pub fn inner(&self) -> &ParseError {
211        &self.inner
212    }
213
214    /// Returns the error location as the starting and ending byte offsets in the input.
215    pub fn location(&self) -> ops::Range<usize> {
216        self.location.clone()
217    }
218
219    /// Unwraps the contained parse error.
220    pub fn into_inner(self) -> ParseError {
221        self.inner
222    }
223}
224
225impl fmt::Display for LocatedParseError {
226    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
227        let Self { inner, location } = self;
228        write!(formatter, "at {}-{}: {inner}", location.start, location.end)
229    }
230}
231
232impl StdError for LocatedParseError {
233    fn source(&self) -> Option<&(dyn StdError + 'static)> {
234        self.inner.source()
235    }
236}
237
238#[derive(Debug)]
239struct InteractionInput {
240    input: UserInput,
241    exit_status: Option<ExitStatus>,
242}
243
244impl Default for InteractionInput {
245    fn default() -> Self {
246        Self {
247            input: UserInput::EMPTY,
248            exit_status: None,
249        }
250    }
251}
252
253impl InteractionInput {
254    fn with_output(self, output: StyledString) -> Interaction {
255        let mut interaction = Interaction::new(self.input, output);
256        interaction.set_exit_status(self.exit_status);
257        interaction
258    }
259
260    fn with_empty_output(self) -> Interaction {
261        self.with_output(StyledString::default())
262    }
263}
264
265#[derive(Debug)]
266struct UserInputState {
267    exit_status: Option<ExitStatus>,
268    is_hidden: bool,
269    text: TextReadingState,
270    prompt: Option<String>,
271    prompt_open_tags: Option<usize>,
272}
273
274impl UserInputState {
275    fn new(exit_status: Option<ExitStatus>, is_hidden: bool) -> Self {
276        Self {
277            exit_status,
278            is_hidden,
279            text: TextReadingState::default(),
280            prompt: None,
281            prompt_open_tags: None,
282        }
283    }
284}
285
286impl UserInputState {
287    /// Can prompt reading be started now?
288    fn can_start_prompt(&self) -> bool {
289        self.text.is_empty() && self.prompt.is_none() && self.prompt_open_tags.is_none()
290    }
291
292    fn can_end_prompt(&self) -> bool {
293        self.prompt.is_none()
294            && self
295                .prompt_open_tags
296                .is_some_and(|tags| tags + 1 == self.text.open_tags())
297    }
298
299    fn process(
300        &mut self,
301        event: Event<'_>,
302        position: ops::Range<usize>,
303    ) -> Result<Option<InteractionInput>, ParseError> {
304        let mut is_prompt_end = false;
305        if let Event::Start(tag) = &event {
306            if self.can_start_prompt() && parse_classes(tag.attributes())?.as_ref() == "prompt" {
307                // Got prompt start.
308                self.prompt_open_tags = Some(self.text.open_tags());
309            }
310        } else if let Event::End(_) = &event {
311            if self.can_end_prompt() {
312                is_prompt_end = true;
313            }
314        }
315
316        let maybe_parsed = self.text.process(event, position)?;
317        if is_prompt_end {
318            if let Some(parsed) = maybe_parsed {
319                // Special case: user input consists of the prompt only.
320                let text = parsed.into_text();
321                let mut input = UserInput::new(String::new()).with_prompt(Some(text));
322                if self.is_hidden {
323                    input = input.hide();
324                }
325
326                return Ok(Some(InteractionInput {
327                    input,
328                    exit_status: self.exit_status,
329                }));
330            }
331            let text = self.text.take_plaintext();
332            self.prompt = Some(text);
333        }
334
335        Ok(maybe_parsed.map(|parsed| {
336            let text = parsed.into_text();
337            let mut input = UserInput::new(into_input_text(text)).with_prompt(self.prompt.take());
338            if self.is_hidden {
339                input = input.hide();
340            }
341
342            InteractionInput {
343                input,
344                exit_status: self.exit_status,
345            }
346        }))
347    }
348}
349
350/// States of the FSM for parsing SVGs.
351#[derive(Debug)]
352enum ParserState {
353    /// Initial state.
354    Initialized,
355    /// Encountered `<svg>` tag; searching for `<div class="container">`.
356    EncounteredSvgTag,
357    /// Encountered `<div class="container">`; searching for `<div class="input">`.
358    EncounteredContainer,
359    /// Reading user input (`<div class="input">` contents).
360    ReadingUserInput(UserInputState),
361    /// Finished reading user input; searching for `<div class="output">`.
362    EncounteredUserInput(InteractionInput),
363    /// Reading terminal output (`<div class="output">` contents).
364    ReadingTermOutput(InteractionInput, TextReadingState),
365}
366
367impl ParserState {
368    #[cfg_attr(feature = "tracing", tracing::instrument(level = "debug"))]
369    fn set_state(&mut self, new_state: Self) {
370        *self = new_state;
371    }
372
373    #[cfg_attr(feature = "tracing", tracing::instrument(level = "trace", err))]
374    fn process(
375        &mut self,
376        event: Event<'_>,
377        position: ops::Range<usize>,
378    ) -> Result<Option<Interaction>, ParseError> {
379        match self {
380            Self::Initialized => {
381                if let Event::Start(tag) = event {
382                    if tag.name().as_ref() == "svg" {
383                        *self = Self::EncounteredSvgTag;
384                    } else {
385                        let tag_name = tag.name().as_ref().to_owned();
386                        return Err(ParseError::UnexpectedRoot(tag_name));
387                    }
388                }
389            }
390
391            Self::EncounteredSvgTag => {
392                if let Event::Start(tag) = event {
393                    if tag.name().as_ref() == "div" {
394                        Self::verify_viewport_attrs(tag.attributes())?;
395                        self.set_state(Self::EncounteredContainer);
396                    } else if tag.name().as_ref() == "g"
397                        && Self::is_svg_container(tag.attributes())?
398                    {
399                        self.set_state(Self::EncounteredContainer);
400                    }
401                }
402            }
403
404            Self::EncounteredContainer => {
405                if let Event::Start(tag) = event {
406                    let classes = parse_classes(tag.attributes())?;
407                    if Self::is_input_class(extract_base_class(&classes)) {
408                        let is_hidden = classes.split(' ').any(|chunk| chunk == "input-hidden");
409                        let exit_status = parse_exit_status(tag.attributes())?;
410                        self.set_state(Self::ReadingUserInput(UserInputState::new(
411                            exit_status,
412                            is_hidden,
413                        )));
414                    }
415                }
416            }
417
418            Self::ReadingUserInput(state) => {
419                if let Some(interaction) = state.process(event, position)? {
420                    self.set_state(Self::EncounteredUserInput(interaction));
421                }
422            }
423
424            Self::EncounteredUserInput(interaction) => {
425                if let Event::Start(tag) = event {
426                    let classes = parse_classes(tag.attributes())?;
427                    let base_class = extract_base_class(&classes);
428
429                    if Self::is_output_class(base_class) {
430                        let interaction = mem::take(interaction);
431                        self.set_state(Self::ReadingTermOutput(
432                            interaction,
433                            TextReadingState::default(),
434                        ));
435                    } else if Self::is_input_class(base_class) {
436                        let interaction = mem::take(interaction);
437                        let exit_status = parse_exit_status(tag.attributes())?;
438                        let is_hidden = classes.split(' ').any(|chunk| chunk == "input-hidden");
439                        self.set_state(Self::ReadingUserInput(UserInputState::new(
440                            exit_status,
441                            is_hidden,
442                        )));
443                        return Ok(Some(interaction.with_empty_output()));
444                    }
445                }
446            }
447
448            Self::ReadingTermOutput(interaction, text_state) => {
449                if let Some(term_output) = text_state.process(event, position)? {
450                    let interaction = mem::take(interaction);
451                    self.set_state(Self::EncounteredContainer);
452                    return Ok(Some(interaction.with_output(term_output)));
453                }
454            }
455        }
456        Ok(None)
457    }
458
459    fn is_input_class(class_name: &str) -> bool {
460        class_name == "input" || class_name == "user-input"
461    }
462
463    fn is_output_class(class_name: &str) -> bool {
464        class_name == "output" || class_name == "term-output"
465    }
466
467    #[cfg_attr(
468        feature = "tracing",
469        tracing::instrument(level = "debug", skip_all, err)
470    )]
471    fn verify_viewport_attrs(attributes: Attributes<'_>) -> Result<(), ParseError> {
472        const HTML_NS: &str = "http://www.w3.org/1999/xhtml";
473
474        let mut has_ns_attribute = false;
475        let mut has_class_attribute = false;
476
477        for attr in attributes {
478            let attr = attr.map_err(quick_xml::Error::InvalidAttr)?;
479            match attr.key.as_ref() {
480                "xmlns" => {
481                    if attr.value.as_ref() != HTML_NS {
482                        return Err(ParseError::InvalidContainer);
483                    }
484                    has_ns_attribute = true;
485                }
486                "class" => {
487                    // Older versions had `div.container` as the top-level HTML element; now, it's wrapped
488                    // in `div.viewport`.
489                    if !["viewport", "container"].contains(&attr.value.as_ref()) {
490                        return Err(ParseError::InvalidContainer);
491                    }
492                    has_class_attribute = true;
493                }
494                _ => { /* Do nothing. */ }
495            }
496        }
497
498        if has_ns_attribute && has_class_attribute {
499            Ok(())
500        } else {
501            Err(ParseError::InvalidContainer)
502        }
503    }
504
505    fn is_svg_container(attributes: Attributes<'_>) -> Result<bool, ParseError> {
506        let classes = parse_classes(attributes)?;
507        Ok(extract_base_class(&classes) == "container")
508    }
509}