pcre2 (grep-pcre2)

Active contributors: Andrew Gallant

Purpose

crates/pcre2 (published as grep-pcre2) implements the Matcher trait on top of PCRE2. It is gated behind the pcre2 Cargo feature on both this crate and the parent grep and ripgrep crates. When enabled and selected at run time with -P/--pcre2, ripgrep uses PCRE2 instead of Rust's native regex engine.

PCRE2 brings:

• Look-around ((?=...), (?<=...), (?!...), (?<!...)).
• Backreferences ((.)\1).
• A different performance profile — sometimes faster, sometimes catastrophically slower (worst-case exponential on pathological patterns, where Rust's regex is linear).

Directory layout

crates/pcre2/src/
├── lib.rs       # Re-exports + brief docs (15 lines)
├── matcher.rs   # RegexMatcher / RegexMatcherBuilder / RegexCaptures (~17K)
└── error.rs     # Error / ErrorKind

Key abstractions

Type	File	Description
RegexMatcher	crates/pcre2/src/matcher.rs	Matcher-trait implementation backed by pcre2::bytes::Regex.
RegexMatcherBuilder	crates/pcre2/src/matcher.rs	Configuration: case-insensitivity, multi-line, JIT, UCP (Unicode character properties), unicode case-folding, max stack frames.
RegexCaptures	crates/pcre2/src/matcher.rs	Captures impl backed by PCRE2's match data.
Error / ErrorKind	crates/pcre2/src/error.rs	Conversion from pcre2::Error into a domain error.

The crate also re-exports two functions from the underlying pcre2 Rust binding:

• is_jit_available() — whether the linked PCRE2 has JIT support compiled in.
• version() — the PCRE2 version string used for --pcre2-version.

How it works

PCRE2 is linked at build time. The pcre2-sys build script:

1. Tries to find a PCRE2 system library via pkg-config.
2. Falls back to building PCRE2 from source statically, using the system C compiler.

This is controlled by environment variables (PCRE2_SYS_STATIC=1 to force static linking) and the build target (musl always builds static).

At runtime, RegexMatcher::new compiles the pattern into a pcre2::bytes::Regex, optionally enabling JIT (default on if available). Each Matcher trait method (find_at, captures_at, is_match_at) delegates to the corresponding PCRE2 binding call.

When PCRE2 is selected

ripgrep's crates/core/flags/hiargs.rs builds a PCRE2 matcher when:

• The user passes -P/--pcre2, or
• The user passes --auto-hybrid-regex and the pattern uses a feature only PCRE2 supports (look-around, backreferences). The auto path tries the default engine first and falls back to PCRE2 on a syntax error indicating an unsupported feature.

The --engine pcre2 and --engine auto flags are aliases for the above.

Integration points

• Implements: grep_matcher::Matcher.
• Used by: crates/core/flags/hiargs.rs::matcher when the user requests PCRE2.
• Depends on: pcre2 (the Rust binding crate), grep-matcher, log, regex-automata, bstr.

When this crate is not built

If the parent build does not enable the pcre2 feature, this crate is not compiled. The grep facade hides its existence behind #[cfg(feature = "pcre2")], and ripgrep will print an error like "PCRE2 is not available in this build of ripgrep" if -P is supplied.

Entry points for modification

• PCRE2 option exposure: extend RegexMatcherBuilder in matcher.rs with the new option, then add a CLI flag in crates/core/flags/defs.rs that calls the new builder method.
• Behavioural divergence from grep-regex: divergence is mostly inherent (PCRE2 is a different engine), but if a feature truly should match across both, mirror the implementation in grep-regex.
• Static linking troubleshooting: read the comments in pcre2-sys's build script, not this crate.