Struct yansi::Paint

source ·
pub struct Paint<T> { /* private fields */ }
Expand description

A structure encapsulating an item and styling.

See the crate level documentation for usage information.

Method Glossary

The Paint structure exposes many methods for convenience.

Unstyled Constructors

Return a new Paint structure with no or default styling applied.

Foreground Color Constructors

Return a new Paint structure with a foreground color applied.

Getters

Return information about the Paint structure.

Setters

Set a style property on a given Paint structure.

These methods can be chained:

use yansi::Paint;

Paint::new("hi").underline().invert().italic().dimmed().bold();

Global Methods

Modify or observe the global behavior of painting.

Implementations§

source§

impl<T> Paint<T>

source

pub fn new(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with no set styling.

use yansi::Paint;

assert_eq!(Paint::new("hello!").to_string(), "hello!".to_string());
source

pub fn default(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the active terminal’s default foreground and background.

use yansi::Paint;

println!("This is going to use {}!", Paint::default("default colors"));
source

pub fn masked(item: T) -> Paint<T>

Constructs a new masked Paint structure encapsulating item with no set styling.

A masked Paint is not written out when painting is disabled during Display or Debug invocations. When painting is enabled, masking has no effect.

use yansi::Paint;

// The emoji won't be printed when coloring is disabled.
println!("{}Sprout!", Paint::masked("🌱 "));
source

pub fn wrapping(item: T) -> Paint<T>

Constructs a new wrapping Paint structure encapsulating item with default styling.

A wrapping Paint converts all color resets written out by the internal value to the styling of itself. This allows for seamless color wrapping of other colored text.

Performance

In order to wrap an internal value, the internal value must first be written out to a local buffer and examined. As a result, displaying a wrapped value is likely to result in a heap allocation and copy.

Example
use yansi::{Paint, Color};

let inner = format!("{} and {}", Paint::red("Stop"), Paint::green("Go"));

// 'Hey!' will be unstyled, "Stop" will be red, "and" will be blue, and
// "Go" will be green. Without a wrapping `Paint`, "and" would be
// unstyled.
println!("Hey! {}", Paint::wrapping(inner).fg(Color::Blue));
source

pub fn rgb(r: u8, g: u8, b: u8, item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to the RGB color r, g, b.

use yansi::Paint;

println!("This is going to be funky: {}", Paint::rgb(70, 130, 122, "hi!"));
source

pub fn fixed(color: u8, item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to the fixed 8-bit color color.

use yansi::Paint;

println!("This is going to be funky: {}", Paint::fixed(100, "hi!"));
source

pub fn black(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to black.

use yansi::Paint;

println!("This is going to be black: {}", Paint::black("yay!"));
source

pub fn red(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to red.

use yansi::Paint;

println!("This is going to be red: {}", Paint::red("yay!"));
source

pub fn green(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to green.

use yansi::Paint;

println!("This is going to be green: {}", Paint::green("yay!"));
source

pub fn yellow(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to yellow.

use yansi::Paint;

println!("This is going to be yellow: {}", Paint::yellow("yay!"));
source

pub fn blue(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to blue.

use yansi::Paint;

println!("This is going to be blue: {}", Paint::blue("yay!"));
source

pub fn magenta(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to magenta.

use yansi::Paint;

println!("This is going to be magenta: {}", Paint::magenta("yay!"));
source

pub fn cyan(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to cyan.

use yansi::Paint;

println!("This is going to be cyan: {}", Paint::cyan("yay!"));
source

pub fn white(item: T) -> Paint<T>

Constructs a new Paint structure encapsulating item with the foreground color set to white.

use yansi::Paint;

println!("This is going to be white: {}", Paint::white("yay!"));
source

pub fn style(&self) -> Style

Retrieves the style currently set on self.

use yansi::{Style, Color, Paint};

let alert = Style::new(Color::Red).bold().underline();
let painted = Paint::red("hi").bold().underline();

assert_eq!(alert, painted.style());
source

pub fn inner(&self) -> &T

Retrieves a borrow to the inner item.

use yansi::Paint;

let x = Paint::red("Hello, world!");
assert_eq!(*x.inner(), "Hello, world!");
source

pub fn with_style(self, style: Style) -> Paint<T>

Sets the style of self to style.

Any styling currently set on self is lost. Prefer to use the style.paint() method to create a Paint struct from Style.

use yansi::{Paint, Color, Style};

let s = Style::new(Color::Red).bold().underline();

// Using this method.
println!("Alert: {}", Paint::new("This thing happened!").with_style(s));

// Using the `style.paint()` method.
println!("Alert: {}", s.paint("This thing happened!"));
source

pub fn mask(self) -> Paint<T>

Masks self.

A masked Paint is not written out when painting is disabled during Display or Debug invocations. When painting is enabled, masking has no effect.

use yansi::Paint;

// "Whoops! " will only print when coloring is enabled.
println!("{}Something happened.", Paint::red("Whoops! ").mask());
source

pub fn wrap(self) -> Paint<T>

Makes self a wrapping Paint.

A wrapping Paint converts all color resets written out by the internal value to the styling of itself. This allows for seamless color wrapping of other colored text.

Performance

In order to wrap an internal value, the internal value must first be written out to a local buffer and examined. As a result, displaying a wrapped value is likely to result in a heap allocation and copy.

Example
use yansi::{Paint, Color};

let inner = format!("{} and {}", Paint::red("Stop"), Paint::green("Go"));

// 'Hey!' will be unstyled, "Stop" will be red, "and" will be blue, and
// "Go" will be green. Without a wrapping `Paint`, "and" would be
// unstyled.
println!("Hey! {}", Paint::blue(inner).wrap());
source

pub fn fg(self, color: Color) -> Paint<T>

Sets the foreground to color.

use yansi::Paint;
use yansi::Color::Red;

println!("Red foreground: {}", Paint::new("hi!").fg(Red));
source

pub fn bg(self, color: Color) -> Paint<T>

Sets the background to color.

use yansi::Paint;
use yansi::Color::Yellow;

println!("Yellow background: {}", Paint::new("hi!").bg(Yellow));
source

pub fn bold(self) -> Paint<T>

Enables the bold style on self.

use yansi::Paint;

println!("Using bold: {}", Paint::new("hi").bold());
source

pub fn dimmed(self) -> Paint<T>

Enables the dimmed style on self.

use yansi::Paint;

println!("Using dimmed: {}", Paint::new("hi").dimmed());
source

pub fn italic(self) -> Paint<T>

Enables the italic style on self.

use yansi::Paint;

println!("Using italic: {}", Paint::new("hi").italic());
source

pub fn underline(self) -> Paint<T>

Enables the underline style on self.

use yansi::Paint;

println!("Using underline: {}", Paint::new("hi").underline());

Enables the blink style on self.

use yansi::Paint;

println!("Using blink: {}", Paint::new("hi").blink());
source

pub fn invert(self) -> Paint<T>

Enables the invert style on self.

use yansi::Paint;

println!("Using invert: {}", Paint::new("hi").invert());
source

pub fn hidden(self) -> Paint<T>

Enables the hidden style on self.

use yansi::Paint;

println!("Using hidden: {}", Paint::new("hi").hidden());
source

pub fn strikethrough(self) -> Paint<T>

Enables the strikethrough style on self.

use yansi::Paint;

println!("Using strikethrough: {}", Paint::new("hi").strikethrough());
source§

impl Paint<()>

source

pub fn disable()

Disables coloring globally.

Example
use yansi::Paint;

// With coloring enabled, ANSI color codes are emitted.
assert_ne!(Paint::green("go").to_string(), "go".to_string());

// With coloring disabled, ANSI color codes are _not_ emitted.
Paint::disable();
assert_eq!(Paint::green("go").to_string(), "go".to_string());
source

pub fn enable()

Enables coloring globally. Coloring is enabled by default, so this method should only be called to re enable coloring.

Example
use yansi::Paint;

// With coloring disabled, ANSI color codes are _not_ emitted.
Paint::disable();
assert_eq!(Paint::green("go").to_string(), "go".to_string());

// Reenabling causes color code to be emitted.
Paint::enable();
assert_ne!(Paint::green("go").to_string(), "go".to_string());
source

pub fn is_enabled() -> bool

Returns true if coloring is enabled and false otherwise. Coloring is enabled by default but can be enabled and disabled on-the-fly with the Paint::enable() and Paint::disable() methods.

Example
use yansi::Paint;

// Coloring is enabled by default.
assert!(Paint::is_enabled());

// Disable it with `Paint::disable()`.
Paint::disable();
assert!(!Paint::is_enabled());

// Reenable with `Paint::enable()`.
Paint::enable();
assert!(Paint::is_enabled());
source

pub fn enable_windows_ascii() -> bool

Enables ASCII terminal escape sequences on Windows consoles when possible. Returns true if escape sequence support was successfully enabled and false otherwise. On non-Windows targets, this method always returns true.

Support for escape sequences in Windows consoles was added in the Windows 10 anniversary update. For targets with older Windows installations, this method is expected to return false.

Example
use yansi::Paint;

// A best-effort Windows ASCII terminal support enabling.
Paint::enable_windows_ascii();

Trait Implementations§

source§

impl<T: Clone> Clone for Paint<T>

source§

fn clone(&self) -> Paint<T>

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<T: Debug> Debug for Paint<T>

source§

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

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

impl<T: Default> Default for Paint<T>

source§

fn default() -> Paint<T>

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

impl<T: Display> Display for Paint<T>

source§

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

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

impl<T: Hash> Hash for Paint<T>

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<T: Ord> Ord for Paint<T>

source§

fn cmp(&self, other: &Paint<T>) -> Ordering

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

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

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

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

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

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

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

impl<T: PartialEq> PartialEq for Paint<T>

source§

fn eq(&self, other: &Paint<T>) -> 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<T: PartialOrd> PartialOrd for Paint<T>

source§

fn partial_cmp(&self, other: &Paint<T>) -> 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<T: Copy> Copy for Paint<T>

source§

impl<T: Eq> Eq for Paint<T>

source§

impl<T> StructuralEq for Paint<T>

source§

impl<T> StructuralPartialEq for Paint<T>

Auto Trait Implementations§

§

impl<T> RefUnwindSafe for Paint<T>
where T: RefUnwindSafe,

§

impl<T> Send for Paint<T>
where T: Send,

§

impl<T> Sync for Paint<T>
where T: Sync,

§

impl<T> Unpin for Paint<T>
where T: Unpin,

§

impl<T> UnwindSafe for Paint<T>
where T: UnwindSafe,

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where 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 T
where 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> ToOwned for T
where 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> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where 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 T
where 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.