Getting started with ANTLR and avoiding common mistakes.

Question

I have started to learn ANTLR and have both the 2007 book "The Definitive ANTLR Reference" and ANTLRWorks (an interactive tool for creating grammars). And, being that sort of person, I started at Chapter 3. ("A quick tour for the impatient").

It's a fairly painful process especially as some errors are rather impenetrable (e.g. http://stackoverflow.com/questions/1658869/antlr-missing-attribute-access-on-rule-scope-problem which just means to me "you got something wrong"). Also I have some very simple grammars (3-4 productions only) and simple input (2 lines) which when run give "OutOfMemory" error.

The ANTLR site is useful but somewhat fragmented and some SO users have commented (http://stackoverflow.com/questions/278480/good-tutorial-for-antlr) that the book and the tutorials expect a high entry level. I've been reluctant to approach the ANTLR discussion list because of this.

LATER We are beginning to get to grips with it. It would be useful to have simple reliable examples that could be gently expanded. It's certainly worth mastering as we have remodelled quite a lot of our thinking based on ANTLR.

One problem is that ANTLR V3 has signifcant changes from V2. One answer on SO (and on the ANTLR pages) refered to a V2 syntax that is no longer available.

Some of the ANTLR questions on SO have helped me a lot, but finding them is a bit ad hoc. So I'd like to know how SO users can help to make the learning process less painful. (If you refer to the reference book it would be useful to point to particular pages).

EDIT. @duffymo and @JamesAnderson have confirmed that ANTLR is hard work - largely because parsers are difficult. (FWIW I have been through LEX/YACC, etc. and there's no doubt that ANTLR is more powerful and easier to work with.) I think it would still be useful to have areas where it's possible to avoid fouling up such as:

• ensure correct capitalisation of variable names
• add package name to lexer as well as parser
• take care over order of rules as it affects precedence

and more of these sort would be useful.

Answer 1

I agree - ANTLR is not for the faint of heart. It does expect a high entry level, because grammars and parsers are not trivial.

With that said, here are a few suggestions:

1. Forget about v2. Version 3 is the standard; don't even waste time considering the earlier version or its documentation.
2. OutOfMemoryError is telling you that there's something circular in the grammar you've defined.
3. IntelliJ has a wonderful IDE for working with ANTLR v3. It'll give you a graphical representation of your grammar, step-through debugging, etc. If you're going to be doing a lot of work with ANTLR it'd be worth a few dollars to buy a license.

ANTLR won't be easy to master. The book is good, but dense. The error messages are cryptic, as you've noted. I'd be surprised if anyone here could make it easy.

Answer 2

Sorry but my experience of ANTLR (indeed javacc, bison or any full function parser) is that most of your learning will be by fixing your own mistakes!

Getting good examples of other peoples code will cut this down somewhat, the best examples look really simple -- but you are missing all the sweat and hair pulling it took to get them looking that easy.

Answer 3

Even if you prefer command line, it is worth using AntlrWorks when you have problems. The diagramatic representation can make it easier to see what i sgoing wrong.

A picture is worth a thousand error messages.