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}