README file for Programming Assignment 3 (Java edition)
=======================================================

Your directory should now contain the following files:

 Makefile
 README
 cool.cup
 bad.cl
 good.cl
 cool-tree.java		  -> [cool root]/src/PA3J/cool-tree.java
 cool-tree.aps		  -> [cool root]/src/PA3J/cool-tree.aps
 AbstractSymbol.java	  -> [cool root]/src/PA3J/AbstractSymbol.java
 AbstractTable.java	  -> [cool root]/src/PA3J/AbstractTable.java
 BoolConst.java		  -> [cool root]/src/PA3J/BoolConst.java
 CgenClassTable.java	  -> [cool root]/src/PA3J/CgenClassTable.java
 CgenNode.java		  -> [cool root]/src/PA3J/CgenNode.java
 CgenSupport.java	  -> [cool root]/src/PA3J/CgenSupport.java
 ClassTable.java	  -> [cool root]/src/PA3J/ClassTable.java
 CoolParser.java	  -> [cool root]/src/PA3J/CoolParser.java
 CoolTokenLexer.java	  -> [cool root]/src/PA3J/CoolTokenLexer.java
 Flags.java		  -> [cool root]/src/PA3J/Flags.java
 IdSymbol.java		  -> [cool root]/src/PA3J/IdSymbol.java
 IdTable.java		  -> [cool root]/src/PA3J/IdTable.java
 IntSymbol.java		  -> [cool root]/src/PA3J/IntSymbol.java
 IntTable.java		  -> [cool root]/src/PA3J/IntTable.java
 ListNode.java		  -> [cool root]/src/PA3J/ListNode.java
 Parser.java		  -> [cool root]/src/PA3J/Parser.java
 StringSymbol.java	  -> [cool root]/src/PA3J/StringSymbol.java
 StringTable.java	  -> [cool root]/src/PA3J/StringTable.java
 SymbolTable.java	  -> [cool root]/src/PA3J/SymbolTable.java
 TokenConstants.java	  -> [cool root]/src/PA3J/TokenConstants.java
 TreeConstants.java	  -> [cool root]/src/PA3J/TreeConstants.java
 TreeNode.java		  -> [cool root]/src/PA3J/TreeNode.java
 Utilities.java		  -> [cool root]/src/PA3J/Utilities.java
 *.java			  other generated files

	The Makefile contains targets for compiling and running your
	program. DO NOT MODIFY.
    
	The README contains this info. Part of the assignment is to
	fill in the README with the write-up for your project. You should
	explain design decisions, explain why your code is correct, and why
	your test cases are adequate. It is part of the assignment to
	clearly and concisely explain things in text as well as to comment
	your code. Just edit this file.

	cool.cup is the skeleton for the parser specification that you
	are to write. It already contains productions for the program
	and the classes. Use them as an example to write the remaining
	productions.  You should also read the CUP documentation.
	This skeleton will compile and run as is, but it doesn't
	do much.

	good.cl, bad.cl test a few features of the grammar. You should
	add tests to ensure that good.cl exercises every legal
	construction of the grammar and that bad.cl exercises as many
	different parsing errors as you can squeeze into one file.

	cool-tree.aps contains the definitions for the tree language
	which you use to construct the abstract syntax tree (AST).  From
	this file, cool-tree.java is automatically generated by a
	utility that compiles the specification into Java classes for
	constructing tree nodes.  This file is provided for your
	reference.  DO NOT MODIFY.

        TreeNode.java and ListNode.java contain definitions used by the
        tree package. DO NOT MODIFY.  

        Parser.java contains a driver to test the parser. DO NOT MODIFY.

	Flags.java implements routines for parsing command line
	flags. DO NOT MODIFY.

        The rest of the files are created as byproducts of `CUP', or
        are internal parser support files.  DO NOT MODIFY.
        `CoolParser.java' is the generated Java file containing the
        parser.  DO NOT MODIFY this file directly; instead, edit
        cool.cup and this file will be regenerated automatically.

	Files not discussed are covered in the README for PA2J.

Instructions
------------

	To compile your parser program type:

	% make parser

	This compiles all the classes and produces an shell script named
	"parser" which invokes Parser.main() as the standalone phase of
	the Cool compiler.  It requires lexer, semant, and cgen to do
	anything useful.

	To test your parser on a file 'foo.cl' type

	% myparser foo.cl

	myparser is a shell script that "glues" together lexer and
	parser using pipes.  Don't worry if the line numbers you get by
	running Java version of the parser are slightly off as compared
	to the "official" parser.

	To run your parser on the files good.cl and bad.cl type:

	% make dotest

	To run the (provided) lexer and your parser on a file called test.cl type:

	% ./lexer test.cl | ./parser

	If you think your parser is correct and behaves like
	the one we wrote, you may want to run a COOL compiler using
	your parser:

	% mycoolc foo.cl

	To overwrite the default lexical analyzer with yours, replace 
	lexer (which is a symbolic link to the "official" lexer) with
        your lexer from PA2.

	If you change architectures you must issue

	% make clean

	when you switch from one type of machine to the other.

	GOOD LUCK!

---8<------8<------8<------8<---cut here---8<------8<------8<------8<---

Write-up for PA3J
-----------------