Provided by: libregexp-assemble-perl_0.35-2_all bug

NAME

       Regexp::Assemble - Assemble multiple Regular Expressions into a single RE

VERSION

       This document describes version 0.35 of Regexp::Assemble, released 2011-04-07.

SYNOPSIS

         use Regexp::Assemble;

         my $ra = Regexp::Assemble->new;
         $ra->add( 'ab+c' );
         $ra->add( 'ab+-' );
         $ra->add( 'a\w\d+' );
         $ra->add( 'a\d+' );
         print $ra->re; # prints a(?:\w?\d+|b+[-c])

DESCRIPTION

       Regexp::Assemble takes an arbitrary number of regular expressions and assembles them into
       a single regular expression (or RE) that matches all that the individual REs match.

       As a result, instead of having a large list of expressions to loop over, a target string
       only needs to be tested against one expression.  This is interesting when you have several
       thousand patterns to deal with. Serious effort is made to produce the smallest pattern
       possible.

       It is also possible to track the original patterns, so that you can determine which, among
       the source patterns that form the assembled pattern, was the one that caused the match to
       occur.

       You should realise that large numbers of alternations are processed in perl's regular
       expression engine in O(n) time, not O(1). If you are still having performance problems,
       you should look at using a trie. Note that Perl's own regular expression engine will
       implement trie optimisations in perl 5.10 (they are already available in perl 5.9.3 if you
       want to try them out). "Regexp::Assemble" will do the right thing when it knows it's
       running on a trie'd perl.  (At least in some version after this one).

       Some more examples of usage appear in the accompanying README. If that file isn't easy to
       access locally, you can find it on a web repository such as
       http://search.cpan.org/dist/Regexp-Assemble/README <http://search.cpan.org/dist/Regexp-
       Assemble/README> or http://cpan.uwinnipeg.ca/htdocs/Regexp-Assemble/README.html
       <http://cpan.uwinnipeg.ca/htdocs/Regexp-Assemble/README.html>.

METHODS

       new     Creates a new "Regexp::Assemble" object. The following optional key/value
               parameters may be employed. All keys have a corresponding method that can be used
               to change the behaviour later on. As a general rule, especially if you're just
               starting out, you don't have to bother with any of these.

               anchor_*, a family of optional attributes that allow anchors ("^", "\b", "\Z"...)
               to be added to the resulting pattern.

               flags, sets the "imsx" flags to add to the assembled regular expression.  Warning:
               no error checking is done, you should ensure that the flags you pass are
               understood by the version of Perl you are using. modifiers exists as an alias, for
               users familiar with Regexp::List.

               chomp, controls whether the pattern should be chomped before being lexed. Handy if
               you are reading patterns from a file. By default, "chomp"ing is performed (this
               behaviour changed as of version 0.24, prior versions did not chomp automatically).
               See also the "file" attribute and the "add_file" method.

               file, slurp the contents of the specified file and add them to the assembly.
               Multiple files may be processed by using a list.

                 my $r = Regexp::Assemble->new(file => 're.list');

                 my $r = Regexp::Assemble->new(file => ['re.1', 're.2']);

               If you really don't want chomping to occur, you will have to set the "chomp"
               attribute to 0 (zero). You may also want to look at the "input_record_separator"
               attribute, as well.

               input_record_separator, controls what constitutes a record separator when using
               the "file" attribute or the "add_file" method. May be abbreviated to rs. See the
               $/ variable in perlvar.

               lookahead, controls whether the pattern should contain zero-width lookahead
               assertions (For instance: (?=[abc])(?:bob|alice|charles).  This is not activated
               by default, because in many circumstances the cost of processing the assertion
               itself outweighs the benefit of its faculty for short-circuiting a match that will
               fail. This is sensitive to the probability of a match succeeding, so if you're
               worried about performance you'll have to benchmark a sample population of targets
               to see which way the benefits lie.

               track, controls whether you want know which of the initial patterns was the one
               that matched. See the "matched" method for more details. Note for version 5.8 of
               Perl and below, in this mode of operation YOU SHOULD BE AWARE OF THE SECURITY
               IMPLICATIONS that this entails. Perl 5.10 does not suffer from any such
               restriction.

               indent, the number of spaces used to indent nested grouping of a pattern. Use this
               to produce a pretty-printed pattern. See the "as_string" method for a more
               detailed explanation.

               pre_filter, allows you to add a callback to enable sanity checks on the pattern
               being loaded. This callback is triggered before the pattern is split apart by the
               lexer. In other words, it operates on the entire pattern. If you are loading
               patterns from a file, this would be an appropriate place to remove comments.

               filter, allows you to add a callback to enable sanity checks on the pattern being
               loaded. This callback is triggered after the pattern has been split apart by the
               lexer.

               unroll_plus, controls whether to unroll, for example, "x+" into "x", "x*", which
               may allow additional reductions in the resulting assembled pattern.

               reduce, controls whether tail reduction occurs or not. If set, patterns like
               "a(?:bc+d|ec+d)" will be reduced to "a[be]c+d".  That is, the end of the pattern
               in each part of the b... and d...  alternations is identical, and hence is hoisted
               out of the alternation and placed after it. On by default. Turn it off if you're
               really pressed for short assembly times.

               lex, specifies the pattern used to lex the input lines into tokens. You could
               replace the default pattern by a more sophisticated version that matches
               arbitrarily nested parentheses, for example.

               debug, controls whether copious amounts of output is produced during the loading
               stage or the reducing stage of assembly.

                 my $ra = Regexp::Assemble->new;
                 my $rb = Regexp::Assemble->new( chomp => 1, debug => 3 );

               mutable, controls whether new patterns can be added to the object after the
               assembled pattern is generated. DEPRECATED.

               This method/attribute will be removed in a future release. It doesn't really serve
               any purpose, and may be more effectively replaced by cloning an existing
               "Regexp::Assemble" object and spinning out a pattern from that instead.

               A more detailed explanation of these attributes follows.

       clone   Clones the contents of a Regexp::Assemble object and creates a new object (in
               other words it performs a deep copy).

               If the Storable module is installed, its dclone method will be used, otherwise the
               cloning will be performed using a pure perl approach.

               You can use this method to take a snapshot of the patterns that have been added so
               far to an object, and generate an assembly from the clone. Additional patterns may
               to be added to the original object afterwards.

                 my $re = $main->clone->re();
                 $main->add( 'another-pattern-\\d+' );

       add(LIST)
               Takes a string, breaks it apart into a set of tokens (respecting meta characters)
               and inserts the resulting list into the "R::A" object. It uses a naive regular
               expression to lex the string that may be fooled complex expressions (specifically,
               it will fail to lex nested parenthetical expressions such as "ab(cd(ef)?gh)ij"
               correctly). If this is the case, the end of the string will not be tokenised
               correctly and returned as one long string.

               On the one hand, this may indicate that the patterns you are trying to feed the
               "R::A" object are too complex. Simpler patterns might allow the algorithm to work
               more effectively and perform more reductions in the resulting pattern.

               On the other hand, you can supply your own pattern to perform the lexing if you
               need. The test suite contains an example of a lexer pattern that will match one
               level of nested parentheses.

               Note that there is an internal optimisation that will bypass a much of the lexing
               process. If a string contains no "\" (backslash), "[" (open square bracket), "("
               (open paren), "?" (question mark), "+" (plus), "*" (star) or "{" (open curly), a
               character split will be performed directly.

               A list of strings may be supplied, thus you can pass it a file handle of a file
               opened for reading:

                   $re->add( '\d+-\d+-\d+-\d+\.example\.com' );
                   $re->add( <IN> );

               If the file is very large, it may be more efficient to use a "while" loop, to read
               the file line-by-line:

                   $re->add($_) while <IN>;

               The "add" method will chomp the lines automatically. If you do not want this to
               occur (you want to keep the record separator), then disable "chomp"ing.

                   $re->chomp(0);
                   $re->add($_) while <IN>;

               This method is chainable.

       add_file(FILENAME [...])
               Takes a list of file names. Each file is opened and read line by line. Each line
               is added to the assembly.

                 $r->add_file( 'file.1', 'file.2' );

               If a file cannot be opened, the method will croak. If you cannot afford to let
               this happen then you should wrap the call in a "eval" block.

               Chomping happens automatically unless you the chomp(0) method to disable it. By
               default, input lines are read according to the value of the
               "input_record_separator" attribute (if defined), and will otherwise fall back to
               the current setting of the system $/ variable. The record separator may also be
               specified on each call to "add_file". Internally, the routine "local"ises the
               value of $/ to whatever is required, for the duration of the call.

               An alternate calling mechanism using a hash reference is available.  The
               recognised keys are:

               file
                   Reference to a list of file names, or the name of a single file.

                     $r->add_file({file => ['file.1', 'file.2', 'file.3']});
                     $r->add_file({file => 'file.n'});

               input_record_separator
                   If present, indicates what constitutes a line

                     $r->add_file({file => 'data.txt', input_record_separator => ':' });

               rs  An alias for input_record_separator (mnemonic: same as the English variable
                   names).

                 $r->add_file( {
                   file => [ 'pattern.txt', 'more.txt' ],
                   input_record_separator  => "\r\n",
                 });

       insert(LIST)
               Takes a list of tokens representing a regular expression and stores them in the
               object. Note: you should not pass it a bare regular expression, such as
               "ab+c?d*e". You must pass it as a list of tokens, e.g. "('a', 'b+', 'c?', 'd*',
               'e')".

               This method is chainable, e.g.:

                 my $ra = Regexp::Assemble->new
                   ->insert( qw[ a b+ c? d* e ] )
                   ->insert( qw[ a c+ d+ e* f ] );

               Lexing complex patterns with metacharacters and so on can consume a significant
               proportion of the overall time to build an assembly.  If you have the information
               available in a tokenised form, calling "insert" directly can be a big win.

       lexstr  Use the "lexstr" method if you are curious to see how a pattern gets tokenised. It
               takes a scalar on input, representing a pattern, and returns a reference to an
               array, containing the tokenised pattern. You can recover the original pattern by
               performing a "join":

                 my @token = $re->lexstr($pattern);
                 my $new_pattern = join( '', @token );

               If the original pattern contains unnecessary backslashes, or "\x4b" escapes, or
               quotemeta escapes ("\Q"..."\E") the resulting pattern may not be identical.

               Call "lexstr" does not add the pattern to the object, it is merely for exploratory
               purposes. It will, however, update various statistical counters.

       pre_filter(CODE)
               Allows you to install a callback to check that the pattern being loaded contains
               valid input. It receives the pattern as a whole to be added, before it been
               tokenised by the lexer. It may to return 0 or "undef" to indicate that the pattern
               should not be added, any true value indicates that the contents are fine.

               A filter to strip out trailing comments (marked by #):

                 $re->pre_filter( sub { $_[0] =~ s/\s*#.*$//; 1 } );

               A filter to ignore blank lines:

                 $re->pre_filter( sub { length(shift) } );

               If you want to remove the filter, pass "undef" as a parameter.

                 $ra->pre_filter(undef);

               This method is chainable.

       filter(CODE)
               Allows you to install a callback to check that the pattern being loaded contains
               valid input. It receives a list on input, after it has been tokenised by the
               lexer. It may to return 0 or undef to indicate that the pattern should not be
               added, any true value indicates that the contents are fine.

               If you know that all patterns you expect to assemble contain a restricted set of
               of tokens (e.g. no spaces), you could do the following:

                 $ra->filter(sub { not grep { / / } @_ });

               or

                 sub only_spaces_and_digits {
                   not grep { ![\d ] } @_
                 }
                 $ra->filter( \&only_spaces_and_digits );

               These two examples will silently ignore faulty patterns, If you want the user to
               be made aware of the problem you should raise an error (via "warn" or "die"), log
               an error message, whatever is best. If you want to remove a filter, pass "undef"
               as a parameter.

                 $ra->filter(undef);

               This method is chainable.

       as_string
               Assemble the expression and return it as a string. You may want to do this if you
               are writing the pattern to a file. The following arguments can be passed to
               control the aspect of the resulting pattern:

               indent, the number of spaces used to indent nested grouping of a pattern. Use this
               to produce a pretty-printed pattern (for some definition of "pretty"). The
               resulting output is rather verbose. The reason is to ensure that the
               metacharacters "(?:" and ")" always occur on otherwise empty lines. This allows
               you grep the result for an even more synthetic view of the pattern:

                 egrep -v '^ *[()]' <regexp.file>

               The result of the above is quite readable. Remember to backslash the spaces
               appearing in your own patterns if you wish to use an indented pattern in an
               "m/.../x" construct. Indenting is ignored if tracking is enabled.

               The indent argument takes precedence over the "indent" method/attribute of the
               object.

               Calling this method will drain the internal data structure. Large numbers of
               patterns can eat a significant amount of memory, and this lets perl recover the
               memory used for other purposes.

               If you want to reduce the pattern and continue to add new patterns, clone the
               object and reduce the clone, leaving the original object intact.

       re      Assembles the pattern and return it as a compiled RE, using the "qr//" operator.

               As with "as_string", calling this method will reset the internal data structures
               to free the memory used in assembling the RE.

               The indent attribute, documented in the "as_string" method, can be used here (it
               will be ignored if tracking is enabled).

               With method chaining, it is possible to produce a RE without having a temporary
               "Regexp::Assemble" object lying around, e.g.:

                 my $re = Regexp::Assemble->new
                   ->add( q[ab+cd+e] )
                   ->add( q[ac\\d+e] )
                   ->add( q[c\\d+e] )
                   ->re;

               The $re variable now contains a Regexp object that can be used directly:

                 while( <> ) {
                   /$re/ and print "Something in [$_] matched\n";
                 )

               The "re" method is called when the object is used in string context (hence, within
               an "m//" operator), so by and large you do not even need to save the RE in a
               separate variable. The following will work as expected:

                 my $re = Regexp::Assemble->new->add( qw[ fee fie foe fum ] );
                 while( <IN> ) {
                   if( /($re)/ ) {
                     print "Here be giants: $1\n";
                   }
                 }

               This approach does not work with tracked patterns. The "match" and "matched"
               methods must be used instead, see below.

       match(SCALAR)
               The following information applies to Perl 5.8 and below. See the section that
               follows for information on Perl 5.10.

               If pattern tracking is in use, you must "use re 'eval'" in order to make things
               work correctly. At a minimum, this will make your code look like this:

                   my $did_match = do { use re 'eval'; $target =~ /$ra/ }
                   if( $did_match ) {
                       print "matched ", $ra->matched, "\n";
                   }

               (The main reason is that the $^R variable is currently broken and an ugly
               workaround that runs some Perl code during the match is required, in order to
               simulate what $^R should be doing. See Perl bug #32840 for more information if you
               are curious. The README also contains more information). This bug has been fixed
               in 5.10.

               The important thing to note is that with "use re 'eval'", THERE ARE SECURITY
               IMPLICATIONS WHICH YOU IGNORE AT YOUR PERIL. The problem is this: if you do not
               have strict control over the patterns being fed to "Regexp::Assemble" when
               tracking is enabled, and someone slips you a pattern such as "/^(?{system 'rm -rf
               /'})/" and you attempt to match a string against the resulting pattern, you will
               know Fear and Loathing.

               What is more, the $^R workaround means that that tracking does not work if you
               perform a bare "/$re/" pattern match as shown above. You have to instead call the
               "match" method, in order to supply the necessary context to take care of the
               tracking housekeeping details.

                  if( defined( my $match = $ra->match($_)) ) {
                      print "  $_ matched by $match\n";
                  }

               In the case of a successful match, the original matched pattern is returned
               directly. The matched pattern will also be available through the "matched" method.

               (Except that the above is not true for 5.6.0: the "match" method returns true or
               undef, and the "matched" method always returns undef).

               If you are capturing parts of the pattern e.g. "foo(bar)rat" you will want to get
               at the captures. See the "mbegin", "mend", "mvar" and "capture" methods. If you
               are not using captures then you may safely ignore this section.

               In 5.10, since the bug concerning $^R has been resolved, there is no need to use
               "re 'eval'" and the assembled pattern does not require any Perl code to be
               executed during the match.

       source  When using tracked mode, after a successful match is made, returns the original
               source pattern that caused the match. In Perl 5.10, the $^R variable can be used
               to as an index to fetch the correct pattern from the object.

               If no successful match has been performed, or the object is not in tracked mode,
               this method returns "undef".

                 my $r = Regexp::Assemble->new->track(1)->add(qw(foo? bar{2} [Rr]at));

                 for my $w (qw(this food is rather barren)) {
                   if ($w =~ /$r/) {
                     print "$w matched by ", $r->source($^R), $/;
                   }
                   else {
                     print "$w no match\n";
                   }
                 }

       mbegin  This method returns a copy of "@-" at the moment of the last match. You should
               ordinarily not need to bother with this, "mvar" should be able to supply all your
               needs.

       mend    This method returns a copy of "@+" at the moment of the last match.

       mvar(NUMBER)
               The "mvar" method returns the captures of the last match.  mvar(1) corresponds to
               $1, mvar(2) to $2, and so on.  mvar(0) happens to return the target string
               matched, as a byproduct of walking down the "@-" and "@+" arrays after the match.

               If called without a parameter, "mvar" will return a reference to an array
               containing all captures.

       capture The "capture" method returns the the captures of the last match as an array.
               Unlink "mvar", this method does not include the matched string. It is equivalent
               to getting an array back that contains "$1, $2, $3, ...".

               If no captures were found in the match, an empty array is returned, rather than
               "undef". You are therefore guaranteed to be able to use "for my $c ($re->capture)
               { ..."  without have to check whether anything was captured.

       matched If pattern tracking has been set, via the "track" attribute, or through the
               "track" method, this method will return the original pattern of the last
               successful match. Returns undef match has yet been performed, or tracking has not
               been enabled.

               See below in the NOTES section for additional subtleties of which you should be
               aware of when tracking patterns.

               Note that this method is not available in 5.6.0, due to limitations in the
               implementation of "(?{...})" at the time.

   Statistics/Reporting routines
       stats_add
               Returns the number of patterns added to the assembly (whether by "add" or
               "insert"). Duplicate patterns are not included in this total.

       stats_dup
               Returns the number of duplicate patterns added to the assembly.  If non-zero, this
               may be a sign that something is wrong with your data (or at the least, some
               needless redundancy). This may occur when you have two patterns (for instance,
               "a\-b" and "a-b") which map to the same result.

       stats_raw
               Returns the raw number of bytes in the patterns added to the assembly. This
               includes both original and duplicate patterns.  For instance, adding the two
               patterns "ab" and "ab" will count as 4 bytes.

       stats_cooked
               Return the true number of bytes added to the assembly. This will not include
               duplicate patterns. Furthermore, it may differ from the raw bytes due to quotemeta
               treatment. For instance, "abc\,def" will count as 7 (not 8) bytes, because "\,"
               will be stored as ",". Also, "\Qa.b\E" is 7 bytes long, however, after the
               quotemeta directives are processed, "a\.b" will be stored, for a total of 4 bytes.

       stats_length
               Returns the length of the resulting assembled expression.  Until "as_string" or
               "re" have been called, the length will be 0 (since the assembly will have not yet
               been performed). The length includes only the pattern, not the additional
               ("(?-xism...") fluff added by the compilation.

       dup_warn(NUMBER|CODEREF)
               Turns warnings about duplicate patterns on or off. By default, no warnings are
               emitted. If the method is called with no parameters, or a true parameter, the
               object will carp about patterns it has already seen. To turn off the warnings, use
               0 as a parameter.

                 $r->dup_warn();

               The method may also be passed a code block. In this case the code will be executed
               and it will receive a reference to the object in question, and the lexed pattern.

                 $r->dup_warn(
                   sub {
                     my $self = shift;
                     print $self->stats_add, " patterns added at line $.\n",
                         join( '', @_ ), " added previously\n";
                   }
                 )

   Anchor routines
       Suppose you wish to assemble a series of patterns that all begin with "^"  and end with
       "$" (anchor pattern to the beginning and end of line). Rather than add the anchors to each
       and every pattern (and possibly forget to do so when a new entry is added), you may
       specify the anchors in the object, and they will appear in the resulting pattern, and you
       no longer need to (or should) put them in your source patterns. For example, the two
       following snippets will produce identical patterns:

         $r->add(qw(^this ^that ^them))->as_string;

         $r->add(qw(this that them))->anchor_line_begin->as_string;

         # both techniques will produce ^th(?:at|em|is)

       All anchors are possible word ("\b") boundaries, line boundaries ("^" and "$") and string
       boundaries ("\A" and "\Z" (or "\z" if you absolutely need it)).

       The shortcut "anchor_mumble" implies both "anchor_mumble_begin" "anchor_mumble_end" is
       also available. If different anchors are specified the most specific anchor wins. For
       instance, if both "anchor_word_begin" and "anchor_line_begin" are specified,
       "anchor_word_begin" takes precedence.

       All the anchor methods are chainable.

       anchor_word_begin
               The resulting pattern will be prefixed with a "\b" word boundary assertion when
               the value is true. Set to 0 to disable.

                 $r->add('pre')->anchor_word_begin->as_string;
                 # produces '\bpre'

       anchor_word_end
               The resulting pattern will be suffixed with a "\b" word boundary assertion when
               the value is true. Set to 0 to disable.

                 $r->add(qw(ing tion))
                   ->anchor_word_end
                   ->as_string; # produces '(?:tion|ing)\b'

       anchor_word
               The resulting pattern will be have "\b" word boundary assertions at the beginning
               and end of the pattern when the value is true. Set to 0 to disable.

                 $r->add(qw(cat carrot)
                   ->anchor_word(1)
                   ->as_string; # produces '\bca(?:rro)t\b'

       anchor_line_begin
               The resulting pattern will be prefixed with a "^" line boundary assertion when the
               value is true. Set to 0 to disable.

                 $r->anchor_line_begin;
                 # or
                 $r->anchor_line_begin(1);

       anchor_line_end
               The resulting pattern will be suffixed with a "$" line boundary assertion when the
               value is true. Set to 0 to disable.

                 # turn it off
                 $r->anchor_line_end(0);

       anchor_line
               The resulting pattern will be have the "^" and "$" line boundary assertions at the
               beginning and end of the pattern, respectively, when the value is true. Set to 0
               to disable.

                 $r->add(qw(cat carrot)
                   ->anchor_line
                   ->as_string; # produces '^ca(?:rro)t$'

       anchor_string_begin
               The resulting pattern will be prefixed with a "\A" string boundary assertion when
               the value is true. Set to 0 to disable.

                 $r->anchor_string_begin(1);

       anchor_string_end
               The resulting pattern will be suffixed with a "\Z" string boundary assertion when
               the value is true. Set to 0 to disable.

                 # disable the string boundary end anchor
                 $r->anchor_string_end(0);

       anchor_string_end_absolute
               The resulting pattern will be suffixed with a "\z" string boundary assertion when
               the value is true. Set to 0 to disable.

                 # disable the string boundary absolute end anchor
                 $r->anchor_string_end_absolute(0);

               If you don't understand the difference between "\Z" and "\z", the former will
               probably do what you want.

       anchor_string
               The resulting pattern will be have the "\A" and "\Z" string boundary assertions at
               the beginning and end of the pattern, respectively, when the value is true. Set to
               0 to disable.

                 $r->add(qw(cat carrot)
                   ->anchor_string
                   ->as_string; # produces '\Aca(?:rro)t\Z'

       anchor_string_absolute
               The resulting pattern will be have the "\A" and "\z" string boundary assertions at
               the beginning and end of the pattern, respectively, when the value is true. Set to
               0 to disable.

                 $r->add(qw(cat carrot)
                   ->anchor_string_absolute
                   ->as_string; # produces '\Aca(?:rro)t\z'

       debug(NUMBER)
               Turns debugging on or off. Statements are printed to the currently selected file
               handle (STDOUT by default).  If you are already using this handle, you will have
               to arrange to select an output handle to a file of your own choosing, before call
               the "add", "as_string" or "re") functions, otherwise it will scribble all over
               your carefully formatted output.

               0       Off. Turns off all debugging output.

               1       Add. Trace the addition of patterns.

               2       Reduce. Trace the process of reduction and assembly.

               4       Lex. Trace the lexing of the input patterns into its constituent tokens.

               8       Time. Print to STDOUT the time taken to load all the patterns. This is
                       nothing more than the difference between the time the object was
                       instantiated and the time reduction was initiated.

                         # load=<num>

                       Any lengthy computation performed in the client code will be reflected in
                       this value. Another line will be printed after reduction is complete.

                         # reduce=<num>

                       The above output lines will be changed to "load-epoch" and "reduce-epoch"
                       if the internal state of the object is corrupted and the initial timestamp
                       is lost.

                       The code attempts to load Time::HiRes in order to report fractional
                       seconds. If this is not successful, the elapsed time is displayed in whole
                       seconds.

               Values can be added (or or'ed together) to trace everything

                 $r->debug(7)->add( '\\d+abc' );

               Calling "debug" with no arguments turns debugging off.

       dump    Produces a synthetic view of the internal data structure. How to interpret the
               results is left as an exercise to the reader.

                 print $r->dump;

       chomp(0|1)
               Turns chomping on or off.

               IMPORTANT: As of version 0.24, chomping is now on by default as it makes
               "add_file" Just Work. The only time you may run into trouble is with
               "add("\\$/")". So don't do that, or else explicitly turn off chomping.

               To avoid incorporating (spurious) record separators (such as "\n" on Unix) when
               reading from a file, "add()" "chomp"s its input. If you don't want this to happen,
               call "chomp" with a false value.

                 $re->chomp(0); # really want the record separators
                 $re->add(<DATA>);

       fold_meta_pairs(NUMBER)
               Determines whether "\s", "\S" and "\w", "\W" and "\d", "\D" are folded into a "."
               (dot). Folding happens by default (for reasons of backwards compatibility, even
               though it is wrong when the "/s" expression modifier is active).

               Call this method with a false value to prevent this behaviour (which is only a
               problem when dealing with "\n" if the "/s" expression modifier is also set).

                 $re->add( '\\w', '\\W' );
                 my $clone = $re->clone;

                 $clone->fold_meta_pairs(0);
                 print $clone->as_string; # prints '.'
                 print $re->as_string;    # print '[\W\w]'

       indent(NUMBER)
               Sets the level of indent for pretty-printing nested groups within a pattern. See
               the "as_string" method for more details.  When called without a parameter, no
               indenting is performed.

                 $re->indent( 4 );
                 print $re->as_string;

       lookahead(0|1)
               Turns on zero-width lookahead assertions. This is usually beneficial when you
               expect that the pattern will usually fail.  If you expect that the pattern will
               usually match you will probably be worse off.

       flags(STRING)
               Sets the flags that govern how the pattern behaves (for versions of Perl up to 5.9
               or so, these are "imsx"). By default no flags are enabled.

       modifiers(STRING)
               An alias of the "flags" method, for users familiar with "Regexp::List".

       track(0|1)
               Turns tracking on or off. When this attribute is enabled, additional housekeeping
               information is inserted into the assembled expression using "({...}" embedded code
               constructs. This provides the necessary information to determine which, of the
               original patterns added, was the one that caused the match.

                 $re->track( 1 );
                 if( $target =~ /$re/ ) {
                   print "$target matched by ", $re->matched, "\n";
                 }

               Note that when this functionality is enabled, no reduction is performed and no
               character classes are generated. In other words, "brag|tag" is not reduced down to
               "(?:br|t)ag" and "dig|dim" is not reduced to "di[gm]".

       unroll_plus(0|1)
               Turns the unrolling of plus metacharacters on or off. When a pattern is broken up,
               "a+" becomes "a", "a*" (and "b+?" becomes "b", "b*?". This may allow the freed "a"
               to assemble with other patterns. Not enabled by default.

       lex(SCALAR)
               Change the pattern used to break a string apart into tokens.  You can examine the
               "eg/naive" script as a starting point.

       reduce(0|1)
               Turns pattern reduction on or off. A reduced pattern may be considerably shorter
               than an unreduced pattern. Consider "/sl(?:ip|op|ap)/" versus "/sl[aio]p/". An
               unreduced pattern will be very similar to those produced by "Regexp::Optimizer".
               Reduction is on by default. Turning it off speeds assembly (but assembly is pretty
               fast -- it's the breaking up of the initial patterns in the lexing stage that can
               consume a non-negligible amount of time).

       mutable(0|1)
               This method has been marked as DEPRECATED. It will be removed in a future release.
               See the "clone" method for a technique to replace its functionality.

       reset   Empties out the patterns that have been "add"ed or "insert"-ed into the object.
               Does not modify the state of controller attributes such as "debug", "lex",
               "reduce" and the like.

       Default_Lexer
               Warning: the "Default_Lexer" function is a class method, not an object method. It
               is a fatal error to call it as an object method.

               The "Default_Lexer" method lets you replace the default pattern used for all
               subsequently created "Regexp::Assemble" objects. It will not have any effect on
               existing objects. (It is also possible to override the lexer pattern used on a
               per-object basis).

               The parameter should be an ordinary scalar, not a compiled pattern. If the pattern
               fails to match all parts of the string, the missing parts will be returned as
               single chunks. Therefore the following pattern is legal (albeit rather cork-
               brained):

                   Regexp::Assemble::Default_Lexer( '\\d' );

               The above pattern will split up input strings digit by digit, and all non-digit
               characters as single chunks.

DIAGNOSTICS

         "Cannot pass a C<refname> to Default_Lexer"

       You tried to replace the default lexer pattern with an object instead of a scalar.
       Solution: You probably tried to call "$obj->Default_Lexer". Call the qualified class
       method instead "Regexp::Assemble::Default_Lexer".

         "filter method not passed a coderef"

         "pre_filter method not passed a coderef"

       A reference to a subroutine (anonymous or otherwise) was expected.  Solution: read the
       documentation for the "filter" method.

         "duplicate pattern added: /.../"

       The "dup_warn" attribute is active, and a duplicate pattern was added (well duh!).
       Solution: clean your data.

         "cannot open [file] for input: [reason]"

       The "add_file" method was unable to open the specified file for whatever reason. Solution:
       make sure the file exists and the script has the required privileges to read it.

NOTES

       This module has been tested successfully with a range of versions of perl, from 5.005_03
       to 5.9.3. Use of 5.6.0 is not recommended.

       The expressions produced by this module can be used with the PCRE library.

       Remember to "double up" your backslashes if the patterns are hard-coded as constants in
       your program. That is, you should literally "add('a\\d+b')" rather than "add('a\d+b')". It
       usually will work either way, but it's good practice to do so.

       Where possible, supply the simplest tokens possible. Don't add "X(?-\d+){2})Y" when
       "X-\d+-\d+Y" will do. The reason is that if you also add "X\d+Z" the resulting assembly
       changes dramatically: "X(?:(?:-\d+){2}Y|-\d+Z)" versus "X-\d+(?:-\d+Y|Z)". Since R::A
       doesn't perform enough analysis, it won't "unroll" the "{2}" quantifier, and will fail to
       notice the divergence after the first "-d\d+".

       Furthermore, when the string 'X-123000P' is matched against the first assembly, the regexp
       engine will have to backtrack over each alternation (the one that ends in Y and the one
       that ends in Z) before determining that there is no match. No such backtracking occurs in
       the second pattern: as soon as the engine encounters the 'P' in the target string, neither
       of the alternations at that point ("-\d+Y" or "Z") could succeed and so the match fails.

       "Regexp::Assemble" does, however, know how to build character classes. Given "a-b", "axb"
       and "a\db", it will assemble these into "a[-\dx]b". When "-" (dash) appears as a candidate
       for a character class it will be the first character in the class. When "^" (circumflex)
       appears as a candidate for a character class it will be the last character in the class.

       It also knows about meta-characters than can "absorb" regular characters. For instance,
       given "X\d" and "X5", it knows that 5 can be represented by "\d" and so the assembly is
       just "X\d".  The "absorbent" meta-characters it deals with are ".", "\d", "\s" and "\W"
       and their complements. It will replace "\d"/"\D", "\s"/"\S" and "\w"/"\W" by "." (dot),
       and it will drop "\d" if "\w" is also present (as will "\D" in the presence of "\W").

       "Regexp::Assemble" deals correctly with "quotemeta"'s propensity to backslash many
       characters that have no need to be. Backslashes on non-metacharacters will be removed.
       Similarly, in character classes, a number of characters lose their magic and so no longer
       need to be backslashed within a character class. Two common examples are "."  (dot) and
       "$". Such characters will lose their backslash.

       At the same time, it will also process "\Q...\E" sequences. When such a sequence is
       encountered, the inner section is extracted and "quotemeta" is applied to the section. The
       resulting quoted text is then used in place of the original unquoted text, and the "\Q"
       and "\E" metacharacters are thrown away. Similar processing occurs with the "\U...\E" and
       "\L...\E" sequences. This may have surprising effects when using a dispatch table. In this
       case, you will need to know exactly what the module makes of your input. Use the "lexstr"
       method to find out what's going on:

         $pattern = join( '', @{$re->lexstr($pattern)} );

       If all the digits 0..9 appear in a character class, "Regexp::Assemble" will replace them
       by "\d". I'd do it for letters as well, but thinking about accented characters and other
       glyphs hurts my head.

       In an alternation, the longest paths are chosen first (for example, "horse|bird|dog").
       When two paths have the same length, the path with the most subpaths will appear first.
       This aims to put the "busiest" paths to the front of the alternation. For example, the
       list "bad", "bit", "few", "fig" and "fun" will produce the pattern
       "(?:f(?:ew|ig|un)|b(?:ad|it))". See eg/tld for a real-world example of how alternations
       are sorted. Once you have looked at that, everything should be crystal clear.

       When tracking is in use, no reduction is performed. nor are character classes formed. The
       reason is that it is too difficult to determine the original pattern afterwards. Consider
       the two patterns "pale" and "palm". These should be reduced to "pal[em]". The final
       character matches one of two possibilities.  To resolve whether it matched an 'e' or 'm'
       would require keeping track of the fact that the pattern finished up in a character class,
       which would the require a whole lot more work to figure out which character of the class
       matched. Without character classes it becomes much easier. Instead, "pal(?:e|m)" is
       produced, which lets us find out more simply where we ended up.

       Similarly, "dogfood" and "seafood" should form "(?:dog|sea)food".  When the pattern is
       being assembled, the tracking decision needs to be made at the end of the grouping, but
       the tail of the pattern has not yet been visited. Deferring things to make this work
       correctly is a vast hassle. In this case, the pattern becomes merely "(?:dogfood|seafood".
       Tracked patterns will therefore be bulkier than simple patterns.

       There is an open bug on this issue:

       <http://rt.perl.org/rt3/Ticket/Display.html?id=32840>

       If this bug is ever resolved, tracking would become much easier to deal with (none of the
       "match" hassle would be required - you could just match like a regular RE and it would
       Just Work).

SEE ALSO

       perlre  General information about Perl's regular expressions.

       re      Specific information about "use re 'eval'".

       Regex::PreSuf
               "Regex::PreSuf" takes a string and chops it itself into tokens of length 1. Since
               it can't deal with tokens of more than one character, it can't deal with meta-
               characters and thus no regular expressions.  Which is the main reason why I wrote
               this module.

       Regexp::Optimizer
               "Regexp::Optimizer" produces regular expressions that are similar to those
               produced by R::A with reductions switched off. It's biggest drawback is that it is
               exponentially slower than Regexp::Assemble on very large sets of patterns.

       Regexp::Parser
               Fine grained analysis of regular expressions.

       Regexp::Trie
               Funnily enough, this was my working name for "Regexp::Assemble" during its
               development. I changed the name because I thought it was too obscure. Anyway,
               "Regexp::Trie" does much the same as "Regexp::Optimizer" and "Regexp::Assemble"
               except that it runs much faster (according to the author). It does not recognise
               meta characters (that is, 'a+b' is interpreted as 'a\+b').

       Text::Trie
               "Text::Trie" is well worth investigating. Tries can outperform very bushy (read:
               many alternations) patterns.

       Tree::Trie
               "Tree::Trie" is another module that builds tries. The algorithm that
               "Regexp::Assemble" uses appears to be quite similar to the algorithm described
               therein, except that "R::A" solves its end-marker problem without having to
               rewrite the leaves.

LIMITATIONS

       "Regexp::Assemble" does not attempt to find common substrings. For instance, it will not
       collapse "/cabababc/" down to "/c(?:ab){3}c/".  If there's a module out there that
       performs this sort of string analysis I'd like to know about it. But keep in mind that the
       algorithms that do this are very expensive: quadratic or worse.

       "Regexp::Assemble" does not interpret meta-character modifiers.  For instance, if the
       following two patterns are given: "X\d" and "X\d+", it will not determine that "\d" can be
       matched by "\d+". Instead, it will produce "X(?:\d|\d+)". Along a similar line of
       reasoning, it will not determine that "Z" and "Z\d+" is equivalent to "Z\d*" (It will
       produce "Z(?:\d+)?"  instead).

       You cannot remove a pattern that has been added to an object. You'll just have to start
       over again. Adding a pattern is difficult enough, I'd need a solid argument to convince me
       to add a "remove" method.  If you need to do this you should read the documentation for
       the "clone" method.

       "Regexp::Assemble" does not (yet)? employ the "(?>...)"  construct.

       The module does not produce POSIX-style regular expressions. This would be quite easy to
       add, if there was a demand for it.

BUGS

       Patterns that generate look-ahead assertions sometimes produce incorrect patterns in
       certain obscure corner cases. If you suspect that this is occurring in your pattern,
       disable lookaheads.

       Tracking doesn't really work at all with 5.6.0. It works better in subsequent 5.6
       releases. For maximum reliability, the use of a 5.8 release is strongly recommended.
       Tracking barely works with 5.005_04. Of note, using "\d"-style meta-characters invariably
       causes panics. Tracking really comes into its own in Perl 5.10.

       If you feed "Regexp::Assemble" patterns with nested parentheses, there is a chance that
       the resulting pattern will be uncompilable due to mismatched parentheses (not enough
       closing parentheses). This is normal, so long as the default lexer pattern is used. If you
       want to find out which pattern among a list of 3000 patterns are to blame (speaking from
       experience here), the eg/debugging script offers a strategy for pinpointing the pattern at
       fault. While you may not be able to use the script directly, the general approach is easy
       to implement.

       The algorithm used to assemble the regular expressions makes extensive use of mutually-
       recursive functions (that is, A calls B, B calls A, ...) For deeply similar expressions,
       it may be possible to provoke "Deep recursion" warnings.

       The module has been tested extensively, and has an extensive test suite (that achieves
       close to 100% statement coverage), but you never know...  A bug may manifest itself in two
       ways: creating a pattern that cannot be compiled, such as "a\(bc)", or a pattern that
       compiles correctly but that either matches things it shouldn't, or doesn't match things it
       should. It is assumed that Such problems will occur when the reduction algorithm
       encounters some sort of edge case. A temporary work-around is to disable reductions:

         my $pattern = $assembler->reduce(0)->re;

       A discussion about implementation details and where bugs might lurk appears in the README
       file. If this file is not available locally, you should be able to find a copy on the Web
       at your nearest CPAN mirror.

       Seriously, though, a number of people have been using this module to create expressions
       anywhere from 140Kb to 600Kb in size, and it seems to be working according to spec. Thus,
       I don't think there are any serious bugs remaining.

       If you are feeling brave, extensive debugging traces are available to figure out where
       assembly goes wrong.

       Please report all bugs at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Regexp-Assemble
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Regexp-Assemble>

       Make sure you include the output from the following two commands:

         perl -MRegexp::Assemble -le 'print $Regexp::Assemble::VERSION'
         perl -V

       There is a mailing list for the discussion of "Regexp::Assemble".  Subscription details
       are available at http://listes.mongueurs.net/mailman/listinfo/regexp-assemble
       <http://listes.mongueurs.net/mailman/listinfo/regexp-assemble>.

ACKNOWLEDGEMENTS

       This module grew out of work I did building access maps for Postfix, a modern SMTP mail
       transfer agent. See <http://www.postfix.org/> for more information. I used Perl to build
       large regular expressions for blocking dynamic/residential IP addresses to cut down on
       spam and viruses. Once I had the code running for this, it was easy to start adding stuff
       to block really blatant spam subject lines, bogus HELO strings, spammer mailer-ids and
       more...

       I presented the work at the French Perl Workshop in 2004, and the thing most people asked
       was whether the underlying mechanism for assembling the REs was available as a module. At
       that time it was nothing more that a twisty maze of scripts, all different. The interest
       shown indicated that a module was called for. I'd like to thank the people who showed
       interest. Hey, it's going to make my messy scripts smaller, in any case.

       Thomas Drugeon was a valuable sounding board for trying out early ideas. Jean Forget and
       Philippe Blayo looked over an early version. H.Merijn Brandt stopped over in Paris one
       evening, and discussed things over a few beers.

       Nicholas Clark pointed out that while what this module does (?:c|sh)ould be done in perl's
       core, as per the 2004 TODO, he encouraged me to continue with the development of this
       module. In any event, this module allows one to gauge the difficulty of undertaking the
       endeavour in C. I'd rather gouge my eyes out with a blunt pencil.

       Paul Johnson settled the question as to whether this module should live in the Regex::
       namespace, or Regexp:: namespace. If you're not convinced, try running the following one-
       liner:

         perl -le 'print ref qr//'

       Philippe Bruhat found a couple of corner cases where this module could produce incorrect
       results. Such feedback is invaluable, and only improves the module's quality.

AUTHOR

       David Landgren

       Copyright (C) 2004-2011. All rights reserved.

         http://www.landgren.net/perl/

       If you use this module, I'd love to hear about what you're using it for. If you want to be
       informed of updates, send me a note.

       You can look at the latest working copy in the following Subversion repository:

         http://svnweb.mongueurs.net/Regexp-Assemble

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.