home *** CD-ROM | disk | FTP | other *** search
- QPARSER help file 'qphelp.hlp'.
- COPYRIGHT (C) 1990, QCAD Systems, Inc. All rights reserved.
-
- This is the help file for Qparser's debugging and other menus.
- This is supposed to reside in a file designated by the environment
- variable QPHELP, or if QPHELP isn't defined, in the local directory as
- file 'qphelp.hlp'.
- It is called out through a 'topic', which appears in here prefixed
- by an @ sign in column one, e.g. '@inspect_sem' below.
- You can add topics, or make use of the 'help.c' ('uhelp.pas') file
- that displays help information on the screen.
-
- @inspect_sem
-
- [inspect_sem] ?(help, N(ame, A(ll names, T(ree, U(p
-
- This lets you inspect one semantics structure (record), for example, any
- semantics structure carried on the stack. You can also examine other
- parser features.
-
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
-
- N(ame -- prompt for a user-level identifier, and describe its properties.
- The name is case-sensitive -- the name 'SAM' is considered different than
- 'sam' or 'Sam'. The name is supposed to match something placed in the
- symbol table, for example by the function 'get_symbol'.
-
- A(ll -- report all the identifiers carried in the symbol table. Reserved
- words (at level -1) are ignored.
-
- T(ree -- report the semantic tree structure rooted in this semantics
- record. For this to work properly, you must have generated the tree with
- the QTREEs option set, and have taken care to follow the tree-building
- conventions if you have generated tree nodes through private code. The
- tree report of a ROOT node and its children looks like this:
-
- ROOT (this is a production tag, or GENL_KIND if the production is untagged)
- +-1 left child (position ONE, CHILD or LEFT)
- |
- |
- +-2 next child (position TWO or RIGHT)
- |
- +-3 next child (position THREE)
-
- Any of the children of ROOT can be tree structures. For example,
-
- ROOT
- +-1 STMTLIST
- +-1 ASSIGN
- | +-1 IDENT
- | +-2 PLUS
- | +-1 FIXED
- | +-2 IDENT
- +-2 GOTO
-
- represents a code fragment that might look like this originally:
-
- k = 16 + l; /* the ASSIGN */
- goto 15; /* the GOTO */
-
- U(p -- return to the previous debug level, if any. After working
- down into a semantics tree structure, you can go back up with 'U'.
- (the ENTER key also returns).
-
- S(ym -- appears when the object is a user identifier. This brings up
- a submenu that reports the identifier's properties, and perhaps
- additional semantics information to explore. See the '?' option
- under this submenu, or topic 'dump_sym'.
-
- The values of literal numbers and strings are reported. Identifiers
- can be explored more deeply through a symbol table inspection prompt.
- In order for this to work well, you need to keep function 'dump_sym'
- and 'dump_sem' in good repair, corresponding to the typedefs 'symtabtype'
- and 'semrectype', respectively. With QTREES, you probably don't need
- to do anything about 'semrectype', but you will almost surely have several
- more identifier types to deal with.
-
- @inspect_stack
-
- 1: 1 Stmts GENL_KIND:
- 2: 18 QUIT NULL
- * 3: 22 <eol> NULL
- [inspect_stack] ?(help, N(ame, A(ll names,
- I(nspect, T(ree, +(tos, -(tos, ENTER?
-
- This permits inspection of the state and semantics stack. These two
- stacks correspond, except when error recovery is in progress.
- The parser stack is shown -- in the example, it contains 3 items.
- TOS is the last item shown -- #3 in the example. A 'referenced' stack
- element is marked with '*'; its position can be moved up and down with
- the '+' and '-' keys.
- From left to right in each stack element:
-
- stack position, counting 1 at the bottom of the stack (ex: 1)
- state number (ex: 1)
- in-symbol corresponding to the state (ex: Stmts)
- semantics type (ex: GENL_KIND)
- (optionally) other semantics information
-
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
-
- N(ame -- prompt for a user-level identifier, and describe its properties.
- The name is case-sensitive -- the name 'SAM' is considered different than
- 'sam' or 'Sam'. The name is supposed to match something placed in the
- symbol table, for example by the function 'get_symbol'.
-
- A(ll names -- report all the identifiers carried in the symbol table.
- Reserved words (at level -1) are ignored.
-
- I(nspect -- inspect the 'referenced' semantics frame (marked with '*').
- This option will appear only if the semantics frame is coordinated with
- the state stack. See the help option or topic 'inspect_sem' for details.
-
- T(ree -- display the semantics tree attached to the 'referenced' semantics
- frame. This option will appear only if the semantics frame is coordinated
- with the state stack. See topic 'inspect_sem' for details about tree
- representation.
-
- +(tos -- move the referenced stack position toward to the stack top.
-
- -(tos -- move the referenced stack position away from the stack top.
-
- ENTER -- return to the calling environment.
-
- @inspect_sym
-
- What symbol (case-sensitive!) ? A
- 0> SYM: A (USER)
- 0> U(p u
-
- This menu invites you to explore the properties of the identifier,
- based on information in its symbol table struct. The default information
- isn't much, but you will want to expand this description as you design
- attribute classes for identifiers.
-
- What symbol (case-sensitive!) ? -- enter a name, usually upper case
- is required.
-
- U(p -- return to calling environment.
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
-
- @set_prodtraps
-
- 1: Expr -> Expr + Term #PLUS
- 2: Expr -> Expr - Term #MINUS
- (etc.)
- 17: Term -> Fact
- 18: Term -> Term * Fact #MPY
- [set_prodtraps] ?(help, C(lear all, S(elect all,
- #( <number>, SPACE, ENTER
-
- This menu invites you to set a parser trap on one or more productions.
-
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
- C(lear all -- clear all the traps.
- S(elect all -- set a trap on every production.
- #( <number> -- set or clear a trap on a production by its
- number in the list. You can enter several numbers, including numbers not
- shown on the screen. The number associated with a production is its
- reduce state, which won't change unless you change the grammar and
- recompile. The same production may appear more than once in the list
- in different reduce states.
- SPACE -- continue the listing of productions, one screen at
- a time. When the end is reached, it will start over from the top.
- ENTER -- return to the calling debug environment.
-
- The productions are ordered by their reduce state number, and the
- same production may appear in the list more than once. A trap may be
- set on a production whether or not it is tagged.
- The trap is sprung in a reduce state in function 'parser', and will
- occur regardless of the setting of the 'debug' level.
- You must have compiled your parser with the '-d' option of LR1P for
- each file containing the 'debugging' flag.
-
- @set_nodetraps
-
- OTHER
- SEMERR
- (etc.)
- REALVAL
- UMINUS
- [set_nodetraps] ?(help, S(elect all, C(lear all,
- #( <tag>, SPACE, ENTER?
-
- This menu sets traps in a tree evaluator or semantics checker AFTER
- an abstract tree has been generated. Recall that under QTREES, an AST
- is built through parsing actions, during which the source is scanned.
-
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
- S(elect all -- set a trap on every node.
- C(lear all -- clear all node traps.
- #( <tag> -- select or unselect this particular tag. The tags
- are associated with productions, which are displayed on the screen.
- You can enter several names on this line, and the names don't have
- to appear on the display. Enter the tags like this:
-
- # ADD SUB ASSIGN (etc.)
-
- SPACE -- show more names and productions, or start over with the list.
- ENTER -- return to the previous environment or continue.
-
- At some point, you need to call a tree walking function through a
- production REDUCE action, in the APPLY function. The tree walker is
- usually a set of recursive functions that select on the production tags
- found as tree tags.
- In order to trap on a tree node, you need to include calls to the functions
- 'traceit' and 'endit' wherever the tree walker will encounter a node.
- These must appear in nested-pair fashion, i.e. every 'traceit' call must
- be accompanied at some later time by a matching 'endit' call. See the
- tiny Pascal example semantics routines for examples of this coding.
- When the trap is sprung, you can examine the tree in detail, walking
- down through it, looking at its structure, attributes, etc. just prior
- to its evaluation by the tree walker.
-
- @idebug
-
- [idebug] ?(help, N(ame, A(ll, D(bug level,
- P(rodTrap, T(race, L(ex, S(tack, ENTER?
-
- This is a master debugging menu, called on any trap, which was
- triggered in one of these ways:
- 1) By a debug level > 0 through a parser action.
- 2) By the '-d' option when the compiled parser is executed.
- 3) By including the debug trap character '!' in the parsed source
- file somewhere. (The trap character '!' is defined in function GET_TOKEN
- in file SKELLEX.)
-
- F1 key (PC only) -- append the screen contents to file 'screen.txt'.
-
- N(ame -- prompts for a user identifier name, and reports its symbol
- attributes.
-
- A(ll -- report all the user identifiers known at this point, except
- reserved names.
-
- D(bug level -- set parser trap levels and reporting levels.
- Level 0 is no reporting. Level 1 reports each reduce action, showing the
- production about to be reduced, and this menu line. Level 2 reports each
- reduce action, the current stack contents, and the production about to
- be reduced. Level 3 reports all level 2 activity, and in addition, each
- SHIFT and LOOKAHEAD transition. Level 4 reports all the level activity,
- and in addition, all parser actions involved in an error recovery sequence.
- The parser traps are written into function 'parser' and require
- source generation with the '-d' option of LR1P to be effective.
-
- P(rodtrap -- set traps on particular productions. Set the debug level
- to 0 to bypass all reduce actions except those for the productions you've
- selected. See 'help' under this menu selection or topic 'set_prodtraps'
- for details.
-
- T(race -- set a trap on the evaluation phase of an abstract syntax
- tree, AFTER the tree has been constructed. This requires careful attention
- to coding the tree evaluator functions. See 'help' under this selection
- or topic 'set_nodetraps' for details.
-
- L(ex -- report the current state of the lexical analyzer. The 'next'
- token, its token number and other information are given.
-
- S(tack -- enter a semantics stack inspector, to examine the
- semantics stack and any trees rooted in the stack in detail. See 'help'
- under this selection or topic 'inspect_sem' for details.
-
- ENTER -- continue parsing from wherever this menu was called.
-
- @gramchk
-
- 'gramchk' checks some basic grammar properties, including the grammar
- syntax. It also provides listings of useful information.
- You can run 'gramchk' with just a grammar name, as follows:
-
- gramchk gramfile
-
- This will cause gramchk to check your grammar's syntax, to look for
- nonterminals that can't generate any terminal strings, and for any
- tokens that can't be derived from the goal symbol.
- Some of the 'gramchk' tests are built into LR1, and others aren't.
- (LR1 also complains if the grammar isn't LALR(1), which 'gramchk'
- doesn't check for.)
-
- To obtain more details on gramchk's services, do the following:
-
- Run 'gramchk' with no parameters -- you will obtain a list of the
- options possible. You can combine several options under the same '-'
- flag, or separate them. Any number of options can be chosen, or none,
- and their order doesn't matter.
-
- If you want more detailed help on any one option, for example, the 'f'
- option, run gramchk as follows:
-
- gramchk -f?
-
- This will display help information on that topic.
-
- Any of the information or tables may be redirected to a file or printer,
- as follows:
-
- gramchk (options) grammar > FILE
-
- Your printer is probably attached to device PRN, LPT1 or LPT2 -- use one
- of those names as FILE to print the information.
-
- The line length of certain reports -- production rules in particular --
- is not bounded, which may cause problems in your editor or printer. Most
- of the report line are limited to 75 characters.
-
- @lex
-
- Option -l causes a series of lexical tests to be
- performed. These tests depend on the language mode you are in -- see
- topic 'langmode' for more details. This version is set up to
- deal with the C and Pascal languages only.
- These tests look for problems that the Qparser lexical analyzer
- will likely have in identifying the tokens you have specified in your
- grammar.
- Gramchk can only look for problems with the STANDARD Qparser lexical
- analyzer under C or Pascal lexical rules. If you are using non-standard
- skeleton files, the reported problems may not exist, or you may have
- lexical problems that this can't look for. (The C code for gramchk is
- shipped with the product so that you can adapt it to unusual lexical
- situations if you want to.)
- Details on Qparser's lexical analysis are given in the manual. Here's
- a summary:
-
- 1. Identifiers (<identifier>) are assumed to start with a letter
- and continue with letters, digits or underscore (_). It's OK to have
- specific tokens look like an identifier, but it's NOT OK to have a
- token that starts with a letter, but includes any character other than
- letters, digits or underscore. For example, any of these tokens
- are considered illegal:
-
- TOK*
- C++
- alphabet%soup
-
- You will have to modify the lexical analyzer, in particular 'get_token'
- and 'get_symbol', to deal with such cases.
- A WARNING will appear if an identifier can be followed by some token
- whose first character is a letter, digit or underscore -- you will have
- to make sure that a SPACE appears as a separator between such tokens.
- A WARNING will appear if any token starts with a lower-case letter. The
- default lexical analyzer upshifts the letters in all such tokens from
- lowercase to uppercase, making such tokens unrecognizable. You can
- easily change this convention -- see skellex.c or skellex.pas. When
- such tokens are built into the Qparser tables, their case is NOT changed --
- they will appear in the tables exactly as entered in the grammar.
-
- 2. Integers (<integer>) are assumed to start with a digit and continue
- with digits. It's NOT OK to have any other token start with a digit.
- For example, any of these are considered illegal:
-
- 5xyz
- 0*66
-
- You will have to modify the lexical analyzer, in particular 'get_token'
- and 'get_number', to deal with such cases.
- A WARNING will appear if an integer can be followed by some token
- whose first character is a digit -- you will have
- to make sure that a SPACE appears as a separator between such tokens.
-
- 3. Real numbers (<real>) are assumed to start with a digit or a
- decimal point. It's NOT OK to have any other token start with a digit
- or a decimal point, therefore.
-
- For example, any of these are considered illegal:
-
- 5xyz
- ..
- .XOR.
-
- You will have to modify the lexical analyzer, in particular 'get_token'
- and 'get_number', to deal with such cases.
- A WARNING will appear if an integer or real can be followed by some token
- whose first character is a digit, letter or '.' -- you will have
- to make sure that a SPACE appears as a separator between such tokens.
- The reason for this warning is that if a '.' or letter 'E' follows a
- digit string with no separating space, the lexical analyzer assumes that
- a real number is being scanned.
-
- 4. Strings (<string>) are assumed to start with a string-quote
- character -- " in C, ' in Pascal. It's NOT OK to have any other token
- start with a quote character.
-
- For example, this is considered illegal tokens under C rules:
-
- "xx
-
- You will have to modify the lexical analyzer, in particular 'get_token'
- and 'get_string', to deal with such cases.
-
- 5. Comments can appear anywhere. In the C skeletons, a comment
- follows C rules -- it opens with '/*' and closes with '*/'. Clearly,
- no token should start with '/*', otherwise it'll be confused with
- a comment opening. In the Pascal skeletons, a comment is assumed to
- open with '{' and close with '}'.
- If your grammar contains the token <eol>, the rules change -- a
- comment is assumed to open with a semicolon ';' and close at the
- end of the line. Clearly no token can open with ';'.
- See function 'skipblanks' in file 'skellex' for details on
- how comments are identified and scanned. You can easily change the
- rules to suit your situation.
-
- @nullables
-
- A 'nullable' nonterminal is a nonterminal that can derive the
- empty string <empty>. The derivation can entail any number of rule
- expansions. Option -n prints the nullable nonterminals that exist
- in your grammar.
-
- @prods
-
- Option -p prints the productions with their flags in the order that
- they appear in your grammar. These are reformatted, and not just a
- copy of how they appear in your source grammar. The index numbers
- refer to their position in the input file.
- NOTE: When you run 'lr1', the table 'prodx' is indexed by a reduce
- state number, not a production number, and refers to the associated
- production. The reduce state number will usually not correspond to
- the production's input file index.
-
- @flags
-
- Option -f prints the production flags -- sorted alphabetically --
- and the production or productions with which each one is associated.
- You can use this to look for multiply-defined flags, which are legal
- but may not be what you expect.
- Note that each flag name will be declared within your parser program
- as a #define (in C) or a 'const' (in Pascal). You need to be aware
- that a flag may conflict with a keyword or user symbol in its scope.
- Gramchk will warn you about conflicts with host language keywords
- and Qparser names.
-
- Option -fC prints the production flags -- sorted alphabetically --
- and the productions, then lists the child node flags that can appear
- under each of the production's right member nonterminals.
-
- Option -fP prints the production flags -- sorted alphabetically --
- and the productions, then lists the node flags that can appear as this
- node's parent.
-
- @preds
-
- Option -P displays the predecessors of each token in the language,
- whether terminal or nonterminal. The predecessor set pred(T) for a
- token T is defined as follows:
-
- Given a production
-
- A -> w1 w2 w3 ...
-
- then 1) pred(w1) will contain pred(A),
- 2) pred(w2) contains w1,
- 3) pred(w3) contains w2, etc.
-
- It can be shown that if token T appears in the semantics stack
- during an LR parse, then the token preceding it in the stack (i.e. deeper
- in the stack) will be a member of pred(T). The converse is true if
- the grammar is closed -- i.e. every nonterminal can derive the empty
- string and can be reached from the goal token by some derivation.
-
- @crossref
-
- Option -r generates a cross-reference table of tokens in your
- grammar. The tokens are sorted, and the production indices that
- contain at least one instance of the token are listed. We suggest
- running
-
- gramchk -pr
-
- to also produce an indexed production list.
-
- @sprods
-
- Option -s generates an indexed list of productions sorted by
- their left member. (The index numbers correspond to their position
- in the input file, but are usually out of order).
-
- @tokens
-
- Option -t generates a list of the tokens and their token indices
- assigned by Qparser. The terminal tokens are listed first, followed
- by the nonterminal tokens.
- The token index will be built into the parsing tables and into
- the function 'get_token'. Function 'get_token' is partially built
- by Qparser based on this list of token numbers.
-
- @firstfol
-
- Option -F generates a list of the 'first' and 'follow' sets. These
- are explained in more detail in the manual and in most popular compiler
- construction textbooks. They are useful in constructing an LL(1)
- parser, and in understanding LR(1) parser conflicts. A summary follows:
-
- first(N) is a mapping of the set {terminals, nonterminals} to the
- set {terminals, <empty>}. Essentially, first(N) is the set of all
- terminal tokens that can appear as the leftmost token in any string
- derivable from N.
-
- follow(N) is a mapping of the set {terminals, nonterminals} to the
- set {terminals, nonterminals, <stop>}. Let S be any sentential
- form derivable from the goal symbol G:
-
- G ==>* S
-
- and let S contain a token W followed by a string w:
-
- S = x W w
-
- Then head(w follow(S)) is in follow(W), where 'head' is the left-most
- character of the composite string
-
- w follow(S)
-
- The token <stop> will always be in follow(G).
-
- @ll1gen
-
- The -L option causes gramchk to ignore its other options (except
- for this help feature) and generate a set of arrays that can be used to
- build an LL(1) parser. (This is primarily for the benefit of our academic
- users -- we don't recommend an LL(1) parser for commercial use).
- The syntax of the tables will be in either C or Pascal form, depending
- on the setting of the language mode option '-m'.
- The tables can be included in a parser program (not supplied), which
- can use the 'lex' file generated from 'skellex' as the lexical analyzer.
- A more complete description of the tables can be found in "Compiler
- Construction: Theory and Practice", Barrett and Couch.
- LL(1) conflicts are reported as comments, and should be dealt with in
- order that the parser recognize the whole language.
- The 'token' table is an array of tokens indexed by token number. This
- isn't required in the LL(1) parser, but can be used to make a table-driven
- lexical analyzer.
- The 'rpartx' table is an array of indices into 'rpart'. Given the
- production rule index P, where the length of the right member is N, then
- the production is
-
- A -> rpart[rpartx[P]+N-1] rpart[rpartx[P]+N-2] ...
- rpart[rpartx[P]+0]
- Notice that the right member is in reverse order as it appears in the
- 'rpart' table. The element rpart[rpartx[P]] is always 0, so that it
- can be used as a stopper. Except for the '0', each 'rpart' element is
- a token number. Only the right members are listed -- the left member
- isn't required.
- The 'nttx', 'nttl' and 'aprodn' tables are organized in a similar manner,
- and are entered by a token number. Their use is explained below.
-
- If your grammar is LL(1), then an LL(1) parser can be built as follows:
-
- 1. Provide a pushdown stack containing token numbers, initially containing
- the 'goal' token -- this is token rpart[0].
- 2. Given a token T on the stack top, and a token R under the read head,
- a. If token N is the <stop> token, the stack should be empty. HALT.
- b. If T is a terminal, it must match token R, else SYNTAX ERROR.
- Pop the stack and move the read head one position (i.e. request
- the next token by calling 'next_token'). Go to step (a).
- c. If T is nonterminal, enter the 'nttx' table with the index
- T - NT_OFFSET
- Let n = nttx[T - NT_OFFSET].
- d. Scan the 'nttl' table starting at index n, continuing until
- nttl[n] == 0 (syntax error)
- OR
- nttl[n] == R. (OK)
- e. Table aprodn[n] is an index into the 'rpartx' table. Pop the
- stack and push the right member of the production onto the
- stack such that the left-most token in the right member is
- on the stack top. You can just push the 'rpart' elements
- into the stack, starting with index k= n, incrementing k,
- until rpart[k] == 0. This is an 'apply' step and can be
- used to develop semantics and/or code generation based on the
- selected production.
- f. Table 'map' is indexed by 'n' from step (e); it contains
- a flag index related to the 'flags' table. Use this to apply
- your semantics to a particular production rule on an apply step.
- Go to step (a).
- 3. Recovery from a syntax error is a difficult topic and can't be dealt
- with here.
-
- @langmode
-
- Option -mX selects one of three 'language modes': C, P (for Pascal),
- or N (for none). If you are using a semantics-extended grammar, it's
- important that you select this mode when using gramchk, otherwise you'll
- probably get a grammar syntax error.
- The default language is C.
- This mode is also used in the -l and -L options, which are sensitive
- to the language choice.
-
- @lr1
-
- lr1 [options] GFILE
-
- GFILE is a grammar file name, which can appear with or without its
- standard suffix '.grm'. lr1 generates a binary table file 'GFILE.tbl'.
- A grammar file consists of BNF-style production rules, in the form
-
- Left -> { RightToken } [ #tag ]
-
- in one line, i.e. a line feed terminates a production rule. The token
- 'Left' is considered a nonterminal. All rules with the same 'Left' must
- be grouped together. Each 'RightToken' is a nonterminal or a terminal.
- Terminal tokens stand for themselves, and can be quoted if special
- characters are used.
- The 'tag' is a case-sensitive name that must be compatible with a
- user identifier in the host language -- it will show up as a 'const'
- in Pascal or a 'define' in C skeletons.
- The special terminals
-
- <stop> <eol> <identifier> <real> <integer> <string>
-
- stand for end-of-file, end-of-line, user identifier, floating-point
- number, integer, and quoted string, repectively in the source file.
- The form of these is defined in file SKELLEX and can be modified.
- The default <identifier> starts with a letter, and continues with
- letters, digits and the underbar character. See function 'get_symbol'
- in file skellex.
- The default <real> is known through an embedded decimal point, or
- an exponent part or both. See function 'get_number' in file skellex.
- The default <integer> is a simple decimal number. See function
- 'get_number' in file skellex.
- The default <string> is Pascal-style in the Pascal skeletons and
- C-style in the C skeletons. See function 'get_string' in file skellex.
-
- A brief list of the options are provided by running 'lr1' with no
- options, i.e.
-
- lr1
-
- which should produce the following report:
-
- QPARSER vs. 4.7
- Copyright (c) QCAD Systems, Inc. 1990. All rights reserved.
- Usage: lr1 [options] GrammarFile [RptFile]
- options: -t dump tokens
- -p dump productions
- -n dump nullable nonterminals
- -i dump itemsets
- -mL language mode -- L==C, P, N
- -MN dump state machine
- N= 1, 2: dump level
- -r dump reads/includes/lookbacks
- -T tablefile table file name
- -s suppress single-production bypassing
- -? help: more description of the options
- -C generate table file compatible with 3.0
- (default tablefile name is grammar-filename.tbl)
-
- The token and production lists are self-explanatory.
- A "nullable nonterminal" is a nonterminal that can generate an
- empty string. Option -n lists all of these associated with the grammar.
- An "itemset" (-i) is a collection of marked productions associated with
- a state in the LR parsing machine. You need to study LR table construction
- to understand these. Option '-r' produces an itemset dump at a later
- stage that reports the LALR 'reads', 'includes' and 'lookback' sets,
- described in the Penello/DeRemer paper on this construction method.
- The language mode (-mC, -mP, -mN) is required if you are using a
- semantics-extended grammar. (Such a grammar has semantics attached to
- one or more production rules). The grammar scanner must know the
- language mode (C, Pascal or None) in order to scan the semantics rules
- properly.
- The "state machine" (option -M) is a semi-reduced representation of
- the LALR state machine in terms of reduce, shift and lookahead states,
- and their transitions. This is derived from the itemsets, but the
- states have been renumbered.
- Option -T specifies an alternative table file name. The default table
- file name is derived from the grammar name.
- Option -s suppresses an optimization by which some single productions
- are bypassed.
- Option -C causes LR1 to generate a table file compatible with the
- older version 3.0 Qparser system. You can use such a file with any
- earlier version of LR1P.
-
- @lr1p
-
- lr1p requires a table file and a skeleton file. It produces an
- expanded source file as its 'standard-out' -- this is normally
- redirected to a source file.
- The skeleton file is mostly copied, except for sections delimited
- by the special tokens '{##' and '##}'. These contain a source
- generator program, whose definition is too complicated to describe
- here. Each generator program section is replaced by source code
- based on the grammar tables and the generator directions. The intent
- is to produce source ready to compile, whether by a C or Pascal
- compiler or whatever.
- Running lr1p by itself produces a brief listing of its options,
- similar to the following:
-
- LR1P [options] tablefile skeletonfile [targetfile]
- (or redirect output to target source file)
- Options:
- -d include debug code (default: no debug code)
- -mX language mode (X= P or C). C is the default.
- -t charfile
- -? help: describes options and operations
- -C accept vs. 3.0 compatible table file
-
- Option -d causes lr1p to generate material needed by the debugging
- system.
-
- Option -mP selects Pascal mode, and -mC C mode. These are used to
- determine how 'qstring' and 'qcharacter' will expand strings and
- characters. Option -t selects a character translation file, which is
- a more general way of controlling string and character expansion.
- In Pascal mode, a single-quote character in a string or character will
- expand into a pair of single quotes. qstring and qcharacter will enclose
- the resulting string or character in a pair of single quotes.
- In C mode, a double-quote in qstring will appear as \", a backslash
- in qstring or qcharacter will appear as \\, and a single quote in a
- qcharacter will appear as \'. qstring will enclose the string in double
- quotes. qcharacter will enclose a character in single quotes. All other
- characters appear "as is".
- If the -t option is selected, a character expansion file is read. Please
- see the user manual or release notes regarding its format and usage. It
- specifies how qstring and qcharacter map characters and enclose a string
- or character. An expansion file for C, which also contains documentation,
- is CFILE.CEF.
-
- Option -C causes lr1p to accept a table file generated by a vs. 3.0
- Qparser lr1 program.
-
- @opt
-
- Program 'opt' applies several optimizations to the table file
- generated by lr1. You don't need to use it, but the time spent in
- running opt is usually less than a few seconds, and is worth it in
- terms of smaller tables. Opt can be applied to an optimized table
- file and does nothing to the file.
-
- Running 'opt' by itself produces a brief description of its options:
-
- Usage: opt [-h][-C] table_filename
- -? help: more program description
- -C optimize vs. 3.0 table file
-
- Option -C causes opt to accept a vs. 3.0 table file. This is for
- compatibility only. Version 3.0 supports a similar optimization built
- into its lr1 program, so running opt provides no space improvement.
- However, by running lr1 and opt with -C, you can then use the vs. 3.0
- (or earlier) lr1p and other skeleton files with the generated table file.
-