printer (grep-printer)

Active contributors: Andrew Gallant

Purpose

crates/printer (published as grep-printer) provides three implementations of grep_searcher::Sink, each producing a different output format:

• Standard — the human-readable, colored, grep-style output that rg produces by default. Path, line number, column, and the matching line, optionally with surrounding context.
• Summary — aggregate output: just the count, just the file name, just the matched-or-not boolean. Used by -c/--count, -l/--files-with-matches, etc.
• JSON — structured JSON Lines output for downstream tooling (delta, editors, scripts). Used by --json.

The crate also handles color configuration, terminal hyperlinks, and aggregate Stats.

Directory layout

crates/printer/src/
├── lib.rs              # Re-exports + crate docs
├── standard.rs         # Standard / StandardBuilder / StandardSink (~136K, the largest file in the crate)
├── summary.rs          # Summary / SummaryBuilder / SummarySink / SummaryKind (~40K)
├── json.rs             # JSON / JSONBuilder / JSONSink (~37K)
├── jsont.rs            # JSON message types (begin/end/match/context/summary)
├── color.rs            # ColorSpecs / UserColorSpec / default color schemes
├── hyperlink/          # Terminal hyperlink format parsing and emission
├── path.rs             # PathPrinter and PathPrinterBuilder
├── stats.rs            # Stats: matches, matched_lines, searches, bytes counters
├── counter.rs          # CounterWriter wrapper that tracks bytes/lines for stats
├── util.rs             # Shared helpers: replacer, trimmers, formatters
└── macros.rs           # write_path!, write_match! etc.

Key abstractions

Type	File	Description
Standard / StandardBuilder / StandardSink	crates/printer/src/standard.rs	The default printer. Builder configures colors, line numbers, column numbers, max columns, replacement, trimming, multi-line behaviour, hyperlinks, and many more.
Summary / SummaryBuilder / SummarySink	crates/printer/src/summary.rs	Aggregate-only printer. SummaryKind selects the mode (Count, CountMatches, PathWithMatch, PathWithoutMatch, Quiet).
JSON / JSONBuilder / JSONSink	crates/printer/src/json.rs	JSON Lines printer; gated behind serde feature. Each match becomes a match JSON object; per-file begin/end brackets and a final summary.
ColorSpecs / UserColorSpec	crates/printer/src/color.rs	The structured form of --colors path:fg:red:intense user input.
HyperlinkFormat / HyperlinkConfig / HyperlinkAlias	crates/printer/src/hyperlink/	Terminal hyperlink format strings (file://{host}{path}#{line}) and the predefined aliases (default, vscode, cursor, ...).
PathPrinter	crates/printer/src/path.rs	A simple printer for --files mode that just prints paths with the same coloring/hyperlink machinery.
Stats	crates/printer/src/stats.rs	Aggregate counters: matches, matched lines, searches, bytes printed, bytes searched, search time.
CounterWriter	crates/printer/src/counter.rs	A Write adapter that counts bytes for Stats.

Sink ↔ printer mapping

graph LR
    Searcher --> Sink[grep_searcher::Sink]
    Sink -->|trait impl| StdSink[StandardSink]
    Sink -->|trait impl| SumSink[SummarySink]
    Sink -->|trait impl| JsonSink[JSONSink]
    StdSink --> StdOut[stdout / Buffer]
    SumSink --> StdOut
    JsonSink --> StdOut

The Standard/Summary/JSON types are factories: each produces a *Sink for one search invocation by calling .sink(matcher). The sink owns mutable state (current file's stats, captures buffer, replacement scratch) and is reset per invocation.

How it works

A typical use:

let matcher = grep::regex::RegexMatcher::new(r"Sherlock")?;
let mut printer = grep::printer::Standard::new_no_color(vec![]);
grep::searcher::Searcher::new()
    .search_slice(&matcher, SHERLOCK, printer.sink(&matcher))?;

The printer doesn't read the haystack; the searcher does. The printer just receives SinkMatch / SinkContext / SinkFinish callbacks and writes formatted output. All formatting decisions (whether to print the file path, whether to color, what column number format to use) are made inside the printer based on its builder configuration.

The largest part of standard.rs (the bulk of the crate's size) handles the many output combinations: with/without line numbers, with/without context, with/without colors, with/without trimming, with/without column numbers, with/without replacements, with/without hyperlinks, with/without multi-line.

Hyperlinks

Terminal hyperlinks (OSC-8 escape sequences) let rg's output show clickable file paths in supported terminals. The format is configurable via --hyperlink-format. The crate's hyperlink/ directory parses the format string (with {path}, {host}, {line}, {column} placeholders) and emits the right escape codes. There are predefined aliases for several editors and terminals (default, file, vscode, vscode-insiders, cursor, kitty, iterm2, wezterm, ...).

Stats

When --stats is set, the binary keeps a Stats per SearchWorker and merges them at the end of the search. The print_stats function in crates/core/main.rs emits the final summary (in human or JSON form depending on SearchMode).

Integration points

• Implements: grep_searcher::Sink.
• Used by: crates/core/search.rs::SearchWorker, anyone embedding the search engine via grep::printer.
• Depends on: grep-matcher, grep-searcher, bstr, termcolor, serde (optional), serde_json (optional), base64 (optional, for non-UTF-8 paths in JSON).
• Re-exported by: grep::printer.

Entry points for modification

• New --color knob: crates/printer/src/color.rs defines the type kind enumeration and parsing.
• New JSON message field: jsont.rs defines the message structs; json.rs writes them.
• Output formatting bug: usually standard.rs. Add an integration test in tests/feature.rs (or a more specific test file) before fixing.
• New hyperlink alias: crates/printer/src/hyperlink/. The aliases are listed in a static table.

For the upstream side of the pipeline see searcher.