NAME
    Shishi - Perl wrapper for the "shishi" parsing library

SYNOPSIS
      use Shishi;

      # Create a parser
      my $parser = new Shishi("some name");

      # Add a basic node
      my $nodea = Shishi::Node->new("start");
      $parser->add_node($nodea);

      # Add a node with a simple rule:
      # State C: match 'c' -> go to ACCEPT state
      my $nodec = Shishi::Node->new("C")->add_decision(
            new Shishi::Decision(target => 'c', type => 'char', action => 'finish')
      );

      # State B: match 'b' -> go to state C
      my $nodeb = Shishi::Node->new("B")->add_decision(
            new Shishi::Decision(target => 'b', type => 'char', action => 'continue',
            next_node=>$nodec));

      # From the first node: match 'a' -> go to state B
      $parser->start_node->add_decision(
         new Shishi::Decision(target => 'a', type => 'char', action => 'continue',
                              next_node => $nodeb)
      );

      # Tell the parser that these states belong. (Helps with GC)
      $parser->add_node($nodeb);
      $parser->add_node($nodec);

      # We now have a state machine which accepts 'abc':
      ok(!$parser->execute(Shishi->new_match("ab")));
      ok($parser->execute(Shishi->new_match("abc")));

DESCRIPTION
    The "shishi" library is a tool for creating state machines for parsing
    text. Unlike most implementations of finite state automata, it doesn't
    use a transition table, but more directly implements the structure of a
    transition network diagram; that's to say, you have nodes which
    represent states, and decisions which represent the arrows between
    states. The reason for this rather curious design decision is to allow
    you to modify the state machine while it's running, something you'll
    want to do if you're dealing with user-modifiable grammars.

    To do anything with shishi, you need a parser; parsers are labelled for
    debugging purposes, so create one like this:

        my $parser = new Shishi ("my parser");

    Now your parser needs some states:

        my $node = new Shishi::Node ("first") ;
        $parser->add_node($node);

        my $node2 = new Shishi::Node ("last") ;
        $parser->add_node($node2);

    And now you need to have some transitions between those states; these
    are called "decisions".

        $node->add_decision(
            target => "abc", 
            type => "text", 
            action => "continue",
            next_node => $node2
        );

    This moves from the "first" node to the "last" node if it sees the text
    "abc". Actually, moving to an accept state is also a transition.

        $node2->add_decision(
            type => "end",
            action => "finish"
        );

    This says that we should accept the string if this we're now at the end
    of the string. Otherwise, we fail.

    As you can see, a decision has both a matching rule ("if you match the
    text abc", "if you match the end of the string") and an action ("then
    move to node 2", "then accept the string"). Here are the possible match
    types:

  MATCH TYPES
    "text"
       Matches a string exactly. Pass the string in as "target".

    "char"
       Matches a single character; equivalent to "text" but more efficient
       for single-character matching.

    "token"
       Equivalent to "char" currently; will be used to implement both
       parsing (passing tokens instead of characters) and Unicode character
       support (token values outside the range 0-255) in future versions.

    "end"
       Match only the end of the string. Equivalent to the "$" atom in
       regular expressions.

    "skip", "any"
       Matches any character. Equivalent to . in regular expressions.

       Hint
          This is particularly useful for doing non-anchored matches.
          Normally, shishi begins matching at the start of a string, as if
          the "^" RE atom was a default. To "undo" this an allow
          non-anchored matches, do this:

              $foo->start_node->add_decision(
               new Shishi::Decision(type => 'skip', next_node => $foo->start_node,
               action => 'continue')
              );

    "true"
       Always matches.

    "code"
       Executes the supplied comparison function. Pass a subroutine in as
       "code".

       The subroutine is called with the following parameters: the current
       "Shishi::Decision" being executed; the text to be parsed; the
       "Shishi" parser object; the "Shishi::Match" object.

       You're currently not able to modify the text. This will be fixed.

  ACTIONS
    As for actions, you have the choice of:

    "continue"
       Transition to another node in the network, specified with
       "next_node".

    "finish"
       Accept, return success.

    "fail"
       Abort the match completely.

    Other actions, such as "shift" and "reduce", may appear in time.

AUTHOR
    Simon Cozens, "simon@cpan.org"