use strict;
use warnings;
-our $VERSION = "0.06_03";
+our $VERSION = "0.09";
our @ISA = qw(Exporter);
-our @EXPORT_OK = qw(is_regexp regexp_pattern);
+my @XS_FUNCTIONS = qw(regmust);
+my %XS_FUNCTIONS = map { $_ => 1 } @XS_FUNCTIONS;
+our @EXPORT_OK = (@XS_FUNCTIONS,
+ qw(is_regexp regexp_pattern
+ regname regnames regnames_count));
our %EXPORT_OK = map { $_ => 1 } @EXPORT_OK;
# *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***
OPTIMISE => 0x000002,
TRIEC => 0x000004,
DUMP => 0x000008,
+ FLAGS => 0x000010,
EXECUTE => 0x00FF00,
INTUIT => 0x000100,
STATE => 0x080000,
OPTIMISEM => 0x100000,
STACK => 0x280000,
+ BUFFERS => 0x400000,
);
-$flags{ALL} = -1;
+$flags{ALL} = -1 & ~($flags{OFFSETS}|$flags{OFFSETSDBG}|$flags{BUFFERS});
$flags{All} = $flags{all} = $flags{DUMP} | $flags{EXECUTE};
$flags{Extra} = $flags{EXECUTE} | $flags{COMPILE};
$flags{More} = $flags{MORE} = $flags{All} | $flags{TRIEC} | $flags{TRIEM} | $flags{STATE};
} elsif ($s eq 'debug' or $s eq 'debugcolor') {
setcolor() if $s =~/color/i;
_load_unload($on);
+ last;
} elsif (exists $bitmask{$s}) {
$bits |= $bitmask{$s};
+ } elsif ($XS_FUNCTIONS{$s}) {
+ _do_install();
+ if (! $installed) {
+ require Carp;
+ Carp::croak("\"re\" function '$s' not available");
+ }
+ require Exporter;
+ re->export_to_level(2, 're', $s);
} elsif ($EXPORT_OK{$s}) {
- _do_install();
require Exporter;
re->export_to_level(2, 're', $s);
} else {
...
use re qw(Debug All); # Finer tuned debugging options.
- use re qw(Debug More);
+ use re qw(Debug More);
no re qw(Debug ALL); # Turn of all re debugging in this scope
-
+
use re qw(is_regexp regexp_pattern); # import utility functions
my ($pat,$mods)=regexp_pattern(qr/foo/i);
if (is_regexp($obj)) {
print "Got regexp: ",
scalar regexp_pattern($obj); # just as perl would stringify it
} # but no hassle with blessed re's.
-
(We use $^X in these examples because it's tainted by default.)
Dump the final program out after it is compiled and optimised.
-
=back
=item Execute related options
Turns on all "extra" debugging options.
+=item BUFFERS
+
+Enable debugging the capture buffer storage during match. Warning,
+this can potentially produce extremely large output.
+
=item TRIEM
Enable enhanced TRIE debugging. Enhances both TRIEE
=item STATE
-Enable debugging of states in the engine.
+Enable debugging of states in the engine.
=item STACK
=item ALL
-Enable all compile and execute options at once.
+Enable all options at once except OFFSETS, OFFSETSDBG and BUFFERS
=item All
=back
As of 5.9.5 the directive C<use re 'debug'> and its equivalents are
-lexically scoped, as the other directives are. However they have both
+lexically scoped, as the other directives are. However they have both
compile-time and run-time effects.
=head2 Exportable Functions
As of perl 5.9.5 're' debug contains a number of utility functions that
-may be optionally exported into the callers namespace. They are listed
+may be optionally exported into the caller's namespace. They are listed
below.
=over 4
=item is_regexp($ref)
Returns true if the argument is a compiled regular expression as returned
-by C<qr//>, false if it is not.
+by C<qr//>, false if it is not.
-This function will not be confused by overloading or blessing. In
-internals terms this extracts the regexp pointer out of the
+This function will not be confused by overloading or blessing. In
+internals terms, this extracts the regexp pointer out of the
PERL_MAGIC_qr structure so it it cannot be fooled.
=item regexp_pattern($ref)
-If the argument is a compiled regular expression as returned by C<qr//>
-then this function returns the pattern.
+If the argument is a compiled regular expression as returned by C<qr//>,
+then this function returns the pattern.
-In list context it returns a two element list, the first element
-containing the pattern and the second containing the modifiers used when
-the pattern was compiled.
+In list context it returns a two element list, the first element
+containing the pattern and the second containing the modifiers used when
+the pattern was compiled.
- my ($pat,$mods)=regexp_pattern($ref);
+ my ($pat, $mods) = regexp_pattern($ref);
-In scalar context it returns the same as perl would when strigifying a
-raw qr// with the same pattern inside. If the argument is not a
-compiled reference then this routine returns false but defined in scalar
-context, and the empty list in list context. Thus the following
+In scalar context it returns the same as perl would when strigifying a raw
+C<qr//> with the same pattern inside. If the argument is not a compiled
+reference then this routine returns false but defined in scalar context,
+and the empty list in list context. Thus the following
if (regexp_pattern($ref) eq '(?i-xsm:foo)')
will be warning free regardless of what $ref actually is.
-Like c<is_regexp> this function will not be confused by overloading
-or blessing of the object.
+Like C<is_regexp> this function will not be confused by overloading
+or blessing of the object.
+
+=item regmust($ref)
+
+If the argument is a compiled regular expression as returned by C<qr//>,
+then this function returns what the optimiser consiers to be the longest
+anchored fixed string and longest floating fixed string in the pattern.
+
+A I<fixed string> is defined as being a substring that must appear for the
+pattern to match. An I<anchored fixed string> is a fixed string that must
+appear at a particular offset from the beginning of the match. A I<floating
+fixed string> is defined as a fixed string that can appear at any point in
+a range of positions relative to the start of the match. For example,
+
+ my $qr = qr/here .* there/x;
+ my ($anchored, $floating) = regmust($qr);
+ print "anchored:'$anchored'\nfloating:'$floating'\n";
+
+results in
+
+ anchored:'here'
+ floating:'there'
+
+Because the C<here> is before the C<.*> in the pattern, its position
+can be determined exactly. That's not true, however, for the C<there>;
+it could appear at any point after where the anchored string appeared.
+Perl uses both for its optimisations, prefering the longer, or, if they are
+equal, the floating.
+
+B<NOTE:> This may not necessarily be the definitive longest anchored and
+floating string. This will be what the optimiser of the Perl that you
+are using thinks is the longest. If you believe that the result is wrong
+please report it via the L<perlbug> utility.
+
+=item regname($name,$all)
+
+Returns the contents of a named buffer of the last successful match. If
+$all is true, then returns an array ref containing one entry per buffer,
+otherwise returns the first defined buffer.
+
+=item regnames($all)
+
+Returns a list of all of the named buffers defined in the last successful
+match. If $all is true, then it returns all names defined, if not it returns
+only names which were involved in the match.
+
+=item regnames_count()
+
+Returns the number of distinct names defined in the pattern used
+for the last successful match.
+
+B<Note:> this result is always the actual number of distinct
+named buffers defined, it may not actually match that which is
+returned by C<regnames()> and related routines when those routines
+have not been called with the $all parameter set.
=back
projects / p5sagit/p5-mst-13.2.git / blobdiff