* data/yacc.c (YYSIZE_T): Reindent to make it clearer. This

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index c25813fb608f8216c7cc72fd1ab01681a81ebdd1..eae08d978a961d6e4cf341f4324aff77e3080d29 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -1197,11 +1197,13 @@ function @code{yyerror} and the parser function @code{yyparse} itself.
 This also includes numerous identifiers used for internal purposes.
 Therefore, you should avoid using C identifiers starting with @samp{yy}
 or @samp{YY} in the Bison grammar file except for the ones defined in
 This also includes numerous identifiers used for internal purposes.
 Therefore, you should avoid using C identifiers starting with @samp{yy}
 or @samp{YY} in the Bison grammar file except for the ones defined in

-this manual.
+this manual.  Also, you should avoid using the C identifiers
+@samp{malloc} and @samp{free} for anything other than their usual
+meanings.

 
 In some cases the Bison parser file includes system headers, and in
 those cases your code should respect the identifiers reserved by those
 
 In some cases the Bison parser file includes system headers, and in
 those cases your code should respect the identifiers reserved by those

-headers.  On some non-@acronym{GNU} hosts, @code{<alloca.h>},
+headers.  On some non-@acronym{GNU} hosts, @code{<alloca.h>}, @code{<malloc.h>},

 @code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
 declare memory allocators and related types.  @code{<libintl.h>} is
 included if message translation is in use
 @code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
 declare memory allocators and related types.  @code{<libintl.h>} is
 included if message translation is in use


@@ -1716,12 +1718,12 @@ With all the source in a single file, you use the following command to
 convert it into a parser file:
 
 @example
 convert it into a parser file:
 
 @example

-bison @var{file_name}.y
+bison @var{file}.y

 @end example
 
 @noindent
 In this example the file was called @file{rpcalc.y} (for ``Reverse Polish
 @end example
 
 @noindent
 In this example the file was called @file{rpcalc.y} (for ``Reverse Polish

-@sc{calc}ulator'').  Bison produces a file named @file{@var{file_name}.tab.c},
+@sc{calc}ulator'').  Bison produces a file named @file{@var{file}.tab.c},

 removing the @samp{.y} from the original file name.  The file output by
 Bison contains the source code for @code{yyparse}.  The additional
 functions in the input file (@code{yylex}, @code{yyerror} and @code{main})
 removing the @samp{.y} from the original file name.  The file output by
 Bison contains the source code for @code{yyparse}.  The additional
 functions in the input file (@code{yylex}, @code{yyerror} and @code{main})


@@ -3779,10 +3781,10 @@ Declare that the @var{code} must be invoked before parsing each time
 For instance, if your locations use a file name, you may use
 
 @example
 For instance, if your locations use a file name, you may use
 
 @example

-%parse-param @{ const char *filename @};
+%parse-param @{ char const *file_name @};

 %initial-action
 @{
 %initial-action
 @{

-  @@$.begin.filename = @@$.end.filename = filename;
+  @@$.begin.filename = @@$.end.filename = file_name;

 @};
 @end example
 
 @};
 @end example
 


@@ -4133,7 +4135,7 @@ parser file contains just @code{#define} directives and static variable
 declarations.
 
 This option also tells Bison to write the C code for the grammar actions
 declarations.
 
 This option also tells Bison to write the C code for the grammar actions

-into a file named @file{@var{filename}.act}, in the form of a
+into a file named @file{@var{file}.act}, in the form of a

 brace-surrounded body fit for a @code{switch} statement.
 @end deffn
 
 brace-surrounded body fit for a @code{switch} statement.
 @end deffn
 


@@ -4146,8 +4148,8 @@ associate errors with the parser file, treating it an independent source
 file in its own right.
 @end deffn
 
 file in its own right.
 @end deffn
 

-@deffn {Directive} %output="@var{filename}"
-Specify the @var{filename} for the parser file.
+@deffn {Directive} %output="@var{file}"
+Specify @var{file} for the parser file.

 @end deffn
 
 @deffn {Directive} %pure-parser
 @end deffn
 
 @deffn {Directive} %pure-parser


@@ -4271,7 +4273,11 @@ without reading further.
 The value returned by @code{yyparse} is 0 if parsing was successful (return
 is due to end-of-input).
 
 The value returned by @code{yyparse} is 0 if parsing was successful (return
 is due to end-of-input).
 

-The value is 1 if parsing failed (return is due to a syntax error).
+The value is 1 if parsing failed because of invalid input, i.e., input
+that contains a syntax error or that causes @code{YYABORT} to be
+invoked.
+
+The value is 2 if parsing failed due to memory exhaustion.

 @end deftypefun
 
 In an action, you can cause immediate return from @code{yyparse} by using
 @end deftypefun
 
 In an action, you can cause immediate return from @code{yyparse} by using


@@ -4689,7 +4695,7 @@ preferable since it more accurately describes the return type for
 
 @vindex yynerrs
 The variable @code{yynerrs} contains the number of syntax errors
 
 @vindex yynerrs
 The variable @code{yynerrs} contains the number of syntax errors

-encountered so far.  Normally this variable is global; but if you
+reported so far.  Normally this variable is global; but if you

 request a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser})
 then it is a local variable which only the actions can access.
 
 request a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser})
 then it is a local variable which only the actions can access.
 


@@ -6605,14 +6611,15 @@ bison @var{infile}
 
 Here @var{infile} is the grammar file name, which usually ends in
 @samp{.y}.  The parser file's name is made by replacing the @samp{.y}
 
 Here @var{infile} is the grammar file name, which usually ends in
 @samp{.y}.  The parser file's name is made by replacing the @samp{.y}

-with @samp{.tab.c}.  Thus, the @samp{bison foo.y} filename yields
-@file{foo.tab.c}, and the @samp{bison hack/foo.y} filename yields
-@file{hack/foo.tab.c}.  It's also possible, in case you are writing
+with @samp{.tab.c} and removing any leading directory.  Thus, the
+@samp{bison foo.y} file name yields
+@file{foo.tab.c}, and the @samp{bison hack/foo.y} file name yields
+@file{foo.tab.c}.  It's also possible, in case you are writing

 C++ code instead of C in your grammar file, to name it @file{foo.ypp}
 or @file{foo.y++}.  Then, the output files will take an extension like
 the given one as input (respectively @file{foo.tab.cpp} and
 @file{foo.tab.c++}).
 C++ code instead of C in your grammar file, to name it @file{foo.ypp}
 or @file{foo.y++}.  Then, the output files will take an extension like
 the given one as input (respectively @file{foo.tab.cpp} and
 @file{foo.tab.c++}).

-This feature takes effect with all options that manipulate filenames like
+This feature takes effect with all options that manipulate file names like

 @samp{-o} or @samp{-d}.
 
 For example :
 @samp{-o} or @samp{-d}.
 
 For example :


@@ -6770,11 +6777,11 @@ 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}.
 

-@item -o @var{filename}
-@itemx --output=@var{filename}
-Specify the @var{filename} for the parser file.
+@item -o @var{file}
+@itemx --output=@var{file}
+Specify the @var{file} for the parser file.

 
 

-The other output files' names are constructed from @var{filename} as
+The other output files' names are constructed from @var{file} as

 described under the @samp{-v} and @samp{-d} options.
 
 @item -g
 described under the @samp{-v} and @samp{-d} options.
 
 @item -g


@@ -6786,7 +6793,7 @@ be @file{foo.vcg}.
 @item --graph=@var{graph-file}
 The behavior of @var{--graph} is the same than @samp{-g}.  The only
 difference is that it has an optional argument which is the name of
 @item --graph=@var{graph-file}
 The behavior of @var{--graph} is the same than @samp{-g}.  The only
 difference is that it has an optional argument which is the name of

-the output graph filename.
+the output graph file.

 @end table
 
 @node Option Cross Key
 @end table
 
 @node Option Cross Key


@@ -6902,13 +6909,13 @@ used for location tracking.  @xref{C++ Location Values}.
 @item stack.hh
 An auxiliary class @code{stack} used by the parser.
 
 @item stack.hh
 An auxiliary class @code{stack} used by the parser.
 

-@item @var{filename}.hh
-@itemx @var{filename}.cc
+@item @var{file}.hh
+@itemx @var{file}.cc

 The declaration and implementation of the C++ parser class.
 The declaration and implementation of the C++ parser class.

-@var{filename} is the name of the output file.  It follows the same
+@var{file} is the name of the output file.  It follows the same

 rules as with regular C parsers.
 
 rules as with regular C parsers.
 

-Note that @file{@var{filename}.hh} is @emph{mandatory}, the C++ cannot
+Note that @file{@var{file}.hh} is @emph{mandatory}, the C++ cannot

 work without the parser class declaration.  Therefore, you must either
 pass @option{-d}/@option{--defines} to @command{bison}, or use the
 @samp{%defines} directive.
 work without the parser class declaration.  Therefore, you must either
 pass @option{-d}/@option{--defines} to @command{bison}, or use the
 @samp{%defines} directive.


@@ -6957,7 +6964,7 @@ 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).
 
 and a @code{location}, a range composed of a pair of
 @code{position}s (possibly spanning several files).
 

-@deftypemethod {position} {std::string*} filename
+@deftypemethod {position} {std::string*} file

 The name of the file.  It will always be handled as a pointer, the
 parser will never duplicate nor deallocate it.  As an experimental
 feature you may change it to @samp{@var{type}*} using @samp{%define
 The name of the file.  It will always be handled as a pointer, the
 parser will never duplicate nor deallocate it.  As an experimental
 feature you may change it to @samp{@var{type}*} using @samp{%define


@@ -6989,8 +6996,8 @@ Various forms of syntactic sugar for @code{columns}.
 
 @deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p})
 Report @var{p} on @var{o} like this:
 
 @deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p})
 Report @var{p} on @var{o} like this:

-@samp{@var{filename}:@var{line}.@var{column}}, or
-@samp{@var{line}.@var{column}} if @var{filename} is null.
+@samp{@var{file}:@var{line}.@var{column}}, or
+@samp{@var{line}.@var{column}} if @var{file} is null.

 @end deftypemethod
 
 @deftypemethod {location} {position} begin
 @end deftypemethod
 
 @deftypemethod {location} {position} begin


@@ -7358,7 +7365,7 @@ avoid name clashes.
 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

-%token        YYEOF          0 "end of file"
+%token        TOKEN_EOF      0 "end of file"

 %token        TOKEN_ASSIGN     ":="
 %token <sval> TOKEN_IDENTIFIER "identifier"
 %token <ival> TOKEN_NUMBER     "number"
 %token        TOKEN_ASSIGN     ":="
 %token <sval> TOKEN_IDENTIFIER "identifier"
 %token <ival> TOKEN_NUMBER     "number"


@@ -7425,6 +7432,9 @@ parser's to get the set of defined tokens.
 @comment file: calc++-scanner.ll
 @example
 %@{                                            /* -*- C++ -*- */
 @comment file: calc++-scanner.ll
 @example
 %@{                                            /* -*- C++ -*- */

+# include <cstdlib>
+# include <errno.h>
+# include <limits.h>

 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"


@@ -7482,7 +7492,14 @@ errors.
 @example
 [-+*/]     return yytext[0];
 ":="       return TOKEN_ASSIGN;
 @example
 [-+*/]     return yytext[0];
 ":="       return TOKEN_ASSIGN;

-@{int@}      yylval->ival = atoi (yytext); return TOKEN_NUMBER;
+@{int@}      @{
+  errno = 0;
+  long n = strtol (yytext, NULL, 10);
+  if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
+    driver.error (*yylloc, "integer is out of range");
+  yylval->ival = n;
+  return TOKEN_NUMBER;
+@}

 @{id@}       yylval->sval = new std::string (yytext); return TOKEN_IDENTIFIER;
 .          driver.error (*yylloc, "invalid character");
 %%
 @{id@}       yylval->sval = new std::string (yytext); return TOKEN_IDENTIFIER;
 .          driver.error (*yylloc, "invalid character");
 %%


@@ -7520,7 +7537,7 @@ The top level file, @file{calc++.cc}, poses no problem.
 #include "calc++-driver.hh"
 
 int
 #include "calc++-driver.hh"
 
 int

-main (int argc, const char* argv[])
+main (int argc, char *argv[])

 @{
   calcxx_driver driver;
   for (++argv; argv[0]; ++argv)
 @{
   calcxx_driver driver;
   for (++argv; argv[0]; ++argv)


@@ -7913,7 +7930,7 @@ Bison declaration to assign non-associativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 

-@deffn {Directive} %output="@var{filename}"
+@deffn {Directive} %output="@var{file}"

 Bison declaration to set the name of the parser file.  @xref{Decl
 Summary}.
 @end deffn
 Bison declaration to set the name of the parser file.  @xref{Decl
 Summary}.
 @end deffn


@@ -8082,7 +8099,7 @@ Management}.
 @end deffn
 
 @deffn {Variable} yynerrs
 @end deffn
 
 @deffn {Variable} yynerrs

-Global variable which Bison increments each time there is a syntax error.
+Global variable which Bison increments each time it reports a syntax error.

 (In a pure parser, it is a local variable within @code{yyparse}.)
 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
 @end deffn
 (In a pure parser, it is a local variable within @code{yyparse}.)
 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
 @end deffn


@@ -8112,10 +8129,7 @@ the parser will use @code{malloc} to extend its stacks.  If defined to
 reserved for future Bison extensions.  If not defined,
 @code{YYSTACK_USE_ALLOCA} defaults to 0.
 
 reserved for future Bison extensions.  If not defined,
 @code{YYSTACK_USE_ALLOCA} defaults to 0.
 

-If you define @code{YYSTACK_USE_ALLOCA} to 1, it is your
-responsibility to make sure that @code{alloca} is visible, e.g., by
-using @acronym{GCC} or by including @code{<stdlib.h>}.  Furthermore,
-in the all-too-common case where your code may run on a host with a
+In the all-too-common case where your code may run on a host with a

 limited stack and with unreliable stack-overflow checking, you should
 set @code{YYMAXDEPTH} to a value that cannot possibly result in
 unchecked stack overflow on any of your target hosts when
 limited stack and with unreliable stack-overflow checking, you should
 set @code{YYMAXDEPTH} to a value that cannot possibly result in
 unchecked stack overflow on any of your target hosts when