Compiler-Generator Coco/R
=========================

               (Pat Terry,  updated Wed  05-13-98)
                       cspt@cs.ru.ac.za

Coco/R generates recursive descent parsers and their associated scanners from
attributed grammars.  The distribution kit contains source files for the
compiler generator Coco/R (Moessenboeck, 1990), as well as the executables,
frame files, and some sample applications.

Coco/R was originally written in Oberon by Hanspeter Moessenboeck.  It was
then ported into Modula-2; the first such port being done by Hanspeter
Moessenboeck for the Apple MacMeth system.  A port was done to JPI TopSpeed
Modula-2 at ETH Zurich by Marc Brandis and Christof Brass.  This was made
available to Pat Terry, who corrected several errors, enhanced the
portability, and provided the versions which you find on this distribution.
Responsibility for remaining bugs in these versions now rests largely with
Pat Terry.

The Modula-2 versions for WinTel platforms are known to be immediately
usable with any of the PIM based TopSpeed (JPI) compilers; the Fitted
Software Tools (FST) compilers, versions 2.x through 3.5; the StonyBrook
QuickMod 2.2 compiler; and the Logitech compiler, version 3.03.  As from
release 1.43, the system should also be fully compatible with ISO compilers
such as StonyBrook V4, and XDS from XTech Ltd.

Full source code for Coco/R compatible with these compilers is supplied.  It
is hoped that this will be trivially portable to other Modula-2 compilers
presently available, save for the I/O module used by Coco/R (and, in one
mode of use, its generated parsers); code for the I/O module for the
compilers listed above is, naturally, supplied.

So far as other operating systems are concerned, the Modula-2 versions of
Coco/R have also been ported to Mocka Modula-2 by Pat Terry and Toshinori
Maeno, for both Linux and BSD386, and to the Apple MAC p1 compiler by Woody
Yeung (yeung@reed.edu).  The source code is identical save for the I/O
modules for these compilers (which code is also provided in the DOS kit),
and in addition, distributions are available for these systems in their
native format.

Coco/R was first ported to Gardens Point Modula-2 by John Gough. (Gardens
Point Modula-2 is available for a wide variety of platforms, including Intel,
Sparc and MIPS machines).  The source code for the I/O modules for use with
the freeware Gardens Point Modula-2 for the PC (gpm-pc) is supplied with the
DOS distribution kit, and a complete port of Coco/R for the Unix hosted
versions of Gardens Point Modula-2 is also available.

Coco/R was also ported to TDI Modula-2 for the Atari by Rolf Schrader.
The sources (at level 1.39) are also supplied in a complete kit.  These
have numerous minor differences from the MS-DOS versions, although they
were derived from them, and not having access to an Atari, they have not
been kept up to date.  A contact address for this version is

    Rolf Schrader, Dipl.-Math. & Dipl.-Phys.,
    Kronenstr. 24,
    D-76133 Karlsruhe,
    Germany.

As from release 1.39, versions of Coco/R that produce Turbo Pascal units have
been made available through a port largely done by Volker Pohlers
(pohlers@escher.hrz.fh-stralsund.de), and now also maintained by Pat Terry.

There is also a C/C++ version of Coco/R, ported by Frankie Arzu
(farzu@daman.org or farzu@uvg.edu.gt).  As from version 1.06 a user has had
the option of generating either C or C++ code. The C++ version generates
scanner and parser classes based on a simple but effective class hierarchy.

All of these versions of Coco/R can bootstrap themselves to generate a
driver, parser, scanner, and semantic evaluator from an attributed grammar
CR.ATG.  This grammar thus serves as an an example of how to write compiler
descriptions for Coco/R.  There are also other simpler examples showing its
use.

Oberon versions of Coco/R are still available, and a new Java version has
recently been released.  These versions are maintained by Hanspeter
Moessenboeck in Linz (see address below).

It is important to realise that Coco/R is intended for use with grammars that
meet the LL(1) conditions.  Many grammars require some massaging before these
conditions are met.  Some of the examples in the kit are (deliberately)
non-LL(1), and are intended as examples for study and experiment.

While every attempt has been made to ensure that Coco/R performs
satisfactorily, the developers can accept no liability for any damage or
loss, including special, incidental, or consequential, caused by the use of
the software, directly or indirectly.


Where to get the latest versions
================================

Up to date information about Coco/r is available on the WWW at

        http://cs.ru.ac.za/homes/cspt/cocor.htm

The latest versions of Coco/R should be available for anonymous ftp from any
of the servers listed below (not all servers carry all versions):

In Europe

         ftp.ssw.uni-linz.ac.at:/pub/Coco

In Australia

         ftp.fit.qut.edu.au:/pub/coco

The freeware gpm-pc Modula-2 compiler is available on the same server.

In South Africa

         cs.ru.ac.za:/pub/coco

The latest shareware version of the FST Modula-2 compiler for the PC is
available on the same server in the directory /pub/languages.

In Central America

         uvg.edu.gt:/pub/coco

In the USA

         ftp.psg.com:/pub/modula-2/coco

where it also will be available by mail server

         To: server@ftp.psg.com
         From: <address to which it is to be sent>
         Subject: send pub/modula-2/coco/...

The latest shareware version of FST Modula-2 for the PC is available on the
same server in the directory /pub/modula-2 (fst-40s.lzh, compressed with
LHA).

The distributions come in various files (in each case "xxx" denotes the
release number, for example 143 for version 1.43)

    (a)    COCOxxx.EXE   - the kit for MS-DOS platforms
    (b)    gpmxxx.tgz    - the equivalent kit for Gardens Point
    (c)    ATARIxxx.EXE  - the kit for the Atari platform
    (d)    MOCKAxxx.tgz  - the kit for Mocka (Linux and 386BSD)
    (e)    COCOPxxx.EXE  - the kit for producing Turbo Pascal hosted in Modula
    (f)    TURBOxxx.EXE  - the kit for producing Turbo Pascal hosted in Pascal
    (g)    COCORCxx.ZIP  - the kit for producing C/C++
    (g)    README        - this file
    (h)    README.1st    - unpacking and installation notes

The kits contain sources, objects, examples and vanilla-ASCII documentation
files.  The MS-DOS versions are self-extracting files for MS-DOS, compressed
with the public domain utility LHA (which is also available on many Unix
systems).  All that is needed to install the system on a WinTel platform
is to copy the .EXE file to a suitable directory and to execute it.  About
1.6 MB of space is needed for the entire distribution, but several files
are compiler/platform specific, and need not be retained.

The Atari version is also supplied as a self-extracting file for MS-DOS.  It
is hoped that users will be able to find an easy way to transfer the files to
their Atari systems.  The Atari port is presently sufficiently different from
the others that the distribution kit is self contained, rather than being
merged with the MS-DOS versions.

For the latest on the Oberon versions, point your browser at

         ftp://ftp.ssw-linz.ac.at/pub/Oberon/LinzTools/Coco.cod

or look for the ile on the other mirrors.  Like the Modula-2 version, this
release comes with full source code.

For the Java versions, point your browser at

         http://www.ssw-linz.ac.at/Projects/Coco/Coco.html


FileList
========

The following gives an indication of the files provided in various kits of
Coco/R (Modula).  Essentially the same distribution is to be found in the
other kits (including the Pascal versions) - allowing for differences in
file and directory naming conventions.  There may also be extra files,
depending on the release date and version.  The Pascal kits have "units"
with extensions PAS, rather than separate DEF and MOD files.

  READ.ME              This file
  README.GPM           Notes on the Gardens Point implementation
  README.ISO           Notes on using the ISO compliant system
  README.1ST           Unpacking and installation information
  HELP.LHA             Notes on packing the kit with LHA
  PACK.BAT             Pack up system into a self-extracting file
  COCOR.EXE            Compiler-compiler executable
  HISTORY              Summary of bug fixes and modifications
  CONVERT.MOD          Program to convert text files between systems -
                       translating line marks appropriate to the O/S in use