1re(3pm) Perl Programmers Reference Guide re(3pm)
2
6 re - Perl pragma to alter regular expression behaviour
7
9 use re 'taint';
10 ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
11 $pat = '(?{ $foo = 1 })';
13 use re 'eval';
14 /foo${pat}bar/; # won't fail (when not under -T switch)
15 {
17 no re 'taint'; # the default
18 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
19 no re 'eval'; # the default
21 /foo${pat}bar/; # disallowed (with or without -T switch)
22 }
23 use re 'debug'; # output debugging info during
25 /^(.*)$/s; # compile and run time
26 use re 'debugcolor'; # same as 'debug', but with colored output
29 ...
30 use re qw(Debug All); # Finer tuned debugging options.
32 use re qw(Debug More);
33 no re qw(Debug ALL); # Turn of all re debugging in this scope
34 use re qw(is_regexp regexp_pattern); # import utility functions
36 my ($pat,$mods)=regexp_pattern(qr/foo/i);
37 if (is_regexp($obj)) {
38 print "Got regexp: ",
39 scalar regexp_pattern($obj); # just as perl would stringify it
40 } # but no hassle with blessed re's.
41 (We use $^X in these examples because it's tainted by default.)
43
45 'taint' mode
46 When "use re 'taint'" is in effect, and a tainted string is the target
47 of a regex, the regex memories (or values returned by the m// operator
48 in list context) are tainted. This feature is useful when regex
49 operations on tainted data aren't meant to extract safe substrings, but
50 to perform other transformations.
51 'eval' mode
53 When "use re 'eval'" is in effect, a regex is allowed to contain "(?{
54 ... })" zero-width assertions even if regular expression contains
55 variable interpolation. That is normally disallowed, since it is a
56 potential security risk. Note that this pragma is ignored when the
57 regular expression is obtained from tainted data, i.e. evaluation is
58 always disallowed with tainted regular expressions. See "(?{ code })"
59 in perlre.
60 For the purpose of this pragma, interpolation of precompiled regular
62 expressions (i.e., the result of "qr//") is not considered variable
63 interpolation. Thus:
64 /foo${pat}bar/
66 is allowed if $pat is a precompiled regular expression, even if $pat
68 contains "(?{ ... })" assertions.
69 'debug' mode
71 When "use re 'debug'" is in effect, perl emits debugging messages when
72 compiling and using regular expressions. The output is the same as
73 that obtained by running a "-DDEBUGGING"-enabled perl interpreter with
74 the -Dr switch. It may be quite voluminous depending on the complexity
75 of the match. Using "debugcolor" instead of "debug" enables a form of
76 output that can be used to get a colorful display on terminals that
77 understand termcap color sequences. Set $ENV{PERL_RE_TC} to a comma-
78 separated list of "termcap" properties to use for highlighting strings
79 on/off, pre-point part on/off. See "Debugging regular expressions" in
80 perldebug for additional info.
81 As of 5.9.5 the directive "use re 'debug'" and its equivalents are
83 lexically scoped, as the other directives are. However they have both
84 compile-time and run-time effects.
85 See "Pragmatic Modules" in perlmodlib.
87 'Debug' mode
89 Similarly "use re 'Debug'" produces debugging output, the difference
90 being that it allows the fine tuning of what debugging output will be
91 emitted. Options are divided into three groups, those related to
92 compilation, those related to execution and those related to special
93 purposes. The options are as follows:
94 Compile related options
96 COMPILE
97 Turns on all compile related debug options.
98 PARSE
100 Turns on debug output related to the process of parsing the
101 pattern.
102 OPTIMISE
104 Enables output related to the optimisation phase of
105 compilation.
106 TRIEC
108 Detailed info about trie compilation.
109 DUMP
111 Dump the final program out after it is compiled and optimised.
112 Execute related options
114 EXECUTE
115 Turns on all execute related debug options.
116 MATCH
118 Turns on debugging of the main matching loop.
119 TRIEE
121 Extra debugging of how tries execute.
122 INTUIT
124 Enable debugging of start point optimisations.
125 Extra debugging options
127 EXTRA
128 Turns on all "extra" debugging options.
129 BUFFERS
131 Enable debugging the capture buffer storage during match.
132 Warning, this can potentially produce extremely large output.
133 TRIEM
135 Enable enhanced TRIE debugging. Enhances both TRIEE and TRIEC.
136 STATE
138 Enable debugging of states in the engine.
139 STACK
141 Enable debugging of the recursion stack in the engine. Enabling
142 or disabling this option automatically does the same for
143 debugging states as well. This output from this can be quite
144 large.
145 OPTIMISEM
147 Enable enhanced optimisation debugging and start point
148 optimisations. Probably not useful except when debugging the
149 regex engine itself.
150 OFFSETS
152 Dump offset information. This can be used to see how regops
153 correlate to the pattern. Output format is
154 NODENUM:POSITION[LENGTH]
156 Where 1 is the position of the first char in the string. Note
158 that position can be 0, or larger than the actual length of the
159 pattern, likewise length can be zero.
160 OFFSETSDBG
162 Enable debugging of offsets information. This emits copious
163 amounts of trace information and doesn't mesh well with other
164 debug options.
165 Almost definitely only useful to people hacking on the offsets
167 part of the debug engine.
168 Other useful flags
170 These are useful shortcuts to save on the typing.
171 ALL Enable all options at once except OFFSETS, OFFSETSDBG and
173 BUFFERS
174 All Enable DUMP and all execute options. Equivalent to:
176 use re 'debug';
178 MORE
180 More
181 Enable TRIEM and all execute compile and execute options.
182 As of 5.9.5 the directive "use re 'debug'" and its equivalents are
184 lexically scoped, as the other directives are. However they have both
185 compile-time and run-time effects.
186 Exportable Functions
188 As of perl 5.9.5 're' debug contains a number of utility functions that
189 may be optionally exported into the caller's namespace. They are listed
190 below.
191 is_regexp($ref)
193 Returns true if the argument is a compiled regular expression as
194 returned by "qr//", false if it is not.
195 This function will not be confused by overloading or blessing. In
197 internals terms, this extracts the regexp pointer out of the
198 PERL_MAGIC_qr structure so it it cannot be fooled.
199 regexp_pattern($ref)
201 If the argument is a compiled regular expression as returned by
202 "qr//", then this function returns the pattern.
203 In list context it returns a two element list, the first element
205 containing the pattern and the second containing the modifiers used
206 when the pattern was compiled.
207 my ($pat, $mods) = regexp_pattern($ref);
209 In scalar context it returns the same as perl would when
211 strigifying a raw "qr//" with the same pattern inside. If the
212 argument is not a compiled reference then this routine returns
213 false but defined in scalar context, and the empty list in list
214 context. Thus the following
215 if (regexp_pattern($ref) eq '(?i-xsm:foo)')
217 will be warning free regardless of what $ref actually is.
219 Like "is_regexp" this function will not be confused by overloading
221 or blessing of the object.
222 regmust($ref)
224 If the argument is a compiled regular expression as returned by
225 "qr//", then this function returns what the optimiser consiers to
226 be the longest anchored fixed string and longest floating fixed
227 string in the pattern.
228 A fixed string is defined as being a substring that must appear for
230 the pattern to match. An anchored fixed string is a fixed string
231 that must appear at a particular offset from the beginning of the
232 match. A floating fixed string is defined as a fixed string that
233 can appear at any point in a range of positions relative to the
234 start of the match. For example,
235 my $qr = qr/here .* there/x;
237 my ($anchored, $floating) = regmust($qr);
238 print "anchored:'$anchored'\nfloating:'$floating'\n";
239 results in
241 anchored:'here'
243 floating:'there'
244 Because the "here" is before the ".*" in the pattern, its position
246 can be determined exactly. That's not true, however, for the
247 "there"; it could appear at any point after where the anchored
248 string appeared. Perl uses both for its optimisations, prefering
249 the longer, or, if they are equal, the floating.
250 NOTE: This may not necessarily be the definitive longest anchored
252 and floating string. This will be what the optimiser of the Perl
253 that you are using thinks is the longest. If you believe that the
254 result is wrong please report it via the perlbug utility.
255 regname($name,$all)
257 Returns the contents of a named buffer of the last successful
258 match. If $all is true, then returns an array ref containing one
259 entry per buffer, otherwise returns the first defined buffer.
260 regnames($all)
262 Returns a list of all of the named buffers defined in the last
263 successful match. If $all is true, then it returns all names
264 defined, if not it returns only names which were involved in the
265 match.
266 regnames_count()
268 Returns the number of distinct names defined in the pattern used
269 for the last successful match.
270 Note: this result is always the actual number of distinct named
272 buffers defined, it may not actually match that which is returned
273 by "regnames()" and related routines when those routines have not
274 been called with the $all parameter set.
275
277 "Pragmatic Modules" in perlmodlib.
278perl v5.10.1 2017-03-22 re(3pm)