FAQ - Getting Started

Skip to end of metadata
Comment: Migrated to Confluence 4.0
Go to start of metadata

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:

Page: How do I use ANTLR v3 generated Lexer and Parser from Java? (ANTLR 3)
Labels: faq_gettingstarted, antlr3
Page: FAQ - Getting Started (ANTLRMorph)
Labels: faq_gettingstarted
Page: What is the difference between ANTLR v2 and v3? (ANTLR 3)
Labels: faq_general, faq_gettingstarted
Page: How do I install this damn thing? (ANTLR 3)
Labels: faq_gettingstarted, updated_for_v3_3
Page: How do I use ANTLR v3 from the command line? (ANTLR 3)
Labels: faq_gettingstarted, faq_general
Page: Where do I find this damn thing? (ANTLR 3)
Labels: faq_gettingstarted, faq_general
Page: How do I use ant with ANTLR 3? (ANTLR 3)
Labels: faq_gettingstarted
Page: Where does ANTLR write output files? (ANTLR 3)
Labels: faq_gettingstarted, faq_options
Page: How to run the generated Morpher.java? (ANTLRMorph)
Labels: faq_gettingstarted
Labels:
None
Edit Labels

3 Comments

Hide/Show Comments

  1. Oct 16, 2008

    Erik Purins

    As a win32 non-java dude starting with ANTLR, it took my awhile to figure out I actually needed the JDK (not just the JRE) to use the debugger, and that I had to manually config the path to javac. That's worth pointing out a little earlier, right by the part where you download and run antlrworks. After that, it was pretty smooth sailing. I can't believe how kickass a jumpstart this is, compared to starting with flex/bison nutshell book.

  2. Jan 08, 2009

    Tim Wersted

    Are the ANTLR runtimes besides Java (like C and Python) under the BSD license? I am under the impression they might not because they are written by other authors.

  3. Jan 08, 2009

    Terence Parr

    Yep, all BSD stuff. (smile)