1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104

//! Control console coloring across all dependencies
//!
//! # Motivation
//!
//! Detecting a terminal's color capabilities and passing it down to each writer
//! can be obnoxious.  Some crates try to make this easier by detecting the environment for you and
//! making their own choice to print colors.  As an application author, you own the experience for
//! your application and want the behavior to be consistent.  To get this, you have to dig into
//! each crate's implementation to see how they auto-detect color capabilities and, if they don't
//! do it how you want, hope they provide a way to override it so you can implement it yourself.
//!
//! Like with logging, your terminal's capabilities and how to treat it is a behavior that cuts
//! across your application.  So to make things more consistent and easier to control,
//! `concolor-control` introduces shared detection logic that all crates can call into to get
//! consistent behavior.  The application author can then choose what feature flags are enabled to
//! decide on what the end-user experience should be.
//!
//! # `[[bin]]`s
//!
//! ```toml
//! [dependencies]
//! concolor-control = { version = "0.0.6", features = "color" }
//! ```
//! Notes:
//! - With the
//!   [2021 edition / `resolver = "2"`](https://doc.rust-lang.org/nightly/edition-guide/rust-2021/default-cargo-resolver.html),
//!   you will also need to specify this in your `build-dependencies` if you want `build.rs` to have color
//!   as well.
//!
//! If you are providing a command line option for controlling color, just call
//! ```rust
//! let when = concolor_control::ColorChoice::Always;
//! concolor_control::set(when);
//! ```
//!
//! See also [`concolor-clap`](https://docs.rs/concolor-clap)
//!
//! # `[lib]`s
//!
//! The `[[bin]]` is responsible for defining the policy of how colors are determined, so to depend
//! on `concolor-control`:
//! ```toml
//! [dependencies]
//! concolor-control = { version = "0.0.6", default-features = false }
//! ```
//!
//! At times, you might want to provide a convenience feature for color support, so you could also:
//! ```toml
//! [features]
//! default = ["color"]
//! color = "concolor-control/auto"
//!
//! [dependencies]
//! concolor-control = { version = "0.0.6", optional = True}
//! ```
//! Notes:
//! - Your choice on whether to make this default or not
//! - Depending on your context, name it either `color` (for a crate like `clap`) or `auto` (for a
//!   crate like `termcolor`)
//!
//! Then just ask as needed:
//! ```rust
//! let stdout_support = concolor_control::get(concolor_control::Stream::Stdout);
//! if stdout_support.ansi_color() {
//!     // Output ANSI escape sequences
//!     if stdout_support.truecolor() {
//!         // Get even fancier with the colors
//!     }
//! } else if stdout_support.color() {
//!     // Legacy Windows version, control the console as needed
//! } else {
//!     // No coloring
//! }
//! ```
//!
//! # Features
//!
//! - `auto`: Guess color status based on all possible sources, including:
//!   - `api`: Allow controlling color via the API
//!   - `interactive`: Check if stdout/stderr is a TTY
//!   - `clicolor`: Respect [CLICOLOR] spec
//!   - `no_color`: Respect [NO_COLOR] spec
//!   - `term`: Check `TERM`
//!   - `windows`: Check if we can enable ANSI support
//!
//! [CLICOLOR]: https://bixense.com/clicolors/
//! [NO_COLOR]: https://no-color.org/

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(feature = "api")]
mod color;
#[cfg(feature = "api")]
pub use color::*;

#[cfg(not(feature = "api"))]
mod no_color;
#[cfg(not(feature = "api"))]
pub use no_color::*;

mod choice;
pub use choice::*;
mod stream;
pub use stream::*;