Crate cli_boxes 

CLI Boxes

A high-performance Rust library providing Unicode box-drawing characters for creating beautiful CLI interfaces. Perfect for terminal applications, CLI tools, and text-based user interfaces.

🎯 Features

• 9 Beautiful Box Styles: From elegant single-line to decorative arrows
• Unicode & ASCII Support: Full Unicode compliance with ASCII fallback
• Zero-Cost Abstractions: Compile-time constants and zero-allocation parsing
• Type Safety: Strong typing prevents incorrect usage
• Ergonomic Builder API: Fluent interface for custom box creation
• String Parsing: Parse styles from configuration files or user input
• Serde Integration: Optional serialization support (feature-gated)
• Comprehensive Testing: 100% test coverage with extensive edge case handling

📦 Box Styles

Style	Preview	Use Case
SINGLE	┌─┐│┘─└│	General purpose, clean appearance
DOUBLE	╔═╗║╝═╚║	Emphasis, important content
ROUND	╭─╮│╯─╰│	Modern, soft appearance
BOLD	┏━┓┃┛━┗┃	Strong emphasis, headers
SINGLE_DOUBLE	╓─╖║╜─╙║	Mixed style, unique look
DOUBLE_SINGLE	╒═╕│╛═╘│	Alternative mixed style
CLASSIC	+─+|+─+|	ASCII compatibility, legacy systems
ARROW	↘↓↙←↖↑↗→	Decorative, special effects
NONE		Invisible borders, spacing

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
cli-boxes = "0.1.0"

Basic Usage

use cli_boxes::{BoxChars, BorderStyle};

// Create a simple box
let box_chars = BoxChars::SINGLE;
println!("{}{}{}",
    box_chars.top_left,
    box_chars.top.to_string().repeat(10),
    box_chars.top_right
);
println!("{}          {}", box_chars.left, box_chars.right);
println!("{}{}{}",
    box_chars.bottom_left,
    box_chars.bottom.to_string().repeat(10),
    box_chars.bottom_right
);
// Output:
// ┌──────────┐
// │          │
// └──────────┘

Advanced Usage with Builder Pattern

use cli_boxes::BoxChars;

// Create custom box with builder pattern
let custom = BoxChars::builder()
    .corners('●')
    .horizontal('═')
    .vertical('║')
    .top_left('╔')  // Override specific corner
    .build();

// Asymmetric design
let fancy = BoxChars::builder()
    .top_left('╭').top('─').top_right('╮')
    .left('│').right('│')
    .bottom_left('└').bottom('─').bottom_right('┘')
    .build();

Dynamic Style Selection

use cli_boxes::{BorderStyle, BoxChars};

// Parse from configuration
let style: BorderStyle = "double".parse().unwrap();
let box_chars = style.chars();

// Iterate through all styles
for style in BorderStyle::all() {
    let chars = style.chars();
    println!("{}: {}", style, chars);
}

🎨 Real-World Examples

Creating a Status Box

use cli_boxes::BoxChars;

fn create_status_box(message: &str, width: usize) -> String {
    let box_chars = BoxChars::DOUBLE;
    let padding = width.saturating_sub(message.len() + 2);
    let left_pad = padding / 2;
    let right_pad = padding - left_pad;
     
    format!(
        "{}{}{}\n{}{}{}{}{}\n{}{}{}",
        box_chars.top_left,
        box_chars.top.to_string().repeat(width),
        box_chars.top_right,
        box_chars.left,
        " ".repeat(left_pad),
        message,
        " ".repeat(right_pad),
        box_chars.right,
        box_chars.bottom_left,
        box_chars.bottom.to_string().repeat(width),
        box_chars.bottom_right
    )
}

Configuration-Driven Boxes

use cli_boxes::{BorderStyle, BoxChars};
use std::collections::HashMap;

fn get_box_for_level(level: &str) -> BoxChars {
    let styles: HashMap<&str, BorderStyle> = [
        ("info", BorderStyle::Single),
        ("warning", BorderStyle::Bold),
        ("error", BorderStyle::Double),
        ("success", BorderStyle::Round),
    ].iter().cloned().collect();
     
    styles.get(level)
        .map(|s| s.chars())
        .unwrap_or(BoxChars::CLASSIC)
}

⚡ Performance

This library is designed for maximum performance:

• Zero Allocations: String parsing uses byte-level comparison without heap allocation
• Compile-Time Constants: All predefined styles are const and computed at compile time
• Minimal Dependencies: Only strum for enum iteration, optional serde for serialization
• Small Memory Footprint: BoxChars is only 32 bytes (8 × 4-byte chars)

🔧 Optional Features

Serde Support

Enable serialization support:

[dependencies]
cli-boxes = { version = "0.1.0", features = ["serde"] }

use cli_boxes::{BoxChars, BorderStyle};
use serde_json;

let style = BorderStyle::Double;
let json = serde_json::to_string(&style).unwrap();
let deserialized: BorderStyle = serde_json::from_str(&json).unwrap();

🛡️ Error Handling

The library provides helpful error messages for invalid input:

use cli_boxes::BorderStyle;

match "invalid_style".parse::<BorderStyle>() {
    Ok(style) => println!("Parsed: {}", style),
    Err(e) => println!("{}", e),
    // Output: Invalid border style: 'invalid_style'.
    // Did you mean one of: none, single, double, round, bold,
    // single_double, double_single, classic, arrow?
}

🔗 Related Crates

• tui - Terminal user interface library
• crossterm - Cross-platform terminal manipulation
• console - Terminal and console abstraction

📄 License

This project is licensed under either of

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

at your option.

Structs

BorderStyleIter

An iterator over the variants of BorderStyle

BoxChars

A collection of Unicode characters used for drawing boxes in CLI applications.

BoxCharsBuilder

Builder for creating custom BoxChars with a fluent, type-safe API.

Enums

BorderStyle

Available box drawing styles with semantic meaning and use cases.

ParseBorderStyleError

Error type for parsing BorderStyle from string.