# 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:
```bash
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`.
```rust
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:
```rust
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:
```rust
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):
```rust
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.
```rust
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:
```bash
cargo run --example demo
```
Its source is in [`examples/demo`](./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](LICENSE) file for details.