Compiler-Generator Coco/R  (C/C++ Version 1.08 - 1.12)
=========================================================================

           (Frankie Arzu  Mar-31-1998
            e-mail:farzu@uvg.edu.gt or farzu@damanconsulting.com)

Coco/R generates recursive descent parsers, their associated scanners, and
optionally driver programs, from LL(1) attributed grammars.

Coco/R can bootstrap itself to generate its own driver, parser, scanner, and
semantic evaluator from the attributed grammar CR.ATG.  This grammar thus
serves as an example of how to write compiler descriptions for Coco.  There
are also other simpler examples in the distribution kit showing its use.

It is important to realize 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.

The distributions contain sources, objects, examples and ASCII-TEXT
documentation files.

Compiler-Generator Coco/R for C/C++  (Version 1.12)
=========================================================================

"Coco/R for C" is an implementation of Coco/R written in C that can generate
parsers, scanners and driver routines either in C or, optionally, using classes
in C++.  It has been compiled using the following compilers and platforms:

    Borland C++  4.1                MS-DOS
    Microsoft C 6.0                 MS-DOS, OS/2
    Microsoft Visual C++ 5.0        WIN 95/NT
    Standard C compiler             Unix SVR4 for Intel
    GNU C, g++                      Unix SVR4 for Intel
    GNU C, g++                      SUN's Solaris 2 and SunOS
    GNU C, g++                      Linux 1.03
    Standard C compiler             NextStep 3.2 on a NeXT machine
                                    (-DNEXTSTEP option)
    Standard C compiler             AIX on a IBM RISC/6000 320
    Standard C compiler             HP-UX on a HP9000 (-AA compiler option)

Full source is supplied, and it is hoped that this will be trivially portable
to other C compilers presently available.


FileList
==========================================================================

The following files are provided in the C/C++ distribution:

  readme.1st	       Gives instructions to build the distribution
  read.me              This file
  history              Summary of bug fixes and modifications
  dos2unix.sh          Shell script to convert TEXT files from DOS to UNIX
  dos2unix.uue	       UUENCODE version of dos2unix.sh
  borlandc.mk          Makefile to build the distribution with Borland C++
  unix.mk              Makefile to build the distribution in unix

Subdirectory "docs"    Documentation

  coco.use             Notes on the use of Coco/R
  coco2msg.use         Notes on the use of Coco to Msg translator
                       for Borland C++ 3.1
  cocol                The compiler description language
  cocor.1              nroff manual page for UNIX (source)

Subdirectory "frames"  Specimen frame files for C generation

  scan_h.frm
  scan_c.frm           Frames from which the scanner is generated
  parser_h.frm
  parser_c.frm         Frames from which the parser is generated
  compiler.frm         Frame from which a driver compiler may be generated

Subdirectory "frames/cplus2"  Specimen frame files for C++ generation

  scan_h.frm
  scan_c.frm           Frames from which the scanner is generated
  parser_h.frm
  parser_c.frm         Frames from which the parser is generated
  compiler.frm         Frame from which a driver compiler may be generated

Subdirectory "cplus2"

  cr_abs.hpp
  cr_abs.cpp           Abstract base classes for C++ version
  cr_scan.cpp
  cr_scan.hpp          Base classes for C++ scanners
  cr_error.hpp
  cr_error.cpp         Base classes for C++ error reporters
  cr_parse.hpp
  cr_parse.cpp         Base classes for C++ parsers

Subdirectory "sources" and its sub-directories - Sources for Coco/R

  *.mk                 Makefiles for MAKE (Unix, Borland C, etc)
  cr.c                 Main program (generated by Coco/R from CR.FRM)
  cr.atg               Fully attributed grammar of Coco/R
  crs.c + .h           Scanner (generated by Coco/R from CR.ATG)
  crp.c + .h           Parser (generated by Coco/R from CR.ATG)
  crt.c + .h           Symbol table, top-down graph, grammar tests.
  cra.c + .h           Generation of the scanner.
  crx.c + .h           Generation of the parser.
  crc.h                Module giving symbolic names for scanner/parser
  cre.h                Module giving error messages for scanner
  collect.c + .h       Collection implementation (Dynamic Vectors)
  set.c + .h           Set implementation (Bit Vector)
  cr.frm               Frame from which cr.c may be regenerated ($C pragma)

Subdirectory "sample"  Further sample grammars for Coco/R

--- These are not necessarily suitable for immediate use.  They may need
    massaging and adaptation before sensible parsers can be constructed

  adacs.atg            Subset Ada grammar based on Fischer and LeBlanc
  calc.atg             Simple calculator grammar based on Dobler
  clang1.atg           Clang level 1 grammar based on Terry
  clang2.atg           Clang prettyprinter based on Terry
  expr.atg             Simple expression grammar
  microada.atg         Subset Ada grammar based on Dobler
  mod2.atg             Modula-2 grammar based on Dobler's
  pimmod2.atg          Modula-2 grammar based on PIM
  c.atg                Grammar for a subset of C
  oberon.atg           Grammar for Oberon
  pascal.atg           Jensen and Wirth Pascal grammar
  umbrielx.atg         Grammars for Umbriel

Subdirectory "taste"   Taste compiler (simple stack machine code for simple
                       Pascal-like subset language)

  taste.atg            Taste Compiler grammar
  taste.frm            Taste Compiler frame file
  xref.atg             Taste Cross Reference generator grammar
  xref.frm             Taste Cross Reference generator frame file
  pretty.atg           Taste Pretty Printer grammar
  pretty.frm           Taste Pretty Printer frame file
  *.c, *.h             Auxiliary C modules

Subdirectory "taste_cp"   Taste compiler (C++ version)

  taste.atg            Taste Compiler grammar
  taste.frm            Taste Compiler frame file
  xref.atg             Taste Cross Reference generator grammar
  xref.frm             Taste Cross Reference generator frame file
  pretty.atg           Taste Pretty Printer grammar
  pretty.frm           Taste Pretty Printer frame file
  *.cpp, *.hpp         Auxiliary C++ classes


Credits
============================================================================

Coco/R was originally written in Oberon-2 by Hanspeter Moessenboeck at ETH
Zurich, Switzerland.  It was ported to Modula-2 by Marc Brandis (ETH Zurich)
and Pat Terry (Rhodes University, Grahamstown, South Africa).

The C version was developed by Frankie Arzu (Universidad del Valle, Guatemala,
Central America).

Further advice on portability is available from:

      Frankie Arzu
      e-mail: farzu@uvg.edu.gt or farzu@damanconsulting.com

Users who implement Coco/R under other compilers are encouraged to share their
experience and to make their modifications available in later releases of the
system.


Where to get other versions
===========================================================================

Latest versions of the Coco/R packages should be available via ftp from the
following servers:

Europe:     ftp.ssw.uni-linz.ac.at:/pub/Coco
            Oberon, Java
            Modula for DOS, Unix, Macintosh,
            Turbo Pascal,
            C/C++ for DOS, UNIX, OS/2

USA:        ftp.psg.com:/pub/modula-2/coco
            Modula for DOS, Unix
            Turbo Pascal,
            C/C++ for DOS, UNIX, OS/2
            Java

Central 
America:    uvg.edu.gt:/pub/coco
            C for DOS, UNIX, OS/2

Australia:  pluto.fit.qut.edu.au:/pub/coco
            Modula for DOS, Unix   

South 
Africa:     cs.ru.ac.za:/pub/coco
            Modula for DOS, Unix
            Turbo Pascal,
            C/C++ for DOS, UNIX, OS/2
            Java

References
===========================================================================

For further information on the use and implementation of Coco refer to

  Moessenboeck, H. : A Generator for Fast Compiler Front-Ends.
  Report 127, Dept. Informatik, ETH Zurich (1990)

  Moessenboeck, H. : A generator for production quality compilers.
  Proc 3rd Int'l Workshop on Compiler-Compilers, Schwerin FRG, 1990

Related insight may be gained from

  Rechenberg, P and Moessenboeck, H. : A compiler generator for
  microcomputers (Prentice-Hall, 1989)

which describes Alex and Coco, predecessors of Coco/R, and from

  Dobler, H. and Pirklbauer, P.  : Coco-2, a new Compiler Compiler
  (ACM SIGPLAN Notices, 25(5), 82-90, May 1990

  Dobler, H. : Top-down Parsing in Coco-2
  (ACM SIGPLAN Notices, 26(3), 79-87, March 1991.

which describe Coco-2, another derivative of the original Coco.

Copyrights and Trade Marks
===========================================================================

 Borland C++, Turbo C++, TurboPascal and Delphi are trademarks of Borland
 International Corporation.

 Visual C++ is a trademarks of Microsoft Corporation.

 GNU C Compiler is a trademark of the Free Software Foundation.

 IBM and IBM PC are trademarks of International Business Machines Corporation.

 Intel is a registered trademark of Intel Corporation.

 Microsoft, MS and MS-DOS are registered trademarks, and Windows is a
 trademark of Microsoft Corporation.

 Stony Brook Software and QuickMod are trademarks of Gogesch Micro Systems,
 Inc.

 UNIX is a registered trademark of AT&T Bell Laboratories.

 Solaris is a trademark of Sun Microsystems.

 Any other trademarks are also duly acknowledged.

=end=