colorz

A zero-alloc, no_std compatible way of coloring your terminal outputs!

This is a "fork" of owo-colors with more features.

use colorz::{Colorize, xterm};

// will print `hello world` in red
println!("{}", "hello world".red());
// will print `hello world` on a red background
println!("{}", "hello world".on_red());
// will print `hello world` on a with an Aqua underline
println!("{}", "hello world".underline_color(xterm::Aqua).underline());

Features:

• Format using any std formatting trait, (Display, Debug, etc.)
• Format using a custom format function (StyledValue::fmt_with)
• Per-value conditional styling via StyledValue::stream
• Global conditional styling for all StyledValues via
  • colorz::mode
  • strip-colors feature flag
• zero-dependency by default
• Standard names for Ansi, Xterm, and Css colors
• Rgb color support
• Ansi modifier (bold, italics, underline)
• Multi-color support (foreground, background, and underline color)
• mostly a drop-in replacement for owo-colors for simple cases
  • (some xterm color names may be different, some methods are called a little differently)
• compile-time selection of xterm colors by color code
• compile-time style construction
• compile-time style value construction
• NO_COLOR/ALWAYS_COLOR environment variables: colorz::mode::{Mode::from_env, set_coloring_mode_from_env}
  • requires std or supports-color feature

Feature Flags

This crate has a few feature flags

• strip-colors - removes all coloring for StyledValue's formatting methods
• std - this enables the standard library (since this library is no_std by default)
• supports-color - this enables the supports-color crate (which also uses the std library)

None of the feature is enabled by default. And they should only be turned on by the final binary crate.

If these features are turned off, then only the global mode settings is respected, and no stream-based color detection is done.

if strip-colors is enabled, then colorz::mode::get_coloring_mode will always return Mode::Never, and StyledValue will never be colored.

else if supports-color is enabled, then the supports-color crate is used to detect if ANSI, Xterm or RGB colors are supports. If a StyledValue tries to use any unsupported color types, then it will not do any coloring. For example, if you terminal doesn't support Xterm colors, and you write

use colorz::{Colorize, xterm};

println!("{}", "hello world".fg(xterm::Red));

Then you will see hello world in your default terminal color.

finally if std is enabled, then if the stream is a terminal then all coloring types will be used. and if the stream isn't a terminal then no coloring will be chosen.

Coloring Mode

There are many ways to specify the coloring mode for colorz, and it may not be obvious how they interact, so here is a precedence list. To figure out how colorz chooses to colorz, go down the list, and the first element that applies will be selected.

• if the feature flag strip-colors is enabled -> NO COLORING
• if the global coloring mode is Mode::Always -> DO COLOR
• if the global coloring mode is Mode::NEVER -> NO COLORING
• if the per-value stream if set to
  • Stream::AlwaysColor -> DO COLOR
  • Stream::NeverColor -> NO COLORING
  • Stream::Stdout/Stream::Stderr -> detect coloring using std or support-color (see docs on feature flags for details)
• if global stream is set to
  • Stream::AlwaysColor -> DO COLOR
  • Stream::NeverColor -> NO COLORING
  • Stream::Stdout/Stream::Stderr -> detect coloring using std or support-color (see docs on feature flags for details)

The global stream is always set to one of the possible Stream values, so one option on the list will always be chosen.

NOTE that setting the coloring mode from the environment sets the global coloring mode, so either the second or third option on the list.

NOTE that the coloring mode only affects StyledValue (which includes all outputs of the Colorize trait). Using Style::apply/Style::clear directly will not respect the coloring mode, and can be used to force coloring regardless of the current coloring mode. You can use Style::should_color to detect if a given style should be used based on the current coloring mode.

use colorz::{Style, xterm, mode::Stream};

let style = Style::new().fg(xterm::Aquamarine);

if style.should_color(Stream::AlwaysColor) {
    println!("{}style if global is set{}", style.apply(), style.clear());
}

if style.should_color(None) {
    println!("{}style if global is set or default stream is set{}", style.apply(), style.clear());
}

Examples

Format any value

use colorz::{Colorize, xterm, css};

#[derive(Debug)]
struct MyType {
    value: String,
}

// will print `hello world` in red
println!("{}", "hello world".red());
// will print `100` on an aquamarine background
println!("{}", 100.bg(css::Aquamarine));
// will print `hello world` on a with an Aqua underline
println!("{:?}", MyType { value: "hello world".into() }.underline_color(xterm::Aqua).underline());

With conditional formatting per value

use colorz::{Colorize, xterm, mode::Stream::*};

// will print `hello world` in red if Stdout points to a terminal
println!("{}", "hello world".red().stream(Stdout));

Easily turn it off at any time

use colorz::{Colorize, xterm, mode::Stream::*};

colorz::mode::set_coloring_mode(colorz::mode::Mode::Never);

// doesn't style the value
println!("{}", "hello world".red());

assert_eq!(format!("{}", "hello world".red()), "hello world");

Create compile time style sheets

use colorz::{Colorize, Style, Effect, xterm};

const MY_STYLE: Style = Style::new()
    .fg(xterm::ForestGreen)
    .effects_array([Effect::Italic, Effect::Bold])
    .const_into_runtime_style();

// styles `my text` in forest green with italics and bold
println!("{}", "my text".style_with(MY_STYLE));