Getting Started With ANTLR

Terence Parr

This Field Guide entry leads you through the development and execution of your first ANTLR parser and lexer. Follow these steps to achieve Nirvana:

1. Create a new file, t.g, and cut-n-paste in the following grammar.

   class P extends Parser;
   
   startRule
       :   n:NAME
           {System.out.println("Hi there, "+n.getText());}
       ;
   
   class L extends Lexer;
   
   // one-or-more letters followed by a newline
   NAME:   ( 'a'..'z'|'A'..'Z' )+ NEWLINE
       ;
   
   NEWLINE
       :   '\r' '\n'   // DOS
       |   '\n'        // UNIX
       ;
   

   The file does not need to end in ".g", but it is an ANTLR convention. Make sure your editor saves it as a text file. You can place this grammar file anywhere on your disk that you want, but it makes sense to have a directory for each Field Guide entry you complete. The next step assumes that the file is called "t.g" and that your current working directory is the one containing "t.g".

2. Have ANTLR process the grammar file from the command line with:

   java antlr.Tool t.g
   

   ANTLR will generate:

   • L.java
     The lexical analyzer (Lexer).
   • P.java
     The Parser.
   • PTokenTypes.java
     The token type definitions (integer constants). The Lexer breaks up the input stream of characters into vocabulary symbols called tokens, which are identified by token types.
   • PTokenTypes.txt
     A file containing all the token types that ANTLR can easily read back in if a parser in another file wants to use the vocabulary, lexer, or parser defined in t.g. You can look at this as a persistence file.

3. Create a file called "Main.java" that contains the following Java code:

   import java.io.*;
   
   class Main {
       public static void main(String[] args) {
           try {
               L lexer = new L(new DataInputStream(System.in));
               P parser = new P(lexer);
               parser.startRule();
           } catch(Exception e) {
               System.err.println("exception: "+e);
           }
       }
   }
   

   This main program creates a lexer, L, that reads input from standard input and then creates a parser, P, attached to that lexer. To begin parsing, the parser startRule method (resulting from the startRule grammar rule) is called.

   Any parser exceptions such as MismatchedToken will be caught by the "catch" block and an error will be printed.

4. Compile the output of ANTLR from the command line with:

   javac *.java
   

5. Run the resulting parser, Main, as you would any Java program. Here is a complete transcript from parser build through execution:

   on a DOS computer:
   c:\> java antlr.Tool t.g
   ANTLR Parser Generator   Version 2.20   1997 MageLang Institute
   c:\> javac *.java
   c:\> java Main
   Terence
   ^Z
   Hi there, Terence
   c:\>