X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/378e917c55295fb209173857c936288a72e6cf0a..f9c75dd016198f9b8c255f1bb139360eef3f071f:/doc/bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 456eb7b6..8391e714 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -33,7 +33,7 @@
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 
-Copyright @copyright{} 1988-1993, 1995, 1998-2011 Free Software
+Copyright @copyright{} 1988-1993, 1995, 1998-2012 Free Software
 Foundation, Inc.
 
 @quotation
@@ -125,7 +125,7 @@ The Concepts of Bison
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -181,15 +181,15 @@ Multi-Function Calculator: @code{mfcalc}
 
 Bison Grammar Files
 
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 
 Outline of a Bison Grammar
 
@@ -451,7 +451,7 @@ use Bison or Yacc, we suggest you start by reading this chapter carefully.
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -1178,8 +1178,8 @@ Another Bison feature requiring special consideration is @code{YYERROR}
 initiate error recovery.
 During deterministic GLR operation, the effect of @code{YYERROR} is
 the same as its effect in a deterministic parser.
-The effect in a deferred action is similar, but the precise point of the 
-error is undefined;  instead, the parser reverts to deterministic operation, 
+The effect in a deferred action is similar, but the precise point of the
+error is undefined;  instead, the parser reverts to deterministic operation,
 selecting an unspecified stack on which to continue with a syntax error.
 In a semantic predicate (see @ref{Semantic Predicates}) during nondeterministic
 parsing, @code{YYERROR} silently prunes
@@ -1210,12 +1210,12 @@ widget :
 @end smallexample
 
 @noindent
-is one way to allow the same parser to handle two different syntaxes for 
+is one way to allow the same parser to handle two different syntaxes for
 widgets.  The clause preceded by @code{%?} is treated like an ordinary
 action, except that its text is treated as an expression and is always
-evaluated immediately (even when in nondeterministic mode).  If the 
+evaluated immediately (even when in nondeterministic mode).  If the
 expression yields 0 (false), the clause is treated as a syntax error,
-which, in a nondeterministic parser, causes the stack in which it is reduced 
+which, in a nondeterministic parser, causes the stack in which it is reduced
 to die.  In a deterministic parser, it acts like YYERROR.
 
 As the example shows, predicates otherwise look like semantic actions, and
@@ -1226,7 +1226,7 @@ labels.
 
 There is a subtle difference between semantic predicates and ordinary
 actions in nondeterministic mode, since the latter are deferred.
-For example, we could try to rewrite the previous example as 
+For example, we could try to rewrite the previous example as
 
 @smallexample
 widget :
@@ -1240,7 +1240,7 @@ widget :
 false).  However, this
 does @emph{not} have the same effect if @code{new_args} and @code{old_args}
 have overlapping syntax.
-Since the mid-rule actions testing @code{new_syntax} are deferred, 
+Since the mid-rule actions testing @code{new_syntax} are deferred,
 a GLR parser first encounters the unresolved ambiguous reduction
 for cases where @code{new_args} and @code{old_args} recognize the same string
 @emph{before} performing the tests of @code{new_syntax}.  It therefore
@@ -1278,7 +1278,7 @@ will suffice.  Otherwise, we suggest
 %@}
 @end example
 
-@node Locations Overview
+@node Locations
 @section Locations
 @cindex location
 @cindex textual location
@@ -1290,9 +1290,10 @@ the @dfn{textual location}, or @dfn{location}, of each syntactic construct.
 Bison provides a mechanism for handling these locations.
 
 Each token has a semantic value.  In a similar fashion, each token has an
-associated location, but the type of locations is the same for all tokens and
-groupings.  Moreover, the output parser is equipped with a default data
-structure for storing locations (@pxref{Locations}, for more details).
+associated location, but the type of locations is the same for all tokens
+and groupings.  Moreover, the output parser is equipped with a default data
+structure for storing locations (@pxref{Tracking Locations}, for more
+details).
 
 Like semantic values, locations can be reached in actions using a dedicated
 set of constructs.  In the example above, the location of the whole grouping
@@ -2299,17 +2300,17 @@ Here is a sample session with the multi-function calculator:
 @example
 $ @kbd{mfcalc}
 @kbd{pi = 3.141592653589}
-3.1415926536
+@result{} 3.1415926536
 @kbd{sin(pi)}
-0.0000000000
+@result{} 0.0000000000
 @kbd{alpha = beta1 = 2.3}
-2.3000000000
+@result{} 2.3000000000
 @kbd{alpha}
-2.3000000000
+@result{} 2.3000000000
 @kbd{ln(alpha)}
-0.8329091229
+@result{} 0.8329091229
 @kbd{exp(ln(beta1))}
-2.3000000000
+@result{} 2.3000000000
 $
 @end example
 
@@ -2326,11 +2327,12 @@ Note that multiple assignment and nested function calls are permitted.
 
 Here are the C and Bison declarations for the multi-function calculator.
 
+@comment file: mfcalc.y
 @smallexample
 @group
 %@{
-  #include <math.h>  /* For math functions, cos(), sin(), etc.  */
-  #include "calc.h"  /* Contains definition of `symrec'.  */
+  #include <stdio.h>  /* For printf, etc. */
+  #include "calc.h"   /* Contains definition of `symrec'.  */
   int yylex (void);
   void yyerror (char const *);
 %@}
@@ -2384,6 +2386,7 @@ Here are the grammar rules for the multi-function calculator.
 Most of them are copied directly from @code{calc}; three rules,
 those which mention @code{VAR} or @code{FNCT}, are new.
 
+@comment file: mfcalc.y
 @smallexample
 @group
 input:   /* empty */
@@ -2394,8 +2397,8 @@ input:   /* empty */
 @group
 line:
           '\n'
-        | exp '\n'   @{ printf ("\t%.10g\n", $1); @}
-        | error '\n' @{ yyerrok;                  @}
+        | exp '\n'   @{ printf ("%.10g\n", $1); @}
+        | error '\n' @{ yyerrok;                @}
 ;
 @end group
 
@@ -2430,6 +2433,7 @@ The symbol table itself consists of a linked list of records.  Its
 definition, which is kept in the header @file{calc.h}, is as follows.  It
 provides for either functions or variables to be placed in the table.
 
+@comment file: calc.h
 @smallexample
 @group
 /* Function type.  */
@@ -2466,6 +2470,7 @@ The new version of @code{main} includes a call to @code{init_table}, a
 function that initializes the symbol table.  Here it is, and
 @code{init_table} as well:
 
+@comment file: mfcalc.y
 @smallexample
 #include <stdio.h>
 
@@ -2487,15 +2492,16 @@ struct init
 @end group
 
 @group
+#include <math.h>  /* Math functions, cos(), sin(), etc.  */
 struct init const arith_fncts[] =
 @{
-  "sin",  sin,
-  "cos",  cos,
-  "atan", atan,
-  "ln",   log,
-  "exp",  exp,
-  "sqrt", sqrt,
-  0, 0
+  @{ "atan", atan @},
+  @{ "cos",  cos  @},
+  @{ "exp",  exp  @},
+  @{ "ln",   log  @},
+  @{ "sin",  sin  @},
+  @{ "sqrt", sqrt @},
+  @{ 0, 0 @},
 @};
 @end group
 
@@ -2506,6 +2512,7 @@ symrec *sym_table;
 
 @group
 /* Put arithmetic functions in table.  */
+static
 void
 init_table (void)
 @{
@@ -2539,7 +2546,11 @@ linked to the front of the list, and a pointer to the object is returned.
 The function @code{getsym} is passed the name of the symbol to look up.  If
 found, a pointer to that symbol is returned; otherwise zero is returned.
 
+@comment file: mfcalc.y
 @smallexample
+#include <stdlib.h> /* malloc. */
+#include <string.h> /* strlen. */
+
 symrec *
 putsym (char const *sym_name, int sym_type)
 @{
@@ -2581,6 +2592,7 @@ returned to @code{yyparse}.
 No change is needed in the handling of numeric values and arithmetic
 operators in @code{yylex}.
 
+@comment file: mfcalc.y
 @smallexample
 @group
 #include <ctype.h>
@@ -2623,7 +2635,10 @@ yylex (void)
       /* Initially make the buffer long enough
          for a 40-character symbol name.  */
       if (length == 0)
-        length = 40, symbuf = (char *)malloc (length + 1);
+        @{
+          length = 40;
+          symbuf = (char *) malloc (length + 1);
+        @}
 
       i = 0;
       do
@@ -2695,15 +2710,15 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 @xref{Invocation, ,Invoking Bison}.
 
 @menu
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 @end menu
 
 @node Grammar Outline
@@ -3583,8 +3598,8 @@ 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}.
 
-@xref{Named References,,Using Named References}, for more information
-about using the named references construct.
+@xref{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
@@ -3880,7 +3895,7 @@ 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.
 
-@node Locations
+@node Tracking Locations
 @section Tracking Locations
 @cindex location
 @cindex textual location
@@ -3950,8 +3965,8 @@ The location of the @var{n}th component of the right hand side is
 
 In addition, the named references construct @code{@@@var{name}} and
 @code{@@[@var{name}]} may also be used to address the symbol locations.
-@xref{Named References,,Using Named References}, for more information
-about using the named references construct.
+@xref{Named References}, for more information about using the named
+references construct.
 
 Here is a basic example using the default data type for locations:
 
@@ -4089,13 +4104,19 @@ statement when it is followed by a semicolon.
 @end itemize
 
 @node Named References
-@section Using Named References
+@section 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:
+As described in the preceding sections, the traditional way to refer to any
+semantic value or location is a @dfn{positional reference}, which takes the
+form @code{$@var{n}}, @code{$$}, @code{@@@var{n}}, and @code{@@$}.  However,
+such a reference is not very descriptive.  Moreover, if you later decide to
+insert or remove symbols in the right-hand side of a grammar rule, the need
+to renumber such references can be tedious and error-prone.
+
+To avoid these issues, you can also refer to a semantic value or location
+using a @dfn{named reference}.  First of all, original symbol names may be
+used as named references.  For example:
 
 @example
 @group
@@ -4105,8 +4126,7 @@ invocation: op '(' args ')'
 @end example
 
 @noindent
-The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
-mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
+Positional and named references can be mixed arbitrarily.  For example:
 
 @example
 @group
@@ -4144,10 +4164,9 @@ exp[result]: exp[left] '/' exp[right]
 @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:
+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]
@@ -4168,11 +4187,14 @@ if-stmt: IF '(' expr ')' THEN then.stmt ';'
 
 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.
+@samp{$name.suffix} as a reference to symbol value @code{$name} followed by
+@samp{.suffix}, i.e., an access to the @code{suffix} field of the semantic
+value.  In order to force Bison to recognize @samp{name.suffix} in its
+entirety as the name of a semantic value, the bracketed syntax
+@samp{$[name.suffix]} must be used.
+
+The named references feature is experimental.  More user feedback will help
+to stabilize it.
 
 @node Declarations
 @section Bison Declarations
@@ -4620,12 +4642,12 @@ redefine it from @code{$end} to, for example, @code{END}:
 @cindex mid-rule actions
 Finally, Bison will never invoke a @code{%destructor} for an unreferenced
 mid-rule semantic value (@pxref{Mid-Rule Actions,,Actions in Mid-Rule}).
-That is, Bison does not consider a mid-rule to have a semantic value if you do
-not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
-@var{n} is the RHS symbol position of the mid-rule) in any later action in that
-rule.
-However, if you do reference either, the Bison-generated parser will invoke the
-@code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
+That is, Bison does not consider a mid-rule to have a semantic value if you
+do not reference @code{$$} in the mid-rule's action or @code{$@var{n}}
+(where @var{n} is the right-hand side symbol position of the mid-rule) in
+any later action in that rule.  However, if you do reference either, the
+Bison-generated parser will invoke the @code{<>} @code{%destructor} whenever
+it discards the mid-rule symbol.
 
 @ignore
 @noindent
@@ -4991,9 +5013,8 @@ Unless your parser is pure, the parser header file declares
 (Reentrant) Parser}.
 
 If you have also used locations, the parser header file declares
-@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
-the @code{YYSTYPE} macro and @code{yylval}.  @xref{Locations,
-,Tracking Locations}.
+@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of the
+@code{YYSTYPE} macro and @code{yylval}.  @xref{Tracking Locations}.
 
 This parser header file is normally essential if you wish to put the
 definition of @code{yylex} in a separate source file, because
@@ -5995,12 +6016,12 @@ then the code in @code{yylex} might look like this:
 @subsection Textual Locations of Tokens
 
 @vindex yylloc
-If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, ,
-Tracking Locations}) in actions to keep track of the textual locations
-of tokens and groupings, then you must provide this information in
-@code{yylex}.  The function @code{yyparse} expects to find the textual
-location of a token just parsed in the global variable @code{yylloc}.
-So @code{yylex} must store the proper data in that variable.
+If you are using the @samp{@@@var{n}}-feature (@pxref{Tracking Locations})
+in actions to keep track of the textual locations of tokens and groupings,
+then you must provide this information in @code{yylex}.  The function
+@code{yyparse} expects to find the textual location of a token just parsed
+in the global variable @code{yylloc}.  So @code{yylex} must store the proper
+data in that variable.
 
 By default, the value of @code{yylloc} is a structure and you need only
 initialize the members that are going to be used by the actions.  The
@@ -6337,9 +6358,9 @@ Actions}).
 
 @deffn {Value} @@$
 @findex @@$
-Acts like a structure variable containing information on the textual location
-of the grouping made by the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the grouping made by the current rule.  @xref{Tracking
+Locations}.
 
 @c Check if those paragraphs are still useful or not.
 
@@ -6363,9 +6384,9 @@ Tracking Locations}.
 
 @deffn {Value} @@@var{n}
 @findex @@@var{n}
-Acts like a structure variable containing information on the textual location
-of the @var{n}th component of the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the @var{n}th component of the current rule.  @xref{Tracking
+Locations}.
 @end deffn
 
 @node Internationalization
@@ -7738,7 +7759,7 @@ that allows variable-length arrays.  The default is 200.
 Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
 
 You can generate a deterministic parser containing C++ user code from
-the default (C) skeleton, as well as from the C++ skeleton 
+the default (C) skeleton, as well as from the C++ skeleton
 (@pxref{C++ Parsers}).  However, if you do use the default skeleton
 and want to allow the parsing stack to grow,
 be careful not to use semantic types or location types that require
@@ -9169,10 +9190,10 @@ is some time and/or some talented C++ hacker willing to contribute to Bison.
 @c - %define filename_type "const symbol::Symbol"
 
 When the directive @code{%locations} is used, the C++ parser supports
-location tracking, see @ref{Locations, , Locations Overview}.  Two
-auxiliary classes define a @code{position}, a single point in a file,
-and a @code{location}, a range composed of a pair of
-@code{position}s (possibly spanning several files).
+location tracking, see @ref{Tracking Locations}.  Two auxiliary classes
+define a @code{position}, a single point in a file, and a @code{location}, a
+range composed of a pair of @code{position}s (possibly spanning several
+files).
 
 @deftypemethod {position} {std::string*} file
 The name of the file.  It will always be handled as a pointer, the
@@ -9263,7 +9284,8 @@ scanner should use @code{yy::parser::token::FOO}.  The scanner can use
 
 @defcv {Type} {parser} {syntax_error}
 This class derives from @code{std::runtime_error}.  Throw instances of it
-from user actions to raise parse errors.  This is equivalent with first
+from the scanner or from the user actions to raise parse errors.  This is
+equivalent with first
 invoking @code{error} to report the location and message of the syntax
 error, and then to invoke @code{YYERROR} to enter the error-recovery mode.
 But contrary to @code{YYERROR} which can only be invoked from user actions
@@ -10093,14 +10115,13 @@ can be used to print the semantic values.  This however may change
 @c - class Position
 @c - class Location
 
-When the directive @code{%locations} is used, the Java parser
-supports location tracking, see @ref{Locations, , Locations Overview}.
-An auxiliary user-defined class defines a @dfn{position}, a single point
-in a file; Bison itself defines a class representing a @dfn{location},
-a range composed of a pair of positions (possibly spanning several
-files).  The location class is an inner class of the parser; the name
-is @code{Location} by default, and may also be renamed using
-@samp{%define location_type "@var{class-name}"}.
+When the directive @code{%locations} is used, the Java parser supports
+location tracking, see @ref{Tracking Locations}.  An auxiliary user-defined
+class defines a @dfn{position}, a single point in a file; Bison itself
+defines a class representing a @dfn{location}, a range composed of a pair of
+positions (possibly spanning several files).  The location class is an inner
+class of the parser; the name is @code{Location} by default, and may also be
+renamed using @samp{%define location_type "@var{class-name}"}.
 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed
@@ -10931,7 +10952,7 @@ transcript of the build session, starting with the invocation of
 send additional files as well (such as `config.h' or `config.cache').
 
 Patches are most welcome, but not required.  That is, do not hesitate to
-send a bug report just because you can not provide a fix.
+send a bug report just because you cannot provide a fix.
 
 Send bug reports to @email{bug-bison@@gnu.org}.
 
@@ -10984,22 +11005,22 @@ See @url{http://lists.gnu.org/}.
 
 @deffn {Variable} @@$
 In an action, the location of the left-hand side of the rule.
-@xref{Locations, , Locations Overview}.
+@xref{Tracking Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{n}
-In an action, the location of the @var{n}-th symbol of the right-hand
-side of the rule.  @xref{Locations, , Locations Overview}.
+In an action, the location of the @var{n}-th symbol of the right-hand side
+of the rule.  @xref{Tracking Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{name}
-In an action, the location of a symbol addressed by name.
-@xref{Locations, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} @@[@var{name}]
-In an action, the location of a symbol addressed by name.
-@xref{Locations, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} $$