Skip to content

Latest commit

 

History

History
323 lines (297 loc) · 8.65 KB

README.md

File metadata and controls

323 lines (297 loc) · 8.65 KB
Raw

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.