7 re - Perl pragma to alter regular expression behaviour
12 ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
14 $pat = '(?{ $foo = 1 })';
16 /foo${pat}bar/; # won't fail (when not under -T switch)
19 no re 'taint'; # the default
20 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
22 no re 'eval'; # the default
23 /foo${pat}bar/; # disallowed (with or without -T switch)
26 use re 'debug'; # NOT lexically scoped (as others are)
27 /^(.*)$/s; # output debugging info during
28 # compile and run time
30 use re 'debugcolor'; # same as 'debug', but with colored output
33 use re qw(Debug All); # Finer tuned debugging options.
34 use re qw(Debug More); # Similarly not lexically scoped.
35 no re qw(Debug ALL); # Turn of all re dugging and unload the module.
37 (We use $^X in these examples because it's tainted by default.)
41 When C<use re 'taint'> is in effect, and a tainted string is the target
42 of a regex, the regex memories (or values returned by the m// operator
43 in list context) are tainted. This feature is useful when regex operations
44 on tainted data aren't meant to extract safe substrings, but to perform
45 other transformations.
47 When C<use re 'eval'> is in effect, a regex is allowed to contain
48 C<(?{ ... })> zero-width assertions even if regular expression contains
49 variable interpolation. That is normally disallowed, since it is a
50 potential security risk. Note that this pragma is ignored when the regular
51 expression is obtained from tainted data, i.e. evaluation is always
52 disallowed with tainted regular expressions. See L<perlre/(?{ code })>.
54 For the purpose of this pragma, interpolation of precompiled regular
55 expressions (i.e., the result of C<qr//>) is I<not> considered variable
60 I<is> allowed if $pat is a precompiled regular expression, even
61 if $pat contains C<(?{ ... })> assertions.
63 When C<use re 'debug'> is in effect, perl emits debugging messages when
64 compiling and using regular expressions. The output is the same as that
65 obtained by running a C<-DDEBUGGING>-enabled perl interpreter with the
66 B<-Dr> switch. It may be quite voluminous depending on the complexity
67 of the match. Using C<debugcolor> instead of C<debug> enables a
68 form of output that can be used to get a colorful display on terminals
69 that understand termcap color sequences. Set C<$ENV{PERL_RE_TC}> to a
70 comma-separated list of C<termcap> properties to use for highlighting
71 strings on/off, pre-point part on/off.
72 See L<perldebug/"Debugging regular expressions"> for additional info.
74 Similarly C<use re 'Debug'> produces debugging output, the difference
75 being that it allows the fine tuning of what debugging output will be
76 emitted. Following the 'Debug' keyword one of several options may be
77 provided: COMPILE, EXECUTE, TRIE_COMPILE, TRIE_EXECUTE, TRIE_MORE,
78 OPTIMISE, OFFSETS and ALL. Additionally the special keywords 'All' and
79 'More' may be provided. 'All' represents everything but OPTIMISE and
80 OFFSETS and TRIE_MORE, and 'More' is similar but include TRIE_MORE.
81 Saying C<< no re Debug => 'EXECUTE' >> will disable executing debug
82 statements and saying C<< use re Debug => 'EXECUTE' >> will turn it on. Note
83 that these flags can be set directly via ${^RE_DEBUG_FLAGS} by using the
84 following flag values:
88 RE_DEBUG_TRIE_COMPILE 4
89 RE_DEBUG_TRIE_EXECUTE 8
94 The directive C<use re 'debug'> and its equivalents are I<not> lexically
95 scoped, as the other directives are. They have both compile-time and run-time
98 See L<perlmodlib/Pragmatic Modules>.
102 # N.B. File::Basename contains a literal for 'taint' as a fallback. If
103 # taint is changed here, File::Basename must be updated as well.
105 taint => 0x00100000, # HINT_RE_TAINT
106 eval => 0x00200000, # HINT_RE_EVAL
110 eval { # Ignore errors
113 my $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
114 my $props = $ENV{PERL_RE_TC} || 'md,me,so,se,us,ue';
115 my @props = split /,/, $props;
116 my $colors = join "\t", map {$terminal->Tputs($_,1)} @props;
119 $ENV{PERL_RE_COLORS} = $colors;
130 OPTIMIZE => 32, # alias
144 Carp::carp("Useless use of \"re\" pragma");
146 foreach my $idx (0..$#_){
148 if ($s eq 'Debug' or $s eq 'Debugcolor') {
149 setcolor() if $s eq 'Debugcolor';
150 ${^RE_DEBUG_FLAGS} = 0 unless defined ${^RE_DEBUG_FLAGS};
152 XSLoader::load('re');
153 for my $idx ($idx+1..$#_) {
154 if ($flags{$_[$idx]}) {
156 ${^RE_DEBUG_FLAGS} |= $flags{$_[$idx]};
158 ${^RE_DEBUG_FLAGS} &= ~ $flags{$_[$idx]};
162 Carp::carp("Unknown \"re\" Debug flag '$_[$idx]', possible flags: ",
163 join(", ",sort { $flags{$a} <=> $flags{$b} } keys %flags ) );
167 install() unless $installed;
169 } elsif (!${^RE_DEBUG_FLAGS}) {
170 uninstall() if $installed;
174 } elsif ($s eq 'debug' or $s eq 'debugcolor') {
175 setcolor() if $s eq 'debugcolor';
177 XSLoader::load('re');
179 install() unless $installed;
182 uninstall() if $installed;
185 } elsif (exists $bitmask{$s}) {
186 $bits |= $bitmask{$s};
189 Carp::carp("Unknown \"re\" subpragma '$s' (known ones are: ",
190 join(', ', map {qq('$_')} 'debug', 'debugcolor', sort keys %bitmask),
204 $^H &= ~ bits(0, @_);