Skip to content
Cross platform terminal colors for Rust.
Rust Shell
Branch: master
Clone or download
Latest commit 224c903 Aug 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ci termcolor: rearrange repository Jul 17, 2018
src windows: support the first 16 Ansi256 Jun 4, 2019
wincolor wincolor-1.0.2 Aug 16, 2019
.gitignore termcolor: rearrange repository Jul 17, 2018
.travis.yml ci Jul 17, 2018
COPYING initial commit Feb 27, 2016
Cargo.toml 1.0.5 Jun 4, 2019
LICENSE-MIT initial commit Feb 27, 2016
README.md readme: update recommended version number Jul 21, 2018
UNLICENSE initial commit Feb 27, 2016
appveyor.yml termcolor: rearrange repository Jul 17, 2018

README.md

termcolor

A simple cross platform library for writing colored text to a terminal. This library writes colored text either using standard ANSI escape sequences or by interacting with the Windows console. Several convenient abstractions are provided for use in single-threaded or multi-threaded command line applications.

Linux build status Windows build status

Dual-licensed under MIT or the UNLICENSE.

Documentation

https://docs.rs/termcolor

Usage

Add this to your Cargo.toml:

[dependencies]
termcolor = "1"

and this to your crate root:

extern crate termcolor;

Organization

The WriteColor trait extends the io::Write trait with methods for setting colors or resetting them.

StandardStream and StandardStreamLock both satisfy WriteColor and are analogous to std::io::Stdout and std::io::StdoutLock, or std::io::Stderr and std::io::StderrLock.

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 or stderr 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 StandardStream

The StandardStream 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, StandardStream, WriteColor};

let mut stdout = StandardStream::stdout(ColorChoice::Always);
stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?;
writeln!(&mut stdout, "green text!")?;

Example: using BufferWriter

A BufferWriter can create buffers and write buffers to stdout or stderr. It does not implement io::Write or WriteColor itself. Instead, Buffer implements io::Write and termcolor::WriteColor.

This example shows how to print some green text to stderr.

use std::io::Write;
use termcolor::{BufferWriter, Color, ColorChoice, ColorSpec, WriteColor};

let mut bufwtr = BufferWriter::stderr(ColorChoice::Always);
let mut buffer = bufwtr.buffer();
buffer.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?;
writeln!(&mut buffer, "green text!")?;
bufwtr.print(&buffer)?;
You can’t perform that action at this time.