###############################################################################
# File:         README
# Author:       Alex Brandt
# Date:         2009/12/14
###############################################################################

*******************************************************************************
* INSTALL
*******************************************************************************

This utility is a minimal pascal compiler that should compile to an
intermediary language appropriate for running in the shazam virtual
environment.  This program was created using Gentoo Linux with a 2.6.30 gentoo
sources kernel revision 4 on an X86_64 architecture.  The compiler used for
building and testing is gcc version 4.3.2 release 3 in the portage tree
provided by Gentoo (www.gentoo.org).  This software is licensed under the GPL
as specified in the file COPYING.

Build Instructions:

$mkdir -p ${BUILD_DIR}
$cd ${BUILD_DIR}
$cmake ${SRC_DIR}
$make

If you want this installed to /usr/local type:

$make install

The executable will be in ${BUILD_DIR}/src/pl0.

***********************
* Program Description *
***********************

This program utilizes the following:
  1) STL map
  2) STL list
  3) Boost Program Options
  4) STL vector
  5) Boost Lexical Cast
  6) FLEX (Lexical Analyzer Generator)

****************************
* Program Input and Output *
****************************

Input ::
  Options which are parsed from the CLI as well as a set of source files to
  compile.

Ouput ::
  Outputs any syntax errors in the input file and prints out a semi-meaningful
  error report.  If any errors are reported the output file will not be
  generated.  A file that will work with the fsti interpreter will be output in
  a.st or whatever filename is specified in the -o option.

**************
* File Index *
**************

include/compiler.h
  - Compiler class declaration.
    * Specification of the Compiler class.

include/instruction.h
  - Instruction class declaration.
    * Specification of the Instruction class.

include/programstore.h
  - ProgramStore class declaration.
    * Specification of the ProgramStore class.

include/symboltable.h
  - SymbolTable class declaration.
    * Specification of the SymbolTable class.

include/symboltableentry.h
  - SymbolTableEntry class declaration.
    * Specification of the SymbolTableEntry class.

include/compiler.cpp
  - Compiler class declaration.
    * Implementation of the Compiler class.

lib/instruction.cpp
  - Instruction class declaration.
    * Implementation of the Instruction class.

lib/programstore.cpp
  - ProgramStore class declaration.
    * Implementation of the ProgramStore class.

lib/symboltable.cpp
  - SymbolTable class declaration.
    * Implementation of the SymbolTable class.

lib/symboltableentry.cpp
  - SymbolTableEntry class declaration.
    * Implementation of the SymbolTableEntry class.

lib/scanner.l
  - Flex definition file to generate a lexical analyzer.
    * Definition of regular patterns and other flex necessities.

lib/parser.y
  - Bison definition file to generate an LALR parser.
    * Definition of the the translation scheme.

lib/CMakeLists.txt
  - CMake definition file for lib.
    * Defines parser library.
    * Defines symboltable library.
    * Defines tokenizer library.

src/main.cpp
  - Main function declaration.
    * Creates a Compiler and Runs it.

src/symboltabletest.cpp
  - Main function declaration.
    * Creates a SymbolTable and tests it.
    * Not linked into main executable.

src/CMakeLists.txt
  - CMake definition file for src.
    * Defines pl0 executable.

test/fuzzer.py
  - Python script that generates random PL/0 files.
    * Creates random input files for the pl0 executable.

CMakeLists.txt
  - CMake definition file for this project.
    * Directs compilation of subdirectories.

COPYING
  - Copy of the GPLv2.

README
  - This file.

*******************
* Program Testing *
*******************

A series of test programs are available in the test directory.  Each file has a short
description at the top with the intended test.

**************
* Known Bugs *
**************

 * Passing arrays as parameters does not work at all.
 * Return values behave incorrectly in recursive functions.
 * Other misbehaving return types haven't been noticed, but probably exist due to the previous caveat.

No other currently known issues exist within the application.

If bugs are found please email Alex Brandt <alunduil@alunduil.com>.