```{index} single: Peta::PCRE2 ``` # Peta::PCRE2 ```{pperl-module-badges} Peta::PCRE2 ``` 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 ```perl 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`](PCRE2/new) Compile a pattern into a `Peta::PCRE2` object. ### Matching #### [`match`](PCRE2/match) Match the pattern against a subject string once. #### [`count`](PCRE2/count) Count non-overlapping matches of the pattern in a subject string. ### Substitution #### [`substitute`](PCRE2/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** ```perl 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"`). ```{toctree} :hidden: :maxdepth: 1 PCRE2/new PCRE2/match PCRE2/count PCRE2/substitute ```