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 Display
ed, 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 unlikeansi_term
, any type implementingDisplay
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. |