From 2e5f39c22cf659a8a79ebedc84e9636f198c21ab Mon Sep 17 00:00:00 2001 From: Alex Rozenman Date: Sat, 14 Nov 2009 22:06:26 +0200 Subject: [PATCH] Document named references. * doc/bison.texinfo (Actions): Add new example and xref to Using Named References node. (Using Named References): New node. --- ChangeLog | 7 +++ doc/bison.texinfo | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 117 insertions(+), 3 deletions(-) diff --git a/ChangeLog b/ChangeLog index b1425e3..672f12f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2009-10-03 Alex Rozenman + + Document named references. + * doc/bison.texinfo (Actions): Add new example and xref to + Using Named References node. + (Using Named References): New node. + 2009-10-16 Joel E. Denny cleanup. diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 651645d..a8036f0 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 @@ -3367,6 +3368,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 @@ -3444,9 +3446,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 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 current grouping) is translated to a modifiable lvalue, so it can be assigned to. Here is a typical example: @@ -3459,16 +3464,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 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 +3783,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 symbol names may be used. +Explicit symbol 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 symbol 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 symbol 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] '+' @{$$ = $x;@}[left] exp[right] + @{ $$ = $left + $right; @} +@end group +@end example + +@noindent + +In order to access symbol 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 @code{$name} symbol followed by +@code{.suffix}, i.e., an access to the @code{suffix} field of the semantic +value. In order to force Bison to resolve a named reference as a +reference to a symbol having the format @code{name.suffix}, bracketed +syntax @code{$[name.suffix]} must be used. + + @node Locations @section Tracking Locations @cindex location -- 1.6.2.5