Struct yansi::Paint

pub struct Paint<T> { /* private fields */ }

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.

• Paint::new(item: T)
• Paint::default(item: T)
• Paint::masked(item: T)
• Paint::wrapping(item: T)

Foreground Color Constructors

Return a new Paint structure with a foreground color applied.

• Paint::rgb(r: u8, g: u8, b: u8, item: T)
• Paint::fixed(color: u8, item: T)
• Paint::black(item: T)
• Paint::red(item: T)
• Paint::green(item: T)
• Paint::yellow(item: T)
• Paint::blue(item: T)
• Paint::magenta(item: T)
• Paint::cyan(item: T)
• Paint::white(item: T)

Getters

Return information about the Paint structure.

• paint.style()
• paint.inner()

Setters

Set a style property on a given Paint structure.

• paint.with_style(style: Style)
• paint.mask()
• paint.wrap()
• paint.fg(color: Color)
• paint.bg(color: Color)
• paint.bold()
• paint.dimmed()
• paint.italic()
• paint.underline()
• paint.blink()
• paint.invert()
• paint.hidden()
• paint.strikethrough()

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.

• Paint::enable()
• Paint::disable()
• Paint::is_enabled()
• Paint::enable_windows_ascii()

Implementations

impl<T> Paint<T>

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

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"));

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("🌱 "));

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

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!"));

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!"));

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!"));

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!"));

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!"));

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!"));

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!"));

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!"));

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!"));

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!"));

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

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!");

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!"));

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

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

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

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

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

Enables the bold style on self.

use yansi::Paint;

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

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

Enables the dimmed style on self.

use yansi::Paint;

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

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

Enables the italic style on self.

use yansi::Paint;

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

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

Enables the underline style on self.

use yansi::Paint;

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

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

Enables the blink style on self.

use yansi::Paint;

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

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

Enables the invert style on self.

use yansi::Paint;

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

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

Enables the hidden style on self.

use yansi::Paint;

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

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

Enables the strikethrough style on self.

use yansi::Paint;

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

impl Paint<()>

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

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

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

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

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Paint<T>

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

Formats the value using the given formatter.

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

fn default() -> Paint<T>

Returns the “default value” for a type.

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

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

Formats the value using the given formatter.

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

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

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

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

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

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

impl<T> StructuralEq for Paint<T>

impl<T> StructuralPartialEq for Paint<T>