Hi Akim, Hi Joel, All I added some documentation for Named References (a patch is attached). Please consider it as a starting point for a discussion. Please tell me if you have any objects/additions. For your convenience, I also attached two affected HTML files.
Another issue: should we remove "Labeling the symbols" item from "TODO" file ? -- Best regards, Alex Rozenman ([email protected]).
<html lang="en"> <head> <title>Actions - Bison 2.4.414-bb31-dirty</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="Bison 2.4.414-bb31-dirty"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> <link rel="up" href="Semantics.html#Semantics" title="Semantics"> <link rel="prev" href="Multiple-Types.html#Multiple-Types" title="Multiple Types"> <link rel="next" href="Action-Types.html#Action-Types" title="Action Types"> <link href="http://www.gnu.org/software/texinfo/"; rel="generator-home" title="Texinfo Homepage"> <!-- This manual (6 November 2009) is for GNU Bison (version 2.4.414-bb31-dirty), the GNU parser generator. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' --> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <a name="Actions"></a> <p> Next: <a rel="next" accesskey="n" href="Action-Types.html#Action-Types">Action Types</a>, Previous: <a rel="previous" accesskey="p" href="Multiple-Types.html#Multiple-Types">Multiple Types</a>, Up: <a rel="up" accesskey="u" href="Semantics.html#Semantics">Semantics</a> <hr> </div> <h4 class="subsection">3.5.3 Actions</h4> <p><a name="index-action-135"></a><a name="index-g_t_0024_0024-136"></a><a name="index-g_t_0024_0040var_007bn_007d-137"></a> 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 is to compute a semantic value for the grouping built by the rule from the semantic values associated with tokens or smaller groupings. <p>An action consists of braced code containing C statements, and can be placed at any position in the rule; it is executed at that position. Most rules have just one action at the end of the rule, following all the components. Actions in the middle of a rule are tricky and used only for special purposes (see <a href="Mid_002dRule-Actions.html#Mid_002dRule-Actions">Actions in Mid-Rule</a>). <p>The C code in an action can refer to the semantic values of the components matched by the rule with the construct <code>$</code><var>n</var>, which stands for the value of the <var>n</var>th component. The semantic value for the grouping being constructed is <code>$$</code>. In addition, the semantic values of symbols can be accessed with named references construct <code>$</code><var>name</var> or <code>$[</code><var>name</var><code>]</code>. Bison translates both of these constructs into expressions of the appropriate type when it copies the actions into the parser file. <code>$$</code> (or <code>$</code><var>name</var>, when it stands for current grouping) is translated to a modifiable lvalue, so it can be assigned to. <p>Here is a typical example: <pre class="example"> exp: ... | exp '+' exp { $$ = $1 + $3; } </pre> <p>Or, in terms of named references: <pre class="example"> exp[result]: ... | exp[left] '+' exp[right] { $result = $left + $right; } </pre> <p class="noindent">This rule constructs an <code>exp</code> from two smaller <code>exp</code> groupings connected by a plus-sign token. In the action, <code>$1</code> and <code>$3</code> (<code>$left</code> and <code>$right</code>) refer to the semantic values of the two component <code>exp</code> groupings, which are the first and third symbols on the right hand side of the rule. The sum is stored into <code>$$</code> (<code>$result</code>) 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><span class="samp">+</span></samp>’ token, it could be referred to as <code>$2</code>. <p>See <a href="Named-References.html#Named-References">Using Named References</a>, for more information about using named references construct. <p>Note that the vertical-bar character ‘<samp><span class="samp">|</span></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><span class="samp">|</span></samp>’ stands for either “or”, or “the same action as that of the next rule”. In the following example, the action is triggered only when ‘<samp><span class="samp">b</span></samp>’ is found: <pre class="example"> a-or-b: 'a'|'b' { a_or_b_found = 1; }; </pre> <p><a name="index-default-action-138"></a>If you don't specify an action for a rule, Bison supplies a default: <code>$$ = $1</code>.<!-- /@w --> Thus, the value of the first symbol in the rule becomes the value of the whole rule. Of course, the default action is valid only if the two data types match. There is no meaningful default action for an empty rule; every empty rule must have an explicit action unless the rule's value does not matter. <p><code>$</code><var>n</var> with <var>n</var> zero or negative is allowed for reference to tokens and groupings on the stack <em>before</em> those that match the current rule. This is a very risky practice, and to use it reliably you must be certain of the context in which the rule is applied. Here is a case in which you can use this reliably: <pre class="example"> foo: expr bar '+' expr { ... } | expr bar '-' expr { ... } ; bar: /* empty */ { previous_expr = $0; } ; </pre> <p>As long as <code>bar</code> is used only in the fashion shown here, <code>$0</code> always refers to the <code>expr</code> which precedes <code>bar</code> in the definition of <code>foo</code>. <p><a name="index-yylval-139"></a>It is also possible to access the semantic value of the lookahead token, if any, from a semantic action. This semantic value is stored in <code>yylval</code>. See <a href="Action-Features.html#Action-Features">Special Features for Use in Actions</a>. </body></html>
0001--Document-named-references.patch
Description: Binary data
<html lang="en"> <head> <title>Named References - Bison 2.4.414-bb31-dirty</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="Bison 2.4.414-bb31-dirty"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> <link rel="up" href="Semantics.html#Semantics" title="Semantics"> <link rel="prev" href="Mid_002dRule-Actions.html#Mid_002dRule-Actions" title="Mid-Rule Actions"> <link href="http://www.gnu.org/software/texinfo/"; rel="generator-home" title="Texinfo Homepage"> <!-- This manual (6 November 2009) is for GNU Bison (version 2.4.414-bb31-dirty), the GNU parser generator. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' --> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <a name="Named-References"></a> <p> Previous: <a rel="previous" accesskey="p" href="Mid_002dRule-Actions.html#Mid_002dRule-Actions">Mid-Rule Actions</a>, Up: <a rel="up" accesskey="u" href="Semantics.html#Semantics">Semantics</a> <hr> </div> <h4 class="subsection">3.5.6 Using Named References</h4> <p><a name="index-named-references-147"></a> While every semantic value can be accessed with positional references <code>$</code><var>n</var> and <code>$$</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: <pre class="example"> invocation: op '(' args ')' { $invocation = new_invocation ($op, $args, @invocation); } </pre> <p class="noindent">The positional <code>$$</code>, <code>@$</code>, <code>$n</code>, and <code>@n</code> can be mixed with <code>$name</code> and <code>@name</code> arbitrarily. For example: <pre class="example"> invocation: op '(' args ')' { $$ = new_invocation ($op, $args, @$); } </pre> <p class="noindent">However, sometimes regular symbol names are not sufficient due to ambiguities: <pre class="example"> 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. </pre> <p class="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: <pre class="example"> exp[result]: exp[left] '/' exp[right] { $result = $left / $right; } </pre> <p class="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: <pre class="example"> exp[res]: exp[x] '+' {$$ = $x;}[left] exp[right] { $$ = $left + $right; } </pre> <p class="noindent">In order to access symbol names containing dots and dashes, an explicit bracketed syntax <code>$[name]</code> and <code>@[name]</code> must be used: <pre class="example"> if-stmt: IF '(' expr ')' THEN then.stmt ';' { $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); } </pre> <p>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</code> as a reference to <code>$name</code> symbol followed by <code>.suffix</code>, i.e., an access to the <code>suffix</code> 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</code>, bracketed syntax <code>$[name.suffix]</code> must be used. </body></html>
