Nikki DelRosso
CIS 461 - Intro to Compiler Construction
Spring 2013


Usage: coolc <FILE_INPUT> (<OUTPUT FILE>)

---------

Compiler for the Cool language for the University of Oregon spring 2013 
compilers class.  This compiler does not have the ArrayAny or Symbol classes 
implemented.


Prerequisites:
  This project was made using Python 2.7.3, and is not Python 3 compatible.
  Compliation also requires clang, and was made while using clang 3.0, which 
  corresponds to LLVM version 3.0.

  The path to the clang executable is configurable in the settings.py file.

Notes:
- String's substring and charAt methods don't check that the provided indices 
  are in bounds. Out-of-bounds incides will access unknown memory.

- The IO.in() method has an input limit of 1024 characters.  Overflowing input
  may be captured by subsequent in() calls.

- Since Symbol is not implemented, IO does not have the Symbol methods.

- There are almost certainly bugs!  Some files may not compile, but all of the 
  provided example files have been tested to work.
  

Final disclaimer:
  Anyone who happens to run across this project: it was written for a class, 
  and there are several problems with how it's put together - and some awful
  practices were thrown together in the final rush.  It's not good code! but
  it does appear to work, for what it's worth.

----------

Contents:

  coolc - A shortcut executable for running the driver file

  examples/  - Contains example cool programs
  |
  | A2I.cool      - The A2I class provided with the Cool materials for turning
  |                 Strings into Ints, and a driver for testing Int operators.
  |
  | hello.cool    - A simple hello world program.
  |
  | IOTest.cool   - Tests each of the IO methods.
  |
  | override.cool - Tests inheritance and override; uses 'this' and 'super'
  |
  | pal.cool      - Provided with the Cool materials. Takes a string as input
  |                 and tells you if that string is a palindrome.
  |
  | primes.cool   - Provided with the Cool materials. Generates prime numbers
  |                 until user-terminated.  This will crash fast, since there
  |                 is no garbage collection.
  |
  | strings.cool  - Tests each of the String methods.
  |

  README - You're reading it.

  src/  - Contains source code
  |
  | codegen/  - Contains code related to code generation
  | |
  | | build/   - Contains files needed to build the LLVM for final compilation
  | | |
  | | | basic.ll - LLVM program defining the basic.cool functionality
  | | |
  | | | blank.c  - Empty file - used for generating LLVM headers automatically
  | | |
  | | | driver.c - C driver for running llvm_main, and some other helper code
  | | |
  | |
  | | __init__.py      - Control code for codegen to be used by the driver
  | |
  | | basic.cool       - The basic.cool file for Cool 2013.  Just there for 
  | |                    documentation purposes.
  | |
  | | nodes.py         - This file has classes matching those in the AST, and
  | |                    defines the code generation rules for those nodes.
  | |
  | | node_code_gen.py - Base class for codegen nodes
  | |
  |
  | ply/          - The PLY library (so you don't have to install it!)
  |
  | type_checking - Contains code related to type checking
  | |
  | | __init__.py     - Control code for type checking to be used by the driver
  | |
  | | environment.py  - Keeps track of variables, methods and classes during 
  | |                   type checking.Also keeps track of static information for 
  | |                   vars/attrs/methods.
  | |
  | | nodes.py        - This file has classes matching those in the AST, and 
  | |                   defines the type checking rules for those nodes.
  | |
  | | node_checker.py - Base class for the checker nodes
  | |
  |
  | driver.py - The driver file.  Takes a cool file as input, and runs the lexer
  |             and parser on the file.
  |
  | error.py  - Contains exceptions for error handling.  Includes the 
  |             calculation of columns for error reporting
  |
  | lexer.py  - Contains lexing rules, token definitions, and a list of 
  |             "Extended Cool" reserved words
  |
  | parser.py - Contains grammar rules and builds an abstract syntax tree using
  |             nodes from tree.py.  The yacc script generates a parse table on 
  |             its first run.
  |
  | tree.py   - Class definitions for the AST nodes, including methods to print 
  |             the tree.
  |
  | tree_linker.py - Defines a base class for the control code in codegen and
  |             type checking.  Links nodes from the AST to nodes in another
  |             module file if they have the same name.
  |