toothbrush / cco-tdiag Goto Github PK

README file for the 2nd assignment of Compiler Construction

T-Diagrams

9 March, 2011

Author: Paul van der Walt (3120805)

------------------------------------------------------------------------------------------

FOR THE RUSHED

$ tar xvvzf tdiagrams-0.0.4.tar.gz
$ cd tdiagrams-0.0.4/
$ cabal configure
$ cabal build
$ cabal install
$ cat exampleX.tdiag | parse-tdiag | tc-tdiag | tdiag2picture | pp-picture > output.tex
$ open output.tex

------------------------------------------------------------------------------------------

FOR THE IMPATIENT

To get started, unpack this tarball (evidently this was successful if you're reading
this), and run:

$ cabal configure
$ cabal build

and optionally 

$ cabal install # this is so you can run the commands directly, 
                # without invocations like `dist/build/parse-tdiag/parse-tdiag`. 

For documentation:

$ cabal haddock

Documentation gets placed in dist/doc/html/tdiagrams/index.html (this is a good starting
point). To try out the various examples, assuming you have run `cabal install`, try 
the following:

$ cat exampleX.tdiag | parse-tdiag | tc-tdiag | tdiag2picture | pp-picture > output.tex

or if you'd rather not install:

$ cat exampleX.tdiag | dist/build/parse-tdiag/parse-tdiag | dist/build/tc-tdiag/tc-tdiag \
                     | dist/build/tdiag2picture/tdiag2picture | dist/build/pp-picture/pp-picture \
                     > output.tex

and open the generated file, output.tex, in a text editor, or, optionally, compile with PDFLaTeX.
To do this though, you will need to wrap the output in a 

\documentclass{article}
\begin{document}
...
\end{document}

format. The T-Diagram process may take a while, so don't be surprised if it's
not finished after 5 seconds. 

There are also files called 'badexample?.tdiag', these cntain various errors and are 
supposed to fail type checking. 

-------------------------------------------------------------------------------------------

EXAMPLES

A number of examples are included, see ./example?.tdiag, the examples
illustrate the features of this implementation of tdiagrams. Examples 1-4 just
use the primitive building blocks, examples 5 and 6 show the use of compilation
and execution, and example 7 illustrates the composition of diagrams. The bad
examples (1-4) illustrate the following errors, respectively:

1. Attempting to execute a platform,
2. Executing anything on a program,
3. Executing a program on a compiler or interpreter of the incorrect type,
4. Compiling a platform.

-------------------------------------------------------------------------------------------

FOR THE PATIENT (or the more curious)

The included Makefile takes care of generating Haskell from the Attribute
Grammar (AG) sources, then runs the usual cabal {configure,make} incantation.
Just running `make' should be sufficient to get a working toolset. Try `cabal
haddock' to see the online generated Haddock documentation, where the details
are given which aren't covered in the design docs. 

Features

This implementation supports the basic T-Diagram features, which are:

* Converting any valid T-Diagram into LaTeX code
* Support for arbitrary nesting of diagrams
* Type checking (including language compatibility and block-compatibility, i.e.
  one cannot compile an execution)

In a future version, possibilities for improvement include:

* Support for comments in .tdiag files
* Support binding diagrams to variables
* Improve type checking method (get rid of useless category attribute)

Requirements:

This package has been tested on Mac OS X.6 and Linux 2.6.35, using GHC6.12.3 and GHC7.0.1.
Also required are at least the following packages (can be obtained via the Haskell Cabal):

- cco
- uuagc

Documentation:

For extensive documentation, as well as a report detailing implementational details and 
architecture of this suite, we refer the reader to the Haddock generated documentation. 
This can be obtained by running

$ cabal haddock

and opening the resulting file, dist/doc/html/tdiagrams/index.html. This file includes
an introduction as well as links to the rest of the documentation.

There is also a design document, giving more of an executive summary than can be gleaned
from the Haddock. This can be generated with

$ make documentation

Afterwards, open the file doc/design.pdf