ansi-align 0.2.0

# ansi-align


[![Crates.io](https://img.shields.io/crates/v/ansi-align.svg)](https://crates.io/crates/ansi-align)
[![Documentation](https://docs.rs/ansi-align/badge.svg)](https://docs.rs/ansi-align)
[![License](https://img.shields.io/crates/l/ansi-align.svg)](https://github.com/sabry-awad97/ansi-align#license)
[![Build Status](https://img.shields.io/github/actions/workflow/status/sabry-awad97/ansi-align/ci.yml?branch=main)](https://github.com/sabry-awad97/ansi-align/actions)

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`:

```toml
[dependencies]
ansi-align = "0.1.0"
```

## Quick Start


```rust
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


```rust
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:

```rust
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:

```rust
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`


```rust
pub enum Alignment {
    Left,
    Center,
    Right,
}
```

#### `Width`


A type-safe wrapper for display width values:

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

#### `AlignOptions`


Configuration for alignment behavior:

```rust
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:

```bash
# 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


```rust
use ansi_align::center;

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

### Code Block Alignment


```rust
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


```rust
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](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.