Re: Documentation for Named References

[Joel E. Denny]

Hi Alex,

On Mon, 16 Nov 2009, Alex Rozenman wrote:

> I added some documentation for Named References (a patch is attached).

Thanks.

> Please consider it as a starting point for a discussion. Please tell me if
> you have any objects/additions.

It's a very nice start.  Comments are inlined below.

> For your convenience, I also attached two affected HTML files.

Thanks, but don't worry about attaching those in the future unless someone 
else finds it helpful.

> Another issue: should we remove "Labeling the symbols" item from "TODO" file
> ?

I would say yes, but Akim wrote that, so maybe he should decide if there 
are any ideas left in there he wants to keep.

> 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}).

At the beginning of this section, there is:

  @vindex $$
  @vindex address@hidden

It seems you should add:

  @vindex address@hidden
  @vindex address@hidden

Also, there are nearby sections talking about locations and mid-rule 
actions.  For consistency, there should probably be mention of named 
references there as well.  For the locations section, another @vindex or 
two seems logical.

>  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 named references construct @address@hidden

You're missing "the" in "with the named references construct".

> +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 current grouping) is translated to a modifiable

Missing "the" in "for the current grouping".

>  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:
> +
> 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 named references construct.

Missing "the" in "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 +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.
>  
> address@hidden Named References
> address@hidden Using Named References

Is there a reason to name the node and subsection differently?

> 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:

Throughout your changes, please put two spaces after periods at the ends 
of sentences.

> +
> 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 symbol names may be used.
> +Explicit symbol names are declared as a bracketed name after a symbol

I'd not say "symbol names" here because these are names for the values and 
locations not for the symbols themselves.  So you might reword to:

  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 symbol names may be declared for RHS and for LHS symbols as well.

Likewise:

  Explicit names may be declared for RHS and LHS values and locations 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

"an explicit name"

> +name after the closing brace of the mid-rule action code:
> address@hidden
> address@hidden
> +exp[res]: exp[x] '+' @{$$ = $x;@}[left] exp[right]
> +  @{ $$ = $left + $right; @}

I think it would be better to convert each $$ to a named reference.  This 
would be especially helpful in the mid-rule where it's not obvious that 
it's possible because "left" is declared afterward.

> address@hidden group
> address@hidden example
> +
> address@hidden
> +
> +In order to access symbol names containing dots and dashes, an explicit

Those could be the original symbol names or explicitly declared names, so 
I'd say:

  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 @code{$name} symbol followed by

"reference to the symbol value @code{$name}".

> address@hidden, i.e., an access to the @code{suffix} field of the semantic

I've only recently begun to understand the difference between @samp and 
@code (because I saw Akim correct some of my poor usage), and I'm not sure 
I completely understand it.  However, I'm pretty sure @code{.suffix} 
should be @samp{.suffix} because it discusses a string of text instead of, 
for example, a variable name.  There may be other places here, but I'm not 
sure.

> +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.

Maybe reword to "reference to the value of a symbol having", but this 
makes it harder to read.  Maybe this is better:

  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.

It would also be nice to explain some of the error messages the user might 
see, but that can be added some other time.