docextract 0.4.0

documentation extractor
Documentation
/// Pattern matching for tag filtering — feature-gated at compile time.
///
/// When the `regex` feature is enabled (default), uses `regex_lite::Regex`.
/// When disabled (`--no-default-features`), uses a hand-rolled matcher.
mod regex;
mod simple;

use std::fmt;

/// Error returned when a pattern string cannot be compiled.
///
/// Defined unconditionally (no `#[cfg]` gate) so that `filter_output`
/// always returns `Result<&mut Self, PatternError>`. On the no-regex path,
/// `Pattern::new` is infallible and the `_Unreachable` variant is never constructed.
#[derive(Debug)]
pub enum PatternError {
    /// Regex compile error or malformed pattern syntax.
    /// Only constructed when the `regex` feature is enabled.
    #[cfg(feature = "regex")]
    InvalidSyntax(String),
    /// Hidden variant so the enum can't be matched exhaustively from outside.
    /// On the no-regex path this variant is never constructed.
    #[doc(hidden)]
    _Unreachable,
}

impl fmt::Display for PatternError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            #[cfg(feature = "regex")]
            PatternError::InvalidSyntax(msg) => write!(f, "invalid filter pattern: {msg}"),
            PatternError::_Unreachable => {
                write!(
                    f,
                    "(unreachable — PatternError constructed on no-regex path)"
                )
            }
        }
    }
}

/// A compiled pattern that can be tested against tag names.
pub(crate) trait PatternMatcher {
    /// Returns `true` if `target` matches this pattern.
    fn matches(&self, target: &str) -> bool;
}

/// Compiles a pattern string, selecting the implementation at compile time.
///
/// When `cfg(feature = "regex")`: delegates to `regex_lite::Regex::new()`.
/// When `cfg(not(feature = "regex"))`: uses the hand-rolled simple matcher.
pub(crate) struct Pattern(Box<dyn PatternMatcher>);

impl Pattern {
    /// Compile a pattern string into a `Pattern`.
    ///
    /// The syntax depends on the compile-time feature configuration.
    #[allow(clippy::unnecessary_wraps)]
    pub(crate) fn new(pattern: &str) -> Result<Self, PatternError> {
        #[cfg(feature = "regex")]
        {
            // regex-lite's empty regex matches everywhere, but per the spec
            // an empty filter pattern should match only empty tag names.
            // Use "^$" to match the empty string only.
            let compiled = if pattern.is_empty() { "^$" } else { pattern };
            regex::RegexMatcher::new(compiled)
                .map(|m| Pattern(Box::new(m)))
                .map_err(PatternError::InvalidSyntax)
        }
        #[cfg(not(feature = "regex"))]
        {
            Ok(Pattern(Box::new(simple::SimpleMatcher::new(pattern))))
        }
    }

    /// Test whether `target` matches this pattern.
    pub(crate) fn matches(&self, target: &str) -> bool {
        self.0.matches(target)
    }
}