* data/glr.c (b4_shared_declarations): Put start-header first,

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 4f43dbf981b62f546777949e5d415ce7d9dfa64e..013847b5d884e5d9ea3a854f4d8fd79762417868 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -2649,6 +2649,7 @@ can be done with two @var{Prologue} blocks, one before and one after the
 
 @smallexample
 %@{
+  #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
@@ -2666,6 +2667,13 @@ can be done with two @var{Prologue} blocks, one before and one after the
 @dots{}
 @end smallexample
 
+When in doubt, it is usually safer to put prologue code before all
+Bison declarations, rather than after.  For example, any definitions
+of feature test macros like @code{_GNU_SOURCE} or
+@code{_POSIX_C_SOURCE} should appear before all Bison declarations, as
+feature test macros can affect the behavior of Bison-generated
+@code{#include} directives.
+
 @findex %before-header
 @findex %start-header
 @findex %after-header
@@ -3986,6 +3994,7 @@ For instance, if your locations use a file name, you may use
 @subsection Freeing Discarded Symbols
 @cindex freeing discarded symbols
 @findex %destructor
+@findex %symbol-default
 
 During error recovery (@pxref{Error Recovery}), symbols already pushed
 on the stack and tokens coming from the rest of the file are discarded
@@ -4010,18 +4019,24 @@ Within @var{code}, @code{$$} designates the semantic value associated
 with the discarded symbol, and @code{@@$} designates its location.
 The additional parser parameters are also available (@pxref{Parser Function, ,
 The Parser Function @code{yyparse}}).
-@end deffn
 
-@deffn {Directive} %destructor @{ @var{code} @}
-@cindex default %destructor
-Invoke the braced @var{code} whenever the parser discards any user-defined
-grammar symbol for which the user has not specifically declared any
-@code{%destructor}.
-This is known as the default @code{%destructor}.
-As in the previous form, @code{$$}, @code{@@$}, and the additional parser
-parameters are available.
+When a symbol is listed among @var{symbols}, its @code{%destructor} is called a
+per-symbol @code{%destructor}.
+You may also define a per-type @code{%destructor} by listing a semantic type
+among @var{symbols}.
+In that case, the parser will invoke this @var{code} whenever it discards any
+grammar symbol that has that semantic type unless that symbol has its own
+per-symbol @code{%destructor}.
+
+Finally, you may define a default @code{%destructor} by placing
+@code{%symbol-default} in the @var{symbols} list of exactly one
+@code{%destructor} declaration in your grammar file.
+In that case, the parser will invoke the associated @var{code} whenever it
+discards any user-defined grammar symbol for which there is no per-type or
+per-symbol @code{%destructor}.
 @end deffn
 
+@noindent
 For instance:
 
 @smallexample
@@ -4030,13 +4045,18 @@ For instance:
 %token <string> STRING2
 %type  <string> string1
 %type  <string> string2
-%destructor @{ free ($$); @}
+%union @{ char character; @}
+%token <character> CHR
+%type  <character> chr
+%destructor @{ free ($$); @} %symbol-default
 %destructor @{ free ($$); printf ("%d", @@$.first_line); @} STRING1 string1
+%destructor @{ @} <character>
 @end smallexample
 
 @noindent
-guarantees that, when the parser discards any user-defined symbol, it passes
-its semantic value to @code{free}.
+guarantees that, when the parser discards any user-defined symbol that has a
+semantic type tag other than @code{<character>}, it passes its semantic value
+to @code{free}.
 However, when the parser discards a @code{STRING1} or a @code{string1}, it also
 prints its line number to @code{stdout}.
 It performs only the second @code{%destructor} in this case, so it invokes
@@ -7411,8 +7431,8 @@ factor both as follows.
 
 @comment file: calc++-driver.hh
 @example
-// Announce to Flex the prototype we want for lexing function, ...
-# define YY_DECL                                       \
+// Tell Flex the lexer's prototype ...
+# define YY_DECL                                        \
   yy::calcxx_parser::token_type                         \
   yylex (yy::calcxx_parser::semantic_type* yylval,      \
          yy::calcxx_parser::location_type* yylloc,      \
@@ -7663,7 +7683,9 @@ unit: assignments exp  @{ driver.result = $2; @};
 assignments: assignments assignment @{@}
            | /* Nothing.  */        @{@};
 
-assignment: "identifier" ":=" exp @{ driver.variables[*$1] = $3; @};
+assignment:
+     "identifier" ":=" exp
+       @{ driver.variables[*$1] = $3; delete $1; @};
 
 %left '+' '-';
 %left '*' '/';
@@ -7671,7 +7693,7 @@ exp: exp '+' exp   @{ $$ = $1 + $3; @}
    | exp '-' exp   @{ $$ = $1 - $3; @}
    | exp '*' exp   @{ $$ = $1 * $3; @}
    | exp '/' exp   @{ $$ = $1 / $3; @}
-   | "identifier"  @{ $$ = driver.variables[*$1]; @}
+   | "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
    | "number"      @{ $$ = $1; @};
 %%
 @end example
@@ -7832,8 +7854,8 @@ main (int argc, char *argv[])
       driver.trace_scanning = true;
     else
       @{
-       driver.parse (*argv);
-       std::cout << driver.result << std::endl;
+        driver.parse (*argv);
+        std::cout << driver.result << std::endl;
       @}
 @}
 @end example
@@ -8505,6 +8527,11 @@ Bison declaration to specify the start symbol.  @xref{Start Decl, ,The
 Start-Symbol}.
 @end deffn
 
+@deffn {Directive} %symbol-default
+Used to declare a default @code{%destructor} or default @code{%printer}.
+@xref{Destructor Decl, , Freeing Discarded Symbols}.
+@end deffn
+
 @deffn {Directive} %token
 Bison declaration to declare token(s) without specifying precedence.
 @xref{Token Decl, ,Token Type Names}.