ansi-align

A Rust library for aligning text with proper support for ANSI escape sequences and Unicode characters.

Features

ANSI-aware alignment: Correctly handles text containing ANSI escape sequences (colors, formatting)
Unicode support: Properly calculates display width for Unicode characters including CJK characters
Multiple alignment options: Left, center, and right alignment
Customizable: Configure split strings and padding characters
Performance optimized: Single-pass processing with efficient memory usage
Type-safe: Uses a Width type for display width values

Installation

Add this to your Cargo.toml:

[dependencies]

ansi-align = "0.1.0"

Quick Start

use ansi_align::{ansi_align, center, left, right};

// Basic alignment (defaults to center)
let text = "hello\nworld";
let centered = ansi_align(text);

// Specific alignment functions
let left_aligned = left("short\nlonger line");
let centered = center("short\nlonger line");
let right_aligned = right("short\nlonger line");

Advanced Usage

Custom Options

use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};

let text = "line1|line2|line3";
let options = AlignOptions::new(Alignment::Right)
    .with_split("|")           // Custom line separator
    .with_pad('.');            // Custom padding character

let result = ansi_align_with_options(text, &options);
// Result: "..line1|..line2|..line3"

ANSI Escape Sequences

The library correctly handles ANSI escape sequences by ignoring them during width calculation:

use ansi_align::center;

let colored_text = "\x1b[31mred\x1b[0m\n\x1b[32mgreen text\x1b[0m";
let aligned = center(colored_text);
// ANSI codes are preserved but don't affect alignment

Unicode Characters

Wide Unicode characters (like CJK) are handled correctly:

use ansi_align::center;

let unicode_text = "古\n古古古";
let aligned = center(unicode_text);
// Properly accounts for double-width characters

API Reference

Core Functions

ansi_align(text: &str) -> String - Center align text (default)
ansi_align_with_options(text: &str, opts: AlignOptions) -> String - Align with custom options
left(text: &str) -> String - Left align (no-op, returns original)
center(text: &str) -> String - Center align text
right(text: &str) -> String - Right align text

Types

`Alignment`

pub enum Alignment {
    Left,
    Center,
    Right,
}

`Width`

A type-safe wrapper for display width values:

let width = Width::new(42);
let value = width.get(); // Returns usize

`AlignOptions`

Configuration for alignment behavior:

pub struct AlignOptions {
    pub align: Alignment,    // Alignment type
    pub split: String,       // Line separator (default: "\n")
    pub pad: char,          // Padding character (default: ' ')
}

Builder methods:

AlignOptions::new(align: Alignment) - Create with alignment
.with_split(split: impl Into<String>) - Set custom line separator
.with_pad(pad: char) - Set custom padding character

Performance

Left alignment: Optimized as a no-op, returns input unchanged
Single pass: Text is processed once for optimal performance
Efficient padding: Uses optimized string creation for different padding sizes
Memory conscious: Minimal allocations with capacity pre-calculation

CLI Tool

The crate includes a beautiful CLI tool for interactive text alignment:

# Run the demo to see all features

cargo run --example cli_tool -- --demo


# Align text from command line

cargo run --example cli_tool -- "Hello\nWorld\nRust" --align center --border


# Read from stdin

echo -e "Line 1\nLonger Line 2\nShort" | cargo run --example cli_tool -- - --align right --pad '.'


# Read from file

cargo run --example cli_tool -- --file examples/sample.txt --align center --border


# Custom separator

cargo run --example cli_tool -- "Name|Age|City" --split "|" --align center --pad '_'

CLI Features

🎨 Beautiful output with optional colorful borders
📁 Multiple input sources: command line, stdin, or file
🌈 ANSI color preservation in aligned output
🌏 Unicode support including CJK characters
⚙️ Customizable padding characters and line separators
📋 Interactive demo showing all capabilities

Examples

Simple Menu Alignment

use ansi_align::center;

let menu = "Home\nAbout Us\nContact\nServices";
let aligned_menu = center(menu);
println!("{}", aligned_menu);

Code Block Alignment

use ansi_align::right;

let code = "if x:\n    return y\nelse:\n    return z";
let aligned_code = right(code);
println!("{}", aligned_code);

Custom Separator and Padding

use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};

let data = "Name|Age|City";
let options = AlignOptions::new(Alignment::Center)
    .with_split("|")
    .with_pad('_');

let result = ansi_align_with_options(data, options);

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE)
MIT license (LICENSE-MIT)

at your option.

ansi-align 0.2.0