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 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 Display
ed or Debug
ed, 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 ANSII
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 unlikeansi_term
, any type implementingDisplay
can be stylized, not only 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 borrows the general API from the 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. |