Debian Codegraph @

upstream/debian-unstable/man3/re.3perl

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