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
15 # switch)
16 {
18 no re 'taint'; # the default
19 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
20 no re 'eval'; # the default
22 /foo${pat}bar/; # disallowed (with or without -T
23 # switch)
24 }
25 use re 'strict'; # Raise warnings for more conditions
27 use re '/ix';
29 "FOO" =~ / foo /; # /ix implied
30 no re '/x';
31 "FOO" =~ /foo/; # just /i implied
32 use re 'debug'; # output debugging info during
34 /^(.*)$/s; # compile and run time
35 use re 'debugcolor'; # same as 'debug', but with colored
38 # output
39 ...
40 use re qw(Debug All); # Same as "use re 'debug'", but you
42 # can use "Debug" with things other
43 # than 'All'
44 use re qw(Debug More); # 'All' plus output more details
45 no re qw(Debug ALL); # Turn on (almost) all re debugging
46 # in this scope
47 use re qw(is_regexp regexp_pattern); # import utility functions
49 my ($pat,$mods)=regexp_pattern(qr/foo/i);
50 if (is_regexp($obj)) {
51 print "Got regexp: ",
52 scalar regexp_pattern($obj); # just as perl would stringify
53 } # it but no hassle with blessed
54 # re's.
55 (We use $^X in these examples because it's tainted by default.)
57
59 'taint' mode
60 When "use re 'taint'" is in effect, and a tainted string is the target
61 of a regexp, the regexp memories (or values returned by the m//
62 operator in list context) are tainted. This feature is useful when
63 regexp operations on tainted data aren't meant to extract safe
64 substrings, but to perform other transformations.
65 'eval' mode
67 When "use re 'eval'" is in effect, a regexp is allowed to contain "(?{
68 ... })" zero-width assertions and "(??{ ... })" postponed
69 subexpressions that are derived from variable interpolation, rather
70 than appearing literally within the regexp. That is normally
71 disallowed, since it is a potential security risk. Note that this
72 pragma is ignored when the regular expression is obtained from tainted
73 data, i.e. evaluation is always disallowed with tainted regular
74 expressions. See "(?{ code })" in perlre and "(??{ code })" in perlre.
75 For the purpose of this pragma, interpolation of precompiled regular
77 expressions (i.e., the result of "qr//") is not considered variable
78 interpolation. Thus:
79 /foo${pat}bar/
81 is allowed if $pat is a precompiled regular expression, even if $pat
83 contains "(?{ ... })" assertions or "(??{ ... })" subexpressions.
84 'strict' mode
86 Note that this is an experimental feature which may be changed or
87 removed in a future Perl release.
88 When "use re 'strict'" is in effect, stricter checks are applied than
90 otherwise when compiling regular expressions patterns. These may cause
91 more warnings to be raised than otherwise, and more things to be fatal
92 instead of just warnings. The purpose of this is to find and report at
93 compile time some things, which may be legal, but have a reasonable
94 possibility of not being the programmer's actual intent. This
95 automatically turns on the "regexp" warnings category (if not already
96 on) within its scope.
97 As an example of something that is caught under ""strict'", but not
99 otherwise, is the pattern
100 qr/\xABC/
102 The "\x" construct without curly braces should be followed by exactly
104 two hex digits; this one is followed by three. This currently
105 evaluates as equivalent to
106 qr/\x{AB}C/
108 that is, the character whose code point value is 0xAB, followed by the
110 letter "C". But since "C" is a a hex digit, there is a reasonable
111 chance that the intent was
112 qr/\x{ABC}/
114 that is the single character at 0xABC. Under 'strict' it is an error
116 to not follow "\x" with exactly two hex digits. When not under
117 'strict' a warning is generated if there is only one hex digit, and no
118 warning is raised if there are more than two.
119 It is expected that what exactly 'strict' does will evolve over time as
121 we gain experience with it. This means that programs that compile
122 under it in today's Perl may not compile, or may have more or fewer
123 warnings, in future Perls. There is no backwards compatibility
124 promises with regards to it. Also there are already proposals for an
125 alternate syntax for enabling it. For these reasons, using it will
126 raise a "experimental::re_strict" class warning, unless that category
127 is turned off.
128 Note that if a pattern compiled within 'strict' is recompiled, say by
130 interpolating into another pattern, outside of 'strict', it is not
131 checked again for strictness. This is because if it works under strict
132 it must work under non-strict.
133 '/flags' mode
135 When "use re '/flags'" is specified, the given flags are automatically
136 added to every regular expression till the end of the lexical scope.
137 flags can be any combination of 'a', 'aa', 'd', 'i', 'l', 'm', 'n',
138 'p', 's', 'u', 'x', and/or 'xx'.
139 "no re '/flags'" will turn off the effect of "use re '/flags'" for the
141 given flags.
142 For example, if you want all your regular expressions to have /msxx on
144 by default, simply put
145 use re '/msxx';
147 at the top of your code.
149 The character set "/adul" flags cancel each other out. So, in this
151 example,
152 use re "/u";
154 "ss" =~ /\xdf/;
155 use re "/d";
156 "ss" =~ /\xdf/;
157 the second "use re" does an implicit "no re '/u'".
159 Similarly,
161 use re "/xx"; # Doubled-x
163 ...
164 use re "/x"; # Single x from here on
165 ...
166 Turning on one of the character set flags with "use re" takes
168 precedence over the "locale" pragma and the 'unicode_strings'
169 "feature", for regular expressions. Turning off one of these flags when
170 it is active reverts to the behaviour specified by whatever other
171 pragmata are in scope. For example:
172 use feature "unicode_strings";
174 no re "/u"; # does nothing
175 use re "/l";
176 no re "/l"; # reverts to unicode_strings behaviour
177 'debug' mode
179 When "use re 'debug'" is in effect, perl emits debugging messages when
180 compiling and using regular expressions. The output is the same as
181 that obtained by running a "-DDEBUGGING"-enabled perl interpreter with
182 the -Dr switch. It may be quite voluminous depending on the complexity
183 of the match. Using "debugcolor" instead of "debug" enables a form of
184 output that can be used to get a colorful display on terminals that
185 understand termcap color sequences. Set $ENV{PERL_RE_TC} to a comma-
186 separated list of "termcap" properties to use for highlighting strings
187 on/off, pre-point part on/off. See "Debugging Regular Expressions" in
188 perldebug for additional info.
189 As of 5.9.5 the directive "use re 'debug'" and its equivalents are
191 lexically scoped, as the other directives are. However they have both
192 compile-time and run-time effects.
193 See "Pragmatic Modules" in perlmodlib.
195 'Debug' mode
197 Similarly "use re 'Debug'" produces debugging output, the difference
198 being that it allows the fine tuning of what debugging output will be
199 emitted. Options are divided into three groups, those related to
200 compilation, those related to execution and those related to special
201 purposes. The options are as follows:
202 Compile related options
204 COMPILE
205 Turns on all compile related debug options.
206 PARSE
208 Turns on debug output related to the process of parsing the
209 pattern.
210 OPTIMISE
212 Enables output related to the optimisation phase of
213 compilation.
214 TRIEC
216 Detailed info about trie compilation.
217 DUMP
219 Dump the final program out after it is compiled and optimised.
220 FLAGS
222 Dump the flags associated with the program
223 TEST
225 Print output intended for testing the internals of the compile
226 process
227 Execute related options
229 EXECUTE
230 Turns on all execute related debug options.
231 MATCH
233 Turns on debugging of the main matching loop.
234 TRIEE
236 Extra debugging of how tries execute.
237 INTUIT
239 Enable debugging of start-point optimisations.
240 Extra debugging options
242 EXTRA
243 Turns on all "extra" debugging options.
244 BUFFERS
246 Enable debugging the capture group storage during match.
247 Warning, this can potentially produce extremely large output.
248 TRIEM
250 Enable enhanced TRIE debugging. Enhances both TRIEE and TRIEC.
251 STATE
253 Enable debugging of states in the engine.
254 STACK
256 Enable debugging of the recursion stack in the engine. Enabling
257 or disabling this option automatically does the same for
258 debugging states as well. This output from this can be quite
259 large.
260 GPOS
262 Enable debugging of the \G modifier.
263 OPTIMISEM
265 Enable enhanced optimisation debugging and start-point
266 optimisations. Probably not useful except when debugging the
267 regexp engine itself.
268 OFFSETS
270 Dump offset information. This can be used to see how regops
271 correlate to the pattern. Output format is
272 NODENUM:POSITION[LENGTH]
274 Where 1 is the position of the first char in the string. Note
276 that position can be 0, or larger than the actual length of the
277 pattern, likewise length can be zero.
278 OFFSETSDBG
280 Enable debugging of offsets information. This emits copious
281 amounts of trace information and doesn't mesh well with other
282 debug options.
283 Almost definitely only useful to people hacking on the offsets
285 part of the debug engine.
286 Other useful flags
288 These are useful shortcuts to save on the typing.
289 ALL Enable all options at once except OFFSETS, OFFSETSDBG and
291 BUFFERS. (To get every single option without exception, use
292 both ALL and EXTRA, or starting in 5.30 on a
293 "-DDEBUGGING"-enabled perl interpreter, use the -Drv command-
294 line switches.)
295 All Enable DUMP and all execute options. Equivalent to:
297 use re 'debug';
299 MORE
301 More
302 Enable the options enabled by "All", plus STATE, TRIEC, and
303 TRIEM.
304 As of 5.9.5 the directive "use re 'debug'" and its equivalents are
306 lexically scoped, as are the other directives. However they have both
307 compile-time and run-time effects.
308 Exportable Functions
310 As of perl 5.9.5 're' debug contains a number of utility functions that
311 may be optionally exported into the caller's namespace. They are listed
312 below.
313 is_regexp($ref)
315 Returns true if the argument is a compiled regular expression as
316 returned by "qr//", false if it is not.
317 This function will not be confused by overloading or blessing. In
319 internals terms, this extracts the regexp pointer out of the
320 PERL_MAGIC_qr structure so it cannot be fooled.
321 regexp_pattern($ref)
323 If the argument is a compiled regular expression as returned by
324 "qr//", then this function returns the pattern.
325 In list context it returns a two element list, the first element
327 containing the pattern and the second containing the modifiers used
328 when the pattern was compiled.
329 my ($pat, $mods) = regexp_pattern($ref);
331 In scalar context it returns the same as perl would when
333 stringifying a raw "qr//" with the same pattern inside. If the
334 argument is not a compiled reference then this routine returns
335 false but defined in scalar context, and the empty list in list
336 context. Thus the following
337 if (regexp_pattern($ref) eq '(?^i:foo)')
339 will be warning free regardless of what $ref actually is.
341 Like "is_regexp" this function will not be confused by overloading
343 or blessing of the object.
344 regmust($ref)
346 If the argument is a compiled regular expression as returned by
347 "qr//", then this function returns what the optimiser considers to
348 be the longest anchored fixed string and longest floating fixed
349 string in the pattern.
350 A fixed string is defined as being a substring that must appear for
352 the pattern to match. An anchored fixed string is a fixed string
353 that must appear at a particular offset from the beginning of the
354 match. A floating fixed string is defined as a fixed string that
355 can appear at any point in a range of positions relative to the
356 start of the match. For example,
357 my $qr = qr/here .* there/x;
359 my ($anchored, $floating) = regmust($qr);
360 print "anchored:'$anchored'\nfloating:'$floating'\n";
361 results in
363 anchored:'here'
365 floating:'there'
366 Because the "here" is before the ".*" in the pattern, its position
368 can be determined exactly. That's not true, however, for the
369 "there"; it could appear at any point after where the anchored
370 string appeared. Perl uses both for its optimisations, preferring
371 the longer, or, if they are equal, the floating.
372 NOTE: This may not necessarily be the definitive longest anchored
374 and floating string. This will be what the optimiser of the Perl
375 that you are using thinks is the longest. If you believe that the
376 result is wrong please report it via the perlbug utility.
377 regname($name,$all)
379 Returns the contents of a named buffer of the last successful
380 match. If $all is true, then returns an array ref containing one
381 entry per buffer, otherwise returns the first defined buffer.
382 regnames($all)
384 Returns a list of all of the named buffers defined in the last
385 successful match. If $all is true, then it returns all names
386 defined, if not it returns only names which were involved in the
387 match.
388 regnames_count()
390 Returns the number of distinct names defined in the pattern used
391 for the last successful match.
392 Note: this result is always the actual number of distinct named
394 buffers defined, it may not actually match that which is returned
395 by "regnames()" and related routines when those routines have not
396 been called with the $all parameter set.
397
399 "Pragmatic Modules" in perlmodlib.
400perl v5.30.2 2020-03-27 re(3pm)