ansi_escape_sequences/

lib.rs

//! # ANSI Regex - Professional ANSI Escape Sequence Processing
//!
//! [![Crates.io](https://img.shields.io/crates/v/ansi-regex.svg)](https://crates.io/crates/ansi-regex)
//! [![Documentation](https://docs.rs/ansi-regex/badge.svg)](https://docs.rs/ansi-regex)
//! [![License](https://img.shields.io/crates/l/ansi-regex.svg)](LICENSE)
//!
//! 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
//!
//! ```rust
//! 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
//!
//! ```rust
//! 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
//!
//! ```rust
//! 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

#![deny(missing_docs)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::nursery)]

use regex::Regex;
use std::sync::LazyLock;

/// Comprehensive error types for ANSI regex operations
///
/// This enum represents all possible errors that can occur when working with ANSI regex patterns.
/// Currently, the primary error case is regex compilation failure, but this enum is designed
/// to be extensible for future error types.
///
/// # Examples
///
/// ```rust
/// use ansi_escape_sequences::AnsiRegexError;
///
/// // Errors are typically handled internally, but can be exposed in custom implementations
/// match some_regex_operation() {
///     Ok(result) => println!("Success: {:?}", result),
///     Err(AnsiRegexError::RegexCompilation(e)) => {
///         eprintln!("Regex compilation failed: {}", e);
///     }
/// }
/// # fn some_regex_operation() -> Result<(), AnsiRegexError> { Ok(()) }
/// ```
#[derive(Debug)]
pub enum AnsiRegexError {
    /// Failed to compile the internal regex pattern
    ///
    /// This error occurs when the underlying regex engine fails to compile the ANSI pattern.
    /// This should be extremely rare in normal usage as the patterns are pre-validated.
    RegexCompilation(regex::Error),
}

impl std::fmt::Display for AnsiRegexError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::RegexCompilation(err) => {
                write!(f, "Failed to compile regex pattern: {err}")
            }
        }
    }
}

impl std::error::Error for AnsiRegexError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::RegexCompilation(err) => Some(err),
        }
    }
}

impl From<regex::Error> for AnsiRegexError {
    fn from(err: regex::Error) -> Self {
        Self::RegexCompilation(err)
    }
}

/// Configuration options for ANSI regex pattern matching behavior
///
/// This struct provides a builder-pattern API for configuring how ANSI escape sequences
/// are matched and processed. It allows fine-tuning of the regex behavior for different
/// use cases and performance requirements.
///
/// # Design Philosophy
///
/// The options are designed to be:
/// - **Composable**: Chain method calls for readable configuration
/// - **Immutable**: Each method returns a new instance, preventing accidental mutation
/// - **Zero-cost**: Configuration happens at compile time where possible
/// - **Explicit**: Clear method names that describe the intended behavior
///
/// # Examples
///
/// ## Basic Configuration
///
/// ```rust
/// use ansi_escape_sequences::AnsiRegexOptions;
///
/// // Default configuration (matches all sequences globally)
/// let default_opts = AnsiRegexOptions::new();
///
/// // Match only the first ANSI sequence found
/// let first_only = AnsiRegexOptions::new().only_first();
///
/// // Explicitly configure for global matching (same as default)
/// let global_opts = AnsiRegexOptions::new().global();
/// ```
///
/// ## Method Chaining
///
/// ```rust
/// use ansi_escape_sequences::AnsiRegexOptions;
///
/// // Configuration methods can be chained fluently
/// let opts = AnsiRegexOptions::new()
///     .only_first()  // Find first match only
///     .global();     // Override to global matching
///
/// // The last method in the chain takes precedence
/// assert!(!opts.is_only_first());
/// ```
///
/// ## Performance Considerations
///
/// ```rust
/// use ansi_escape_sequences::AnsiRegexOptions;
///
/// // For processing large texts where you only need to know if ANSI codes exist
/// let check_opts = AnsiRegexOptions::new().only_first();
///
/// // For complete processing where all sequences matter
/// let process_opts = AnsiRegexOptions::new().global();
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AnsiRegexOptions {
    only_first: bool,
}

impl AnsiRegexOptions {
    /// Create new options with default values (global matching)
    #[must_use]
    pub const fn new() -> Self {
        Self { only_first: false }
    }

    /// Configure to match only the first ANSI sequence encountered
    ///
    /// When this option is enabled, the regex will be optimized for finding just the first
    /// ANSI escape sequence in the text. This is more efficient when you only need to detect
    /// the presence of ANSI codes or process the first occurrence.
    ///
    /// # Performance Benefits
    ///
    /// - Stops searching after finding the first match
    /// - Reduces memory allocation for match results
    /// - Ideal for validation and detection use cases
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};
    ///
    /// let text = "\u{001B}[31mRed\u{001B}[0m \u{001B}[32mGreen\u{001B}[0m";
    /// let options = AnsiRegexOptions::new().only_first();
    /// let regex = ansi_regex(Some(options));
    ///
    /// // Only finds the first sequence
    /// let first_match = regex.find(text).unwrap();
    /// assert_eq!(first_match.as_str(), "\u{001B}[31m");
    /// ```
    #[must_use]
    pub const fn only_first(mut self) -> Self {
        self.only_first = true;
        self
    }

    /// Configure to match all ANSI sequences globally (default behavior)
    ///
    /// This is the default matching mode that finds all ANSI escape sequences in the text.
    /// Use this when you need to process, count, or extract all ANSI codes from the input.
    ///
    /// # Use Cases
    ///
    /// - Complete ANSI code removal
    /// - Counting total sequences
    /// - Processing all formatting information
    /// - Converting formatted text to other formats
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};
    ///
    /// let text = "\u{001B}[31mRed\u{001B}[0m \u{001B}[32mGreen\u{001B}[0m";
    /// let options = AnsiRegexOptions::new().global();
    /// let regex = ansi_regex(Some(options));
    ///
    /// // Finds all sequences
    /// let matches: Vec<_> = regex.find_iter(text).collect();
    /// assert_eq!(matches.len(), 4); // 2 color codes + 2 reset codes
    /// ```
    #[must_use]
    pub const fn global(mut self) -> Self {
        self.only_first = false;
        self
    }

    /// Check if configured for first-only matching
    ///
    /// Returns `true` if the options are configured to match only the first ANSI sequence,
    /// `false` if configured for global matching.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_escape_sequences::AnsiRegexOptions;
    ///
    /// let first_only = AnsiRegexOptions::new().only_first();
    /// assert!(first_only.is_only_first());
    ///
    /// let global = AnsiRegexOptions::new().global();
    /// assert!(!global.is_only_first());
    /// ```
    #[must_use]
    pub const fn is_only_first(&self) -> bool {
        self.only_first
    }

    /// Remove all ANSI escape sequences from a string
    ///
    /// This is a high-performance utility function that strips all ANSI escape sequences
    /// from the input text, returning clean, plain text suitable for storage, logging,
    /// or display in non-terminal environments.
    ///
    /// # Performance Characteristics
    ///
    /// - Uses pre-compiled static regex for optimal performance
    /// - Zero-allocation when no ANSI sequences are found
    /// - Efficient string replacement using regex engine optimizations
    ///
    /// # Examples
    ///
    /// ## Basic Usage
    ///
    /// ```rust
    /// use ansi_escape_sequences::strip_ansi;
    ///
    /// let colored = "\u{001B}[31mError:\u{001B}[0m Something went wrong";
    /// let clean = strip_ansi(colored);
    /// assert_eq!(clean, "Error: Something went wrong");
    /// ```
    ///
    /// ## Complex ANSI Sequences
    ///
    /// ```rust
    /// use ansi_escape_sequences::strip_ansi;
    ///
    /// let complex = "\u{001B}[1;31;4mBold Red Underlined\u{001B}[0m Normal";
    /// let clean = strip_ansi(complex);
    /// assert_eq!(clean, "Bold Red Underlined Normal");
    /// ```
    ///
    /// ## Log Processing
    ///
    /// ```rust
    /// use ansi_escape_sequences::strip_ansi;
    ///
    /// let log_line = "[INFO] \u{001B}[32m✓\u{001B}[0m Operation completed successfully";
    /// let clean_log = strip_ansi(log_line);
    /// assert_eq!(clean_log, "[INFO] ✓ Operation completed successfully");
    /// ```
    #[must_use]
    pub(crate) fn strip_ansi(text: &str) -> String {
        ansi_regex_global().replace_all(text, "").into_owned()
    }

    /// Check if a string contains any ANSI escape sequences
    ///
    /// This function provides a fast way to detect the presence of ANSI escape sequences
    /// without extracting or processing them. It's optimized for validation and filtering
    /// use cases where you only need a boolean result.
    ///
    /// # Performance Benefits
    ///
    /// - Early termination on first match found
    /// - No memory allocation for match results
    /// - Optimized regex matching for existence check
    ///
    /// # Examples
    ///
    /// ## Basic Detection
    ///
    /// ```rust
    /// use ansi_escape_sequences::has_ansi;
    ///
    /// assert!(has_ansi("\u{001B}[31mcolored\u{001B}[0m"));
    /// assert!(!has_ansi("plain text"));
    /// ```
    ///
    /// ## Filtering Content
    ///
    /// ```rust
    /// use ansi_escape_sequences::has_ansi;
    ///
    /// let messages = vec![
    ///     "Plain message",
    ///     "\u{001B}[32mSuccess!\u{001B}[0m",
    ///     "Another plain message",
    /// ];
    ///
    /// let colored_messages: Vec<_> = messages
    ///     .iter()
    ///     .filter(|msg| has_ansi(msg))
    ///     .collect();
    ///
    /// assert_eq!(colored_messages.len(), 1);
    /// ```
    ///
    /// ## Conditional Processing
    ///
    /// ```rust
    /// use ansi_escape_sequences::{has_ansi, strip_ansi};
    ///
    /// fn process_text(text: &str) -> String {
    ///     if has_ansi(text) {
    ///         // Process colored text
    ///         strip_ansi(text)
    ///     } else {
    ///         // Pass through plain text unchanged
    ///         text.to_string()
    ///     }
    /// }
    /// ```
    #[must_use]
    pub(crate) fn has_ansi(text: &str) -> bool {
        ansi_regex_global().is_match(text)
    }

    /// Find and extract all ANSI escape sequences from a string
    ///
    /// This function returns detailed information about every ANSI escape sequence found
    /// in the input text, including their positions and content. This is useful for
    /// analysis, conversion, or detailed processing of terminal-formatted text.
    ///
    /// # Return Value
    ///
    /// Returns a `Vec<regex::Match>` where each `Match` contains:
    /// - The matched ANSI sequence as a string slice
    /// - Start and end positions in the original text
    /// - Methods for extracting the sequence content
    ///
    /// # Examples
    ///
    /// ## Basic Sequence Extraction
    ///
    /// ```rust
    /// use ansi_escape_sequences::AnsiRegexOptions;
    ///
    /// let text = "\u{001B}[31mRed\u{001B}[0m Normal \u{001B}[32mGreen\u{001B}[0m";
    /// let sequences = AnsiRegexOptions::find_ansi_sequences(text);
    ///
    /// assert_eq!(sequences.len(), 4);
    /// assert_eq!(sequences[0].as_str(), "\u{001B}[31m"); // Red color
    /// assert_eq!(sequences[1].as_str(), "\u{001B}[0m");  // Reset
    /// assert_eq!(sequences[2].as_str(), "\u{001B}[32m"); // Green color
    /// assert_eq!(sequences[3].as_str(), "\u{001B}[0m");  // Reset
    /// ```
    ///
    /// ## Position Analysis
    ///
    /// ```rust
    /// use ansi_escape_sequences::AnsiRegexOptions;
    ///
    /// let text = "Hello \u{001B}[31mWorld\u{001B}[0m!";
    /// let sequences = AnsiRegexOptions::find_ansi_sequences(text);
    ///
    /// for (i, seq) in sequences.iter().enumerate() {
    ///     println!("Sequence {}: '{}' at position {}-{}",
    ///              i, seq.as_str(), seq.start(), seq.end());
    /// }
    /// ```
    ///
    /// ## Content Reconstruction
    ///
    /// ```rust
    /// use ansi_escape_sequences::AnsiRegexOptions;
    ///
    /// let original = "\u{001B}[1mBold\u{001B}[0m text";
    /// let sequences = AnsiRegexOptions::find_ansi_sequences(original);
    ///
    /// // Reconstruct with different formatting
    /// let mut result = original.to_string();
    /// for seq in sequences.iter().rev() { // Reverse to maintain positions
    ///     let replacement = format!("<ansi:{}>", seq.as_str().len());
    ///     result.replace_range(seq.range(), &replacement);
    /// }
    /// ```
    #[must_use]
    pub fn find_ansi_sequences(text: &str) -> Vec<regex::Match> {
        ansi_regex_global().find_iter(text).collect()
    }
}

impl Default for AnsiRegexOptions {
    fn default() -> Self {
        Self::new()
    }
}

/// Create a high-performance regex pattern for matching ANSI escape sequences
///
/// This is the primary entry point for the library, providing access to pre-compiled,
/// optimized regex patterns for ANSI escape sequence detection and processing. The function
/// returns static references to cached regex instances for maximum performance.
///
/// # Design Philosophy
///
/// - **Zero-allocation**: Returns references to static, pre-compiled regex patterns
/// - **Performance-first**: Optimized patterns with minimal backtracking
/// - **Flexible**: Supports both global and first-match-only modes
/// - **Thread-safe**: All returned regex instances are safe for concurrent use
///
/// # Arguments
///
/// * `options` - Configuration options for regex behavior. Pass `None` for default global matching,
///   or `Some(AnsiRegexOptions)` for custom configuration.
///
/// # Returns
///
/// A reference to a pre-compiled `Regex` that matches ANSI escape sequences according to
/// the specified options. The regex lifetime is `'static`, making it suitable for storage
/// in static variables or long-lived data structures.
///
/// # Performance Characteristics
///
/// - **Compilation**: Happens once per pattern type using `LazyLock`
/// - **Memory**: Minimal overhead with shared static instances
/// - **Matching**: Optimized for common ANSI sequence patterns
/// - **Concurrency**: Thread-safe with no synchronization overhead
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use ansi_escape_sequences::ansi_regex;
///
/// // Default configuration - matches all ANSI sequences
/// let regex = ansi_regex(None);
///
/// let text = "\u{001B}[31mRed text\u{001B}[0m and \u{001B}[32mgreen text\u{001B}[0m";
/// assert!(regex.is_match(text));
///
/// // Count all ANSI sequences
/// let count = regex.find_iter(text).count();
/// assert_eq!(count, 4); // 2 color codes + 2 reset codes
/// ```
///
/// ## Configuration Options
///
/// ```rust
/// use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};
///
/// // Match only the first ANSI sequence (more efficient for detection)
/// let first_only = AnsiRegexOptions::new().only_first();
/// let regex = ansi_regex(Some(first_only));
///
/// let text = "\u{001B}[31mRed\u{001B}[0m \u{001B}[32mGreen\u{001B}[0m";
/// let first_match = regex.find(text).unwrap();
/// assert_eq!(first_match.as_str(), "\u{001B}[31m");
///
/// // Global matching (explicit, same as default)
/// let global = AnsiRegexOptions::new().global();
/// let regex = ansi_regex(Some(global));
/// let all_matches: Vec<_> = regex.find_iter(text).collect();
/// assert_eq!(all_matches.len(), 4);
/// ```
///
/// ## Advanced Processing
///
/// ```rust
/// use ansi_escape_sequences::ansi_regex;
///
/// let regex = ansi_regex(None);
/// let input = "Normal \u{001B}[1;31mBold Red\u{001B}[0m Normal";
///
/// // Extract plain text by removing ANSI codes
/// let clean_text = regex.replace_all(input, "");
/// assert_eq!(clean_text, "Normal Bold Red Normal");
///
/// // Replace ANSI codes with HTML tags
/// let html = regex.replace_all(input, |caps: &regex::Captures| {
///     match caps.get(0).unwrap().as_str() {
///         "\u{001B}[1;31m" => "<span style='color: red; font-weight: bold'>",
///         "\u{001B}[0m" => "</span>",
///         _ => "",
///     }
/// });
/// ```
///
/// ## Performance Optimization
///
/// ```rust
/// use ansi_escape_sequences::{ansi_regex, AnsiRegexOptions};
///
/// // For validation/detection only - use first-match mode
/// let detector = ansi_regex(Some(AnsiRegexOptions::new().only_first()));
/// let text_with_ansi = "\u{001B}[31mRed\u{001B}[0m text";
/// let plain_text = "Plain text";
///
/// // Check for ANSI codes efficiently
/// assert!(detector.is_match(text_with_ansi)); // Stops at first match
/// assert!(!detector.is_match(plain_text));
///
/// // For complete processing - use global mode
/// let processor = ansi_regex(None);
///
/// // Strip all ANSI codes
/// let clean_text = processor.replace_all(text_with_ansi, "").into_owned();
/// assert_eq!(clean_text, "Red text");
/// ```
///
/// ## Static Storage
///
/// ```rust
/// use ansi_escape_sequences::ansi_regex;
/// use std::sync::LazyLock;
///
/// // Store regex in static variable for application-wide use
/// static ANSI_DETECTOR: LazyLock<&'static regex::Regex> = LazyLock::new(|| {
///     ansi_regex(None)
/// });
///
/// fn process_log_line(line: &str) -> String {
///     ANSI_DETECTOR.replace_all(line, "").into_owned()
/// }
/// ```
#[must_use]
pub fn ansi_regex(options: Option<AnsiRegexOptions>) -> &'static Regex {
    let opts = options.unwrap_or_default();

    if opts.is_only_first() {
        ansi_regex_first()
    } else {
        ansi_regex_global()
    }
}

/// Internal ANSI escape sequence pattern constants and utilities
///
/// This module contains the low-level pattern definitions used to construct the ANSI regex.
/// These patterns are based on the ANSI X3.64 standard and VT100/VT220 terminal specifications.
///
/// # Pattern Design
///
/// The patterns are designed to be:
/// - **Comprehensive**: Cover all common ANSI escape sequence types
/// - **Efficient**: Minimize regex backtracking and false positives
/// - **Standards-compliant**: Follow ANSI/ISO terminal control standards
/// - **Unicode-aware**: Handle both 7-bit and 8-bit control sequences
///
/// # Technical Details
///
/// ANSI escape sequences follow these general patterns:
/// - **7-bit sequences**: Start with ESC (0x1B) followed by specific characters
/// - **8-bit sequences**: Use C1 control characters directly (0x80-0x9F range)
/// - **Parameter sequences**: Include numeric parameters separated by semicolons
/// - **String sequences**: Contain arbitrary data terminated by specific sequences
mod patterns {
    /// Valid string terminator sequences for OSC and similar commands
    ///
    /// These terminators are used to end string-based ANSI sequences like OSC (Operating System Command).
    /// The pattern matches any of the three standard terminators:
    ///
    /// - **BEL** (`\u{0007}`): Bell character, traditional terminator
    /// - **ESC\\** (`\u{001B}\u{005C}`): ESC followed by backslash, standard terminator  
    /// - **ST** (`\u{009C}`): String Terminator C1 control character
    ///
    /// # Examples of Usage
    ///
    /// ```text
    /// \u{001B}]0;Window Title\u{0007}        // OSC sequence with BEL terminator
    /// \u{001B}]0;Window Title\u{001B}\u{005C} // OSC sequence with ESC\ terminator
    /// \u{001B}]0;Window Title\u{009C}        // OSC sequence with ST terminator
    /// ```
    pub const STRING_TERMINATORS: &str = r"(?:\u{0007}|\u{001B}\u{005C}|\u{009C})";

    /// ESC (Escape) character - the foundation of 7-bit ANSI sequences
    ///
    /// The ESC character (`\u{001B}` or decimal 27) introduces most ANSI escape sequences.
    /// It's followed by specific characters to form different types of control sequences:
    ///
    /// - **CSI**: ESC + `[` → Control Sequence Introducer
    /// - **OSC**: ESC + `]` → Operating System Command  
    /// - **DCS**: ESC + `P` → Device Control String
    /// - **APC**: ESC + `_` → Application Program Command
    ///
    /// # Historical Context
    ///
    /// The ESC character was chosen because it's outside the printable ASCII range
    /// and unlikely to appear in normal text, making it safe for control purposes.
    pub const ESC: &str = r"\u{001B}";

    /// C1 CSI (Control Sequence Introducer) - 8-bit equivalent of ESC[
    ///
    /// The C1 CSI character (`\u{009B}` or decimal 155) is the 8-bit equivalent
    /// of the two-character sequence ESC[. It directly introduces control sequences
    /// without needing the ESC prefix.
    ///
    /// # Usage Context
    ///
    /// - **7-bit mode**: Uses ESC[ (two characters)
    /// - **8-bit mode**: Uses CSI directly (one character)
    /// - **Compatibility**: Modern terminals support both forms
    ///
    /// # Examples
    ///
    /// ```text
    /// \u{001B}[31m  // 7-bit: ESC[ followed by parameters and final byte
    /// \u{009B}31m   // 8-bit: CSI directly followed by parameters and final byte
    /// ```
    pub const C1_CSI: &str = r"\u{009B}";
}

// Pre-compiled regex patterns for common use cases
static ANSI_REGEX_GLOBAL: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(&build_ansi_pattern()).expect("Failed to compile global ANSI regex")
});

static ANSI_REGEX_FIRST: LazyLock<Regex> = LazyLock::new(|| {
    // For first-only matching, we use the same pattern but the caller will use find() instead of find_iter()
    // The regex itself doesn't need to be different - the behavior difference is in how it's used
    Regex::new(&build_ansi_pattern()).expect("Failed to compile first-only ANSI regex")
});

/// Build the comprehensive ANSI escape sequence regex pattern
///
/// This function constructs the complete regex pattern that matches all supported ANSI escape
/// sequences. The pattern is optimized for performance while maintaining comprehensive coverage
/// of ANSI/VT terminal control sequences.
///
/// # Pattern Architecture
///
/// The regex combines two main pattern types using alternation (`|`):
///
/// 1. **OSC (Operating System Command) sequences**: `ESC]...ST`
/// 2. **CSI (Control Sequence Introducer) sequences**: `ESC[` or C1 CSI + parameters + final byte
///
/// # Technical Implementation
///
/// ## OSC Pattern: `(?:ESC\][\s\S]*?STRING_TERMINATORS)`
///
/// - Matches ESC followed by `]` (OSC introducer)
/// - `[\s\S]*?` matches any character (including newlines) non-greedily
/// - Terminated by any valid string terminator (BEL, ESC\, or ST)
/// - Non-greedy matching prevents over-consumption across multiple sequences
///
/// ## CSI Pattern: `[ESC[C1_CSI][\[\]()#;?]*(?:\d{1,4}(?:[;:]\d{0,4}})*)?[A-PR-TZcf-nq-uy=><~]`
///
/// - `[ESC[C1_CSI]` matches either ESC[ or direct C1 CSI character
/// - `[\[\]()#;?]*` matches optional intermediate characters
/// - `(?:\d{1,4}(?:[;:]\d{0,4}})*)?` matches optional numeric parameters
/// - `[A-PR-TZcf-nq-uy=><~]` matches the final command character
///
/// # Performance Optimizations
///
/// - **Character classes**: Use efficient character class matching where possible
/// - **Non-greedy quantifiers**: Prevent excessive backtracking
/// - **Anchored alternation**: Order patterns by frequency for faster matching
/// - **Bounded repetition**: Limit parameter lengths to prevent `ReDoS` attacks
///
/// # Standards Compliance
///
/// The pattern follows these terminal standards:
/// - **ANSI X3.64**: Core escape sequence definitions
/// - **ISO/IEC 6429**: International standard for control functions
/// - **VT100/VT220**: DEC terminal compatibility
/// - **xterm**: Extended sequence support
///
/// # Examples of Matched Sequences
///
/// ```text
/// \u{001B}[31m           // CSI: Set foreground color to red
/// \u{001B}[2J            // CSI: Clear entire screen
/// \u{001B}[1;1H          // CSI: Move cursor to position 1,1
/// \u{001B}]0;Title\u{0007} // OSC: Set window title
/// \u{009B}31m            // C1 CSI: Set foreground color (8-bit)
/// ```
fn build_ansi_pattern() -> String {
    use patterns::{C1_CSI, ESC, STRING_TERMINATORS};

    // OSC sequences: ESC ] ... ST (non-greedy until first ST)
    // Matches operating system commands like window title setting
    let osc = format!(r"(?:{ESC}\][\s\S]*?{STRING_TERMINATORS})");

    // CSI sequences: ESC[/C1, optional intermediates, params, final byte
    // Matches control sequence introducers for cursor movement, colors, etc.
    let csi = format!(
        r"[{ESC}{C1_CSI}][\[\]()#;?]*(?:\d{{1,4}}(?:[;:]\d{{0,4}})*)?[A-PR-TZcf-nq-uy=><~]"
    );

    // Combine patterns with alternation, OSC first as it's typically longer
    format!("{osc}|{csi}")
}

/// Get a pre-compiled global ANSI regex (matches all occurrences)
///
/// This is equivalent to calling `ansi_regex(None)` but more explicit about the behavior.
/// Use this when you want to find all ANSI sequences in a string.
#[must_use]
fn ansi_regex_global() -> &'static Regex {
    &ANSI_REGEX_GLOBAL
}

/// Get a pre-compiled ANSI regex for first-match usage
///
/// Note: This returns the same regex as `ansi_regex_global()`. The "first only" behavior
/// is achieved by using `find()` instead of `find_iter()` on the regex.
/// This function exists for API consistency and clarity of intent.
#[must_use]
fn ansi_regex_first() -> &'static Regex {
    &ANSI_REGEX_FIRST
}

/// Create an owned copy of the ANSI regex
///
/// Use this when you need ownership of the regex rather than a reference.
/// This is less efficient than using the static references but provides more flexibility.
///
/// # Arguments
///
/// * `options` - Configuration options for the regex pattern
///
/// # Returns
///
/// An owned regex that matches ANSI escape sequences
///
/// # Examples
///
/// ```
/// use ansi_escape_sequences::{ansi_regex_owned, AnsiRegexOptions};
///
/// let regex = ansi_regex_owned(None);
/// assert!(regex.is_match("\u{001B}[31m"));
/// ```
#[must_use]
pub fn ansi_regex_owned(options: Option<AnsiRegexOptions>) -> Regex {
    ansi_regex(options).clone()
}

/// Remove all ANSI sequences from a string
///
/// This is a convenience function equivalent to `AnsiRegexOptions::strip_ansi()`.
///
/// # Arguments
///
/// * `text` - The text to strip ANSI sequences from
///
/// # Returns
///
/// A new string with all ANSI sequences removed
///
/// # Examples
///
/// ```
/// use ansi_escape_sequences::strip_ansi;
///
/// let text = "\u{001B}[31mred\u{001B}[0m text";
/// let clean = strip_ansi(text);
/// assert_eq!(clean, "red text");
/// ```
#[must_use]
pub fn strip_ansi(text: &str) -> String {
    AnsiRegexOptions::strip_ansi(text)
}

/// Check if a string contains any ANSI sequences
///
/// This is a convenience function equivalent to `AnsiRegexOptions::has_ansi()`.
///
/// # Arguments
///
/// * `text` - The text to check for ANSI sequences
///
/// # Returns
///
/// `true` if the text contains ANSI sequences, `false` otherwise
///
/// # Examples
///
/// ```
/// use ansi_escape_sequences::has_ansi;
///
/// assert!(has_ansi("\u{001B}[31mred\u{001B}[0m"));
/// assert!(!has_ansi("plain text"));
/// ```
#[must_use]
pub fn has_ansi(text: &str) -> bool {
    AnsiRegexOptions::has_ansi(text)
}

#[cfg(test)]
mod tests;