NAME
    YAPE::Regex - Yet Another Parser/Extractor for Regular
    Expressions

SYNOPSIS
      use YAPE::Regex;
      use strict;
      
      my $regex = qr/reg(ular\s+)?exp?(ression)?/i;
      my $parser = YAPE::Regex->new($regex);
      
      # here is the tokenizing part
      while (my $chunk = $parser->next) {
        # ...
      }

`YAPE' MODULES
    The `YAPE' hierarchy of modules is an attempt at a unified means
    of parsing and extracting content. It attempts to maintain a
    generic interface, to promote simplicity and reusability. The
    API is powerful, yet simple. The modules do tokenization (which
    can be intercepted) and build trees, so that extraction of
    specific nodes is doable.

DESCRIPTION
    This module is yet another (?) parser and tree-builder for Perl
    regular expressions. It builds a tree out of a regex, but at the
    moment, the extent of the extraction tool for the tree is quite
    limited (see the section on "Extracting Sections"). However, the
    tree can be useful to extension modules.

USAGE
    In addition to the base class, `YAPE::Regex', there is the
    auxiliary class `YAPE::Regex::Element' (common to all `YAPE'
    base classes) that holds the individual nodes' classes. There is
    documentation for the node classes in that module's
    documentation.

  Methods for `YAPE::Regex'

    * `use YAPE::Regex;'
    * `use YAPE::Regex qw( MyExt::Mod );'
        If supplied no arguments, the module is loaded normally, and
        the node classes are given the proper inheritence (from
        `YAPE::Regex::Element'). If you supply a module (or list of
        modules), `import' will automatically include them (if
        needed) and set up *their* node classes with the proper
        inheritence -- that is, it will append `YAPE::Regex' to
        `@MyExt::Mod::ISA', and `YAPE::Regex::xxx' to each node
        class's `@ISA' (where `xxx' is the name of the specific node
        class).

          package MyExt::Mod;
          use YAPE::Regex 'MyExt::Mod';
          
          # does the work of:
          # @MyExt::Mod::ISA = 'YAPE::Regex'
          # @MyExt::Mod::text::ISA = 'YAPE::Regex::text'
          # ...

    * `my $p = YAPE::Regex->new($REx);'
        Creates a `YAPE::Regex' object, using the contents of `$REx'
        as a regular expression. The `new' method will *attempt* to
        convert `$REx' to a compiled regex (using `qr//') if `$REx'
        isn't already one. If there is an error in the regex, this
        will fail, but the parser will pretend it was ok. It will
        then report the bad token when it gets to it, in the course
        of parsing.

    * `my $text = $p->chunk($len);'
        Returns the next `$len' characters in the input string;
        `$len' defaults to 30 characters. This is useful for
        figuring out why a parsing error occurs.

    * `my $done = $p->done;'
        Returns true if the parser is done with the input string,
        and false otherwise.

    * `my $errstr = $p->error;'
        Returns the parser error message.

    * `my $backref = $p->extract;'
        Returns a code reference that returns the next back-
        reference in the regex. For more information on enhancements
        in upcoming versions of this module, check the section on
        "Extracting Sections".

    * `my $node = $p->display(...);'
        Returns a string representation of the entire content. It
        calls the `parse' method in case there is more data that has
        not yet been parsed. This calls the `fullstring' method on
        the root nodes. Check the `YAPE::Regex::Element' docs on the
        arguments to `fullstring'.

    * `my $node = $p->next;'
        Returns the next token, or `undef' if there is no valid
        token. There will be an error message (accessible with the
        `error' method) if there was a problem in the parsing.

    * `my $node = $p->parse;'
        Calls `next' until all the data has been parsed.

    * `my $node = $p->root;'
        Returns the root node of the tree structure.

    * `my $state = $p->state;'
        Returns the current state of the parser. It is one of the
        following values: `alt', `anchor', `any', `backref',
        `capture(N)', `Cchar', `class', `close', `code', `comment',
        `cond(TYPE)', `ctrl', `cut', `done', `error', `flags',
        `group', `hex', `later', `lookahead(neg|pos)',
        `lookbehind(neg|pos)', `macro', `named', `oct', `slash',
        `text', and `utf8hex'.

        For `capture(N)', *N* will be the number the captured
        pattern represents.

        For `cond(TYPE)', *TYPE* will either be a number
        representing the back-reference that the conditional depends
        on, or the string `assert'.

        For `lookahead' and `lookbehind', one of `neg' and `pos'
        will be there, depending on the type of assertion.

    * `my $node = $p->top;'
        Synonymous to `root'.

  Extracting Sections

    While extraction of nodes is the goal of the `YAPE' modules, the
    author is at a loss for words as to what needs to be extracted
    from a regex. At the current time, all the `extract' method does
    is allow you access to the regex's set of back-references:

      my $extor = $parser->extract;
      while (my $backref = $extor->()) {
        # ...
      }

    `japhy' is very open to suggestions as to the approach to node
    extraction (in how the API should look, in addition to what
    should be proffered). Preliminary ideas include extraction
    keywords like the output of -Dr (or the `re' module's `debug'
    option).

EXTENSIONS
    * `YAPE::Regex::Explain' 3.00
        Presents an explanation of a regular expression, node by
        node.

    * `YAPE::Regex::Reverse' (Not released)
        Reverses the nodes of a regular expression.

TO DO
    This is a listing of things to add to future versions of this
    module.

  API

    * Create a robust `extract' method
        Open to suggestions.

BUGS
    Following is a list of known or reported bugs.

  Pending

    * `use charnames ':full''
        To understand `\N{...}' properly, you must be using 5.6.0 or
        higher. However, the parser only knows how to resolve full
        names (those made using `use charnames ':full''). There
        might be an option in the future to specify a class name.

SUPPORT
    Visit `YAPE''s web site at http://www.pobox.com/~japhy/YAPE/.

SEE ALSO
    The `YAPE::Regex::Element' documentation, for information on the
    node classes. Also, `Text::Balanced', Damian Conway's excellent
    module, used for the matching of `(?{ ... })' and `(??{ ... })'
    blocks.

AUTHOR
      Jeff "japhy" Pinyan
      CPAN ID: PINYAN
      japhy@pobox.com
      http://www.pobox.com/~japhy/