lib.rs: Code Companion¶

Reference code for the Regex Crate Entry lecture. Sections correspond to the lecture document.

Section 1: The Documentation Attribute¶

/*!
An implementation of `grep-matcher`'s `Matcher` trait for Rust's regex engine.
*/

The /*! syntax creates an inner documentation comment that attaches to the enclosing item—in this case, the crate itself. This becomes the crate-level documentation visible in cargo doc output.

Section 2: The Missing Docs Lint¶

#![deny(missing_docs)]

The #! prefix makes this an inner attribute applying to the entire crate. Any public item without documentation will cause a compilation error, not just a warning.

Section 3: The Public API Through Re-exports¶

pub use crate::{
    // Error handling types from the error module
    error::{Error, ErrorKind},
    // Core matching types from the matcher module
    matcher::{RegexCaptures, RegexMatcher, RegexMatcherBuilder},
};

The pub use statement selectively re-exports only five types from internal modules, defining the complete public API. The crate:: prefix explicitly anchors paths to the crate root.

Section 4: The Builder Pattern in Context¶

pub use crate::{
    // ...
    matcher::{
        RegexCaptures,        // Holds captured groups from a match
        RegexMatcher,         // The matcher implementing grep-matcher's trait
        RegexMatcherBuilder,  // Builder for configuring RegexMatcher
    },
};

Exporting RegexMatcherBuilder alongside RegexMatcher indicates users construct matchers through the builder pattern rather than direct instantiation. This mirrors the builder ecosystem found throughout ripgrep.

Section 5: The Internal Module Structure¶

// Private modules - no `pub` keyword means internal to this crate
mod ast;         // Abstract syntax tree manipulation
mod ban;         // Pattern/feature restrictions
mod config;      // Configuration handling
mod error;       // Error types (partially re-exported)
mod literal;     // Literal extraction for optimization
mod matcher;     // Matcher trait implementation (partially re-exported)
mod non_matching;// Handling of non-matching patterns
mod strip;       // Pattern transformation/stripping

Eight private modules contain the implementation complexity. Only selected types from error and matcher are exposed publicly through the pub use declaration above.

Section 6: Why These Specific Modules?¶

// From the re-exports, we can infer the public-facing module purposes:
error::{Error, ErrorKind},  // Structured error handling for regex compilation failures
matcher::{
    RegexCaptures,          // Capture group storage for the Matcher trait
    RegexMatcher,           // The Matcher trait implementation
    RegexMatcherBuilder,    // Configuration and construction
},

The error module provides structured diagnostics for compilation failures. The matcher module bridges grep-matcher's abstract Matcher trait with the concrete regex crate. The literal module (internal) enables fast-path searching by extracting fixed strings from patterns.

Section 7: The Supporting Modules¶

// Internal modules handling specialized concerns:
mod ast;          // Parse and analyze regex pattern structure
mod ban;          // Restrict problematic regex features
mod config;       // Centralized configuration management
mod non_matching; // Handle patterns guaranteed not to match
mod strip;        // Transform patterns (e.g., strip comments)

These modules handle regex analysis and transformation at the AST level, pattern restrictions for grep-style searching, and configuration management—all hidden from crate users behind the minimal five-type public API.

Quick Reference¶

Public API Summary¶

Type	Module	Purpose
`Error`	error	Error type for regex operations
`ErrorKind`	error	Enum categorizing error causes
`RegexMatcher`	matcher	Implements `grep-matcher::Matcher`
`RegexMatcherBuilder`	matcher	Configures and builds `RegexMatcher`
`RegexCaptures`	matcher	Stores captured groups from matches

Attribute Syntax Reference¶

Syntax	Name	Scope
`#[...]`	Outer attribute	Applies to the following item
`#![...]`	Inner attribute	Applies to the enclosing item
`/! ... /`	Inner doc comment	Documents the enclosing item
`/// ...`	Outer doc comment	Documents the following item

Module Visibility¶

mod private_mod;      // Private to this crate
pub mod public_mod;   // Visible outside this crate
pub use mod::Type;    // Re-export specific items as public