Antlr - Getting Started (Hello World)

About

A getting started page that brings you in the world of Antlr.

Steps

Installation

Antlr - Installation (Version 4)

Grammar

Create a grammar file called Hello.g4 and define the grammar called Hello

grammar Hello;     // The name of the grammar is Hello
r  : 'hello' ID ;         // The rule/production r match keyword `hello` followed by the rule `ID`
ID : [a-z]+ ;             // The rule/production `ID` match all lower-case characters
WS : [ \t\r\n]+ -> skip ; // This WS rule (WhiteSpace) skip spaces, tabs, newlines

where:

• ID : [a-z]+ ; and WS : [ \t\r\n]+ → skip are lexer rule (name is uppercase) that defines the tokens.
• r : 'hello' ID ; is a parser rule that defines the relation between the tokens to build the parse tree

Generate the lexer and parser

with the antlr command line

cd /temp/hellog4
antlr4 Hello.g4 # Run the tool

Next to the grammar file, you got:

• the lexer HelloLexer.java - to create the token
• the parser HelloParser.java - to build the tree
• the listener HelloListener.java - to traverse the tree

ls -A1

Hello.g4
Hello.interp
Hello.tokens
HelloBaseListener.java
HelloLexer.interp
HelloLexer.java
HelloLexer.tokens
HelloListener.java
HelloParser.java

• Compile the java file
  • The cp (class path) option should point to the antlr jar file downloaded during the installation
  • javac is the compiler and is in the bin directory of the jdk (Example: c:\java\jdk1.8.0_231\bin\javac)

javac -cp "C:\antlr\antlr-4.8-complete.jar" Hello*.java # Compile the generated class

• The following compiled java class file were created

ls -A1 *.class

HelloBaseListener.class
HelloLexer.class
HelloListener.class
'HelloParser$RContext.class'
HelloParser.class

Parse and print the tree

With the LISP notation

Start grun

grun Hello r -tree

where:

• Hello is the name of the grammar (ie the file name without the extension)
• r is the start rule to where to build the tree
• -tree prints the parse tree in LISP notation.

Enter the text to parse and terminate with an End of File Character

• Type Ctrl+D (^D) on unix
• or Ctrl+Z (^Z) on Windows

hello Nico # Type hello + your name
^Z  # End of file (Ctrl+Z)

• Output

(r hello nico)

With the gui parse tree inspector

With the minimal grun gui parse tree inspector

grun Hello r -gui

hello nicoooo # Type your text to parse
^Z # send an end of file ( Ctrl+Z - windows or Ctrl-Z linux)

With Idea plugin

With the idea plugin:

• right click on the line of the start rule
• start to type a text to see the tree

With Java

With all import from org.antlr.v4

public class Hello {

    public static void main(String[] args) {

        // The input
        String input = "hello nico";
        ANTLRInputStream inputStream = new ANTLRInputStream(input);

        // Lexer
        HelloLexer lexer = new HelloLexer(inputStream);

        // Stream of token
        CommonTokenStream commonTokenStream = new CommonTokenStream(lexer);

        // Create the parser
        HelloParser parser = new HelloParser(commonTokenStream);

        // Create the tree from the r parser rule
        ParseTree tree = parser.r();

        // Print the tree
        printNode(tree, 0, Arrays.asList(parser.getRuleNames()));

        // Or with the utility function to print the LISP-style tree
        // equivalent to `grun Hello r --tree`
        System.out.println(tree.toStringTree(parser));
        
    }

    /**
     * Recursive function to print a node
     * @param node
     * @param level
     * @param ruleNames
     */
    private static void printNode(ParseTree node, int level, List<String> ruleNames) {
        String nodeText = Trees.getNodeText(node, ruleNames);

        // Print
        StringBuilder line = new StringBuilder();
        IntStream.range(0, level).forEach(i -> line.append(" "));
        line
                .append("Level ")
                .append(level)
                .append(" - ")
                .append(nodeText);
        System.out.println(line.toString());


        // Chilrdnre
        if (node instanceof ParserRuleContext) {
            ParserRuleContext parserRuleContext = (ParserRuleContext) node;
            if (parserRuleContext.children != null) {
                for (ParseTree child : parserRuleContext.children) {
                    printNode(child, level + 1, ruleNames);
                }
            }
        }
    }
}

Level 0 - r
 Level 1 - hello
 Level 1 - nico

• LISP

(r hello nico)

Support

Can't load Hello as lexer or parser

when starting grun, you may get the following error:

Can't load Hello as lexer or parser

This is because the lexer and parser generated class file are not in the classpath.

For dos, be sure that the doskey has the current directory (ie .;) in the classpath. Example:

doskey grun=java -cp ".;C:\antlr\antlr-4.8-complete.jar" org.antlr.v4.runtime.misc.TestRig $*

Documentation / Reference

• https://github.com/antlr/antlr4/blob/master/doc/getting-started.md
• Videos and tuto
• Parsing XML with Antlr3
• Antlr 3 Getting Started