-------------------------------------------------------------------------------
| Developers' Readme.txt                                                      |
-------------------------------------------------------------------------------

This document shows how to build the source code of JassLib. If you require
further assistance, please feel free to email jp@magnus99.dhs.org.

Building
--------

1) Install a Java Development Kit (J2SE). Windows users can get one from
   Sun Microsystems (http://java.sun.com). Mac users will have one if they
   install Apple's developer tools.

2) Install some basic UNIX tools. Mac OS X users will already have them
   available with Apple's developer tools. Windows users are encouraged to
   use Cygwin (http://www.cygwin.com). At a minimum you need a bourne shell
   (sh), GNU make, sed, cd, ls, mkdir, cp, rm, tar, zip, and possibly others.
   Perl is required for running tests.

3) Enter the top level directory JassLib/. Type:

make

This will build all the Java class files in src/.

4) To build the Demo JASS Syntax Checker, type:

make demo-win32

for the windows version and

make demo-mac

for the Mac OS X version. This will also create lib/jass.jar, which is a
JAR archive of all the required classes.

Directories
-----------

bin/          - some utility shell and perl scripts
etc/          - files distributed with packages
lib/          - required libraries for compiling and runtime
src/          - source code
test/         - regression tests

Packages
--------

jass.api      - API for syntax checking
jass.demo     - demo GUI application that uses the API
jass.syntax   - core syntax checking implementation
jass.util     - utility classes

API Usage
---------

If you wish to use the syntax checking API in your own Java program, build
jass.jar as described above. Then look at the class
jass.api.SyntaxAnalyzer for how to use the basic API. You can use
jass.demo.DemoChecker as an example. When you run your program, you
need to include jass.jar and jcup.jar in the classpath.

Implementation Notes
--------------------

If you browse through the jass.syntax package, you will probably observe
that the syntax analyzer goes to an unnecessary amount of trouble (and hence
the code is a bit bloated). For example, the analyzer strictly goes through
three distinct phases: lexical analysis (tokenizing), parsing (grammar
analysis -- construction of an abstract syntax tree), and semantic
analysis (type checking and analyzing the AST). These three steps are
usually required for a lanuage with a context free grammar and forward
references. Because I "reverse engineered" the JASS language as I wrote
the analyzer, I didn't know until I finished that forward references are
illegal in JASS. Hence, analysis can really be done in one pass.

If I were to start over (or if you were to write a parser), here are the
design improvements I would make based on the JASS language's features:

 * Forget about writing a grammar for the entire input stream. Instead,
   after tokenizing the stream treat each line individually (grammars
   that are not free form and delimited by newlines are ugly). All
   lines are trivially checked by manual examination except for expressions.
   Just write a grammar for expressions and delegate the stream to the
   parser when you need to check an expression. As a bonus, this allows
   you to make error messages for some syntax errors more meaningful.

 * Do semantic analysis in the same pass that you parse. Because there can not
   be forward references, you don't have to worry about stuff that hasn't
   been parsed yet. This is faster and memory efficient since you don't have
   to build an AST (you can check each expression's tree on the fly as you
   parse it). You still do need to keep around a symbol table for variables
   and function names (and a type tree for handle types) obviously. Also,
   since you don't have to keep an AST around, memory management is much
   simpler.

 * Parse individual files separately. There is a wierd ordering of certain
   global declarations that has to be maintained within each file, but
   not among all files (which makes sense since there isn't really an
   "include" or "import" method). Just keep around the symbol table and type
   tree after you parse the library files like common.j.

 * Don't use a global (i.e., "static") symbol table. This ugly design hack
   exists in my code because I derived it from one of UC Berkeley's undergrad
   compiler project templates. Design so you can easily "export" the symbol
   table and type tree to a stream (e.g., file) and import it back -- 
   this way you can "precompile" the library files like common.j and only 
   have to load the symbol table and type tree instead of having to re-parse 
   it every time.

Of course, these suggestions are for an analyzer that is built for speed;
it is not very flexible and would be difficult to adapt if a major change 
were made to the JASS language (e.g., forward references). Obviously, also
write it in C or C++. Java, Perl, VB, etc. are for prototyping -- this is 
the prototype. :)
