mbterm 0.1.4

ANSI terminal renderer for MBDown documents
Documentation
//! Terminal escape-sequence scanning shared by rendering and plain-text output.

/// OSC 8 hyperlink close using the string-terminator form.
pub(crate) const OSC8_CLOSE: &str = "\x1b]8;;\x1b\\";

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Token<'a> {
    Char(char),
    Sequence(Sequence<'a>),
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct Sequence<'a> {
    value: &'a str,
    kind: SequenceKind,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum SequenceKind {
    Csi { final_byte: Option<u8> },
    Osc { terminated: bool },
    StringControl,
    Control,
    Escape,
    TruncatedEscape,
}

impl<'a> Sequence<'a> {
    pub(crate) fn as_str(self) -> &'a str {
        self.value
    }

    pub(crate) fn is_sgr(self) -> bool {
        matches!(
            self.kind,
            SequenceKind::Csi {
                final_byte: Some(b'm')
            }
        )
    }

    pub(crate) fn is_sgr_reset(self) -> bool {
        self.is_sgr()
            && matches!(
                self.value,
                "\x1b[m" | "\x1b[0m" | "\u{009b}m" | "\u{009b}0m"
            )
    }

    pub(crate) fn osc8(self) -> Option<Osc8<'a>> {
        if !matches!(self.kind, SequenceKind::Osc { terminated: true }) {
            return None;
        }
        let value = self
            .value
            .strip_prefix("\x1b]")
            .or_else(|| self.value.strip_prefix('\u{009d}'))?;
        let payload = value
            .strip_suffix('\x07')
            .or_else(|| value.strip_suffix("\x1b\\"))
            .or_else(|| value.strip_suffix('\u{009c}'))?;
        let mut fields = payload.splitn(3, ';');
        if fields.next()? != "8" {
            return None;
        }
        let _parameters = fields.next()?;
        let uri = fields.next()?;
        Some(if uri.is_empty() {
            Osc8::Close
        } else {
            Osc8::Open(self.value)
        })
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Osc8<'a> {
    Open(&'a str),
    Close,
}

pub(crate) fn tokens(input: &str) -> Tokens<'_> {
    Tokens { input, index: 0 }
}

pub(crate) struct Tokens<'a> {
    input: &'a str,
    index: usize,
}

impl<'a> Iterator for Tokens<'a> {
    type Item = Token<'a>;

    fn next(&mut self) -> Option<Self::Item> {
        let rest = self.input.get(self.index..)?;
        if rest.is_empty() {
            return None;
        }
        let character = rest
            .chars()
            .next()
            .expect("non-empty input starts on a UTF-8 boundary");
        let parsed = match character {
            '\x1b' => Some(sequence(rest)),
            '\u{0090}' | '\u{0098}' | '\u{009e}' | '\u{009f}' => Some(string_control(
                rest,
                character.len_utf8(),
                SequenceKind::StringControl,
                false,
            )),
            '\u{009d}' => Some(string_control(
                rest,
                character.len_utf8(),
                SequenceKind::Osc { terminated: false },
                true,
            )),
            '\u{009b}' => Some(csi(rest.as_bytes(), character.len_utf8())),
            '\u{0080}'..='\u{009f}' => Some((character.len_utf8(), SequenceKind::Control)),
            _ => None,
        };
        let Some((length, kind)) = parsed else {
            self.index += character.len_utf8();
            return Some(Token::Char(character));
        };

        let value = &rest[..length];
        self.index += length;
        Some(Token::Sequence(Sequence { value, kind }))
    }
}

fn sequence(input: &str) -> (usize, SequenceKind) {
    let Some(next) = input[1..].chars().next() else {
        return (1, SequenceKind::TruncatedEscape);
    };
    match next {
        '[' => csi(input.as_bytes(), 2),
        ']' => string_control(input, 2, SequenceKind::Osc { terminated: false }, true),
        'P' | 'X' | '^' | '_' => string_control(input, 2, SequenceKind::StringControl, false),
        _ => escape(input.as_bytes()),
    }
}

fn csi(bytes: &[u8], mut index: usize) -> (usize, SequenceKind) {
    while bytes
        .get(index)
        .is_some_and(|byte| (0x30..=0x3f).contains(byte))
    {
        index += 1;
    }
    while bytes
        .get(index)
        .is_some_and(|byte| (0x20..=0x2f).contains(byte))
    {
        index += 1;
    }
    match bytes.get(index).copied() {
        Some(final_byte) if (0x40..=0x7e).contains(&final_byte) => (
            index + 1,
            SequenceKind::Csi {
                final_byte: Some(final_byte),
            },
        ),
        _ => (index, SequenceKind::Csi { final_byte: None }),
    }
}

fn escape(bytes: &[u8]) -> (usize, SequenceKind) {
    let mut index = 1;
    while bytes
        .get(index)
        .is_some_and(|byte| (0x20..=0x2f).contains(byte))
    {
        index += 1;
    }
    match bytes.get(index) {
        Some(byte) if (0x30..=0x7e).contains(byte) => (index + 1, SequenceKind::Escape),
        _ => (index, SequenceKind::TruncatedEscape),
    }
}

fn string_control(
    input: &str,
    mut index: usize,
    unterminated_kind: SequenceKind,
    accepts_bel: bool,
) -> (usize, SequenceKind) {
    while index < input.len() {
        let rest = &input[index..];
        if accepts_bel && rest.starts_with('\x07') {
            return (index + 1, terminated_string_kind(unterminated_kind));
        }
        if rest.starts_with("\x1b\\") {
            return (index + 2, terminated_string_kind(unterminated_kind));
        }
        if rest.starts_with('\u{009c}') {
            return (
                index + '\u{009c}'.len_utf8(),
                terminated_string_kind(unterminated_kind),
            );
        }
        index += rest
            .chars()
            .next()
            .expect("non-empty remainder starts on a UTF-8 boundary")
            .len_utf8();
    }
    (input.len(), unterminated_kind)
}

fn terminated_string_kind(kind: SequenceKind) -> SequenceKind {
    match kind {
        SequenceKind::Osc { .. } => SequenceKind::Osc { terminated: true },
        _ => kind,
    }
}

/// Remove CSI, OSC, string controls, and other terminal sequences from `input`.
///
/// Incomplete sequences are removed through the end of the input. Ordinary
/// Unicode text is retained unchanged.
pub fn strip_terminal_sequences(input: &str) -> String {
    tokens(input)
        .filter_map(|token| match token {
            Token::Char(character) => Some(character),
            Token::Sequence(_) => None,
        })
        .collect()
}

/// Remove OSC 8 hyperlink boundaries while preserving their visible labels
/// and every other terminal sequence, including SGR text styling.
pub fn strip_osc8_sequences(input: &str) -> String {
    let mut output = String::with_capacity(input.len());
    for token in tokens(input) {
        match token {
            Token::Char(character) => output.push(character),
            Token::Sequence(sequence) if sequence.osc8().is_some() => {}
            Token::Sequence(sequence) => output.push_str(sequence.as_str()),
        }
    }
    output
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn strips_csi_osc_and_other_escape_sequences() {
        let input = concat!(
            "前\x1b[38:2:1:2:3m景\x1b[0m",
            "\x1b]8;;https://example.test/路径\x07链接\x1b]8;;\x1b\\",
            "\x1b7后"
        );
        assert_eq!(strip_terminal_sequences(input), "前景链接后");
    }

    #[test]
    fn strips_string_controls_through_st() {
        for introducer in ["\x1bP", "\x1bX", "\x1b^", "\x1b_"] {
            assert_eq!(
                strip_terminal_sequences(&format!("a{introducer}secret\x1b\\b")),
                "ab"
            );
            assert_eq!(
                strip_terminal_sequences(&format!("a{introducer}秘密\u{009c}b")),
                "ab"
            );
        }
    }

    #[test]
    fn strips_c1_controls_as_unicode_scalars() {
        for introducer in ['\u{0090}', '\u{0098}', '\u{009e}', '\u{009f}'] {
            assert_eq!(
                strip_terminal_sequences(&format!("a{introducer}秘密\u{009c}b")),
                "ab"
            );
        }
        assert_eq!(
            strip_terminal_sequences("a\u{009b}31mred\u{009b}0mb"),
            "aredb"
        );
        assert_eq!(strip_terminal_sequences("a\u{0085}b\u{009c}c"), "abc");
        assert_eq!(strip_terminal_sequences("a\u{015b}b"), "a\u{015b}b");
    }

    #[test]
    fn safely_consumes_truncated_sequences_after_unicode() {
        assert_eq!(strip_terminal_sequences("你好\x1b"), "你好");
        assert_eq!(strip_terminal_sequences("你好\x1b[31"), "你好");
        assert_eq!(strip_terminal_sequences("你好\x1b]8;;链接"), "你好");
        assert_eq!(strip_terminal_sequences("你好\x1bP载荷"), "你好");
        assert_eq!(strip_terminal_sequences("你好\u{0090}载荷"), "你好");
        assert_eq!(strip_terminal_sequences("你好\x1b界"), "你好界");
    }

    #[test]
    fn malformed_sequences_do_not_swallow_following_utf8_text() {
        assert_eq!(strip_terminal_sequences("a\x1b[31中b"), "a中b");
        assert_eq!(strip_terminal_sequences("a\x1b(中b"), "a中b");
    }

    #[test]
    fn recognizes_bel_and_st_terminated_osc8() {
        let mut links = tokens(concat!(
            "\x1b]8;;https://a\x07x\x1b]8;;\x1b\\",
            "\u{009d}8;;https://b\u{009c}y\u{009d}8;;\x1b\\"
        ))
        .filter_map(|token| match token {
            Token::Sequence(sequence) => sequence.osc8(),
            Token::Char(_) => None,
        });
        assert_eq!(links.next(), Some(Osc8::Open("\x1b]8;;https://a\x07")));
        assert_eq!(links.next(), Some(Osc8::Close));
        assert_eq!(
            links.next(),
            Some(Osc8::Open("\u{009d}8;;https://b\u{009c}"))
        );
        assert_eq!(links.next(), Some(Osc8::Close));
        assert_eq!(links.next(), None);
    }

    #[test]
    fn strips_only_osc8_boundaries() {
        let input = concat!(
            "\x1b[1;31m",
            "\x1b]8;;https://example.test\x1b\\",
            "label",
            "\x1b]8;;\x1b\\",
            "\x1b[0m"
        );
        assert_eq!(strip_osc8_sequences(input), "\x1b[1;31mlabel\x1b[0m");
    }
}