Using ANTLRWorks with Java.g

ANTLRWorks is a GUI development environment for ANTLR grammars. Using ANTLRWorks, you can see how ANTLR uses the grammar to analyse any Java source code you provide.

The following instructions provide a brief tutorial to show you how to use ANTLRWorks with Java.g.

Download ANTLRWorks.

You can download ANTLRWorks from the ANTLR download page at http://antlr.org/download.html. The current version of ANTLRWorks is 1.2.1. You can also download it directly from http://www.antlr.org/download/antlrworks-1.2.1.jar
Start ANTLRWorks.

Usually if you have JRE installed, you should be able to double-click the downloaded .jar file and start ANTLRWorks directly. If this doesn't work, run:
```
java -jar antlrworks-1.2.1.jar
```
Open the file Java.g in ANTLRWorks.

Save the file to your local disk, select File→Open, then choose Java.g. The window should look like this: (click on image for full size image)
Set parameters for ANTLRWorks.

Select File→Preferences, then in ANTLR options, add:
```
     -Xconversiontimeout 100000
```
The window should look like this:

Then press Apply and close the window.
Start the debugger.

Select Debugger→Debug, then input the following program into the Text area:
```
            public class Test {
                public  static void main(String[] args) {
                    System.out.println("Hello world!");
                }
            }
            
```
Make sure you check the Text option rather than File, and make sure that compilationUnit is selected for Start Rule.

Then press OK to start debugging. The window should look like this:

Note: if the window does not respond for a while or if it gives an exception, try to restart ANTLRWorks with an increased 512M heap.
```
java -Xmx512m -jar antlrworks-1.2.1.jar
```
Debugging the input.

On the bottom half of the window, you should see a debugger panel like this:

By putting the cursor on top of each button, you should see a tool tip explaining what it is used for. This is similar to how you would debug a Java program in Eclipse, NetBeans and other IDEs.

Then, by clicking the Step Forward button, you should be able to see how the parser recognizes the input and what paths it tries in the three windows on the bottom.

The Input window shows the tokens the parser reads in currently. The Parse Tree window shows the rules that have been traversed or tries in a tree. The Stack window shows a stack of rules that has been called.

There are many other menus/tabs for you to explore, but this should be enough to get you started. You can find the full ANTLRWorks documentation at the ANTLR website (http://www.antlr.org/works/index.html).