Fix test failure reported by Tom Lane in

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index e40788c5984988ea7aecfa6d891ea928e89a0f43..013847b5d884e5d9ea3a854f4d8fd79762417868 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -1998,7 +1998,9 @@ type for storing locations is not needed: we will use the type provided
 by default (@pxref{Location Type, ,Data Types of Locations}), which is a
 four member structure with the following integer fields:
 @code{first_line}, @code{first_column}, @code{last_line} and
 by default (@pxref{Location Type, ,Data Types of Locations}), which is a
 four member structure with the following integer fields:
 @code{first_line}, @code{first_column}, @code{last_line} and

-@code{last_column}.
+@code{last_column}.  By conventions, and in accordance with the GNU
+Coding Standards and common practice, the line and column count both
+start at 1.

 
 @node Ltcalc Rules
 @subsection Grammar Rules for @code{ltcalc}
 
 @node Ltcalc Rules
 @subsection Grammar Rules for @code{ltcalc}


@@ -2633,7 +2635,7 @@ they precede the definition of @code{yyparse}.  You can use
 don't need any C declarations, you may omit the @samp{%@{} and
 @samp{%@}} delimiters that bracket this section.
 
 don't need any C declarations, you may omit the @samp{%@{} and
 @samp{%@}} delimiters that bracket this section.
 

-The @var{Prologue} section is terminated by the the first occurrence
+The @var{Prologue} section is terminated by the first occurrence

 of @samp{%@}} that is outside a comment, a string literal, or a
 character constant.
 
 of @samp{%@}} that is outside a comment, a string literal, or a
 character constant.
 


@@ -2647,6 +2649,7 @@ can be done with two @var{Prologue} blocks, one before and one after the
 
 @smallexample
 %@{
 
 @smallexample
 %@{

+  #define _GNU_SOURCE

   #include <stdio.h>
   #include "ptypes.h"
 %@}
   #include <stdio.h>
   #include "ptypes.h"
 %@}


@@ -2664,6 +2667,13 @@ can be done with two @var{Prologue} blocks, one before and one after the
 @dots{}
 @end smallexample
 
 @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
 @findex %before-header
 @findex %start-header
 @findex %after-header


@@ -3090,7 +3100,8 @@ the semantic values of all language constructs.  This was true in the
 @acronym{RPN} and infix calculator examples (@pxref{RPN Calc, ,Reverse Polish
 Notation Calculator}).
 
 @acronym{RPN} and infix calculator examples (@pxref{RPN Calc, ,Reverse Polish
 Notation Calculator}).
 

-Bison's default is to use type @code{int} for all semantic values.  To
+Bison normally uses the type @code{int} for semantic values if your
+program uses the same data type for all language constructs.  To

 specify some other type, define @code{YYSTYPE} as a macro, like this:
 
 @example
 specify some other type, define @code{YYSTYPE} as a macro, like this:
 
 @example


@@ -3117,9 +3128,11 @@ requires you to do two things:
 
 @itemize @bullet
 @item
 
 @itemize @bullet
 @item

-Specify the entire collection of possible data types, with the
+Specify the entire collection of possible data types, either by using the

 @code{%union} Bison declaration (@pxref{Union Decl, ,The Collection of
 @code{%union} Bison declaration (@pxref{Union Decl, ,The Collection of

-Value Types}).
+Value Types}), or by using a @code{typedef} or a @code{#define} to
+define @code{YYSTYPE} to be a union type whose member names are
+the type tags.

 
 @item
 Choose one of those types for each symbol (terminal or nonterminal) for
 
 @item
 Choose one of those types for each symbol (terminal or nonterminal) for


@@ -3343,8 +3356,8 @@ it might discard the previous semantic context @code{$<context>5} without
 restoring it.
 Thus, @code{$<context>5} needs a destructor (@pxref{Destructor Decl, , Freeing
 Discarded Symbols}).
 restoring it.
 Thus, @code{$<context>5} needs a destructor (@pxref{Destructor Decl, , Freeing
 Discarded Symbols}).

-However, Bison currently provides no means to declare a destructor for a
-mid-rule action's semantic value.
+However, Bison currently provides no means to declare a destructor specific to
+a particular mid-rule action's semantic value.

 
 One solution is to bury the mid-rule action inside a nonterminal symbol and to
 declare a destructor for that symbol:
 
 One solution is to bury the mid-rule action inside a nonterminal symbol and to
 declare a destructor for that symbol:


@@ -3498,7 +3511,7 @@ since all tokens and groupings always use the same type.
 
 You can specify the type of locations by defining a macro called
 @code{YYLTYPE}, just as you can specify the semantic value type by
 
 You can specify the type of locations by defining a macro called
 @code{YYLTYPE}, just as you can specify the semantic value type by

-defining @code{YYSTYPE} (@pxref{Value Type}).
+defining a @code{YYSTYPE} macro (@pxref{Value Type}).

 When @code{YYLTYPE} is not defined, Bison uses a default structure type with
 four members:
 
 When @code{YYLTYPE} is not defined, Bison uses a default structure type with
 four members:
 


@@ -3512,6 +3525,9 @@ typedef struct YYLTYPE
 @} YYLTYPE;
 @end example
 
 @} YYLTYPE;
 @end example
 

+At the beginning of the parsing, Bison initializes all these fields to 1
+for @code{yylloc}.
+

 @node Actions and Locations
 @subsection Actions and Locations
 @cindex location actions
 @node Actions and Locations
 @subsection Actions and Locations
 @cindex location actions


@@ -3890,6 +3906,35 @@ only the first @code{%union} declaration can specify a tag.
 Note that, unlike making a @code{union} declaration in C, you need not write
 a semicolon after the closing brace.
 
 Note that, unlike making a @code{union} declaration in C, you need not write
 a semicolon after the closing brace.
 

+Instead of @code{%union}, you can define and use your own union type
+@code{YYSTYPE} if your grammar contains at least one
+@samp{<@var{type}>} tag.  For example, you can put the following into
+a header file @file{parser.h}:
+
+@example
+@group
+union YYSTYPE @{
+  double val;
+  symrec *tptr;
+@};
+typedef union YYSTYPE YYSTYPE;
+@end group
+@end example
+
+@noindent
+and then your grammar can use the following
+instead of @code{%union}:
+
+@example
+@group
+%@{
+#include "parser.h"
+%@}
+%type <val> expr
+%token <tptr> ID
+@end group
+@end example
+

 @node Type Decl
 @subsection Nonterminal Symbols
 @cindex declaring value types, nonterminals
 @node Type Decl
 @subsection Nonterminal Symbols
 @cindex declaring value types, nonterminals


@@ -3949,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
 @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
 
 During error recovery (@pxref{Error Recovery}), symbols already pushed
 on the stack and tokens coming from the rest of the file are discarded


@@ -3970,26 +4016,73 @@ symbol is automatically discarded.
 Invoke the braced @var{code} whenever the parser discards one of the
 @var{symbols}.
 Within @var{code}, @code{$$} designates the semantic value associated
 Invoke the braced @var{code} whenever the parser discards one of the
 @var{symbols}.
 Within @var{code}, @code{$$} designates the semantic value associated

-with the discarded symbol.  The additional parser parameters are also
-available (@pxref{Parser Function, , The Parser Function
-@code{yyparse}}).
+with the discarded symbol, and @code{@@$} designates its location.
+The additional parser parameters are also available (@pxref{Parser Function, ,
+The Parser Function @code{yyparse}}).
+
+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
 
 @end deffn
 

+@noindent

 For instance:
 
 @smallexample
 For instance:
 
 @smallexample

-%union
-@{
-  char *string;
-@}
-%token <string> STRING
-%type  <string> string
-%destructor @{ free ($$); @} STRING string
+%union @{ char *string; @}
+%token <string> STRING1
+%token <string> STRING2
+%type  <string> string1
+%type  <string> string2
+%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
 @end smallexample
 
 @noindent

-guarantees that when a @code{STRING} or a @code{string} is discarded,
-its associated memory will be freed.
+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
+@code{free} only once.
+
+Notice that a Bison-generated parser invokes the default @code{%destructor}
+only for user-defined as opposed to Bison-defined symbols.
+For example, the parser will not invoke it for the special Bison-defined
+symbols @code{$accept}, @code{$undefined}, or @code{$end} (@pxref{Table of
+Symbols, ,Bison Symbols}), none of which you can reference in your grammar.
+It also will not invoke it for the @code{error} token (@pxref{Table of Symbols,
+,error}), which is always defined by Bison regardless of whether you reference
+it in your grammar.
+However, it will invoke it for the end token (token 0) if you redefine it from
+@code{$end} to, for example, @code{END}:
+
+@smallexample
+%token END 0
+@end smallexample
+
+@ignore
+@noindent
+In the future, it may be possible to redefine the @code{error} token as a
+nonterminal that captures the discarded symbols.
+In that case, the parser will invoke the default destructor for it as well.
+@end ignore

 
 @sp 1
 
 
 @sp 1
 


@@ -4207,10 +4300,13 @@ names defined in the grammar as well as a few other declarations.
 If the parser output file is named @file{@var{name}.c} then this file
 is named @file{@var{name}.h}.
 
 If the parser output file is named @file{@var{name}.c} then this file
 is named @file{@var{name}.h}.
 

-Unless @code{YYSTYPE} is already defined as a macro, the output header
-declares @code{YYSTYPE}.  Therefore, if you are using a @code{%union}
+For C parsers, the output header declares @code{YYSTYPE} unless
+@code{YYSTYPE} is already defined as a macro or you have used a
+@code{<@var{type}>} tag without using @code{%union}.
+Therefore, if you are using a @code{%union}

 (@pxref{Multiple Types, ,More Than One Value Type}) with components that
 require other definitions, or if you have defined a @code{YYSTYPE} macro
 (@pxref{Multiple Types, ,More Than One Value Type}) with components that
 require other definitions, or if you have defined a @code{YYSTYPE} macro

+or type definition

 (@pxref{Value Type, ,Data Types of Semantic Values}), you need to
 arrange for these definitions to be propagated to all modules, e.g., by
 putting them in a prerequisite header that is included both by your
 (@pxref{Value Type, ,Data Types of Semantic Values}), you need to
 arrange for these definitions to be propagated to all modules, e.g., by
 putting them in a prerequisite header that is included both by your


@@ -4222,7 +4318,7 @@ Parser}.
 
 If you have also used locations, the output header declares
 @code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
 
 If you have also used locations, the output header declares
 @code{YYLTYPE} and @code{yylloc} using a protocol similar to that of

-@code{YYSTYPE} and @code{yylval}.  @xref{Locations, ,Tracking
+the @code{YYSTYPE} macro and @code{yylval}.  @xref{Locations, ,Tracking

 Locations}.
 
 This output file is normally essential if you wish to put the definition
 Locations}.
 
 This output file is normally essential if you wish to put the definition


@@ -6710,7 +6806,7 @@ The trace facility outputs messages with macro calls of the form
 @var{format} and @var{args} are the usual @code{printf} format and
 arguments.  If you define @code{YYDEBUG} to a nonzero value but do not
 define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included
 @var{format} and @var{args} are the usual @code{printf} format and
 arguments.  If you define @code{YYDEBUG} to a nonzero value but do not
 define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included

-and @code{YYPRINTF} is defined to @code{fprintf}.
+and @code{YYFPRINTF} is defined to @code{fprintf}.

 
 Once you have compiled the program with trace facilities, the way to
 request a trace is to store a nonzero value in the variable @code{yydebug}.
 
 Once you have compiled the program with trace facilities, the way to
 request a trace is to store a nonzero value in the variable @code{yydebug}.


@@ -6941,7 +7037,7 @@ Same as above, but save in the file @var{defines-file}.
 
 @item -b @var{file-prefix}
 @itemx --file-prefix=@var{prefix}
 
 @item -b @var{file-prefix}
 @itemx --file-prefix=@var{prefix}

-Pretend that @code{%file-prefix} was specified, i.e, specify prefix to use
+Pretend that @code{%file-prefix} was specified, i.e., specify prefix to use

 for all Bison output file names.  @xref{Decl Summary}.
 
 @item -r @var{things}
 for all Bison output file names.  @xref{Decl Summary}.
 
 @item -r @var{things}


@@ -6965,7 +7061,7 @@ the full set of items for each state, instead of its core only.
 
 @item -v
 @itemx --verbose
 
 @item -v
 @itemx --verbose

-Pretend that @code{%verbose} was specified, i.e, write an extra output
+Pretend that @code{%verbose} was specified, i.e., write an extra output

 file containing verbose descriptions of the grammar and
 parser.  @xref{Decl Summary}.
 
 file containing verbose descriptions of the grammar and
 parser.  @xref{Decl Summary}.
 


@@ -7335,8 +7431,8 @@ factor both as follows.
 
 @comment file: calc++-driver.hh
 @example
 
 @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,      \
   yy::calcxx_parser::token_type                         \
   yylex (yy::calcxx_parser::semantic_type* yylval,      \
          yy::calcxx_parser::location_type* yylloc,      \


@@ -7366,7 +7462,6 @@ public:
 @noindent
 To encapsulate the coordination with the Flex scanner, it is useful to
 have two members function to open and close the scanning phase.
 @noindent
 To encapsulate the coordination with the Flex scanner, it is useful to
 have two members function to open and close the scanning phase.

-members.

 
 @comment file: calc++-driver.hh
 @example
 
 @comment file: calc++-driver.hh
 @example


@@ -7588,7 +7683,9 @@ unit: assignments exp  @{ driver.result = $2; @};
 assignments: assignments assignment @{@}
            | /* Nothing.  */        @{@};
 
 assignments: assignments assignment @{@}
            | /* Nothing.  */        @{@};
 

-assignment: "identifier" ":=" exp @{ driver.variables[*$1] = $3; @};
+assignment:
+     "identifier" ":=" exp
+       @{ driver.variables[*$1] = $3; delete $1; @};

 
 %left '+' '-';
 %left '*' '/';
 
 %left '+' '-';
 %left '*' '/';


@@ -7596,7 +7693,7 @@ exp: exp '+' exp   @{ $$ = $1 + $3; @}
    | exp '-' exp   @{ $$ = $1 - $3; @}
    | exp '*' exp   @{ $$ = $1 * $3; @}
    | 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
    | "number"      @{ $$ = $1; @};
 %%
 @end example


@@ -7757,8 +7854,8 @@ main (int argc, char *argv[])
       driver.trace_scanning = true;
     else
       @{
       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
       @}
 @}
 @end example


@@ -8430,6 +8527,11 @@ Bison declaration to specify the start symbol.  @xref{Start Decl, ,The
 Start-Symbol}.
 @end deffn
 
 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}.
 @deffn {Directive} %token
 Bison declaration to declare token(s) without specifying precedence.
 @xref{Token Decl, ,Token Type Names}.


@@ -8831,7 +8933,7 @@ grammatically indivisible.  The piece of text it represents is a token.
 @c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH
 @c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm VCG notype
 @c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args
 @c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH
 @c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm VCG notype
 @c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args

-@c LocalWords: YYPRINTF infile ypp yxx outfile itemx vcg tex leaderfill
+@c LocalWords: infile ypp yxx outfile itemx vcg tex leaderfill

 @c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll
 @c LocalWords: yyrestart nbar yytext fst snd osplit ntwo strdup AST
 @c LocalWords: YYSTACK DVI fdl printindex
 @c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll
 @c LocalWords: yyrestart nbar yytext fst snd osplit ntwo strdup AST
 @c LocalWords: YYSTACK DVI fdl printindex