This package contains a evaluator and online and offline partial
evaluators for a simple Flow Chart Language (FCL).  To run it, you
first must set it up in your CLASSPATH.  In bash it would look like:

     export CLASSPATH=$CLASSPATH:$HOME/FCL-Java-compiled

if you decompressed it in your home directory.  This
directory contains several subdirectories:

  JLex     - contains a lex-like tool for Java
  java_cup - contains a yacc-like tool for Java
  fcl      - contains the code for the fcl evaluator and partial evaluators

The fcl implementation uses a parser generated with JLex and java_cup,
but we need not be concerned with with these directories.

Now go to the fcl directory.

In the file Makefile there are several different options.  
The most useful are those which run the fcl systems on examples.
These are:

   test - runs a simple test programs that finds the nth prime number
   PEtest - runs an online partial evaluator on the power example
   Offtest - runs an offline partial evaluator on the power example
   turing - runs an online partial evaluator on a simple turing machine
   turing2 - runs an offline partial evaluator on a simple turing machine

If you look at the Makefile, you will see how to run the systems
directly from the command line.  For example,

..this runs the evaluator to find the 5th prime number

	java fcl.eval -f examples/prime.fcl 5

..this runs the evaluator to find the 5th prime number (with
    debug level set to 5 -- this will print out trace information.)

        java fcl.eval -f examples/power.fcl -debug 5 5 2

..this runs the online PE to specialize the power program to
  exponent value of 3.

	java fcl.onlinePE -f examples/power.fcl DYNAMIC 3

..this runs the offline PE to specialize the power program to
  exponent value of 3.

	java fcl.offlinePE -f examples/power.fcl DYNAMIC 3

There are a few other options:

   clean - remove all the .class and ~ files.
   distclean - remove all non-source files
   docs - makes html documentation for the fcl packages

Finally, you can use the Makefile to compile the evaluator,
online PE, and offline PE.

** Note: make sure that you use the GNU version of make.
This is 'gmake' on the DIKU HP machines.


The programming exercises involve filling in code templates in
this directory.  Fortunately, I have supplied most of the code
for you.  You will need to look at a lot of code to see what is
going on.  I printed out the code using the following command
in the Makefile.  There is no table of contents, but the command
below should give you some idea of the order of the files.

printout:
	a2ps -o fcl.ps -A README.txt \
        eval.java onlinePE.java offlinePE.java \
        prog/Prog.java \
        blocks/BlockList.java blocks/Block.java blocks/BlockTuple.java \
        statements/StatementList.java statements/Statement.java \
        statements/AssignStatement.java \
        exprs/ExprList.java exprs/Expr.java exprs/ConstExpr.java \
       exprs/OpExpr.java exprs/Op.java exprs/VarExpr.java exprs/LiftExpr.java \
        prog/Node.java prog/VarList.java prog/Var.java \
        jumps/Jump.java jumps/Goto.java jumps/If.java jumps/Return.java \
        jumps/JumpPair.java jumps/JumpTuple.java \
        labels/LabelSet.java labels/Label.java labels/StoreLabel.java \
        values/ValueList.java values/Value.java \
        values/TagValue.java values/TagValueList.java \
        values/IntValue.java values/BoolValue.java values/SymValue.java \
        values/NullValue.java values/CellValue.java \
        store/Store.java \
        types/Type.java types/Signatures.java types/Signature.java \
        states/Pending.java states/StateSet.java states/State.java \
        util/List.java util/Set.java util/Table.java util/mappable.java \
        util/Spec.java 

The main data structure in the implementations is the abstract syntax
tree.  For each node in the abstract syntax tree there are methods
to evaluate, onlinePE, and offlinePE the node.  So for example,
to fill in the templates for the onlinePE, you will need to modify
the code for each of the abstract syntax tree nodes:

      prog/Prog.java, blocks/BlockList.java, blocks/Block.java,
      jumps/If.java jumps/Goto.java ......etc.....

Here is a brief explanation of the files.

The files

      eval.java onlinePE.java offlinePE.java

are just boring top level calls that parse input, etc.  You shouldn't
worry too much about these.

The file         

      prog/Prog.java 

is important.  It gives the top-level loop for the evaluation, 
onlinePE, and offlinePE.

The files blocks/* statements/* exprs/* jumps/*  implement the AST
nodes for the syntactic constructs of the language.  

As it stands, all the code for the evaluator is given.  However,
you will need to modify the files below to get the online and 
offline PE's working.

   jumps/If.java
   statements/AssignStatement.java
   exprs/VarExpr.java
   exprs/OpExpr.java