Peta::PCRE2#

📦 std

Compile and run PCRE2 regular expressions via the system’s libpcre2-8 library.

The library is located at run time, so pperl needs no build-time dependency on it. If libpcre2-8.so is not installed, use Peta::PCRE2 still succeeds, the PCRE2_* constants still work, and every other call croaks with an instruction telling you which package to install.

Peta::PCRE2 is an explicit binding, not a regex-engine plugin: a compiled pattern is a blessed object and matching is a method call. Perl’s own m// is untouched. Reach for it when you want PCRE2’s JIT specifically - each method is one native call, and the scan loop behind count runs entirely on the C side.

A pattern whose scalar carries the UTF8 flag is compiled with PCRE2_UTF. A subject is matched in the pattern’s encoding: against a UTF pattern a byte string is matched as its UTF-8 upgrade, and against a byte pattern a UTF-8 string that fits in Latin-1 is matched as its bytes - so "\xe9" matches "\xe9" whichever way either is stored. Every reported offset is a byte offset into the subject in that encoding. A start offset inside a UTF-8 character croaks. A subject with characters above 0xFF against a byte pattern is matched as its UTF-8 bytes. substitute’s result is UTF-8 exactly when the subject it matched was.

Synopsis#

use Peta::PCRE2 qw(PCRE2_CASELESS);

my $re = Peta::PCRE2->new("ab+c", PCRE2_CASELESS);
my ($start, $end) = $re->match("xxABBBCxx");   # byte offsets, () on no match
my $n   = $re->count($genome);                  # non-overlapping match count
my $out = $re->substitute($seq, "<2>");         # global replace, new string

Compile constants#

Pass these to new, OR’d together. All are exportable on request; none are exported by default.

  • PCRE2_CASELESS - case-insensitive matching, like /i.

  • PCRE2_MULTILINE - ^ and $ match at internal newlines, like /m.

  • PCRE2_DOTALL - . matches newline too, like /s.

  • PCRE2_EXTENDED - ignore unescaped whitespace and # comments in the pattern, like /x. PCRE2_EXTENDED_MORE additionally ignores spaces and tabs inside character classes, like /xx.

  • PCRE2_UNGREEDY - invert greediness: quantifiers are lazy unless followed by ?.

  • PCRE2_LITERAL - treat the whole pattern as a literal string, with no metacharacters at all.

  • PCRE2_DUPNAMES - permit several capture groups to share one name.

  • PCRE2_ANCHORED - match only at the start offset.

  • PCRE2_UTF - interpret pattern and subject as UTF-8. Set automatically when the pattern scalar is UTF8-flagged, so you rarely need it by hand.

Substitution constants#

Pass these to substitute, whose default is PCRE2_SUBSTITUTE_GLOBAL alone.

  • PCRE2_SUBSTITUTE_GLOBAL - replace every match, not just the first.

  • PCRE2_SUBSTITUTE_EXTENDED - enable backslash escapes and conditional forms such as ${1:-default} in the replacement.

Differences from upstream#

There is no CPAN module this mirrors. The closest, re::engine::PCRE2, is a different design: it replaces perl’s regex engine inside a lexical scope so that ordinary m// runs under PCRE2, and it offers no substitution entry point. This module never touches perl’s engine and exposes PCRE2 directly instead, which is why matching is a method call rather than an operator.

Functions#

Construction#

new#

Compile a pattern into a Peta::PCRE2 object.

Matching#

match#

Match the pattern against a subject string once.

count#

Count non-overlapping matches of the pattern in a subject string.

Substitution#

substitute#

Replace matches of the pattern in a subject, returning a new string.

Introspection#

capture_count#

Number of capturing groups in the compiled pattern.

Synopsis

Peta::PCRE2->new("(a)(b(c))?")->capture_count;   # 3

jit#

Whether this pattern was successfully JIT-compiled.

jit_available#

Whether the loaded libpcre2-8 was built with JIT support.

version#

Version string of the loaded libpcre2-8 (e.g. "10.47 2025-06-30").