Crate colour

Colour

Macros for creating coloured console output.

General

To view the colour palette:

cargo run --example println

The following macros are provided:

Like print! (writes to stdout, no newline)		Like println! (writes to stdout, with newline)
Normal Colour	Dark Colour	Normal Colour	Dark Colour
black!	N/A	black_ln!	N/A
red!	dark_red!	red_ln!	dark_red_ln!
green!	dark_green!	green_ln!	dark_green_ln!
yellow!	dark_yellow!	yellow_ln!	dark_yellow_ln!
blue!	dark_blue!	blue_ln!	dark_blue_ln!
magenta!	dark_magenta!	magenta_ln!	dark_magenta_ln!
cyan!	dark_cyan!	cyan_ln!	dark_cyan_ln!
grey!	dark_grey!	grey_ln!	dark_grey_ln!
gray!	dark_gray!	gray_ln!	dark_gray_ln!
white!	N/A	white_ln!	N/A

Like eprint! (writes to stderr, no newline)		Like eprintln! (writes to stderr, with newline)
Normal Colour	Dark Colour	Normal Colour	Dark Colour
e_black!	N/A	e_black_ln!	N/A
e_red!	e_dark_red!	e_red_ln!	e_dark_red_ln!
e_green!	e_dark_green!	e_green_ln!	e_dark_green_ln!
e_yellow!	e_dark_yellow!	e_yellow_ln!	e_dark_yellow_ln!
e_blue!	e_dark_blue!	e_blue_ln!	e_dark_blue_ln!
e_magenta!	e_dark_magenta!	e_magenta_ln!	e_dark_magenta_ln!
e_cyan!	e_dark_cyan!	e_cyan_ln!	e_dark_cyan_ln!
e_grey!	e_dark_grey!	e_grey_ln!	e_dark_grey_ln!
e_gray!	e_dark_gray!	e_gray_ln!	e_dark_gray_ln!
e_white!	N/A	e_white_ln!	N/A

Like write! (no newline)		Like writeln! (with newline)
Normal Colour	Dark Colour	Normal Colour	Dark Colour
write_black!	N/A	write_black_ln!	N/A
write_red!	write_dark_red!	write_red_ln!	write_dark_red_ln!
write_green!	write_dark_green!	write_green_ln!	write_dark_green_ln!
write_yellow!	write_dark_yellow!	write_yellow_ln!	write_dark_yellow_ln!
write_blue!	write_dark_blue!	write_blue_ln!	write_dark_blue_ln!
write_magenta!	write_dark_magenta!	write_magenta_ln!	write_dark_magenta_ln!
write_cyan!	write_dark_cyan!	write_cyan_ln!	write_dark_cyan_ln!
write_grey!	write_dark_grey!	write_grey_ln!	write_dark_grey_ln!
write_gray!	write_dark_gray!	write_gray_ln!	write_dark_gray_ln!
write_white!	N/A	write_white_ln!	N/A

All of these macros are available with bold formatting by appending _bold (for example blue_ln_bold).

There following macros which use the default foreground colour are also available:

• print_bold!
• eprint_bold! and e_print_bold!
• println_bold! and print_ln_bold!
• eprintln_bold! and e_print_ln_bold!
• write_bold!
• writeln_bold!

Configuration

The crate follows the recommendations in Standard for ANSI Colors in Terminals, meaning that the environment variables NO_COLOR and CLICOLOR_FORCE are respected. The library acts as if CLICOLOR is set, so that environment variable has no effect.

The environment variable TERM is also considered: if set to dumb, coloured output is disabled, and if set to any other value, coloured output is enabled.

The order of precedence is NO_COLOR, followed by CLICOLOR_FORCE and then TERM.

Usage in Binaries

Binaries can override these environment variables and the automatic detection of a terminal/tty by calling force_colour or force_no_colour. The binary should call only one of these, and the call should happen before any potential calls to any of the macros this crate provides.

Libraries should generally never call these functions.

Example

use colour::*;

fn _foo() {
    let err: Result<(), u8> = Err(1);
    yellow_ln!("Failed on {}", 9);
    print!("Error details: ");
    dark_red_ln_bold!("{:?}", err);
}

fn main() {
    grey_ln!("grey");
    grey_ln_bold!("bold grey");
    dark_grey_ln!("dark grey");
    dark_grey_ln_bold!("bold dark grey");
    red_ln!("red");
    red_ln_bold!("bold red");
    dark_red_ln!("dark red");
    dark_red_ln_bold!("bold dark red");
    green_ln!("green");
    green_ln_bold!("bold green");
    dark_green_ln!("dark green");
    dark_green_ln_bold!("bold dark green");
    yellow_ln!("yellow");
    yellow_ln_bold!("bold yellow");
    dark_yellow_ln!("dark yellow");
    dark_yellow_ln_bold!("bold dark yellow");
    blue_ln!("blue");
    blue_ln_bold!("bold blue");
    dark_blue_ln!("dark blue");
    dark_blue_ln_bold!("bold dark blue");
    magenta_ln!("magenta");
    magenta_ln_bold!("bold magenta");
    dark_magenta_ln!("dark magenta");
    dark_magenta_ln_bold!("bold dark magenta");
    cyan_ln!("cyan");
    cyan_ln_bold!("bold cyan");
    dark_cyan_ln!("dark cyan");
    dark_cyan_ln_bold!("bold dark cyan");
    black_ln!("black");
    black_ln_bold!("bold black");
    white_ln!("white");
    white_ln_bold!("bold white");
    println!("default colour");
    println_bold!("bold default colour");
}

Minimum Rust Version

The crate can be compiled with Rust versions 1.70.0 and newer.

License

colour is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-MIT and LICENSE-APACHE for details.

Macros

black

black_bold

black_ln

black_ln_bold

blue

blue_bold

blue_ln

blue_ln_bold

cyan

cyan_bold

cyan_ln

cyan_ln_bold

dark_blue

dark_blue_bold

dark_blue_ln

dark_blue_ln_bold

dark_cyan

dark_cyan_bold

dark_cyan_ln

dark_cyan_ln_bold

dark_gray

dark_gray_bold

dark_gray_ln

dark_gray_ln_bold

dark_green

dark_green_bold

dark_green_ln

dark_green_ln_bold

dark_grey

dark_grey_bold

dark_grey_ln

dark_grey_ln_bold

dark_magenta

dark_magenta_bold

dark_magenta_ln

dark_magenta_ln_bold

dark_red

dark_red_bold

dark_red_ln

dark_red_ln_bold

dark_yellow

dark_yellow_bold

dark_yellow_ln

dark_yellow_ln_bold

e_black

e_black_bold

e_black_ln

e_black_ln_bold

e_blue

e_blue_bold

e_blue_ln

e_blue_ln_bold

e_cyan

e_cyan_bold

e_cyan_ln

e_cyan_ln_bold

e_dark_blue

e_dark_blue_bold

e_dark_blue_ln

e_dark_blue_ln_bold

e_dark_cyan

e_dark_cyan_bold

e_dark_cyan_ln

e_dark_cyan_ln_bold

e_dark_gray

e_dark_gray_bold

e_dark_gray_ln

e_dark_gray_ln_bold

e_dark_green

e_dark_green_bold

e_dark_green_ln

e_dark_green_ln_bold

e_dark_grey

e_dark_grey_bold

e_dark_grey_ln

e_dark_grey_ln_bold

e_dark_magenta

e_dark_magenta_bold

e_dark_magenta_ln

e_dark_magenta_ln_bold

e_dark_red

e_dark_red_bold

e_dark_red_ln

e_dark_red_ln_bold

e_dark_yellow

e_dark_yellow_bold

e_dark_yellow_ln

e_dark_yellow_ln_bold

e_gray

e_gray_bold

e_gray_ln

e_gray_ln_bold

e_green

e_green_bold

e_green_ln

e_green_ln_bold

e_grey

e_grey_bold

e_grey_ln

e_grey_ln_bold

e_magenta

e_magenta_bold

e_magenta_ln

e_magenta_ln_bold

e_print_bold

e_print_ln_bold

e_red

e_red_bold

e_red_ln

e_red_ln_bold

e_white

e_white_bold

e_white_ln

e_white_ln_bold

e_yellow

e_yellow_bold

e_yellow_ln

e_yellow_ln_bold

eprint_bold

eprintln_bold

gray

gray_bold

gray_ln

gray_ln_bold

green

green_bold

green_ln

green_ln_bold

grey

grey_bold

grey_ln

grey_ln_bold

magenta

magenta_bold

magenta_ln

magenta_ln_bold

print_bold

print_ln_bold

println_bold

red

red_bold

red_ln

red_ln_bold

white

white_bold

white_ln

white_ln_bold

write_black

write_black_bold

write_blue

write_blue_bold

write_bold

write_cyan

write_cyan_bold

write_dark_blue

write_dark_blue_bold

write_dark_cyan

write_dark_cyan_bold

write_dark_gray

write_dark_gray_bold

write_dark_green

write_dark_green_bold

write_dark_grey

write_dark_grey_bold

write_dark_magenta

write_dark_magenta_bold

write_dark_red

write_dark_red_bold

write_dark_yellow

write_dark_yellow_bold

write_gray

write_gray_bold

write_green

write_green_bold

write_grey

write_grey_bold

write_magenta

write_magenta_bold

write_red

write_red_bold

write_white

write_white_bold

write_yellow

write_yellow_bold

writeln_black

writeln_black_bold

writeln_blue

writeln_blue_bold

writeln_bold

writeln_cyan

writeln_cyan_bold

writeln_dark_blue

writeln_dark_blue_bold

writeln_dark_cyan

writeln_dark_cyan_bold

writeln_dark_gray

writeln_dark_gray_bold

writeln_dark_green

writeln_dark_green_bold

writeln_dark_grey

writeln_dark_grey_bold

writeln_dark_magenta

writeln_dark_magenta_bold

writeln_dark_red

writeln_dark_red_bold

writeln_dark_yellow

writeln_dark_yellow_bold

writeln_gray

writeln_gray_bold

writeln_green

writeln_green_bold

writeln_grey

writeln_grey_bold

writeln_magenta

writeln_magenta_bold

writeln_red

writeln_red_bold

writeln_white

writeln_white_bold

writeln_yellow

writeln_yellow_bold

yellow

yellow_bold

yellow_ln

yellow_ln_bold

Structs

AlreadySet

Error returned when forcing colour on or off, if it has already been initialised to a different value.

Functions

force_color

As per force_colour.

force_colour

Inject ANSI colour escape codes into the output, regardless of the value of the NO_COLOR environment variable, or whether the output terminal (if any) supports them.

force_no_color

As per force_no_colour.

force_no_colour

Do not inject ANSI colour escape codes into the output, regardless of the value of the CLICOLOR_FORCE environment variable, or whether the output terminal (if any) supports them.