From: Joel E. Denny Date: Sun, 29 May 2011 23:59:44 +0000 (-0400) Subject: doc: discuss named references after locations. X-Git-Tag: v2.5.1_rc2~153 X-Git-Url: https://git.saurik.com/bison.git/commitdiff_plain/908c8647de654d4ab0944ecef7811af1d736742b doc: discuss named references after locations. Reported by Hans Aberg at . * NEWS (2.5.1): Document. * doc/bison.texinfo (Named References): Because it discusses locations in addition to semantic values, move this subsection out of the section `Defining Language Semantics', where locations have not yet been introduced, to be a new section after the following section, `Tracking Locations'. --- diff --git a/ChangeLog b/ChangeLog index 66ea5aeb..2bcb75d8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2011-05-29 Joel E. Denny + + doc: discuss named references after locations. + Reported by Hans Aberg at + . + * NEWS (2.5.1): Document. + * doc/bison.texinfo (Named References): Because it discusses + locations in addition to semantic values, move this subsection out + of the section `Defining Language Semantics', where locations have + not yet been introduced, to be a new section after the following + section, `Tracking Locations'. + 2011-05-29 Joel E. Denny Prepare for the possibility of a 2.5.1 release. diff --git a/NEWS b/NEWS index bc761162..f8479889 100644 --- a/NEWS +++ b/NEWS @@ -3,6 +3,8 @@ Bison News * Changes in version 2.5.1 (????-??-??): +** Minor improvements have been made to the manual. + * Changes in version 2.5 (2011-05-14): ** Grammar symbol names can now contain non-initial dashes: diff --git a/doc/bison.texinfo b/doc/bison.texinfo index e0d5aa5b..8fdac074 100644 --- 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. +* 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. @@ -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. -* Named References:: Using named references in actions. Tracking Locations @@ -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. +* 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 @@ -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. -* Named References:: Using named references in actions. @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. -@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 @@ -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 +@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