home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / oxcc1433.zip / DOC / LRG.TXT < prev    next >
Text File  |  1995-11-05  |  4KB  |  116 lines
  1. LRG.TXT  -- table generator for lr grammars
  2.     
  3.     Copyright (c) 1995
  4.     Norman D. Culver dba
  5.     Oxbow Software
  6.     1323 S.E. 17th Street #662
  7.     Ft. Lauderdale, FL 33316
  8.     (305) 527-1663 Voice
  9.     (305) 760-7584 Fax
  10.     (305) 760-4679 Data
  11.     norman.culver@channel1.com
  12.     ndc@gcomm.com
  13.     All rights reserved.
  14.  
  15.     LRG processes a grammar file and produces tables which are used by
  16.     a parser engine embedded in the Oxbow Framework. The parser uses the
  17.     tables to process input text and create an Abstract Syntax Tree which
  18.     describes the input in a way that is suitable for further processing
  19.     by a compiler or similar program. LRG itself is stored in the file
  20.     oxlib.cff and can be run using the cfrun command.
  21.  
  22.     The grammar file contains both a Phrase Structure Grammar and a Lexical
  23.     grammar. LRG builds tables for both and the builtin Parser engine
  24.     dynamically loads the proper tables when instantiated.
  25.  
  26.     The EBNF grammar and Parser were inspired by `LALR' a compiler
  27.     construction tool developed by Paul Mann. LRG is not `LALR' and was
  28.     developed independently by Norman D. Culver.
  29.  
  30.  
  31. SPECIFICATION OF A LANGUAGE WITH THE EBNF GRAMMAR OF LRG
  32.  
  33.     First, look at the c.grm file and notice the general layout and
  34.     syntax. The object of grammar specification is to achieve 0 reduce/reduce
  35.     errors and not too many shift/reduce errors. Be sure to check your
  36.     spelling and terminate each production with a semicolon `;'. LRG
  37.     will derive terminal symbols for literals (characters enclosed in
  38.     apostrophes) and any identifiers which appear on the left hand side
  39.     of productions and not on the right hand side.
  40.     
  41.     If you have shift/reduce errors the grammar may not work but you won't
  42.     know that until you test it. Use the program `genast' to test.
  43.     e.g.
  44.         cfrun genast c <testprg.c >testprg.ast
  45.  
  46.     LRG puts information about each run in a file with the suffix `.out'
  47.     and will optionally generate a `.sta' file containing a full specification
  48.     of the logical tables. Have fun.
  49.  
  50.  
  51. COMMAND LINE OPERATION
  52.  
  53. Usage: cfrun lrg [-advgrDRSLTP] filename
  54.   Switch
  55.    a  - Print abstract syntax tree of grammar (to file .ast)
  56.    d  - Add debugging info to .out file.
  57.    v  - Verbose diagnostics to .out file.
  58.    g  - Generate parser tables.
  59.    r  - Print rewritten AST (used with 'a').
  60.    Dn - Enable input parser/lexer debug (to stdout).
  61.    R  - Regenerate source from ast (to file .grr).
  62.    S  - Print parser states (to file .sta).
  63.    L  - Print lexer states (to file .sta).
  64.    T  - Generate human readable/compilable tables (requires g).
  65.    E  - Use expanded parser states (for debugging).
  66.  
  67.  
  68. HOW TO RUN LRG
  69.  
  70.    cfrun lrg c.grm -gvSL   // verbosely generate the c.lod file for c.grm
  71.                            // and also save the state info in c.sta
  72.    cfar -FCr ../oxlib.cff/language c.lod  // save the c.lod file
  73.  
  74.    or
  75.  
  76.    cfrun lrg xxx.grm -gTSL  // generate the xxx.tab file for xxx.grm
  77.                             // .tab files are C format and can be included
  78.                             // in C programs
  79.  
  80.  
  81. HOW TO RUN THE PARSER FROM A FRAMEWORK PROGRAM
  82.     {
  83.     #include <oxbow.h>
  84.     ASTVARS(64);              // see oxbow.h
  85.     AstP curnode;             // see oxbow.h
  86.     extern object Parser;
  87.     FILE *if;
  88.     void *instance;
  89.     PG *pg;   // parser instance variable struct, see oxbow.h
  90.     int errs;
  91.  
  92.       /* GET AN INSTANCE OF THE PARSER  */
  93.       if(!(instance = gNew(Parser, "c"))) // `c' language tables are loaded
  94.          abort();
  95.       pg = (PG*)GetIVptr(instance, Parser); // get pointer to instance variables
  96.  
  97.       /* PARSE A FILE -- you might call a pre-processor before this step */
  98.       if = cffopen(myprg.c, "r");          // `if' can be an object
  99.       errs = gParse(instance, if, stderr); // input from `if', errors to stderr
  100.       cffclose(if);                        // stderr can be an object
  101.  
  102.       /* PROCESS THE RESULTS OF THE PARSE */
  103.       if(errs == 0)
  104.       {
  105.          curnode = pg->root; // the AST is located at pg->root
  106.          MARKAST;
  107.          while(DOWNAST)
  108.          {
  109.            ...
  110.          }
  111.          PrintAst(pg, stdout, 1);  // print the AST with node numbers
  112.       }
  113.       gDispose(instance);  // Parser tables and AST are deallocated
  114.     }
  115.  
  116.