Fix some porting glitches found by Nelson H. F. Beebe.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 671d1c4eb7e2f8fa16ab34a80bb46de24d9d40a7..5ff8f8638f38c15bb5accec00eaf02855d1f20d8 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -44,7 +44,7 @@ This manual is for @acronym{GNU} Bison (version @value{VERSION},
 @value{UPDATED}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
 @value{UPDATED}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,

-1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.

 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document


@@ -145,9 +145,10 @@ The Concepts of Bison
 
 Writing @acronym{GLR} Parsers
 
 
 Writing @acronym{GLR} Parsers
 

-* Simple GLR Parsers::       Using @acronym{GLR} parsers on unambiguous grammars
-* Merging GLR Parses::       Using @acronym{GLR} parsers to resolve ambiguities
-* Compiler Requirements::    @acronym{GLR} parsers require a modern C compiler
+* Simple GLR Parsers::      Using @acronym{GLR} parsers on unambiguous grammars.
+* Merging GLR Parses::      Using @acronym{GLR} parsers to resolve ambiguities.
+* GLR Semantic Actions::    Deferred semantic actions have special concerns.
+* Compiler Requirements::   @acronym{GLR} parsers require a modern C compiler.

 
 Examples
 
 
 Examples
 


@@ -733,9 +734,10 @@ user-defined function on the resulting values to produce an arbitrary
 merged result.
 
 @menu
 merged result.
 
 @menu

-* Simple GLR Parsers::       Using @acronym{GLR} parsers on unambiguous grammars
-* Merging GLR Parses::       Using @acronym{GLR} parsers to resolve ambiguities
-* Compiler Requirements::    @acronym{GLR} parsers require a modern C compiler
+* Simple GLR Parsers::      Using @acronym{GLR} parsers on unambiguous grammars.
+* Merging GLR Parses::      Using @acronym{GLR} parsers to resolve ambiguities.
+* GLR Semantic Actions::    Deferred semantic actions have special concerns.
+* Compiler Requirements::   @acronym{GLR} parsers require a modern C compiler.

 @end menu
 
 @node Simple GLR Parsers
 @end menu
 
 @node Simple GLR Parsers


@@ -1094,6 +1096,52 @@ productions that participate in any particular merge have identical
 and the parser will report an error during any parse that results in
 the offending merge.
 
 and the parser will report an error during any parse that results in
 the offending merge.
 

+@node GLR Semantic Actions
+@subsection GLR Semantic Actions
+
+@cindex deferred semantic actions
+By definition, a deferred semantic action is not performed at the same time as
+the associated reduction.
+This raises caveats for several Bison features you might use in a semantic
+action in a @acronym{GLR} parser.
+
+@vindex yychar
+@cindex @acronym{GLR} parsers and @code{yychar}
+@vindex yylval
+@cindex @acronym{GLR} parsers and @code{yylval}
+@vindex yylloc
+@cindex @acronym{GLR} parsers and @code{yylloc}
+In any semantic action, you can examine @code{yychar} to determine the type of
+the look-ahead token present at the time of the associated reduction.
+After checking that @code{yychar} is not set to @code{YYEMPTY} or @code{YYEOF},
+you can then examine @code{yylval} and @code{yylloc} to determine the
+look-ahead token's semantic value and location, if any.
+In a nondeferred semantic action, you can also modify any of these variables to
+influence syntax analysis.
+@xref{Look-Ahead, ,Look-Ahead Tokens}.
+
+@findex yyclearin
+@cindex @acronym{GLR} parsers and @code{yyclearin}
+In a deferred semantic action, it's too late to influence syntax analysis.
+In this case, @code{yychar}, @code{yylval}, and @code{yylloc} are set to
+shallow copies of the values they had at the time of the associated reduction.
+For this reason alone, modifying them is dangerous.
+Moreover, the result of modifying them is undefined and subject to change with
+future versions of Bison.
+For example, if a semantic action might be deferred, you should never write it
+to invoke @code{yyclearin} (@pxref{Action Features}) or to attempt to free
+memory referenced by @code{yylval}.
+
+@findex YYERROR
+@cindex @acronym{GLR} parsers and @code{YYERROR}
+Another Bison feature requiring special consideration is @code{YYERROR}
+(@pxref{Action Features}), which you can invoke in any semantic action to
+initiate error recovery.
+During deterministic @acronym{GLR} operation, the effect of @code{YYERROR} is
+the same as its effect in an @acronym{LALR}(1) parser.
+In a deferred semantic action, its effect is undefined.
+@c The effect is probably a syntax error at the split point.
+

 @node Compiler Requirements
 @subsection Considerations when Compiling @acronym{GLR} Parsers
 @cindex @code{inline}
 @node Compiler Requirements
 @subsection Considerations when Compiling @acronym{GLR} Parsers
 @cindex @code{inline}


@@ -3140,6 +3188,12 @@ As long as @code{bar} is used only in the fashion shown here, @code{$0}
 always refers to the @code{expr} which precedes @code{bar} in the
 definition of @code{foo}.
 
 always refers to the @code{expr} which precedes @code{bar} in the
 definition of @code{foo}.
 

+@vindex yylval
+It is also possible to access the semantic value of the look-ahead token, if
+any, from a semantic action.
+This semantic value is stored in @code{yylval}.
+@xref{Action Features, ,Special Features for Use in Actions}.
+

 @node Action Types
 @subsection Data Types of Values in Actions
 @cindex action data types
 @node Action Types
 @subsection Data Types of Values in Actions
 @cindex action data types


@@ -3457,6 +3511,12 @@ exp:    @dots{}
 @end group
 @end example
 
 @end group
 @end example
 

+@vindex yylloc
+It is also possible to access the location of the look-ahead token, if any,
+from a semantic action.
+This location is stored in @code{yylloc}.
+@xref{Action Features, ,Special Features for Use in Actions}.
+

 @node Location Default Action
 @subsection Default Action for Locations
 @vindex YYLLOC_DEFAULT
 @node Location Default Action
 @subsection Default Action for Locations
 @vindex YYLLOC_DEFAULT


@@ -3742,10 +3802,15 @@ As an extension to @acronym{POSIX}, a tag is allowed after the
 @end group
 @end example
 
 @end group
 @end example
 

+@noindent

 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to
 @code{YYSTYPE}.
 
 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to
 @code{YYSTYPE}.
 

+As another extension to @acronym{POSIX}, you may specify multiple
+@code{%union} declarations; their contents are concatenated.  However,
+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.
 


@@ -4763,6 +4828,12 @@ In either case, the rest of the action is not executed.
 Value stored in @code{yychar} when there is no look-ahead token.
 @end deffn
 
 Value stored in @code{yychar} when there is no look-ahead token.
 @end deffn
 

+@deffn {Macro} YYEOF
+@vindex YYEOF
+Value stored in @code{yychar} when the look-ahead is the end of the input
+stream.
+@end deffn
+

 @deffn {Macro} YYERROR;
 @findex YYERROR
 Cause an immediate syntax error.  This statement initiates error
 @deffn {Macro} YYERROR;
 @findex YYERROR
 Cause an immediate syntax error.  This statement initiates error


@@ -4779,15 +4850,20 @@ is recovering from a syntax error, and 0 the rest of the time.
 @end deffn
 
 @deffn {Variable} yychar
 @end deffn
 
 @deffn {Variable} yychar

-Variable containing the current look-ahead token.  (In a pure parser,
-this is actually a local variable within @code{yyparse}.)  When there is
-no look-ahead token, the value @code{YYEMPTY} is stored in the variable.
+Variable containing either the look-ahead token, or @code{YYEOF} when the
+look-ahead is the end of the input stream, or @code{YYEMPTY} when no look-ahead
+has been performed so the next token is not yet known.
+Do not modify @code{yychar} in a deferred semantic action (@pxref{GLR Semantic
+Actions}).

 @xref{Look-Ahead, ,Look-Ahead Tokens}.
 @end deffn
 
 @deffn {Macro} yyclearin;
 Discard the current look-ahead token.  This is useful primarily in
 @xref{Look-Ahead, ,Look-Ahead Tokens}.
 @end deffn
 
 @deffn {Macro} yyclearin;
 Discard the current look-ahead token.  This is useful primarily in

-error rules.  @xref{Error Recovery}.
+error rules.
+Do not invoke @code{yyclearin} in a deferred semantic action (@pxref{GLR
+Semantic Actions}).
+@xref{Error Recovery}.

 @end deffn
 
 @deffn {Macro} yyerrok;
 @end deffn
 
 @deffn {Macro} yyerrok;


@@ -4796,6 +4872,22 @@ errors.  This is useful primarily in error rules.
 @xref{Error Recovery}.
 @end deffn
 
 @xref{Error Recovery}.
 @end deffn
 

+@deffn {Variable} yylloc
+Variable containing the look-ahead token location when @code{yychar} is not set
+to @code{YYEMPTY} or @code{YYEOF}.
+Do not modify @code{yylloc} in a deferred semantic action (@pxref{GLR Semantic
+Actions}).
+@xref{Actions and Locations, ,Actions and Locations}.
+@end deffn
+
+@deffn {Variable} yylval
+Variable containing the look-ahead token semantic value when @code{yychar} is
+not set to @code{YYEMPTY} or @code{YYEOF}.
+Do not modify @code{yylval} in a deferred semantic action (@pxref{GLR Semantic
+Actions}).
+@xref{Actions, ,Actions}.
+@end deffn
+

 @deffn {Value} @@$
 @findex @@$
 Acts like a structure variable containing information on the textual location
 @deffn {Value} @@$
 @findex @@$
 Acts like a structure variable containing information on the textual location


@@ -5033,7 +5125,11 @@ doing so would produce on the stack the sequence of symbols @code{expr
 '!'}.  No rule allows that sequence.
 
 @vindex yychar
 '!'}.  No rule allows that sequence.
 
 @vindex yychar

-The current look-ahead token is stored in the variable @code{yychar}.
+@vindex yylval
+@vindex yylloc
+The look-ahead token is stored in the variable @code{yychar}.
+Its semantic value and location, if any, are stored in the variables
+@code{yylval} and @code{yylloc}.

 @xref{Action Features, ,Special Features for Use in Actions}.
 
 @node Shift/Reduce
 @xref{Action Features, ,Special Features for Use in Actions}.
 
 @node Shift/Reduce


@@ -5850,6 +5946,7 @@ The previous look-ahead token is reanalyzed immediately after an error.  If
 this is unacceptable, then the macro @code{yyclearin} may be used to clear
 this token.  Write the statement @samp{yyclearin;} in the error rule's
 action.
 this is unacceptable, then the macro @code{yyclearin} may be used to clear
 this token.  Write the statement @samp{yyclearin;} in the error rule's
 action.

+@xref{Action Features, ,Special Features for Use in Actions}.

 
 For example, suppose that on a syntax error, an error handling routine is
 called that advances the input stream to some point where parsing should
 
 For example, suppose that on a syntax error, an error handling routine is
 called that advances the input stream to some point where parsing should


@@ -6677,13 +6774,14 @@ Print the version number of Bison and exit.
 @item --print-localedir
 Print the name of the directory containing locale-dependent data.
 
 @item --print-localedir
 Print the name of the directory containing locale-dependent data.
 

-@need 1750

 @item -y
 @itemx --yacc
 @item -y
 @itemx --yacc

-Equivalent to @samp{-o y.tab.c}; the parser output file is called
+Act more like the traditional Yacc command.  This can cause
+different diagnostics to be generated, and may change behavior in
+other minor ways.  Most importantly, imitate Yacc's output
+file name conventions, so that the parser output file is called

 @file{y.tab.c}, and the other outputs are called @file{y.output} and
 @file{y.tab.c}, and the other outputs are called @file{y.output} and

-@file{y.tab.h}.  The purpose of this option is to imitate Yacc's output
-file name conventions.  Thus, the following shell script can substitute
+@file{y.tab.h}.  Thus, the following shell script can substitute

 for Yacc, and the Bison distribution contains such a script for
 compatibility with @acronym{POSIX}:
 
 for Yacc, and the Bison distribution contains such a script for
 compatibility with @acronym{POSIX}:
 


@@ -6691,6 +6789,12 @@ compatibility with @acronym{POSIX}:
 #! /bin/sh
 bison -y "$@@"
 @end example
 #! /bin/sh
 bison -y "$@@"
 @end example

+
+The @option{-y}/@option{--yacc} option is intended for use with
+traditional Yacc grammars.  If your grammar uses a Bison extension
+like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
+this option is specified.
+

 @end table
 
 @noindent
 @end table
 
 @noindent


@@ -8032,7 +8136,7 @@ token.  @xref{Action Features, ,Special Features for Use in Actions}.
 @end deffn
 
 @deffn {Variable} yychar
 @end deffn
 
 @deffn {Variable} yychar

-External integer variable that contains the integer value of the current
+External integer variable that contains the integer value of the

 look-ahead token.  (In a pure parser, it is a local variable within
 @code{yyparse}.)  Error-recovery rule actions may examine this variable.
 @xref{Action Features, ,Special Features for Use in Actions}.
 look-ahead token.  (In a pure parser, it is a local variable within
 @code{yyparse}.)  Error-recovery rule actions may examine this variable.
 @xref{Action Features, ,Special Features for Use in Actions}.


@@ -8093,7 +8197,7 @@ the next token.  @xref{Lexical, ,The Lexical Analyzer Function
 
 @deffn {Macro} YYLEX_PARAM
 An obsolete macro for specifying an extra argument (or list of extra
 
 @deffn {Macro} YYLEX_PARAM
 An obsolete macro for specifying an extra argument (or list of extra

-arguments) for @code{yyparse} to pass to @code{yylex}.  he use of this
+arguments) for @code{yyparse} to pass to @code{yylex}.  The use of this

 macro is deprecated, and is supported only for Yacc like parsers.
 @xref{Pure Calling,, Calling Conventions for Pure Parsers}.
 @end deffn
 macro is deprecated, and is supported only for Yacc like parsers.
 @xref{Pure Calling,, Calling Conventions for Pure Parsers}.
 @end deffn


@@ -8102,9 +8206,12 @@ macro is deprecated, and is supported only for Yacc like parsers.
 External variable in which @code{yylex} should place the line and column
 numbers associated with a token.  (In a pure parser, it is a local
 variable within @code{yyparse}, and its address is passed to
 External variable in which @code{yylex} should place the line and column
 numbers associated with a token.  (In a pure parser, it is a local
 variable within @code{yyparse}, and its address is passed to

-@code{yylex}.)  You can ignore this variable if you don't use the
-@samp{@@} feature in the grammar actions.  @xref{Token Locations,
-,Textual Locations of Tokens}.
+@code{yylex}.)
+You can ignore this variable if you don't use the @samp{@@} feature in the
+grammar actions.
+@xref{Token Locations, ,Textual Locations of Tokens}.
+In semantic actions, it stores the location of the look-ahead token.
+@xref{Actions and Locations, ,Actions and Locations}.

 @end deffn
 
 @deffn {Type} YYLTYPE
 @end deffn
 
 @deffn {Type} YYLTYPE


@@ -8116,7 +8223,10 @@ members.  @xref{Location Type, , Data Types of Locations}.
 External variable in which @code{yylex} should place the semantic
 value associated with a token.  (In a pure parser, it is a local
 variable within @code{yyparse}, and its address is passed to
 External variable in which @code{yylex} should place the semantic
 value associated with a token.  (In a pure parser, it is a local
 variable within @code{yyparse}, and its address is passed to

-@code{yylex}.)  @xref{Token Values, ,Semantic Values of Tokens}.
+@code{yylex}.)
+@xref{Token Values, ,Semantic Values of Tokens}.
+In semantic actions, it stores the semantic value of the look-ahead token.
+@xref{Actions, ,Actions}.

 @end deffn
 
 @deffn {Macro} YYMAXDEPTH
 @end deffn
 
 @deffn {Macro} YYMAXDEPTH


@@ -8377,7 +8487,7 @@ grammatically indivisible.  The piece of text it represents is a token.
 @c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES
 @c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param
 @c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP
 @c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES
 @c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param
 @c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP

-@c LocalWords: YYEMPTY YYRECOVERING yyclearin GE def UMINUS maybeword
+@c LocalWords: YYEMPTY YYEOF YYRECOVERING yyclearin GE def UMINUS maybeword

 @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