Simon Cozens


Shishi - Perl wrapper for the shishi parsing library


  use Shishi;

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

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

  # 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',

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

  # Tell the parser that these states belong. (Helps with GC)

  # We now have a state machine which accepts 'abc':


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

    my $node2 = new Shishi::Node ("last") ;

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

        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.

        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:



Matches a string exactly. Pass the string in as target.


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


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.


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

skip, any

Matches any character. Equivalent to . in regular expressions.


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:

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

Always matches.


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.


As for actions, you have the choice of:


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


Accept, return success.


Abort the match completely.

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


Simon Cozens,