A dead simple ANSI terminal color painting library.

Usage

Usage is best illustrated via a quick example:

use yansi::Paint;
use yansi::Color::White;

println!("Testing, {}, {}, {}!", Paint::red(1),
    Paint::green(2).bold().underline(),
    Paint::blue("3").bg(White).italic());

Paint

The main entry point into this library is the Paint type. Paint encapsulates a value of any type that implements the Display or Debug trait. When a Paint is Displayed or Debuged, the appropriate ANSI escape characters are emitted before and after the wrapped type's fmt implementation.

Paint can be constructed via any of following methods: black, red, green, yellow, blue, purple, cyan, white. Each of these methods sets the foreground color of the item to be displayed according to the name of the method. Additionally, rgb and fixed allow you to customize the foreground color to your liking. In addition to these constructors, you can also use the paint method on a given Color value to construct a Paint type. Both of these approaches are shown below:

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

println!("I'm {}!", Paint::red("red").bold());
println!("I'm also {}!", Red.paint("red").bold());

Finally, new creates a Paint item without a foreground color applied.

Styling

Modifications to the styling of the item can be added via the followiing chainable builder methods: fg, bg, bold, dimmed, italic, underline, blink, invert, hidden, strikethrough.

Disabling

On Rust nightly and with the nightly feature enabled, painting can be disabled globally via the Paint::disable() method. When painting is disabled, the Display and Debug implementations for Paint will emit the Display or Debug of the contained object and nothing else. Painting can be reenabled via the Paint::enable() method.

One potential use of this feature is to allow users to control color ouput via an environment variable. For instance, to disable coloring if the CLICOLOR variable is set to 0, you might write:

use yansi::Paint;

if let Ok(true) = std::env::var("CLICOLOR").map(|v| v == "0") {
    Paint::disable();
}

Masking

Paint structures can mask arbitrary values. When a value is masked and painting is disabled, the Display and Debug implementations of Paint write nothing. This allows you to selectively omit output when painting is disabled. Values can be masked using the mask builder method or Paint::masked() constructor.

One use for this feature is to print certain characters only when painting is enabled. For instance, you might wish to emit the 🎨 emoji when coloring is enabled but not otherwise. This can be accomplished by masking the emoji:

use yansi::Paint;

println!("I like colors!{}", Paint::masked(" 🎨"));

This will print "I like colors! 🎨" when painting is enabled and "I like colors!" when painting is disabled.

Windows

Since the Windows 10 anniversary update, Windows consoles support ANSI escape sequences. This support, however, must be explicitly enabled. yansi provides the Paint::enable_windows_ascii() method to enable ASCII support on Windows consoles when available.

use yansi::Paint;

// Enable ASCII escape sequence support on Windows consoles.
Paint::enable_windows_ascii();

Why?

Several terminal coloring libraries exist (ansi_term, colored, term_painter, to name a few), begging the question: why yet another? Here are a few reasons:

• This library is much simpler: there are two types! The complete implementation is only about 250 lines of code.
• Like term_painter, but unlike ansi_term, any type implementing Display can be stylized, not only strings.
• Styling can be enabled and disabled on the fly.
• Arbitrary items can be masked for selective disabling.
• Typically, only one type needs to be imported: Paint.
• Zero dependencies. It really is simple.
• The name yansi is pretty short.

All that being said, this library borrows the general API from the three libraries as well as plenty of code from ansi_term.