README file from ~ftp/pub/mag on watmsg.waterloo.edu

This stuff is a mess.  If anybody writes some documentation and/or
a shell script to do something useful, please let me know
(gvcormack@waterloo.edu).

In this directory are various programs that make up a Modular Attribute
Grammar generator and evaluator as described in

  "Modular Attribute Grammars", by Gery Dueck and Gordon Cormack, 
     to appear in Computer Journal (hopefully April 90).  

  (its also a University of Waterloo Research Report # ???)
  (the source for the paper is in mag.t - eqn, tbl, -ms, troff)

Nothing is automated at the moment; here are the basic parts.

  slr - a program to read a grammar and produce parse tables, as
        described in "slr.doc".  written in vax-dependent modula 2.
        there are other parser generators that are input/output
        compatible with this one, and could be substituted.  Nigel
        Horspool has a C LR and incremental LR version; Dan Salomon
        at Manitoba has a noncanonical one with powerful extensions that
        allow scannerless parsing.  Norbert Kusters (waterloo) wrote
        a C++ version that has error recovery "An LR substring parser
        for noncorrecting error recovery", by Cormack, Sigplan Notices
        July 89.

  pattr - takes a set of patterns and generates tables for attribute
          grammar evaluator.  these patterns are described in general
          in "Modular attribute grammars", and more specifically
          below.

      usage: pattr [-adelprtvx]* [filename]
      	-a: print generated attribute grammar
      	-c: write C source file
      	-d: write attab and symtab to attr.list
      	-e: print messages about undefined or
      	    ambiguous generated synthesized attributes
      	-f: fold trivial attribute assignments
      	-g: provide a listing of the grammar
      	-h: compute hash values on definitions
      	-m: print patterns that match rules
      	-o: optimize procedure generation
      	-O: optimize everything; = -four
      	-p: provide a listing of the patterns
      	-P: print attributes changed in each pass
      	-r: check all attributes reachable from goal
      	-t: trace reachables
      	-u: remove unreachables
      	-U  print unreachable attribute definitions
      	-v: verbose: print all attr defs
      	-w: write tables
      	-x: print cross-reference table
      
      produces: attr.slr - grammar without attributes
                attr.list - if -d specified
                attr.tbl - attribute tables

  format - takes the output from slr and pattr and generates a c
           include file


      Usage: format [-S] [-a] [-p] [filename]
      	-S produce (vax) assembler
      	-a input contains only attr tables
      	-p input contains only parse tables

  parser - a c program that uses the tables to parse and evaluate the
           attribute grammar

"makefile" has a little more documentation, but i'm afraid you will 
have to read the examples and maybe even the code to find out more.
------

How to use Maggie

1.  Prepare a context-free grammar suitable for input to "slr".  This
    is described in the document slr.doc.  Place this in a file called
    xxx.slr   (Have a look at test.slr as an example). 

2.  Run the parser generator.

    slr < xxx.slr

    If there are conflict reports fix the grammar.  Otherwise, the
    tables will be in the file "slr.tbl".

3.  Copy slr.tbl to xxx.ptb  (for the benefit of Maggie)

4.  Prepare a pattern attribute file and name it xxx.pat.  
    (have a look at test.pat as an example).

    Basically, it is a set of patterns.  For each pattern you have
    a header like:

       A B C ... $E ... F

    Here, A,B,C etc. match any grammar symbol; $E matches only the
    grammar symbol E, and ... match 0 or more grammar symbols.  The
    first symbol (A) is the LHS of the rule, and the rest are the RHS.

    Following the header, you have a bunch of C statements, enclosed
    in {}.  In the C statements, you can use attribute names like
    A.fred  or  A3.fred  (which means the 4th occurrence of A in the
    pattern).

5.  If these computations require some global C definitions, place these
    these in the file xxx.h

6.  make f=xxx

7.  ./xxx will run your parser/attribute evaluator.  there is a builtin
    scanner that is really dumb.  it has some hardcoded rules for
    separating lexemes, then looks in your vocabulary to see if they
    match.  If there's no match and the lexeme looks like a name,
    it tries the token <name>.  For strings and integer constants,
    it tries <string> and <integer>.  The first terminal in 
    the rule for the start symbol is generated automatically.  End of
    file generates the token <eof>.  Each terminal symbol is 
    automatically given the attributes "text", "line", and "col, 
    specifying the lexeme's text and position in the source file.
    Try "./test" as an example.

    The generated evaluator has the following flags:

      usage: ./xxx [-abdemprsv] [-t[number]] [filename]
      	 -b trace attribute expression builder
      	 -d dump proc address, code vector, and tptr space
      	 -r print parser reductions
      	 -t[number] start tracing phase number