竜 TatSu-LTS

竜 TatSu-LTS is a friendly fork of 竜 TatSu that guarantees compatibility with all supported versions of Python. Compatibility with older Python versions is maintained as long as that does not require additional changes. Only patches required to support Python version older than the ones supported by the upstream project are applied. 竜 TatSu-LTS releases use the same version number as the 竜 TatSu release on which they are based and should be published shortly after the corresponding upstream release.

Both the 竜 TatSu and 竜 TatSu-LTS distributions install a Python package and an executable named tatsu. Users can thus switch seamlessly between the two, depending on which Python version support guarantees they prefer. For project that desire to support a wide range of Python versions, there is no drawback in depending on 竜 TatSu-LTS other than the short delay in the release of new versions.

竜 TatSu

竜 TatSu is a tool that takes grammars in a variation of EBNF as input, and outputs memoizing (Packrat) PEG parsers in Python.

Why use a PEG parser? Because regular languages (those parsable with Python's re package) "cannot count". Any language with nested structures or with balancing of demarcations requires more than regular expressions to be parsed.

竜 TatSu can compile a grammar stored in a string into a tatsu.grammars.Grammar object that can be used to parse any given input, much like the re module does with regular expressions, or it can generate a Python module that implements the parser.

竜 TatSu supports left-recursive rules in PEG grammars using the algorithm by Laurent and Mens. The generated AST has the expected left associativity.

竜 TatSu requires a maintained version of Python (3.13+ at the moment). While no code in 竜 TatSu yet depends on new language or standard library features, the authors don't want to be constrained by Python version compatibility considerations when developing features that will be part of future releases.

Installation

$ pip install TatSu-LTS

Using the Tool

竜 TatSu can be used as a library, much like Python's re, by embedding grammars as strings and generating grammar models instead of generating Python code.

This compiles the grammar and generates an in-memory parser that can subsequently be used for parsing input with.

parser = tatsu.compile(grammar)

Compiles the grammar and parses the given input producing an AST as result.

ast = tatsu.parse(grammar, input)

The result is equivalent to calling:

parser = compile(grammar)
ast = parser.parse(input)

Compiled grammars are cached for efficiency.

This compiles the grammar to the Python sourcecode that implements the parser.

parser_source = tatsu.to_python_sourcecode(grammar)

This is an example of how to use 竜 TatSu as a library:

GRAMMAR = '''
    @@grammar::CALC


    start = expression $ ;


    expression
        =
        | expression '+' term
        | expression '-' term
        | term
        ;


    term
        =
        | term '*' factor
        | term '/' factor
        | factor
        ;


    factor
        =
        | '(' expression ')'
        | number
        ;


    number = /\d+/ ;
'''


if __name__ == '__main__':
    import json
    from tatsu import parse
    from tatsu.util import asjson

    ast = parse(GRAMMAR, '3 + 5 * ( 10 - 20 )')
    print(json.dumps(asjson(ast), indent=2))

竜 TatSu will use the first rule defined in the grammar as the start rule.

This is the output:

[
  "3",
  "+",
  [
    "5",
    "*",
    [
      "10",
      "-",
      "20"
    ]
  ]
]

Documentation

For a detailed explanation of what 竜 TatSu is capable of, please see the documentation.

Questions?

Please use the [tatsu] tag on StackOverflow for general Q&A, and limit Github issues to bugs, enhancement proposals, and feature requests.

Changes

See the RELEASES for details.

License

You may use 竜 TatSu under the terms of the BSD-style license described in the enclosed LICENSE.txt file. If your project requires different licensing please email.