vendor/anstream-0.5.0/src/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.
   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 = std::io::stdout();
  66     AutoStream::auto(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 = std::io::stderr();
  76     AutoStream::auto(stderr)
  77 }
  78
  79 /// Selection for overriding color output
  80 #[cfg(feature = "auto")]
  81 pub use colorchoice::ColorChoice;