coco.use

一个Modula-2语言分析器

Quick start notes on the use of Coco/R (Modula-2 version)
=========================================================

                  Pat Terry, updated Thursday  05-14-98
                          [e-mail]

These notes apply directly to the WinTel or MS-Dos versions of Coco/R
(Modula), and also apply very closely to the various Unix versions of Coco/R.

We know that you can't wait to begin!

Installation
============

Please read the file README.1ST for details of how to install the system.

Getting going
=============

Examples of input for Coco/R can be found in the case study source files on
this diskette.  It is suggested that you experiment with these before
developing your own applications (see further details below).

For each application, the user has to prepare a text file to contain the
attributed grammar.  Points to be aware of are that

 - it is sensible to work within a "project directory" (say C:\WORK) and not
   within the "system directory" (C:\COCO);

 - text file preparation must be done with an ASCII editor, and not with a
   word processor;

 - by convention the file is named with a primary name that is based on the
   grammar's goal symbol, and with an "ATG" extension, for example CALC.ATG.

Running Coco/R
==============

When you first start it, Coco/R will respond with something like

       Coco/R (WinTel) - Compiler-Compiler V1.xx
       Released by Pat Terry ReleaseDate

and prompt you for the name of an input file.  Alternatively, the input file
name can be entered on the command line.  If no extension is given, the default
extension ".ATG" is assumed.

          COCOR   TEST.ATG

A second parameter can be supplied to set compiler options, for example:

          COCOR   TEST.ATG   /MCS

or, if you prefer the Unix form

          COCOR   -MCS  TESTATG

For those who need reminding, the command

          COCOR /?  (DOS)  or  COCOR --h  (Unix)

will print a help screen something like the following, and then abort.

     Coco/R (WinTel) - Compiler-Compiler V1.xx
     Released by Pat Terry ReleaseDate
     Usage: COCOR [-Options] [Grammar[.atg]] [-Options]
     Example: COCOR -mcs Test

     Options are
     a  - Trace automaton
     c  - Generate compiler module
     d  - Suppress generation of Definition Modules
     f  - Give Start and Follower sets
     g  - Print top-down graph
     i  - Trace start set computations
     l  - Force listing
     m  - (Multipass) Suppress FORWARD declarations
     n  - Generate symbolic names
     p  - Generate parser only
     s  - Print symbol table
     t  - Grammar tests only - no code generated
     x  - Print cross reference list
     COMPILER.FRM, SCANNER.FRM and PARSER.FRM must be in the working directory,
     or on the path specified by the environment variable CRFRAMES

Input to Coco/R
===============

Thus, Coco/R takes three (or four) files as input, and produces six (or nine)
files as output.  These output files can then be combined with a main program
and any other auxiliary files needed, so as to produce a complete compiler.

The input files needed are

   grammar.ATG  -  an attributed grammar  ("grammar" is used here for
                   illustration, the file does not have to have that name)
   PARSER.FRM   -  the frame file for the parser generation
   SCANNER.FRM  -  the frame file for the scanner generation

optionally

   grammar.FRM  -  an application specific frame file for complete compiler
                   generation

Frame Files
===========

Coco/R, like several other parser generators, achieves its results by parsing
an attributed grammar, and then merging code (based on that grammar) into
so-called "frame files" that provide skeletons for each of the main components
of the required compiler - the scanner definition/implementation (or ".h" and
".c" files in C++ terminology), the parser definition/implementation, and the
main driver implementation.

A "generic" version of this last frame file is supplied in the distribution as

   COMPILER.FRM  -  the generic frame file for the compiler generation

and this is intended to act as a model for your own applications, a process
that will be helped by studying various application specific frame files
supplied in the sources on this diskette.  The other frame files are
effectively standardized and should require little if any alteration; they are
fairly resilient, and any particular configuring for specific applications
will require some experience of the internal workings of Coco/R itself.

There are two supplied scanner frame files.  The generated scanners try to
achieve efficiency by reading the entire source program into memory, rather
than making calls to a low level routine every time a character is needed. The
frame file named SCANNER.FRM handles large source programs, by constructing a
chained list of blocks of source, allocated from the heap by Storage.ALLOCATE.
The one named SCANNER2.FRM handles source programs small enough to be read
into a single block (on an MS-DOS system the limitation is just less than
64Kb). SCANNER2.FRM produces even more efficient scanners, of course.  To use
SCANNER2.FRM, it should, of course be renamed SCANNER.FRM.

When using Coco/R, the frame files SCANNER.FRM and PARSER.FRM are first
searched for in the directory of the input file and then, if they are not
found, in the directories specified in the environment variable CRFRAMES.  To
set this variable, use the DOS SET command, for example

            SET CRFRAMES=C:\COCO\FRAMES
or
            SET CRFRAMES=C:\COCO\ISOFRAME

(for the difference, see further discussion below)

or the equivalent in Unix, for example

            CRFRAMES=coco/frames
            export CRFRAMES

You may like to add this to your AUTOEXEC.BAT or .profile file, so that it
takes effect every time you start your computer.

The frame file for the compiler itself is named as grammar.FRM, where grammar
is the grammar name.  This is searched for in the directory of the input file.
If it is not found, a search is made for the generic COMPILER.FRM in this
directory; failing that, COMPILER.FRM is searched for in the directories
specified in the environment variable CRFRAMES.  The basic compiler frame file
(COMPILER.FRM) that comes with the kit will allow simple applications to be
generated immediately, but it is sensible to copy this basic file to the
project directory, and then to rename and edit it to suit the application.
This subject is treated in more detail in the author's textbook:

  Terry, P.D. : Compilers and Compiler Generators - an introduction with C++
  (ITCP, London, 1997)

which, despite its title, has material pertinent to all versions of Coco/R.

Output from Coco/R
==================

The generated files are placed in the same directory as the grammar file.

Coco/R for Modula generates the files

  grammarS.DEF+MOD     generated FSA scanner
  grammarP.DEF+MOD     generated recursive descent parser
  grammar.ERR          error numbers and corresponding message texts
  grammar.LST          compilation history

and, optionally, the files

  grammarG.DEF+MOD     generated module exporting symbolic names that
                       will be used if the $N pragma or /N option was in
                       effect.
  grammar.MOD          generated main module for the complete compiler

where grammar is the name of the attributed grammar (this grammar is sensibly
stored in the file grammar.ATG).

The input/output and miscellaneous module FileIO
================================================

Although I/O has now effectively been standardized for ISO Modula-2, such
libraries are not available on many early compilers.  The system supplied here
attempts to get around this by providing (yet another!) I/O module, called
FileIO, with a definition module that should be acceptable to any compiler,
and with implementations for various compilers that differ subtly in various
places.  This module is of fairly widespread applicability beyond the confines
of Coco/R; note, however, that in one mode of working, the modules generated
by Coco/R will assume that the module will be present.

However, there is no longer a need for developers using Coco/R to rely on
FileIO as the way to handle I/O in the applications that they derive - if the
ISO libraries provide all the functionality required, then by all means they
might advantageously be used.  To this end, Coco/R has been modified as from
version 1.43 to add nothing to the frame files that would be is dependent on
FileIO itself.  This means that a user can either

(a) make use of the traditional frame files (or rather, subtly updated
    versions of these as from version 1.43) that result in scanners and
    parsers being generated that perform I/O entirely through the FileIO
    interface; or

(b) make use of newly supplied frame files that will result in scanners and
    parsers being generated that perform I/O through the ISO interfaces; or

(c) if really adventurous, produce a completely new set of frame files that
    use some completely different I/O library (to do this, one would, of
    course, have to study the internal workings of Coco/R rather more deeply,
    but would probably derive frame files rather similar to the ones we have
    supplied in any case).

We should remark that the frame files are, in any event, non-sacrosanct.
Those provided in the distribution for the scanner and parser components are,
in fact, amazingly resilient.  That provided for the main driver routine
usually has to be tweaked a little, depending on the application; as we have
observed, various examples of how this is done are also provided in the case
studies.

Choosing to generate systems for use with FileIO or with the ISO library
========================================================================

This is easily achieved by defining the CRFRAMES environment variable to point
to the directory in which the required frame files reside.  The "traditional"
frame files are supplied in the kit in a subdirectory FRAMES; the new
ISO-based ones are in the subdirectory ISOFRAME.

Of course, the way in which the attribute grammar is written will also depend