Struct yansi::Condition

source ·
#[repr(transparent)]
pub struct Condition(pub fn() -> bool);
Expand description

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)conditionimplication
detect-ttyTTY Detectorsstd, is-terminal
detect-envEnvironment Variable Checkersstd
[detect-tty, detect-env]All Above, Combo Detectorsstd, 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 creared via 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§

source§

impl Condition

source

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.

source

pub const ALWAYS: Condition = _

A condition that always evaluates to true.

source

pub const NEVER: Condition = _

A condition that always evaluated to false.

source

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());
source

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());
source

pub const fn always() -> bool

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

source

pub const fn never() -> bool

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

source

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.

source§

impl Condition

Feature dependent conditions.

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

source

pub const STDOUT_IS_TTY: Condition = _

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.

source

pub const STDERR_IS_TTY: Condition = _

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.

source

pub const STDIN_IS_TTY: Condition = _

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.

source

pub const STDOUTERR_ARE_TTY: Condition = _

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.

source

pub const STDOUT_IS_TTY_LIVE: Condition = _

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.

source

pub const STDERR_IS_TTY_LIVE: Condition = _

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.

source

pub const STDIN_IS_TTY_LIVE: Condition = _

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.

source

pub const STDOUTERR_ARE_TTY_LIVE: Condition = _

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.

source

pub fn stdout_is_tty() -> bool

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.

source

pub fn stderr_is_tty() -> bool

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.

source

pub fn stdin_is_tty() -> bool

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.

source

pub fn stdouterr_are_tty() -> bool

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.

source

pub fn stdout_is_tty_live() -> bool

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

This is the backing function for STDOUT_IS_TTY_LIVE.

source

pub fn stderr_is_tty_live() -> bool

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

This is the backing function for STDERR_IS_TTY_LIVE.

source

pub fn stdin_is_tty_live() -> bool

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

This is the backing function for STDIN_IS_TTY_LIVE.

source

pub fn stdouterr_are_tty_live() -> bool

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

This is the backing function for STDOUTERR_ARE_TTY_LIVE.

Trait Implementations§

source§

impl Clone for Condition

source§

fn clone(&self) -> Condition

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Condition

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Condition

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl Deref for Condition

§

type Target = fn() -> bool

The resulting type after dereferencing.
source§

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

Dereferences the value.
source§

impl Hash for Condition

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl Ord for Condition

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

impl PartialEq<Condition> for Condition

source§

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

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

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.
source§

impl PartialOrd<Condition> for Condition

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

impl Copy for Condition

source§

impl Eq for Condition

source§

impl StructuralEq for Condition

source§

impl StructuralPartialEq for Condition

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Paint for Twhere T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S: Into<Style>>(&self, style: S) -> Painted<&Self>

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.