1termcolor
2=========
3A simple cross platform library for writing colored text to a terminal. This
4library writes colored text either using standard ANSI escape sequences or
5by interacting with the Windows console. Several convenient abstractions
6are provided for use in single-threaded or multi-threaded command line
7applications.
8
9[![Build status](https://github.com/BurntSushi/termcolor/workflows/ci/badge.svg)](https://github.com/BurntSushi/termcolor/actions)
10[![](https://img.shields.io/crates/v/termcolor.svg)](https://crates.io/crates/termcolor)
11
12Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).
13
14### Documentation
15
16[https://docs.rs/termcolor](https://docs.rs/termcolor)
17
18### Usage
19
20Add this to your `Cargo.toml`:
21
22```toml
23[dependencies]
24termcolor = "1.1"
25```
26
27### Organization
28
29The `WriteColor` trait extends the `io::Write` trait with methods for setting
30colors or resetting them.
31
32`StandardStream` and `StandardStreamLock` both satisfy `WriteColor` and are
33analogous to `std::io::Stdout` and `std::io::StdoutLock`, or `std::io::Stderr`
34and `std::io::StderrLock`.
35
36`Buffer` is an in memory buffer that supports colored text. In a parallel
37program, each thread might write to its own buffer. A buffer can be printed to
38stdout or stderr using a `BufferWriter`. The advantage of this design is that
39each thread can work in parallel on a buffer without having to synchronize
40access to global resources such as the Windows console. Moreover, this design
41also prevents interleaving of buffer output.
42
43`Ansi` and `NoColor` both satisfy `WriteColor` for arbitrary implementors of
44`io::Write`. These types are useful when you know exactly what you need. An
45analogous type for the Windows console is not provided since it cannot exist.
46
47### Example: using `StandardStream`
48
49The `StandardStream` type in this crate works similarly to `std::io::Stdout`,
50except it is augmented with methods for coloring by the `WriteColor` trait.
51For example, to write some green text:
52
53```rust
54use std::io::{self, Write};
55use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, WriteColor};
56
57fn write_green() -> io::Result<()> {
58    let mut stdout = StandardStream::stdout(ColorChoice::Always);
59    stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?;
60    writeln!(&mut stdout, "green text!")
61}
62```
63
64### Example: using `BufferWriter`
65
66A `BufferWriter` can create buffers and write buffers to stdout or stderr. It
67does *not* implement `io::Write` or `WriteColor` itself. Instead, `Buffer`
68implements `io::Write` and `termcolor::WriteColor`.
69
70This example shows how to print some green text to stderr.
71
72```rust
73use std::io::{self, Write};
74use termcolor::{BufferWriter, Color, ColorChoice, ColorSpec, WriteColor};
75
76fn write_green() -> io::Result<()> {
77    let mut bufwtr = BufferWriter::stderr(ColorChoice::Always);
78    let mut buffer = bufwtr.buffer();
79    buffer.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?;
80    writeln!(&mut buffer, "green text!")?;
81    bufwtr.print(&buffer)
82}
83```
84
85### Automatic color selection
86
87When building a writer with termcolor, the caller must provide a
88[`ColorChoice`](https://docs.rs/termcolor/1.0.5/termcolor/enum.ColorChoice.html)
89selection. When the color choice is `Auto`, termcolor will attempt to determine
90whether colors should be enabled by inspecting the environment. Currently,
91termcolor will inspect the `TERM` and `NO_COLOR` environment variables:
92
93* If `NO_COLOR` is set to any value, then colors will be suppressed.
94* If `TERM` is set to `dumb`, then colors will be suppressed.
95* In non-Windows environments, if `TERM` is not set, then colors will be
96  suppressed.
97
98This decision procedure may change over time.
99
100Currently, `termcolor` does not attempt to detect whether a tty is present or
101not. To achieve that, please use the [`atty`](https://crates.io/crates/atty)
102crate.
103
104### Minimum Rust version policy
105
106This crate's minimum supported `rustc` version is `1.34.0`.
107
108The current policy is that the minimum Rust version required to use this crate
109can be increased in minor version updates. For example, if `crate 1.0` requires
110Rust 1.20.0, then `crate 1.0.z` for all values of `z` will also require Rust
1111.20.0 or newer. However, `crate 1.y` for `y > 0` may require a newer minimum
112version of Rust.
113
114In general, this crate will be conservative with respect to the minimum
115supported version of Rust.
116