commit d013372c3fe11e99525713dcdfd1b098f0f909e2 Author: Alex Rozenman Date: Sat Nov 14 22:06:26 2009 +0200 Document named references. * doc/bison.texinfo (Actions): Add new example and xref to Using Named References node. (Using Named References): New node. 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..8cb3861 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 @@ -3428,6 +3430,8 @@ Decl, ,Nonterminal Symbols}). @cindex action @vindex $$ @vindex address@hidden address@hidden address@hidden address@hidden address@hidden 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 +3448,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 @address@hidden, 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 address@hidden@var{name}} or @address@hidden 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 @address@hidden, 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 +3466,31 @@ exp: @dots{} @end group @end example +Or, in terms of named references: + address@hidden address@hidden +exp[result]: @dots{} + | exp[left] '+' exp[right] + @{ $result = $left + $right; @} address@hidden group address@hidden 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}. address@hidden 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 +3785,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. address@hidden Named References address@hidden Using Named References address@hidden named references + +While every semantic value can be accessed with positional references address@hidden@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: + address@hidden address@hidden +invocation: op '(' args ')' + @{ $invocation = new_invocation ($op, $args, @@invocation); @} address@hidden group address@hidden example + address@hidden +The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be +mixed with @code{$name} and @code{@@name} arbitrarily. For example: + address@hidden address@hidden +invocation: op '(' args ')' + @{ $$ = new_invocation ($op, $args, @@$); @} address@hidden group address@hidden example + address@hidden +However, sometimes regular symbol names are not sufficient due to +ambiguities: + address@hidden address@hidden +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. address@hidden group address@hidden example + address@hidden +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: address@hidden address@hidden +exp[result]: exp[left] '/' exp[right] + @{ $result = $left / $right; @} address@hidden group address@hidden example + address@hidden +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: address@hidden address@hidden +exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right] + @{ $res = $left + $right; @} address@hidden group address@hidden example + address@hidden + +In references, in order to specify names containing dots and dashes, an explicit +bracketed syntax @code{$[name]} and @code{@@[name]} must be used: address@hidden address@hidden +if-stmt: IF '(' expr ')' THEN then.stmt ';' + @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @} address@hidden group address@hidden 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 address@hidden as a reference to symbol value @code{$name} followed by address@hidden, 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 +3927,8 @@ Action Decl, , Performing Actions before Parsing}. @cindex actions, location @vindex @@$ @vindex @@@var{n} address@hidden @@@var{name} address@hidden @@address@hidden Actions are not only useful for defining language semantics, but also for describing the behavior of the output parser with locations. @@ -3829,6 +3940,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 address@hidden@@address@hidden may also be used to address the symbol locations. address@hidden 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 @@ -10446,6 +10562,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 address@hidden {Variable} @@@var{name} +In an action, the location of a symbol addressed by name. address@hidden, , Locations Overview}. address@hidden deffn + address@hidden {Variable} @@address@hidden +In an action, the location of a symbol addressed by name. address@hidden, , Locations Overview}. address@hidden deffn + @deffn {Variable} $$ In an action, the semantic value of the left-hand side of the rule. @xref{Actions}. @@ -10456,6 +10582,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 address@hidden {Variable} address@hidden +In an action, the semantic value of a symbol addressed by name. address@hidden address@hidden deffn + address@hidden {Variable} address@hidden +In an action, the semantic value of a symbol addressed by name. address@hidden address@hidden deffn + @deffn {Delimiter} %% Delimiter used to separate the grammar rule section from the Bison declarations section or the epilogue.