coco.use

一个Pascal语言分析器

Quick start notes on the use of Coco/R (Turbo Pascal version)
=============================================================

                  Pat Terry, updated Tuesday  04-28-98
                          [e-mail]

These notes apply directly to the MS-Dos versions of Coco/R (Pascal).

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.

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
==============

To start Coco/R, type COCOR, adding the name of the file that contains your
attribute grammar:

          COCOR   TEST.ATG

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

          COCOR   TEST.ATG   /CL

or, if you prefer the Unix form

          COCOR   -CL  TEST.ATG

For those who need reminding, the command

          COCOR /?

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

     Coco/R (MS-DOS) - Compiler-Compiler V1.xx (Pascal)
     Turbo Pascal (TM) version by Pat Terry/Volker Pohlers ReleaseDate
     Usage: COCOR [-Options] [Grammar[.atg]] [-Options]
     Example: COCOR -cs Test

     Options are
     a  - Trace automaton
     c  - Generate compiler module
     f  - Give Start and Follower sets
     g  - Print top-down graph
     i  - Trace start set computations
     l  - Force listing
     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
===============

Coco/R takes three (or four) files as input, and produces four (or six) 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 used here for illustration)
   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

A "generic" version of this last frame file is given 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.

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

You may like to add this line to your AUTOEXEC.BAT 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.

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

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

Coco/R for Pascal generates the files

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

and, optionally, the files

  grammarG.PAS         generated module exporting symbolic names that
                       will be used if the $N pragma or /N option was in
                       effect.
  grammar.PAS          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 system should produce code acceptable to Turbo Pascal - hopefully any
version from 4 onwards (it has only been tested on version 6).

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

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 two simple
applications - one is a crossreference generator for EBNF productions, and the
other is the "Taste" toy compiler described in Moessenboeck's report 127 from
ETH (1990), modified minimally to convert it from Oberon to Modula-2.

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

Once the components of the application have been generated, they are ready to
be compiled by your Turbo Pascal compiler.  It is assumed that you are
familiar with the process of compiling such programs.

For a very simple MS-DOS application one might be able to use a command like

          TPC /M 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 ACFGLNPSTX in either upper
or lower case.

The C L N P and T options are generally useful

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.

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

N  - Generate symbolic names, and the module grammarG.PAS.
     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

S  - Print symbol table

X  - Print cross reference list