X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/3cdc21cfd78fad8bfa885034f7a92c563deefbc5..8bb3a2e7dfd705ff7cb78fb12028557a92b4feaf:/doc/bison.texinfo?ds=inline

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index e38bfa56..ab2cd6c5 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -206,6 +206,7 @@ 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.
+* Named References::  Using named references in actions.
 
 Tracking Locations
 
@@ -352,9 +353,10 @@ Copying This Manual
 @cindex introduction
 
 @dfn{Bison} is a general-purpose parser generator that converts an
-annotated context-free grammar into a deterministic or @acronym{GLR}
-parser employing @acronym{LALR}(1), @acronym{IELR}(1), or canonical
-@acronym{LR}(1) parser tables.
+annotated context-free grammar into a deterministic @acronym{LR} or
+generalized @acronym{LR} (@acronym{GLR}) parser employing
+@acronym{LALR}(1), @acronym{IELR}(1), or canonical @acronym{LR}(1)
+parser tables.
 Once you are proficient with Bison, you can use it to develop a wide
 range of language parsers, from those used in simple desk calculators to
 complex programming languages.
@@ -3367,6 +3369,7 @@ 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.
+* Named References::  Using named references in actions.
 @end menu
 
 @node Value Type
@@ -3428,6 +3431,8 @@ Decl, ,Nonterminal Symbols}).
 @cindex action
 @vindex $$
 @vindex $@var{n}
+@vindex $@var{name}
+@vindex $[@var{name}]
 
 An action accompanies a syntactic rule and contains C code to be executed
 each time an instance of that rule is recognized.  The task of most actions
@@ -3444,9 +3449,12 @@ Actions, ,Actions in Mid-Rule}).
 The C code in an action can refer to the semantic values of the components
 matched by the rule with the construct @code{$@var{n}}, which stands for
 the value of the @var{n}th component.  The semantic value for the grouping
-being constructed is @code{$$}.  Bison translates both of these
+being constructed is @code{$$}.  In addition, the semantic values of
+symbols can be accessed with the named references construct
+@code{$@var{name}} or @code{$[@var{name}]}.  Bison translates both of these
 constructs into expressions of the appropriate type when it copies the
-actions into the parser file.  @code{$$} is translated to a modifiable
+actions into the parser file.  @code{$$} (or @code{$@var{name}}, when it
+stands for the current grouping) is translated to a modifiable
 lvalue, so it can be assigned to.
 
 Here is a typical example:
@@ -3459,16 +3467,31 @@ exp:    @dots{}
 @end group
 @end example
 
+Or, in terms of named references:
+
+@example
+@group
+exp[result]:    @dots{}
+        | exp[left] '+' exp[right]
+            @{ $result = $left + $right; @}
+@end group
+@end example
+
 @noindent
 This rule constructs an @code{exp} from two smaller @code{exp} groupings
 connected by a plus-sign token.  In the action, @code{$1} and @code{$3}
+(@code{$left} and @code{$right})
 refer to the semantic values of the two component @code{exp} groupings,
 which are the first and third symbols on the right hand side of the rule.
-The sum is stored into @code{$$} so that it becomes the semantic value of
+The sum is stored into @code{$$} (@code{$result}) so that it becomes the
+semantic value of
 the addition-expression just recognized by the rule.  If there were a
 useful semantic value associated with the @samp{+} token, it could be
 referred to as @code{$2}.
 
+@xref{Named References,,Using Named References}, for more information
+about using the named references construct.
+
 Note that the vertical-bar character @samp{|} is really a rule
 separator, and actions are attached to a single rule.  This is a
 difference with tools like Flex, for which @samp{|} stands for either
@@ -3763,6 +3786,93 @@ 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.
 
+@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
@@ -3818,6 +3928,8 @@ Action Decl, , Performing Actions before Parsing}.
 @cindex actions, location
 @vindex @@$
 @vindex @@@var{n}
+@vindex @@@var{name}
+@vindex @@[@var{name}]
 
 Actions are not only useful for defining language semantics, but also for
 describing the behavior of the output parser with locations.
@@ -3829,6 +3941,11 @@ The location of the @var{n}th component of the right hand side is
 @code{@@@var{n}}, while the location of the left hand side grouping is
 @code{@@$}.
 
+In addition, the named references construct @code{@@@var{name}} and
+@code{@@[@var{name}]} may also be used to address the symbol locations.
+@xref{Named References,,Using Named References}, for more information
+about using the named references construct.
+
 Here is a basic example using the default data type for locations:
 
 @example
@@ -8617,7 +8734,7 @@ alias analysis must be disabled}.  Use the option
 There might be portability issues we are not aware of.
 @end itemize
 
-As far as we know, these limitations \emph{can} be alleviated.  All it takes
+As far as we know, these limitations @emph{can} be alleviated.  All it takes
 is some time and/or some talented C++ hacker willing to contribute to Bison.
 
 @node C++ Location Values
@@ -9113,7 +9230,7 @@ definition of ``symbol'', we enable @code{lex_symbol}.
 @findex %code requires
 Then come the declarations/inclusions needed by the semantic values.
 Because the parser uses the parsing driver and reciprocally, both would like
-to include the header of the other, which is, of course, insane.  These
+to include the header of the other, which is, of course, insane.  This
 mutual dependency will be broken using forward declarations.  Because the
 driver's header needs detailed knowledge about the parser class (in
 particular its inner types), it is the parser's header which will use a
@@ -9249,9 +9366,9 @@ exp:
 | exp "-" exp   @{ $$ = $1 - $3; @}
 | exp "*" exp   @{ $$ = $1 * $3; @}
 | exp "/" exp   @{ $$ = $1 / $3; @}
-| "(" exp ")"   @{ std::swap($$, $2); @}
+| "(" exp ")"   @{ std::swap ($$, $2); @}
 | "identifier"  @{ $$ = driver.variables[$1]; @}
-| "number"      @{ std::swap($$, $1); @};
+| "number"      @{ std::swap ($$, $1); @};
 %%
 @end example
 
@@ -9808,11 +9925,6 @@ Start error recovery without printing an error message.
 @xref{Error Recovery}.
 @end deffn
 
-@deffn {Statement} {return YYFAIL;}
-Print an error message and start error recovery.
-@xref{Error Recovery}.
-@end deffn
-
 @deftypefn {Function} {boolean} recovering ()
 Return whether error recovery is being done. In this state, the parser
 reads token until it reaches a known state, and then restarts normal
@@ -10446,6 +10558,16 @@ In an action, the location of the @var{n}-th symbol of the right-hand
 side of the rule.  @xref{Locations, , Locations Overview}.
 @end deffn
 
+@deffn {Variable} @@@var{name}
+In an action, the location of a symbol addressed by name.
+@xref{Locations, , Locations Overview}.
+@end deffn
+
+@deffn {Variable} @@[@var{name}]
+In an action, the location of a symbol addressed by name.
+@xref{Locations, , Locations Overview}.
+@end deffn
+
 @deffn {Variable} $$
 In an action, the semantic value of the left-hand side of the rule.
 @xref{Actions}.
@@ -10456,6 +10578,16 @@ In an action, the semantic value of the @var{n}-th symbol of the
 right-hand side of the rule.  @xref{Actions}.
 @end deffn
 
+@deffn {Variable} $@var{name}
+In an action, the semantic value of a symbol addressed by name.
+@xref{Actions}.
+@end deffn
+
+@deffn {Variable} $[@var{name}]
+In an action, the semantic value of a symbol addressed by name.
+@xref{Actions}.
+@end deffn
+
 @deffn {Delimiter} %%
 Delimiter used to separate the grammar rule section from the
 Bison declarations section or the epilogue.
@@ -11193,5 +11325,5 @@ grammatically indivisible.  The piece of text it represents is a token.
 @c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv
 @c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url
 @c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
-@c LocalWords: getLVal defvar YYFAIL deftypefn deftypefnx gotos msgfmt
+@c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt
 @c LocalWords: subdirectory Solaris nonassociativity