DJGPP specific replacement file for lib/subpipe.c.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 50f1f42a2198f54f60b26d01eb28db27558fbb2e..36ee6470a2b46fca4368c58f7d247a5274c397c3 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


@@ -4693,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.
 


@@ -6931,12 +6933,13 @@ for a complete and accurate documentation.
 The @code{%union} directive works as for C, see @ref{Union Decl, ,The
 Collection of Value Types}.  In particular it produces a genuine
 @code{union}@footnote{In the future techniques to allow complex types
 The @code{%union} directive works as for C, see @ref{Union Decl, ,The
 Collection of Value Types}.  In particular it produces a genuine
 @code{union}@footnote{In the future techniques to allow complex types

-within pseudo-unions (variants) might be implemented to alleviate
-these issues.}, which have a few specific features in C++.
+within pseudo-unions (similar to Boost variants) might be implemented to
+alleviate these issues.}, which have a few specific features in C++.

 @itemize @minus
 @item
 @itemize @minus
 @item

-The name @code{YYSTYPE} also denotes @samp{union YYSTYPE}.  You may
-forward declare it just with @samp{union YYSTYPE;}.
+The type @code{YYSTYPE} is defined but its use is discouraged: rather
+you should refer to the parser's encapsulated type
+@code{yy::parser::semantic_type}.

 @item
 Non POD (Plain Old Data) types cannot be used.  C++ forbids any
 instance of classes with constructors in unions: only @emph{pointers}
 @item
 Non POD (Plain Old Data) types cannot be used.  C++ forbids any
 instance of classes with constructors in unions: only @emph{pointers}


@@ -7137,7 +7140,8 @@ transforming the simple parsing context structure into a fully blown
 
 The declaration of this driver class, @file{calc++-driver.hh}, is as
 follows.  The first part includes the CPP guard and imports the
 
 The declaration of this driver class, @file{calc++-driver.hh}, is as
 follows.  The first part includes the CPP guard and imports the

-required standard library components.
+required standard library components, and the declaration of the parser
+class.

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


@@ -7145,26 +7149,9 @@ required standard library components.
 # define CALCXX_DRIVER_HH
 # include <string>
 # include <map>
 # define CALCXX_DRIVER_HH
 # include <string>
 # include <map>

+# include "calc++-parser.hh"

 @end example
 
 @end example
 

-@noindent
-Then come forward declarations.  Because the parser uses the parsing
-driver and reciprocally, simple inclusions of header files will not
-do.  Because the driver's declaration is the one that will be imported
-by the rest of the project, it is saner to forward declare the
-parser's information here.
-
-@comment file: calc++-driver.hh
-@example
-// Forward declarations.
-union YYSTYPE;
-namespace yy
-@{
-  class location;
-  class calcxx_parser;
-@}
-class calcxx_driver;
-@end example

 
 @noindent
 Then comes the declaration of the scanning function.  Flex expects
 
 @noindent
 Then comes the declaration of the scanning function.  Flex expects


@@ -7176,7 +7163,9 @@ factor both as follows.
 @example
 // Announce to Flex the prototype we want for lexing function, ...
 # define YY_DECL                                                \
 @example
 // Announce to Flex the prototype we want for lexing function, ...
 # define YY_DECL                                                \

-  int yylex (YYSTYPE* yylval, yy::location* yylloc, calcxx_driver& driver)
+  int yylex (yy::calcxx_parser::semantic_type* yylval,           \
+             yy::calcxx_parser::location_type* yylloc,           \
+             calcxx_driver& driver)

 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example
 // ... and declare it for the parser's sake.
 YY_DECL;
 @end example


@@ -7287,18 +7276,29 @@ calcxx_driver::error (const std::string& m)
 @subsection Calc++ Parser
 
 The parser definition file @file{calc++-parser.yy} starts by asking
 @subsection Calc++ Parser
 
 The parser definition file @file{calc++-parser.yy} starts by asking

-for the C++ skeleton, the creation of the parser header file, and
-specifies the name of the parser class.  It then includes the required
-headers.
+for the C++ LALR(1) skeleton, the creation of the parser header file, and
+specifies the name of the parser class.

 
 @comment file: calc++-parser.yy
 @example
 %skeleton "lalr1.cc"                          /*  -*- C++ -*- */
 
 @comment file: calc++-parser.yy
 @example
 %skeleton "lalr1.cc"                          /*  -*- C++ -*- */

-%define "parser_class_name" "calcxx_parser"

 %defines
 %defines

+%define "parser_class_name" "calcxx_parser"
+@end example
+
+@noindent
+Then come the declarations/inclusions needed to define the
+@code{%union}.  Because the parser uses the parsing driver and
+reciprocally, both cannot include the header of the other.  Because the
+driver's header needs detailed knowledge about the parser class (in
+particular its inner types), it is the parser's header which will simply
+use a forward declaration of the driver.
+
+@comment file: calc++-parser.yy
+@example

 %@{
 # include <string>
 %@{
 # include <string>

-# include "calc++-driver.hh"
+class calcxx_driver;

 %@}
 @end example
 
 %@}
 @end example
 


@@ -7354,6 +7354,19 @@ them.
 @};
 @end example
 
 @};
 @end example
 

+@noindent
+The code between @samp{%@{} and @samp{%@}} after the introduction of the
+@samp{%union} is output in the @file{*.cc} file; it needs detailed
+knowledge about the driver.
+
+@comment file: calc++-parser.yy
+@example
+%@{
+# include "calc++-driver.hh"
+%@}
+@end example
+
+

 @noindent
 The token numbered as 0 corresponds to end of file; the following line
 allows for nicer error messages referring to ``end of file'' instead
 @noindent
 The token numbered as 0 corresponds to end of file; the following line
 allows for nicer error messages referring to ``end of file'' instead


@@ -7363,11 +7376,11 @@ avoid name clashes.
 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

-%token        YYEOF          0 "end of file"
-%token        TOKEN_ASSIGN     ":="
-%token <sval> TOKEN_IDENTIFIER "identifier"
-%token <ival> TOKEN_NUMBER     "number"
-%type  <ival> exp              "expression"
+%token        END      0 "end of file"
+%token        ASSIGN     ":="
+%token <sval> IDENTIFIER "identifier"
+%token <ival> NUMBER     "number"
+%type  <ival> exp        "expression"

 @end example
 
 @noindent
 @end example
 
 @noindent


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

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

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


@@ -7402,8 +7415,8 @@ 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; @}

-   | TOKEN_IDENTIFIER  @{ $$ = driver.variables[*$1]; @}
-   | TOKEN_NUMBER      @{ $$ = $1; @};
+   | "identifier"  @{ $$ = driver.variables[*$1]; @}
+   | "number"      @{ $$ = $1; @};

 %%
 @end example
 
 %%
 @end example
 


@@ -7483,22 +7496,28 @@ preceding tokens.  Comments would be treated equally.
 @end example
 
 @noindent
 @end example
 
 @noindent

-The rules are simple, just note the use of the driver to report
-errors.
+The rules are simple, just note the use of the driver to report errors.
+It is convenient to use a typedef to shorten
+@code{yy::calcxx_parser::token::identifier} into
+@code{token::identifier} for isntance.

 
 @comment file: calc++-scanner.ll
 @example
 
 @comment file: calc++-scanner.ll
 @example

+%@{
+  typedef yy::calcxx_parser::token token;
+%@}
+

 [-+*/]     return yytext[0];
 [-+*/]     return yytext[0];

-":="       return TOKEN_ASSIGN;
+":="       return token::ASSIGN;

 @{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;
 @{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;
+  return token::NUMBER;

 @}
 @}

-@{id@}       yylval->sval = new std::string (yytext); return TOKEN_IDENTIFIER;
+@{id@}       yylval->sval = new std::string (yytext); return token::IDENTIFIER;

 .          driver.error (*yylloc, "invalid character");
 %%
 @end example
 .          driver.error (*yylloc, "invalid character");
 %%
 @end example


@@ -8097,7 +8116,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


@@ -8127,10 +8146,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