# 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 ```perl 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" =~ /(?foo)(?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`](re/install.md) Return an integer handle to the regex engine and reset the debug-colour flag. ### Pattern introspection #### [`is_regexp`](re/is_regexp.md) Return true if the argument is a compiled regular expression. #### [`regexp_pattern`](re/regexp_pattern.md) Return the pattern text and modifiers of a compiled regular expression. ### Named captures #### [`regname`](re/regname.md) Return the contents of a named capture group from the most recent successful match. #### [`regnames`](re/regnames.md) Return the names of the named capture groups in the most recent successful match. #### [`regnames_count`](re/regnames_count.md) Return the number of distinct named capture groups in the pattern of the most recent successful match. ### Optimiser introspection #### [`regmust`](re/regmust.md) Return the longest anchored and longest floating fixed strings the optimiser extracted from a compiled pattern. #### [`optimization`](re/optimization.md) Return a hashref of the optimiser’s compile-time findings for a compiled pattern.