doc: discuss named references after locations.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index b226726e918405ea4be32531a6a567890b8e598a..8fdac074ae066d11ce0fe3833d178dcd631b3e90 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -186,6 +186,7 @@ Bison Grammar Files
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.

+* Named References::  Using named references in actions.

 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 


@@ -206,7 +207,6 @@ Defining Language Semantics
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.

-* Named References::  Using named references in actions.

 
 Tracking Locations
 
 
 Tracking Locations
 


@@ -264,7 +264,7 @@ The Bison Parser Algorithm
 * Contextual Precedence::  When an operator's precedence depends on context.
 * Parser States::     The parser is a finite-state-machine with stack.
 * Reduce/Reduce::     When two rules are applicable in the same situation.
 * Contextual Precedence::  When an operator's precedence depends on context.
 * Parser States::     The parser is a finite-state-machine with stack.
 * Reduce/Reduce::     When two rules are applicable in the same situation.

-* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
+* Mysterious Conflicts:: Conflicts that look unjustified.

 * Tuning LR::         How to tune fundamental aspects of LR-based parsing.
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.
 * Tuning LR::         How to tune fundamental aspects of LR-based parsing.
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.


@@ -488,10 +488,10 @@ are called LR(1) grammars.  In brief, in these grammars, it must be possible
 to tell how to parse any portion of an input string with just a single token
 of lookahead.  For historical reasons, Bison by default is limited by the
 additional restrictions of LALR(1), which is hard to explain simply.
 to tell how to parse any portion of an input string with just a single token
 of lookahead.  For historical reasons, Bison by default is limited by the
 additional restrictions of LALR(1), which is hard to explain simply.

-@xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}, for more
-information on this.  As an experimental feature, you can escape these
-additional restrictions by requesting IELR(1) or canonical LR(1) parser
-tables.  @xref{LR Table Construction}, to learn how.
+@xref{Mysterious Conflicts}, for more information on this.  As an
+experimental feature, you can escape these additional restrictions by
+requesting IELR(1) or canonical LR(1) parser tables.  @xref{LR Table
+Construction}, to learn how.

 
 @cindex GLR parsing
 @cindex generalized LR (GLR) parsing
 
 @cindex GLR parsing
 @cindex generalized LR (GLR) parsing


@@ -2627,6 +2627,7 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.

+* Named References::  Using named references in actions.

 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 @end menu
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 @end menu


@@ -3388,7 +3389,6 @@ the numbers associated with @var{x} and @var{y}.
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.

-* Named References::  Using named references in actions.

 @end menu
 
 @node Value Type
 @end menu
 
 @node Value Type


@@ -3806,93 +3806,6 @@ compound: subroutine
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 

-@node Named References
-@subsection Using Named References
-@cindex named references
-
-While every semantic value can be accessed with positional references
-@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
-them by name.  First of all, original symbol names may be used as named
-references.  For example:
-
-@example
-@group
-invocation: op '(' args ')'
-  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
-@end group
-@end example
-
-@noindent
-The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
-mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
-
-@example
-@group
-invocation: op '(' args ')'
-  @{ $$ = new_invocation ($op, $args, @@$); @}
-@end group
-@end example
-
-@noindent
-However, sometimes regular symbol names are not sufficient due to
-ambiguities:
-
-@example
-@group
-exp: exp '/' exp
-  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $3; @} // No error.
-@end group
-@end example
-
-@noindent
-When ambiguity occurs, explicitly declared names may be used for values and
-locations.  Explicit names are declared as a bracketed name after a symbol
-appearance in rule definitions.  For example:
-@example
-@group
-exp[result]: exp[left] '/' exp[right]
-  @{ $result = $left / $right; @}
-@end group
-@end example
-
-@noindent
-Explicit names may be declared for RHS and for LHS symbols as well.  In order
-to access a semantic value generated by a mid-rule action, an explicit name
-may also be declared by putting a bracketed name after the closing brace of
-the mid-rule action code:
-@example
-@group
-exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
-  @{ $res = $left + $right; @}
-@end group
-@end example
-
-@noindent
-
-In references, in order to specify names containing dots and dashes, an explicit
-bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
-@example
-@group
-if-stmt: IF '(' expr ')' THEN then.stmt ';'
-  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
-@end group
-@end example
-
-It often happens that named references are followed by a dot, dash or other
-C punctuation marks and operators.  By default, Bison will read
-@code{$name.suffix} as a reference to symbol value @code{$name} followed by
-@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
-value.  In order to force Bison to recognize @code{name.suffix} in its entirety
-as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
-must be used.
-
-

 @node Locations
 @section Tracking Locations
 @cindex location
 @node Locations
 @section Tracking Locations
 @cindex location


@@ -4101,6 +4014,92 @@ macro should expand to something that can be used as a single
 statement when it is followed by a semicolon.
 @end itemize
 
 statement when it is followed by a semicolon.
 @end itemize
 

+@node Named References
+@section Using Named References
+@cindex named references
+
+While every semantic value can be accessed with positional references
+@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
+them by name.  First of all, original symbol names may be used as named
+references.  For example:
+
+@example
+@group
+invocation: op '(' args ')'
+  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
+@end group
+@end example
+
+@noindent
+The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
+mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
+
+@example
+@group
+invocation: op '(' args ')'
+  @{ $$ = new_invocation ($op, $args, @@$); @}
+@end group
+@end example
+
+@noindent
+However, sometimes regular symbol names are not sufficient due to
+ambiguities:
+
+@example
+@group
+exp: exp '/' exp
+  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $3; @} // No error.
+@end group
+@end example
+
+@noindent
+When ambiguity occurs, explicitly declared names may be used for values and
+locations.  Explicit names are declared as a bracketed name after a symbol
+appearance in rule definitions.  For example:
+@example
+@group
+exp[result]: exp[left] '/' exp[right]
+  @{ $result = $left / $right; @}
+@end group
+@end example
+
+@noindent
+Explicit names may be declared for RHS and for LHS symbols as well.  In order
+to access a semantic value generated by a mid-rule action, an explicit name
+may also be declared by putting a bracketed name after the closing brace of
+the mid-rule action code:
+@example
+@group
+exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
+  @{ $res = $left + $right; @}
+@end group
+@end example
+
+@noindent
+
+In references, in order to specify names containing dots and dashes, an explicit
+bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
+@example
+@group
+if-stmt: IF '(' expr ')' THEN then.stmt ';'
+  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
+@end group
+@end example
+
+It often happens that named references are followed by a dot, dash or other
+C punctuation marks and operators.  By default, Bison will read
+@code{$name.suffix} as a reference to symbol value @code{$name} followed by
+@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
+value.  In order to force Bison to recognize @code{name.suffix} in its entirety
+as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
+must be used.
+

 @node Declarations
 @section Bison Declarations
 @cindex declarations, Bison
 @node Declarations
 @section Bison Declarations
 @cindex declarations, Bison


@@ -5166,11 +5165,11 @@ contain default reductions.  @xref{Default Reductions}.  (The ability to
 specify where default reductions should be used is experimental.  More user
 feedback will help to stabilize it.)
 
 specify where default reductions should be used is experimental.  More user
 feedback will help to stabilize it.)
 

-@item Accepted Values: @code{all}, @code{consistent}, @code{accepting}
+@item Accepted Values: @code{most}, @code{consistent}, @code{accepting}

 @item Default Value:
 @itemize
 @item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
 @item Default Value:
 @itemize
 @item @code{accepting} if @code{lr.type} is @code{canonical-lr}.

-@item @code{all} otherwise.
+@item @code{most} otherwise.

 @end itemize
 @end itemize
 
 @end itemize
 @end itemize
 


@@ -6262,7 +6261,7 @@ This kind of parser is known in the literature as a bottom-up parser.
 * Contextual Precedence::  When an operator's precedence depends on context.
 * Parser States::     The parser is a finite-state-machine with stack.
 * Reduce/Reduce::     When two rules are applicable in the same situation.
 * Contextual Precedence::  When an operator's precedence depends on context.
 * Parser States::     The parser is a finite-state-machine with stack.
 * Reduce/Reduce::     When two rules are applicable in the same situation.

-* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
+* Mysterious Conflicts:: Conflicts that look unjustified.

 * Tuning LR::         How to tune fundamental aspects of LR-based parsing.
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.
 * Tuning LR::         How to tune fundamental aspects of LR-based parsing.
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.


@@ -6779,8 +6778,8 @@ redirects:redirect
         ;
 @end example
 
         ;
 @end example
 

-@node Mystery Conflicts
-@section Mysterious Reduce/Reduce Conflicts
+@node Mysterious Conflicts
+@section Mysterious Conflicts

 @cindex Mysterious Conflicts
 
 Sometimes reduce/reduce conflicts can occur that don't look warranted.
 @cindex Mysterious Conflicts
 
 Sometimes reduce/reduce conflicts can occur that don't look warranted.


@@ -6936,7 +6935,7 @@ user feedback will help to stabilize them.
 For historical reasons, Bison constructs LALR(1) parser tables by default.
 However, LALR does not possess the full language-recognition power of LR.
 As a result, the behavior of parsers employing LALR parser tables is often
 For historical reasons, Bison constructs LALR(1) parser tables by default.
 However, LALR does not possess the full language-recognition power of LR.
 As a result, the behavior of parsers employing LALR parser tables is often

-mysterious.  We presented a simple example of this effect in @ref{Mystery
+mysterious.  We presented a simple example of this effect in @ref{Mysterious

 Conflicts}.
 
 As we also demonstrated in that example, the traditional approach to
 Conflicts}.
 
 As we also demonstrated in that example, the traditional approach to


@@ -6971,7 +6970,7 @@ grammar file:
 %define lr.type ielr
 @end example
 
 %define lr.type ielr
 @end example
 

-@noindent For the example in @ref{Mystery Conflicts}, the mysterious
+@noindent For the example in @ref{Mysterious Conflicts}, the mysterious

 conflict is then eliminated, so there is no need to invest time in
 comprehending the conflict or restructuring the grammar to fix it.  If,
 during future development, the grammar evolves such that all mysterious
 conflict is then eliminated, so there is no need to invest time in
 comprehending the conflict or restructuring the grammar to fix it.  If,
 during future development, the grammar evolves such that all mysterious


@@ -7143,7 +7142,7 @@ To adjust which states have default reductions enabled, use the
 Specify the kind of states that are permitted to contain default reductions.
 The accepted values of @var{WHERE} are:
 @itemize
 Specify the kind of states that are permitted to contain default reductions.
 The accepted values of @var{WHERE} are:
 @itemize

-@item @code{all} (default for LALR and IELR)
+@item @code{most} (default for LALR and IELR)

 @item @code{consistent}
 @item @code{accepting} (default for canonical LR)
 @end itemize
 @item @code{consistent}
 @item @code{accepting} (default for canonical LR)
 @end itemize


@@ -7152,9 +7151,6 @@ The accepted values of @var{WHERE} are:
 experimental.  More user feedback will help to stabilize it.)
 @end deffn
 
 experimental.  More user feedback will help to stabilize it.)
 @end deffn
 

-FIXME: Because of the exceptions described above, @code{all} is a misnomer.
-Rename to @code{full}.
-

 @node LAC
 @subsection LAC
 @findex %define parse.lac
 @node LAC
 @subsection LAC
 @findex %define parse.lac


@@ -7259,6 +7255,10 @@ never physically copied.  In our experience, the performance penalty of LAC
 has proven insignificant for practical grammars.
 @end itemize
 
 has proven insignificant for practical grammars.
 @end itemize
 

+While the LAC algorithm shares techniques that have been recognized in the
+parser community for years, for the publication that introduces LAC,
+@pxref{Bibliography,,Denny 2010 May}.
+

 @node Unreachable States
 @subsection Unreachable States
 @findex %define lr.keep-unreachable-states
 @node Unreachable States
 @subsection Unreachable States
 @findex %define lr.keep-unreachable-states


@@ -7319,7 +7319,7 @@ sequence of reductions cannot have deterministic parsers in this sense.
 The same is true of languages that require more than one symbol of
 lookahead, since the parser lacks the information necessary to make a
 decision at the point it must be made in a shift-reduce parser.
 The same is true of languages that require more than one symbol of
 lookahead, since the parser lacks the information necessary to make a
 decision at the point it must be made in a shift-reduce parser.

-Finally, as previously mentioned (@pxref{Mystery Conflicts}),
+Finally, as previously mentioned (@pxref{Mysterious Conflicts}),

 there are languages where Bison's default choice of how to
 summarize the input seen so far loses necessary information.
 
 there are languages where Bison's default choice of how to
 summarize the input seen so far loses necessary information.
 


@@ -8425,10 +8425,24 @@ These warnings are not enabled by default since they sometimes prove to
 be false alarms in existing grammars employing the Yacc constructs
 @code{$0} or @code{$-@var{n}} (where @var{n} is some positive integer).
 
 be false alarms in existing grammars employing the Yacc constructs
 @code{$0} or @code{$-@var{n}} (where @var{n} is some positive integer).
 

-

 @item yacc
 Incompatibilities with POSIX Yacc.
 
 @item yacc
 Incompatibilities with POSIX Yacc.
 

+@item conflicts-sr
+@itemx conflicts-rr
+S/R and R/R conflicts.  These warnings are enabled by default.  However, if
+the @code{%expect} or @code{%expect-rr} directive is specified, an
+unexpected number of conflicts is an error, and an expected number of
+conflicts is not reported, so @option{-W} and @option{--warning} then have
+no effect on the conflict report.
+
+@item other
+All warnings not categorized above.  These warnings are enabled by default.
+
+This category is provided merely for the sake of completeness.  Future
+releases of Bison may move warnings from this category to new, more specific
+categories.
+

 @item all
 All the warnings.
 @item none
 @item all
 All the warnings.
 @item none


@@ -10970,7 +10984,7 @@ Tokens}.
 @item LALR(1)
 The class of context-free grammars that Bison (like most other parser
 generators) can handle by default; a subset of LR(1).
 @item LALR(1)
 The class of context-free grammars that Bison (like most other parser
 generators) can handle by default; a subset of LR(1).

-@xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}.
+@xref{Mysterious Conflicts}.

 
 @item LR(1)
 The class of context-free grammars in which at most one token of
 
 @item LR(1)
 The class of context-free grammars in which at most one token of