e8a30cb893
This commit completely guts all of the color handling code and replaces
most of it with two new crates: wincolor and termcolor. wincolor
provides a simple API to coloring using the Windows console and
termcolor provides a platform independent coloring API tuned for
multithreaded command line programs. This required a lot more
flexibility than what the `term` crate provided, so it was dropped.
We instead switch to writing ANSI escape sequences directly and ignore
the TERMINFO database.
In addition to fixing several bugs, this commit also permits end users
to customize colors to a certain extent. For example, this command will
set the match color to magenta and the line number background to yellow:
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo
For tty handling, we've adopted a hack from `git` to do tty detection in
MSYS/mintty terminals. As a result, ripgrep should get both color
detection and piping correct on Windows regardless of which terminal you
use.
Finally, switch to line buffering. Performance doesn't seem to be
impacted and it's an otherwise more user friendly option.
Fixes #37, Fixes #51, Fixes #94, Fixes #117, Fixes #182, Fixes #231
|
||
|---|---|---|
| .. | ||
| src | ||
| Cargo.toml | ||
| 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.
Dual-licensed under MIT or the UNLICENSE.
Documentation
Usage
Add this to your Cargo.toml:
[dependencies]
termcolor = "0.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.
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));