re - Perl pragma to alter regular expression behaviour
use re 'taint';
($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
$pat = '(?{ $foo = 1 })';
use re 'eval';
/foo${pat}bar/; # won't fail (when not under -T
# switch)
{
no re 'taint'; # the default
($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
no re 'eval'; # the default
/foo${pat}bar/; # disallowed (with or without -T
# switch)
}
use re 'strict'; # Raise warnings for more conditions
use re '/ix';
"FOO" =~ / foo /; # /ix implied
no re '/x';
"FOO" =~ /foo/; # just /i implied
use re 'debug'; # output debugging info during
/^(.*)$/s; # compile and run time
use re 'debugcolor'; # same as 'debug', but with colored
# output
...
use re qw(Debug All); # Same as "use re 'debug'", but you
# can use "Debug" with things other
# than 'All'
use re qw(Debug More); # 'All' plus output more details
no re qw(Debug ALL); # Turn on (almost) all re debugging
# in this scope
use re qw(is_regexp regexp_pattern); # import utility functions
my ($pat,$mods)=regexp_pattern(qr/foo/i);
if (is_regexp($obj)) {
print "Got regexp: ",
scalar regexp_pattern($obj); # just as perl would stringify
} # it but no hassle with blessed
# re's.(We use $^X in these examples because it's tainted by default.)
When use re 'taint' is in effect, and a tainted string is the target of a regexp, the regexp memories (or values returned by the m// operator in list context) are tainted. This feature is useful when regexp operations on tainted data aren't meant to extract safe substrings, but to perform other transformations.
When use re 'eval' is in effect, a regexp is allowed to contain (?{ ... }) zero-width assertions and (??{ ... }) postponed subexpressions that are derived from variable interpolation, rather than appearing literally within the regexp. That is normally disallowed, since it is a potential security risk. Note that this pragma is ignored when the regular expression is obtained from tainted data, i.e. evaluation is always disallowed with tainted regular expressions. See "(?{ code })" in perlre and "(??{ code })" in perlre.
For the purpose of this pragma, interpolation of precompiled regular expressions (i.e., the result of qr//) is not considered variable interpolation. Thus:
/foo${pat}bar/is allowed if $pat is a precompiled regular expression, even if $pat contains (?{ ... }) assertions or (??{ ... }) subexpressions.
Note that this is an experimental feature which may be changed or removed in a future Perl release.
When use re 'strict' is in effect, stricter checks are applied than otherwise when compiling regular expressions patterns. These may cause more warnings to be raised than otherwise, and more things to be fatal instead of just warnings. The purpose of this is to find and report at compile time some things, which may be legal, but have a reasonable possibility of not being the programmer's actual intent. This automatically turns on the "regexp" warnings category (if not already on) within its scope.
As an example of something that is caught under "strict', but not otherwise, is the pattern
qr/\xABC/The "\x" construct without curly braces should be followed by exactly two hex digits; this one is followed by three. This currently evaluates as equivalent to
qr/\x{AB}C/that is, the character whose code point value is 0xAB, followed by the letter C. But since C is a hex digit, there is a reasonable chance that the intent was
qr/\x{ABC}/that is the single character at 0xABC. Under 'strict' it is an error to not follow \x with exactly two hex digits. When not under 'strict' a warning is generated if there is only one hex digit, and no warning is raised if there are more than two.
It is expected that what exactly 'strict' does will evolve over time as we gain experience with it. This means that programs that compile under it in today's Perl may not compile, or may have more or fewer warnings, in future Perls. There is no backwards compatibility promises with regards to it. Also there are already proposals for an alternate syntax for enabling it. For these reasons, using it will raise a experimental::re_strict class warning, unless that category is turned off.
Note that if a pattern compiled within 'strict' is recompiled, say by interpolating into another pattern, outside of 'strict', it is not checked again for strictness. This is because if it works under strict it must work under non-strict.
When use re '/flags' is specified, the given flags are automatically added to every regular expression till the end of the lexical scope. flags can be any combination of 'a', 'aa', 'd', 'i', 'l', 'm', 'n', 'p', 's', 'u', 'x', and/or 'xx'.
no re '/flags' will turn off the effect of use re '/flags' for the given flags.
For example, if you want all your regular expressions to have /msxx on by default, simply put
use re '/msxx';at the top of your code.
The character set /adul flags cancel each other out. So, in this example,
use re "/u";
"ss" =~ /\xdf/;
use re "/d";
"ss" =~ /\xdf/;the second use re does an implicit no re '/u'.
Similarly,
use re "/xx"; # Doubled-x
...
use re "/x"; # Single x from here on
...Turning on one of the character set flags with use re takes precedence over the locale pragma and the 'unicode_strings' feature, for regular expressions. Turning off one of these flags when it is active reverts to the behaviour specified by whatever other pragmata are in scope. For example:
use feature "unicode_strings";
no re "/u"; # does nothing
use re "/l";
no re "/l"; # reverts to unicode_strings behaviourDefault flags are applied to wherever a pattern is compiled with the exception of the /x flag, which is not applied to patterns compiled from string arguments to split. Thus `use re "/x";` does not affect the behaviour of split " " but does affect the behavior of split / /.
When use re 'debug' is in effect, perl emits debugging messages when compiling and using regular expressions. The output is the same as that obtained by running a -DDEBUGGING-enabled perl interpreter with the -Dr switch. It may be quite voluminous depending on the complexity of the match. Using debugcolor instead of debug enables a form of output that can be used to get a colorful display on terminals that understand termcap color sequences. Set $ENV{PERL_RE_TC} to a comma-separated list of termcap properties to use for highlighting strings on/off, pre-point part on/off. See "Debugging Regular Expressions" in perldebug for additional info.
NOTE that the exact format of the debug mode is NOT considered to be an officially supported API of Perl. It is intended for debugging only and may change as the core development team deems appropriate without notice or deprecation in any release of Perl, major or minor. Any documentation of the output is purely advisory.
As of 5.9.5 the directive use re 'debug' and its equivalents are lexically scoped, as the other directives are. However they have both compile-time and run-time effects.
See "Pragmatic Modules" in perlmodlib.
Similarly use re 'Debug' produces debugging output, the difference being that it allows the fine tuning of what debugging output will be emitted. Options are divided into three groups, those related to compilation, those related to execution and those related to special purposes.
NOTE that the options provided under the Debug mode and the exact format of the output they create is NOT considered to be an officially supported API of Perl. It is intended for debugging only and may change as the core development team deems appropriate without notice or deprecation in any release of Perl, major or minor. Any documentation of the format or options available is advisory only and is subject to change without notice.
The options are as follows:
Turns on all non-extra compile related debug options.
Turns on debug output related to the process of parsing the pattern.
Enables output related to the optimisation phase of compilation.
Detailed info about trie compilation.
Dump the final program out after it is compiled and optimised.
Dump the flags associated with the program
Print output intended for testing the internals of the compile process