librustty 0.0.0

Experimental pure-Rust terminal emulation library; initial releases focus on VT stream parsing
Documentation
#![allow(missing_docs)]

use rustty::{Handler, Parser};

#[derive(Debug, PartialEq, Eq)]
enum Event {
    Print(char),
    Execute(u8),
    Esc {
        final_byte: u8,
        intermediates: Vec<u8>,
        truncated: bool,
    },
    Csi {
        final_byte: u8,
        private: Vec<u8>,
        params: Vec<u8>,
        intermediates: Vec<u8>,
        truncated: bool,
    },
    Osc {
        data: Vec<u8>,
        bell: bool,
        truncated: bool,
    },
    String {
        kind: StringKind,
        final_byte: Option<u8>,
        data: Vec<u8>,
        truncated: bool,
    },
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum StringKind {
    Dcs,
    Apc,
    Pm,
    Sos,
}

#[derive(Default)]
struct Collector {
    events: Vec<Event>,
}

impl Handler for Collector {
    fn print(&mut self, ch: char) {
        self.events.push(Event::Print(ch));
    }

    fn execute(&mut self, byte: u8) {
        self.events.push(Event::Execute(byte));
    }

    fn esc_dispatch(&mut self, event: rustty::EscDispatch<'_>) {
        self.events.push(Event::Esc {
            final_byte: event.final_byte,
            intermediates: event.intermediates.to_vec(),
            truncated: event.truncated,
        });
    }

    fn csi_dispatch(&mut self, event: rustty::CsiDispatch<'_>) {
        self.events.push(Event::Csi {
            final_byte: event.final_byte,
            private: event.private_markers.to_vec(),
            params: event.params.as_bytes().to_vec(),
            intermediates: event.intermediates.to_vec(),
            truncated: event.truncated,
        });
    }

    fn osc_dispatch(&mut self, event: rustty::OscDispatch<'_>) {
        self.events.push(Event::Osc {
            data: event.data.to_vec(),
            bell: event.termination == rustty::StringTermination::Bell,
            truncated: event.truncated,
        });
    }

    fn string_dispatch(&mut self, event: rustty::StringDispatch<'_>) {
        let kind = match event.kind {
            rustty::StringKind::Dcs => StringKind::Dcs,
            rustty::StringKind::Apc => StringKind::Apc,
            rustty::StringKind::Pm => StringKind::Pm,
            rustty::StringKind::Sos => StringKind::Sos,
            rustty::StringKind::Osc => panic!("OSC uses its own callback"),
        };
        self.events.push(Event::String {
            kind,
            final_byte: event.final_byte,
            data: event.data.to_vec(),
            truncated: event.truncated,
        });
    }
}

fn parse(input: &[u8]) -> Vec<Event> {
    let mut parser = Parser::new();
    let mut collector = Collector::default();
    parser.advance(&mut collector, input);
    collector.events
}

#[test]
fn parses_printable_ascii_and_controls() {
    assert_eq!(
        parse(b"abc\r\n\t"),
        vec![
            Event::Print('a'),
            Event::Print('b'),
            Event::Print('c'),
            Event::Execute(b'\r'),
            Event::Execute(b'\n'),
            Event::Execute(b'\t'),
        ]
    );
}

#[test]
fn parses_utf8_and_replaces_invalid_bytes() {
    assert_eq!(
        parse("a€中".as_bytes()),
        vec![Event::Print('a'), Event::Print('€'), Event::Print('中')]
    );
    assert_eq!(
        parse(&[0xF0, 0x28, 0x8C, 0x28]),
        vec![
            Event::Print('\u{FFFD}'),
            Event::Print('('),
            Event::Execute(0x8C),
            Event::Print('('),
        ]
    );
}

#[test]
fn parses_esc_and_csi_sequences() {
    assert_eq!(
        parse(b"\x1b7\x1b(0\x1b[31;1m\x1b[?25l"),
        vec![
            Event::Esc {
                final_byte: b'7',
                intermediates: vec![],
                truncated: false,
            },
            Event::Esc {
                final_byte: b'0',
                intermediates: vec![b'('],
                truncated: false,
            },
            Event::Csi {
                final_byte: b'm',
                private: vec![],
                params: b"31;1".to_vec(),
                intermediates: vec![],
                truncated: false,
            },
            Event::Csi {
                final_byte: b'l',
                private: vec![b'?'],
                params: b"25".to_vec(),
                intermediates: vec![],
                truncated: false,
            },
        ]
    );
}

#[test]
fn preserves_colon_subparameters_and_empty_values() {
    let mut parser = Parser::new();
    let mut collector = Collector::default();
    parser.advance(&mut collector, b"\x1b[38:2::255:0:0m\x1b[;m");

    assert_eq!(collector.events.len(), 2);
    let Event::Csi { params, .. } = &collector.events[0] else {
        panic!("expected CSI")
    };
    assert_eq!(params, b"38:2::255:0:0");

    let Event::Csi { params, .. } = &collector.events[1] else {
        panic!("expected CSI")
    };
    assert_eq!(params, b";");

    let mut parser = Parser::new();
    let mut values = ParamsCollector::default();
    parser.advance(&mut values, b"\x1b[38:2::255:0:0m");
    assert_eq!(
        values.values,
        vec![vec![Some(38), Some(2), None, Some(255), Some(0), Some(0)]]
    );
}

#[derive(Default)]
struct ParamsCollector {
    values: Vec<Vec<Option<u64>>>,
}

impl Handler for ParamsCollector {
    fn csi_dispatch(&mut self, event: rustty::CsiDispatch<'_>) {
        self.values.push(
            event
                .params
                .iter()
                .flat_map(|param| param.subparams().map(rustty::Subparam::value))
                .collect(),
        );
    }
}

#[test]
fn parses_osc_terminators_and_split_payloads() {
    assert_eq!(
        parse(b"\x1b]0;title\x07\x1b]1;other\x1b\\\x9dthird\x9c"),
        vec![
            Event::Osc {
                data: b"0;title".to_vec(),
                bell: true,
                truncated: false,
            },
            Event::Osc {
                data: b"1;other".to_vec(),
                bell: false,
                truncated: false,
            },
            Event::Osc {
                data: b"third".to_vec(),
                bell: false,
                truncated: false,
            },
        ]
    );

    let mut parser = Parser::new();
    let mut collector = Collector::default();
    for byte in b"\x1b]0;split\x1b\\" {
        parser.advance(&mut collector, &[*byte]);
    }
    assert_eq!(
        collector.events,
        vec![Event::Osc {
            data: b"0;split".to_vec(),
            bell: false,
            truncated: false,
        }]
    );
}

#[test]
fn recognizes_other_control_strings() {
    assert_eq!(
        parse(b"\x1bPdcs\x1b\\\x1b_apc\x1b\\\x1b^pm\x1b\\\x1bXsos\x1b\\"),
        vec![
            Event::String {
                kind: StringKind::Dcs,
                final_byte: Some(b'd'),
                data: b"cs".to_vec(),
                truncated: false,
            },
            Event::String {
                kind: StringKind::Apc,
                final_byte: None,
                data: b"apc".to_vec(),
                truncated: false,
            },
            Event::String {
                kind: StringKind::Pm,
                final_byte: None,
                data: b"pm".to_vec(),
                truncated: false,
            },
            Event::String {
                kind: StringKind::Sos,
                final_byte: None,
                data: b"sos".to_vec(),
                truncated: false,
            },
        ]
    );
}

#[test]
fn cancellation_discards_pending_sequences() {
    assert_eq!(
        parse(b"\x1b[31\x18mA"),
        vec![Event::Print('m'), Event::Print('A')]
    );
    assert_eq!(parse(b"\x1b]discard\x1am"), vec![Event::Print('m')]);
}

#[test]
fn raw_c1_introducers_are_controls_not_text() {
    assert_eq!(
        parse(b"\x9b31m\x9dtitle\x07"),
        vec![
            Event::Csi {
                final_byte: b'm',
                private: vec![],
                params: b"31".to_vec(),
                intermediates: vec![],
                truncated: false,
            },
            Event::Osc {
                data: b"title".to_vec(),
                bell: true,
                truncated: false,
            },
        ]
    );
}

#[test]
fn c1_introducers_replace_pending_sequences() {
    assert_eq!(
        parse(b"\x1b[31\x9dtitle\x07"),
        vec![Event::Osc {
            data: b"title".to_vec(),
            bell: true,
            truncated: false,
        }]
    );
    assert_eq!(
        parse(b"\x1b]old\x9b31m"),
        vec![Event::Csi {
            final_byte: b'm',
            private: vec![],
            params: b"31".to_vec(),
            intermediates: vec![],
            truncated: false,
        }]
    );
}

#[test]
fn delete_is_ignored_in_ground_and_control_states() {
    assert_eq!(parse(b"a\x7fb"), vec![Event::Print('a'), Event::Print('b')]);
    assert_eq!(
        parse(b"\x1b[1\x7f;m"),
        vec![Event::Csi {
            final_byte: b'm',
            private: vec![],
            params: b"1;".to_vec(),
            intermediates: vec![],
            truncated: false,
        }]
    );
}

#[test]
fn reset_discards_state_and_allows_reuse() {
    let mut parser = Parser::new();
    let mut collector = Collector::default();
    parser.advance(&mut collector, b"\x1b[31");
    parser.reset();
    parser.advance(&mut collector, b"ok");
    parser.finish(&mut collector);
    assert_eq!(collector.events, vec![Event::Print('o'), Event::Print('k')]);
}

#[test]
fn finish_replaces_incomplete_utf8_and_discards_incomplete_sequences() {
    let mut parser = Parser::new();
    let mut collector = Collector::default();
    parser.advance(&mut collector, b"x\xE2\x82\x1b[31");
    parser.finish(&mut collector);
    parser.advance(&mut collector, b"y");
    assert_eq!(
        collector.events,
        vec![
            Event::Print('x'),
            Event::Print('\u{FFFD}'),
            Event::Print('y'),
        ]
    );
}