FAQ - Getting Started

Created by TerenceP
Last updated: Dec 23, 2010Version comment

Getting started with ANTLR is pretty easy if you start playing around with some existing grammars and read some introductory material. As you progress, you will want to check out more advanced topics and play around by working with bigger grammars. Also please join us on the antlr-interest mailing list for active discussions on ANTLR and languages.

The Definitive ANTLR Reference

To get the most out of ANTLR, you should get The Definitive ANTLR Reference: Building Domain-Specific Languages. The book describes all features in detail, including the amazing new LL(star) parsing technology, tree construction facilities, StringTemplate code generation template engine, and sophisticated ANTLRWorks GUI development environment. You'll learn all about ANTLR grammar syntax, resolving grammar ambiguities, parser fault tolerance and error reporting, embedding actions to interpret or translate languages, building intermediate-form trees, extracting information from trees, generating source code, and how to use the ANTLR Java API. The definitive reference is required reading to become an advanced user. For example, Part III provides the only thorough explanation available anywhere of ANTLR's LL(*) parsing strategy.

If you are totally new to ANTLR v3, follow these steps:

For building projects manually or with ANTLRWorks IDE:

  1. Make sure you have installed the Java JDK (not JRE)
  2. Then you have to get the software: Download ANTLR v3 and install it (see How do I install this damn thing?) or get the ANTLRWorks grammar development environment, which includes ANTLR. You can just click on the ANTLRWorks jar to get started.
  3. Try a cut-and-paste example such as Expression evaluator either by pasting into ANTLRWorks and running the interpreter or debugger (see ANTLRWorks tutorial) or using an editor and manually invoking ANTLR from the command line (see How do I use ANTLR v3 from the command line?).
  4. Try modifying an existing grammar; change actions and rule elements to see what happens. You can look for grammars in the ANTLR grammar list (though, most of them are currently v2 grammars) or take a look at some of the ANTLR v3 examples.
  5. Check out the Five minute introduction to ANTLR 3 which breaks out an example grammar into very simple chunks.

Or for building projects using IDEs and Maven, see Building ANTLR Projects with Maven.

If you are familiar with ANTLR v2, check out Migrating from ANTLR 2 to ANTLR 3.

That should give you a taste of how to run ANTLR on a simple grammar and some clue about how to build a recognizer and translator. From here, you should start with an existing grammar that is similar to your intended application and start modifying it. There are a number of Tutorials you can look at that explain some of the basics of building translators and provide some grammars to tweak:

You might want to check out Terence's ANTLR v3 summary lecture and config file example from Sydney JUG talk; here are the Sydney JUG slides. Here's the Fig config file reader example.

When you run into questions, first examine the code generated by ANTLR (and source of ANTLR if you want) to see if you can answer your own question. Then you should check the following:

Here are the FAQ entries associated with a getting started: