re

📦 min

The re pragma and regular-expression introspection module.

Two jobs, one module:

• As a pragma — use re turns on lexically scoped regex behaviour: compile-time and run-time debug output (use re 'debug', use re 'debugcolor', use re qw(Debug ...)), permission to run code inside patterns derived from interpolated variables (use re 'eval'), taint propagation (use re 'taint'), stricter pattern checking (use re 'strict'), and default pattern flags (use re '/ix').

• As an introspection API — when imported, it exposes a small set of utility functions for inspecting compiled patterns (qr// objects) and the named-capture groups of the most recent successful match: is_regexp, regexp_pattern, regname, regnames, regnames_count, regmust, optimization.

Synopsis

use re 'debug';                     # dump compile + match info
use re qw(Debug PARSE DUMP);        # pick specific debug categories
use re 'eval';                      # allow (?{...}) from variables
use re '/ix';                       # add /i and /x to every regex

use re qw(is_regexp regexp_pattern regnames);
if (is_regexp($qr)) {
    my ($pat, $mods) = regexp_pattern($qr);   # list: pattern, modifiers
    my $str          = regexp_pattern($qr);   # scalar: "(?^flags:pattern)"
}
"foobar" =~ /(?<first>foo)(?<rest>bar)/;
my @names = regnames();                        # ('first', 'rest')
my $cap   = regname('first');                  # 'foo'

What you can do with it

• Turn on regex debug output during one lexical scope and turn it back off outside — handy when a single pattern misbehaves in a large program.

• Ask whether an arbitrary value is really a compiled regex (even if it’s blessed or overloaded) without having it stringify on you.

• Recover the original pattern text and modifier letters from a qr//, in either list or scalar form.

• Walk the named-capture groups of the last successful match by name, enumerate all names, or just count them.

• Peek at what the regex optimiser found — the longest anchored and floating substrings, the start class, the start-of-string anchors — to understand why a pattern is fast or slow.

Functions

Pragma behaviour

install

Return an integer handle to the regex engine and reset the debug-colour flag.

Pattern introspection

is_regexp

Return true if the argument is a compiled regular expression.

regexp_pattern

Return the pattern text and modifiers of a compiled regular expression.

Named captures

regname

Return the contents of a named capture group from the most recent successful match.

regnames

Return the names of the named capture groups in the most recent successful match.

regnames_count

Return the number of distinct named capture groups in the pattern of the most recent successful match.

Optimiser introspection

regmust

Return the longest anchored and longest floating fixed strings the optimiser extracted from a compiled pattern.

optimization

Return a hashref of the optimiser’s compile-time findings for a compiled pattern.