X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/0cc3da3a4e993080b69ee94156c280b5f2630013..4bfd5e4e5373627074d31ec2f15b2eb1947b8f5c:/doc/bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 84761760..fe23e603 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -16,6 +16,10 @@
 @c @clear shorttitlepage-enabled
 @c @set shorttitlepage-enabled
 
+@c Set following if you want to document %default-prec and %no-default-prec.
+@c This feature is experimental and may change in future Bison versions.
+@c @set defaultprec
+
 @c ISPELL CHECK: done, 14 Jan 1993 --bob
 
 @c Check COPYRIGHT dates.  should be updated in the titlepage, ifinfo
@@ -40,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,
-1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -219,7 +223,7 @@ Bison Declarations
 * 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.
+* Expect Decl::       Suppressing warnings about parsing conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Decl Summary::      Table of all Bison declarations.
@@ -352,7 +356,7 @@ encourage people to make other software free.  So we decided to make the
 practical conditions for using Bison match the practical conditions for
 using the other @acronym{GNU} tools.
 
-This exception applies only when Bison is generating C code for a
+This exception applies only when Bison is generating C code for an
 @acronym{LALR}(1) parser; otherwise, the @acronym{GPL} terms operate
 as usual.  You can
 tell whether the exception applies to your @samp{.c} output file by
@@ -2334,7 +2338,7 @@ can be done with two @var{Prologue} blocks, one before and one after the
 %@}
 
 %union @{
-  long n;
+  long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
 
@@ -2477,7 +2481,8 @@ does not enforce this convention, but if you depart from it, people who
 read your program will be confused.
 
 All the escape sequences used in string literals in C can be used in
-Bison as well.  However, unlike Standard C, trigraphs have no special
+Bison as well, except that you must not use a null character within a
+string literal.  Also, unlike Standard C, trigraphs have no special
 meaning in Bison string literals, nor is backslash-newline allowed.  A
 literal string token must contain two or more characters; for a token
 containing just one character, use a character token (see above).
@@ -2750,7 +2755,7 @@ This macro definition must go in the prologue of the grammar file
 
 In most programs, you will need different data types for different kinds
 of tokens and groupings.  For example, a numeric constant may need type
-@code{int} or @code{long}, while a string constant needs type @code{char *},
+@code{int} or @code{long int}, while a string constant needs type @code{char *},
 and an identifier might need a pointer to an entry in the symbol table.
 
 To use more than one data type for semantic values in one parser, Bison
@@ -3275,7 +3280,7 @@ Grammars}).
 * 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.
+* Expect Decl::       Suppressing warnings about parsing conflicts.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Decl Summary::      Table of all Bison declarations.
@@ -3304,10 +3309,12 @@ associativity and precedence.  @xref{Precedence Decl, ,Operator
 Precedence}.
 
 You can explicitly specify the numeric code for a token type by appending
-an integer value in the field immediately following the token name:
+a decimal or hexadecimal integer value in the field immediately
+following the token name:
 
 @example
 %token NUM 300
+%token XNUM 0x12d // a GNU extension
 @end example
 
 @noindent
@@ -3553,6 +3560,7 @@ typefull: string;  // $$ = $1 applies, $1 is not destroyed.
 @cindex warnings, preventing
 @cindex conflicts, suppressing warnings of
 @findex %expect
+@findex %expect-rr
 
 Bison normally warns if there are any conflicts in the grammar
 (@pxref{Shift/Reduce, ,Shift/Reduce Conflicts}), but most real grammars
@@ -3573,6 +3581,18 @@ reduce/reduce conflicts.  The usual warning is
 given if there are either more or fewer conflicts, or if there are any
 reduce/reduce conflicts.
 
+For normal LALR(1) parsers, reduce/reduce conflicts are more serious,
+and should be eliminated entirely.  Bison will always report
+reduce/reduce conflicts for these parsers.  With GLR parsers, however,
+both shift/reduce and reduce/reduce are routine (otherwise, there
+would be no need to use GLR parsing).  Therefore, it is also possible
+to specify an expected number of reduce/reduce conflicts in GLR
+parsers, using the declaration:
+
+@example
+%expect-rr @var{n}
+@end example
+
 In general, using @code{%expect} involves these steps:
 
 @itemize @bullet
@@ -3684,10 +3704,12 @@ Declare a terminal symbol (token type name) that is nonassociative
 Using it in a way that would be associative is a syntax error.
 @end deffn
 
+@ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules lacking an explicit @code{%prec} modifier
 (@pxref{Contextual Precedence, ,Context-Dependent Precedence}).
 @end deffn
+@end ifset
 
 @deffn {Directive} %type
 Declare the type of semantic values for a nonterminal symbol
@@ -3717,17 +3739,33 @@ already defined, so that the debugging facilities are compiled.
 @xref{Tracing, ,Tracing Your Parser}.
 
 @deffn {Directive} %defines
-Write an extra output file containing macro definitions for the token
-type names defined in the grammar and the semantic value type
-@code{YYSTYPE}, as well as a few @code{extern} variable declarations.
-
+Write a header file containing macro definitions for the token type
+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}.
 
-This output file is essential if you wish to put the definition of
-@code{yylex} in a separate source file, because @code{yylex} needs to
-be able to refer to token type codes and the variable
-@code{yylval}.  @xref{Token Values, ,Semantic Values of Tokens}.
+Unless @code{YYSTYPE} is already defined as a macro, the output header
+declares @code{YYSTYPE}.  Therefore, if you have defined a
+@code{YYSTYPE} macro (@pxref{Value Type, ,Data Types of Semantic
+Values}) you need to arrange for this definition to be propagated to
+all modules, e.g., by putting the macro definition in another,
+prerequisite header that is included both by your parser and by any
+other module that needs @code{YYSTYPE}.
+
+Unless your parser is pure, the output header declares @code{yylval}
+as an external variable.  @xref{Pure Decl, ,A Pure (Reentrant)
+Parser}.
+
+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
+Locations}.
+
+This output file is normally essential if you wish to put the
+definition of @code{yylex} in a separate source file, because
+@code{yylex} typically needs to be able to refer to the
+above-mentioned declarations and to the token type codes.
+@xref{Token Values, ,Semantic Values of Tokens}.
 @end deffn
 
 @deffn {Directive} %destructor
@@ -3759,11 +3797,13 @@ and so on.  @xref{Multiple Parsers, ,Multiple Parsers in the Same
 Program}.
 @end deffn
 
+@ifset defaultprec
 @deffn {Directive} %no-default-prec
 Do not assign a precedence to rules lacking an explicit @code{%prec}
 modifier (@pxref{Contextual Precedence, ,Context-Dependent
 Precedence}).
 @end deffn
+@end ifset
 
 @deffn {Directive} %no-parser
 Do not include any C code in the parser file; generate tables only.  The
@@ -4863,6 +4903,7 @@ exp:    @dots{}
 @end group
 @end example
 
+@ifset defaultprec
 If you forget to append @code{%prec UMINUS} to the rule for unary
 minus, Bison silently assumes that minus has its usual precedence.
 This kind of problem can be tricky to debug, since one typically
@@ -4882,6 +4923,7 @@ grammar, but it helps to protect against incorrect rule precedences.
 
 The effect of @code{%no-default-prec;} can be reversed by giving
 @code{%default-prec;}, which is the default.
+@end ifset
 
 @node Parser States
 @section Parser States
@@ -6203,7 +6245,7 @@ compatibility with @acronym{POSIX}:
 
 @example
 #! /bin/sh
-bison -y "$@"
+bison -y "$@@"
 @end example
 @end table
 
@@ -6255,8 +6297,7 @@ Adjust the output:
 @itemx --defines
 Pretend that @code{%defines} was specified, i.e., write an extra output
 file containing macro definitions for the token type names defined in
-the grammar and the semantic value type @code{YYSTYPE}, as well as a few
-@code{extern} variable declarations.  @xref{Decl Summary}.
+the grammar, as well as a few other declarations.  @xref{Decl Summary}.
 
 @item --defines=@var{defines-file}
 Same as above, but save in the file @var{defines-file}.
@@ -6497,6 +6538,11 @@ handle features like include files, you might consider using Flex
 functions like @samp{yy_switch_to_buffer} that manipulate multiple
 input buffers.
 
+If your Flex-generated scanner uses start conditions (@pxref{Start
+conditions, , Start conditions, flex, The Flex Manual}), you might
+also want to reset the scanner's state, i.e., go back to the initial
+start condition, through a call to @samp{BEGIN (0)}.
+
 @node Strings are Destroyed
 @section Strings are Destroyed
 
@@ -6814,11 +6860,13 @@ parsing.  @xref{Parser Function, ,The Parser Function @code{yyparse}}.
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 
+@ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules that lack an explicit @samp{%prec}
 modifier.  @xref{Contextual Precedence, ,Context-Dependent
 Precedence}.
 @end deffn
+@end ifset
 
 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
@@ -6873,11 +6921,13 @@ function is applied to the two semantic values to get a single result.
 Bison declaration to rename the external symbols.  @xref{Decl Summary}.
 @end deffn
 
+@ifset defaultprec
 @deffn {Directive} %no-default-prec
 Do not assign a precedence to rules that lack an explicit @samp{%prec}
 modifier.  @xref{Contextual Precedence, ,Context-Dependent
 Precedence}.
 @end deffn
+@end ifset
 
 @deffn {Directive} %no-lines
 Bison declaration to avoid generating @code{#line} directives in the