summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/re.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/re.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/re.pm150
1 files changed, 131 insertions, 19 deletions
diff --git a/Master/tlpkg/tlperl/lib/re.pm b/Master/tlpkg/tlperl/lib/re.pm
index e2eddc09b91..d1db4625c00 100644
--- a/Master/tlpkg/tlperl/lib/re.pm
+++ b/Master/tlpkg/tlperl/lib/re.pm
@@ -4,11 +4,13 @@ package re;
use strict;
use warnings;
-our $VERSION = "0.40";
+our $VERSION = "0.41";
our @ISA = qw(Exporter);
-our @EXPORT_OK = ('regmust',
- qw(is_regexp regexp_pattern
- regname regnames regnames_count));
+our @EXPORT_OK = qw{
+ is_regexp regexp_pattern
+ regname regnames regnames_count
+ regmust optimization
+};
our %EXPORT_OK = map { $_ => 1 } @EXPORT_OK;
my %bitmask = (
@@ -751,6 +753,28 @@ 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.
+=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.
+
=item regmust($ref)
If the argument is a compiled regular expression as returned by C<qr//>,
@@ -783,27 +807,115 @@ 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)
+=item optimization($ref)
-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.
+If the argument is a compiled regular expression as returned by C<qr//>,
+then this function returns a hashref of the optimization information
+discovered at compile time, so we can write tests around it. If any
+other argument is given, returns C<undef>.
-=item regnames($all)
+The hash contents are expected to change from time to time as we develop
+new ways to optimize - no assumption of stability should be made, not
+even between minor versions of perl.
-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.
+For the current version, the hash will have the following contents:
-=item regnames_count()
+=over 4
-Returns the number of distinct names defined in the pattern used
-for the last successful match.
+=item minlen
-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.
+An integer, the least number of characters in any string that can match.
+
+=item minlenret
+
+An integer, the least number of characters that can be in C<$&> after a
+match. (Consider eg C< /ns(?=\d)/ >.)
+
+=item gofs
+
+An integer, the number of characters before C<pos()> to start match at.
+
+=item noscan
+
+A boolean, C<TRUE> to indicate that any anchored/floating substrings
+found should not be used. (CHECKME: apparently this is set for an
+anchored pattern with no floating substring, but never used.)
+
+=item isall
+
+A boolean, C<TRUE> to indicate that the optimizer information is all
+that the regular expression contains, and thus one does not need to
+enter the regexp runtime engine at all.
+
+=item anchor SBOL
+
+A boolean, C<TRUE> if the pattern is anchored to start of string.
+
+=item anchor MBOL
+
+A boolean, C<TRUE> if the pattern is anchored to any start of line
+within the string.
+
+=item anchor GPOS
+
+A boolean, C<TRUE> if the pattern is anchored to the end of the previous
+match.
+
+=item skip
+
+A boolean, C<TRUE> if the start class can match only the first of a run.
+
+=item implicit
+
+A boolean, C<TRUE> if a C</.*/> has been turned implicitly into a C</^.*/>.
+
+=item anchored/floating
+
+A byte string representing an anchored or floating substring respectively
+that any match must contain, or undef if no such substring was found, or
+if the substring would require utf8 to represent.
+
+=item anchored utf8/floating utf8
+
+A utf8 string representing an anchored or floating substring respectively
+that any match must contain, or undef if no such substring was found, or
+if the substring contains only 7-bit ASCII characters.
+
+=item anchored min offset/floating min offset
+
+An integer, the first offset in characters from a match location at which
+we should look for the corresponding substring.
+
+=item anchored max offset/floating max offset
+
+An integer, the last offset in characters from a match location at which
+we should look for the corresponding substring.
+
+Ignored for anchored, so may be 0 or same as min.
+
+=item anchored end shift/floating end shift
+
+FIXME: not sure what this is, something to do with lookbehind. regcomp.c
+says:
+ When the final pattern is compiled and the data is moved from the
+ scan_data_t structure into the regexp structure the information
+ about lookbehind is factored in, with the information that would
+ have been lost precalculated in the end_shift field for the
+ associated string.
+
+=item checking
+
+A constant string, one of "anchored", "floating" or "none" to indicate
+which substring (if any) should be checked for first.
+
+=item stclass
+
+A string representation of a character class ("start class") that must
+be the first character of any match.
+
+TODO: explain the representations.
+
+=back
=back