anstyle_stream/
lib.rs

1//! **Auto-adapting [`stdout`] / [`stderr`] streams**
2//!
3//! [`AutoStream`] always accepts [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code),
4//! adapting to the user's terminal's capabilities.
5//!
6//! Benefits
7//! - Allows the caller to not be concerned with the terminal's capabilities
8//! - Semver safe way of passing styled text between crates as ANSI escape codes offer more
9//!   compatibility than most crate APIs.
10//!
11//! # Example
12//!
13//! ```
14//! #  #[cfg(feature = "auto")] {
15//! use anstyle_stream::println;
16//! use owo_colors::OwoColorize as _;
17//!
18//! // Foreground colors
19//! println!("My number is {:#x}!", 10.green());
20//! // Background colors
21//! println!("My number is not {}!", 4.on_red());
22//! # }
23//! ```
24//!
25//! And this will correctly handle piping to a file, etc
26
27#![cfg_attr(docsrs, feature(doc_auto_cfg))]
28
29pub mod adapter;
30mod buffer;
31#[macro_use]
32mod macros;
33mod auto;
34mod lockable;
35mod raw;
36mod strip;
37#[cfg(all(windows, feature = "wincon"))]
38mod wincon;
39
40pub use auto::AutoStream;
41pub use lockable::Lockable;
42pub use raw::RawStream;
43pub use strip::StripStream;
44#[cfg(all(windows, feature = "wincon"))]
45pub use wincon::WinconStream;
46
47pub use buffer::Buffer;
48
49/// Create an ANSI escape code compatible stdout
50///
51/// **Note:** Call [`AutoStream::lock`] in loops to avoid the performance hit of acquiring/releasing
52/// from the implicit locking in each [`std::io::Write`] call
53#[cfg(feature = "auto")]
54pub fn stdout() -> AutoStream<std::io::Stdout> {
55    let stdout = std::io::stdout();
56    AutoStream::auto(stdout)
57}
58
59/// Create an ANSI escape code compatible stderr
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 stderr() -> AutoStream<std::io::Stderr> {
65    let stderr = std::io::stderr();
66    AutoStream::auto(stderr)
67}
68
69/// Selection for overriding color output with [`force_color`]
70#[cfg(feature = "auto")]
71pub use concolor_override::ColorChoice;
72
73/// Override the detected [`ColorChoice`]
74#[cfg(feature = "auto")]
75pub fn force_color(choice: ColorChoice) {
76    concolor_override::set(choice);
77}
anstyle_stream/lib.rs

anstyle_stream/
lib.rs
