CLASS API

The package exports the API described here.

::pt::peg::interpreter objectName grammar

The command creates a new parser object and returns the fully qualified name of the object command as its result. The API of this object command is described in the section Object API. It may be used to invoke various operations on the object.

This new parser is configured for the execution of an empty PEG. To configure the object for any other PEG use the method use of the Object API.

OBJECT API

All objects created by this package provide the following methods.

objectName use grammar

This method configures the grammar interpreter / parser for the execution of the PEG stored in grammar, an object which is API-compatible to instances of pt::peg::container. The parser copies the relevant information of the grammar, and does not take ownership of the object.

The information of any previously used grammar is overwritten.

The result of the method the empty string.

objectName destroy

This method destroys the parser instance, releasing all claimed memory and other resources, and deleting the instance command.

The result of the command is the empty string.

objectName parse chan

This method runs the parser using the contents of chan as input (starting at the current location in the channel), until parsing is not possible anymore, either because parsing has completed, or run into a syntax error.

Note here that the Parser Tools are based on Tcl 8.5+. In other words, the channel argument is not restricted to files, sockets, etc. We have the full power of reflected channels available.

It should also be noted that the parser pulls the characters from the input stream as it needs them. If a parser created by this package has to be operated in a push aka event-driven manner it will be necessary to go to Tcl 8.6+ and use the coroutine::auto to wrap it into a coroutine where read is properly changed for push-operation.

Upon successful completion the command returns an abstract syntax tree as its result. This AST is in the form specified in section AST serialization format. As a plain nested Tcl-list it can then be processed with any Tcl commands the user likes, doing transformations, semantic checks, etc. To help in this the package pt::ast provides a set of convenience commands for validation of the tree's basic structure, printing it for debugging, and walking it either from the bottom up, or top down.

When encountering a syntax error the command will throw an error instead. This error will be a 4-element Tcl-list, containing, in the order listed below:

objectName parset text

This method runs the parser using the string in text as input. In all other ways it behaves like the method parse, shown above.

EXAMPLE

Assuming the parsing expression grammar below

PEG calculator (Expression)


    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'	;


    Sign       <- '-' / '+'					;


    Number     <- Sign? Digit+					;


    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;


    MulOp      <- '*' / '/'					;


    Factor     <- Term (AddOp Term)*				;


    AddOp      <- '+'/'-'					;


    Term       <- Number					;
END;

and the input string

 120+5

set ast {Expression 0 4


    {Factor 0 4


        {Term 0 2


            {Number 0 2


                {Digit 0 0}


                {Digit 1 1}


                {Digit 2 2}


            }


        }


        {AddOp 3 3}


        {Term 4 4


            {Number 4 4


                {Digit 4 4}


            }


        }


    }
}

Or, more graphical

IMAGE: expr_ast

EXAMPLE

Assuming the parsing expression shown on the right-hand side of the rule

    Expression <- '(' Expression ')'


                / Factor (MulOp Factor)*

then its canonical serialization (except for whitespace) is

    {/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}