Pretty 🌸 Tty

[ Docs.rs | GitHub Pages | Rust Crate | Repository ]

Prettytty is a lightweight and flexible terminal library for Rust that has only one low-level dependency, i.e., libc on Unix and windows-sys on Windows. Its API is clean and simple: Open a Connection to the terminal and share it across threads as needed. Write Commands to Output. Read Query responses from Input. Scan::read_token takes care of low-level UTF-8 and ANSI escape sequence decoding and Query::parse turns token payloads into objects. A cmd library with 80+ built-in commands covers basic needs and then some. Commands generally are zero-sized. That is, unless they require string arguments or are designed for dynamic state (and hence prefixed with Dyn for dynamic).

Example

Here's how the above mentioned abstractions are used in practice:

use prettytty::{Connection, Query, Scan};
use prettytty::cmd::{MoveToColumn, RequestCursorPosition};
use prettytty::opt::Options;

// Open a terminal connection with 1s timeout.
let tty = Connection::with_options(Options::with_log())?;

let pos = {
    let (mut input, mut output) = tty.io();

    // Move cursor, issue query for position.
    output.exec(MoveToColumn::<17>)?;
    output.exec(RequestCursorPosition)?;

    // Read and parse response.
    let response = input.read_sequence(
        RequestCursorPosition.control())?;
    RequestCursorPosition.parse(response)?
};

assert_eq!(pos.1, 17);

Release History

v0.3.0 (2025-09-15)

• The Command trait now has both Debug and Display as supertraits.

• For commands synthesized with fuse! or fuse_sgr!, the debug trait now displays the macro name and arguments.

• The new Output::exec_defer method takes two commands as arguments. It immediately executes the first command but defers the second command until just before the Connection is closed.

• The new Query::run method turns three-line boilerplate for querying the terminal into a two-argument method invocation.

• The updated progress.rs illustrates the use of fuse!, Output::exec_defer, and Query::run.

• cmd now includes commands for enabling/disabling reverse mode, scrolling up and down, setting the scroll region, and setting the cursor appearance. It also replaces the single RequestBatchMode query with the mode-independent efficient RequestMode and general DynRequestMode queries.

• util's support for parsing and pretty-printing byte strings has been completely refactored, with ByteParser turning byte strings into unsigned integers and ByteFormat displaying them in one of three formats. Also, the new Rewriter adapts an std::io::Write to a core::fmt::Write.

• Thanks to more thorough testing, RequestMode::parse, RequestColor::parse, and RequestCursorPosition::parse won't panic on invalid payloads anymore, instead returning an error.

• event is an incomplete and optional draft module adding support for keyboard and mouse events.

v0.2.2 (2025-02-01)

Fix link to docs.rs.

v0.2.1 (2025-02-01)

• Fix the fuse! macro.

• Update both fuse! and fuse_sgr! to generate commands that are consistent with all of prettytty's commands other than DynLink and DynSetWindowTitle and hence implement the Copy, Clone, Debug, PartialEq, and Eq traits.

• Update SetForeground8, SetBackground8, and their Dyn versions to generate shorter ANSI escape sequences for the first 16 colors, which are the 8 ANSI colors and their bright variants.

v0.2 (2025-01-31)

Add zero-sized generic versions for commands that set colors or move cursor. Keep previous, argument-based versions with Dyn prefix. Rename other commands with runtime arguments to also use Dyn prefix.

Rename sgr! macro for combining several Sgr commands into one command to fuse_sgr! and introduce the more general fuse! macro for combining arbitrary commands into one command.

Add Rust version of progress bar to illustrate API differences from Python version.

v0.1 (2024-12-23)

Initial release.

Copyright 2024-2025 Robert Grimm. The code in this repository has been released as open source under the Apache 2.0 license.