13 releases (4 stable)

2.1.0	Jun 9, 2024
1.1.0	Apr 28, 2024
0.7.0	Mar 2, 2023
0.6.0	Mar 15, 2021
0.2.0	Apr 9, 2017

#106 in Command-line interface

8,978 downloads per month
Used in 30 crates (29 directly)

MIT/Apache

34KB
515 lines

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.

Dependencies

~175KB