yansi/
global.rs

Help
1use crate::condition::{AtomicCondition, Condition};
2
3static ENABLED: AtomicCondition = AtomicCondition::DEFAULT;
4
5/// Unconditionally disables styling globally.
6///
7/// # Example
8///
9/// ```rust
10/// use yansi::Paint;
11///
12/// // With styling enabled, ANSI color codes are emitted, thus `ne`.
13/// assert_ne!("go".green().to_string(), "go".to_string());
14///
15/// // With styling disabled, ANSI color codes are _not_ emitted.
16/// yansi::disable();
17/// assert_eq!("go".green().to_string(), "go".to_string());
18/// ```
19pub fn disable() {
20    ENABLED.store(Condition::NEVER);
21}
22
23/// Unconditionally enables styling globally.
24///
25/// By default, styling is enabled based on [`Condition::DEFAULT`], which checks
26/// for operating system support.
27///
28/// # Example
29///
30/// ```rust
31/// use yansi::Paint;
32///
33/// // With styling disabled, ANSI color codes are _not_ emitted.
34/// yansi::disable();
35/// assert_eq!("go".green().to_string(), "go".to_string());
36///
37/// // Reenabling causes color code to be emitted.
38/// yansi::enable();
39/// assert_ne!("go".green().to_string(), "go".to_string());
40/// ```
41pub fn enable() {
42    ENABLED.store(Condition::ALWAYS);
43}
44
45/// Dynamically enables and disables styling globally based on `condition`.
46///
47/// `condition` is expected to be fast: it is checked dynamically, each time a
48/// [`Painted`](crate::Painted) value is displayed.
49///
50/// # Example
51///
52/// ```rust
53/// # #[cfg(all(feature = "detect-tty", feature = "detect-env"))] {
54/// use yansi::Condition;
55///
56/// yansi::whenever(Condition::STDOUT_IS_TTY);
57///
58/// // On each styling, check if we have TTYs.
59/// yansi::whenever(Condition::STDOUTERR_ARE_TTY_LIVE);
60///
61/// // Check `NO_COLOR`, `CLICOLOR`, and if we have TTYs.
62/// const HAVE_COLOR: Condition = Condition(|| {
63///     std::env::var_os("NO_COLOR").is_none()
64///         && (Condition::CLICOLOR_LIVE)()
65///         && Condition::stdouterr_are_tty_live()
66/// });
67///
68/// // This will call `HAVE_COLOR` every time styling is needed. In this
69/// // example, this means that env vars will be checked on each styling.
70/// yansi::whenever(HAVE_COLOR);
71///
72/// // This instead caches the value (checking `env()` exactly once, now).
73/// yansi::whenever(Condition::cached((HAVE_COLOR)()));
74///
75/// // Is identical to this:
76/// match (HAVE_COLOR)() {
77///     true => yansi::enable(),
78///     false => yansi::disable(),
79/// }
80/// # }
81/// ```
82pub fn whenever(condition: Condition) {
83    ENABLED.store(condition);
84}
85
86/// Returns `true` if styling is globally enabled and `false` otherwise.
87///
88/// By default, styling is enabled based on [`Condition::DEFAULT`], which checks
89/// for operating system support. It can be enabled and disabled on-the-fly with
90/// [`enable()`] and [`disable()`] and via a dynamic condition with
91/// [`whenever()`].
92///
93/// # Example
94///
95/// ```rust
96/// // Styling is enabled by default.
97/// # yansi::enable();
98/// assert!(yansi::is_enabled());
99///
100/// // Disable it with `Painted::disable()`.
101/// yansi::disable();
102/// assert!(!yansi::is_enabled());
103///
104/// // Reenable with `Painted::enable()`.
105/// yansi::enable();
106/// assert!(yansi::is_enabled());
107/// ```
108pub fn is_enabled() -> bool {
109    ENABLED.read()
110}
yansi/global.rs

yansi/
global.rs
