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.
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;
38mod buffer;
39#[macro_use]
40mod macros;
41mod auto;
42mod is_terminal;
43mod lockable;
44mod raw;
45mod strip;
46#[cfg(all(windows, feature = "wincon"))]
47mod wincon;
48
49pub use auto::AutoStream;
50pub use is_terminal::IsTerminal;
51pub use lockable::Lockable;
52pub use raw::RawStream;
53pub use strip::StripStream;
54#[cfg(all(windows, feature = "wincon"))]
55pub use wincon::WinconStream;
56
57pub use buffer::Buffer;
58
59/// Create an ANSI escape code compatible stdout
60///
61/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
62/// from the implicit locking in each [`std::io::Write`] call
63#[cfg(feature = "auto")]
64pub fn stdout() -> AutoStream<std::io::Stdout> {
65 let stdout: Stdout = std::io::stdout();
66 AutoStream::auto(raw:stdout)
67}
68
69/// Create an ANSI escape code compatible stderr
70///
71/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
72/// from the implicit locking in each [`std::io::Write`] call
73#[cfg(feature = "auto")]
74pub fn stderr() -> AutoStream<std::io::Stderr> {
75 let stderr: Stderr = std::io::stderr();
76 AutoStream::auto(raw:stderr)
77}
78
79/// Selection for overriding color output
80#[cfg(feature = "auto")]
81pub use colorchoice::ColorChoice;
82