[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 6/6] doc: explain how mid-rule actions are translated
From: |
Akim Demaille |
Subject: |
[PATCH 6/6] doc: explain how mid-rule actions are translated |
Date: |
Sun, 9 Dec 2012 16:31:37 +0100 |
* doc/bison.texi (Actions in Mid-Rule): Mention and use named references.
Split into three subsections, among which...
(Mid-Rule Action Translation): this new section.
---
NEWS | 10 ++---
doc/bison.texi | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 123 insertions(+), 9 deletions(-)
diff --git a/NEWS b/NEWS
index cecc676..6149ea8 100644
--- a/NEWS
+++ b/NEWS
@@ -2,9 +2,6 @@ GNU Bison NEWS
* Noteworthy changes in release ?.? (????-??-??) [?]
-
-* Noteworthy changes in release 2.6.90 (2012-12-07) [beta]
-
** Bug fixes
Warnings about uninitialized yylloc in yyparse have been fixed.
@@ -99,13 +96,16 @@ GNU Bison NEWS
These changes are present in both --graph output and xml2dot.xsl XSLT
processing, with minor (documented) differences.
- Two nodes were added to the documentation: Xml and Graphviz.
-
** Documentation
The sections about shift/reduce and reduce/reduce conflicts resolution
have been fixed and extended.
+ Although introduced more than four years ago, XML and Graphviz reports
+ were not properly documented.
+
+ The translation of mid-rule actions is now described.
+
* Noteworthy changes in release 2.6.5 (2012-11-07) [stable]
We consider compiler warnings about Bison generated parsers to be bugs.
diff --git a/doc/bison.texi b/doc/bison.texi
index 5a6cb68..a508b9c 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -208,6 +208,12 @@ Defining Language Semantics
This says when, why and how to use the exceptional
action in the middle of a rule.
+Actions in Mid-Rule
+
+* Using Mid-Rule Actions:: Putting an action in the middle of a rule.
+* Mid-Rule Action Translation:: How mid-rule actions are actually processed.
+* Mid-Rule Conflicts:: Mid-rule actions can cause conflicts.
+
Tracking Locations
* Location Type:: Specifying a data type for locations.
@@ -3739,6 +3745,15 @@ Occasionally it is useful to put an action in the middle
of a rule.
These actions are written just like usual end-of-rule actions, but they
are executed before the parser even recognizes the following components.
address@hidden
+* Using Mid-Rule Actions:: Putting an action in the middle of a rule.
+* Mid-Rule Action Translation:: How mid-rule actions are actually processed.
+* Mid-Rule Conflicts:: Mid-rule actions can cause conflicts.
address@hidden menu
+
address@hidden Using Mid-Rule Actions
address@hidden Using Mid-Rule Actions
+
A mid-rule action may refer to the components preceding it using
@address@hidden, but it may not refer to subsequent components because
it is run before they are parsed.
@@ -3791,8 +3806,27 @@ list of accessible variables) as its semantic value,
using alternative
@code{context} in the data-type union. Then it calls
@code{declare_variable} to add the new variable to that list. Once the
first action is finished, the embedded statement @code{stmt} can be
-parsed. Note that the mid-rule action is component number 5, so the
address@hidden is component number 6.
+parsed.
+
+Note that the mid-rule action is component number 5, so the @samp{stmt} is
+component number 6. Named references can be used to improve the readability
+and maintainability (@pxref{Named References}):
+
address@hidden
address@hidden
+stmt:
+ "let" '(' var ')'
+ @{
+ $<context>let = push_context ();
+ declare_variable ($3);
+ @}[let]
+ stmt
+ @{
+ $$ = $6;
+ pop_context ($<context>let);
+ @}
address@hidden group
address@hidden example
After the embedded statement is parsed, its semantic value becomes the
value of the entire @code{let}-statement. Then the semantic value from the
@@ -3826,13 +3860,13 @@ stmt:
let stmt
@{
$$ = $2;
- pop_context ($1);
+ pop_context ($let);
@};
let:
"let" '(' var ')'
@{
- $$ = push_context ();
+ $let = push_context ();
declare_variable ($3);
@};
@@ -3844,6 +3878,76 @@ Note that the action is now at the end of its rule.
Any mid-rule action can be converted to an end-of-rule action in this way, and
this is what Bison actually does to implement mid-rule actions.
address@hidden Mid-Rule Action Translation
address@hidden Mid-Rule Action Translation
address@hidden $@@@var{n}
address@hidden @@@var{n}
+
+As hinted earlier, mid-rule actions are actually transformed into regular
+rules and actions. The various reports generated by Bison (textual,
+graphical, etc., see @ref{Understanding, , Understanding Your Parser})
+reveal this translation, best explained by means of an example. The
+following rule:
+
address@hidden
+exp: @{ a(); @} "b" @{ c(); @} @{ d(); @} "e" @{ f(); @};
address@hidden example
+
address@hidden
+is translated into:
+
address@hidden
+$@@1: /* empty */ @{ a(); @};
+$@@2: /* empty */ @{ c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: $@@1 "b" $@@2 $@@3 "e" @{ f(); @};
address@hidden example
+
address@hidden
+with new nonterminal symbols @code{$@@@var{n}}, where @var{n} is a number.
+
+A mid-rule action is expected to generate a value if it uses @code{$$}, or
+the (final) action uses @address@hidden where @var{n} denote the mid-rule
+action. In that case its nonterminal is rather named @code{@@@var{n}}:
+
address@hidden
+exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
address@hidden example
+
address@hidden
+is translated into
+
address@hidden
+@@1: /* empty */ @{ a(); @};
+@@2: /* empty */ @{ $$ = c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: @@1 "b" @@2 $@@3 "e" @{ f = $1; @}
address@hidden example
+
+There are probably two errors in the above example: the first mid-rule
+action does not generate a value (it does not use @code{$$} although the
+final action uses it), and the value of the second one is not used (the
+final action does not use @code{$3}). Bison reports these errors when the
address@hidden warnings are enabled (@pxref{Invocation, ,Invoking
+Bison}):
+
address@hidden
+$ bison -fcaret -Wmidrule-value mid.y
address@hidden
+mid.y:2.6-13: warning: unset value: $$
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+ ^^^^^^^^
address@hidden group
address@hidden
+mid.y:2.19-31: warning: unused value: $3
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+ ^^^^^^^^^^^^^
address@hidden group
address@hidden example
+
+
address@hidden Mid-Rule Conflicts
address@hidden Conflicts due to Mid-Rule Actions
Taking action before a rule is completely recognized often leads to
conflicts since the parser must commit to a parse in order to execute the
action. For example, the following two rules, without mid-rule actions,
@@ -3941,6 +4045,7 @@ compound:
Now Bison can execute the action in the rule for @code{subroutine} without
deciding which rule for @code{compound} it will eventually use.
+
@node Tracking Locations
@section Tracking Locations
@cindex location
@@ -11404,8 +11509,12 @@ In an action, the location of the left-hand side of
the rule.
@end deffn
@deffn {Variable} @@@var{n}
address@hidden {Symbol} @@@var{n}
In an action, the location of the @var{n}-th symbol of the right-hand side
of the rule. @xref{Tracking Locations}.
+
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with a semantical value. @xref{Mid-Rule Action Translation}.
@end deffn
@deffn {Variable} @@@var{name}
@@ -11414,6 +11523,11 @@ In an action, the location of a symbol addressed by
@var{name}.
@xref{Tracking Locations}.
@end deffn
address@hidden {Symbol} $@@@var{n}
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with no semantical value. @xref{Mid-Rule Action Translation}.
address@hidden deffn
+
@deffn {Variable} $$
In an action, the semantic value of the left-hand side of the rule.
@xref{Actions}.
--
1.8.0.1
- [PATCH 0/6] {maint} more documentation about mid-rule actions, Akim Demaille, 2012/12/12
- Re: [PATCH 0/6] {maint} more documentation about mid-rule actions, Akim Demaille, 2012/12/10
- [PATCH 6/6] doc: explain how mid-rule actions are translated,
Akim Demaille <=
- [PATCH 5/6] error: use better locations for unused midrule values, Akim Demaille, 2012/12/12
- [PATCH 2/6] tests: be robust to C being compiled with a C++11 compiler, Akim Demaille, 2012/12/12
- [PATCH 4/6] doc: various minor improvements and fixes, Akim Demaille, 2012/12/12
- [PATCH 3/6] tests: ignore more useless compiler warnings, Akim Demaille, 2012/12/12
- [PATCH 1/6] build: beware of Clang++ not supporting POSIXLY_CORRECT, Akim Demaille, 2012/12/12