Simplify y.tab.c when location tracking is disabled.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 8f40afbee4e52833a2cba7d6160084859ebbc089..2af89175af4825bd7a4cdfa330fe8fd7e80dfffd 100644 (file)
--- 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.
 * 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
 


@@ -352,9 +353,10 @@ Copying This Manual
 @cindex introduction
 
 @dfn{Bison} is a general-purpose parser generator that converts an
 @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.
 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.
 * 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


@@ -3428,6 +3431,8 @@ Decl, ,Nonterminal Symbols}).
 @cindex action
 @vindex $$
 @vindex $@var{n}
 @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
 
 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
 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
 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:
 lvalue, so it can be assigned to.
 
 Here is a typical example:


@@ -3459,16 +3467,31 @@ exp:    @dots{}
 @end group
 @end example
 
 @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}
 @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.
 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}.
 
 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
 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.
 
 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


@@ -3818,6 +3928,8 @@ Action Decl, , Performing Actions before Parsing}.
 @cindex actions, location
 @vindex @@$
 @vindex @@@var{n}
 @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.
 
 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{@@$}.
 
 @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
 Here is a basic example using the default data type for locations:
 
 @example


@@ -9249,9 +9366,9 @@ exp:
 | exp "-" exp   @{ $$ = $1 - $3; @}
 | exp "*" exp   @{ $$ = $1 * $3; @}
 | exp "/" exp   @{ $$ = $1 / $3; @}
 | exp "-" exp   @{ $$ = $1 - $3; @}
 | exp "*" exp   @{ $$ = $1 * $3; @}
 | exp "/" exp   @{ $$ = $1 / $3; @}

-| "(" exp ")"   @{ std::swap($$, $2); @}
+| "(" exp ")"   @{ std::swap ($$, $2); @}

 | "identifier"  @{ $$ = driver.variables[$1]; @}
 | "identifier"  @{ $$ = driver.variables[$1]; @}

-| "number"      @{ std::swap($$, $1); @};
+| "number"      @{ std::swap ($$, $1); @};

 %%
 @end example
 
 %%
 @end example
 


@@ -10446,6 +10563,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
 
 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}.
 @deffn {Variable} $$
 In an action, the semantic value of the left-hand side of the rule.
 @xref{Actions}.


@@ -10456,6 +10583,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
 
 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.
 @deffn {Delimiter} %%
 Delimiter used to separate the grammar rule section from the
 Bison declarations section or the epilogue.