3 our $VERSION = 0.06_01;
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:
87 RE_DEBUG_COMPILE 0x001
88 RE_DEBUG_EXECUTE 0x002
89 RE_DEBUG_TRIE_COMPILE 0x004
90 RE_DEBUG_TRIE_EXECUTE 0x008
91 RE_DEBUG_TRIE_MORE 0x010
92 RE_DEBUG_OPTIMISE 0x020
93 RE_DEBUG_OFFSETS 0x040
95 RE_DEBUG_OFFSETS_DEBUG 0x100
97 The directive C<use re 'debug'> and its equivalents are I<not> lexically
98 scoped, as the other directives are. They have both compile-time and run-time
101 See L<perlmodlib/Pragmatic Modules>.
105 # N.B. File::Basename contains a literal for 'taint' as a fallback. If
106 # taint is changed here, File::Basename must be updated as well.
108 taint => 0x00100000, # HINT_RE_TAINT
109 eval => 0x00200000, # HINT_RE_EVAL
113 eval { # Ignore errors
116 my $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
117 my $props = $ENV{PERL_RE_TC} || 'md,me,so,se,us,ue';
118 my @props = split /,/, $props;
119 my $colors = join "\t", map {$terminal->Tputs($_,1)} @props;
122 $ENV{PERL_RE_COLORS} = $colors;
133 OPTIMIZE => 32, # alias
136 OFFSETS_DEBUG => 256,
148 XSLoader::load('re');
157 Carp::carp("Useless use of \"re\" pragma");
159 foreach my $idx (0..$#_){
161 if ($s eq 'Debug' or $s eq 'Debugcolor') {
162 setcolor() if $s eq 'Debugcolor';
163 ${^RE_DEBUG_FLAGS} = 0 unless defined ${^RE_DEBUG_FLAGS};
164 for my $idx ($idx+1..$#_) {
165 if ($flags{$_[$idx]}) {
167 ${^RE_DEBUG_FLAGS} |= $flags{$_[$idx]};
168 ${^RE_DEBUG_FLAGS} |= 1
169 if $flags{$_[$idx]}>2;
171 ${^RE_DEBUG_FLAGS} &= ~ $flags{$_[$idx]};
175 Carp::carp("Unknown \"re\" Debug flag '$_[$idx]', possible flags: ",
176 join(", ",sort { $flags{$a} <=> $flags{$b} } keys %flags ) );
179 _load_unload($on ? 1 : ${^RE_DEBUG_FLAGS});
181 } elsif ($s eq 'debug' or $s eq 'debugcolor') {
182 setcolor() if $s eq 'debugcolor';
184 } elsif (exists $bitmask{$s}) {
185 $bits |= $bitmask{$s};
188 Carp::carp("Unknown \"re\" subpragma '$s' (known ones are: ",
189 join(', ', map {qq('$_')} 'debug', 'debugcolor', sort keys %bitmask),
203 $^H &= ~ bits(0, @_);