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} egin{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. Trycabal 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