tastty 0.1.0

Embeddable pseudoterminal sessions for Rust applications
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! Embeddable pseudoterminal sessions for Rust TUI applications.
//!
//! Tastty spawns a child process inside a PTY and exposes a thread-safe
//! handle ([`Terminal`]) for reading the virtual screen, sending
//! input, resizing, and waiting for exit. A background reader thread
//! feeds PTY output into a VT parser so the screen is always up to date.
//! Host queries ([DA1/DA2/DA3, XTVERSION, DECRQM/DECRQSS, OSC color,
//! XTGETTCAP][xterm-ctlseqs]) are auto-replied by default; intercept on a
//! per-query basis via [`SessionOptions::on_host_query`] to override the
//! canonical reply or suppress fingerprintable responses.
//!
//! # Quick overview
//!
//! 1. Build a [`Builder`] for the program, configure via its chained
//!    setters, and pass it to [`Terminal::spawn`]. Pipe-backed sessions
//!    with no child process call [`Terminal::from_reader_writer`] with
//!    [`SessionOptions`] directly.
//! 2. Read the current screen contents via [`Terminal::with_screen`].
//! 3. Send raw bytes with [`Terminal::send`], keystrokes with
//!    [`Terminal::send_key`], or clipboard paste with
//!    [`Terminal::send_paste`].
//! 4. Resize the PTY with [`Terminal::resize`].
//! 5. Wait for exit with [`Terminal::wait_async`] or poll with
//!    [`Terminal::try_wait`].
//! 6. Drop the handle (or let it fall out of scope). For [`Managed`], this
//!    blocks the caller for up to ~200 ms while the child is terminated
//!    and the I/O threads are joined; see [`Terminal`] for the timing
//!    breakdown and hot-path mitigations.
//!
//! # Relationship to `tastty-core`
//!
//! This crate owns PTY/session lifecycle and uses [`tastty_core`] for VT
//! parsing, screen state, input encoding, and host replies. Low-level types
//! such as [`Parser`], [`Screen`], [`KeyEncoder`], [`MouseEvent`], and
//! [`HostReply`] are re-exported so embedders can name them without
//! depending on `tastty-core` directly.
//!
//! For parser-only use without tokio or PTY management, depend on
//! `tastty-core` directly.
//!
//! # Feature flags
//!
//! - **`widget`** -- Provides a ratatui widget ([`widget::PseudoTerminal`])
//!   that renders the session screen directly into a TUI frame.
//! - **`crossterm`** -- Enables `From` conversions between crossterm input
//!   types and tastty's [`KeyEvent`] / [`MouseEvent`].
//!
//! Both features are enabled by default.
//!
//! See the `examples/` directory in the repository for working demos.
//!
//! [xterm-ctlseqs]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![warn(
    missing_docs,
    rustdoc::broken_intra_doc_links,
    rustdoc::private_intra_doc_links,
    unreachable_pub
)]

/// Keyboard and mouse event encoders.
pub mod encoder {
    pub use tastty_core::encoder::*;
}
mod builder;
pub mod error;
mod exit_status;
/// Typed replies to terminal host queries.
pub mod host_reply {
    pub use tastty_core::host_reply::*;
}
/// Keyboard and mouse input event types.
pub mod input {
    pub use tastty_core::input::*;
}
/// Allow / deny gating for OSC 52 clipboard sequences applied at the
/// reader thread before any event reaches the embedder or auto-reply.
pub mod osc_policy;
mod process_group;
/// Session lifecycle, I/O callbacks, and session mode markers.
pub mod session;

pub use builder::Builder;
pub use error::{
    Error, IoError, IoErrorReceiver, ReaderError, Result, WriterError, WriterOperation,
};
pub use exit_status::ExitStatus;
pub use osc_policy::{ClipboardPolicy, OscPolicy, PerTargetPolicy};
pub use session::{
    KeyAction, Managed, ManagedTerminal, SessionOptions, Terminal, TerminalOwnership, Unmanaged,
    UnmanagedTerminal, WriterHandle,
};
pub use tastty_core::{
    AbsolutePosition, Attrs, Cell, CellPixelSize, ClipboardTarget, Color, ColorTarget, CursorShape,
    CursorStyle, FormattedOptions, HostProfile, HostQuery, HostReply, Hyperlink, KeyEncoder,
    KeyEvent, KeyScreenState, LogicalLineOptions, LogicalLineSpan, LogicalLines, ModeStatus,
    MouseEncoder, MouseEvent, Parser, PlainOptions, Position, ReplyAction, Screen, ScreenEvent,
    TerminalMode, TerminalSize, UnderlineStyle, frame,
};

#[cfg(feature = "widget")]
/// Ratatui widget integration for rendering a live session.
pub mod widget;