Data models

The principal in-memory structures and how they connect.

CLI argument layering

graph TD
    Argv[std::env::args_os] --> Parser[lexopt::Parser]
    Parser --> LowArgs[LowArgs - flat record]
    Config[RIPGREP_CONFIG_PATH file] --> Parser
    LowArgs -->|HiArgs::from_low_args| HiArgs[HiArgs - resolved record]
    HiArgs --> Walker[walk_builder]
    HiArgs --> MatcherFn[matcher]
    HiArgs --> SearcherFn[searcher]
    HiArgs --> PrinterFn[printer]
    HiArgs --> Stdout[stdout]

Type	File	Role
Flag (trait)	crates/core/flags/mod.rs	Per-flag schema: short/long names, doc text, category, update method
Category (enum)	crates/core/flags/mod.rs	Input, Search, Filter, Output, OutputModes, Logging, OtherBehaviors
LowArgs	crates/core/flags/lowargs.rs	Flat struct, one field per flag. Filled in by Flag::update.
HiArgs	crates/core/flags/hiargs.rs	Resolved. Knows how to build matchers, walkers, searchers, printers.
Mode (enum)	crates/core/flags/lowargs.rs	Search(SearchMode), Files, Types, Generate(GenerateMode)
SearchMode	crates/core/flags/lowargs.rs	Standard, Summary, JSON
SpecialMode	crates/core/flags/lowargs.rs	HelpShort, HelpLong, VersionShort, VersionLong, VersionPCRE2
GenerateMode	crates/core/flags/lowargs.rs	Man, CompleteBash, CompleteZsh, CompleteFish, CompletePowerShell
ParseResult<T>	crates/core/flags/parse.rs	Ok(T), Err(anyhow::Error), Special(SpecialMode)

Search-time structures

Type	File	Role
Haystack	crates/core/haystack.rs	The current file (or stdin) being searched
SearchWorker	crates/core/search.rs	Per-thread bundle of Searcher + Matcher + Printer
Searcher	crates/searcher/src/searcher/mod.rs	The line-oriented search loop
LineBuffer	crates/searcher/src/line_buffer.rs	Streaming buffer for non-mmap mode
BinaryDetection	crates/searcher/src/searcher/mod.rs	None / Quit(byte) / Convert(byte)
Encoding	crates/searcher/src/searcher/mod.rs	Optional encoding_rs decoder
MmapChoice	crates/searcher/src/searcher/mmap.rs	Auto / Always / Never
Sink (trait)	crates/searcher/src/sink.rs	Receiver of match callbacks; implemented by printers
SinkMatch, SinkContext, SinkFinish	crates/searcher/src/sink.rs	Payloads passed to Sink callbacks
Matcher (trait)	crates/matcher/src/lib.rs	Engine-agnostic regex interface
Match	crates/matcher/src/lib.rs	(start, end) byte range; structurally a Range<usize> with invariants
Captures (trait)	crates/matcher/src/lib.rs	Capture-group access

Walker structures

Type	File	Role
WalkBuilder	crates/ignore/src/walk.rs	Configures both Walk and WalkParallel
Walk	crates/ignore/src/walk.rs	Single-threaded iterator
WalkParallel	crates/ignore/src/walk.rs	Parallel walker with thread pool
WalkState	crates/ignore/src/walk.rs	Worker visitor return: Continue / Skip / Quit
DirEntry	crates/ignore/src/walk.rs	Yielded entry: path, depth, file type, error
Match<T>	crates/ignore/src/lib.rs	Three-state result: None / Ignore(T) / Whitelist(T)
Gitignore	crates/ignore/src/gitignore.rs	Parsed .gitignore-style file
Override	crates/ignore/src/overrides.rs	--glob / --iglob matcher
Types	crates/ignore/src/types.rs	-t/-T type matcher

Globset structures

Type	File	Role
Glob	crates/globset/src/glob.rs	Parsed (uncompiled) glob
GlobMatcher	crates/globset/src/glob.rs	Compiled, matchable single glob
GlobSet	crates/globset/src/lib.rs	Set of globs, all matched in parallel
GlobSetBuilder	crates/globset/src/lib.rs	Builder for GlobSet
Candidate	crates/globset/src/lib.rs	Path pre-processed for matching (cached basename + extension)

Printer structures

Type	File	Role
Standard	crates/printer/src/standard.rs	Human-readable printer (the default)
Summary	crates/printer/src/summary.rs	Aggregate-only printer
JSON	crates/printer/src/json.rs	JSON Lines printer (gated behind serde)
SummaryKind	crates/printer/src/summary.rs	Count, CountMatches, PathWithMatch, PathWithoutMatch, Quiet
ColorSpecs	crates/printer/src/color.rs	Resolved color configuration
UserColorSpec	crates/printer/src/color.rs	Parsed --colors KIND:ATTR:VALUE user input
Stats	crates/printer/src/stats.rs	Aggregate match/byte/file/time counters
HyperlinkFormat, HyperlinkConfig, HyperlinkAlias	crates/printer/src/hyperlink/mod.rs	Terminal hyperlink configuration
PathPrinter	crates/printer/src/path.rs	Path-only printer used by --files mode

Lifetime sketch

sequenceDiagram
    autonumber
    participant Argv
    participant Parser as flags::parse
    participant LA as LowArgs
    participant HA as HiArgs
    participant Walker as ignore::WalkParallel
    participant SW as SearchWorker
    participant Out as BufferWriter

    Argv->>Parser: tokens
    Parser->>LA: each Flag::update
    LA->>HA: from_low_args (resolves config, env)
    HA->>Walker: walk_builder().build_parallel()
    HA->>SW: search_worker(matcher, searcher, printer)
    par worker threads
        Walker->>SW: yield path
        SW->>SW: search(haystack)
        SW->>Out: write to per-thread buffer
        Out->>Out: serialize per-file flush
    end