Skip to main content

rustty/vt/
event.rs

1//! Borrowed events emitted by the VT parser.
2
3use super::params::Params;
4
5/// The kind of control string that was dispatched.
6#[derive(Clone, Copy, Debug, PartialEq, Eq)]
7pub enum StringKind {
8    /// An operating-system command introduced by OSC.
9    Osc,
10    /// A device-control string introduced by DCS.
11    Dcs,
12    /// An application-program command introduced by APC.
13    Apc,
14    /// A privacy-message string introduced by PM.
15    Pm,
16    /// A system-function string introduced by SOS.
17    Sos,
18}
19
20/// The way a control string reached its final dispatch.
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum StringTermination {
23    /// OSC was terminated by the BEL byte.
24    Bell,
25    /// The string was terminated by ST, either `ESC \\` or the 8-bit C1 ST.
26    St,
27}
28
29/// An ESC sequence whose final byte was dispatched.
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct EscDispatch<'a> {
32    /// The final byte of the sequence.
33    pub final_byte: u8,
34    /// Intermediate bytes between ESC and the final byte.
35    pub intermediates: &'a [u8],
36    /// Whether an intermediate limit caused the sequence to be truncated.
37    pub truncated: bool,
38}
39
40impl EscDispatch<'_> {
41    /// Returns the final byte as a Unicode scalar when it is valid ASCII.
42    #[must_use]
43    pub fn final_char(self) -> Option<char> {
44        char::from_u32(u32::from(self.final_byte))
45    }
46}
47
48/// A CSI sequence whose final byte was dispatched.
49#[derive(Clone, Copy, Debug, PartialEq, Eq)]
50pub struct CsiDispatch<'a> {
51    /// The final byte of the sequence.
52    pub final_byte: u8,
53    /// Private parameter marker bytes such as `?` or `>`.
54    pub private_markers: &'a [u8],
55    /// Semicolon- and colon-separated parameters.
56    pub params: Params<'a>,
57    /// Intermediate bytes between parameters and the final byte.
58    pub intermediates: &'a [u8],
59    /// Whether a parameter or intermediate limit caused the sequence to be
60    /// truncated and ignored until its final byte.
61    pub truncated: bool,
62}
63
64impl CsiDispatch<'_> {
65    /// Returns the final byte as a Unicode scalar when it is valid ASCII.
66    #[must_use]
67    pub fn final_char(self) -> Option<char> {
68        char::from_u32(u32::from(self.final_byte))
69    }
70
71    /// Returns the private parameter markers.
72    #[must_use]
73    pub fn private(&self) -> &[u8] {
74        self.private_markers
75    }
76}
77
78/// An OSC sequence whose payload was dispatched.
79#[derive(Clone, Copy, Debug, PartialEq, Eq)]
80pub struct OscDispatch<'a> {
81    /// The bytes between the OSC introducer and its terminator.
82    pub data: &'a [u8],
83    /// The terminator used by the OSC sequence.
84    pub termination: StringTermination,
85    /// Whether the payload exceeded the configured string limit.
86    pub truncated: bool,
87}
88
89impl OscDispatch<'_> {
90    /// Returns the payload as UTF-8 when it is valid.
91    #[must_use]
92    pub fn as_str(&self) -> Option<&str> {
93        core::str::from_utf8(self.data).ok()
94    }
95}
96
97/// A DCS, APC, PM, or SOS sequence whose payload was dispatched.
98#[derive(Clone, Copy, Debug, PartialEq, Eq)]
99pub struct StringDispatch<'a> {
100    /// The control-string family.
101    pub kind: StringKind,
102    /// The final byte of a DCS introducer, when one was recognized.
103    pub final_byte: Option<u8>,
104    /// Private parameter marker bytes from a DCS introducer.
105    pub private_markers: &'a [u8],
106    /// Parameters from a DCS introducer.
107    pub params: Params<'a>,
108    /// Intermediate bytes from a DCS introducer.
109    pub intermediates: &'a [u8],
110    /// The passthrough bytes after a DCS final byte, or all bytes after the
111    /// introducer for APC, PM, and SOS.
112    pub data: &'a [u8],
113    /// The terminator used by the string.
114    pub termination: StringTermination,
115    /// Whether a parser limit caused the sequence or payload to be truncated.
116    pub truncated: bool,
117}
118
119impl StringDispatch<'_> {
120    /// Returns the payload as UTF-8 when it is valid.
121    #[must_use]
122    pub fn as_str(&self) -> Option<&str> {
123        core::str::from_utf8(self.data).ok()
124    }
125}
126
127/// Receives synchronous, borrowed parser events.
128///
129/// Every event view is valid only during its callback. A handler that needs to
130/// retain bytes must copy them before returning. The default methods make it
131/// possible to implement only the event families a caller needs.
132pub trait Handler {
133    /// Handles one decoded printable Unicode scalar.
134    fn print(&mut self, _ch: char) {}
135
136    /// Handles a C0 or C1 control byte that is not a sequence introducer.
137    fn execute(&mut self, _byte: u8) {}
138
139    /// Handles a completed ESC sequence.
140    fn esc_dispatch(&mut self, _event: EscDispatch<'_>) {}
141
142    /// Handles a completed CSI sequence.
143    fn csi_dispatch(&mut self, _event: CsiDispatch<'_>) {}
144
145    /// Handles a completed OSC sequence.
146    fn osc_dispatch(&mut self, _event: OscDispatch<'_>) {}
147
148    /// Handles a completed DCS, APC, PM, or SOS sequence.
149    fn string_dispatch(&mut self, _event: StringDispatch<'_>) {}
150}