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 effects (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.bold().applied_to("text")).
• Immutability: All styling types are immutable and most implement Copy.

Installation

Run this command in your project directory:

cargo add fluent-ansi

Usage

The primary way to use fluent-ansi is through its fluent API. You can combine colors and effecs 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.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::*, ColorTarget, Style, TargetedColor};

let style: Style = Style::new().set(Effect::Bold, true).set(ColorTarget::Foreground, Some(Color::RED.to_color()));
let style: Style = Style::new().set_effect(Effect::Bold, true).set_color(ColorTarget::Foreground, Some(Color::RED));
let style: Style = Style::new().add(Effect::Bold).add(TargetedColor::new(Color::RED, ColorTarget::Foreground));
let style: Style = Style::new().effect(Effect::Bold).color(TargetedColor::new(Color::RED, ColorTarget::Foreground));
let style: Style = Style::new().bold().fg(Color::RED);
let style: Style = Effect::Bold.fg(Color::RED);
let style: Style = Color::RED.bold();

Styling Elements

Effects

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

use fluent_ansi::prelude::*;

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

Underline Effects

In addition to standard effects, specific underline effects are supported (and are mutually exclusive):

use fluent_ansi::prelude::*;

assert_eq!(format!("{}", Effect::CurlyUnderline), "\x1b[4:3m");
assert_eq!(format!("{}", Style::new().dashed_underline()), "\x1b[4:5m");

Colors

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

use fluent_ansi::prelude::*;

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


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

Demo

Execute this to see a demo of ANSI formatting in action:

cargo run --example demo

Its source is in examples/demo if you want to check it.

Changelog

v0.4.0

• Huge refactor to define common methods with macros instead of traits
• Add demo application as example
• Breaking change: rename UnderlineStyle to UnderlineEffect and the Underline singleton to UnderlineStyle
• Breaking change: make the underline effects names uniform regarding the solid variant
• Breaking change: rename the unset() method to remove() and review method groups and docs

v0.3.0

• Use colors with Foreground as default target
• Add underline effects and color
• Extract trait methods tests into macros
• Move some items to their own modules
• Review Effect variants
• Rename some types

v0.2.1

• Fix version in the README file

v0.2.0

• Define blanket implementation of ColorKind instead of implementing for each color type
• Turn a few methods const
• Rename Forma to Style

v0.1.0

• Initial version

License

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