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//! (once it hits 1.0)
16//! - [owo-colors](https://docs.rs/owo-colors) for feature-rich runtime styling
17//! - [color-print](https://docs.rs/color-print) for feature-rich compile-time styling
18//!
19//! # Example
20//!
21//! ```
22//! # #[cfg(feature = "auto")] {
23//! use anstream::println;
24//! use owo_colors::OwoColorize as _;
25//!
26//! // Foreground colors
27//! println!("My number is {:#x}!", 10.green());
28//! // Background colors
29//! println!("My number is not {}!", 4.on_red());
30//! # }
31//! ```
32//!
33//! And this will correctly handle piping to a file, etc
34
35#![cfg_attr(docsrs, feature(doc_auto_cfg))]
36
37pub mod adapter;
38pub mod stream;
39
40mod buffer;
41#[macro_use]
42mod macros;
43mod auto;
44mod fmt;
45mod strip;
46#[cfg(all(windows, feature = "wincon"))]
47mod wincon;
48
49pub use auto::AutoStream;
50pub use strip::StripStream;
51#[cfg(all(windows, feature = "wincon"))]
52pub use wincon::WinconStream;
53
54#[allow(deprecated)]
55pub use buffer::Buffer;
56
57pub type Stdout = AutoStream<std::io::Stdout>;
58pub type Stderr = AutoStream<std::io::Stderr>;
59
60/// Create an ANSI escape code compatible stdout
61///
62/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
63/// from the implicit locking in each [`std::io::Write`] call
64#[cfg(feature = "auto")]
65pub fn stdout() -> Stdout {
66 let stdout: Stdout = std::io::stdout();
67 AutoStream::auto(raw:stdout)
68}
69
70/// Create an ANSI escape code compatible stderr
71///
72/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
73/// from the implicit locking in each [`std::io::Write`] call
74#[cfg(feature = "auto")]
75pub fn stderr() -> Stderr {
76 let stderr: Stderr = std::io::stderr();
77 AutoStream::auto(raw:stderr)
78}
79
80/// Selection for overriding color output
81pub use colorchoice::ColorChoice;
82