Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-09 04:13:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: discuss named references after locations.

Browse Source 
Reported by Hans Aberg at
<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
* 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'.
This commit is contained in:
Joel E. Denny
2011-05-29 19:59:44 -04:00
parent 90dcd4156c
commit 908c8647de
3 changed files with 102 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
ChangeLog
View File

@@ -1,3 +1,15 @@
2011-05-29 Joel E. Denny <joeldenny@joeldenny.org>
doc: discuss named references after locations.
Reported by Hans Aberg at
<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
* 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 <joeldenny@joeldenny.org> 2011-05-29 Joel E. Denny <joeldenny@joeldenny.org>
Prepare for the possibility of a 2.5.1 release. Prepare for the possibility of a 2.5.1 release.

2
NEWS
View File

@@ -3,6 +3,8 @@ Bison News
* Changes in version 2.5.1 (????-??-??): * Changes in version 2.5.1 (????-??-??):
** Minor improvements have been made to the manual.
* Changes in version 2.5 (2011-05-14): * Changes in version 2.5 (2011-05-14):
** Grammar symbol names can now contain non-initial dashes: ** Grammar symbol names can now contain non-initial dashes:

177
doc/bison.texinfo
View File

@@ -186,6 +186,7 @@ Bison Grammar Files
* Recursion:: Writing recursive rules. * Recursion:: Writing recursive rules.
* Semantics:: Semantic values and actions. * Semantics:: Semantic values and actions.
* Locations:: Locations and actions. * Locations:: Locations and actions.
* Named References:: Using named references in actions.
* Declarations:: All kinds of Bison declarations are described here. * Declarations:: All kinds of Bison declarations are described here.
* Multiple Parsers:: Putting more than one Bison parser in one program. * 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. * Mid-Rule Actions:: Most actions go at the end of a rule.
This says when, why and how to use the exceptional This says when, why and how to use the exceptional
action in the middle of a rule. action in the middle of a rule.
* Named References:: Using named references in actions.
Tracking Locations Tracking Locations
@@ -2627,6 +2627,7 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
* Recursion:: Writing recursive rules. * Recursion:: Writing recursive rules.
* Semantics:: Semantic values and actions. * Semantics:: Semantic values and actions.
* Locations:: Locations and actions. * Locations:: Locations and actions.
* Named References:: Using named references in actions.
* Declarations:: All kinds of Bison declarations are described here. * Declarations:: All kinds of Bison declarations are described here.
* Multiple Parsers:: Putting more than one Bison parser in one program. * Multiple Parsers:: Putting more than one Bison parser in one program.
@end menu @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. * Mid-Rule Actions:: Most actions go at the end of a rule.
This says when, why and how to use the exceptional This says when, why and how to use the exceptional
action in the middle of a rule. action in the middle of a rule.
* Named References:: Using named references in actions.
@end menu @end menu
@node Value Type @node Value Type
@@ -3806,93 +3806,6 @@ compound: subroutine
Now Bison can execute the action in the rule for @code{subroutine} without Now Bison can execute the action in the rule for @code{subroutine} without
deciding which rule for @code{compound} it will eventually use. 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 @node Locations
@section Tracking Locations @section Tracking Locations
@cindex location @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. statement when it is followed by a semicolon.
@end itemize @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 @node Declarations
@section Bison Declarations @section Bison Declarations
@cindex declarations, Bison @cindex declarations, Bison