| ansi.rs |
|
14048 |
| debug.rs |
|
4773 |
| difference.rs |
|
5976 |
| display.rs |
|
8924 |
| lib.rs |
This is a library for controlling colours and formatting, such as
red bold text or blue underlined text, on ANSI terminals.
## Basic usage
There are three main types in this crate that you need to be
concerned with: [`ANSIString`], [`Style`], and [`Colour`].
A `Style` holds stylistic information: foreground and background colours,
whether the text should be bold, or blinking, or other properties. The
[`Colour`] enum represents the available colours. And an [`ANSIString`] is a
string paired with a [`Style`].
[`Color`] is also available as an alias to `Colour`.
To format a string, call the `paint` method on a `Style` or a `Colour`,
passing in the string you want to format as the argument. For example,
here’s how to get some red text:
```
use ansi_term::Colour::Red;
println!("This is in red: {}", Red.paint("a red string"));
```
It’s important to note that the `paint` method does *not* actually return a
string with the ANSI control characters surrounding it. Instead, it returns
an [`ANSIString`] value that has a [`Display`] implementation that, when
formatted, returns the characters. This allows strings to be printed with a
minimum of [`String`] allocations being performed behind the scenes.
If 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:
```
use ansi_term::Colour::Red;
let red_string = Red.paint("a red string").to_string();
```
## Bold, underline, background, and other styles
For anything more complex than plain foreground colour changes, you need to
construct `Style` values themselves, rather than beginning with a `Colour`.
You can do this by chaining methods based on a new `Style`, created with
[`Style::new()`]. Each method creates a new style that has that specific
property set. For example:
```
use ansi_term::Style;
println!("How about some {} and {}?",
Style::new().bold().paint("bold"),
Style::new().underline().paint("underline"));
```
For 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:
```
use ansi_term::Colour::{Blue, Yellow};
println!("Demonstrating {} and {}!",
Blue.bold().paint("blue bold"),
Yellow.underline().paint("yellow underline"));
println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
```
The complete list of styles you can use are: [`bold`], [`dimmed`], [`italic`],
[`underline`], [`blink`], [`reverse`], [`hidden`], [`strikethrough`], and [`on`] for
background colours.
In some cases, you may find it easier to change the foreground on an
existing `Style` rather than starting from the appropriate `Colour`.
You can do this using the [`fg`] method:
```
use ansi_term::Style;
use ansi_term::Colour::{Blue, Cyan, Yellow};
println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
```
You can turn a `Colour` into a `Style` with the [`normal`] method.
This 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.
```
use ansi_term::Style;
use ansi_term::Colour::Red;
Red.normal().paint("yet another red string");
Style::default().paint("a completely regular string");
```
## Extended colours
You can access the extended range of 256 colours by using the `Colour::Fixed`
variant, which takes an argument of the colour number to use. This can be
included wherever you would use a `Colour`:
```
use ansi_term::Colour::Fixed;
Fixed(134).paint("A sort of light purple");
Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");
```
The first sixteen of these values are the same as the normal and bold
standard colour variants. There’s nothing stopping you from using these as
`Fixed` colours instead, but there’s nothing to be gained by doing so
either.
You can also access full 24-bit colour by using the `Colour::RGB` variant,
which takes separate `u8` arguments for red, green, and blue:
```
use ansi_term::Colour::RGB;
RGB(70, 130, 180).paint("Steel blue");
```
## Combining successive coloured strings
|
10026 |
| style.rs |
|
14530 |
| util.rs |
|
1911 |
| windows.rs |
|
2412 |
| write.rs |
|
917 |