ripgrep crates/searcher/src/lib.rs: Code Companion¶

/*!
This crate provides an implementation of line oriented search, with optional
support for multi-line search.

# Brief overview

The principle type in this crate is a [`Searcher`], which can be configured
and built by a [`SearcherBuilder`]. A `Searcher` is responsible for reading
bytes from a source (e.g., a file), executing a search of those bytes using
a `Matcher` (e.g., a regex) and then reporting the results of that search to
a [`Sink`] (e.g., stdout). The `Searcher` itself is principally responsible
for managing the consumption of bytes from a source and applying a `Matcher`
over those bytes in an efficient way. The `Searcher` is also responsible for
inverting a search, counting lines, reporting contextual lines, detecting
binary data and even deciding whether or not to use memory maps.
*/

pub use crate::{
    // Line iteration utilities from the lines module
    lines::{LineIter, LineStep},

    // Core searcher types and configuration
    searcher::{
        BinaryDetection,    // How to handle binary files
        ConfigError,        // Configuration validation errors
        Encoding,           // Text encoding settings
        MmapChoice,         // Memory-mapped file options
        Searcher,           // The main search executor
        SearcherBuilder,    // Builder for configuring Searcher
    },

    // Result handling types
    sink::{
        Sink,              // Trait for receiving search results
        SinkContext,       // Context lines around matches
        SinkContextKind,   // Before/after context distinction
        SinkError,         // Error type for sink operations
        SinkFinish,        // End-of-search summary data
        SinkMatch,         // Individual match data
        sinks,             // Module of convenience implementations
    },
};

pub use crate::{
    searcher::{
        // The builder creates configured Searcher instances
        SearcherBuilder,
        // The built type with all configuration applied
        Searcher,
    },
    // ...
};

pub use crate::{
    sink::{
        Sink,              // The core trait - defines callback methods
        SinkContext,       // Data passed for context lines
        SinkContextKind,   // Enum: Before, After, or Other
        SinkError,         // Errors that can occur in sink callbacks
        SinkFinish,        // Summary data at search completion
        SinkMatch,         // Data passed for each matching line
        sinks,             // Convenience implementations
    },
};

// From the documentation example - using the UTF8 convenience sink
use grep_searcher::sinks::UTF8;

// The closure signature: (line_number, line_content) -> Result<bool, Error>
// Return Ok(true) to continue, Ok(false) to stop early
Searcher::new().search_slice(&matcher, SHERLOCK, UTF8(|lnum, line| {
    // Process the match...
    Ok(true)  // Continue searching
}))?;

use {
    grep_matcher::Matcher,      // The trait (from grep-matcher crate)
    grep_regex::RegexMatcher,   // The implementation (from grep-regex crate)
    grep_searcher::Searcher,    // The search orchestrator
    grep_searcher::sinks::UTF8, // Convenience sink for UTF-8 text
};

// Test data as a byte slice
const SHERLOCK: &'static [u8] = b"...";

// Step 1: Build the matcher
let matcher = RegexMatcher::new(r"Doctor \w+")?;

// Step 2: Prepare result storage
let mut matches: Vec<(u64, String)> = vec![];

// Step 3: Execute the search
Searcher::new().search_slice(&matcher, SHERLOCK, UTF8(|lnum, line| {
    // The searcher found a line with a match, but we re-run
    // the matcher to get precise match boundaries
    let mymatch = matcher.find(line.as_bytes())?.unwrap();
    matches.push((lnum, line[mymatch].to_string()));
    Ok(true)
}))?;

// Macro definitions available to subsequent modules
#[macro_use]
mod macros;

// Internal modules (no pub = private to crate)
mod line_buffer;  // Buffered reading implementation
mod lines;        // Line iteration utilities
mod searcher;     // Core Searcher type and builder
mod sink;         // Sink trait and implementations

// Test utilities only compiled in test builds
#[cfg(test)]
mod testutil;

Source (file/stdin/bytes)
         ↓
    Searcher (orchestration)
         ↓
    Matcher (pattern matching)
         ↓
    Sink (result handling)

// Internal structure:
mod internal_module {
    pub struct SomeType;
}

// Public API (in lib.rs):
pub use crate::internal_module::SomeType;

// User sees:
use my_crate::SomeType;  // Clean, flat path