README.md
1# rust-ansi-term [](https://crates.io/crates/ansi_term) [](https://travis-ci.org/ogham/rust-ansi-term) [](https://coveralls.io/github/ogham/rust-ansi-term?branch=master)
2
3This is a library for controlling colours and formatting, such as red bold text or blue underlined text, on ANSI terminals.
4
5### [View the Rustdoc](https://docs.rs/ansi_term/0.9.0/ansi_term/)
6
7
8# Installation
9
10This crate works with [Cargo](http://crates.io). Add the following to your `Cargo.toml` dependencies section:
11
12```toml
13[dependencies]
14ansi_term = "0.9"
15```
16
17
18## Basic usage
19
20There are two main data structures in this crate that you need to be concerned with: `ANSIString` and `Style`.
21A `Style` holds stylistic information: colours, whether the text should be bold, or blinking, or whatever.
22There are also `Colour` variants that represent simple foreground colour styles.
23An `ANSIString` is a string paired with a `Style`.
24
25(Yes, it’s British English, but you won’t have to write “colour” very often. `Style` is used the majority of the time.)
26
27To format a string, call the `paint` method on a `Style` or a `Colour`, passing in the string you want to format as the argument.
28For example, here’s how to get some red text:
29
30```rust
31use ansi_term::Colour::Red;
32println!("This is in red: {}", Red.paint("a red string"));
33```
34
35It’s important to note that the `paint` method does *not* actually return a string with the ANSI control characters surrounding it.
36Instead, it returns an `ANSIString` value that has a `Display` implementation that, when formatted, returns the characters.
37This allows strings to be printed with a minimum of `String` allocations being performed behind the scenes.
38
39If you *do* want to get at the escape codes, then you can convert the `ANSIString` to a string as you would any other `Display` value:
40
41```rust
42use ansi_term::Colour::Red;
43use std::string::ToString;
44let red_string = Red.paint("a red string").to_string();
45```
46
47**Note for Windows 10 users:** On Windows 10, the application must enable ANSI support first:
48
49```rust
50let enabled = ansi_term::enable_ansi_support();
51```
52
53## Bold, underline, background, and other styles
54
55For anything more complex than plain foreground colour changes, you need to construct `Style` objects themselves, rather than beginning with a `Colour`.
56You can do this by chaining methods based on a new `Style`, created with `Style::new()`.
57Each method creates a new style that has that specific property set.
58For example:
59
60```rust
61use ansi_term::Style;
62println!("How about some {} and {}?",
63 Style::new().bold().paint("bold"),
64 Style::new().underline().paint("underline"));
65```
66
67For brevity, these methods have also been implemented for `Colour` values, so you can give your styles a foreground colour without having to begin with an empty `Style` value:
68
69```rust
70use ansi_term::Colour::{Blue, Yellow};
71println!("Demonstrating {} and {}!",
72 Blue.bold().paint("blue bold"),
73 Yellow.underline().paint("yellow underline"));
74println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
75```
76
77The complete list of styles you can use are:
78`bold`, `dimmed`, `italic`, `underline`, `blink`, `reverse`, `hidden`, and `on` for background colours.
79
80In some cases, you may find it easier to change the foreground on an existing `Style` rather than starting from the appropriate `Colour`.
81You can do this using the `fg` method:
82
83```rust
84 use ansi_term::Style;
85 use ansi_term::Colour::{Blue, Cyan, Yellow};
86 println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
87 println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
88```
89
90Finally, you can turn a `Colour` into a `Style` with the `normal` method.
91This will produce the exact same `ANSIString` as if you just used the `paint` method on the `Colour` directly, but it’s useful in certain cases: for example, you may have a method that returns `Styles`, and need to represent both the “red bold” and “red, but not bold” styles with values of the same type. The `Style` struct also has a `Default` implementation if you want to have a style with *nothing* set.
92
93```rust
94use ansi_term::Style;
95use ansi_term::Colour::Red;
96Red.normal().paint("yet another red string");
97Style::default().paint("a completely regular string");
98```
99
100
101## Extended colours
102
103You can access the extended range of 256 colours by using the `Fixed` colour variant, which takes an argument of the colour number to use.
104This can be included wherever you would use a `Colour`:
105
106```rust
107use ansi_term::Colour::Fixed;
108Fixed(134).paint("A sort of light purple");
109Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");
110```
111
112The first sixteen of these values are the same as the normal and bold standard colour variants.
113There’s nothing stopping you from using these as `Fixed` colours instead, but there’s nothing to be gained by doing so either.
114
115You can also access full 24-bit color by using the `RGB` colour variant, which takes separate `u8` arguments for red, green, and blue:
116
117```rust
118 use ansi_term::Colour::RGB;
119 RGB(70, 130, 180).paint("Steel blue");
120```
121
122## Combining successive coloured strings
123
124The benefit of writing ANSI escape codes to the terminal is that they *stack*: you do not need to end every coloured string with a reset code if the text that follows it is of a similar style.
125For example, if you want to have some blue text followed by some blue bold text, it’s possible to send the ANSI code for blue, followed by the ANSI code for bold, and finishing with a reset code without having to have an extra one between the two strings.
126
127This crate can optimise the ANSI codes that get printed in situations like this, making life easier for your terminal renderer.
128The `ANSIStrings` struct takes a slice of several `ANSIString` values, and will iterate over each of them, printing only the codes for the styles that need to be updated as part of its formatting routine.
129
130The following code snippet uses this to enclose a binary number displayed in red bold text inside some red, but not bold, brackets:
131
132```rust
133use ansi_term::Colour::Red;
134use ansi_term::{ANSIString, ANSIStrings};
135let some_value = format!("{:b}", 42);
136let strings: &[ANSIString<'static>] = &[
137 Red.paint("["),
138 Red.bold().paint(some_value),
139 Red.paint("]"),
140];
141println!("Value: {}", ANSIStrings(strings));
142```
143
144There are several things to note here.
145Firstly, the `paint` method can take *either* an owned `String` or a borrowed `&str`.
146Internally, an `ANSIString` holds a copy-on-write (`Cow`) string value to deal with both owned and borrowed strings at the same time.
147This is used here to display a `String`, the result of the `format!` call, using the same mechanism as some statically-available `&str` slices.
148Secondly, that the `ANSIStrings` value works in the same way as its singular counterpart, with a `Display` implementation that only performs the formatting when required.
149
150## Byte strings
151
152This library also supports formatting `[u8]` byte strings; this supports
153applications working with text in an unknown encoding. `Style` and
154`Color` support painting `[u8]` values, resulting in an `ANSIByteString`.
155This type does not implement `Display`, as it may not contain UTF-8, but
156it does provide a method `write_to` to write the result to any
157`io::Write`:
158
159```rust
160use ansi_term::Colour::Green;
161Green.paint("user data".as_bytes()).write_to(&mut std::io::stdout()).unwrap();
162```
163
164Similarly, the type `ANSIByteStrings` supports writing a list of
165`ANSIByteString` values with minimal escape sequences:
166
167```rust
168use ansi_term::Colour::Green;
169use ansi_term::ANSIByteStrings;
170ANSIByteStrings(&[
171 Green.paint("user data 1\n".as_bytes()),
172 Green.bold().paint("user data 2\n".as_bytes()),
173]).write_to(&mut std::io::stdout()).unwrap();
174```
175
){kind=link}
){kind=link}