Crate ansi_term [] [src]

This is a library for controlling colours and formatting, such as red bold text or blue underlined text, on ANSI terminals.

extern crate ansi_term;
use ansi_term::Colour::{Black, Red, Green, Yellow, Blue, Purple, Cyan, Fixed};
use ansi_term::Style::Plain;

Simple Colours

You can format strings by calling the paint method on a Colour or a Style object, passing in the string you want to format. For example, to get some red text, call the paint method on Red:

println!("This is in red: {}!", Red.paint("a red string"));

The paint method returns an ANSIString object, which will get automatically converted to the correct sequence of escape codes when used in a println! or format! macro, or anything else that supports using the Show trait. This means that if you just want a string of the escape codes without anything else, you can still use the to_string method:

let red_string: String = Red.paint("another red string").to_string();

Bold, Underline, and Background

To do anything more complex than just foreground colours, you need to use Style objects. Calling the bold or underline method on a Colour returns a Style that has the appropriate property set on it:

println!("Demonstrating {} and {}!",
         Blue.bold().paint("blue bold"),
         Yellow.underline().paint("yellow underline"));

These methods chain, so you can call them on existing Style objects to set more than one particular properly, like so:

Blue.underline().bold().paint("Blue underline bold!")

You can set the background colour of a Style by using the on method:

Blue.on(Yellow).paint("Blue on yellow!")

Finally, you can turn a Colour into a Style with the normal method, though it'll produce the exact same string if you just use the Colour. It's only useful if you're writing a method that can return either normal or bold (or underline) styles, and need to return a Style object from it.

Red.normal().paint("yet another red string")

Extended Colours

You can access the extended range of 256 colours by using the Fixed constructor, which takes an argument of the colour number to use. This can be used wherever you would use a Colour:

Fixed(134).paint("A sort of light purple.")

This even works for background colours:

Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup.")

No Formatting

Finally, for the sake of completeness, the Plain style provides neither colours nor formatting.

Plain.paint("No colours here.")

Structs

ANSIString

An ANSI String is a string coupled with the Style to display it in a terminal.

ANSIStrings

A set of ANSIStrings collected together, in order to be written with a minimum of control characters.

Enums

Colour

A colour is one specific type of ANSI escape code, and can refer to either the foreground or background colour.

Style

A style is a collection of properties that can format a string using ANSI escape codes.