Crate ansi_escape_sequences 

ANSI Regex - Professional ANSI Escape Sequence Processing

A high-performance, zero-allocation Rust library for detecting, matching, and processing ANSI escape sequences in terminal text. This crate provides comprehensive support for ANSI/VT100 terminal control sequences with optimized regex patterns and convenient APIs.

🚀 Features

• High Performance: Pre-compiled regex patterns with zero-allocation static references
• Comprehensive Coverage: Supports CSI, OSC, and other ANSI escape sequences
• Flexible API: Multiple matching modes (global, first-only, owned)
• Zero Dependencies: Only depends on the regex crate
• Memory Efficient: Uses LazyLock for optimal memory usage
• Thread Safe: All operations are thread-safe and can be used in concurrent environments

📖 ANSI Escape Sequences Overview

ANSI escape sequences are special character sequences used to control terminal formatting, cursor positioning, and other terminal behaviors. They typically start with the ESC character (\u{001B} or \x1B) followed by specific control characters.

Common ANSI Sequence Types:

• CSI (Control Sequence Introducer): ESC[ followed by parameters and a final character
  • Example: \u{001B}[31m (red foreground color)
  • Example: \u{001B}[2J (clear screen)
• OSC (Operating System Command): ESC] followed by data and terminated by ST
  • Example: \u{001B}]0;Window Title\u{0007} (set window title)
• C1 Control Characters: Direct 8-bit control characters like \u{009B} (CSI)

🔧 Quick Start

Basic Usage

use ansi_escape_sequences::{ansi_regex, strip_ansi, has_ansi};

// Check if text contains ANSI sequences
let colored_text = "\u{001B}[31mHello\u{001B}[0m World";
assert!(has_ansi(colored_text));

// Strip all ANSI sequences
let clean_text = strip_ansi(colored_text);
assert_eq!(clean_text, "Hello World");

// Get a regex for custom processing
let regex = ansi_regex(None);
let matches: Vec<_> = regex.find_iter(colored_text).collect();
assert_eq!(matches.len(), 2); // Found 2 ANSI sequences

Advanced Configuration

use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};

// Match only the first ANSI sequence
let options = AnsiRegexOptions::new().only_first();
let regex = ansi_regex(Some(options));

// Global matching (default behavior)
let options = AnsiRegexOptions::new().global();
let regex = ansi_regex(Some(options));

// Find all ANSI sequences with detailed information
let colored_text = "\u{001B}[31mHello\u{001B}[0m World";
let sequences = AnsiRegexOptions::find_ansi_sequences(colored_text);
for seq in sequences {
    println!("Found ANSI sequence: {:?} at position {}",
             seq.as_str(), seq.start());
}

Performance-Optimized Usage

use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};

// Use pre-compiled static regex for best performance
let global_regex = ansi_regex(None); // For finding all matches
let first_regex = ansi_regex(Some(AnsiRegexOptions::new().only_first())); // For first match only

// Process large amounts of text efficiently
let large_text = "\u{001B}[31mRed\u{001B}[0m text"; // Your large text with ANSI codes
let clean_text = global_regex.replace_all(large_text, "");
assert_eq!(clean_text, "Red text");

🎯 Use Cases

• Log Processing: Clean ANSI codes from log files for storage or analysis
• Terminal Emulators: Parse and process terminal control sequences
• Text Processing: Extract plain text content from terminal-formatted strings
• CLI Tools: Handle colored output in command-line applications
• Web Applications: Convert terminal output for web display
• Testing: Validate terminal output in automated tests

⚡ Performance Notes

• Static regex compilation happens only once per pattern type
• Zero-allocation operations when using static references
• Optimized regex patterns for common ANSI sequence formats
• Thread-safe operations suitable for concurrent processing

🔍 Supported ANSI Sequences

This library recognizes and matches:

• CSI sequences: ESC[ + parameters + final byte
• OSC sequences: ESC] + data + string terminator
• C1 control characters: Direct 8-bit equivalents
• String terminators: BEL (\u{0007}), ESC\ (\u{001B}\u{005C}), ST (\u{009C})

📚 Examples

Structs

AnsiRegexOptions

Configuration options for ANSI regex pattern matching behavior

Enums

AnsiRegexError

Comprehensive error types for ANSI regex operations

Functions

ansi_regex

Create a high-performance regex pattern for matching ANSI escape sequences

ansi_regex_owned

Create an owned copy of the ANSI regex

has_ansi

Check if a string contains any ANSI sequences

strip_ansi

Remove all ANSI sequences from a string