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