Debian Codegraph @

upstream/opensuse-tumbleweed/man3/re.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "re 3pm"
61 .TH re 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 re \- Perl pragma to alter regular expression behaviour
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use re \*(Aqtaint\*(Aq;
72 \& ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
73 \&
74 \& $pat = \*(Aq(?{ $foo = 1 })\*(Aq;
75 \& use re \*(Aqeval\*(Aq;
76 \& /foo${pat}bar/; # won\*(Aqt fail (when not under \-T
77 \& # switch)
78 \&
79 \& {
80 \& no re \*(Aqtaint\*(Aq; # the default
81 \& ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
82 \&
83 \& no re \*(Aqeval\*(Aq; # the default
84 \& /foo${pat}bar/; # disallowed (with or without \-T
85 \& # switch)
86 \& }
87 \&
88 \& use re \*(Aqstrict\*(Aq; # Raise warnings for more conditions
89 \&
90 \& use re \*(Aq/ix\*(Aq;
91 \& "FOO" =~ / foo /; # /ix implied
92 \& no re \*(Aq/x\*(Aq;
93 \& "FOO" =~ /foo/; # just /i implied
94 \&
95 \& use re \*(Aqdebug\*(Aq; # output debugging info during
96 \& /^(.*)$/s; # compile and run time
97 \&
98 \&
99 \& use re \*(Aqdebugcolor\*(Aq; # same as \*(Aqdebug\*(Aq, but with colored
100 \& # output
101 \& ...
102 \&
103 \& use re qw(Debug All); # Same as "use re \*(Aqdebug\*(Aq", but you
104 \& # can use "Debug" with things other
105 \& # than \*(AqAll\*(Aq
106 \& use re qw(Debug More); # \*(AqAll\*(Aq plus output more details
107 \& no re qw(Debug ALL); # Turn on (almost) all re debugging
108 \& # in this scope
109 \&
110 \& use re qw(is_regexp regexp_pattern); # import utility functions
111 \& my ($pat,$mods)=regexp_pattern(qr/foo/i);
112 \& if (is_regexp($obj)) {
113 \& print "Got regexp: ",
114 \& scalar regexp_pattern($obj); # just as perl would stringify
115 \& } # it but no hassle with blessed
116 \& # re\*(Aqs.
117 .Ve
118 .PP
119 (We use $^X in these examples because it\*(Aqs tainted by default.)
120 .SH DESCRIPTION
121 .IX Header "DESCRIPTION"
122 .SS "\*(Aqtaint\*(Aq mode"
123 .IX Subsection "'taint' mode"
124 When \f(CW\*(C`use re \*(Aqtaint\*(Aq\*(C'\fR is in effect, and a tainted string is the target
125 of a regexp, the regexp memories (or values returned by the m// operator
126 in list context) are tainted. This feature is useful when regexp operations
127 on tainted data aren\*(Aqt meant to extract safe substrings, but to perform
128 other transformations.
129 .SS "\*(Aqeval\*(Aq mode"
130 .IX Subsection "'eval' mode"
131 When \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR is in effect, a regexp is allowed to contain
132 \&\f(CW\*(C`(?{ ... })\*(C'\fR zero\-width assertions and \f(CW\*(C`(??{ ... })\*(C'\fR postponed
133 subexpressions that are derived from variable interpolation, rather than
134 appearing literally within the regexp. That is normally disallowed, since
135 it is a
136 potential security risk. Note that this pragma is ignored when the regular
137 expression is obtained from tainted data, i.e. evaluation is always
138 disallowed with tainted regular expressions. See "(?{ code })" in perlre
139 and "(??{ code })" in perlre.
140 .PP
141 For the purpose of this pragma, interpolation of precompiled regular
142 expressions (i.e., the result of \f(CW\*(C`qr//\*(C'\fR) is \fInot\fR considered variable
143 interpolation. Thus:
144 .PP
145 .Vb 1
146 \& /foo${pat}bar/
147 .Ve
148 .PP
149 \&\fIis\fR allowed if \f(CW$pat\fR is a precompiled regular expression, even
150 if \f(CW$pat\fR contains \f(CW\*(C`(?{ ... })\*(C'\fR assertions or \f(CW\*(C`(??{ ... })\*(C'\fR subexpressions.
151 .SS "\*(Aqstrict\*(Aq mode"
152 .IX Subsection "'strict' mode"
153 Note that this is an experimental feature which may be changed or removed in a
154 future Perl release.
155 .PP
156 When \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR is in effect, stricter checks are applied than
157 otherwise when compiling regular expressions patterns. These may cause more
158 warnings to be raised than otherwise, and more things to be fatal instead of
159 just warnings. The purpose of this is to find and report at compile time some
160 things, which may be legal, but have a reasonable possibility of not being the
161 programmer\*(Aqs actual intent. This automatically turns on the \f(CW"regexp"\fR
162 warnings category (if not already on) within its scope.
163 .PP
164 As an example of something that is caught under \f(CW\*(Aqstrict\*(Aq\fR, but not
165 otherwise, is the pattern
166 .PP
167 .Vb 1
168 \& qr/\exABC/
169 .Ve
170 .PP
171 The \f(CW"\ex"\fR construct without curly braces should be followed by exactly two
172 hex digits; this one is followed by three. This currently evaluates as
173 equivalent to
174 .PP
175 .Vb 1
176 \& qr/\ex{AB}C/
177 .Ve
178 .PP
179 that is, the character whose code point value is \f(CW0xAB\fR, followed by the
180 letter \f(CW\*(C`C\*(C'\fR. But since \f(CW\*(C`C\*(C'\fR is a hex digit, there is a reasonable chance
181 that the intent was
182 .PP
183 .Vb 1
184 \& qr/\ex{ABC}/
185 .Ve
186 .PP
187 that is the single character at \f(CW0xABC\fR. Under \f(CW\*(Aqstrict\*(Aq\fR it is an error to
188 not follow \f(CW\*(C`\ex\*(C'\fR with exactly two hex digits. When not under \f(CW\*(Aqstrict\*(Aq\fR a
189 warning is generated if there is only one hex digit, and no warning is raised
190 if there are more than two.
191 .PP
192 It is expected that what exactly \f(CW\*(Aqstrict\*(Aq\fR does will evolve over time as we
193 gain experience with it. This means that programs that compile under it in
194 today\*(Aqs Perl may not compile, or may have more or fewer warnings, in future
195 Perls. There is no backwards compatibility promises with regards to it. Also
196 there are already proposals for an alternate syntax for enabling it. For
197 these reasons, using it will raise a \f(CW\*(C`experimental::re_strict\*(C'\fR class warning,
198 unless that category is turned off.
199 .PP
200 Note that if a pattern compiled within \f(CW\*(Aqstrict\*(Aq\fR is recompiled, say by
201 interpolating into another pattern, outside of \f(CW\*(Aqstrict\*(Aq\fR, it is not checked
202 again for strictness. This is because if it works under strict it must work
203 under non\-strict.
204 .SS "\*(Aq/flags\*(Aq mode"
205 .IX Subsection "'/flags' mode"
206 When \f(CW\*(C`use re \*(Aq/\fR\f(CIflags\fR\f(CW\*(Aq\*(C'\fR is specified, the given \fIflags\fR are automatically
207 added to every regular expression till the end of the lexical scope.
208 \&\fIflags\fR can be any combination of
209 \&\f(CW\*(Aqa\*(Aq\fR,
210 \&\f(CW\*(Aqaa\*(Aq\fR,
211 \&\f(CW\*(Aqd\*(Aq\fR,
212 \&\f(CW\*(Aqi\*(Aq\fR,
213 \&\f(CW\*(Aql\*(Aq\fR,
214 \&\f(CW\*(Aqm\*(Aq\fR,
215 \&\f(CW\*(Aqn\*(Aq\fR,
216 \&\f(CW\*(Aqp\*(Aq\fR,
217 \&\f(CW\*(Aqs\*(Aq\fR,
218 \&\f(CW\*(Aqu\*(Aq\fR,
219 \&\f(CW\*(Aqx\*(Aq\fR,
220 and/or
221 \&\f(CW\*(Aqxx\*(Aq\fR.
222 .PP
223 \&\f(CW\*(C`no re \*(Aq/\fR\f(CIflags\fR\f(CW\*(Aq\*(C'\fR will turn off the effect of \f(CW\*(C`use re \*(Aq/\fR\f(CIflags\fR\f(CW\*(Aq\*(C'\fR for the
224 given flags.
225 .PP
226 For example, if you want all your regular expressions to have /msxx on by
227 default, simply put
228 .PP
229 .Vb 1
230 \& use re \*(Aq/msxx\*(Aq;
231 .Ve
232 .PP
233 at the top of your code.
234 .PP
235 The character set \f(CW\*(C`/adul\*(C'\fR flags cancel each other out. So, in this example,
236 .PP
237 .Vb 4
238 \& use re "/u";
239 \& "ss" =~ /\exdf/;
240 \& use re "/d";
241 \& "ss" =~ /\exdf/;
242 .Ve
243 .PP
244 the second \f(CW\*(C`use re\*(C'\fR does an implicit \f(CW\*(C`no re \*(Aq/u\*(Aq\*(C'\fR.
245 .PP
246 Similarly,
247 .PP
248 .Vb 4
249 \& use re "/xx"; # Doubled\-x
250 \& ...
251 \& use re "/x"; # Single x from here on
252 \& ...
253 .Ve
254 .PP
255 Turning on one of the character set flags with \f(CW\*(C`use re\*(C'\fR takes precedence over the
256 \&\f(CW\*(C`locale\*(C'\fR pragma and the \*(Aqunicode_strings\*(Aq \f(CW\*(C`feature\*(C'\fR, for regular
257 expressions. Turning off one of these flags when it is active reverts to
258 the behaviour specified by whatever other pragmata are in scope. For
259 example:
260 .PP
261 .Vb 4
262 \& use feature "unicode_strings";
263 \& no re "/u"; # does nothing
264 \& use re "/l";
265 \& no re "/l"; # reverts to unicode_strings behaviour
266 .Ve
267 .PP
268 Default flags are applied to wherever a pattern is compiled with the exception
269 of the \f(CW\*(C`/x\*(C'\fR flag, which is not applied to patterns compiled from string arguments
270 to \f(CW\*(C`split\*(C'\fR. Thus \`use re "/x";\` does not affect the behaviour of \f(CW\*(C`split " "\*(C'\fR but
271 \&\fBdoes\fR affect the behavior of \f(CW\*(C`split / /\*(C'\fR.
272 .SS "\*(Aqdebug\*(Aq mode"
273 .IX Subsection "'debug' mode"
274 When \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR is in effect, perl emits debugging messages when
275 compiling and using regular expressions. The output is the same as that
276 obtained by running a \f(CW\*(C`\-DDEBUGGING\*(C'\fR\-enabled perl interpreter with the
277 \&\fB\-Dr\fR switch. It may be quite voluminous depending on the complexity
278 of the match. Using \f(CW\*(C`debugcolor\*(C'\fR instead of \f(CW\*(C`debug\*(C'\fR enables a
279 form of output that can be used to get a colorful display on terminals
280 that understand termcap color sequences. Set \f(CW$ENV{PERL_RE_TC}\fR to a
281 comma\-separated list of \f(CW\*(C`termcap\*(C'\fR properties to use for highlighting
282 strings on/off, pre\-point part on/off.
283 See "Debugging Regular Expressions" in perldebug for additional info.
284 .PP
285 \&\fBNOTE\fR that the exact format of the \f(CW\*(C`debug\*(C'\fR mode is \fBNOT\fR considered
286 to be an officially supported API of Perl. It is intended for debugging
287 only and may change as the core development team deems appropriate
288 without notice or deprecation in any release of Perl, major or minor.
289 Any documentation of the output is purely advisory.
290 .PP
291 As of 5.9.5 the directive \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR and its equivalents are
292 lexically scoped, as the other directives are. However they have both
293 compile\-time and run\-time effects.
294 .PP
295 See "Pragmatic Modules" in perlmodlib.
296 .SS "\*(AqDebug\*(Aq mode"
297 .IX Subsection "'Debug' mode"
298 Similarly \f(CW\*(C`use re \*(AqDebug\*(Aq\*(C'\fR produces debugging output, the difference
299 being that it allows the fine tuning of what debugging output will be
300 emitted. Options are divided into three groups, those related to
301 compilation, those related to execution and those related to special
302 purposes.
303 .PP
304 \&\fBNOTE\fR that the options provided under the \f(CW\*(C`Debug\*(C'\fR mode and the exact
305 format of the output they create is \fBNOT\fR considered to be an
306 officially supported API of Perl. It is intended for debugging only and
307 may change as the core development team deems appropriate without notice
308 or deprecation in any release of Perl, major or minor. Any documentation
309 of the format or options available is advisory only and is subject to
310 change without notice.
311 .PP
312 The options are as follows:
313 .IP "Compile related options" 4
314 .IX Item "Compile related options"
315 .RS 4
316 .PD 0
317 .IP COMPILE 4
318 .IX Item "COMPILE"
319 .PD
320 Turns on all non\-extra compile related debug options.
321 .IP PARSE 4
322 .IX Item "PARSE"
323 Turns on debug output related to the process of parsing the pattern.
324 .IP OPTIMISE 4
325 .IX Item "OPTIMISE"
326 Enables output related to the optimisation phase of compilation.
327 .IP TRIEC 4
328 .IX Item "TRIEC"
329 Detailed info about trie compilation.
330 .IP DUMP 4
331 .IX Item "DUMP"
332 Dump the final program out after it is compiled and optimised.
333 .IP FLAGS 4
334 .IX Item "FLAGS"
335 Dump the flags associated with the program
336 .IP TEST 4
337 .IX Item "TEST"
338 Print output intended for testing the internals of the compile process
339 .RE
340 .RS 4
341 .RE
342 .IP "Execute related options" 4
343 .IX Item "Execute related options"
344 .RS 4
345 .PD 0
346 .IP EXECUTE 4
347 .IX Item "EXECUTE"
348 .PD
349 Turns on all non\-extra execute related debug options.
350 .IP MATCH 4
351 .IX Item "MATCH"
352 Turns on debugging of the main matching loop.
353 .IP TRIEE 4
354 .IX Item "TRIEE"
355 Extra debugging of how tries execute.
356 .IP INTUIT 4
357 .IX Item "INTUIT"
358 Enable debugging of start\-point optimisations.
359 .RE
360 .RS 4
361 .RE
362 .IP "Extra debugging options" 4
363 .IX Item "Extra debugging options"
364 .RS 4
365 .PD 0
366 .IP EXTRA 4
367 .IX Item "EXTRA"
368 .PD
369 Turns on all "extra" debugging options.
370 .IP BUFFERS 4
371 .IX Item "BUFFERS"
372 Enable debugging the capture group storage during match. Warning,
373 this can potentially produce extremely large output.
374 .IP TRIEM 4
375 .IX Item "TRIEM"
376 Enable enhanced TRIE debugging. Enhances both TRIEE
377 and TRIEC.
378 .IP STATE 4
379 .IX Item "STATE"
380 Enable debugging of states in the engine.
381 .IP STACK 4
382 .IX Item "STACK"
383 Enable debugging of the recursion stack in the engine. Enabling
384 or disabling this option automatically does the same for debugging
385 states as well. This output from this can be quite large.
386 .IP GPOS 4
387 .IX Item "GPOS"
388 Enable debugging of the \eG modifier.
389 .IP OPTIMISEM 4
390 .IX Item "OPTIMISEM"
391 Enable enhanced optimisation debugging and start\-point optimisations.
392 Probably not useful except when debugging the regexp engine itself.
393 .IP DUMP_PRE_OPTIMIZE 4
394 .IX Item "DUMP_PRE_OPTIMIZE"
395 Enable the dumping of the compiled pattern before the optimization phase.
396 .IP WILDCARD 4
397 .IX Item "WILDCARD"
398 When Perl encounters a wildcard subpattern, (see "Wildcards in
399 Property Values" in perlunicode), it suspends compilation of the main pattern, compiles the
400 subpattern, and then matches that against all legal possibilities to determine
401 the actual code points the subpattern matches. After that it adds these to
402 the main pattern, and continues its compilation.
403 .Sp
404 You may very well want to see how your subpattern gets compiled, but it is
405 likely of less use to you to see how Perl matches that against all the legal
406 possibilities, as that is under control of Perl, not you. Therefore, the
407 debugging information of the compilation portion is as specified by the other
408 options, but the debugging output of the matching portion is normally
409 suppressed.
410 .Sp
411 You can use the WILDCARD option to enable the debugging output of this
412 subpattern matching. Careful! This can lead to voluminous outputs, and it
413 may not make much sense to you what and why Perl is doing what it is.
414 But it may be helpful to you to see why things aren\*(Aqt going the way you
415 expect.
416 .Sp
417 Note that this option alone doesn\*(Aqt cause any debugging information to be
418 output. What it does is stop the normal suppression of execution\-related
419 debugging information during the matching portion of the compilation of
420 wildcards. You also have to specify which execution debugging information you
421 want, such as by also including the EXECUTE option.
422 .RE
423 .RS 4
424 .RE
425 .IP "Other useful flags" 4
426 .IX Item "Other useful flags"
427 These are useful shortcuts to save on the typing.
428 .RS 4
429 .IP ALL 4
430 .IX Item "ALL"
431 Enable all options at once except BUFFERS, WILDCARD, and DUMP_PRE_OPTIMIZE.
432 (To get every single option without exception, use both ALL and EXTRA, or
433 starting in 5.30 on a \f(CW\*(C`\-DDEBUGGING\*(C'\fR\-enabled perl interpreter, use
434 the \fB\-Drv\fR command\-line switches.)
435 .IP All 4
436 .IX Item "All"
437 Enable DUMP and all non\-extra execute options. Equivalent to:
438 .Sp
439 .Vb 1
440 \& use re \*(Aqdebug\*(Aq;
441 .Ve
442 .IP MORE 4
443 .IX Item "MORE"
444 .PD 0
445 .IP More 4
446 .IX Item "More"
447 .PD
448 Enable the options enabled by "All", plus STATE, TRIEC, and TRIEM.
449 .RE
450 .RS 4
451 .RE
452 .PP
453 As of 5.9.5 the directive \f(CW\*(C`use re \*(Aqdebug\*(Aq\*(C'\fR and its equivalents are
454 lexically scoped, as are the other directives. However they have both
455 compile\-time and run\-time effects.
456 .SS "Exportable Functions"
457 .IX Subsection "Exportable Functions"
458 As of perl 5.9.5, the \f(CW\*(C`re\*(C'\fR module contains a number of utility functions that
459 may be optionally exported into the caller\*(Aqs namespace. They are listed below.
460 .IP is_regexp($ref) 4
461 .IX Item "is_regexp($ref)"
462 Returns true if the argument is a compiled regular expression as returned
463 by \f(CW\*(C`qr//\*(C'\fR, false if it is not.
464 .Sp
465 This function will not be confused by overloading or blessing. In
466 internals terms, this extracts the regexp pointer out of the
467 PERL_MAGIC_qr structure so it cannot be fooled.
468 .IP regexp_pattern($ref) 4
469 .IX Item "regexp_pattern($ref)"
470 If the argument is a compiled regular expression as returned by \f(CW\*(C`qr//\*(C'\fR,
471 then this function returns the pattern.
472 .Sp
473 In list context it returns a two element list, the first element
474 containing the pattern and the second containing the modifiers used when
475 the pattern was compiled.
476 .Sp
477 .Vb 1
478 \& my ($pat, $mods) = regexp_pattern($ref);
479 .Ve
480 .Sp
481 In scalar context it returns the same as perl would when stringifying a raw
482 \&\f(CW\*(C`qr//\*(C'\fR with the same pattern inside. If the argument is not a compiled
483 reference then this routine returns false but defined in scalar context,
484 and the empty list in list context. Thus the following
485 .Sp
486 .Vb 1
487 \& if (regexp_pattern($ref) eq \*(Aq(?^i:foo)\*(Aq)
488 .Ve
489 .Sp
490 will be warning free regardless of what \f(CW$ref\fR actually is.
491 .Sp
492 Like \f(CW\*(C`is_regexp\*(C'\fR this function will not be confused by overloading
493 or blessing of the object.
494 .IP regname($name,$all) 4
495 .IX Item "regname($name,$all)"
496 Returns the contents of a named buffer of the last successful match. If
497 \&\f(CW$all\fR is true, then returns an array ref containing one entry per buffer,
498 otherwise returns the first defined buffer.
499 .IP regnames($all) 4
500 .IX Item "regnames($all)"
501 Returns a list of all of the named buffers defined in the last successful
502 match. If \f(CW$all\fR is true, then it returns all names defined, if not it returns
503 only names which were involved in the match.
504 .IP \fBregnames_count()\fR 4
505 .IX Item "regnames_count()"
506 Returns the number of distinct names defined in the pattern used
507 for the last successful match.
508 .Sp
509 \&\fBNote:\fR this result is always the actual number of distinct
510 named buffers defined, it may not actually match that which is
511 returned by \f(CWregnames()\fR and related routines when those routines
512 have not been called with the \f(CW$all\fR parameter set.
513 .IP regmust($ref) 4
514 .IX Item "regmust($ref)"
515 If the argument is a compiled regular expression as returned by \f(CW\*(C`qr//\*(C'\fR,
516 then this function returns what the optimiser considers to be the longest
517 anchored fixed string and longest floating fixed string in the pattern.
518 .Sp
519 A \fIfixed string\fR is defined as being a substring that must appear for the
520 pattern to match. An \fIanchored fixed string\fR is a fixed string that must
521 appear at a particular offset from the beginning of the match. A \fIfloating
522 fixed string\fR is defined as a fixed string that can appear at any point in
523 a range of positions relative to the start of the match. For example,
524 .Sp
525 .Vb 3
526 \& my $qr = qr/here .* there/x;
527 \& my ($anchored, $floating) = regmust($qr);
528 \& print "anchored:\*(Aq$anchored\*(Aq\enfloating:\*(Aq$floating\*(Aq\en";
529 .Ve
530 .Sp
531 results in
532 .Sp
533 .Vb 2
534 \& anchored:\*(Aqhere\*(Aq
535 \& floating:\*(Aqthere\*(Aq
536 .Ve
537 .Sp
538 Because the \f(CW\*(C`here\*(C'\fR is before the \f(CW\*(C`.*\*(C'\fR in the pattern, its position
539 can be determined exactly. That\*(Aqs not true, however, for the \f(CW\*(C`there\*(C'\fR;
540 it could appear at any point after where the anchored string appeared.
541 Perl uses both for its optimisations, preferring the longer, or, if they are
542 equal, the floating.
543 .Sp
544 \&\fBNOTE:\fR This may not necessarily be the definitive longest anchored and
545 floating string. This will be what the optimiser of the Perl that you
546 are using thinks is the longest. If you believe that the result is wrong
547 please report it via the perlbug utility.
548 .IP optimization($ref) 4
549 .IX Item "optimization($ref)"
550 If the argument is a compiled regular expression as returned by \f(CW\*(C`qr//\*(C'\fR,
551 then this function returns a hashref of the optimization information
552 discovered at compile time, so we can write tests around it. If any
553 other argument is given, returns \f(CW\*(C`undef\*(C'\fR.
554 .Sp
555 The hash contents are expected to change from time to time as we develop
556 new ways to optimize \- no assumption of stability should be made, not
557 even between minor versions of perl.
558 .Sp
559 For the current version, the hash will have the following contents:
560 .RS 4
561 .IP minlen 4
562 .IX Item "minlen"
563 An integer, the least number of characters in any string that can match.
564 .IP minlenret 4
565 .IX Item "minlenret"
566 An integer, the least number of characters that can be in \f(CW$&\fR after a
567 match. (Consider eg \f(CW\*(C` /ns(?=\ed)/ \*(C'\fR.)
568 .IP gofs 4
569 .IX Item "gofs"
570 An integer, the number of characters before \f(CWpos()\fR to start match at.
571 .IP noscan 4
572 .IX Item "noscan"
573 A boolean, \f(CW\*(C`TRUE\*(C'\fR to indicate that any anchored/floating substrings
574 found should not be used. (CHECKME: apparently this is set for an
575 anchored pattern with no floating substring, but never used.)
576 .IP isall 4
577 .IX Item "isall"
578 A boolean, \f(CW\*(C`TRUE\*(C'\fR to indicate that the optimizer information is all
579 that the regular expression contains, and thus one does not need to
580 enter the regexp runtime engine at all.
581 .IP "anchor SBOL" 4
582 .IX Item "anchor SBOL"
583 A boolean, \f(CW\*(C`TRUE\*(C'\fR if the pattern is anchored to start of string.
584 .IP "anchor MBOL" 4
585 .IX Item "anchor MBOL"
586 A boolean, \f(CW\*(C`TRUE\*(C'\fR if the pattern is anchored to any start of line
587 within the string.
588 .IP "anchor GPOS" 4
589 .IX Item "anchor GPOS"
590 A boolean, \f(CW\*(C`TRUE\*(C'\fR if the pattern is anchored to the end of the previous
591 match.
592 .IP skip 4
593 .IX Item "skip"
594 A boolean, \f(CW\*(C`TRUE\*(C'\fR if the start class can match only the first of a run.
595 .IP implicit 4
596 .IX Item "implicit"
597 A boolean, \f(CW\*(C`TRUE\*(C'\fR if a \f(CW\*(C`/.*/\*(C'\fR has been turned implicitly into a \f(CW\*(C`/^.*/\*(C'\fR.
598 .IP anchored/floating 4
599 .IX Item "anchored/floating"
600 A byte string representing an anchored or floating substring respectively
601 that any match must contain, or undef if no such substring was found, or
602 if the substring would require utf8 to represent.
603 .IP "anchored utf8/floating utf8" 4
604 .IX Item "anchored utf8/floating utf8"
605 A utf8 string representing an anchored or floating substring respectively
606 that any match must contain, or undef if no such substring was found, or
607 if the substring contains only 7\-bit ASCII characters.
608 .IP "anchored min offset/floating min offset" 4
609 .IX Item "anchored min offset/floating min offset"
610 An integer, the first offset in characters from a match location at which
611 we should look for the corresponding substring.
612 .IP "anchored max offset/floating max offset" 4
613 .IX Item "anchored max offset/floating max offset"
614 An integer, the last offset in characters from a match location at which
615 we should look for the corresponding substring.
616 .Sp
617 Ignored for anchored, so may be 0 or same as min.
618 .IP "anchored end shift/floating end shift" 4
619 .IX Item "anchored end shift/floating end shift"
620 FIXME: not sure what this is, something to do with lookbehind. regcomp.c
621 says:
622 When the final pattern is compiled and the data is moved from the
623 scan_data_t structure into the regexp structure the information
624 about lookbehind is factored in, with the information that would
625 have been lost precalculated in the end_shift field for the
626 associated string.
627 .IP checking 4
628 .IX Item "checking"
629 A constant string, one of "anchored", "floating" or "none" to indicate
630 which substring (if any) should be checked for first.
631 .IP stclass 4
632 .IX Item "stclass"
633 A string representation of a character class ("start class") that must
634 be the first character of any match.
635 .Sp
636 TODO: explain the representations.
637 .RE
638 .RS 4
639 .RE
640 .SH "SEE ALSO"
641 .IX Header "SEE ALSO"
642 "Pragmatic Modules" in perlmodlib.