1//! > Adapted from [`rust-ansi-term`](https://github.com/ogham/rust-ansi-term)
2//! >
3//! > Refactor for use [`fmt::Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html)
4//! and `FnOnce(&mut fmt::Formatter) -> fmt::Result`
5//! This is a library for controlling colours and formatting, such as
6//! red bold text or blue underlined text, on ANSI terminals.
7//!
8//!
9//! ## Basic usage
10//!
11//! There are three main types in this crate that you need to be
12//! concerned with: [`ANSIString`], [`Style`], and [`Colour`].
13//!
14//! A `Style` holds stylistic information: foreground and background colours,
15//! whether the text should be bold, or blinking, or other properties. The
16//! [`Colour`] enum represents the available colours. And an [`ANSIString`] is a
17//! string paired with a [`Style`].
18//!
19//! [`Color`] is also available as an alias to `Colour`.
20//!
21//! To format a string, call the `paint` method on a `Style` or a `Colour`,
22//! passing in the string you want to format as the argument. For example,
23//! here’s how to get some red text:
24//!
25//! ```
26//! use yansi_term::Colour::Red;
27//!
28//! println!("This is in red: {}", Red.paint("a red string"));
29//! ```
30//!
31//! It’s important to note that the `paint` method does *not* actually return a
32//! string with the ANSI control characters surrounding it. Instead, it returns
33//! that has a [`Display`] implementation that, when formatted, returns the characters.
34//! ```
35//! use yansi_term::Colour::Red;
36//!
37//! let red_string = Red.paint("a red string").to_string();
38//! ```
39//!
40//!
41//! ## Bold, underline, background, and other styles
42//!
43//! For anything more complex than plain foreground colour changes, you need to
44//! construct `Style` values themselves, rather than beginning with a `Colour`.
45//! You can do this by chaining methods based on a new `Style`, created with
46//! [`Style::new()`]. Each method creates a new style that has that specific
47//! property set. For example:
48//!
49//! ```
50//! use yansi_term::Style;
51//!
52//! println!("How about some {} and {}?",
53//! Style::new().bold().paint("bold"),
54//! Style::new().underline().paint("underline"));
55//! ```
56//!
57//! For brevity, these methods have also been implemented for `Colour` values,
58//! so you can give your styles a foreground colour without having to begin with
59//! an empty `Style` value:
60//!
61//! ```
62//! use yansi_term::Colour::{Blue, Yellow};
63//!
64//! println!("Demonstrating {} and {}!",
65//! Blue.bold().paint("blue bold"),
66//! Yellow.underline().paint("yellow underline"));
67//!
68//! println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
69//! ```
70//!
71//! The complete list of styles you can use are: [`bold`], [`dimmed`], [`italic`],
72//! [`underline`], [`blink`], [`reverse`], [`hidden`], [`strikethrough`], and [`on`] for
73//! background colours.
74//!
75//! In some cases, you may find it easier to change the foreground on an
76//! existing `Style` rather than starting from the appropriate `Colour`.
77//! You can do this using the [`fg`] method:
78//!
79//! ```
80//! use yansi_term::Style;
81//! use yansi_term::Colour::{Blue, Cyan, Yellow};
82//!
83//! println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
84//! println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
85//! ```
86//!
87//! You can turn a `Colour` into a `Style` with the [`normal`] method.
88//! This will produce the exact same `ANSIString` as if you just used the
89//! `paint` method on the `Colour` directly, but it’s useful in certain cases:
90//! for example, you may have a method that returns `Styles`, and need to
91//! represent both the “red bold” and “red, but not bold” styles with values of
92//! the same type. The `Style` struct also has a [`Default`] implementation if you
93//! want to have a style with *nothing* set.
94//!
95//! ```
96//! use yansi_term::Style;
97//! use yansi_term::Colour::Red;
98//!
99//! Red.normal().paint("yet another red string");
100//! Style::default().paint("a completely regular string");
101//! ```
102//!
103//!
104//! ## Extended colours
105//!
106//! You can access the extended range of 256 colours by using the `Colour::Fixed`
107//! variant, which takes an argument of the colour number to use. This can be
108//! included wherever you would use a `Colour`:
109//!
110//! ```
111//! use yansi_term::Colour::Fixed;
112//!
113//! Fixed(134).paint("A sort of light purple");
114//! Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");
115//! ```
116//!
117//! The first sixteen of these values are the same as the normal and bold
118//! standard colour variants. There’s nothing stopping you from using these as
119//! `Fixed` colours instead, but there’s nothing to be gained by doing so
120//! either.
121//!
122//! You can also access full 24-bit colour by using the `Colour::RGB` variant,
123//! which takes separate `u8` arguments for red, green, and blue:
124//!
125//! ```
126//! use yansi_term::Colour::RGB;
127//!
128//! RGB(70, 130, 180).paint("Steel blue");
129//! ```
130
131//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
132//! [`Default`]: https://doc.rust-lang.org/std/default/trait.Default.html
133//! [`Style`]: struct.Style.html
134//! [`Style::new()`]: struct.Style.html#method.new
135//! [`Color`]: enum.Color.html
136//! [`Colour`]: enum.Colour.html
137//!
138//! [`bold`]: struct.Style.html#method.bold
139//! [`dimmed`]: struct.Style.html#method.dimmed
140//! [`italic`]: struct.Style.html#method.italic
141//! [`underline`]: struct.Style.html#method.underline
142//! [`blink`]: struct.Style.html#method.blink
143//! [`reverse`]: struct.Style.html#method.reverse
144//! [`hidden`]: struct.Style.html#method.hidden
145//! [`strikethrough`]: struct.Style.html#method.strikethrough
146//! [`fg`]: struct.Style.html#method.fg
147//! [`on`]: struct.Style.html#method.on
148
149#[cfg(target_os = "windows")]
150extern crate winapi;
151#[cfg(test)]
152#[macro_use]
153extern crate doc_comment;
154
155#[cfg(test)]
156doctest!("../README.md");
157
158mod ansi;
159mod style;
160pub use style::{Colour, Style};
161
162/// Color is a type alias for `Colour`.
163pub use Colour as Color;
164
165mod display;
166
167mod windows;
168pub use windows::*;
169