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 | |
37 | pub mod adapter; |
38 | mod buffer; |
39 | #[macro_use ] |
40 | mod macros; |
41 | mod auto; |
42 | mod is_terminal; |
43 | mod lockable; |
44 | mod raw; |
45 | mod strip; |
46 | #[cfg (all(windows, feature = "wincon" ))] |
47 | mod wincon; |
48 | |
49 | pub use auto::AutoStream; |
50 | pub use is_terminal::IsTerminal; |
51 | pub use lockable::Lockable; |
52 | pub use raw::RawStream; |
53 | pub use strip::StripStream; |
54 | #[cfg (all(windows, feature = "wincon" ))] |
55 | pub use wincon::WinconStream; |
56 | |
57 | pub 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" )] |
64 | pub 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" )] |
74 | pub 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" )] |
81 | pub use colorchoice::ColorChoice; |
82 | |