(Torturing the Scanner): Don't invoke "cc a.c b.c

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 290cbab3bf05dcf2db08c0e6574e60ec5e63e762..645a5eba2bd4d31ee70c8eea6ed673045f58e1e0 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -208,6 +208,7 @@ Bison Declarations
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Union Decl::        Declaring the set of all semantic value types.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Union Decl::        Declaring the set of all semantic value types.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.

+* Destructor Decl::   Declaring how symbols are freed.

 * Expect Decl::       Suppressing warnings about shift/reduce conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Expect Decl::       Suppressing warnings about shift/reduce conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.


@@ -268,7 +269,6 @@ Invoking Bison
 * Bison Options::     All the options described in detail,
                         in alphabetical order by short options.
 * Option Cross Key::  Alphabetical list of long options.
 * Bison Options::     All the options described in detail,
                         in alphabetical order by short options.
 * Option Cross Key::  Alphabetical list of long options.

-* VMS Invocation::    Bison command syntax on @acronym{VMS}.

 
 Frequently Asked Questions
 
 
 Frequently Asked Questions
 


@@ -1357,7 +1357,7 @@ here is the definition we will use:
 #include <stdio.h>
 
 void
 #include <stdio.h>
 
 void

-yyerror (const char *s)  /* called by yyparse on error */
+yyerror (const char *s)  /* Called by yyparse on error.  */

 @{
   printf ("%s\n", s);
 @}
 @{
   printf ("%s\n", s);
 @}


@@ -1852,7 +1852,6 @@ symrec  *tptr;   /* For returning symbol-table pointers      */
 %right '^'    /* Exponentiation        */
 
 /* Grammar follows */
 %right '^'    /* Exponentiation        */
 
 /* Grammar follows */

-

 %%
 @end smallexample
 
 %%
 @end smallexample
 


@@ -1929,7 +1928,9 @@ provides for either functions or variables to be placed in the table.
 @group
 /* Function type.                                    */
 typedef double (*func_t) (double);
 @group
 /* Function type.                                    */
 typedef double (*func_t) (double);

+@end group

 
 

+@group

 /* Data type for links in the chain of symbols.      */
 struct symrec
 @{
 /* Data type for links in the chain of symbols.      */
 struct symrec
 @{


@@ -1973,7 +1974,7 @@ main (void)
 
 @group
 void
 
 @group
 void

-yyerror (const char *s)  /* Called by yyparse on error */
+yyerror (const char *s)  /* Called by yyparse on error.  */

 @{
   printf ("%s\n", s);
 @}
 @{
   printf ("%s\n", s);
 @}


@@ -2749,11 +2750,11 @@ a-or-b: 'a'|'b'   @{ a_or_b_found = 1; @};
 
 @cindex default action
 If you don't specify an action for a rule, Bison supplies a default:
 
 @cindex default action
 If you don't specify an action for a rule, Bison supplies a default:

-@w{@code{$$ = $1}.}  Thus, the value of the first symbol in the rule becomes
-the value of the whole rule.  Of course, the default rule 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.
+@w{@code{$$ = $1}.}  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.

 
 @code{$@var{n}} with @var{n} zero or negative is allowed for reference
 to tokens and groupings on the stack @emph{before} those that match the
 
 @code{$@var{n}} with @var{n} zero or negative is allowed for reference
 to tokens and groupings on the stack @emph{before} those that match the


@@ -3175,6 +3176,7 @@ Grammars}).
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Union Decl::        Declaring the set of all semantic value types.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Union Decl::        Declaring the set of all semantic value types.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.

+* Destructor Decl::   Declaring how symbols are freed.

 * Expect Decl::       Suppressing warnings about shift/reduce conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Expect Decl::       Suppressing warnings about shift/reduce conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.


@@ -3365,6 +3367,71 @@ use the same @code{<@var{type}>} construction in a declaration for the
 terminal symbol.  All kinds of token declarations allow
 @code{<@var{type}>}.
 
 terminal symbol.  All kinds of token declarations allow
 @code{<@var{type}>}.
 

+@node Destructor Decl
+@subsection Freeing Discarded Symbols
+@cindex freeing discarded symbols
+@findex %destructor
+
+Some symbols can be discarded by the parser, typically during error
+recovery (@pxref{Error Recovery}).  Basically, during error recovery,
+embarrassing symbols already pushed on the stack, and embarrassing
+tokens coming from the rest of the file are thrown away until the parser
+falls on its feet.  If these symbols convey heap based information, this
+memory is lost.  While this behavior is tolerable for batch parsers,
+such as in compilers, it is unacceptable for parsers that can
+possibility ``never end'' such as shells, or implementations of
+communication protocols.
+
+The @code{%destructor} directive allows for the definition of code that
+is called when a symbol is thrown away.
+
+@deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
+@findex %destructor
+Declare that the @var{code} must be invoked for each of the
+@var{symbols} that will be discarded by the parser.  The @var{code}
+should use @code{$$} to designate the semantic value associated to the
+@var{symbols}.  The additional parser parameters are also avaible
+(@pxref{Parser Function, , The Parser Function @code{yyparse}}).
+
+@strong{Warning:} as of Bison 1.875, this feature is still considered as
+experimental, as there was not enough users feedback.  In particular,
+the syntax might still change.
+@end deffn
+
+For instance:
+
+@smallexample
+%union
+@{
+  char *string;
+@}
+%token <string> STRING
+%type  <string> string
+%destructor @{ free ($$); @} STRING string
+@end smallexample
+
+@noindent
+guarantees that when a @code{STRING} or a @code{string} will be discarded,
+its associated memory will be freed.
+
+Note that in the future, Bison might also consider that right hand side
+members that are not mentioned in the action can be destroyed.  For
+instance, in:
+
+@smallexample
+comment: "/*" STRING "*/";
+@end smallexample
+
+@noindent
+the parser is entitled to destroy the semantic value of the
+@code{string}.  Of course, this will not apply to the default action;
+compare:
+
+@smallexample
+typeless: string;  // $$ = $1 does not apply; $1 is destroyed.
+typefull: string;  // $$ = $1 applies, $1 is not destroyed.
+@end smallexample
+

 @node Expect Decl
 @subsection Suppressing Conflict Warnings
 @cindex suppressing conflict warnings
 @node Expect Decl
 @subsection Suppressing Conflict Warnings
 @cindex suppressing conflict warnings


@@ -3536,6 +3603,10 @@ This output file is essential if you wish to put the definition of
 be able to refer to token type codes and the variable
 @code{yylval}.  @xref{Token Values, ,Semantic Values of Tokens}.
 
 be able to refer to token type codes and the variable
 @code{yylval}.  @xref{Token Values, ,Semantic Values of Tokens}.
 

+@item %destructor
+Specifying how the parser should reclaim the memory associated to
+discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
+

 @item %file-prefix="@var{prefix}"
 Specify a prefix to use for all Bison output file names.  The names are
 chosen as if the input file were named @file{@var{prefix}.y}.
 @item %file-prefix="@var{prefix}"
 Specify a prefix to use for all Bison output file names.  The names are
 chosen as if the input file were named @file{@var{prefix}.y}.


@@ -3635,8 +3706,6 @@ parser states and what is done for each type of look-ahead token in
 that state.  @xref{Understanding, , Understanding Your Parser}, for more
 information.
 
 that state.  @xref{Understanding, , Understanding Your Parser}, for more
 information.
 

-
-

 @item %yacc
 Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
 including its naming conventions.  @xref{Bison Options}, for more.
 @item %yacc
 Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
 including its naming conventions.  @xref{Bison Options}, for more.


@@ -4050,7 +4119,7 @@ The following definition suffices in simple programs:
 @example
 @group
 void
 @example
 @group
 void

-yyerror (char *s)
+yyerror (const char *s)

 @{
 @end group
 @group
 @{
 @end group
 @group


@@ -4064,7 +4133,7 @@ error recovery if you have written suitable error recovery grammar rules
 (@pxref{Error Recovery}).  If recovery is impossible, @code{yyparse} will
 immediately return 1.
 
 (@pxref{Error Recovery}).  If recovery is impossible, @code{yyparse} will
 immediately return 1.
 

-Oviously, in location tracking pure parsers, @code{yyerror} should have
+Obviously, in location tracking pure parsers, @code{yyerror} should have

 an access to the current location.  This is indeed the case for the GLR
 parsers, but not for the Yacc parser, for historical reasons.  I.e., if
 @samp{%locations %pure-parser} is passed then the prototypes for
 an access to the current location.  This is indeed the case for the GLR
 parsers, but not for the Yacc parser, for historical reasons.  I.e., if
 @samp{%locations %pure-parser} is passed then the prototypes for


@@ -4072,14 +4141,14 @@ parsers, but not for the Yacc parser, for historical reasons.  I.e., if
 
 @example
 void yyerror (const char *msg);                 /* Yacc parsers.  */
 
 @example
 void yyerror (const char *msg);                 /* Yacc parsers.  */

-void yyerror (const char *msg, YYLTYPE *locp);  /* GLR parsers.   */
+void yyerror (YYLTYPE *locp, const char *msg);  /* GLR parsers.   */

 @end example
 
 If @samp{%parse-param "int *nastiness"  "nastiness"} is used, then:
 
 @example
 @end example
 
 If @samp{%parse-param "int *nastiness"  "nastiness"} is used, then:
 
 @example

-void yyerror (int *randomness);  /* Yacc parsers.  */
-void yyerror (int *randomness);  /* GLR parsers.   */
+void yyerror (int *randomness, const char *msg);  /* Yacc parsers.  */
+void yyerror (int *randomness, const char *msg);  /* GLR parsers.   */

 @end example
 
 Finally, GLR and Yacc parsers share the same @code{yyerror} calling
 @end example
 
 Finally, GLR and Yacc parsers share the same @code{yyerror} calling


@@ -4104,10 +4173,17 @@ results in the following signatures for all the parser kinds:
 @example
 int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
 int yyparse (int *nastiness, int *randomness);
 @example
 int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
 int yyparse (int *nastiness, int *randomness);

-void yyerror (const char *msg, YYLTYPE *locp,
-              int *nastiness, int *randomness);
+void yyerror (YYLTYPE *locp,
+              int *nastiness, int *randomness,
+              const char *msg);

 @end example
 
 @end example
 

+@noindent
+Please, note that the prototypes are only indications of how the code
+produced by Bison will use @code{yyerror}; you still have freedom on the
+exit value, and even on making @code{yyerror} a variadic function.  It
+is precisely to enable this that the message is always passed last.
+

 @vindex yynerrs
 The variable @code{yynerrs} contains the number of syntax errors
 encountered so far.  Normally this variable is global; but if you
 @vindex yynerrs
 The variable @code{yynerrs} contains the number of syntax errors
 encountered so far.  Normally this variable is global; but if you


@@ -5063,15 +5139,17 @@ will be tokens to read before the next newline.  So the rule is not
 applicable in the ordinary way.
 
 But Bison can force the situation to fit the rule, by discarding part of
 applicable in the ordinary way.
 
 But Bison can force the situation to fit the rule, by discarding part of

-the semantic context and part of the input.  First it discards states and
-objects from the stack until it gets back to a state in which the
+the semantic context and part of the input.  First it discards states
+and objects from the stack until it gets back to a state in which the

 @code{error} token is acceptable.  (This means that the subexpressions
 @code{error} token is acceptable.  (This means that the subexpressions

-already parsed are discarded, back to the last complete @code{stmnts}.)  At
-this point the @code{error} token can be shifted.  Then, if the old
+already parsed are discarded, back to the last complete @code{stmnts}.)
+At this point the @code{error} token can be shifted.  Then, if the old

 look-ahead token is not acceptable to be shifted next, the parser reads
 tokens and discards them until it finds a token which is acceptable.  In
 look-ahead token is not acceptable to be shifted next, the parser reads
 tokens and discards them until it finds a token which is acceptable.  In

-this example, Bison reads and discards input until the next newline
-so that the fourth rule can apply.
+this example, Bison reads and discards input until the next newline so
+that the fourth rule can apply.  Note that discarded symbols are
+possible sources of memory leaks, see @ref{Destructor Decl, , Freeing
+Discarded Symbols}, for a means to reclaim this memory.

 
 The choice of error rules in the grammar is a choice of strategies for
 error recovery.  A simple and useful strategy is simply to skip the rest of
 
 The choice of error rules in the grammar is a choice of strategies for
 error recovery.  A simple and useful strategy is simply to skip the rest of


@@ -5899,7 +5977,6 @@ will produce @file{output.c++} and @file{outfile.h++}.
 * Bison Options::     All the options described in detail,
                         in alphabetical order by short options.
 * Option Cross Key::  Alphabetical list of long options.
 * Bison Options::     All the options described in detail,
                         in alphabetical order by short options.
 * Option Cross Key::  Alphabetical list of long options.

-* VMS Invocation::    Bison command syntax on @acronym{VMS}.

 @end menu
 
 @node Bison Options
 @end menu
 
 @node Bison Options


@@ -6091,34 +6168,6 @@ the corresponding short option.
 @end example
 @end ifinfo
 
 @end example
 @end ifinfo
 

-@node VMS Invocation
-@section Invoking Bison under @acronym{VMS}
-@cindex invoking Bison under @acronym{VMS}
-@cindex @acronym{VMS}
-
-The command line syntax for Bison on @acronym{VMS} is a variant of the usual
-Bison command syntax---adapted to fit @acronym{VMS} conventions.
-
-To find the @acronym{VMS} equivalent for any Bison option, start with the long
-option, and substitute a @samp{/} for the leading @samp{--}, and
-substitute a @samp{_} for each @samp{-} in the name of the long option.
-For example, the following invocation under @acronym{VMS}:
-
-@example
-bison /debug/name_prefix=bar foo.y
-@end example
-
-@noindent
-is equivalent to the following command under @acronym{POSIX}.
-
-@example
-bison --debug --name-prefix=bar foo.y
-@end example
-
-The @acronym{VMS} file system does not permit filenames such as
-@file{foo.tab.c}.  In the above example, the output file
-would instead be named @file{foo_tab.c}.
-

 @c ================================================= Invoking Bison
 
 @node FAQ
 @c ================================================= Invoking Bison
 
 @node FAQ


@@ -6325,6 +6374,10 @@ Equip the parser for debugging.  @xref{Decl Summary}.
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.
 
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.
 

+@item %destructor
+Specifying how the parser should reclaim the memory associated to
+discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
+

 @item %dprec
 Bison declaration to assign a precedence to a rule that is used at parse
 time to resolve reduce/reduce conflicts.  @xref{GLR Parsers, ,Writing
 @item %dprec
 Bison declaration to assign a precedence to a rule that is used at parse
 time to resolve reduce/reduce conflicts.  @xref{GLR Parsers, ,Writing