


re(3p)           Perl Programmers Reference Guide          re(3p)


NAME
       re - Perl pragma to alter regular expression behaviour

SYNOPSIS
           use re 'taint';
           ($x) = ($^X =~ /^(.*)$/s);     # $x is tainted here

           $pat = '(?{ $foo = 1 })';
           use re 'eval';
           /foo${pat}bar/;                # won't fail (when not under -T switch)

           {
               no re 'taint';             # the default
               ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here

               no re 'eval';              # the default
               /foo${pat}bar/;            # disallowed (with or without -T switch)
           }

           use re 'debug';                # output debugging info during
           /^(.*)$/s;                     #     compile and run time


           use re 'debugcolor';           # same as 'debug', but with colored output
           ...

           use re qw(Debug All);          # Finer tuned debugging options.
           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.)

DESCRIPTION
   'taint' mode
       When "use re 'taint'" is in effect, and a tainted string
       is the target of a regex, the regex memories (or values
       returned by the m// operator in list context) are tainted.
       This feature is useful when regex operations on tainted
       data aren't meant to extract safe substrings, but to
       perform other transformations.

   'eval' mode
       When "use re 'eval'" is in effect, a regex is allowed to
       contain "(?{ ... })" zero-width assertions even if regular
       expression contains variable interpolation.  That is
       normally disallowed, since it is a potential security



perl v5.10.1                2010-03-17                          1





re(3p)           Perl Programmers Reference Guide          re(3p)


       risk.  Note that this pragma is ignored when the regular
       expression is obtained from tainted data, i.e.  evaluation
       is always disallowed with tainted regular expressions.
       See "(?{ code })" in perlre.

       For the purpose of this pragma, interpolation of
       precompiled regular expressions (i.e., the result of
       "qr//") is not considered variable interpolation.  Thus:

           /foo${pat}bar/

       is allowed if $pat is a precompiled regular expression,
       even if $pat contains "(?{ ... })" assertions.

   'debug' mode
       When "use re 'debug'" is in effect, perl emits debugging
       messages when compiling and using regular expressions.
       The output is the same as that obtained by running a
       "-DDEBUGGING"-enabled perl interpreter with the -Dr
       switch. It may be quite voluminous depending on the
       complexity of the match.  Using "debugcolor" instead of
       "debug" enables a form of output that can be used to get a
       colorful display on terminals that understand termcap
       color sequences.  Set $ENV{PERL_RE_TC} to a comma-
       separated list of "termcap" properties to use for
       highlighting strings on/off, pre-point part on/off.  See
       "Debugging regular expressions" in perldebug for
       additional info.

       As of 5.9.5 the directive "use re 'debug'" and its
       equivalents are lexically scoped, as the other directives
       are.  However they have both compile-time and run-time
       effects.

       See "Pragmatic Modules" in perlmodlib.

   'Debug' mode
       Similarly "use re 'Debug'" produces debugging output, the
       difference being that it allows the fine tuning of what
       debugging output will be emitted. Options are divided into
       three groups, those related to compilation, those related
       to execution and those related to special purposes. The
       options are as follows:

       Compile related options
           COMPILE
               Turns on all compile related debug options.

           PARSE
               Turns on debug output related to the process of
               parsing the pattern.

           OPTIMISE
               Enables output related to the optimisation phase



perl v5.10.1                2010-03-17                          2





re(3p)           Perl Programmers Reference Guide          re(3p)


               of compilation.

           TRIEC
               Detailed info about trie compilation.

           DUMP
               Dump the final program out after it is compiled
               and optimised.

       Execute related options
           EXECUTE
               Turns on all execute related debug options.

           MATCH
               Turns on debugging of the main matching loop.

           TRIEE
               Extra debugging of how tries execute.

           INTUIT
               Enable debugging of start point optimisations.

       Extra debugging options
           EXTRA
               Turns on all "extra" debugging options.

           BUFFERS
               Enable debugging the capture buffer storage during
               match. Warning, this can potentially produce
               extremely large output.

           TRIEM
               Enable enhanced TRIE debugging. Enhances both
               TRIEE and TRIEC.

           STATE
               Enable debugging of states in the engine.

           STACK
               Enable debugging of the recursion stack in the
               engine. Enabling or disabling this option
               automatically does the same for debugging states
               as well. This output from this can be quite large.

           OPTIMISEM
               Enable enhanced optimisation debugging and start
               point optimisations.  Probably not useful except
               when debugging the regex engine itself.

           OFFSETS
               Dump offset information. This can be used to see
               how regops correlate to the pattern. Output format
               is




perl v5.10.1                2010-03-17                          3





re(3p)           Perl Programmers Reference Guide          re(3p)


                  NODENUM:POSITION[LENGTH]

               Where 1 is the position of the first char in the
               string. Note that position can be 0, or larger
               than the actual length of the pattern, likewise
               length can be zero.

           OFFSETSDBG
               Enable debugging of offsets information. This
               emits copious amounts of trace information and
               doesn't mesh well with other debug options.

               Almost definitely only useful to people hacking on
               the offsets part of the debug engine.

       Other useful flags
           These are useful shortcuts to save on the typing.

           ALL Enable all options at once except OFFSETS,
               OFFSETSDBG and BUFFERS

           All Enable DUMP and all execute options. Equivalent
               to:

                 use re 'debug';

           MORE
           More
               Enable TRIEM and all execute compile and execute
               options.

       As of 5.9.5 the directive "use re 'debug'" and its
       equivalents are lexically scoped, as the other directives
       are.  However they have both compile-time and run-time
       effects.

   Exportable Functions
       As of perl 5.9.5 're' debug contains a number of utility
       functions that may be optionally exported into the
       caller's namespace. They are listed below.

       is_regexp($ref)
           Returns true if the argument is a compiled regular
           expression as returned by "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 PERL_MAGIC_qr structure so it it
           cannot be fooled.

       regexp_pattern($ref)
           If the argument is a compiled regular expression as
           returned by "qr//", then this function returns the
           pattern.



perl v5.10.1                2010-03-17                          4





re(3p)           Perl Programmers Reference Guide          re(3p)


           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);

           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

               if (regexp_pattern($ref) eq '(?i-xsm:foo)')

           will be warning free regardless of what $ref actually
           is.

           Like "is_regexp" this function will not be confused by
           overloading or blessing of the object.

       regmust($ref)
           If the argument is a compiled regular expression as
           returned by "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 fixed string is defined as being a substring that
           must appear for the pattern to match. An anchored
           fixed string is a fixed string that must appear at a
           particular offset from the beginning of the match. A
           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 "here" is before the ".*" in the pattern,
           its position can be determined exactly. That's not
           true, however, for the "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.

           NOTE: This may not necessarily be the definitive



perl v5.10.1                2010-03-17                          5





re(3p)           Perl Programmers Reference Guide          re(3p)


           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 perlbug utility.

       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.

       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.

       regnames_count()
           Returns the number of distinct names defined in the
           pattern used for the last successful match.

           Note: this result is always the actual number of
           distinct named buffers defined, it may not actually
           match that which is returned by "regnames()" and
           related routines when those routines have not been
           called with the $all parameter set.

SEE ALSO
       "Pragmatic Modules" in perlmodlib.




























perl v5.10.1                2010-03-17                          6


