coco.use

一个Modula-2语言分析器

on the choice of libraries, if the actions associated with productions are
required to perform I/O, as might happen in many applications.

The FileIO library - overview
=============================

******************  IMPORTANT NOTE ******************************************

If you do not have an ISO compliant Modula-2 compiler, or if you wish to make
use of FileIO for maximum ease of porting your applications between other
compilers, you will need to copy the files from the directory
SOURCES\CompilerName to your working directory before you can make full use of
Coco.  Please be careful - look at the sources first, and make sure that you
do not overwrite valuable files.

*****************************************************************************

FileIO provides the usual services for opening and closing text files, and for
reading and writing strings, words, whole numbers and line marks to such
files.  It can also handle binary files, as block read and write operations
are provided.  In addition there are some utility procedures, for obtaining
command line parameters and environment strings, and for the output of dates
and times.  It also has some string handling procedures, so as to overcome the
fact that the Strings libraries in pre-ISO compilers also tended to differ
from one commercial system to another.  Finally, it exports various constants
and types.  These latter may need slight adjustment between compilers.

The module is really rather too large, but has been kept this way to minimize
the number of non-portable sections and modules in the kit.  It is hoped that
porting Coco/R to another compiler will require only that the implementation
of FileIO.mod needs to be reworked, with possibly the definitions of a few
constants in FileIO.def altered as well.  Not all of the routines in FileIO
are used by Coco/R itself (although most are).

******************  IMPORTANT NOTE ******************************************

You may wish to extend or modify FileIO to suit your own applications.
Provided that the types, constants and procedures currently exported are left
that way, this should cause no problems.

*****************************************************************************

The implementation of FileIO for the JPI compiler is, in many respects, an
interface onto the JPI FIO module.  Similarly, the implementations for the
LOG, FST and STO system are, in many respects, interfaces onto the highly
compatible FileSystem module provided for each of those systems.  The
implementations for Mocka make use of an interface module to the C library.
The implementation for the Apple Macintosh p1 compiler, and for the later
Gardens Point, XDS and StonyBrook compilers is intended to be ISO compliant.
An alternative implementation for GPM Modula-2 is provided that interfaces
onto the various traditional file handling libraries available with GPM.
Users who wish to improve on the performance of Coco/R, and who have access to
the source code of the libraries for their particular compiler might find the
modification of FileIO (so as to remove a potentially unnecessary layering of
procedure calls) a useful and rewarding exercise.  However, licensing
arrangements for these systems do not permit us to distribute the source code
of modules like FileSystem and FIO.

It should be noted that FileIO attempts to improve performance by taking
advantage of such buffering as the underlying implementations allow.  On
several implementations, FileIO also provides for automatic closing of all
still open files if a client program terminates without explicitly closing all
files.  To achieve this in a simple way, FileIO does not allow more than 16
files (besides the standard ones) to be open at any one time.

The FileIO library has chosen to export 4 standard files, namely

     con    -    assumed to be a non-redirectable "raw" keyboard/screen (like
                 /dev/tty in Unix terms)
     StdIn  -    redirectable standard input
     StdOut -    redirectable standard output
     err    -    non-redirectable standard error

The con stream is really meant for prompts and responses, and input is not
meant to be line buffered.  On several implementations, if StdIn has not been
redirected, input from StdIn becomes synonymous with input from con, and
similarly unredirected output to StdOut becomes synonymous with output to con.

Unfortunately, the various implementations differ in awkward ways.  On GPM-PC,
for example, the implementation of con is such that if standard input is
redirected, input from con will not behave properly.  It is hoped that this
may be corrected in a later release.

Simple case studies
===================

Examples of input for Coco/R can be found in the various subdirectories in
this kit.  It is suggested that you experiment with these before developing
your own applications.  Besides the grammar for Coco/R itself (which we
recommend that you do not experiment with initially), there are some other
applications - one is a cross-reference generator for EBNF productions,
another is the "Taste" toy compiler described in Moessenboeck's report 127
from ETH (1990), modified minimally to convert it from Oberon to Modula-2, and
there is also a Modula-2 pretty printer.  Further case studies can be found in
the author's textbook, cited earlier, the code for which can be downloaded
from

      ftp://cs.ru.ac.za/pub/languages/textbook

Supported target systems
========================

The system should produce code acceptable to any of the following MS-DOS
pre-ISO Modula-2 compilers:

  JPI    TopSpeed Modula-2   versions 1.17, 2.06 and 3.1
         TopSpeed is a trademark of Jensen and Partners, International

  FST    Fitted System Tools versions 2.0 through 4.0 (shareware system)

  LOG    Logitech version 3.03

  STO    Stony Brook QuickMod 2.2 (and, presumably the Stony Brook optimizing
         compiler).  (Stony Brook and QuickMod are trademarks of Gogesch Micro
         Systems)

  GPMPC  GPM-PC Gardens Point Modula-2 for MS-DOS

Extra GPM-PC documentation is supplied, based on that supplied by John Gough,
and is available in the file README.GPM.  Note that GPM-PC is not able to
bootstrap Coco/R itself, due to memory limitations, but it can handle small
parsers constructed by Coco/R.

The system should also produce acceptable to any of the following ISO
compliant Modula-2 compilers:

  ISOGPM Gardens Point Modula-2 for Unix machines

  ISOXDS xTech's XDS Modula-2/Oberon compilers for Wintel machines

  ISOMPW the p1/MPW compiler for the Macintosh

  ISOSTO StonyBrook V3 and V4 compilers for Wintel machines

However, take note of the section on compiler directives below, and in
particular the use of the $M directive or /M command line option.

Compiling the generated compiler
================================

Once the components of the application have been generated, they are ready to
be compiled by your Modula-2 compiler.  It is assumed that you are familiar
with the process of compiling such programs.  Notice, however, that you must
have installed the FileIO library before you can make use of Coco/R if you do
not have an ISO compliant compiler.

For a very simple MS-DOS application using the TopSpeed system, one might
be able to use commands like

          M2 /C CALC /MB+
          M2 /L CALC

Coco/R options and pragmas
==========================

As implied above, various didactic output and useful variations may be invoked
by the use of compiler pragmas in the input grammar, or by the use of a
command line option.  Compiler pragmas take the form

       $String

and the optional command line parameter takes the form

       /String   or    -String

where String contains one or more of the letters ACDFGLMNPSTX in either upper
or lower case.

The C D L M N P and T options are generally useful, M in particular

C  - (Compiler) Generate complete compiler driving module, including source
     listing featuring interleaved error message reporting.  To use this
     option the file COMPILER.FRM (or grammar.FRM) must be available.

D  - Definition Modules are not written if this option is invoked.  Since
     these normally need be generated only once, and then become a nuisance if
     they are regenerated (as all clients have to be recompiled), this option
     is particularly useful when fine tuning of the attribute grammar is
     performed, but must obviously be used with care.

L  - (Listing) Force listing.
     Normally the listing of the grammar is suppressed if the compilation
     is error free.

M  - (Multipass) Suppress generation of FORWARD declarations.
     The TopSpeed (one-pass) compilers require FORWARD generations to be
     added to the generated parser.  Two-pass compilers (like those from FST,
     Logitech and Stony Brook) usually reject such declarations.  When using
     Coco/R with these compilers the M option should always be exercised.
     (alternatively modify and recompile the sources of Coco)).

N  - Generate symbolic names, and the modules grammarG.DEF and grammarG.MOD.
     Normally the generated scanner and parser use numbers for the symbol
     classes, but they can optionally use names (like BEGINSym, periodSym)
     instead.

P  - (Parser only)  Suppress generation of the scanner.
     Regeneration of the scanner is often tedious, and results in no changes
     from the one first generated.  This option must be used with care.  It
     can also be used if a hand-crafted scanner is to be supplied (see the
     notes on the use of hand-crafted scanners in the file COCOL).

T  - (Tests) Suppress generation of scanner and parser.
     If this option is exercised, the generation of the scanner and parser
     is suppressed, but the attributed grammar is parsed and checked for
     grammatical inconsistencies, LL(1) violations and so on.

The following options are really intended to help with debugging/teaching
applications.  Their effect may best be seen by judicious experimentation.

A  - Trace automaton

F  - Give First and Follow sets for each non-terminal in the grammar

G  - Print top-down graph

I  - Trace start set computations (very verbose)

S  - Print symbol table

X  - Print cross reference list

Grammar checks
==============

Coco/R performs several tests to check if the grammar is well-formed.  If one 
of the following error messages is produced, no compiler parts are generated.

   NO PRODUCTION FOR X
     The nonterminal X has been used, but there is no production for it.

   X CANNOT BE REACHED
     There is a production for nonterminal X, but X cannot be derived from the
     start symbol.

   X CANNOT BE DERIVED TO TERMINALS
     For example, if there is a production X = "(" X ")" .

   X - Y, Y - X
     X and Y are nonterminals with circular derivations.