LPG Windows Distribution ReadMe file  May 16, 2006

This is the ReadMe file for the opensource distribution of the LALR Parser Generator (LPG).

LPG consists of a generator component and a Java runtime component.  In addition there are two
examples and documentation on using the lpg package.  We hope to add additional runtime
support (particularly C/C++) in the future.

The important features of LPG include: lexical analysis using lalr parsers, a backtracking parser, 
soft-keyword recognition, error diagnosis and recovery, grammar inheritance, automatic AST 
generation and templates to guide generation of scanners and parsers writtin in Java.

The distribution consists of the following files and directories:
(1) ReadMe.txt -- this file
(2) lpgjavaruntime.jar -- the Java runtime (includes parsers, lexers and stream and AST support
(3) docs -- lpg documentation ("Getting Started with LPG" is out of date, but "Using the LALR PArser Generator" is new)
(4) examples -- a simple expression example and a parser for the Java language (source only)
(5) lpgjavaruntime -- the runtime Java source (class files included in the bin directory)
(6) include -- a directory containing some common code used in LPG scanners
(7) lpgexe -- contains the generator, lpg.exe (compiled with MS C++ compiler)
(8) lpgsource -- the generator C++ source
(9) templates -- java code templates that facilatate generation of parsers and scanners

This distribution also contains ".classpath" and ".project" files so it can be added as an 
eclipse project (say with the name lpgdistribution).  Projects that use lpg can obtain access to
the runtime either through the jar file, lpgjavaruntime.jar, or through the class files generated
from the lpgjavaruntime source directory.

You may wish to create an eclipse external tool to execute lpg.exe on the grammar files.  
The "location" should be the path for lpg.exe; the working directory should be ${container_loc} 
and the arguments could be -list ${resource_loc}. It is necessary to set two environment variables
(under the Environment tab) if you want lpg to compile the examples.  Set "LPG_INCLUDE"  to be 
the location of the "include" directory in your lpg.  Similarly, set "LPG_TEMPLATE" to be the 
location of the template directory.  

Should you wish to run lpg from the command line, set these two environment variables as indicated.
If you use templates but keep them in the directory with the grammar files, then you do not need 
the LPG_TEMPLATE environment variable.  Also, if you do not use LPG $Include sections or if your 
included files are in the input grammar file directory then you do not need the LPG_INCLUDE environment 
variable.
