Chapter 4
Usage

4.1 Package content

TPG is a package which main function is to define a class which particular metaclass converts a doc string into a parser. You only need to import TPG and use these five objects:

tpg.Parser:
This is the base class of the parsers you want to define.
tpg.Error:
This exception is the base of all TPG exceptions.
tpg.LexicalError:
This exception is raised when the lexer fails.
tpg.SyntacticError:
This exception is raised when the parser fails.
tpg.SemanticError:
This exception is raised by the grammar itself when some semantic properties fail.

The grammar must be in the doc string of the class (see figure 4.1).




Figure 4.1: Grammar embeding example
    class Foo(tpg.Parser):  
        r"""  
 
        START/x -> Bar/x ;  
 
        Bar/x -> 'bar'/x ;  
 
        """



Then you can use the new generated parser. The parser is simply a Python class (see figure 4.2).




Figure 4.2: Parser usage example
    test = "bar"  
    my_parser = Foo()  
    x = my_parser(test)               # Uses the START symbol  
    print x  
    x = my_parser.parse('Bar', test)  # Uses the Bar symbol  
    print x



4.2 Command line usage

The tpg script reads a Python script and replaces TPG grammars (in doc string) by Python code. To produce a Python script (*.py) from a script containing grammars (*.pyg) you can use tpg as follow:

    tpg [-v|-vv] grammar.pyg [-o parser.py]

tpg accepts some options on the command line:

-v
turns tpg into a verbose mode (it displays parser names).
-vv
turns tpg into a more verbose mode (it displays parser names and simplified rules).
-o file.py
tells tpg to generate the parser in file.py. The default output file is grammar.py if -o option is not provided and grammar.pyg is the name of the grammar.

Notice that .pyg files are valid Python scripts. So you can choose the run .pyg file (slower startup but easier for debugging purpose) or turn them into a .py file (faster startup but needs a ”precompilation” stage). You can also write .py scripts containing grammars to be used as Python scripts.

In fact I only use the tpg script to convert tpg.pyg into tpg.py because TPG needs obviously to be a pure Python script (it can not translate itself at runtime). Then in most cases it is very convenient to directly write grammars in Python scripts.