This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ext/re/re.pm: Fix up setting debug option defaults
[perl5.git] / ext / re / re.pm
CommitLineData
b3eb6a9b
GS
1package re;
2
99cc5cc6 3# pragma for controlling the regexp engine
de8c5301
YO
4use strict;
5use warnings;
6
51bd1941 7our $VERSION = "0.39";
de8c5301 8our @ISA = qw(Exporter);
ec781434 9our @EXPORT_OK = ('regmust',
192c1e27
JH
10 qw(is_regexp regexp_pattern
11 regname regnames regnames_count));
de8c5301
YO
12our %EXPORT_OK = map { $_ => 1 } @EXPORT_OK;
13
de8c5301
YO
14my %bitmask = (
15 taint => 0x00100000, # HINT_RE_TAINT
16 eval => 0x00200000, # HINT_RE_EVAL
17);
18
1e215989
FC
19my $flags_hint = 0x02000000; # HINT_RE_FLAGS
20my $PMMOD_SHIFT = 0;
21my %reflags = (
22 m => 1 << ($PMMOD_SHIFT + 0),
23 s => 1 << ($PMMOD_SHIFT + 1),
24 i => 1 << ($PMMOD_SHIFT + 2),
25 x => 1 << ($PMMOD_SHIFT + 3),
77c8f263 26 xx => 1 << ($PMMOD_SHIFT + 4),
41d7c59e
MH
27 n => 1 << ($PMMOD_SHIFT + 5),
28 p => 1 << ($PMMOD_SHIFT + 6),
67cdf558 29 strict => 1 << ($PMMOD_SHIFT + 10),
1e215989 30# special cases:
1e215989 31 d => 0,
a62b1201
KW
32 l => 1,
33 u => 2,
cfaf538b 34 a => 3,
b4ab316d 35 aa => 4,
1e215989
FC
36);
37
de8c5301
YO
38sub setcolor {
39 eval { # Ignore errors
40 require Term::Cap;
41
42 my $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
43 my $props = $ENV{PERL_RE_TC} || 'md,me,so,se,us,ue';
44 my @props = split /,/, $props;
45 my $colors = join "\t", map {$terminal->Tputs($_,1)} @props;
46
47 $colors =~ s/\0//g;
48 $ENV{PERL_RE_COLORS} = $colors;
49 };
50 if ($@) {
51 $ENV{PERL_RE_COLORS} ||= qq'\t\t> <\t> <\t\t';
52 }
53
54}
55
56my %flags = (
65064416
KW
57 COMPILE => 0x0000FF,
58 PARSE => 0x000001,
59 OPTIMISE => 0x000002,
60 TRIEC => 0x000004,
61 DUMP => 0x000008,
62 FLAGS => 0x000010,
63 TEST => 0x000020,
de8c5301 64
65064416
KW
65 EXECUTE => 0x00FF00,
66 INTUIT => 0x000100,
67 MATCH => 0x000200,
68 TRIEE => 0x000400,
de8c5301 69
51bd1941 70 EXTRA => 0x3FF0000,
fd41b2d1
KW
71 TRIEM => 0x0010000,
72 OFFSETS => 0x0020000,
73 OFFSETSDBG => 0x0040000,
74 STATE => 0x0080000,
75 OPTIMISEM => 0x0100000,
76 STACK => 0x0280000,
77 BUFFERS => 0x0400000,
78 GPOS => 0x0800000,
79 DUMP_PRE_OPTIMIZE => 0x1000000,
51bd1941 80 WILDCARD => 0x2000000,
de8c5301 81);
51bd1941
KW
82$flags{ALL} = -1 & ~($flags{OFFSETS}
83 |$flags{OFFSETSDBG}
84 |$flags{BUFFERS}
85 |$flags{DUMP_PRE_OPTIMIZE}
86 |$flags{WILDCARD}
87 );
de8c5301 88$flags{All} = $flags{all} = $flags{DUMP} | $flags{EXECUTE};
2c296965 89$flags{Extra} = $flags{EXECUTE} | $flags{COMPILE} | $flags{GPOS};
65064416
KW
90$flags{More} = $flags{MORE} =
91 $flags{All} | $flags{TRIEC} | $flags{TRIEM} | $flags{STATE};
de8c5301
YO
92$flags{State} = $flags{DUMP} | $flags{EXECUTE} | $flags{STATE};
93$flags{TRIE} = $flags{DUMP} | $flags{EXECUTE} | $flags{TRIEC};
94
ec781434
NC
95if (defined &DynaLoader::boot_DynaLoader) {
96 require XSLoader;
da4061d3 97 XSLoader::load();
de8c5301 98}
ec781434
NC
99# else we're miniperl
100# We need to work for miniperl, because the XS toolchain uses Text::Wrap, which
101# uses re 'taint'.
de8c5301
YO
102
103sub _load_unload {
104 my ($on)= @_;
105 if ($on) {
ec781434
NC
106 # We call install() every time, as if we didn't, we wouldn't
107 # "see" any changes to the color environment var since
108 # the last time it was called.
109
110 # install() returns an integer, which if casted properly
99cc5cc6 111 # in C resolves to a structure containing the regexp
ec781434
NC
112 # hooks. Setting it to a random integer will guarantee
113 # segfaults.
114 $^H{regcomp} = install();
de8c5301
YO
115 } else {
116 delete $^H{regcomp};
117 }
118}
119
120sub bits {
121 my $on = shift;
122 my $bits = 0;
3ab1d973 123 my $turning_all_off = ! @_ && ! $on;
d022bb19 124 my $seen_Debug = 0;
3ab1d973
KW
125 if ($turning_all_off) {
126
127 # Pretend were called with certain parameters, which are best dealt
c9a74c77 128 # with that way.
3ab1d973
KW
129 push @_, keys %bitmask; # taint and eval
130 push @_, 'strict';
131 }
132
133 # Process each subpragma parameter
1e215989 134 ARG:
de8c5301
YO
135 foreach my $idx (0..$#_){
136 my $s=$_[$idx];
137 if ($s eq 'Debug' or $s eq 'Debugcolor') {
d022bb19
KW
138 if (! $seen_Debug) {
139 $seen_Debug = 1;
140
141 # Reset to nothing, and then add what follows. $seen_Debug
142 # allows, though unlikely someone would do it, more than one
143 # Debug and flags in the arguments
144 ${^RE_DEBUG_FLAGS} = 0;
145 }
de8c5301 146 setcolor() if $s =~/color/i;
de8c5301
YO
147 for my $idx ($idx+1..$#_) {
148 if ($flags{$_[$idx]}) {
149 if ($on) {
150 ${^RE_DEBUG_FLAGS} |= $flags{$_[$idx]};
151 } else {
152 ${^RE_DEBUG_FLAGS} &= ~ $flags{$_[$idx]};
153 }
154 } else {
155 require Carp;
156 Carp::carp("Unknown \"re\" Debug flag '$_[$idx]', possible flags: ",
157 join(", ",sort keys %flags ) );
158 }
159 }
160 _load_unload($on ? 1 : ${^RE_DEBUG_FLAGS});
161 last;
162 } elsif ($s eq 'debug' or $s eq 'debugcolor') {
d022bb19
KW
163
164 # These default flags should be kept in sync with the same values
165 # in regcomp.h
166 ${^RE_DEBUG_FLAGS} = $flags{'EXECUTE'} | $flags{'DUMP'};
de8c5301
YO
167 setcolor() if $s =~/color/i;
168 _load_unload($on);
66e6b4c5 169 last;
de8c5301
YO
170 } elsif (exists $bitmask{$s}) {
171 $bits |= $bitmask{$s};
172 } elsif ($EXPORT_OK{$s}) {
de8c5301
YO
173 require Exporter;
174 re->export_to_level(2, 're', $s);
67cdf558
KW
175 } elsif ($s eq 'strict') {
176 if ($on) {
177 $^H{reflags} |= $reflags{$s};
178 warnings::warnif('experimental::re_strict',
179 "\"use re 'strict'\" is experimental");
180
181 # Turn on warnings if not already done.
182 if (! warnings::enabled('regexp')) {
183 require warnings;
184 warnings->import('regexp');
185 $^H{re_strict} = 1;
186 }
187 }
188 else {
3ab1d973 189 $^H{reflags} &= ~$reflags{$s} if $^H{reflags};
67cdf558
KW
190
191 # Turn off warnings if we turned them on.
192 warnings->unimport('regexp') if $^H{re_strict};
193 }
194 if ($^H{reflags}) {
195 $^H |= $flags_hint;
196 }
197 else {
198 $^H &= ~$flags_hint;
199 }
1e215989
FC
200 } elsif ($s =~ s/^\///) {
201 my $reflags = $^H{reflags} || 0;
6320bfaf 202 my $seen_charset;
77c8f263 203 my $x_count = 0;
342c8524 204 while ($s =~ m/( . )/gx) {
48895a0d 205 local $_ = $1;
cfaf538b 206 if (/[adul]/) {
342c8524
KW
207 # The 'a' may be repeated; hide this from the rest of the
208 # code by counting and getting rid of all of them, then
209 # changing to 'aa' if there is a repeat.
210 if ($_ eq 'a') {
211 my $sav_pos = pos $s;
212 my $a_count = $s =~ s/a//g;
213 pos $s = $sav_pos - 1; # -1 because got rid of the 'a'
214 if ($a_count > 2) {
215 require Carp;
216 Carp::carp(
217 qq 'The "a" flag may only appear a maximum of twice'
218 );
219 }
220 elsif ($a_count == 2) {
221 $_ = 'aa';
222 }
223 }
1e215989 224 if ($on) {
45a507fa 225 if ($seen_charset) {
96ef02be 226 require Carp;
45a507fa
KW
227 if ($seen_charset ne $_) {
228 Carp::carp(
229 qq 'The "$seen_charset" and "$_" flags '
230 .qq 'are exclusive'
231 );
232 }
233 else {
234 Carp::carp(
235 qq 'The "$seen_charset" flag may not appear '
236 .qq 'twice'
237 );
238 }
96ef02be 239 }
6320bfaf
KW
240 $^H{reflags_charset} = $reflags{$_};
241 $seen_charset = $_;
1e215989
FC
242 }
243 else {
6320bfaf 244 delete $^H{reflags_charset}
b10bad5a
KW
245 if defined $^H{reflags_charset}
246 && $^H{reflags_charset} == $reflags{$_};
1e215989
FC
247 }
248 } elsif (exists $reflags{$_}) {
77c8f263
KW
249 if ($_ eq 'x') {
250 $x_count++;
251 if ($x_count > 2) {
252 require Carp;
253 Carp::carp(
254 qq 'The "x" flag may only appear a maximum of twice'
255 );
256 }
257 elsif ($x_count == 2) {
258 $_ = 'xx'; # First time through got the /x
259 }
260 }
261
cc4d09e1 262 $on
1e215989
FC
263 ? $reflags |= $reflags{$_}
264 : ($reflags &= ~$reflags{$_});
265 } else {
266 require Carp;
267 Carp::carp(
268 qq'Unknown regular expression flag "$_"'
269 );
270 next ARG;
271 }
272 }
6320bfaf 273 ($^H{reflags} = $reflags or defined $^H{reflags_charset})
b10bad5a
KW
274 ? $^H |= $flags_hint
275 : ($^H &= ~$flags_hint);
de8c5301
YO
276 } else {
277 require Carp;
278 Carp::carp("Unknown \"re\" subpragma '$s' (known ones are: ",
279 join(', ', map {qq('$_')} 'debug', 'debugcolor', sort keys %bitmask),
280 ")");
281 }
282 }
3ab1d973
KW
283
284 if ($turning_all_off) {
285 _load_unload(0);
286 $^H{reflags} = 0;
287 $^H{reflags_charset} = 0;
288 $^H &= ~$flags_hint;
289 }
290
de8c5301
YO
291 $bits;
292}
293
294sub import {
295 shift;
296 $^H |= bits(1, @_);
297}
298
299sub unimport {
300 shift;
301 $^H &= ~ bits(0, @_);
302}
303
3041;
305
306__END__
56953603 307
b3eb6a9b
GS
308=head1 NAME
309
310re - Perl pragma to alter regular expression behaviour
311
312=head1 SYNOPSIS
313
e4d48cc9
GS
314 use re 'taint';
315 ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
b3eb6a9b 316
2cd61cdb 317 $pat = '(?{ $foo = 1 })';
e4d48cc9 318 use re 'eval';
48fe68f5
KW
319 /foo${pat}bar/; # won't fail (when not under -T
320 # switch)
e4d48cc9
GS
321
322 {
323 no re 'taint'; # the default
324 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
325
326 no re 'eval'; # the default
48fe68f5
KW
327 /foo${pat}bar/; # disallowed (with or without -T
328 # switch)
e4d48cc9 329 }
b3eb6a9b 330
67cdf558
KW
331 use re 'strict'; # Raise warnings for more conditions
332
1e215989
FC
333 use re '/ix';
334 "FOO" =~ / foo /; # /ix implied
335 no re '/x';
336 "FOO" =~ /foo/; # just /i implied
337
1e2e3d02 338 use re 'debug'; # output debugging info during
48fe68f5 339 /^(.*)$/s; # compile and run time
1e2e3d02 340
2cd61cdb 341
48fe68f5
KW
342 use re 'debugcolor'; # same as 'debug', but with colored
343 # output
02ea72ae
IZ
344 ...
345
48fe68f5
KW
346 use re qw(Debug All); # Same as "use re 'debug'", but you
347 # can use "Debug" with things other
348 # than 'All'
349 use re qw(Debug More); # 'All' plus output more details
350 no re qw(Debug ALL); # Turn on (almost) all re debugging
351 # in this scope
4ee9a43f 352
de8c5301
YO
353 use re qw(is_regexp regexp_pattern); # import utility functions
354 my ($pat,$mods)=regexp_pattern(qr/foo/i);
cbe2fc50 355 if (is_regexp($obj)) {
de8c5301 356 print "Got regexp: ",
48fe68f5
KW
357 scalar regexp_pattern($obj); # just as perl would stringify
358 } # it but no hassle with blessed
359 # re's.
a3621e74 360
3ffabb8c
GS
361(We use $^X in these examples because it's tainted by default.)
362
b3eb6a9b
GS
363=head1 DESCRIPTION
364
de8c5301
YO
365=head2 'taint' mode
366
b3eb6a9b 367When C<use re 'taint'> is in effect, and a tainted string is the target
99cc5cc6
A
368of a regexp, the regexp memories (or values returned by the m// operator
369in list context) are tainted. This feature is useful when regexp operations
e4d48cc9
GS
370on tainted data aren't meant to extract safe substrings, but to perform
371other transformations.
b3eb6a9b 372
de8c5301
YO
373=head2 'eval' mode
374
99cc5cc6 375When C<use re 'eval'> is in effect, a regexp is allowed to contain
0b370c0a 376C<(?{ ... })> zero-width assertions and C<(??{ ... })> postponed
e128ab2c
DM
377subexpressions that are derived from variable interpolation, rather than
378appearing literally within the regexp. That is normally disallowed, since
379it is a
2cd61cdb
IZ
380potential security risk. Note that this pragma is ignored when the regular
381expression is obtained from tainted data, i.e. evaluation is always
0b370c0a 382disallowed with tainted regular expressions. See L<perlre/(?{ code })>
bb1773de 383and L<perlre/(??{ code })>.
2cd61cdb 384
ffbc6a93 385For the purpose of this pragma, interpolation of precompiled regular
0a92e3a8
GS
386expressions (i.e., the result of C<qr//>) is I<not> considered variable
387interpolation. Thus:
2cd61cdb
IZ
388
389 /foo${pat}bar/
390
ffbc6a93 391I<is> allowed if $pat is a precompiled regular expression, even
0b370c0a 392if $pat contains C<(?{ ... })> assertions or C<(??{ ... })> subexpressions.
2cd61cdb 393
67cdf558
KW
394=head2 'strict' mode
395
1eac213a
KW
396Note that this is an experimental feature which may be changed or removed in a
397future Perl release.
398
67cdf558
KW
399When C<use re 'strict'> is in effect, stricter checks are applied than
400otherwise when compiling regular expressions patterns. These may cause more
401warnings to be raised than otherwise, and more things to be fatal instead of
402just warnings. The purpose of this is to find and report at compile time some
403things, which may be legal, but have a reasonable possibility of not being the
404programmer's actual intent. This automatically turns on the C<"regexp">
405warnings category (if not already on) within its scope.
406
1eac213a
KW
407As an example of something that is caught under C<"strict'>, but not
408otherwise, is the pattern
67cdf558
KW
409
410 qr/\xABC/
411
412The C<"\x"> construct without curly braces should be followed by exactly two
413hex digits; this one is followed by three. This currently evaluates as
414equivalent to
415
416 qr/\x{AB}C/
417
418that is, the character whose code point value is C<0xAB>, followed by the
419letter C<C>. But since C<C> is a a hex digit, there is a reasonable chance
420that the intent was
421
422 qr/\x{ABC}/
423
424that is the single character at C<0xABC>. Under C<'strict'> it is an error to
425not follow C<\x> with exactly two hex digits. When not under C<'strict'> a
426warning is generated if there is only one hex digit, and no warning is raised
427if there are more than two.
428
429It is expected that what exactly C<'strict'> does will evolve over time as we
430gain experience with it. This means that programs that compile under it in
431today's Perl may not compile, or may have more or fewer warnings, in future
1eac213a
KW
432Perls. There is no backwards compatibility promises with regards to it. Also
433there are already proposals for an alternate syntax for enabling it. For
434these reasons, using it will raise a C<experimental::re_strict> class warning,
67cdf558
KW
435unless that category is turned off.
436
437Note that if a pattern compiled within C<'strict'> is recompiled, say by
438interpolating into another pattern, outside of C<'strict'>, it is not checked
439again for strictness. This is because if it works under strict it must work
440under non-strict.
441
1e215989
FC
442=head2 '/flags' mode
443
cbe2fc50 444When C<use re '/I<flags>'> is specified, the given I<flags> are automatically
1e215989 445added to every regular expression till the end of the lexical scope.
cbe2fc50
KW
446I<flags> can be any combination of
447C<'a'>,
448C<'aa'>,
449C<'d'>,
450C<'i'>,
451C<'l'>,
452C<'m'>,
453C<'n'>,
454C<'p'>,
455C<'s'>,
456C<'u'>,
457C<'x'>,
458and/or
459C<'xx'>.
460
461C<no re '/I<flags>'> will turn off the effect of C<use re '/I<flags>'> for the
1e215989
FC
462given flags.
463
cbe2fc50 464For example, if you want all your regular expressions to have /msxx on by
1e215989
FC
465default, simply put
466
cbe2fc50 467 use re '/msxx';
1e215989
FC
468
469at the top of your code.
470
cbe2fc50 471The character set C</adul> flags cancel each other out. So, in this example,
1e215989
FC
472
473 use re "/u";
474 "ss" =~ /\xdf/;
475 use re "/d";
476 "ss" =~ /\xdf/;
477
4d220a7d 478the second C<use re> does an implicit C<no re '/u'>.
1e215989 479
cbe2fc50
KW
480Similarly,
481
482 use re "/xx"; # Doubled-x
483 ...
484 use re "/x"; # Single x from here on
485 ...
486
59640339 487Turning on one of the character set flags with C<use re> takes precedence over the
1e215989
FC
488C<locale> pragma and the 'unicode_strings' C<feature>, for regular
489expressions. Turning off one of these flags when it is active reverts to
490the behaviour specified by whatever other pragmata are in scope. For
491example:
492
493 use feature "unicode_strings";
494 no re "/u"; # does nothing
495 use re "/l";
496 no re "/l"; # reverts to unicode_strings behaviour
497
de8c5301
YO
498=head2 'debug' mode
499
ffbc6a93 500When C<use re 'debug'> is in effect, perl emits debugging messages when
2cd61cdb
IZ
501compiling and using regular expressions. The output is the same as that
502obtained by running a C<-DDEBUGGING>-enabled perl interpreter with the
503B<-Dr> switch. It may be quite voluminous depending on the complexity
02ea72ae
IZ
504of the match. Using C<debugcolor> instead of C<debug> enables a
505form of output that can be used to get a colorful display on terminals
506that understand termcap color sequences. Set C<$ENV{PERL_RE_TC}> to a
507comma-separated list of C<termcap> properties to use for highlighting
ffbc6a93 508strings on/off, pre-point part on/off.
57e8c15d 509See L<perldebug/"Debugging Regular Expressions"> for additional info.
2cd61cdb 510
de8c5301 511As of 5.9.5 the directive C<use re 'debug'> and its equivalents are
cbe2fc50 512lexically scoped, as the other directives are. However they have both
de8c5301
YO
513compile-time and run-time effects.
514
515See L<perlmodlib/Pragmatic Modules>.
516
517=head2 'Debug' mode
518
a3621e74
YO
519Similarly C<use re 'Debug'> produces debugging output, the difference
520being that it allows the fine tuning of what debugging output will be
be8e71aa
YO
521emitted. Options are divided into three groups, those related to
522compilation, those related to execution and those related to special
523purposes. The options are as follows:
524
525=over 4
526
527=item Compile related options
528
529=over 4
530
531=item COMPILE
532
9aae37ed 533Turns on all non-extra compile related debug options.
be8e71aa
YO
534
535=item PARSE
536
537Turns on debug output related to the process of parsing the pattern.
538
539=item OPTIMISE
540
541Enables output related to the optimisation phase of compilation.
542
24b23f37 543=item TRIEC
be8e71aa
YO
544
545Detailed info about trie compilation.
546
547=item DUMP
548
549Dump the final program out after it is compiled and optimised.
550
d9a72fcc
YO
551=item FLAGS
552
553Dump the flags associated with the program
554
555=item TEST
556
557Print output intended for testing the internals of the compile process
558
be8e71aa
YO
559=back
560
561=item Execute related options
562
563=over 4
564
565=item EXECUTE
566
9aae37ed 567Turns on all non-extra execute related debug options.
be8e71aa
YO
568
569=item MATCH
570
571Turns on debugging of the main matching loop.
572
24b23f37 573=item TRIEE
be8e71aa
YO
574
575Extra debugging of how tries execute.
576
577=item INTUIT
578
48fe68f5 579Enable debugging of start-point optimisations.
be8e71aa
YO
580
581=back
582
583=item Extra debugging options
584
585=over 4
586
587=item EXTRA
588
589Turns on all "extra" debugging options.
590
e7707071
YO
591=item BUFFERS
592
c27a5cfe 593Enable debugging the capture group storage during match. Warning,
e7707071
YO
594this can potentially produce extremely large output.
595
24b23f37
YO
596=item TRIEM
597
598Enable enhanced TRIE debugging. Enhances both TRIEE
599and TRIEC.
600
601=item STATE
602
4ee9a43f 603Enable debugging of states in the engine.
24b23f37
YO
604
605=item STACK
be8e71aa 606
24b23f37
YO
607Enable debugging of the recursion stack in the engine. Enabling
608or disabling this option automatically does the same for debugging
609states as well. This output from this can be quite large.
610
d9a72fcc
YO
611=item GPOS
612
613Enable debugging of the \G modifier.
614
24b23f37
YO
615=item OPTIMISEM
616
48fe68f5 617Enable enhanced optimisation debugging and start-point optimisations.
99cc5cc6 618Probably not useful except when debugging the regexp engine itself.
24b23f37
YO
619
620=item OFFSETS
621
622Dump offset information. This can be used to see how regops correlate
623to the pattern. Output format is
624
625 NODENUM:POSITION[LENGTH]
626
627Where 1 is the position of the first char in the string. Note that position
628can be 0, or larger than the actual length of the pattern, likewise length
629can be zero.
be8e71aa 630
24b23f37 631=item OFFSETSDBG
be8e71aa
YO
632
633Enable debugging of offsets information. This emits copious
fe759410 634amounts of trace information and doesn't mesh well with other
be8e71aa
YO
635debug options.
636
fe759410 637Almost definitely only useful to people hacking
be8e71aa
YO
638on the offsets part of the debug engine.
639
fd41b2d1
KW
640=item DUMP_PRE_OPTIMIZE
641
642Enable the dumping of the compiled pattern before the optimization phase.
d9a72fcc 643
51bd1941
KW
644=item WILDCARD
645
646When Perl encounters a wildcard subpattern, (see L<perlunicode/Wildcards in
647Property Values>), it suspends compilation of the main pattern, compiles the
648subpattern, and then matches that against all legal possibilities to determine
649the actual code points the subpattern matches. After that it adds these to
650the main pattern, and continues its compilation.
651
652You may very well want to see how your subpattern gets compiled, but it is
653likely of less use to you to see how Perl matches that against all the legal
654possibilities, as that is under control of Perl, not you. Therefore, the
655debugging information of the compilation portion is as specified by the other
656options, but the debugging output of the matching portion is normally
657suppressed.
658
659You can use the WILDCARD option to enable the debugging output of this
660subpattern matching. Careful! This can lead to voluminous outputs, and it
661may not make much sense to you what and why Perl is doing what it is.
662But it may be helpful to you to see why things aren't going the way you
663expect.
664
665Note that this option alone doesn't cause any debugging information to be
666output. What it does is stop the normal suppression of execution-related
667debugging information during the matching portion of the compilation of
668wildcards. You also have to specify which execution debugging information you
669want, such as by also including the EXECUTE option.
670
be8e71aa
YO
671=back
672
673=item Other useful flags
674
675These are useful shortcuts to save on the typing.
676
677=over 4
678
679=item ALL
680
51bd1941 681Enable all options at once except OFFSETS, OFFSETSDBG, BUFFERS, WILDCARD, and
fd41b2d1 682DUMP_PRE_OPTIMIZE.
dafb2544
KW
683(To get every single option without exception, use both ALL and EXTRA, or
684starting in 5.30 on a C<-DDEBUGGING>-enabled perl interpreter, use
685the B<-Drv> command-line switches.)
be8e71aa
YO
686
687=item All
688
51bd1941 689Enable DUMP and all non-extra execute options. Equivalent to:
be8e71aa
YO
690
691 use re 'debug';
692
693=item MORE
694
695=item More
696
48fe68f5 697Enable the options enabled by "All", plus STATE, TRIEC, and TRIEM.
be8e71aa 698
dba3f186 699=back
be8e71aa 700
dba3f186 701=back
a3621e74 702
1e2e3d02 703As of 5.9.5 the directive C<use re 'debug'> and its equivalents are
48fe68f5 704lexically scoped, as are the other directives. However they have both
1e2e3d02 705compile-time and run-time effects.
b3eb6a9b 706
de8c5301 707=head2 Exportable Functions
b3eb6a9b 708
de8c5301 709As of perl 5.9.5 're' debug contains a number of utility functions that
4ee9a43f 710may be optionally exported into the caller's namespace. They are listed
de8c5301 711below.
b3eb6a9b 712
de8c5301 713=over 4
b3eb6a9b 714
de8c5301 715=item is_regexp($ref)
02ea72ae 716
de8c5301 717Returns true if the argument is a compiled regular expression as returned
4ee9a43f 718by C<qr//>, false if it is not.
02ea72ae 719
4ee9a43f
RGS
720This function will not be confused by overloading or blessing. In
721internals terms, this extracts the regexp pointer out of the
3a5e0888 722PERL_MAGIC_qr structure so it cannot be fooled.
894be9b7 723
de8c5301 724=item regexp_pattern($ref)
02ea72ae 725
4ee9a43f
RGS
726If the argument is a compiled regular expression as returned by C<qr//>,
727then this function returns the pattern.
be8e71aa 728
4ee9a43f
RGS
729In list context it returns a two element list, the first element
730containing the pattern and the second containing the modifiers used when
731the pattern was compiled.
be8e71aa 732
4ee9a43f 733 my ($pat, $mods) = regexp_pattern($ref);
a3621e74 734
99cc5cc6 735In scalar context it returns the same as perl would when stringifying a raw
4ee9a43f
RGS
736C<qr//> with the same pattern inside. If the argument is not a compiled
737reference then this routine returns false but defined in scalar context,
738and the empty list in list context. Thus the following
f9f4320a 739
dff5e0c4 740 if (regexp_pattern($ref) eq '(?^i:foo)')
dba3f186 741
de8c5301 742will be warning free regardless of what $ref actually is.
380e0b81 743
4ee9a43f
RGS
744Like C<is_regexp> this function will not be confused by overloading
745or blessing of the object.
b3eb6a9b 746
256ddcd0
YO
747=item regmust($ref)
748
432acd5f 749If the argument is a compiled regular expression as returned by C<qr//>,
99cc5cc6 750then this function returns what the optimiser considers to be the longest
432acd5f
RGS
751anchored fixed string and longest floating fixed string in the pattern.
752
753A I<fixed string> is defined as being a substring that must appear for the
754pattern to match. An I<anchored fixed string> is a fixed string that must
755appear at a particular offset from the beginning of the match. A I<floating
756fixed string> is defined as a fixed string that can appear at any point in
757a range of positions relative to the start of the match. For example,
758
759 my $qr = qr/here .* there/x;
760 my ($anchored, $floating) = regmust($qr);
256ddcd0 761 print "anchored:'$anchored'\nfloating:'$floating'\n";
432acd5f 762
256ddcd0
YO
763results in
764
765 anchored:'here'
766 floating:'there'
767
432acd5f
RGS
768Because the C<here> is before the C<.*> in the pattern, its position
769can be determined exactly. That's not true, however, for the C<there>;
770it could appear at any point after where the anchored string appeared.
d952710b 771Perl uses both for its optimisations, preferring the longer, or, if they are
256ddcd0
YO
772equal, the floating.
773
774B<NOTE:> This may not necessarily be the definitive longest anchored and
432acd5f 775floating string. This will be what the optimiser of the Perl that you
256ddcd0
YO
776are using thinks is the longest. If you believe that the result is wrong
777please report it via the L<perlbug> utility.
778
28d8d7f4 779=item regname($name,$all)
44a2ac75 780
28d8d7f4
YO
781Returns the contents of a named buffer of the last successful match. If
782$all is true, then returns an array ref containing one entry per buffer,
44a2ac75
YO
783otherwise returns the first defined buffer.
784
28d8d7f4 785=item regnames($all)
44a2ac75 786
28d8d7f4
YO
787Returns a list of all of the named buffers defined in the last successful
788match. If $all is true, then it returns all names defined, if not it returns
789only names which were involved in the match.
44a2ac75 790
28d8d7f4 791=item regnames_count()
44a2ac75 792
28d8d7f4
YO
793Returns the number of distinct names defined in the pattern used
794for the last successful match.
44a2ac75 795
28d8d7f4
YO
796B<Note:> this result is always the actual number of distinct
797named buffers defined, it may not actually match that which is
798returned by C<regnames()> and related routines when those routines
799have not been called with the $all parameter set.
44a2ac75 800
de8c5301 801=back
b3eb6a9b 802
de8c5301 803=head1 SEE ALSO
b3eb6a9b 804
de8c5301
YO
805L<perlmodlib/Pragmatic Modules>.
806
807=cut