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[![Linux build status](https://api.travis-ci.org/BurntSushi/termcolor.png)](https://travis-ci.org/BurntSushi/termcolor) 10[![Windows build status](https://ci.appveyor.com/api/projects/status/github/BurntSushi/termcolor?svg=true)](https://ci.appveyor.com/project/BurntSushi/termcolor) 11[![](https://img.shields.io/crates/v/termcolor.svg)](https://crates.io/crates/termcolor) 12 13Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org). 14 15### Documentation 16 17[https://docs.rs/termcolor](https://docs.rs/termcolor) 18 19### Usage 20 21Add this to your `Cargo.toml`: 22 23```toml 24[dependencies] 25termcolor = "1" 26``` 27 28and this to your crate root: 29 30```rust 31extern crate termcolor; 32``` 33 34### Organization 35 36The `WriteColor` trait extends the `io::Write` trait with methods for setting 37colors or resetting them. 38 39`StandardStream` and `StandardStreamLock` both satisfy `WriteColor` and are 40analogous to `std::io::Stdout` and `std::io::StdoutLock`, or `std::io::Stderr` 41and `std::io::StderrLock`. 42 43`Buffer` is an in memory buffer that supports colored text. In a parallel 44program, each thread might write to its own buffer. A buffer can be printed to 45stdout or stderr using a `BufferWriter`. The advantage of this design is that 46each thread can work in parallel on a buffer without having to synchronize 47access to global resources such as the Windows console. Moreover, this design 48also prevents interleaving of buffer output. 49 50`Ansi` and `NoColor` both satisfy `WriteColor` for arbitrary implementors of 51`io::Write`. These types are useful when you know exactly what you need. An 52analogous type for the Windows console is not provided since it cannot exist. 53 54### Example: using `StandardStream` 55 56The `StandardStream` type in this crate works similarly to `std::io::Stdout`, 57except it is augmented with methods for coloring by the `WriteColor` trait. 58For example, to write some green text: 59 60```rust 61use std::io::Write; 62use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, WriteColor}; 63 64let mut stdout = StandardStream::stdout(ColorChoice::Always); 65stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?; 66writeln!(&mut stdout, "green text!")?; 67``` 68 69### Example: using `BufferWriter` 70 71A `BufferWriter` can create buffers and write buffers to stdout or stderr. It 72does *not* implement `io::Write` or `WriteColor` itself. Instead, `Buffer` 73implements `io::Write` and `termcolor::WriteColor`. 74 75This example shows how to print some green text to stderr. 76 77```rust 78use std::io::Write; 79use termcolor::{BufferWriter, Color, ColorChoice, ColorSpec, WriteColor}; 80 81let mut bufwtr = BufferWriter::stderr(ColorChoice::Always); 82let mut buffer = bufwtr.buffer(); 83buffer.set_color(ColorSpec::new().set_fg(Some(Color::Green)))?; 84writeln!(&mut buffer, "green text!")?; 85bufwtr.print(&buffer)?; 86``` 87