Antlr3PythonTarget

Partially working support for the Python target is available since release 3.0b6, but you should either grab the lastest code from the source repository or use a recent daily build.

Both the runtime module and the code generation templates should now be feature complete and in sync with the Java target. But large parts of the runtime are still untested.

I would consider it to be in early beta state. This means that most parts are working (big exceptions are ST output and tree parser stuff), but bugs and problems are to be expected and documentation is pretty poor. It still has to prove itself in a real world application (which is currently being done).

Please send bugreports, feedback, patches to me or the antlr-interest mailing list

Credits go to Clinton Roy for the code to support output=AST.

Documentation

Documentation is one of the missing pieces... Have a peek at the testcases in lib/Python/tests to get an idea how to invoke lexers/parsers from python.

Requirements

The following Python versions are supported: 2.3 2.4 2.5

Actions

This target currently supports the action scopes @lexer and @parser for global actions. The following action names are known:

• header - Will be inserted right after ANTLRs own imports at the top of the generated file. Use it for import statements or any other functions/classes which you need in the module scope.
• init - Will be inserted at the end of the __init__ method of the lexer/parser. Here you can setup your own instance attributes.
• members - Will be inserted in the class body of the lexer/parser right after __init__. This is the right place for custom methods and class attributes.

Caveats

Don't use TABs

Make sure that your editor is using spaces for indention, when you are editing your grammar files. The generated code uses spaces and when your actions are copied into the output, TABs will only cause confusion. A warning should be generated, when ANTLR stumples upon TABs.

% in actions

This is not a Python specific issue, but the % operator is probably used more often in Python than in other languages. See Special symbols in actions for the usage of %, but support for these is not you implemented for the Python target.

In an ANTLR3 grammars % is a special character for StringTemplate and must be escaped, in order to pass a plain % into the generate code. So you'll have to stuff like

...
{ print "hello \%s" \% $t.text }
...

Semicolons after property assignments

If you are assigning a value to a property in an action, it may be required to add a semicolon after the statement.

...
{ $text = "Hello world!"; }  // set text for rule
...
{ $someScope::someMember = value; } // set a scope member
...

ANTLR currently scans the code for a semicolon to detect property assignments. This semicolon is omitted in the generated code. This may lead to some strange code corruption, if ANTLR finds a semicolon in an unexpected place. But I don't know, if this is more than a theoretical problem - sofar I have not run into any issues.

Empty alternatives

In rules with empty alternatives, ANTLR may generate invalid Python code:

r: ( s | t | ) u;

This will result in an else: without an indented block. Until this issue is resolved, just stick a no-op action into the empty alternative:

r: ( s | t | {pass} ) u;

Unsupported features

• output=template: The code generation template looks pretty simple, but I don't know, if this makes sense at all, as long as there is no StringTemplate V3 for Python - that is, if it would work with the current Python ST2.
• ... (I still have to work my way through The Book - perhaps I'll stumble upon more stuff that I have not yet considered)