#[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) | 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 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
impl Condition
sourcepub const DEFAULT: 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
.
sourcepub const fn from(f: fn() -> bool) -> Self
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());
sourcepub const fn cached(value: bool) -> Self
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());
sourcepub const fn always() -> bool
pub const fn always() -> bool
The backing function for Condition::ALWAYS
. Returns true
always.
sourcepub const fn never() -> bool
pub const fn never() -> bool
The backing function for Condition::NEVER
. Returns false
always.
sourcepub fn os_support() -> bool
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
impl Condition
Feature dependent conditions.
Available when compiled with
feature = "detect-tty"
.
sourcepub const STDOUT_IS_TTY: Condition = _
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
.
sourcepub const STDERR_IS_TTY: Condition = _
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
.
sourcepub const STDIN_IS_TTY: Condition = _
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
.
sourcepub const STDOUTERR_ARE_TTY: Condition = _
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
.
sourcepub const STDOUT_IS_TTY_LIVE: Condition = _
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
.
sourcepub const STDERR_IS_TTY_LIVE: Condition = _
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
.
sourcepub const STDIN_IS_TTY_LIVE: Condition = _
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
.
sourcepub const STDOUTERR_ARE_TTY_LIVE: Condition = _
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
.
sourcepub fn stdout_is_tty() -> bool
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
.
sourcepub fn stderr_is_tty() -> bool
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
.
sourcepub fn stdin_is_tty() -> bool
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
.
sourcepub fn stdouterr_are_tty() -> bool
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
.
sourcepub fn stdout_is_tty_live() -> bool
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
.
sourcepub fn stderr_is_tty_live() -> bool
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
.
sourcepub fn stdin_is_tty_live() -> bool
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
.
sourcepub fn stdouterr_are_tty_live() -> bool
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 Ord for Condition
impl Ord for Condition
source§impl PartialEq<Condition> for Condition
impl PartialEq<Condition> for Condition
source§impl PartialOrd<Condition> for Condition
impl PartialOrd<Condition> for Condition
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl Copy for Condition
impl Eq for Condition
impl StructuralEq for Condition
impl StructuralPartialEq for Condition
Auto Trait Implementations§
impl RefUnwindSafe for Condition
impl Send for Condition
impl Sync for Condition
impl Unpin for Condition
impl UnwindSafe for Condition
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
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 bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
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>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
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>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
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>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
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>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
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>
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>
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>
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>
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>
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>
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 underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
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 whenever(&self, value: Condition) -> Painted<&T>
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);