Crate yansi [−] [src]

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 only entry paint to this library is the Paint type. Paint encapsulates a value of any type that implements the Display trait. When a Paint is Displayed, the appropriate ANSI codes are emitted before and after the Display implementation of the wrapped type.

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.

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 implementation for Paint will emit the Display of the contained object and nothing else. Painting can be reenabled via the Paint::enable() method.

Windows

This is an ANSI terminal coloring library. Unless the Windows terminal supports ANSI colors, colors won't display properly on Windows. This is a bummer, I know. If you'd like, yansi makes it easy to disable coloring on Windows:

if cfg!(windows) {
    Paint::disable();
}

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 under 200 lines of code.
  • Like term_painter, but unlike ansi_term, any type implementing Display can be stylized, not just strings.
  • Styling can be enabled and disabled on the fly.
  • 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 borrowed the general API from all three libraries as well as plenty of code from ansi_term.

Structs

Paint

A structure encapsulating all of the styling for a given item.

Enums

Color

An enum representing an ANSI color code.