This is the provided git repository for the WACC compilers lab. You should work 
in this repository regularly committing and pushing your work back to GitLab.

----------------------------
Provided files/directories  
----------------------------

> antlr <

The antlr directory contains simple example ANTLR lexer and parser specification
files BasicLexer.g4 and Basic.g4, along with a script antlrBuild that builds the
corresponding Java class files using the ANTLR libraries (more details below).
  
> lib <

The lib directory contains the ANTLR library files in antlr-4.4-complete.jar. 
You should not need to make any changes in this directory.
  
> src < 

The src directory is currently empty (apart from a simple README file) and is 
where we expect you to write your compiler code.

> grun <

The grun script allows you to run the ANTLR TestRig program that can assist you 
in debugging you lexer and parser (more details below).

> compile <

The compile script should be edited to provide a frontend interface to your WACC
compiler. You are free to change the language used in this script, but do not 
change its name (more details below).

> Makefile <

Your Makefile should be edited so that running 'make' in the root directory 
builds your WACC compiler. Currently running 'make' will call the antlrBuild 
script and the attempt to compile all .java files within the src directory. 
Depending on the structure of your code, you might not need to modify this file.

----------------------------
Using the provided scripts
----------------------------

> antlrBuild <

This script takes a pair of ANTLR lexer and parser configuration files (set 
within the script) and creates the corresponding Java classes that you can use
in your compiler. The Java files are written to the src/antlr directory and 
should not be modified by hand. By default this script is set up to generate a
parse tree and a listerner pattern for traversing this tree, but you can modify
the compilation options within the script if you want to produce different 
outputs

Important! - running the antlrBuild script will overwrite the antlr directory in
             the src directory. We heavily suggest you do not write any of your
             code within the src/antlr directory

> grun <

This script provides access to the ANTLR TestRig program. You will probably find
this helpful for testing your lexer and parser. The script is just a wrapper for
the TestRig in the project environment. You need to tell it what grammar to use
what rule to start parsing with and what kind of output you want.

For example:
  ./grun antlr.Basic prog -tokens
will run the TestRig using the 'Basic' grammar, starting from the rule fo 'prog'
and outputting the tokens seen by the lexer. To see how the parser groups these 
tokens you can use the -tree or -gui options instead, such as:
  ./grun antlr.Basic prog -gui
In either case you will need to type in your input program and then close the 
input stream with ctrl-D.

Rather than typing your input programs in by hand, you can pass the TestRig a 
file to read by piping it in through stdin with
  ./grun antlr.Basic expr -gui < testfile
When using the TestRig in this way you won't need to hit ctrl-D to close the 
input stream as the EOF character in the file does this for you.

> compile <

This script currently writes a TODO: message to the console, but you should
update it to call the the main class of your compiler with appropriate 
arguments. Note that the lab's automated testing service will be using this 
script as the access point to your compiler.

You will need to add the ANTLR jar file to the classpath of your calls to Java
if you want to be able to use any of the built in ANTLR features. You can do 
this be setting the -cp option on the command line
  e.g.  java -cp bin:lib/antlr-4.4-complete.jar ...rest of call...
note that the bin: ensures that the bin directory is still part of your java 
classpath.