This is a library for controlling colours and formatting, such as red bold text or blue underlined text, on ANSI terminals.
This crate works with Cargo. Add the following to your
Cargo.toml dependencies section:
There are three main types in this crate that you need to be concerned with:
Style holds stylistic information: foreground and background colours, whether the text should be bold, or blinking, or other properties.
Colour enum represents the available colours.
ANSIString is a string paired with a
Color is also available as an alias to
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:
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
let red_string = Red.paint.to_string;
Note for Windows 10 users: On Windows 10, the application must enable ANSI support first:
let enabled = enable_ansi_support;
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
You can do this by chaining methods based on a new
Style, created with
Each method creates a new style that has that specific property set.
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
The complete list of styles you can use are:
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
You can do this using the
You can turn a
Colour into a
Style with the
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.
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
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:
Combining successive coloured strings
The 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. For 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.
This crate can optimise the ANSI codes that get printed in situations like this, making life easier for your terminal renderer.
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.
The following code snippet uses this to enclose a binary number displayed in red bold text inside some red, but not bold, brackets:
let some_value = format!;
let strings: & = &;
There are several things to note here.
paint method can take either an owned
String or a borrowed
ANSIString holds a copy-on-write (
Cow) string value to deal with both owned and borrowed strings at the same time.
This is used here to display a
String, the result of the
format! call, using the same mechanism as some statically-available
Secondly, that the
ANSIStrings value works in the same way as its singular counterpart, with a
Display implementation that only performs the formatting when required.
This library also supports formatting
[u8] byte strings; this supports applications working with text in an unknown encoding.
Colour support painting
[u8] values, resulting in an
This type does not implement
Display, as it may not contain UTF-8, but it does provide a method
write_to to write the result to any value that implements
Similarly, the type
ANSIByteStrings supports writing a list of
ANSIByteString values with minimal escape sequences: