LRG.TXT  -- table generator for lr grammars
	
    Copyright (c) 1995
    Norman D. Culver dba
    Oxbow Software
    1323 S.E. 17th Street #662
    Ft. Lauderdale, FL 33316
    (305) 527-1663 Voice
    (305) 760-7584 Fax
    (305) 760-4679 Data
    norman.culver@channel1.com
    ndc@gcomm.com
    All rights reserved.

    LRG processes a grammar file and produces tables which are used by
    a parser engine embedded in the Oxbow Framework. The parser uses the
    tables to process input text and create an Abstract Syntax Tree which
    describes the input in a way that is suitable for further processing
    by a compiler or similar program. LRG itself is stored in the file
    oxlib.cff and can be run using the cfrun command.

    The grammar file contains both a Phrase Structure Grammar and a Lexical
    grammar. LRG builds tables for both and the builtin Parser engine
    dynamically loads the proper tables when instantiated.

    The EBNF grammar and Parser were inspired by `LALR' a compiler
    construction tool developed by Paul Mann. LRG is not `LALR' and was
    developed independently by Norman D. Culver.


SPECIFICATION OF A LANGUAGE WITH THE EBNF GRAMMAR OF LRG

    First, look at the c.grm file and notice the general layout and
    syntax. The object of grammar specification is to achieve 0 reduce/reduce
    errors and not too many shift/reduce errors. Be sure to check your
    spelling and terminate each production with a semicolon `;'. LRG
    will derive terminal symbols for literals (characters enclosed in
    apostrophes) and any identifiers which appear on the left hand side
    of productions and not on the right hand side.
    
    If you have shift/reduce errors the grammar may not work but you won't
    know that until you test it. Use the program `genast' to test.
    e.g.
    	cfrun genast c <testprg.c >testprg.ast

    LRG puts information about each run in a file with the suffix `.out'
    and will optionally generate a `.sta' file containing a full specification
    of the logical tables. Have fun.


COMMAND LINE OPERATION

Usage: cfrun lrg [-advgrDRSLTP] filename
  Switch
   a  - Print abstract syntax tree of grammar (to file .ast)
   d  - Add debugging info to .out file.
   v  - Verbose diagnostics to .out file.
   g  - Generate parser tables.
   r  - Print rewritten AST (used with 'a').
   Dn - Enable input parser/lexer debug (to stdout).
   R  - Regenerate source from ast (to file .grr).
   S  - Print parser states (to file .sta).
   L  - Print lexer states (to file .sta).
   T  - Generate human readable/compilable tables (requires g).
   E  - Use expanded parser states (for debugging).


HOW TO RUN LRG

   cfrun lrg c.grm -gvSL   // verbosely generate the c.lod file for c.grm
                           // and also save the state info in c.sta
   cfar -FCr ../oxlib.cff/language c.lod  // save the c.lod file

   or

   cfrun lrg xxx.grm -gTSL  // generate the xxx.tab file for xxx.grm
                            // .tab files are C format and can be included
                            // in C programs


HOW TO RUN THE PARSER FROM A FRAMEWORK PROGRAM
    {
    #include <oxbow.h>
    ASTVARS(64);              // see oxbow.h
    AstP curnode;             // see oxbow.h
    extern object Parser;
    FILE *if;
    void *instance;
    PG *pg;   // parser instance variable struct, see oxbow.h
    int errs;

      /* GET AN INSTANCE OF THE PARSER  */
      if(!(instance = gNew(Parser, "c"))) // `c' language tables are loaded
         abort();
      pg = (PG*)GetIVptr(instance, Parser); // get pointer to instance variables

      /* PARSE A FILE -- you might call a pre-processor before this step */
      if = cffopen(myprg.c, "r");          // `if' can be an object
      errs = gParse(instance, if, stderr); // input from `if', errors to stderr
      cffclose(if);                        // stderr can be an object

      /* PROCESS THE RESULTS OF THE PARSE */
      if(errs == 0)
      {
         curnode = pg->root; // the AST is located at pg->root
         MARKAST;
         while(DOWNAST)
         {
           ...
         }
         PrintAst(pg, stdout, 1);  // print the AST with node numbers
      }
      gDispose(instance);  // Parser tables and AST are deallocated
    }