home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / Source / GNU / bison / bison.info-3 (.txt) < prev    next >
GNU Info File  |  1996-02-17  |  51KB  |  977 lines
  1. This is Info file bison.info, produced by Makeinfo-1.64 from the input
  2. file ./bison.texinfo.
  3.    This file documents the Bison parser generator.
  4.    Copyright (C) 1988, 89, 90, 91, 92, 93, 1995 Free Software
  5. Foundation, Inc.
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9.    Permission is granted to copy and distribute modified versions of
  10. this manual under the conditions for verbatim copying, provided also
  11. that the sections entitled "GNU General Public License" and "Conditions
  12. for Using Bison" are included exactly as in the original, and provided
  13. that the entire resulting derived work is distributed under the terms
  14. of a permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that the sections entitled "GNU General Public
  18. License", "Conditions for Using Bison" and this permission notice may be
  19. included in translations approved by the Free Software Foundation
  20. instead of in the original English.
  21. File: bison.info,  Node: Mid-Rule Actions,  Prev: Action Types,  Up: Semantics
  22. Actions in Mid-Rule
  23. -------------------
  24.    Occasionally it is useful to put an action in the middle of a rule.
  25. These actions are written just like usual end-of-rule actions, but they
  26. are executed before the parser even recognizes the following components.
  27.    A mid-rule action may refer to the components preceding it using
  28. `$N', but it may not refer to subsequent components because it is run
  29. before they are parsed.
  30.    The mid-rule action itself counts as one of the components of the
  31. rule.  This makes a difference when there is another action later in
  32. the same rule (and usually there is another at the end): you have to
  33. count the actions along with the symbols when working out which number
  34. N to use in `$N'.
  35.    The mid-rule action can also have a semantic value.  The action can
  36. set its value with an assignment to `$$', and actions later in the rule
  37. can refer to the value using `$N'.  Since there is no symbol to name
  38. the action, there is no way to declare a data type for the value in
  39. advance, so you must use the `$<...>' construct to specify a data type
  40. each time you refer to this value.
  41.    There is no way to set the value of the entire rule with a mid-rule
  42. action, because assignments to `$$' do not have that effect.  The only
  43. way to set the value for the entire rule is with an ordinary action at
  44. the end of the rule.
  45.    Here is an example from a hypothetical compiler, handling a `let'
  46. statement that looks like `let (VARIABLE) STATEMENT' and serves to
  47. create a variable named VARIABLE temporarily for the duration of
  48. STATEMENT.  To parse this construct, we must put VARIABLE into the
  49. symbol table while STATEMENT is parsed, then remove it afterward.  Here
  50. is how it is done:
  51.      stmt:   LET '(' var ')'
  52.                      { $<context>$ = push_context ();
  53.                        declare_variable ($3); }
  54.              stmt    { $$ = $6;
  55.                        pop_context ($<context>5); }
  56. As soon as `let (VARIABLE)' has been recognized, the first action is
  57. run.  It saves a copy of the current semantic context (the list of
  58. accessible variables) as its semantic value, using alternative
  59. `context' in the data-type union.  Then it calls `declare_variable' to
  60. add the new variable to that list.  Once the first action is finished,
  61. the embedded statement `stmt' can be parsed.  Note that the mid-rule
  62. action is component number 5, so the `stmt' is component number 6.
  63.    After the embedded statement is parsed, its semantic value becomes
  64. the value of the entire `let'-statement.  Then the semantic value from
  65. the earlier action is used to restore the prior list of variables.  This
  66. removes the temporary `let'-variable from the list so that it won't
  67. appear to exist while the rest of the program is parsed.
  68.    Taking action before a rule is completely recognized often leads to
  69. conflicts since the parser must commit to a parse in order to execute
  70. the action.  For example, the following two rules, without mid-rule
  71. actions, can coexist in a working parser because the parser can shift
  72. the open-brace token and look at what follows before deciding whether
  73. there is a declaration or not:
  74.      compound: '{' declarations statements '}'
  75.              | '{' statements '}'
  76.              ;
  77. But when we add a mid-rule action as follows, the rules become
  78. nonfunctional:
  79.      compound: { prepare_for_local_variables (); }
  80.                '{' declarations statements '}'
  81.              | '{' statements '}'
  82.              ;
  83. Now the parser is forced to decide whether to run the mid-rule action
  84. when it has read no farther than the open-brace.  In other words, it
  85. must commit to using one rule or the other, without sufficient
  86. information to do it correctly.  (The open-brace token is what is called
  87. the "look-ahead" token at this time, since the parser is still deciding
  88. what to do about it.  *Note Look-Ahead Tokens: Look-Ahead.)
  89.    You might think that you could correct the problem by putting
  90. identical actions into the two rules, like this:
  91.      compound: { prepare_for_local_variables (); }
  92.                '{' declarations statements '}'
  93.              | { prepare_for_local_variables (); }
  94.                '{' statements '}'
  95.              ;
  96. But this does not help, because Bison does not realize that the two
  97. actions are identical.  (Bison never tries to understand the C code in
  98. an action.)
  99.    If the grammar is such that a declaration can be distinguished from a
  100. statement by the first token (which is true in C), then one solution
  101. which does work is to put the action after the open-brace, like this:
  102.      compound: '{' { prepare_for_local_variables (); }
  103.                declarations statements '}'
  104.              | '{' statements '}'
  105.              ;
  106. Now the first token of the following declaration or statement, which
  107. would in any case tell Bison which rule to use, can still do so.
  108.    Another solution is to bury the action inside a nonterminal symbol
  109. which serves as a subroutine:
  110.      subroutine: /* empty */
  111.                { prepare_for_local_variables (); }
  112.              ;
  113.      
  114.      compound: subroutine
  115.                '{' declarations statements '}'
  116.              | subroutine
  117.                '{' statements '}'
  118.              ;
  119. Now Bison can execute the action in the rule for `subroutine' without
  120. deciding which rule for `compound' it will eventually use.  Note that
  121. the action is now at the end of its rule.  Any mid-rule action can be
  122. converted to an end-of-rule action in this way, and this is what Bison
  123. actually does to implement mid-rule actions.
  124. File: bison.info,  Node: Declarations,  Next: Multiple Parsers,  Prev: Semantics,  Up: Grammar File
  125. Bison Declarations
  126. ==================
  127.    The "Bison declarations" section of a Bison grammar defines the
  128. symbols used in formulating the grammar and the data types of semantic
  129. values.  *Note Symbols::.
  130.    All token type names (but not single-character literal tokens such as
  131. `'+'' and `'*'') must be declared.  Nonterminal symbols must be
  132. declared if you need to specify which data type to use for the semantic
  133. value (*note More Than One Value Type: Multiple Types.).
  134.    The first rule in the file also specifies the start symbol, by
  135. default.  If you want some other symbol to be the start symbol, you
  136. must declare it explicitly (*note Languages and Context-Free Grammars:
  137. Language and Grammar.).
  138. * Menu:
  139. * Token Decl::        Declaring terminal symbols.
  140. * Precedence Decl::   Declaring terminals with precedence and associativity.
  141. * Union Decl::        Declaring the set of all semantic value types.
  142. * Type Decl::         Declaring the choice of type for a nonterminal symbol.
  143. * Expect Decl::       Suppressing warnings about shift/reduce conflicts.
  144. * Start Decl::        Specifying the start symbol.
  145. * Pure Decl::         Requesting a reentrant parser.
  146. * Decl Summary::      Table of all Bison declarations.
  147. File: bison.info,  Node: Token Decl,  Next: Precedence Decl,  Up: Declarations
  148. Token Type Names
  149. ----------------
  150.    The basic way to declare a token type name (terminal symbol) is as
  151. follows:
  152.      %token NAME
  153.    Bison will convert this into a `#define' directive in the parser, so
  154. that the function `yylex' (if it is in this file) can use the name NAME
  155. to stand for this token type's code.
  156.    Alternatively, you can use `%left', `%right', or `%nonassoc' instead
  157. of `%token', if you wish to specify precedence.  *Note Operator
  158. Precedence: Precedence Decl.
  159.    You can explicitly specify the numeric code for a token type by
  160. appending an integer value in the field immediately following the token
  161. name:
  162.      %token NUM 300
  163. It is generally best, however, to let Bison choose the numeric codes for
  164. all token types.  Bison will automatically select codes that don't
  165. conflict with each other or with ASCII characters.
  166.    In the event that the stack type is a union, you must augment the
  167. `%token' or other token declaration to include the data type
  168. alternative delimited by angle-brackets (*note More Than One Value
  169. Type: Multiple Types.).
  170.    For example:
  171.      %union {              /* define stack type */
  172.        double val;
  173.        symrec *tptr;
  174.      }
  175.      %token <val> NUM      /* define token NUM and its type */
  176.    You can associate a literal string token with a token type name by
  177. writing the literal string at the end of a `%token' declaration which
  178. declares the name.  For example:
  179.      %token arrow "=>"
  180. For example, a grammar for the C language might specify these names with
  181. equivalent literal string tokens:
  182.      %token  <operator>  OR      "||"
  183.      %token  <operator>  LE 134  "<="
  184.      %left  OR  "<="
  185. Once you equate the literal string and the token name, you can use them
  186. interchangeably in further declarations or the grammar rules.  The
  187. `yylex' function can use the token name or the literal string to obtain
  188. the token type code number (*note Calling Convention::.).
  189. File: bison.info,  Node: Precedence Decl,  Next: Union Decl,  Prev: Token Decl,  Up: Declarations
  190. Operator Precedence
  191. -------------------
  192.    Use the `%left', `%right' or `%nonassoc' declaration to declare a
  193. token and specify its precedence and associativity, all at once.  These
  194. are called "precedence declarations".  *Note Operator Precedence:
  195. Precedence, for general information on operator precedence.
  196.    The syntax of a precedence declaration is the same as that of
  197. `%token': either
  198.      %left SYMBOLS...
  199.      %left <TYPE> SYMBOLS...
  200.    And indeed any of these declarations serves the purposes of `%token'.
  201. But in addition, they specify the associativity and relative precedence
  202. for all the SYMBOLS:
  203.    * The associativity of an operator OP determines how repeated uses
  204.      of the operator nest: whether `X OP Y OP Z' is parsed by grouping
  205.      X with Y first or by grouping Y with Z first.  `%left' specifies
  206.      left-associativity (grouping X with Y first) and `%right'
  207.      specifies right-associativity (grouping Y with Z first).
  208.      `%nonassoc' specifies no associativity, which means that `X OP Y
  209.      OP Z' is considered a syntax error.
  210.    * The precedence of an operator determines how it nests with other
  211.      operators.  All the tokens declared in a single precedence
  212.      declaration have equal precedence and nest together according to
  213.      their associativity.  When two tokens declared in different
  214.      precedence declarations associate, the one declared later has the
  215.      higher precedence and is grouped first.
  216. File: bison.info,  Node: Union Decl,  Next: Type Decl,  Prev: Precedence Decl,  Up: Declarations
  217. The Collection of Value Types
  218. -----------------------------
  219.    The `%union' declaration specifies the entire collection of possible
  220. data types for semantic values.  The keyword `%union' is followed by a
  221. pair of braces containing the same thing that goes inside a `union' in
  222.    For example:
  223.      %union {
  224.        double val;
  225.        symrec *tptr;
  226.      }
  227. This says that the two alternative types are `double' and `symrec *'.
  228. They are given names `val' and `tptr'; these names are used in the
  229. `%token' and `%type' declarations to pick one of the types for a
  230. terminal or nonterminal symbol (*note Nonterminal Symbols: Type Decl.).
  231.    Note that, unlike making a `union' declaration in C, you do not write
  232. a semicolon after the closing brace.
  233. File: bison.info,  Node: Type Decl,  Next: Expect Decl,  Prev: Union Decl,  Up: Declarations
  234. Nonterminal Symbols
  235. -------------------
  236. When you use `%union' to specify multiple value types, you must declare
  237. the value type of each nonterminal symbol for which values are used.
  238. This is done with a `%type' declaration, like this:
  239.      %type <TYPE> NONTERMINAL...
  240. Here NONTERMINAL is the name of a nonterminal symbol, and TYPE is the
  241. name given in the `%union' to the alternative that you want (*note The
  242. Collection of Value Types: Union Decl.).  You can give any number of
  243. nonterminal symbols in the same `%type' declaration, if they have the
  244. same value type.  Use spaces to separate the symbol names.
  245.    You can also declare the value type of a terminal symbol.  To do
  246. this, use the same `<TYPE>' construction in a declaration for the
  247. terminal symbol.  All kinds of token declarations allow `<TYPE>'.
  248. File: bison.info,  Node: Expect Decl,  Next: Start Decl,  Prev: Type Decl,  Up: Declarations
  249. Suppressing Conflict Warnings
  250. -----------------------------
  251.    Bison normally warns if there are any conflicts in the grammar
  252. (*note Shift/Reduce Conflicts: Shift/Reduce.), but most real grammars
  253. have harmless shift/reduce conflicts which are resolved in a
  254. predictable way and would be difficult to eliminate.  It is desirable
  255. to suppress the warning about these conflicts unless the number of
  256. conflicts changes.  You can do this with the `%expect' declaration.
  257.    The declaration looks like this:
  258.      %expect N
  259.    Here N is a decimal integer.  The declaration says there should be no
  260. warning if there are N shift/reduce conflicts and no reduce/reduce
  261. conflicts.  The usual warning is given if there are either more or fewer
  262. conflicts, or if there are any reduce/reduce conflicts.
  263.    In general, using `%expect' involves these steps:
  264.    * Compile your grammar without `%expect'.  Use the `-v' option to
  265.      get a verbose list of where the conflicts occur.  Bison will also
  266.      print the number of conflicts.
  267.    * Check each of the conflicts to make sure that Bison's default
  268.      resolution is what you really want.  If not, rewrite the grammar
  269.      and go back to the beginning.
  270.    * Add an `%expect' declaration, copying the number N from the number
  271.      which Bison printed.
  272.    Now Bison will stop annoying you about the conflicts you have
  273. checked, but it will warn you again if changes in the grammar result in
  274. additional conflicts.
  275. File: bison.info,  Node: Start Decl,  Next: Pure Decl,  Prev: Expect Decl,  Up: Declarations
  276. The Start-Symbol
  277. ----------------
  278.    Bison assumes by default that the start symbol for the grammar is
  279. the first nonterminal specified in the grammar specification section.
  280. The programmer may override this restriction with the `%start'
  281. declaration as follows:
  282.      %start SYMBOL
  283. File: bison.info,  Node: Pure Decl,  Next: Decl Summary,  Prev: Start Decl,  Up: Declarations
  284. A Pure (Reentrant) Parser
  285. -------------------------
  286.    A "reentrant" program is one which does not alter in the course of
  287. execution; in other words, it consists entirely of "pure" (read-only)
  288. code.  Reentrancy is important whenever asynchronous execution is
  289. possible; for example, a nonreentrant program may not be safe to call
  290. from a signal handler.  In systems with multiple threads of control, a
  291. nonreentrant program must be called only within interlocks.
  292.    The Bison parser is not normally a reentrant program, because it uses
  293. statically allocated variables for communication with `yylex'.  These
  294. variables include `yylval' and `yylloc'.
  295.    The Bison declaration `%pure_parser' says that you want the parser
  296. to be reentrant.  It looks like this:
  297.      %pure_parser
  298.    The effect is that the two communication variables become local
  299. variables in `yyparse', and a different calling convention is used for
  300. the lexical analyzer function `yylex'.  *Note Calling Conventions for
  301. Pure Parsers: Pure Calling, for the details of this.  The variable
  302. `yynerrs' also becomes local in `yyparse' (*note The Error Reporting
  303. Function `yyerror': Error Reporting.).  The convention for calling
  304. `yyparse' itself is unchanged.
  305. File: bison.info,  Node: Decl Summary,  Prev: Pure Decl,  Up: Declarations
  306. Bison Declaration Summary
  307. -------------------------
  308.    Here is a summary of all Bison declarations:
  309. `%union'
  310.      Declare the collection of data types that semantic values may have
  311.      (*note The Collection of Value Types: Union Decl.).
  312. `%token'
  313.      Declare a terminal symbol (token type name) with no precedence or
  314.      associativity specified (*note Token Type Names: Token Decl.).
  315. `%right'
  316.      Declare a terminal symbol (token type name) that is
  317.      right-associative (*note Operator Precedence: Precedence Decl.).
  318. `%left'
  319.      Declare a terminal symbol (token type name) that is
  320.      left-associative (*note Operator Precedence: Precedence Decl.).
  321. `%nonassoc'
  322.      Declare a terminal symbol (token type name) that is nonassociative
  323.      (using it in a way that would be associative is a syntax error)
  324.      (*note Operator Precedence: Precedence Decl.).
  325. `%type'
  326.      Declare the type of semantic values for a nonterminal symbol
  327.      (*note Nonterminal Symbols: Type Decl.).
  328. `%start'
  329.      Specify the grammar's start symbol (*note The Start-Symbol: Start
  330.      Decl.).
  331. `%expect'
  332.      Declare the expected number of shift-reduce conflicts (*note
  333.      Suppressing Conflict Warnings: Expect Decl.).
  334. `%pure_parser'
  335.      Request a pure (reentrant) parser program (*note A Pure
  336.      (Reentrant) Parser: Pure Decl.).
  337. `%no_lines'
  338.      Don't generate any `#line' preprocessor commands in the parser
  339.      file.  Ordinarily Bison writes these commands in the parser file
  340.      so that the C compiler and debuggers will associate errors and
  341.      object code with your source file (the grammar file).  This
  342.      directive causes them to associate errors with the parser file,
  343.      treating it an independent source file in its own right.
  344. `%raw'
  345.      The output file `NAME.h' normally defines the tokens with
  346.      Yacc-compatible token numbers.  If this option is specified, the
  347.      internal Bison numbers are used instead.  (Yacc-compatible numbers
  348.      start at 257 except for single character tokens; Bison assigns
  349.      token numbers sequentially for all tokens starting at 3.)
  350. `%token_table'
  351.      Generate an array of token names in the parser file.  The name of
  352.      the array is `yytname'; `yytname[I]' is the name of the token
  353.      whose internal Bison token code number is I.  The first three
  354.      elements of `yytname' are always `"$"', `"error"', and
  355.      `"$illegal"'; after these come the symbols defined in the grammar
  356.      file.
  357.      For single-character literal tokens and literal string tokens, the
  358.      name in the table includes the single-quote or double-quote
  359.      characters: for example, `"'+'"' is a single-character literal and
  360.      `"\"<=\""' is a literal string token.  All the characters of the
  361.      literal string token appear verbatim in the string found in the
  362.      table; even double-quote characters are not escaped.  For example,
  363.      if the token consists of three characters `*"*', its string in
  364.      `yytname' contains `"*"*"'.  (In C, that would be written as
  365.      `"\"*\"*\""').
  366.      When you specify `%token_table', Bison also generates macro
  367.      definitions for macros `YYNTOKENS', `YYNNTS', and `YYNRULES', and
  368.      `YYNSTATES':
  369.     `YYNTOKENS'
  370.           The highest token number, plus one.
  371.     `YYNNTS'
  372.           The number of non-terminal symbols.
  373.     `YYNRULES'
  374.           The number of grammar rules,
  375.     `YYNSTATES'
  376.           The number of parser states (*note Parser States::.).
  377. File: bison.info,  Node: Multiple Parsers,  Prev: Declarations,  Up: Grammar File
  378. Multiple Parsers in the Same Program
  379. ====================================
  380.    Most programs that use Bison parse only one language and therefore
  381. contain only one Bison parser.  But what if you want to parse more than
  382. one language with the same program?  Then you need to avoid a name
  383. conflict between different definitions of `yyparse', `yylval', and so
  384.    The easy way to do this is to use the option `-p PREFIX' (*note
  385. Invoking Bison: Invocation.).  This renames the interface functions and
  386. variables of the Bison parser to start with PREFIX instead of `yy'.
  387. You can use this to give each parser distinct names that do not
  388. conflict.
  389.    The precise list of symbols renamed is `yyparse', `yylex',
  390. `yyerror', `yynerrs', `yylval', `yychar' and `yydebug'.  For example,
  391. if you use `-p c', the names become `cparse', `clex', and so on.
  392.    *All the other variables and macros associated with Bison are not
  393. renamed.* These others are not global; there is no conflict if the same
  394. name is used in different parsers.  For example, `YYSTYPE' is not
  395. renamed, but defining this in different ways in different parsers causes
  396. no trouble (*note Data Types of Semantic Values: Value Type.).
  397.    The `-p' option works by adding macro definitions to the beginning
  398. of the parser source file, defining `yyparse' as `PREFIXparse', and so
  399. on.  This effectively substitutes one name for the other in the entire
  400. parser file.
  401. File: bison.info,  Node: Interface,  Next: Algorithm,  Prev: Grammar File,  Up: Top
  402. Parser C-Language Interface
  403. ***************************
  404.    The Bison parser is actually a C function named `yyparse'.  Here we
  405. describe the interface conventions of `yyparse' and the other functions
  406. that it needs to use.
  407.    Keep in mind that the parser uses many C identifiers starting with
  408. `yy' and `YY' for internal purposes.  If you use such an identifier
  409. (aside from those in this manual) in an action or in additional C code
  410. in the grammar file, you are likely to run into trouble.
  411. * Menu:
  412. * Parser Function::   How to call `yyparse' and what it returns.
  413. * Lexical::           You must supply a function `yylex'
  414.                         which reads tokens.
  415. * Error Reporting::   You must supply a function `yyerror'.
  416. * Action Features::   Special features for use in actions.
  417. File: bison.info,  Node: Parser Function,  Next: Lexical,  Up: Interface
  418. The Parser Function `yyparse'
  419. =============================
  420.    You call the function `yyparse' to cause parsing to occur.  This
  421. function reads tokens, executes actions, and ultimately returns when it
  422. encounters end-of-input or an unrecoverable syntax error.  You can also
  423. write an action which directs `yyparse' to return immediately without
  424. reading further.
  425.    The value returned by `yyparse' is 0 if parsing was successful
  426. (return is due to end-of-input).
  427.    The value is 1 if parsing failed (return is due to a syntax error).
  428.    In an action, you can cause immediate return from `yyparse' by using
  429. these macros:
  430. `YYACCEPT'
  431.      Return immediately with value 0 (to report success).
  432. `YYABORT'
  433.      Return immediately with value 1 (to report failure).
  434. File: bison.info,  Node: Lexical,  Next: Error Reporting,  Prev: Parser Function,  Up: Interface
  435. The Lexical Analyzer Function `yylex'
  436. =====================================
  437.    The "lexical analyzer" function, `yylex', recognizes tokens from the
  438. input stream and returns them to the parser.  Bison does not create
  439. this function automatically; you must write it so that `yyparse' can
  440. call it.  The function is sometimes referred to as a lexical scanner.
  441.    In simple programs, `yylex' is often defined at the end of the Bison
  442. grammar file.  If `yylex' is defined in a separate source file, you
  443. need to arrange for the token-type macro definitions to be available
  444. there.  To do this, use the `-d' option when you run Bison, so that it
  445. will write these macro definitions into a separate header file
  446. `NAME.tab.h' which you can include in the other source files that need
  447. it.  *Note Invoking Bison: Invocation.
  448. * Menu:
  449. * Calling Convention::  How `yyparse' calls `yylex'.
  450. * Token Values::      How `yylex' must return the semantic value
  451.                         of the token it has read.
  452. * Token Positions::   How `yylex' must return the text position
  453.                         (line number, etc.) of the token, if the
  454.                         actions want that.
  455. * Pure Calling::      How the calling convention differs
  456.                         in a pure parser (*note A Pure (Reentrant) Parser: Pure Decl.).
  457. File: bison.info,  Node: Calling Convention,  Next: Token Values,  Up: Lexical
  458. Calling Convention for `yylex'
  459. ------------------------------
  460.    The value that `yylex' returns must be the numeric code for the type
  461. of token it has just found, or 0 for end-of-input.
  462.    When a token is referred to in the grammar rules by a name, that name
  463. in the parser file becomes a C macro whose definition is the proper
  464. numeric code for that token type.  So `yylex' can use the name to
  465. indicate that type.  *Note Symbols::.
  466.    When a token is referred to in the grammar rules by a character
  467. literal, the numeric code for that character is also the code for the
  468. token type.  So `yylex' can simply return that character code.  The
  469. null character must not be used this way, because its code is zero and
  470. that is what signifies end-of-input.
  471.    Here is an example showing these things:
  472.      yylex ()
  473.      {
  474.        ...
  475.        if (c == EOF)     /* Detect end of file. */
  476.          return 0;
  477.        ...
  478.        if (c == '+' || c == '-')
  479.          return c;      /* Assume token type for `+' is '+'. */
  480.        ...
  481.        return INT;      /* Return the type of the token. */
  482.        ...
  483.      }
  484. This interface has been designed so that the output from the `lex'
  485. utility can be used without change as the definition of `yylex'.
  486.    If the grammar uses literal string tokens, there are two ways that
  487. `yylex' can determine the token type codes for them:
  488.    * If the grammar defines symbolic token names as aliases for the
  489.      literal string tokens, `yylex' can use these symbolic names like
  490.      all others.  In this case, the use of the literal string tokens in
  491.      the grammar file has no effect on `yylex'.
  492.    * `yylex' can find the multi-character token in the `yytname' table.
  493.      The index of the token in the table is the token type's code.
  494.      The name of a multi-character token is recorded in `yytname' with a
  495.      double-quote, the token's characters, and another double-quote.
  496.      The token's characters are not escaped in any way; they appear
  497.      verbatim in the contents of the string in the table.
  498.      Here's code for looking up a token in `yytname', assuming that the
  499.      characters of the token are stored in `token_buffer'.
  500.           for (i = 0; i < YYNTOKENS; i++)
  501.             {
  502.               if (yytname[i] != 0
  503.                   && yytname[i][0] == '"'
  504.                   && strncmp (yytname[i] + 1, token_buffer, strlen (token_buffer))
  505.                   && yytname[i][strlen (token_buffer) + 1] == '"'
  506.                   && yytname[i][strlen (token_buffer) + 2] == 0)
  507.                 break;
  508.             }
  509.      The `yytname' table is generated only if you use the
  510.      `%token_table' declaration.  *Note Decl Summary::.
  511. File: bison.info,  Node: Token Values,  Next: Token Positions,  Prev: Calling Convention,  Up: Lexical
  512. Semantic Values of Tokens
  513. -------------------------
  514.    In an ordinary (nonreentrant) parser, the semantic value of the
  515. token must be stored into the global variable `yylval'.  When you are
  516. using just one data type for semantic values, `yylval' has that type.
  517. Thus, if the type is `int' (the default), you might write this in
  518. `yylex':
  519.        ...
  520.        yylval = value;  /* Put value onto Bison stack. */
  521.        return INT;      /* Return the type of the token. */
  522.        ...
  523.    When you are using multiple data types, `yylval''s type is a union
  524. made from the `%union' declaration (*note The Collection of Value
  525. Types: Union Decl.).  So when you store a token's value, you must use
  526. the proper member of the union.  If the `%union' declaration looks like
  527. this:
  528.      %union {
  529.        int intval;
  530.        double val;
  531.        symrec *tptr;
  532.      }
  533. then the code in `yylex' might look like this:
  534.        ...
  535.        yylval.intval = value; /* Put value onto Bison stack. */
  536.        return INT;          /* Return the type of the token. */
  537.        ...
  538. File: bison.info,  Node: Token Positions,  Next: Pure Calling,  Prev: Token Values,  Up: Lexical
  539. Textual Positions of Tokens
  540. ---------------------------
  541.    If you are using the `@N'-feature (*note Special Features for Use in
  542. Actions: Action Features.) in actions to keep track of the textual
  543. locations of tokens and groupings, then you must provide this
  544. information in `yylex'.  The function `yyparse' expects to find the
  545. textual location of a token just parsed in the global variable
  546. `yylloc'.  So `yylex' must store the proper data in that variable.  The
  547. value of `yylloc' is a structure and you need only initialize the
  548. members that are going to be used by the actions.  The four members are
  549. called `first_line', `first_column', `last_line' and `last_column'.
  550. Note that the use of this feature makes the parser noticeably slower.
  551.    The data type of `yylloc' has the name `YYLTYPE'.
  552. File: bison.info,  Node: Pure Calling,  Prev: Token Positions,  Up: Lexical
  553. Calling Conventions for Pure Parsers
  554. ------------------------------------
  555.    When you use the Bison declaration `%pure_parser' to request a pure,
  556. reentrant parser, the global communication variables `yylval' and
  557. `yylloc' cannot be used.  (*Note A Pure (Reentrant) Parser: Pure Decl.)
  558. In such parsers the two global variables are replaced by pointers
  559. passed as arguments to `yylex'.  You must declare them as shown here,
  560. and pass the information back by storing it through those pointers.
  561.      yylex (lvalp, llocp)
  562.           YYSTYPE *lvalp;
  563.           YYLTYPE *llocp;
  564.      {
  565.        ...
  566.        *lvalp = value;  /* Put value onto Bison stack.  */
  567.        return INT;      /* Return the type of the token.  */
  568.        ...
  569.      }
  570.    If the grammar file does not use the `@' constructs to refer to
  571. textual positions, then the type `YYLTYPE' will not be defined.  In
  572. this case, omit the second argument; `yylex' will be called with only
  573. one argument.
  574.    If you use a reentrant parser, you can optionally pass additional
  575. parameter information to it in a reentrant way.  To do so, define the
  576. macro `YYPARSE_PARAM' as a variable name.  This modifies the `yyparse'
  577. function to accept one argument, of type `void *', with that name.
  578.    When you call `yyparse', pass the address of an object, casting the
  579. address to `void *'.  The grammar actions can refer to the contents of
  580. the object by casting the pointer value back to its proper type and
  581. then dereferencing it.  Here's an example.  Write this in the parser:
  582.      %{
  583.      struct parser_control
  584.      {
  585.        int nastiness;
  586.        int randomness;
  587.      };
  588.      
  589.      #define YYPARSE_PARAM parm
  590.      %}
  591. Then call the parser like this:
  592.      struct parser_control
  593.      {
  594.        int nastiness;
  595.        int randomness;
  596.      };
  597.      
  598.      ...
  599.      
  600.      {
  601.        struct parser_control foo;
  602.        ...  /* Store proper data in `foo'.  */
  603.        value = yyparse ((void *) &foo);
  604.        ...
  605.      }
  606. In the grammar actions, use expressions like this to refer to the data:
  607.      ((struct parser_control *) parm)->randomness
  608.    If you wish to pass the additional parameter data to `yylex', define
  609. the macro `YYLEX_PARAM' just like `YYPARSE_PARAM', as shown here:
  610.      %{
  611.      struct parser_control
  612.      {
  613.        int nastiness;
  614.        int randomness;
  615.      };
  616.      
  617.      #define YYPARSE_PARAM parm
  618.      #define YYLEX_PARAM parm
  619.      %}
  620.    You should then define `yylex' to accept one additional
  621. argument--the value of `parm'.  (This makes either two or three
  622. arguments in total, depending on whether an argument of type `YYLTYPE'
  623. is passed.)  You can declare the argument as a pointer to the proper
  624. object type, or you can declare it as `void *' and access the contents
  625. as shown above.
  626.    You can use `%pure_parser' to request a reentrant parser without
  627. also using `YYPARSE_PARAM'.  Then you should call `yyparse' with no
  628. arguments, as usual.
  629. File: bison.info,  Node: Error Reporting,  Next: Action Features,  Prev: Lexical,  Up: Interface
  630. The Error Reporting Function `yyerror'
  631. ======================================
  632.    The Bison parser detects a "parse error" or "syntax error" whenever
  633. it reads a token which cannot satisfy any syntax rule.  A action in the
  634. grammar can also explicitly proclaim an error, using the macro
  635. `YYERROR' (*note Special Features for Use in Actions: Action Features.).
  636.    The Bison parser expects to report the error by calling an error
  637. reporting function named `yyerror', which you must supply.  It is
  638. called by `yyparse' whenever a syntax error is found, and it receives
  639. one argument.  For a parse error, the string is normally
  640. `"parse error"'.
  641.    If you define the macro `YYERROR_VERBOSE' in the Bison declarations
  642. section (*note The Bison Declarations Section: Bison Declarations.),
  643. then Bison provides a more verbose and specific error message string
  644. instead of just plain `"parse error"'.  It doesn't matter what
  645. definition you use for `YYERROR_VERBOSE', just whether you define it.
  646.    The parser can detect one other kind of error: stack overflow.  This
  647. happens when the input contains constructions that are very deeply
  648. nested.  It isn't likely you will encounter this, since the Bison
  649. parser extends its stack automatically up to a very large limit.  But
  650. if overflow happens, `yyparse' calls `yyerror' in the usual fashion,
  651. except that the argument string is `"parser stack overflow"'.
  652.    The following definition suffices in simple programs:
  653.      yyerror (s)
  654.           char *s;
  655.      {
  656.        fprintf (stderr, "%s\n", s);
  657.      }
  658.    After `yyerror' returns to `yyparse', the latter will attempt error
  659. recovery if you have written suitable error recovery grammar rules
  660. (*note Error Recovery::.).  If recovery is impossible, `yyparse' will
  661. immediately return 1.
  662.    The variable `yynerrs' contains the number of syntax errors
  663. encountered so far.  Normally this variable is global; but if you
  664. request a pure parser (*note A Pure (Reentrant) Parser: Pure Decl.)
  665. then it is a local variable which only the actions can access.
  666. File: bison.info,  Node: Action Features,  Prev: Error Reporting,  Up: Interface
  667. Special Features for Use in Actions
  668. ===================================
  669.    Here is a table of Bison constructs, variables and macros that are
  670. useful in actions.
  671.      Acts like a variable that contains the semantic value for the
  672.      grouping made by the current rule.  *Note Actions::.
  673.      Acts like a variable that contains the semantic value for the Nth
  674.      component of the current rule.  *Note Actions::.
  675. `$<TYPEALT>$'
  676.      Like `$$' but specifies alternative TYPEALT in the union specified
  677.      by the `%union' declaration.  *Note Data Types of Values in
  678.      Actions: Action Types.
  679. `$<TYPEALT>N'
  680.      Like `$N' but specifies alternative TYPEALT in the union specified
  681.      by the `%union' declaration.  *Note Data Types of Values in
  682.      Actions: Action Types.
  683. `YYABORT;'
  684.      Return immediately from `yyparse', indicating failure.  *Note The
  685.      Parser Function `yyparse': Parser Function.
  686. `YYACCEPT;'
  687.      Return immediately from `yyparse', indicating success.  *Note The
  688.      Parser Function `yyparse': Parser Function.
  689. `YYBACKUP (TOKEN, VALUE);'
  690.      Unshift a token.  This macro is allowed only for rules that reduce
  691.      a single value, and only when there is no look-ahead token.  It
  692.      installs a look-ahead token with token type TOKEN and semantic
  693.      value VALUE; then it discards the value that was going to be
  694.      reduced by this rule.
  695.      If the macro is used when it is not valid, such as when there is a
  696.      look-ahead token already, then it reports a syntax error with a
  697.      message `cannot back up' and performs ordinary error recovery.
  698.      In either case, the rest of the action is not executed.
  699. `YYEMPTY'
  700.      Value stored in `yychar' when there is no look-ahead token.
  701. `YYERROR;'
  702.      Cause an immediate syntax error.  This statement initiates error
  703.      recovery just as if the parser itself had detected an error;
  704.      however, it does not call `yyerror', and does not print any
  705.      message.  If you want to print an error message, call `yyerror'
  706.      explicitly before the `YYERROR;' statement.  *Note Error
  707.      Recovery::.
  708. `YYRECOVERING'
  709.      This macro stands for an expression that has the value 1 when the
  710.      parser is recovering from a syntax error, and 0 the rest of the
  711.      time.  *Note Error Recovery::.
  712. `yychar'
  713.      Variable containing the current look-ahead token.  (In a pure
  714.      parser, this is actually a local variable within `yyparse'.)  When
  715.      there is no look-ahead token, the value `YYEMPTY' is stored in the
  716.      variable.  *Note Look-Ahead Tokens: Look-Ahead.
  717. `yyclearin;'
  718.      Discard the current look-ahead token.  This is useful primarily in
  719.      error rules.  *Note Error Recovery::.
  720. `yyerrok;'
  721.      Resume generating error messages immediately for subsequent syntax
  722.      errors.  This is useful primarily in error rules.  *Note Error
  723.      Recovery::.
  724.      Acts like a structure variable containing information on the line
  725.      numbers and column numbers of the Nth component of the current
  726.      rule.  The structure has four members, like this:
  727.           struct {
  728.             int first_line, last_line;
  729.             int first_column, last_column;
  730.           };
  731.      Thus, to get the starting line number of the third component, use
  732.      `@3.first_line'.
  733.      In order for the members of this structure to contain valid
  734.      information, you must make `yylex' supply this information about
  735.      each token.  If you need only certain members, then `yylex' need
  736.      only fill in those members.
  737.      The use of this feature makes the parser noticeably slower.
  738. File: bison.info,  Node: Algorithm,  Next: Error Recovery,  Prev: Interface,  Up: Top
  739. The Bison Parser Algorithm
  740. **************************
  741.    As Bison reads tokens, it pushes them onto a stack along with their
  742. semantic values.  The stack is called the "parser stack".  Pushing a
  743. token is traditionally called "shifting".
  744.    For example, suppose the infix calculator has read `1 + 5 *', with a
  745. `3' to come.  The stack will have four elements, one for each token
  746. that was shifted.
  747.    But the stack does not always have an element for each token read.
  748. When the last N tokens and groupings shifted match the components of a
  749. grammar rule, they can be combined according to that rule.  This is
  750. called "reduction".  Those tokens and groupings are replaced on the
  751. stack by a single grouping whose symbol is the result (left hand side)
  752. of that rule.  Running the rule's action is part of the process of
  753. reduction, because this is what computes the semantic value of the
  754. resulting grouping.
  755.    For example, if the infix calculator's parser stack contains this:
  756.      1 + 5 * 3
  757. and the next input token is a newline character, then the last three
  758. elements can be reduced to 15 via the rule:
  759.      expr: expr '*' expr;
  760. Then the stack contains just these three elements:
  761.      1 + 15
  762. At this point, another reduction can be made, resulting in the single
  763. value 16.  Then the newline token can be shifted.
  764.    The parser tries, by shifts and reductions, to reduce the entire
  765. input down to a single grouping whose symbol is the grammar's
  766. start-symbol (*note Languages and Context-Free Grammars: Language and
  767. Grammar.).
  768.    This kind of parser is known in the literature as a bottom-up parser.
  769. * Menu:
  770. * Look-Ahead::        Parser looks one token ahead when deciding what to do.
  771. * Shift/Reduce::      Conflicts: when either shifting or reduction is valid.
  772. * Precedence::        Operator precedence works by resolving conflicts.
  773. * Contextual Precedence::  When an operator's precedence depends on context.
  774. * Parser States::     The parser is a finite-state-machine with stack.
  775. * Reduce/Reduce::     When two rules are applicable in the same situation.
  776. * Mystery Conflicts::  Reduce/reduce conflicts that look unjustified.
  777. * Stack Overflow::    What happens when stack gets full.  How to avoid it.
  778. File: bison.info,  Node: Look-Ahead,  Next: Shift/Reduce,  Up: Algorithm
  779. Look-Ahead Tokens
  780. =================
  781.    The Bison parser does *not* always reduce immediately as soon as the
  782. last N tokens and groupings match a rule.  This is because such a
  783. simple strategy is inadequate to handle most languages.  Instead, when a
  784. reduction is possible, the parser sometimes "looks ahead" at the next
  785. token in order to decide what to do.
  786.    When a token is read, it is not immediately shifted; first it
  787. becomes the "look-ahead token", which is not on the stack.  Now the
  788. parser can perform one or more reductions of tokens and groupings on
  789. the stack, while the look-ahead token remains off to the side.  When no
  790. more reductions should take place, the look-ahead token is shifted onto
  791. the stack.  This does not mean that all possible reductions have been
  792. done; depending on the token type of the look-ahead token, some rules
  793. may choose to delay their application.
  794.    Here is a simple case where look-ahead is needed.  These three rules
  795. define expressions which contain binary addition operators and postfix
  796. unary factorial operators (`!'), and allow parentheses for grouping.
  797.      expr:     term '+' expr
  798.              | term
  799.              ;
  800.      
  801.      term:     '(' expr ')'
  802.              | term '!'
  803.              | NUMBER
  804.              ;
  805.    Suppose that the tokens `1 + 2' have been read and shifted; what
  806. should be done?  If the following token is `)', then the first three
  807. tokens must be reduced to form an `expr'.  This is the only valid
  808. course, because shifting the `)' would produce a sequence of symbols
  809. `term ')'', and no rule allows this.
  810.    If the following token is `!', then it must be shifted immediately so
  811. that `2 !' can be reduced to make a `term'.  If instead the parser were
  812. to reduce before shifting, `1 + 2' would become an `expr'.  It would
  813. then be impossible to shift the `!' because doing so would produce on
  814. the stack the sequence of symbols `expr '!''.  No rule allows that
  815. sequence.
  816.    The current look-ahead token is stored in the variable `yychar'.
  817. *Note Special Features for Use in Actions: Action Features.
  818. File: bison.info,  Node: Shift/Reduce,  Next: Precedence,  Prev: Look-Ahead,  Up: Algorithm
  819. Shift/Reduce Conflicts
  820. ======================
  821.    Suppose we are parsing a language which has if-then and if-then-else
  822. statements, with a pair of rules like this:
  823.      if_stmt:
  824.                IF expr THEN stmt
  825.              | IF expr THEN stmt ELSE stmt
  826.              ;
  827. Here we assume that `IF', `THEN' and `ELSE' are terminal symbols for
  828. specific keyword tokens.
  829.    When the `ELSE' token is read and becomes the look-ahead token, the
  830. contents of the stack (assuming the input is valid) are just right for
  831. reduction by the first rule.  But it is also legitimate to shift the
  832. `ELSE', because that would lead to eventual reduction by the second
  833. rule.
  834.    This situation, where either a shift or a reduction would be valid,
  835. is called a "shift/reduce conflict".  Bison is designed to resolve
  836. these conflicts by choosing to shift, unless otherwise directed by
  837. operator precedence declarations.  To see the reason for this, let's
  838. contrast it with the other alternative.
  839.    Since the parser prefers to shift the `ELSE', the result is to attach
  840. the else-clause to the innermost if-statement, making these two inputs
  841. equivalent:
  842.      if x then if y then win (); else lose;
  843.      
  844.      if x then do; if y then win (); else lose; end;
  845.    But if the parser chose to reduce when possible rather than shift,
  846. the result would be to attach the else-clause to the outermost
  847. if-statement, making these two inputs equivalent:
  848.      if x then if y then win (); else lose;
  849.      
  850.      if x then do; if y then win (); end; else lose;
  851.    The conflict exists because the grammar as written is ambiguous:
  852. either parsing of the simple nested if-statement is legitimate.  The
  853. established convention is that these ambiguities are resolved by
  854. attaching the else-clause to the innermost if-statement; this is what
  855. Bison accomplishes by choosing to shift rather than reduce.  (It would
  856. ideally be cleaner to write an unambiguous grammar, but that is very
  857. hard to do in this case.) This particular ambiguity was first
  858. encountered in the specifications of Algol 60 and is called the
  859. "dangling `else'" ambiguity.
  860.    To avoid warnings from Bison about predictable, legitimate
  861. shift/reduce conflicts, use the `%expect N' declaration.  There will be
  862. no warning as long as the number of shift/reduce conflicts is exactly N.
  863. *Note Suppressing Conflict Warnings: Expect Decl.
  864.    The definition of `if_stmt' above is solely to blame for the
  865. conflict, but the conflict does not actually appear without additional
  866. rules.  Here is a complete Bison input file that actually manifests the
  867. conflict:
  868.      %token IF THEN ELSE variable
  869.      %%
  870.      stmt:     expr
  871.              | if_stmt
  872.              ;
  873.      
  874.      if_stmt:
  875.                IF expr THEN stmt
  876.              | IF expr THEN stmt ELSE stmt
  877.              ;
  878.      
  879.      expr:     variable
  880.              ;
  881. File: bison.info,  Node: Precedence,  Next: Contextual Precedence,  Prev: Shift/Reduce,  Up: Algorithm
  882. Operator Precedence
  883. ===================
  884.    Another situation where shift/reduce conflicts appear is in
  885. arithmetic expressions.  Here shifting is not always the preferred
  886. resolution; the Bison declarations for operator precedence allow you to
  887. specify when to shift and when to reduce.
  888. * Menu:
  889. * Why Precedence::    An example showing why precedence is needed.
  890. * Using Precedence::  How to specify precedence in Bison grammars.
  891. * Precedence Examples::  How these features are used in the previous example.
  892. * How Precedence::    How they work.
  893. File: bison.info,  Node: Why Precedence,  Next: Using Precedence,  Up: Precedence
  894. When Precedence is Needed
  895. -------------------------
  896.    Consider the following ambiguous grammar fragment (ambiguous because
  897. the input `1 - 2 * 3' can be parsed in two different ways):
  898.      expr:     expr '-' expr
  899.              | expr '*' expr
  900.              | expr '<' expr
  901.              | '(' expr ')'
  902.              ...
  903.              ;
  904. Suppose the parser has seen the tokens `1', `-' and `2'; should it
  905. reduce them via the rule for the addition operator?  It depends on the
  906. next token.  Of course, if the next token is `)', we must reduce;
  907. shifting is invalid because no single rule can reduce the token
  908. sequence `- 2 )' or anything starting with that.  But if the next token
  909. is `*' or `<', we have a choice: either shifting or reduction would
  910. allow the parse to complete, but with different results.
  911.    To decide which one Bison should do, we must consider the results.
  912. If the next operator token OP is shifted, then it must be reduced first
  913. in order to permit another opportunity to reduce the sum.  The result
  914. is (in effect) `1 - (2 OP 3)'.  On the other hand, if the subtraction
  915. is reduced before shifting OP, the result is `(1 - 2) OP 3'.  Clearly,
  916. then, the choice of shift or reduce should depend on the relative
  917. precedence of the operators `-' and OP: `*' should be shifted first,
  918. but not `<'.
  919.    What about input such as `1 - 2 - 5'; should this be `(1 - 2) - 5'
  920. or should it be `1 - (2 - 5)'?  For most operators we prefer the
  921. former, which is called "left association".  The latter alternative,
  922. "right association", is desirable for assignment operators.  The choice
  923. of left or right association is a matter of whether the parser chooses
  924. to shift or reduce when the stack contains `1 - 2' and the look-ahead
  925. token is `-': shifting makes right-associativity.
  926. File: bison.info,  Node: Using Precedence,  Next: Precedence Examples,  Prev: Why Precedence,  Up: Precedence
  927. Specifying Operator Precedence
  928. ------------------------------
  929.    Bison allows you to specify these choices with the operator
  930. precedence declarations `%left' and `%right'.  Each such declaration
  931. contains a list of tokens, which are operators whose precedence and
  932. associativity is being declared.  The `%left' declaration makes all
  933. those operators left-associative and the `%right' declaration makes
  934. them right-associative.  A third alternative is `%nonassoc', which
  935. declares that it is a syntax error to find the same operator twice "in a
  936. row".
  937.    The relative precedence of different operators is controlled by the
  938. order in which they are declared.  The first `%left' or `%right'
  939. declaration in the file declares the operators whose precedence is
  940. lowest, the next such declaration declares the operators whose
  941. precedence is a little higher, and so on.
  942. File: bison.info,  Node: Precedence Examples,  Next: How Precedence,  Prev: Using Precedence,  Up: Precedence
  943. Precedence Examples
  944. -------------------
  945.    In our example, we would want the following declarations:
  946.      %left '<'
  947.      %left '-'
  948.      %left '*'
  949.    In a more complete example, which supports other operators as well,
  950. we would declare them in groups of equal precedence.  For example,
  951. `'+'' is declared with `'-'':
  952.      %left '<' '>' '=' NE LE GE
  953.      %left '+' '-'
  954.      %left '*' '/'
  955. (Here `NE' and so on stand for the operators for "not equal" and so on.
  956. We assume that these tokens are more than one character long and
  957. therefore are represented by names, not character literals.)
  958. File: bison.info,  Node: How Precedence,  Prev: Precedence Examples,  Up: Precedence
  959. How Precedence Works
  960. --------------------
  961.    The first effect of the precedence declarations is to assign
  962. precedence levels to the terminal symbols declared.  The second effect
  963. is to assign precedence levels to certain rules: each rule gets its
  964. precedence from the last terminal symbol mentioned in the components.
  965. (You can also specify explicitly the precedence of a rule.  *Note
  966. Context-Dependent Precedence: Contextual Precedence.)
  967.    Finally, the resolution of conflicts works by comparing the
  968. precedence of the rule being considered with that of the look-ahead
  969. token.  If the token's precedence is higher, the choice is to shift.
  970. If the rule's precedence is higher, the choice is to reduce.  If they
  971. have equal precedence, the choice is made based on the associativity of
  972. that precedence level.  The verbose output file made by `-v' (*note
  973. Invoking Bison: Invocation.) says how each conflict was resolved.
  974.    Not all rules and not all tokens have precedence.  If either the
  975. rule or the look-ahead token has no precedence, then the default is to
  976. shift.
  977.