anstream/
lib.rs

Help
1//! **Auto-adapting [`stdout`] / [`stderr`] streams**
2//!
3//! *A portmanteau of "ansi stream"*
4//!
5//! [`AutoStream`] always accepts [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code),
6//! [adapting to the user's terminal's capabilities][AutoStream].
7//!
8//! Benefits
9//! - Allows the caller to not be concerned with the terminal's capabilities
10//! - Semver safe way of passing styled text between crates as ANSI escape codes offer more
11//!   compatibility than most crate APIs.
12//!
13//! Available styling crates:
14//! - [anstyle](https://docs.rs/anstyle) for minimal runtime styling, designed to go in public APIs
15//! - [owo-colors](https://docs.rs/owo-colors) for feature-rich runtime styling
16//! - [color-print](https://docs.rs/color-print) for feature-rich compile-time styling
17//!
18//! # Example
19//!
20//! ```
21//! #  #[cfg(feature = "auto")] {
22//! use anstream::println;
23//! use owo_colors::OwoColorize as _;
24//!
25//! // Foreground colors
26//! println!("My number is {:#x}!", 10.green());
27//! // Background colors
28//! println!("My number is not {}!", 4.on_red());
29//! # }
30//! ```
31//!
32//! And this will correctly handle piping to a file, etc
33
34#![cfg_attr(docsrs, feature(doc_auto_cfg))]
35#![warn(missing_docs)]
36#![warn(clippy::print_stderr)]
37#![warn(clippy::print_stdout)]
38
39pub mod adapter;
40pub mod stream;
41
42mod buffer;
43#[macro_use]
44mod macros;
45mod auto;
46mod fmt;
47mod strip;
48#[cfg(all(windows, feature = "wincon"))]
49mod wincon;
50
51pub use auto::AutoStream;
52pub use strip::StripStream;
53#[cfg(all(windows, feature = "wincon"))]
54pub use wincon::WinconStream;
55
56#[allow(deprecated)]
57pub use buffer::Buffer;
58
59/// An adaptive wrapper around the global standard output stream of the current process
60pub type Stdout = AutoStream<std::io::Stdout>;
61/// An adaptive wrapper around the global standard error stream of the current process
62pub type Stderr = AutoStream<std::io::Stderr>;
63
64/// Create an ANSI escape code compatible stdout
65///
66/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
67/// from the implicit locking in each [`std::io::Write`] call
68#[cfg(feature = "auto")]
69pub fn stdout() -> Stdout {
70    let stdout = std::io::stdout();
71    AutoStream::auto(stdout)
72}
73
74/// Create an ANSI escape code compatible stderr
75///
76/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
77/// from the implicit locking in each [`std::io::Write`] call
78#[cfg(feature = "auto")]
79pub fn stderr() -> Stderr {
80    let stderr = std::io::stderr();
81    AutoStream::auto(stderr)
82}
83
84/// Selection for overriding color output
85pub use colorchoice::ColorChoice;
anstream/lib.rs

anstream/
lib.rs
