farben 0.5.0 - Docs.rs

banner logo

Color your terminal without typing whatever the heck '\x1b[31m' is.

[!WARNING] Farben, in this current state, is unstable. It only has a few public interfaces, unfinished features, and is experimental. I do not recommend using it in production, at least not yet.

What Is Farben

Look at the tagline up there ^

Documentation

User Guide: https://razkar-studio.github.io/farben
API Reference: https://docs.rs/farben

Usage

// Using no features
use farben::*;

style!("error", "[bold underline red]");
style!("warn",  "[bold yellow]");

cprintln!("[error]error: [/]Something bad happened.");
cprintln!("[warn]warn: [/]This looks suspicious.");
cprintln!("[bg:blue fg:white]White on blue!");

let name = "Razkar";
cprintln!("[bold green]Hello, {}!", name);

cprintb!("[red]This bleeds ");
cprintln!("into this.");

// Using the "compile" feature
use farben::*;

style!("error", "[bold underline red]");

cprintln!("[error]error: [/]Something bad happened."); // compile-time validation
cprintln!("[bg:blue fg:white]White on blue!");

let name = "Razkar";
cprintln!("[bold green]Hello, {}!", name);

cprintb!("[red]This bleeds ");
cprintln!("into this.");

Features

Markup-like Syntax: Easy to read, write, and powerful when used.
Zero required runtime dependencies: Only farben-core as a path dependency, Farben introduces no complicated dependency tree.
Opt-in Compile-time Processing: Validate and process markup at compile time with no runtime overhead, via the compile feature flag.
Complete Toolkit: Named colors, ANSI256, RGB, emphasis styles, style chaining, foreground and background support.
Drop-in Print Macros: cprint!, cprintln!, cprintb!, and cprintbln! work just like print! and println! but with markup support.
Bleed Variants: cprintb!, cprintbln!, colorb(), and colorb!() skip the trailing reset, letting styles carry forward across multiple calls.
User-defined styles: Define your own tags with style!() that expand to any combination of supported tags.
- Features shouldn't be forced upon you: Opt-out from user-defined styles at anytime, making Farben lighter and easier to work with.
- Format using prefix!(): Your styles, your rules. Make a prefix to go along with it, calling your custom style will resolve to the prefix you define.

Syntax

Tags are written as [tag] and apply from that point forward. Multiple tags can be combined in a single bracket: [bold red].

[!WARNING] Spaces inside ansi() and rgb() are not supported at the moment.

Tag	Description
`[red]`, `[blue]`, ...	Named colors (black, red, green, yellow, blue, magenta, cyan, white)
`[fg:red]`, `[bg:red]`	Explicit foreground/background color — works with all color formats
`[rgb(r,g,b)]`	24-bit RGB color
`[ansi(n)]`	256-color palette index
`[bold]`, `[italic]`, `[dim]`, `[underline]`, `[blink]`, `[strikethrough]`	Emphasis styles
`[/]`	Reset all styles
`\\[`	Escaped bracket, treated as literal `[`
`[yourname]`	User-defined style via `style!()`

Error Handling

color() panics on invalid markup. For graceful error handling, use try_color():

use farben::try_color;

match try_color("[invalid]oops") {
    Ok(s) => println!("{s}"),
    Err(e) => eprintln!("Error: {e}"),
}

Contributing

Contributions are welcome! Feel free to submit a Pull Request.

License

This project is protected under the RazkarStudio Permissive License (RSPL). See LICENSE.md for more details.