1re(3pm)                Perl Programmers Reference Guide                re(3pm)
2
3
4

NAME

6       re - Perl pragma to alter regular expression behaviour
7

SYNOPSIS

9           use re 'taint';
10           ($x) = ($^X =~ /^(.*)$/s);     # $x is tainted here
11
12           $pat = '(?{ $foo = 1 })';
13           use re 'eval';
14           /foo${pat}bar/;                # won't fail (when not under -T
15                                          # switch)
16
17           {
18               no re 'taint';             # the default
19               ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
20
21               no re 'eval';              # the default
22               /foo${pat}bar/;            # disallowed (with or without -T
23                                          # switch)
24           }
25
26           use re 'strict';               # Raise warnings for more conditions
27
28           use re '/ix';
29           "FOO" =~ / foo /; # /ix implied
30           no re '/x';
31           "FOO" =~ /foo/; # just /i implied
32
33           use re 'debug';                # output debugging info during
34           /^(.*)$/s;                     # compile and run time
35
36
37           use re 'debugcolor';           # same as 'debug', but with colored
38                                          # output
39           ...
40
41           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
48           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
56       (We use $^X in these examples because it's tainted by default.)
57

DESCRIPTION

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
66   '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
76       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
80           /foo${pat}bar/
81
82       is allowed if $pat is a precompiled regular expression, even if $pat
83       contains "(?{ ... })" assertions or "(??{ ... })" subexpressions.
84
85   'strict' mode
86       Note that this is an experimental feature which may be changed or
87       removed in a future Perl release.
88
89       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
98       As an example of something that is caught under ""strict'", but not
99       otherwise, is the pattern
100
101        qr/\xABC/
102
103       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
107        qr/\x{AB}C/
108
109       that is, the character whose code point value is 0xAB, followed by the
110       letter "C".  But since "C" is a hex digit, there is a reasonable chance
111       that the intent was
112
113        qr/\x{ABC}/
114
115       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
120       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
129       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
134   '/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
140       "no re '/flags'" will turn off the effect of "use re '/flags'" for the
141       given flags.
142
143       For example, if you want all your regular expressions to have /msxx on
144       by default, simply put
145
146           use re '/msxx';
147
148       at the top of your code.
149
150       The character set "/adul" flags cancel each other out. So, in this
151       example,
152
153           use re "/u";
154           "ss" =~ /\xdf/;
155           use re "/d";
156           "ss" =~ /\xdf/;
157
158       the second "use re" does an implicit "no re '/u'".
159
160       Similarly,
161
162           use re "/xx";   # Doubled-x
163           ...
164           use re "/x";    # Single x from here on
165           ...
166
167       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
173           use feature "unicode_strings";
174           no re "/u"; # does nothing
175           use re "/l";
176           no re "/l"; # reverts to unicode_strings behaviour
177
178   '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
190       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
194       See "Pragmatic Modules" in perlmodlib.
195
196   '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
203       Compile related options
204           COMPILE
205               Turns on all non-extra compile related debug options.
206
207           PARSE
208               Turns on debug output related to the process of parsing the
209               pattern.
210
211           OPTIMISE
212               Enables output related to the optimisation phase of
213               compilation.
214
215           TRIEC
216               Detailed info about trie compilation.
217
218           DUMP
219               Dump the final program out after it is compiled and optimised.
220
221           FLAGS
222               Dump the flags associated with the program
223
224           TEST
225               Print output intended for testing the internals of the compile
226               process
227
228       Execute related options
229           EXECUTE
230               Turns on all non-extra execute related debug options.
231
232           MATCH
233               Turns on debugging of the main matching loop.
234
235           TRIEE
236               Extra debugging of how tries execute.
237
238           INTUIT
239               Enable debugging of start-point optimisations.
240
241       Extra debugging options
242           EXTRA
243               Turns on all "extra" debugging options.
244
245           BUFFERS
246               Enable debugging the capture group storage during match.
247               Warning, this can potentially produce extremely large output.
248
249           TRIEM
250               Enable enhanced TRIE debugging. Enhances both TRIEE and TRIEC.
251
252           STATE
253               Enable debugging of states in the engine.
254
255           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
261           GPOS
262               Enable debugging of the \G modifier.
263
264           OPTIMISEM
265               Enable enhanced optimisation debugging and start-point
266               optimisations.  Probably not useful except when debugging the
267               regexp engine itself.
268
269           OFFSETS
270               Dump offset information. This can be used to see how regops
271               correlate to the pattern. Output format is
272
273                  NODENUM:POSITION[LENGTH]
274
275               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
279           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
284               Almost definitely only useful to people hacking on the offsets
285               part of the debug engine.
286
287           DUMP_PRE_OPTIMIZE
288               Enable the dumping of the compiled pattern before the
289               optimization phase.
290
291           WILDCARD
292               When Perl encounters a wildcard subpattern, (see "Wildcards in
293               Property Values" in perlunicode), it suspends compilation of
294               the main pattern, compiles the subpattern, and then matches
295               that against all legal possibilities to determine the actual
296               code points the subpattern matches.  After that it adds these
297               to the main pattern, and continues its compilation.
298
299               You may very well want to see how your subpattern gets
300               compiled, but it is likely of less use to you to see how Perl
301               matches that against all the legal possibilities, as that is
302               under control of Perl, not you.   Therefore, the debugging
303               information of the compilation portion is as specified by the
304               other options, but the debugging output of the matching portion
305               is normally suppressed.
306
307               You can use the WILDCARD option to enable the debugging output
308               of this subpattern matching.  Careful!  This can lead to
309               voluminous outputs, and it may not make much sense to you what
310               and why Perl is doing what it is.  But it may be helpful to you
311               to see why things aren't going the way you expect.
312
313               Note that this option alone doesn't cause any debugging
314               information to be output.  What it does is stop the normal
315               suppression of execution-related debugging information during
316               the matching portion of the compilation of wildcards.  You also
317               have to specify which execution debugging information you want,
318               such as by also including the EXECUTE option.
319
320       Other useful flags
321           These are useful shortcuts to save on the typing.
322
323           ALL Enable all options at once except OFFSETS, OFFSETSDBG, BUFFERS,
324               WILDCARD, and DUMP_PRE_OPTIMIZE.  (To get every single option
325               without exception, use both ALL and EXTRA, or starting in 5.30
326               on a "-DDEBUGGING"-enabled perl interpreter, use the -Drv
327               command-line switches.)
328
329           All Enable DUMP and all non-extra execute options. Equivalent to:
330
331                 use re 'debug';
332
333           MORE
334           More
335               Enable the options enabled by "All", plus STATE, TRIEC, and
336               TRIEM.
337
338       As of 5.9.5 the directive "use re 'debug'" and its equivalents are
339       lexically scoped, as are the other directives.  However they have both
340       compile-time and run-time effects.
341
342   Exportable Functions
343       As of perl 5.9.5 're' debug contains a number of utility functions that
344       may be optionally exported into the caller's namespace. They are listed
345       below.
346
347       is_regexp($ref)
348           Returns true if the argument is a compiled regular expression as
349           returned by "qr//", false if it is not.
350
351           This function will not be confused by overloading or blessing. In
352           internals terms, this extracts the regexp pointer out of the
353           PERL_MAGIC_qr structure so it cannot be fooled.
354
355       regexp_pattern($ref)
356           If the argument is a compiled regular expression as returned by
357           "qr//", then this function returns the pattern.
358
359           In list context it returns a two element list, the first element
360           containing the pattern and the second containing the modifiers used
361           when the pattern was compiled.
362
363             my ($pat, $mods) = regexp_pattern($ref);
364
365           In scalar context it returns the same as perl would when
366           stringifying a raw "qr//" with the same pattern inside.  If the
367           argument is not a compiled reference then this routine returns
368           false but defined in scalar context, and the empty list in list
369           context. Thus the following
370
371               if (regexp_pattern($ref) eq '(?^i:foo)')
372
373           will be warning free regardless of what $ref actually is.
374
375           Like "is_regexp" this function will not be confused by overloading
376           or blessing of the object.
377
378       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
383       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
389       regnames_count()
390           Returns the number of distinct names defined in the pattern used
391           for the last successful match.
392
393           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
398       regmust($ref)
399           If the argument is a compiled regular expression as returned by
400           "qr//", then this function returns what the optimiser considers to
401           be the longest anchored fixed string and longest floating fixed
402           string in the pattern.
403
404           A fixed string is defined as being a substring that must appear for
405           the pattern to match. An anchored fixed string is a fixed string
406           that must appear at a particular offset from the beginning of the
407           match. A floating fixed string is defined as a fixed string that
408           can appear at any point in a range of positions relative to the
409           start of the match. For example,
410
411               my $qr = qr/here .* there/x;
412               my ($anchored, $floating) = regmust($qr);
413               print "anchored:'$anchored'\nfloating:'$floating'\n";
414
415           results in
416
417               anchored:'here'
418               floating:'there'
419
420           Because the "here" is before the ".*" in the pattern, its position
421           can be determined exactly. That's not true, however, for the
422           "there"; it could appear at any point after where the anchored
423           string appeared.  Perl uses both for its optimisations, preferring
424           the longer, or, if they are equal, the floating.
425
426           NOTE: This may not necessarily be the definitive longest anchored
427           and floating string. This will be what the optimiser of the Perl
428           that you are using thinks is the longest. If you believe that the
429           result is wrong please report it via the perlbug utility.
430
431       optimization($ref)
432           If the argument is a compiled regular expression as returned by
433           "qr//", then this function returns a hashref of the optimization
434           information discovered at compile time, so we can write tests
435           around it. If any other argument is given, returns "undef".
436
437           The hash contents are expected to change from time to time as we
438           develop new ways to optimize - no assumption of stability should be
439           made, not even between minor versions of perl.
440
441           For the current version, the hash will have the following contents:
442
443           minlen
444               An integer, the least number of characters in any string that
445               can match.
446
447           minlenret
448               An integer, the least number of characters that can be in $&
449               after a match. (Consider eg " /ns(?=\d)/ ".)
450
451           gofs
452               An integer, the number of characters before "pos()" to start
453               match at.
454
455           noscan
456               A boolean, "TRUE" to indicate that any anchored/floating
457               substrings found should not be used. (CHECKME: apparently this
458               is set for an anchored pattern with no floating substring, but
459               never used.)
460
461           isall
462               A boolean, "TRUE" to indicate that the optimizer information is
463               all that the regular expression contains, and thus one does not
464               need to enter the regexp runtime engine at all.
465
466           anchor SBOL
467               A boolean, "TRUE" if the pattern is anchored to start of
468               string.
469
470           anchor MBOL
471               A boolean, "TRUE" if the pattern is anchored to any start of
472               line within the string.
473
474           anchor GPOS
475               A boolean, "TRUE" if the pattern is anchored to the end of the
476               previous match.
477
478           skip
479               A boolean, "TRUE" if the start class can match only the first
480               of a run.
481
482           implicit
483               A boolean, "TRUE" if a "/.*/" has been turned implicitly into a
484               "/^.*/".
485
486           anchored/floating
487               A byte string representing an anchored or floating substring
488               respectively that any match must contain, or undef if no such
489               substring was found, or if the substring would require utf8 to
490               represent.
491
492           anchored utf8/floating utf8
493               A utf8 string representing an anchored or floating substring
494               respectively that any match must contain, or undef if no such
495               substring was found, or if the substring contains only 7-bit
496               ASCII characters.
497
498           anchored min offset/floating min offset
499               An integer, the first offset in characters from a match
500               location at which we should look for the corresponding
501               substring.
502
503           anchored max offset/floating max offset
504               An integer, the last offset in characters from a match location
505               at which we should look for the corresponding substring.
506
507               Ignored for anchored, so may be 0 or same as min.
508
509           anchored end shift/floating end shift
510               FIXME: not sure what this is, something to do with lookbehind.
511               regcomp.c says:
512                   When the final pattern is compiled and the data is moved
513               from the
514                   scan_data_t structure into the regexp structure the
515               information
516                   about lookbehind is factored in, with the information that
517               would
518                   have been lost precalculated in the end_shift field for the
519                   associated string.
520
521           checking
522               A constant string, one of "anchored", "floating" or "none" to
523               indicate which substring (if any) should be checked for first.
524
525           stclass
526               A string representation of a character class ("start class")
527               that must be the first character of any match.
528
529               TODO: explain the representations.
530

SEE ALSO

532       "Pragmatic Modules" in perlmodlib.
533
534
535
536perl v5.34.1                      2022-03-15                           re(3pm)
Impressum