fluent-ansi

fluent-ansi is a Rust library designed to handle ANSI escape sequences for the terminal. It provides a modular, composable, and fluent API for styling text with colors and flags (like bold, italic).

Key Features

no_std Compatible: Designed to work without the standard library, relying on core::fmt::Display.
Fluent API: Allows method chaining (e.g., Color::RED.in_fg().bold().applied_to("text")).
Immutability: All styling types are immutable and most implement Copy.

Installation

Add this to your Cargo.toml:

[dependencies]
fluent-ansi = "0.2.1"

Usage

The primary way to use fluent-ansi is through its fluent API. You can combine colors and flags to create a Style, and then apply it to any type that implements Display.

use fluent_ansi::{prelude::*, Style, Styled};

// Create a style
let style: Style = Color::RED.in_fg().bold();

// Apply it to some content
let styled: Styled<&str> = style.applied_to("Some content");

// Print it directly
println!("{}", styled);

// Or get the string with escape sequences
let content_with_escape_sequences = format!("{}", styled);
assert_eq!(content_with_escape_sequences, "\x1b[1;31mSome content\x1b[0m");

Composable API

There are several ways to reach the same result, depending on your preference:

use fluent_ansi::{prelude::*, ColorInAPlane, Style, Plane};

let stl: Style = Style::new().set(Flag::Bold, true).set(Plane::Foreground, Some(Color::RED.to_color()));
let stl: Style = Style::new().set_flag(Flag::Bold, true).set_color(Plane::Foreground, Some(Color::RED));
let stl: Style = Style::new().add(Flag::Bold).add(ColorInAPlane::new(Color::RED, Plane::Foreground));
let stl: Style = Style::new().flag(Flag::Bold).color(ColorInAPlane::new(Color::RED, Plane::Foreground));
let stl: Style = Style::new().bold().fg(Color::RED);
let stl: Style = Flag::Bold.fg(Color::RED);
let stl: Style = Color::RED.in_fg().bold();

Styling Elements

Flags

Flags can be used on their own, combined with other elements, or applied to content:

use fluent_ansi::prelude::*;

assert_eq!(format!("{}", Flag::Bold), "\x1b[1m");
assert_eq!(format!("{}", Flag::Bold.applied_to("Some content")), "\x1b[1mSome content\x1b[0m");

Colors

The library supports Basic (3/4-bit), 8-bit (256 colors), and RGB (TrueColor) colors. Colors must be associated with a Plane (Foreground or Background), and can also be applied to some content.

use fluent_ansi::prelude::*;

let red_in_foreground = Color::RED.in_fg();
assert_eq!(format!("{red_in_foreground}"), "\x1b[31m");
assert_eq!(format!("{}", red_in_foreground.applied_to("Some content")), "\x1b[31mSome content\x1b[0m");


let blue_in_background = Color::BLUE.in_bg();
assert_eq!(format!("{blue_in_background}"), "\x1b[44m");
assert_eq!(format!("{}", blue_in_background.applied_to("Some content")), "\x1b[44mSome content\x1b[0m");

License

This project is licensed under the MIT License - see the LICENSE file for details.

fluent-ansi 0.2.1