use re (Programming Perl)

31.17. use re

This pragma controls the use of regular expressions. It has four possible invocations: "taint" and "eval", which are lexically scoped, plus "debug" and "debugcolor", which aren't.

use re 'taint';                
# Contents of $match are tainted if $dirty was also tainted.
($match) = ($dirty =~ /^(.*)$/s); 

# Allow code interpolation:
use re 'eval';
$pat = '(?{ $var = 1 })';      # embedded code execution
/alpha${pat}omega/;            # won't fail unless under -T
                               # and $pat is tainted

use re 'debug';                # like "perl -Dr"
/^(.*)$/s;                     # output debugging info during
                               #     compile time and run time

use re 'debugcolor';           # same as 'debug', 
                               #    but with colored output

When use re 'taint' is in effect and a tainted string is the target of a regex, the numbered regex variables and values returned by the m// operator in list context are all tainted. This is useful when regex operations on tainted data aren't meant to extract safe substrings, but to perform other transformations. See the discussion on tainting in Chapter 23, "Security".

When use re 'eval' is in effect, a regex is allowed to contain assertions that execute Perl code, which are of the form (?{ ... }), even when the regex contains interpolated variables. Execution of code segments resulting from variable interpolation into a regex is normally disallowed for security reasons: you don't want programs that read patterns from config files, command-line arguments, or CGI form fields to suddenly start executing arbitrary code if they weren't designed to expect this possibility. This use of the pragma allows only untainted strings to be interpolated; tainted data will still cause an exception to be raised (if you're running with taint checks enabled). See also Chapter 5, "Pattern Matching", and Chapter 23, "Security".

For the purposes of this pragma, interpolation of precompiled regular expressions (produced by the qr// operator) is not considered variable interpolation. Nevertheless, when you build the qr// pattern it needs to have use re 'eval' in effect if any of its interpolated strings contain code assertions. For example:

$code = '(?{ $n++ })';      # code assertion
$str  = '\b\w+\b' . $code;  # build string to interpolate


$line =~ /$str/;    # this needs use re 'eval'

$pat = qr/$str/;    # this also needs use re 'eval'
$line =~ /$pat/;    # but this doesn't need use re 'eval'

Under use re 'debug', Perl emits debugging messages when compiling and when executing regular expressions. The output is the same as that obtained by running a "debugging Perl" (one compiled with -DDEBUGGING passed to the C compiler) and then executing your Perl program under Perl's -Dr command-line switch. Depending on how complicated your pattern is, the resulting output can be overwhelming. Calling use re 'debugcolor' enables more colorful output that can be useful, provided your terminal understands color sequences. Set your PERL_RE_TC environment variable to a comma-separated list of relevant termcap(5) properties for highlighting. For more details, see Chapter 20, "The Perl Debugger".


31.16. use overload		31.18. use sigtrap