anstream/lib.rs
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#[doc(hidden)]
42#[macro_use]
43pub mod _macros;
44
45mod auto;
46mod buffer;
47mod fmt;
48mod strip;
49#[cfg(all(windows, feature = "wincon"))]
50mod wincon;
51
52pub use auto::AutoStream;
53pub use strip::StripStream;
54#[cfg(all(windows, feature = "wincon"))]
55pub use wincon::WinconStream;
56
57#[allow(deprecated)]
58pub use buffer::Buffer;
59
60/// An adaptive wrapper around the global standard output stream of the current process
61pub type Stdout = AutoStream<std::io::Stdout>;
62/// An adaptive wrapper around the global standard error stream of the current process
63pub type Stderr = AutoStream<std::io::Stderr>;
64
65/// Create an ANSI escape code compatible stdout
66///
67/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
68/// from the implicit locking in each [`std::io::Write`] call
69#[cfg(feature = "auto")]
70pub fn stdout() -> Stdout {
71 let stdout = std::io::stdout();
72 AutoStream::auto(stdout)
73}
74
75/// Create an ANSI escape code compatible stderr
76///
77/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
78/// from the implicit locking in each [`std::io::Write`] call
79#[cfg(feature = "auto")]
80pub fn stderr() -> Stderr {
81 let stderr = std::io::stderr();
82 AutoStream::auto(stderr)
83}
84
85/// Selection for overriding color output
86pub use colorchoice::ColorChoice;