librustty 0.0.0

Experimental pure-Rust terminal emulation library; initial releases focus on VT stream parsing
Documentation
//! Borrowed events emitted by the VT parser.

use super::params::Params;

/// The kind of control string that was dispatched.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StringKind {
    /// An operating-system command introduced by OSC.
    Osc,
    /// A device-control string introduced by DCS.
    Dcs,
    /// An application-program command introduced by APC.
    Apc,
    /// A privacy-message string introduced by PM.
    Pm,
    /// A system-function string introduced by SOS.
    Sos,
}

/// The way a control string reached its final dispatch.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StringTermination {
    /// OSC was terminated by the BEL byte.
    Bell,
    /// The string was terminated by ST, either `ESC \\` or the 8-bit C1 ST.
    St,
}

/// An ESC sequence whose final byte was dispatched.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct EscDispatch<'a> {
    /// The final byte of the sequence.
    pub final_byte: u8,
    /// Intermediate bytes between ESC and the final byte.
    pub intermediates: &'a [u8],
    /// Whether an intermediate limit caused the sequence to be truncated.
    pub truncated: bool,
}

impl EscDispatch<'_> {
    /// Returns the final byte as a Unicode scalar when it is valid ASCII.
    #[must_use]
    pub fn final_char(self) -> Option<char> {
        char::from_u32(u32::from(self.final_byte))
    }
}

/// A CSI sequence whose final byte was dispatched.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct CsiDispatch<'a> {
    /// The final byte of the sequence.
    pub final_byte: u8,
    /// Private parameter marker bytes such as `?` or `>`.
    pub private_markers: &'a [u8],
    /// Semicolon- and colon-separated parameters.
    pub params: Params<'a>,
    /// Intermediate bytes between parameters and the final byte.
    pub intermediates: &'a [u8],
    /// Whether a parameter or intermediate limit caused the sequence to be
    /// truncated and ignored until its final byte.
    pub truncated: bool,
}

impl CsiDispatch<'_> {
    /// Returns the final byte as a Unicode scalar when it is valid ASCII.
    #[must_use]
    pub fn final_char(self) -> Option<char> {
        char::from_u32(u32::from(self.final_byte))
    }

    /// Returns the private parameter markers.
    #[must_use]
    pub fn private(&self) -> &[u8] {
        self.private_markers
    }
}

/// An OSC sequence whose payload was dispatched.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct OscDispatch<'a> {
    /// The bytes between the OSC introducer and its terminator.
    pub data: &'a [u8],
    /// The terminator used by the OSC sequence.
    pub termination: StringTermination,
    /// Whether the payload exceeded the configured string limit.
    pub truncated: bool,
}

impl OscDispatch<'_> {
    /// Returns the payload as UTF-8 when it is valid.
    #[must_use]
    pub fn as_str(&self) -> Option<&str> {
        core::str::from_utf8(self.data).ok()
    }
}

/// A DCS, APC, PM, or SOS sequence whose payload was dispatched.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct StringDispatch<'a> {
    /// The control-string family.
    pub kind: StringKind,
    /// The final byte of a DCS introducer, when one was recognized.
    pub final_byte: Option<u8>,
    /// Private parameter marker bytes from a DCS introducer.
    pub private_markers: &'a [u8],
    /// Parameters from a DCS introducer.
    pub params: Params<'a>,
    /// Intermediate bytes from a DCS introducer.
    pub intermediates: &'a [u8],
    /// The passthrough bytes after a DCS final byte, or all bytes after the
    /// introducer for APC, PM, and SOS.
    pub data: &'a [u8],
    /// The terminator used by the string.
    pub termination: StringTermination,
    /// Whether a parser limit caused the sequence or payload to be truncated.
    pub truncated: bool,
}

impl StringDispatch<'_> {
    /// Returns the payload as UTF-8 when it is valid.
    #[must_use]
    pub fn as_str(&self) -> Option<&str> {
        core::str::from_utf8(self.data).ok()
    }
}

/// Receives synchronous, borrowed parser events.
///
/// Every event view is valid only during its callback. A handler that needs to
/// retain bytes must copy them before returning. The default methods make it
/// possible to implement only the event families a caller needs.
pub trait Handler {
    /// Handles one decoded printable Unicode scalar.
    fn print(&mut self, _ch: char) {}

    /// Handles a C0 or C1 control byte that is not a sequence introducer.
    fn execute(&mut self, _byte: u8) {}

    /// Handles a completed ESC sequence.
    fn esc_dispatch(&mut self, _event: EscDispatch<'_>) {}

    /// Handles a completed CSI sequence.
    fn csi_dispatch(&mut self, _event: CsiDispatch<'_>) {}

    /// Handles a completed OSC sequence.
    fn osc_dispatch(&mut self, _event: OscDispatch<'_>) {}

    /// Handles a completed DCS, APC, PM, or SOS sequence.
    fn string_dispatch(&mut self, _event: StringDispatch<'_>) {}
}