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