Coloring and Printing

Farben gives you a few ways to color text and print it. Here's when to use each one.

Picking a Color Format

Start with named colors. They're readable, short, and cover the basics.

cprintln!("[red]Error! [green]Success! [yellow]Warning!");

Reach for ANSI256 when you want more variety but don't need exact control. A color chart is your best friend here.

cprintln!("[ansi(208)]A warm orange. [ansi(27)]A vivid blue.");
cprintln!("Orange is an awesome way to use ANSI256 since named colors don't have them.")

Use RGB when you have a specific color in mind, like a brand color or a precise shade.

cprintln!("[rgb(255,90,0)]Fancy Orange (TM).");
cprintln!("That orange looks [italic]fancy...");

Use HSL, HSV, Hex, or the other advanced formats when you need a specific color model.

cprintln!("[hsl(45,80,60)]Warm gold.");
cprintln!("[#ff8800]Orange via hex.");

TIP

When in doubt, named colors first. They're the most readable at a glance and work everywhere.

cstr!() vs try_color() vs cformat!() vs cprintln!()

Use cstr!() as the default choice for producing a colored string. It works in all modes, with or without format arguments, and with or without the compile feature.

use farben::prelude::*;

// Simple colored string, stored for later
let status = cstr!("[green]online");
println!("{status}");

// With interpolation
let path = "/some/file.txt";
let msg = cstr!("[red]File not found: [/]{path}");

Use try_color() when you need to handle markup errors explicitly from an untrusted source.

use farben::try_color;

match try_color("[red]Something went wrong!") {
    Ok(s) => log::error!("{s}"),
    Err(e) => log::error!("markup error: {e}"),
}

Use cformat!() when you need precise format specifiers (e.g. {:.2}) or want to build a string inline with the full format!() syntax.

let msg = cformat!("[green]Score: {:.2}", 95.123);

Use cprintln!() for everything else. It's the shortest path from markup to terminal output.

cprintln!("[green]Done in {}ms.", elapsed);

TIP

cprint!() works the same as cprintln!() but without the trailing newline, useful when you're building output incrementally.

Idiomatic Ways to Bleed

Idioms, idioms. There's a ton of things that have their own idioms, even bleeding!

The main use case for bleeding is to separate printed text into multiple lines that share the same style. If that's not your use case for bleeding, I don't know what is.

To elegantly bleed appropriately, we declare the style first, and then let the text below use that style. Like the following:

cprintb!("[italic blue]"); // Declare the style.
cprintb!("I'm blue and I'm italian. This is a description text yadda yadda, "); // Leading space for printing in-line
cprintb!("Lorem ipsum dolor sit amet. Consectur adipiscing elit. What does that mean? ");
cprintln!("Final description text uses `cprintln!` to finally reset the style.");

cprintln!("\nGuys, what did I miss?");

INFO

This is the idiomatic way to use bleeds. It doesn't matter if you use newlines or not, but declaring the style and then using an in-line print is the correct way.

Writer Variants

Sometimes you need to write to somewhere other than stdout or stderr. Maybe a file, a String, or a custom buffer. Farben has you covered with writer variants that work with any Write implementor.

use farben::prelude::*;
use std::io::Write;

// Write to a String
let mut output = String::new();
cwriteln!(output, "[green]Success![/] operation completed.");
cwrite!(output, "[yellow]Warning: [/]{} items remaining.", count);

// Write to a file
let mut file = std::fs::File::create("log.txt")?;
cwriteb!(file, "[red]ERROR: ");
cwriteln!(file, "{}[/]", error_message);

All four variants are available:

• cwrite! writes without a newline, appends reset
• cwriteln! writes with a trailing newline, appends reset
• cwriteb! writes without a newline, does not reset (bleeds)
• cwritebln! writes with a newline, does not reset (bleeds)

TIP

The writer variants use the exact same markup processing as the stdout macros. They support all colors, emphasis styles, RGB, ANSI256, HSL, hex, and everything else Farben offers.