Crate termcolor [−] [src]
This crate provides a cross platform abstraction for writing colored text to a terminal. Colors are written using either ANSI escape sequences or by communicating with a Windows console. Much of this API was motivated by use inside command line applications, where colors or styles can be configured by the end user and/or the environment.
This crate also provides platform independent support for writing colored text to an in memory buffer. While this is easy to do with ANSI escape sequences (because they are in the buffer themselves), it is trickier to do with the Windows console API, which requires synchronous communication.
Organization
The WriteColor
trait extends the io::Write
trait with methods for setting
colors or resetting them.
Stdout
and StdoutLock
both satisfy WriteColor
and are analogous to
std::io::Stdout
and std::io::StdoutLock
.
Buffer
is an in memory buffer that supports colored text. In a parallel
program, each thread might write to its own buffer. A buffer can be printed
to stdout using a BufferWriter
. The advantage of this design is that
each thread can work in parallel on a buffer without having to synchronize
access to global resources such as the Windows console. Moreover, this design
also prevents interleaving of buffer output.
Ansi
and NoColor
both satisfy WriteColor
for arbitrary implementors of
io::Write
. These types are useful when you know exactly what you need. An
analogous type for the Windows console is not provided since it cannot exist.
Example: using Stdout
The Stdout
type in this crate works similarly to std::io::Stdout
, except
it is augmented with methods for coloring by the WriteColor
trait. For
example, to write some green text:
use std::io::Write; use termcolor::{Color, ColorChoice, ColorSpec, Stdout, WriteColor}; let mut stdout = Stdout::new(ColorChoice::Always); try!(stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)))); try!(writeln!(&mut stdout, "green text!"));
Example: using BufferWriter
A BufferWriter
can create buffers and write buffers to stdout. It does not
implement io::Write
or WriteColor
itself. Instead, Buffer
implements
io::Write
and io::WriteColor
.
This example shows how to print some green text to stdout.
use std::io::Write; use termcolor::{BufferWriter, Color, ColorChoice, ColorSpec, WriteColor}; let mut bufwtr = BufferWriter::stdout(ColorChoice::Always); let mut buffer = bufwtr.buffer(); try!(buffer.set_color(ColorSpec::new().set_fg(Some(Color::Green)))); try!(writeln!(&mut buffer, "green text!")); try!(bufwtr.print(&buffer));
Structs
Ansi |
Satisfies |
Buffer |
Write colored text to memory. |
BufferWriter |
Writes colored buffers to stdout. |
ColorSpec |
A color specification. |
NoColor |
Satisfies |
ParseColorError |
An error from parsing an invalid color name. |
Stdout |
Satisfies |
StdoutLock |
|
Enums
Color |
The set of available English colors for the terminal foreground/background. |
ColorChoice |
ColorChoice represents the color preferences of an end user. |
Traits
WriteColor |
This trait describes the behavior of writers that support colored output. |