Struct yansi::Condition

#[repr(transparent)]
pub struct Condition(pub fn() -> bool);

A function that decides whether styling should be applied.

A styling Condition can be specified globally via yansi::whenever() or locally to a specific style via the whenever() builder method. Any time a Painted value is formatted, both the local and global conditions are checked, and only when both evaluate to true is styling actually applied.

A Condition is nothing more than a function that returns a bool. The function is called each and every time a Painted is formatted, and so it is expected to be fast. All of the built-in conditions (except for their “live” variants) cache their first evaluation as a result: the Condition::cached() constructor can do the same for your conditions.

Built-In Conditions

yansi comes with built-in conditions for common scenarios that can be enabled via crate features:

feature(s)	condition	implication
detect-tty	TTY Detectors	std, is-terminal
detect-env	Environment Variable Checkers	std
[detect-tty, detect-env]	All Above, Combo Detectors	std, is-terminal

For example, to enable the TTY detectors, enable the detect-tty feature:

yansi = { version = "...", features = ["detect-tty"] }

To enable the TTY detectors, env-var checkers, and combo detectors, enable detect-tty and detect-env:

yansi = { version = "...", features = ["detect-tty", "detect-env"] }

use yansi::Condition;

yansi::whenever(Condition::TTY_AND_COLOR);

Custom Conditions

Custom, arbitrary conditions can be created with Condition::from() or Condition::cached().

use yansi::{Condition, Style, Color::*};

// Combine two conditions (`stderr` is a TTY, `CLICOLOR` is set) into one.
static STDERR_COLOR: Condition = Condition::from(||
    Condition::stderr_is_tty() && Condition::clicolor()
);

static DEBUG: Style = Yellow.bold().on_primary().invert().whenever(STDERR_COLOR);

Tuple Fields

0: fn() -> bool

The function that gets called to check the condition.

Implementations

impl Condition

pub const DEFAULT: Condition = _

A condition that evaluates to true if the OS supports coloring.

Uses Condition::os_support(). On Windows, this condition tries to enable coloring support on the first call and caches the result for subsequent calls. Outside of Windows, this always evaluates to true.

pub const ALWAYS: Condition = _

A condition that always evaluates to true.

pub const NEVER: Condition = _

A condition that always evaluated to false.

pub const fn from(f: fn() -> bool) -> Self

Creates a dynamically checked condition from a function f.

The function f is called anytime the condition is checked, including every time a style with the condition is used.

Example

use yansi::Condition;

fn some_function() -> bool {
    /* checking arbitrary conditions */
    todo!()
}

// Create a custom static condition from a function.
static MY_CONDITION: Condition = Condition::from(some_function);

// Create a condition on the stack from a function.
let my_condition = Condition::from(some_function);

// Create a static condition from a closure that becomes a `fn`.
static MY_CONDITION_2: Condition = Condition::from(|| false);

// Create a condition on the stack from a closure that becomes a `fn`.
let my_condition = Condition::from(|| some_function());

pub const fn cached(value: bool) -> Self

Creates a condition that is ALWAYS when value is true and NEVER otherwise.

Example

use yansi::Condition;

fn some_function() -> bool {
    /* checking arbitrary conditions */
    todo!()
}

// Cache the result of `some_function()` so it doesn't get called each
// time the condition needs to be checked.
let my_condition = Condition::cached(some_function());

pub const fn always() -> bool

The backing function for Condition::ALWAYS. Returns true always.

pub const fn never() -> bool

The backing function for Condition::NEVER. Returns false always.

pub fn os_support() -> bool

The backing function for Condition::DEFAULT.

Returns true if the current OS supports ANSI escape sequences for coloring. Outside of Windows, this always returns true. On Windows, the first call to this function attempts to enable support and returns whether it was successful every time thereafter.

impl Condition

Feature dependent conditions.

Available when compiled with feature = "detect-tty".

pub const STDOUT_IS_TTY: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdout()).

The result of the first check is cached for subsequent checks. Internally uses stdout_is_tty.

pub const STDERR_IS_TTY: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stderr()).

The result of the first check is cached for subsequent checks. Internally uses stderr_is_tty.

pub const STDIN_IS_TTY: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdin()).

The result of the first check is cached for subsequent checks. Internally uses stdin_is_tty.

pub const STDOUTERR_ARE_TTY: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdout()) && is_tty(&std::io::stderr()).

The result of the first check is cached for subsequent checks. Internally uses stdouterr_are_tty.

pub const STDOUT_IS_TTY_LIVE: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdout()).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use STDOUT_IS_TTY instead.

Internally uses stdout_is_tty_live.

pub const STDERR_IS_TTY_LIVE: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stderr()).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use STDERR_IS_TTY instead.

Internally uses stderr_is_tty_live.

pub const STDIN_IS_TTY_LIVE: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdin()).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use STDIN_IS_TTY instead.

Internally uses stdin_is_tty_live.

pub const STDOUTERR_ARE_TTY_LIVE: Condition = _

Available on crate feature detect-tty only.

Evaluates to true if is_tty(&std::io::stdout()) && is_tty(&std::io::stderr()).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use STDOUTERR_ARE_TTY instead.

Internally uses stdouterr_are_tty_live.

pub fn stdout_is_tty() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdout()).

The result of the first check is cached for subsequent checks. This is the backing function for STDOUT_IS_TTY.

pub fn stderr_is_tty() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stderr()).

The result of the first check is cached for subsequent checks. This is the backing function for STDERR_IS_TTY.

pub fn stdin_is_tty() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdin()).

The result of the first check is cached for subsequent checks. This is the backing function for STDIN_IS_TTY.

pub fn stdouterr_are_tty() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdout()) && is_tty(&std::io::stderr()).

The result of the first check is cached for subsequent checks. This is the backing function for STDOUTERR_ARE_TTY.

pub fn stdout_is_tty_live() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdout()).

This is the backing function for STDOUT_IS_TTY_LIVE.

pub fn stderr_is_tty_live() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stderr()).

This is the backing function for STDERR_IS_TTY_LIVE.

pub fn stdin_is_tty_live() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdin()).

This is the backing function for STDIN_IS_TTY_LIVE.

pub fn stdouterr_are_tty_live() -> bool

Available on crate feature detect-tty only.

Returns true if is_tty(&std::io::stdout()) && is_tty(&std::io::stderr()).

This is the backing function for STDOUTERR_ARE_TTY_LIVE.

impl Condition

Feature dependent conditions.

Available when compiled with feature = "detect-env".

pub const CLICOLOR: Condition = _

Available on crate feature detect-env only.

Evaluates to true if env_set_or("CLICOLOR_FORCE", false) || env_set_or("CLICOLOR", true).

The result of the first check is cached for subsequent checks. Internally uses clicolor.

pub const YES_COLOR: Condition = _

Available on crate feature detect-env only.

Evaluates to true if !env_set_or("NO_COLOR", false).

The result of the first check is cached for subsequent checks. Internally uses no_color.

pub const CLICOLOR_LIVE: Condition = _

Available on crate feature detect-env only.

Evaluates to true if env_set_or("CLICOLOR_FORCE", false) || env_set_or("CLICOLOR", true).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use CLICOLOR instead.

Internally uses clicolor_live.

pub const YES_COLOR_LIVE: Condition = _

Available on crate feature detect-env only.

Evaluates to true if !env_set_or("NO_COLOR", false).

A call is dispatched each time the condition is checked. This is expensive, so prefer to use YES_COLOR instead.

Internally uses no_color_live.

pub fn clicolor() -> bool

Available on crate feature detect-env only.

Returns true if env_set_or("CLICOLOR_FORCE", false) || env_set_or("CLICOLOR", true).

The result of the first check is cached for subsequent checks. This is the backing function for CLICOLOR.

pub fn no_color() -> bool

Available on crate feature detect-env only.

Returns true if !env_set_or("NO_COLOR", false).

The result of the first check is cached for subsequent checks. This is the backing function for YES_COLOR.

pub fn clicolor_live() -> bool

Available on crate feature detect-env only.

Returns true if env_set_or("CLICOLOR_FORCE", false) || env_set_or("CLICOLOR", true).

This is the backing function for CLICOLOR_LIVE.

pub fn no_color_live() -> bool

Available on crate feature detect-env only.

Returns true if !env_set_or("NO_COLOR", false).

This is the backing function for YES_COLOR_LIVE.

impl Condition

Feature dependent conditions.

Available when compiled with all(feature = "detect-env", feature = "detect-tty").

pub const TTY_AND_COLOR: Condition = _

Available on crate features detect-env and detect-tty only.

Evaluates to true if Condition::stdouterr_are_tty() && Condition::clicolor() && Condition::no_color().

The result of the first check is cached for subsequent checks. Internally uses tty_and_color.

pub const TTY_AND_COLOR_LIVE: Condition = _

Available on crate features detect-env and detect-tty only.

Evaluates to true if Condition::stdouterr_are_tty() && Condition::clicolor() && Condition::no_color().

A call is dispatched each time the condition is checked. This is expensive, so prefer to use TTY_AND_COLOR instead.

Internally uses tty_and_color_live.

pub fn tty_and_color() -> bool

Available on crate features detect-env and detect-tty only.

Returns true if Condition::stdouterr_are_tty() && Condition::clicolor() && Condition::no_color().

The result of the first check is cached for subsequent checks. This is the backing function for TTY_AND_COLOR.

pub fn tty_and_color_live() -> bool

Available on crate features detect-env and detect-tty only.

Returns true if Condition::stdouterr_are_tty() && Condition::clicolor() && Condition::no_color().

This is the backing function for TTY_AND_COLOR_LIVE.

Trait Implementations

impl Clone for Condition

fn clone(&self) -> Condition

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Condition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Condition

fn default() -> Self

Returns the “default value” for a type.

impl Deref for Condition

type Target = fn() -> bool

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for Condition

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Condition

fn cmp(&self, other: &Condition) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Condition

fn eq(&self, other: &Condition) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Condition

fn partial_cmp(&self, other: &Condition) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Condition

impl Eq for Condition

impl StructuralPartialEq for Condition