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