prettytty/
lib.rs

1#![doc(
2    html_logo_url = "https://raw.githubusercontent.com/apparebit/prettypretty/refs/heads/main/docs/figures/prettytty.png"
3)]
4
5//! # Pretty 🌸 Tty
6//!
7//! \[  [**Docs.rs**](https://docs.rs/prettypretty/latest/prettytty/)
8//! | [**GitHub Pages**](https://apparebit.github.io/prettypretty/prettytty/)
9//! | [**Rust Crate**](https://crates.io/crates/prettytty)
10//! | [**Repository**](https://github.com/apparebit/prettypretty)
11//! \]
12//!
13//! This crate provides **lightweight and cross-platform terminal access**. Its
14//! only dependency is the low-level crate enabling system calls, i.e.,
15//! [`libc`](https://crates.io/crates/libc) on Unix and
16//! [`windows-sys`](https://crates.io/crates/windows-sys) on Windows.
17//!
18//! Using its **connection-oriented interface** is easy:
19//!
20//!   * Open a [`Connection`].
21//!   * Issue [`Command`]s by writing their [`Display`](core::fmt::Display) to
22//!     the connection's [`Output`].
23//!   * [`Scan`] and read [`Query`] responses from its [`Input`].
24//!
25//! More generally, [`Input`] implements [`Read`](std::io::Read),
26//! [`BufRead`](std::io::BufRead), and [`Scan`], with the latter turning bytes
27//! into UTF-8 text, control code, and control sequence tokens. Meanwhile,
28//! [`Output`] implements [`Write`](std::io::Write) as well as the auto-flushing
29//! [`print()`](Output::print), [`println()`](Output::println), and
30//! [`exec()`](Output::exec) methods.
31//!
32//! The [`cmd`] module provides a **library of common [`Command`] and [`Query`]
33//! implementations**. It includes, for example, commands to set the window
34//! title, erase (parts of) the screen, to move the cursor, and to style text.
35//!
36//! To facilitate orderly shutdown, **read operations time out** in configurable
37//! increments of 0.1s. That suffices for simple polling but is slow when there
38//! is no input. If you need faster timeouts or integration with I/O
39//! notifications, use a dedicated polling thread with either an
40//! [`std::sync::mpsc`] queue or Unix domain socket.
41//!
42//! Since terminal connections reconfigure the terminal, an application should
43//! go out of its way to **always run [`Connection`]'s drop handler**.
44//!
45//!
46//! # Example
47//!
48//! Prettytty's connection-oriented interface makes interacting with the
49//! terminal a breeze:
50//!
51//! ```
52//! # use std::io::{ErrorKind, Result};
53//! # use prettytty::{Connection, Query, Scan};
54//! # use prettytty::cmd::{MoveToColumn, RequestCursorPosition};
55//! # use prettytty::opt::Options;
56//! # fn run() -> Result<()> {
57//! // Open a terminal connection.
58//! let tty = Connection::with_options(Options::default())?;
59//!
60//! let pos = {
61//!     let (mut input, mut output) = tty.io();
62//!
63//!     // Move cursor, issue query for position.
64//!     output.exec(MoveToColumn::<17>)?;
65//!     output.exec(RequestCursorPosition)?;
66//!
67//!     // Read and parse response.
68//!     let response = input.read_sequence(
69//!         RequestCursorPosition.control())?;
70//!     RequestCursorPosition.parse(response)?
71//! };
72//!
73//! assert_eq!(pos.1, 17);
74//! # Ok(())
75//! # }
76//! # // Treat connection refused errors in CI as implying no TTY.
77//! # match run() {
78//! #     Ok(()) => (),
79//! #     Err(err) if err.kind() == ErrorKind::ConnectionRefused &&
80//! #         std::env::var_os("CI").is_some() => (),
81//! #     Err(err) => return Err(err),
82//! # };
83//! # Ok::<(), std::io::Error>(())
84//! ```
85//!
86//! # Windows
87//!
88//! Prettytty uses platform-specific APIs for configuring the terminal, notably
89//! for setting the correct mode. By contrast, commands and queries are
90//! implemented with ANSI escape sequences. Windows started supporting control
91//! sequences for styling output with Windows 10 version 1511 only. It started
92//! supporting queries for the current color theme with Windows Terminal 1.22
93//! only. Hence, we strongly recommend using prettytty with Windows Terminal
94//! 1.22 or later.
95
96mod api;
97pub mod cmd;
98mod conn;
99pub mod err;
100pub mod opt;
101mod read;
102mod scan;
103mod sys;
104pub mod util;
105
106pub use api::{Command, Control, Query, Scan, Sgr, Token};
107pub use conn::{Connection, Input, Output};
prettytty/lib.rs

prettytty/
lib.rs
