anstream

anstream (a portmanteau of “ansi stream”) is a small, cross-platform Rust library providing specialized stdout and stderr streams that accept ANSI escape codes and adapt them to the terminal’s actual capabilities. When output is a color-capable TTY it passes the codes through; when it is piped to a file or a terminal without color support, it strips or converts them automatically.

Built on the anstyle family of crates, it lets library authors pass styled text between crates as ANSI escape codes — a more compatible interchange format than bespoke styling APIs — while leaving the decision of whether to render color up to the outermost application. On Windows it can translate ANSI sequences into wincon console calls when needed.

What You Get

• AutoStream wrappers over stdout/stderr that detect and adapt to terminal color support
• StripStream for unconditionally removing ANSI escape codes, plus a low-overhead strip_str adapter
• Drop-in print!, println!, eprint!, and eprintln! macros that respect color capability
• Windows console (wincon) support that converts ANSI sequences to native console calls

Common Use Cases

• Writing colored CLI output that automatically turns plain when piped to a file or non-TTY
• Passing styled text between Rust crates using ANSI escape codes as a stable interchange format
• Cross-platform colored terminal output that works on Windows without extra branching

Under The Hood

Architecture — anstream is one crate in the anstyle Cargo workspace under crates/anstream. Its core is AutoStream (src/auto.rs), which wraps an underlying std::io::Write and, using anstyle-query and colorchoice, decides at construction whether to pass ANSI codes through, strip them (src/strip.rs), or translate them to Windows console calls (src/wincon.rs). A small adapter module exposes reusable strip_str parsing built on anstyle-parse/utf8parse. The public print!/println! family lives in _macros.rs and routes through the global adaptive streams exposed by stdout()/stderr().

Tech Stack — Pure Rust (edition set at the workspace level), depending on sibling crates anstyle, anstyle-parse, colorchoice, and optional anstyle-query/anstyle-wincon, plus utf8parse and is_terminal_polyfill. Feature flags (auto, wincon) gate the capability-detection and Windows paths.

Code Quality — The crate is thoroughly tested with unit tests across stream.rs, strip.rs, and the adapter modules, plus integration tests including recorded .vte terminal captures under tests/. It enforces #![warn(missing_docs)] and clippy lints against stray print!/println!, reflecting a disciplined, documentation-first style.

API Design — The public surface is deliberately minimal and mirrors the standard library: AutoStream, StripStream, Stdout/Stderr type aliases, and macros that match std’s naming. Callers get correct behavior with zero configuration, and advanced users can reach for strip_str or explicit stream types when needed.