tastty-core 0.1.0

//! VT parser, screen buffer, byte encoders, and input types for terminal
//! sessions.
//!
//! # What it is
//!
//! Use this crate when you want parser, screen, input-encoding, or host-reply
//! behavior without a managed PTY session. Use the `tastty` crate when you want
//! spawning, resizing, input delivery, and shutdown handled for you.
//!
//! The main entry points are [`Parser`], [`Screen`], [`KeyEncoder`],
//! [`MouseEncoder`], [`frame`], [`HostProfile`], and [`HostReply`].
//!
//! # I/O boundary
//!
//! Feed bytes from your PTY, socket, fixture, or test harness into
//! [`Parser::process`]. After processing, inspect the [`Screen`] and drain
//! [`ScreenEvent`] values with [`Screen::drain_events`]. Use [`HostReply`] for
//! supported terminal replies, and keep [`KeyEncoder`] / [`MouseEncoder`] in
//! sync before sending encoded input bytes back to the child process.
//!
//! # Callback flow
//!
//! A typical loop looks like this:
//!
//! ```
//! use tastty_core::{HostProfile, KeyEncoder, Parser, TerminalSize};
//! use tastty_core::host_reply::auto_reply_bytes;
//! use tastty_core::input::{KeyCode, KeyEvent, KeyModifiers};
//!
//! let host = HostProfile::default();
//! let mut parser = Parser::new(TerminalSize { rows: 24, cols: 80 }, 0);
//! parser.process(b"\x1b[>q");
//!
//! // Default behavior: auto-reply to host queries with the canonical bytes.
//! // Tastty's `Terminal` wrapper does this automatically; bare-Parser
//! // embedders call `auto_reply_bytes` themselves.
//! for event in parser.screen_mut().drain_events() {
//!     if let Some(_wire_bytes) = auto_reply_bytes(&event, &host) {
//!         // Write `_wire_bytes` back to the guest program (e.g., the PTY
//!         // master). For an override (claim DA1 = xterm in a fixture,
//!         // suppress XTVERSION), match on the event yourself and
//!         // synthesize a custom `HostReply::*::encode()` instead.
//!     }
//! }
//!
//! let mut encoder = KeyEncoder::new();
//! encoder.sync(parser.screen());
//! let key = KeyEvent::new(KeyCode::Char('a'), KeyModifiers::NONE);
//! let _wire_bytes = encoder.encode_key(&key);
//! ```
//!
//! # Basic usage
//!
//! ```
//! use tastty_core::{KeyEncoder, Parser, TerminalSize, frame};
//! use tastty_core::input::{KeyCode, KeyEvent, KeyModifiers};
//!
//! // Drive the virtual screen from bytes the caller obtained however it
//! // likes (PTY read, network socket, recorded fixture, ...).
//! let mut parser = Parser::new(TerminalSize { rows: 24, cols: 80 }, 0);
//! parser.process(b"hello\n");
//! let _size = parser.screen().size();
//!
//! // Encode a keystroke to wire bytes for the child process.
//! let enc = KeyEncoder::new();
//! let key = KeyEvent::new(KeyCode::Char('a'), KeyModifiers::NONE);
//! let _bytes: Option<Vec<u8>> = enc.encode_key(&key);
//!
//! // Build an atomic bracketed-paste frame.
//! let _frame: Vec<u8> = frame::bracketed_paste("pasted text", true);
//! ```
//!
//! # Stability
//!
//! `tastty-core` follows semver. The crate is pre-1.0, so expect additions
//! to enums marked `#[non_exhaustive]` without a major-version bump. Breaking
//! changes to existing item signatures get a minor-version bump until 1.0.
//!
//! # Feature flags
//!
//! - **`crossterm`**: adds `From<crossterm::...>` impls that convert
//!   crossterm input events into this crate's [`KeyEvent`] / [`MouseEvent`].
//! - **`widget`**: adds `tui_term::widget::{Screen, Cell}` impls so the
//!   virtual screen can be rendered directly as a ratatui widget.
//!
//! [`vte`]: https://crates.io/crates/vte

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![warn(
    missing_docs,
    rustdoc::broken_intra_doc_links,
    rustdoc::private_intra_doc_links,
    unreachable_pub
)]

/// Text attributes and terminal color types.
pub mod attrs;
/// Virtual terminal cell storage and accessors.
pub mod cell;
mod color;
/// Keyboard and mouse event encoders.
pub mod encoder;
/// Core error types.
pub mod error;
/// Atomic byte-frame helpers for bracketed paste and focus reports.
pub mod frame;
/// Virtual terminal grid internals.
mod grid;
/// Host identity and default-color configuration.
pub mod host_profile;
/// Typed replies to terminal host queries.
pub mod host_reply;
/// Keyboard and mouse input event types.
pub mod input;
pub(crate) mod keys;
/// VT parser wrapper that drives a virtual [`Screen`].
pub mod parser;
pub(crate) mod perform;
/// Virtual terminal row internals.
mod row;
/// Virtual screen state, modes, events, and text extraction.
pub mod screen;

pub use attrs::{Attrs, Color, UnderlineStyle};
pub use cell::{Cell, Hyperlink};
pub use encoder::{KeyEncoder, KeyScreenState, MouseEncoder};
pub use error::{Error, Result};
pub use host_profile::HostProfile;
pub use host_reply::{HostQuery, HostReply, ModeStatus, ReplyAction};
pub use input::{KeyEvent, MouseEvent};
pub use parser::Parser;
pub use screen::{
    AbsolutePosition, CellPixelSize, ClipboardTarget, ColorRole, ColorTarget, CursorShape,
    CursorStyle, DirtyState, FormattedOptions, LogicalLineOptions, LogicalLineSpan, LogicalLines,
    PlainOptions, Position, ProgressState, Screen, ScreenEvent, SemanticPrompt, TerminalMode,
    TerminalSize, XtGetTcapEntry, XtWinOpsReport,
};