/rust/registry/src/index.crates.io-1949cf8c6b5b557f/anstyle-parse-0.2.7/src/lib.rs

Source
//! Parser for implementing virtual terminal emulators
//!
//! [`Parser`] is implemented according to [Paul Williams' ANSI parser
//! state machine]. The state machine doesn't assign meaning to the parsed data
//! and is thus not itself sufficient for writing a terminal emulator. Instead,
//! it is expected that an implementation of [`Perform`] is provided which does
//! something useful with the parsed data. The [`Parser`] handles the book
//! keeping, and the [`Perform`] gets to simply handle actions.
//!
//! # Examples
//!
//! For an example of using the [`Parser`] please see the examples folder. The example included
//! there simply logs all the actions [`Perform`] does. One quick thing to see it in action is to
//! pipe `vim` into it
//!
//! ```sh
//! cargo build --release --example parselog
//! vim | target/release/examples/parselog
//! ```
//!
//! Just type `:q` to exit.
//!
//! # Differences from original state machine description
//!
//! * UTF-8 Support for Input
//! * OSC Strings can be terminated by 0x07
//! * Only supports 7-bit codes. Some 8-bit codes are still supported, but they no longer work in
//!   all states.
//!
//! [Paul Williams' ANSI parser state machine]: https://vt100.net/emu/dec_ansi_parser
#![cfg_attr(not(test), no_std)]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![allow(missing_docs)]
#![warn(clippy::print_stderr)]
#![warn(clippy::print_stdout)]

#[cfg(not(feature = "core"))]
extern crate alloc;

use core::mem::MaybeUninit;

#[cfg(feature = "core")]
use arrayvec::ArrayVec;
#[cfg(feature = "utf8")]
use utf8parse as utf8;

mod params;
pub mod state;

pub use params::{Params, ParamsIter};

use state::{state_change, Action, State};

const MAX_INTERMEDIATES: usize = 2;
const MAX_OSC_PARAMS: usize = 16;
#[cfg(feature = "core")]
const MAX_OSC_RAW: usize = 1024;

/// Parser for raw _VTE_ protocol which delegates actions to a [`Perform`]
#[allow(unused_qualifications)]
#[derive(Default, Clone, Debug, PartialEq, Eq)]
pub struct Parser<C = DefaultCharAccumulator> {
    state: State,
    intermediates: [u8; MAX_INTERMEDIATES],
    intermediate_idx: usize,
    params: Params,
    param: u16,
    #[cfg(feature = "core")]
    osc_raw: ArrayVec<u8, MAX_OSC_RAW>,
    #[cfg(not(feature = "core"))]
    osc_raw: alloc::vec::Vec<u8>,
    osc_params: [(usize, usize); MAX_OSC_PARAMS],
    osc_num_params: usize,
    ignoring: bool,
    utf8_parser: C,
}

impl<C> Parser<C>
where
    C: CharAccumulator,
{
    /// Create a new Parser
    pub fn new() -> Parser {
        Parser::default()
    }

    #[inline]
    fn params(&self) -> &Params {
        &self.params
    }

    #[inline]
    fn intermediates(&self) -> &[u8] {
        &self.intermediates[..self.intermediate_idx]
    }

    /// Advance the parser state
    ///
    /// Requires a [`Perform`] in case `byte` triggers an action
    #[inline]
    pub fn advance<P: Perform>(&mut self, performer: &mut P, byte: u8) {
        // Utf8 characters are handled out-of-band.
        if let State::Utf8 = self.state {
            self.process_utf8(performer, byte);
            return;
        }

        let (state, action) = state_change(self.state, byte);
        self.perform_state_change(performer, state, action, byte);
    }

    #[inline]
    fn process_utf8<P>(&mut self, performer: &mut P, byte: u8)
    where
        P: Perform,
    {
        if let Some(c) = self.utf8_parser.add(byte) {
            performer.print(c);
            self.state = State::Ground;
        }
    }

    #[inline]
    fn perform_state_change<P>(&mut self, performer: &mut P, state: State, action: Action, byte: u8)
    where
        P: Perform,
    {
        match state {
            State::Anywhere => {
                // Just run the action
                self.perform_action(performer, action, byte);
            }
            state => {
                match self.state {
                    State::DcsPassthrough => {
                        self.perform_action(performer, Action::Unhook, byte);
                    }
                    State::OscString => {
                        self.perform_action(performer, Action::OscEnd, byte);
                    }
                    _ => (),
                }

                match action {
                    Action::Nop => (),
                    action => {
                        self.perform_action(performer, action, byte);
                    }
                }

                match state {
                    State::CsiEntry | State::DcsEntry | State::Escape => {
                        self.perform_action(performer, Action::Clear, byte);
                    }
                    State::DcsPassthrough => {
                        self.perform_action(performer, Action::Hook, byte);
                    }
                    State::OscString => {
                        self.perform_action(performer, Action::OscStart, byte);
                    }
                    _ => (),
                }

                // Assume the new state
                self.state = state;
            }
        }
    }

    /// Separate method for `osc_dispatch` that borrows self as read-only
    ///
    /// The aliasing is needed here for multiple slices into `self.osc_raw`
    #[inline]
    fn osc_dispatch<P: Perform>(&self, performer: &mut P, byte: u8) {
        let mut slices: [MaybeUninit<&[u8]>; MAX_OSC_PARAMS] =
            unsafe { MaybeUninit::uninit().assume_init() };

        for (i, slice) in slices.iter_mut().enumerate().take(self.osc_num_params) {
            let indices = self.osc_params[i];
            *slice = MaybeUninit::new(&self.osc_raw[indices.0..indices.1]);
        }

        unsafe {
            let num_params = self.osc_num_params;
            let params = &slices[..num_params] as *const [MaybeUninit<&[u8]>] as *const [&[u8]];
            performer.osc_dispatch(&*params, byte == 0x07);
        }
    }

    #[inline]
    fn perform_action<P: Perform>(&mut self, performer: &mut P, action: Action, byte: u8) {
        match action {
            Action::Print => performer.print(byte as char),
            Action::Execute => performer.execute(byte),
            Action::Hook => {
                if self.params.is_full() {
                    self.ignoring = true;
                } else {
                    self.params.push(self.param);
                }

                performer.hook(self.params(), self.intermediates(), self.ignoring, byte);
            }
            Action::Put => performer.put(byte),
            Action::OscStart => {
                self.osc_raw.clear();
                self.osc_num_params = 0;
            }
            Action::OscPut => {
                #[cfg(feature = "core")]
                {
                    if self.osc_raw.is_full() {
                        return;
                    }
                }

                let idx = self.osc_raw.len();

                // Param separator
                if byte == b';' {
                    let param_idx = self.osc_num_params;
                    match param_idx {
                        // Only process up to MAX_OSC_PARAMS
                        MAX_OSC_PARAMS => return,

                        // First param is special - 0 to current byte index
                        0 => {
                            self.osc_params[param_idx] = (0, idx);
                        }

                        // All other params depend on previous indexing
                        _ => {
                            let prev = self.osc_params[param_idx - 1];
                            let begin = prev.1;
                            self.osc_params[param_idx] = (begin, idx);
                        }
                    }

                    self.osc_num_params += 1;
                } else {
                    self.osc_raw.push(byte);
                }
            }
            Action::OscEnd => {
                let param_idx = self.osc_num_params;
                let idx = self.osc_raw.len();

                match param_idx {
                    // Finish last parameter if not already maxed
                    MAX_OSC_PARAMS => (),

                    // First param is special - 0 to current byte index
                    0 => {
                        self.osc_params[param_idx] = (0, idx);
                        self.osc_num_params += 1;
                    }

                    // All other params depend on previous indexing
                    _ => {
                        let prev = self.osc_params[param_idx - 1];
                        let begin = prev.1;
                        self.osc_params[param_idx] = (begin, idx);
                        self.osc_num_params += 1;
                    }
                }
                self.osc_dispatch(performer, byte);
            }
            Action::Unhook => performer.unhook(),
            Action::CsiDispatch => {
                if self.params.is_full() {
                    self.ignoring = true;
                } else {
                    self.params.push(self.param);
                }

                performer.csi_dispatch(self.params(), self.intermediates(), self.ignoring, byte);
            }
            Action::EscDispatch => {
                performer.esc_dispatch(self.intermediates(), self.ignoring, byte);
            }
            Action::Collect => {
                if self.intermediate_idx == MAX_INTERMEDIATES {
                    self.ignoring = true;
                } else {
                    self.intermediates[self.intermediate_idx] = byte;
                    self.intermediate_idx += 1;
                }
            }
            Action::Param => {
                if self.params.is_full() {
                    self.ignoring = true;
                    return;
                }

                if byte == b';' {
                    self.params.push(self.param);
                    self.param = 0;
                } else if byte == b':' {
                    self.params.extend(self.param);
                    self.param = 0;
                } else {
                    // Continue collecting bytes into param
                    self.param = self.param.saturating_mul(10);
                    self.param = self.param.saturating_add((byte - b'0') as u16);
                }
            }
            Action::Clear => {
                // Reset everything on ESC/CSI/DCS entry
                self.intermediate_idx = 0;
                self.ignoring = false;
                self.param = 0;

                self.params.clear();
            }
            Action::BeginUtf8 => self.process_utf8(performer, byte),
            Action::Ignore => (),
            Action::Nop => (),
        }
    }
}

/// Build a `char` out of bytes
pub trait CharAccumulator: Default {
    /// Build a `char` out of bytes
    ///
    /// Return `None` when more data is needed
    fn add(&mut self, byte: u8) -> Option<char>;
}

/// Most flexible [`CharAccumulator`] for [`Parser`] based on active features
#[cfg(feature = "utf8")]
pub type DefaultCharAccumulator = Utf8Parser;
#[cfg(not(feature = "utf8"))]
pub type DefaultCharAccumulator = AsciiParser;

/// Only allow parsing 7-bit ASCII
#[allow(clippy::exhaustive_structs)]
#[derive(Default, Clone, Debug, PartialEq, Eq)]
pub struct AsciiParser;

impl CharAccumulator for AsciiParser {
    fn add(&mut self, _byte: u8) -> Option<char> {
        unreachable!("multi-byte UTF8 characters are unsupported")
    }
}

/// Allow parsing UTF-8
#[cfg(feature = "utf8")]
#[derive(Default, Clone, Debug, PartialEq, Eq)]
pub struct Utf8Parser {
    utf8_parser: utf8::Parser,
}

#[cfg(feature = "utf8")]
impl CharAccumulator for Utf8Parser {
    fn add(&mut self, byte: u8) -> Option<char> {
        let mut c = None;
        let mut receiver = VtUtf8Receiver(&mut c);
        self.utf8_parser.advance(&mut receiver, byte);
        c
    }
}

#[cfg(feature = "utf8")]
struct VtUtf8Receiver<'a>(&'a mut Option<char>);

#[cfg(feature = "utf8")]
impl utf8::Receiver for VtUtf8Receiver<'_> {
    fn codepoint(&mut self, c: char) {
        *self.0 = Some(c);
    }

    fn invalid_sequence(&mut self) {
        *self.0 = Some('�');
    }
}

/// Performs actions requested by the [`Parser`]
///
/// Actions in this case mean, for example, handling a CSI escape sequence describing cursor
/// movement, or simply printing characters to the screen.
///
/// The methods on this type correspond to actions described in
/// <http://vt100.net/emu/dec_ansi_parser>. I've done my best to describe them in
/// a useful way in my own words for completeness, but the site should be
/// referenced if something isn't clear. If the site disappears at some point in
/// the future, consider checking archive.org.
pub trait Perform {
    /// Draw a character to the screen and update states.
    fn print(&mut self, _c: char) {}

    /// Execute a C0 or C1 control function.
    fn execute(&mut self, _byte: u8) {}

    /// Invoked when a final character arrives in first part of device control string.
    ///
    /// The control function should be determined from the private marker, final character, and
    /// execute with a parameter list. A handler should be selected for remaining characters in the
    /// string; the handler function should subsequently be called by `put` for every character in
    /// the control string.
    ///
    /// The `ignore` flag indicates that more than two intermediates arrived and
    /// subsequent characters were ignored.
    fn hook(&mut self, _params: &Params, _intermediates: &[u8], _ignore: bool, _action: u8) {}

    /// Pass bytes as part of a device control string to the handle chosen in `hook`. C0 controls
    /// will also be passed to the handler.
    fn put(&mut self, _byte: u8) {}

    /// Called when a device control string is terminated.
    ///
    /// The previously selected handler should be notified that the DCS has
    /// terminated.
    fn unhook(&mut self) {}

    /// Dispatch an operating system command.
    fn osc_dispatch(&mut self, _params: &[&[u8]], _bell_terminated: bool) {}

    /// A final character has arrived for a CSI sequence
    ///
    /// The `ignore` flag indicates that either more than two intermediates arrived
    /// or the number of parameters exceeded the maximum supported length,
    /// and subsequent characters were ignored.
    fn csi_dispatch(
        &mut self,
        _params: &Params,
        _intermediates: &[u8],
        _ignore: bool,
        _action: u8,
    ) {
    }

    /// The final character of an escape sequence has arrived.
    ///
    /// The `ignore` flag indicates that more than two intermediates arrived and
    /// subsequent characters were ignored.
    fn esc_dispatch(&mut self, _intermediates: &[u8], _ignore: bool, _byte: u8) {}
}

#[doc = include_str!("../README.md")]
#[cfg(doctest)]
pub struct ReadmeDoctests;

Coverage Report

Created: 2026-02-18 06:58

Line	Count	Source
1		//! Parser for implementing virtual terminal emulators
2		//!
3		//! [`Parser`] is implemented according to [Paul Williams' ANSI parser
4		//! state machine]. The state machine doesn't assign meaning to the parsed data
5		//! and is thus not itself sufficient for writing a terminal emulator. Instead,
6		//! it is expected that an implementation of [`Perform`] is provided which does
7		//! something useful with the parsed data. The [`Parser`] handles the book
8		//! keeping, and the [`Perform`] gets to simply handle actions.
9		//!
10		//! # Examples
11		//!
12		//! For an example of using the [`Parser`] please see the examples folder. The example included
13		//! there simply logs all the actions [`Perform`] does. One quick thing to see it in action is to
14		//! pipe `vim` into it
15		//!
16		//! ```sh
17		//! cargo build --release --example parselog
18		//! vim \| target/release/examples/parselog
19		//! ```
20		//!
21		//! Just type `:q` to exit.
22		//!
23		//! # Differences from original state machine description
24		//!
25		//! * UTF-8 Support for Input
26		//! * OSC Strings can be terminated by 0x07
27		//! * Only supports 7-bit codes. Some 8-bit codes are still supported, but they no longer work in
28		//! all states.
29		//!
30		//! [Paul Williams' ANSI parser state machine]: https://vt100.net/emu/dec_ansi_parser
31		#![cfg_attr(not(test), no_std)]
32		#![cfg_attr(docsrs, feature(doc_auto_cfg))]
33		#![allow(missing_docs)]
34		#![warn(clippy::print_stderr)]
35		#![warn(clippy::print_stdout)]
36
37		#[cfg(not(feature = "core"))]
38		extern crate alloc;
39
40		use core::mem::MaybeUninit;
41
42		#[cfg(feature = "core")]
43		use arrayvec::ArrayVec;
44		#[cfg(feature = "utf8")]
45		use utf8parse as utf8;
46
47		mod params;
48		pub mod state;
49
50		pub use params::{Params, ParamsIter};
51
52		use state::{state_change, Action, State};
53
54		const MAX_INTERMEDIATES: usize = 2;
55		const MAX_OSC_PARAMS: usize = 16;
56		#[cfg(feature = "core")]
57		const MAX_OSC_RAW: usize = 1024;
58
59		/// Parser for raw _VTE_ protocol which delegates actions to a [`Perform`]
60		#[allow(unused_qualifications)]
61		#[derive(Default, Clone, Debug, PartialEq, Eq)]
62		pub struct Parser<C = DefaultCharAccumulator> {
63		state: State,
64		intermediates: [u8; MAX_INTERMEDIATES],
65		intermediate_idx: usize,
66		params: Params,
67		param: u16,
68		#[cfg(feature = "core")]
69		osc_raw: ArrayVec<u8, MAX_OSC_RAW>,
70		#[cfg(not(feature = "core"))]
71		osc_raw: alloc::vec::Vec<u8>,
72		osc_params: [(usize, usize); MAX_OSC_PARAMS],
73		osc_num_params: usize,
74		ignoring: bool,
75		utf8_parser: C,
76		}
77
78		impl<C> Parser<C>
79		where
80		C: CharAccumulator,
81		{
82		/// Create a new Parser
83	0	pub fn new() -> Parser {
84	0	Parser::default()
85	0	}
86
87		#[inline]
88	0	fn params(&self) -> &Params {
89	0	&self.params
90	0	}
91
92		#[inline]
93	0	fn intermediates(&self) -> &[u8] {
94	0	&self.intermediates[..self.intermediate_idx]
95	0	}
96
97		/// Advance the parser state
98		///
99		/// Requires a [`Perform`] in case `byte` triggers an action
100		#[inline]
101	0	pub fn advance<P: Perform>(&mut self, performer: &mut P, byte: u8) {
102		// Utf8 characters are handled out-of-band.
103	0	if let State::Utf8 = self.state {
104	0	self.process_utf8(performer, byte);
105	0	return;
106	0	}
107
108	0	let (state, action) = state_change(self.state, byte);
109	0	self.perform_state_change(performer, state, action, byte);
110	0	}
111
112		#[inline]
113	0	fn process_utf8<P>(&mut self, performer: &mut P, byte: u8)
114	0	where
115	0	P: Perform,
116		{
117	0	if let Some(c) = self.utf8_parser.add(byte) {
118	0	performer.print(c);
119	0	self.state = State::Ground;
120	0	}
121	0	}
122
123		#[inline]
124	0	fn perform_state_change<P>(&mut self, performer: &mut P, state: State, action: Action, byte: u8)
125	0	where
126	0	P: Perform,
127		{
128	0	match state {
129	0	State::Anywhere => {
130	0	// Just run the action
131	0	self.perform_action(performer, action, byte);
132	0	}
133	0	state => {
134	0	match self.state {
135	0	State::DcsPassthrough => {
136	0	self.perform_action(performer, Action::Unhook, byte);
137	0	}
138	0	State::OscString => {
139	0	self.perform_action(performer, Action::OscEnd, byte);
140	0	}
141	0	_ => (),
142		}
143
144	0	match action {
145	0	Action::Nop => (),
146	0	action => {
147	0	self.perform_action(performer, action, byte);
148	0	}
149		}
150
151	0	match state {
152	0	State::CsiEntry \| State::DcsEntry \| State::Escape => {
153	0	self.perform_action(performer, Action::Clear, byte);
154	0	}
155	0	State::DcsPassthrough => {
156	0	self.perform_action(performer, Action::Hook, byte);
157	0	}
158	0	State::OscString => {
159	0	self.perform_action(performer, Action::OscStart, byte);
160	0	}
161	0	_ => (),
162		}
163
164		// Assume the new state
165	0	self.state = state;
166		}
167		}
168	0	}
169
170		/// Separate method for `osc_dispatch` that borrows self as read-only
171		///
172		/// The aliasing is needed here for multiple slices into `self.osc_raw`
173		#[inline]
174	0	fn osc_dispatch<P: Perform>(&self, performer: &mut P, byte: u8) {
175	0	let mut slices: [MaybeUninit<&[u8]>; MAX_OSC_PARAMS] =
176	0	unsafe { MaybeUninit::uninit().assume_init() };
177
178	0	for (i, slice) in slices.iter_mut().enumerate().take(self.osc_num_params) {
179	0	let indices = self.osc_params[i];
180	0	*slice = MaybeUninit::new(&self.osc_raw[indices.0..indices.1]);
181	0	}
182
183	0	unsafe {
184	0	let num_params = self.osc_num_params;
185	0	let params = &slices[..num_params] as const [MaybeUninit<&[u8]>] as const [&[u8]];
186	0	performer.osc_dispatch(&*params, byte == 0x07);
187	0	}
188	0	}
189
190		#[inline]
191	0	fn perform_action<P: Perform>(&mut self, performer: &mut P, action: Action, byte: u8) {
192	0	match action {
193	0	Action::Print => performer.print(byte as char),
194	0	Action::Execute => performer.execute(byte),
195		Action::Hook => {
196	0	if self.params.is_full() {
197	0	self.ignoring = true;
198	0	} else {
199	0	self.params.push(self.param);
200	0	}
201
202	0	performer.hook(self.params(), self.intermediates(), self.ignoring, byte);
203		}
204	0	Action::Put => performer.put(byte),
205	0	Action::OscStart => {
206	0	self.osc_raw.clear();
207	0	self.osc_num_params = 0;
208	0	}
209		Action::OscPut => {
210		#[cfg(feature = "core")]
211		{
212		if self.osc_raw.is_full() {
213		return;
214		}
215		}
216
217	0	let idx = self.osc_raw.len();
218
219		// Param separator
220	0	if byte == b';' {
221	0	let param_idx = self.osc_num_params;
222	0	match param_idx {
223		// Only process up to MAX_OSC_PARAMS
224	0	MAX_OSC_PARAMS => return,
225
226		// First param is special - 0 to current byte index
227	0	0 => {
228	0	self.osc_params[param_idx] = (0, idx);
229	0	}
230
231		// All other params depend on previous indexing
232	0	_ => {
233	0	let prev = self.osc_params[param_idx - 1];
234	0	let begin = prev.1;
235	0	self.osc_params[param_idx] = (begin, idx);
236	0	}
237		}
238
239	0	self.osc_num_params += 1;
240	0	} else {
241	0	self.osc_raw.push(byte);
242	0	}
243		}
244		Action::OscEnd => {
245	0	let param_idx = self.osc_num_params;
246	0	let idx = self.osc_raw.len();
247
248	0	match param_idx {
249		// Finish last parameter if not already maxed
250	0	MAX_OSC_PARAMS => (),
251
252		// First param is special - 0 to current byte index
253	0	0 => {
254	0	self.osc_params[param_idx] = (0, idx);
255	0	self.osc_num_params += 1;
256	0	}
257
258		// All other params depend on previous indexing
259	0	_ => {
260	0	let prev = self.osc_params[param_idx - 1];
261	0	let begin = prev.1;
262	0	self.osc_params[param_idx] = (begin, idx);
263	0	self.osc_num_params += 1;
264	0	}
265		}
266	0	self.osc_dispatch(performer, byte);
267		}
268	0	Action::Unhook => performer.unhook(),
269		Action::CsiDispatch => {
270	0	if self.params.is_full() {
271	0	self.ignoring = true;
272	0	} else {
273	0	self.params.push(self.param);
274	0	}
275
276	0	performer.csi_dispatch(self.params(), self.intermediates(), self.ignoring, byte);
277		}
278	0	Action::EscDispatch => {
279	0	performer.esc_dispatch(self.intermediates(), self.ignoring, byte);
280	0	}
281		Action::Collect => {
282	0	if self.intermediate_idx == MAX_INTERMEDIATES {
283	0	self.ignoring = true;
284	0	} else {
285	0	self.intermediates[self.intermediate_idx] = byte;
286	0	self.intermediate_idx += 1;
287	0	}
288		}
289		Action::Param => {
290	0	if self.params.is_full() {
291	0	self.ignoring = true;
292	0	return;
293	0	}
294
295	0	if byte == b';' {
296	0	self.params.push(self.param);
297	0	self.param = 0;
298	0	} else if byte == b':' {
299	0	self.params.extend(self.param);
300	0	self.param = 0;
301	0	} else {
302	0	// Continue collecting bytes into param
303	0	self.param = self.param.saturating_mul(10);
304	0	self.param = self.param.saturating_add((byte - b'0') as u16);
305	0	}
306		}
307	0	Action::Clear => {
308	0	// Reset everything on ESC/CSI/DCS entry
309	0	self.intermediate_idx = 0;
310	0	self.ignoring = false;
311	0	self.param = 0;
312	0
313	0	self.params.clear();
314	0	}
315	0	Action::BeginUtf8 => self.process_utf8(performer, byte),
316	0	Action::Ignore => (),
317	0	Action::Nop => (),
318		}
319	0	}
320		}
321
322		/// Build a `char` out of bytes
323		pub trait CharAccumulator: Default {
324		/// Build a `char` out of bytes
325		///
326		/// Return `None` when more data is needed
327		fn add(&mut self, byte: u8) -> Option<char>;
328		}
329
330		/// Most flexible [`CharAccumulator`] for [`Parser`] based on active features
331		#[cfg(feature = "utf8")]
332		pub type DefaultCharAccumulator = Utf8Parser;
333		#[cfg(not(feature = "utf8"))]
334		pub type DefaultCharAccumulator = AsciiParser;
335
336		/// Only allow parsing 7-bit ASCII
337		#[allow(clippy::exhaustive_structs)]
338		#[derive(Default, Clone, Debug, PartialEq, Eq)]
339		pub struct AsciiParser;
340
341		impl CharAccumulator for AsciiParser {
342	0	fn add(&mut self, _byte: u8) -> Option<char> {
343	0	unreachable!("multi-byte UTF8 characters are unsupported")
344		}
345		}
346
347		/// Allow parsing UTF-8
348		#[cfg(feature = "utf8")]
349		#[derive(Default, Clone, Debug, PartialEq, Eq)]
350		pub struct Utf8Parser {
351		utf8_parser: utf8::Parser,
352		}
353
354		#[cfg(feature = "utf8")]
355		impl CharAccumulator for Utf8Parser {
356	0	fn add(&mut self, byte: u8) -> Option<char> {
357	0	let mut c = None;
358	0	let mut receiver = VtUtf8Receiver(&mut c);
359	0	self.utf8_parser.advance(&mut receiver, byte);
360	0	c
361	0	}
362		}
363
364		#[cfg(feature = "utf8")]
365		struct VtUtf8Receiver<'a>(&'a mut Option<char>);
366
367		#[cfg(feature = "utf8")]
368		impl utf8::Receiver for VtUtf8Receiver<'_> {
369	0	fn codepoint(&mut self, c: char) {
370	0	*self.0 = Some(c);
371	0	}
372
373	0	fn invalid_sequence(&mut self) {
374	0	*self.0 = Some('�');
375	0	}
376		}
377
378		/// Performs actions requested by the [`Parser`]
379		///
380		/// Actions in this case mean, for example, handling a CSI escape sequence describing cursor
381		/// movement, or simply printing characters to the screen.
382		///
383		/// The methods on this type correspond to actions described in
384		/// <http://vt100.net/emu/dec_ansi_parser>. I've done my best to describe them in
385		/// a useful way in my own words for completeness, but the site should be
386		/// referenced if something isn't clear. If the site disappears at some point in
387		/// the future, consider checking archive.org.
388		pub trait Perform {
389		/// Draw a character to the screen and update states.
390	0	fn print(&mut self, _c: char) {}
391
392		/// Execute a C0 or C1 control function.
393	0	fn execute(&mut self, _byte: u8) {}
394
395		/// Invoked when a final character arrives in first part of device control string.
396		///
397		/// The control function should be determined from the private marker, final character, and
398		/// execute with a parameter list. A handler should be selected for remaining characters in the
399		/// string; the handler function should subsequently be called by `put` for every character in
400		/// the control string.
401		///
402		/// The `ignore` flag indicates that more than two intermediates arrived and
403		/// subsequent characters were ignored.
404	0	fn hook(&mut self, _params: &Params, _intermediates: &[u8], _ignore: bool, _action: u8) {}
405
406		/// Pass bytes as part of a device control string to the handle chosen in `hook`. C0 controls
407		/// will also be passed to the handler.
408	0	fn put(&mut self, _byte: u8) {}
409
410		/// Called when a device control string is terminated.
411		///
412		/// The previously selected handler should be notified that the DCS has
413		/// terminated.
414	0	fn unhook(&mut self) {}
415
416		/// Dispatch an operating system command.
417	0	fn osc_dispatch(&mut self, _params: &[&[u8]], _bell_terminated: bool) {}
418
419		/// A final character has arrived for a CSI sequence
420		///
421		/// The `ignore` flag indicates that either more than two intermediates arrived
422		/// or the number of parameters exceeded the maximum supported length,
423		/// and subsequent characters were ignored.
424	0	fn csi_dispatch(
425	0	&mut self,
426	0	_params: &Params,
427	0	_intermediates: &[u8],
428	0	_ignore: bool,
429	0	_action: u8,
430	0	) {
431	0	}
432
433		/// The final character of an escape sequence has arrived.
434		///
435		/// The `ignore` flag indicates that more than two intermediates arrived and
436		/// subsequent characters were ignored.
437	0	fn esc_dispatch(&mut self, _intermediates: &[u8], _ignore: bool, _byte: u8) {}
438		}
439
440		#[doc = include_str!("../README.md")]
441		#[cfg(doctest)]
442		pub struct ReadmeDoctests;