* src/parse-gram.y: Define PERCENT_EXPECT_RR.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 22abaadabf05c1113a41ab67c98f60eef3c515b8..22e5da910da69dc3175c599a52794b34bf8bfa7d 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -16,6 +16,10 @@
 @c @clear shorttitlepage-enabled
 @c @set shorttitlepage-enabled
 
 @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
 @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,
 @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
 
 @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.
 * 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.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Decl Summary::      Table of all Bison declarations.


@@ -284,7 +288,7 @@ Invoking Bison
 Frequently Asked Questions
 
 * Parser Stack Overflow::      Breaking the Stack Limits
 Frequently Asked Questions
 
 * Parser Stack Overflow::      Breaking the Stack Limits

-* How Can I Reset @code{yyparse}::    @code{yyparse} Keeps some State
+* How Can I Reset the Parser:: @code{yyparse} Keeps some State

 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * C++ Parsers::                Compiling Parsers with C++ Compilers
 * Implementing Loops::         Control Flow in the Calculator
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * C++ Parsers::                Compiling Parsers with C++ Compilers
 * Implementing Loops::         Control Flow in the Calculator


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


@@ -1415,7 +1419,7 @@ here is the definition we will use:
 void
 yyerror (char const *s)
 @{
 void
 yyerror (char const *s)
 @{

-  printf ("%s\n", s);
+  fprintf (stderr, "%s\n", s);

 @}
 @end group
 @end example
 @}
 @end group
 @end example


@@ -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
 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).
 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).


@@ -2797,9 +2802,10 @@ Actions, ,Actions in Mid-Rule}).
 The C code in an action can refer to the semantic values of the components
 matched by the rule with the construct @code{$@var{n}}, which stands for
 the value of the @var{n}th component.  The semantic value for the grouping
 The C code in an action can refer to the semantic values of the components
 matched by the rule with the construct @code{$@var{n}}, which stands for
 the value of the @var{n}th component.  The semantic value for the grouping

-being constructed is @code{$$}.  (Bison translates both of these constructs
-into array element references when it copies the actions into the parser
-file.)
+being constructed is @code{$$}.  Bison translates both of these
+constructs into expressions of the appropriate type when it copies the
+actions into the parser file.  @code{$$} is translated to a modifiable
+lvalue, so it can be assigned to.

 
 Here is a typical example:
 
 
 Here is a typical example:
 


@@ -3082,8 +3088,6 @@ Though grammar rules and semantic actions are enough to write a fully
 functional parser, it can be useful to process some additional information,
 especially symbol locations.
 
 functional parser, it can be useful to process some additional information,
 especially symbol locations.
 

-@c (terminal or not) ?
-

 The way locations are handled is defined by providing a data type, and
 actions to take when rules are matched.
 
 The way locations are handled is defined by providing a data type, and
 actions to take when rules are matched.
 


@@ -3148,9 +3152,10 @@ exp:    @dots{}
               else
                 @{
                   $$ = 1;
               else
                 @{
                   $$ = 1;

-                  printf("Division by zero, l%d,c%d-l%d,c%d",
-                         @@3.first_line, @@3.first_column,
-                         @@3.last_line, @@3.last_column);
+                  fprintf (stderr,
+                           "Division by zero, l%d,c%d-l%d,c%d",
+                           @@3.first_line, @@3.first_column,
+                           @@3.last_line, @@3.last_column);

                 @}
             @}
 @end group
                 @}
             @}
 @end group


@@ -3174,9 +3179,10 @@ exp:    @dots{}
               else
                 @{
                   $$ = 1;
               else
                 @{
                   $$ = 1;

-                  printf("Division by zero, l%d,c%d-l%d,c%d",
-                         @@3.first_line, @@3.first_column,
-                         @@3.last_line, @@3.last_column);
+                  fprintf (stderr,
+                           "Division by zero, l%d,c%d-l%d,c%d",
+                           @@3.first_line, @@3.first_column,
+                           @@3.last_line, @@3.last_column);

                 @}
             @}
 @end group
                 @}
             @}
 @end group


@@ -3210,11 +3216,11 @@ By default, @code{YYLLOC_DEFAULT} is defined this way for simple
 
 @example
 @group
 
 @example
 @group

-#define YYLLOC_DEFAULT(Current, Rhs, N)          \
-  Current.first_line   = Rhs[1].first_line;      \
-  Current.first_column = Rhs[1].first_column;    \
-  Current.last_line    = Rhs[N].last_line;       \
-  Current.last_column  = Rhs[N].last_column;
+# define YYLLOC_DEFAULT(Current, Rhs, N)               \
+   ((Current).first_line   = (Rhs)[1].first_line,      \
+    (Current).first_column = (Rhs)[1].first_column,    \
+    (Current).last_line    = (Rhs)[N].last_line,       \
+    (Current).last_column  = (Rhs)[N].last_column)

 @end group
 @end example
 
 @end group
 @end example
 


@@ -3223,11 +3229,11 @@ and like this for @acronym{GLR} parsers:
 
 @example
 @group
 
 @example
 @group

-#define YYLLOC_DEFAULT(Current, Rhs, N)          \
-  Current.first_line   = YYRHSLOC(Rhs,1).first_line;      \
-  Current.first_column = YYRHSLOC(Rhs,1).first_column;    \
-  Current.last_line    = YYRHSLOC(Rhs,N).last_line;       \
-  Current.last_column  = YYRHSLOC(Rhs,N).last_column;
+# define YYLLOC_DEFAULT(yyCurrent, yyRhs, YYN)                 \
+   ((yyCurrent).first_line = YYRHSLOC(yyRhs, 1).first_line,    \
+    (yyCurrent).first_column = YYRHSLOC(yyRhs, 1).first_column,        \
+    (yyCurrent).last_line = YYRHSLOC(yyRhs, YYN).last_line,    \
+    (yyCurrent).last_column  = YYRHSLOC(yyRhs, YYN).last_column)

 @end group
 @end example
 
 @end group
 @end example
 


@@ -3241,6 +3247,12 @@ result) should be modified by @code{YYLLOC_DEFAULT}.
 @item
 For consistency with semantic actions, valid indexes for the location
 array range from 1 to @var{n}.
 @item
 For consistency with semantic actions, valid indexes for the location
 array range from 1 to @var{n}.

+
+@item
+Your macro should parenthesize its arguments, if need be, since the
+actual arguments may not be surrounded by parentheses.  Also, your
+macro should expand to something that can be used as a single
+statement when it is followed by a semicolon.

 @end itemize
 
 @node Declarations
 @end itemize
 
 @node Declarations


@@ -3268,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.
 * 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.
 * Start Decl::        Specifying the start symbol.
 * Pure Decl::         Requesting a reentrant parser.
 * Decl Summary::      Table of all Bison declarations.


@@ -3297,10 +3309,12 @@ associativity and precedence.  @xref{Precedence Decl, ,Operator
 Precedence}.
 
 You can explicitly specify the numeric code for a token type by appending
 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
 
 @example
 %token NUM 300

+%token XNUM 0x12d // a GNU extension

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -3546,6 +3560,7 @@ typefull: string;  // $$ = $1 applies, $1 is not destroyed.
 @cindex warnings, preventing
 @cindex conflicts, suppressing warnings of
 @findex %expect
 @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
 
 Bison normally warns if there are any conflicts in the grammar
 (@pxref{Shift/Reduce, ,Shift/Reduce Conflicts}), but most real grammars


@@ -3566,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.
 
 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
 In general, using @code{%expect} involves these steps:
 
 @itemize @bullet


@@ -3673,9 +3700,16 @@ Declare a terminal symbol (token type name) that is left-associative
 
 @deffn {Directive} %nonassoc
 Declare a terminal symbol (token type name) that is nonassociative
 
 @deffn {Directive} %nonassoc
 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

 (@pxref{Precedence Decl, ,Operator Precedence}).
 (@pxref{Precedence Decl, ,Operator Precedence}).

+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
 
 @deffn {Directive} %type
 Declare the type of semantic values for a nonterminal symbol


@@ -3747,6 +3781,14 @@ and so on.  @xref{Multiple Parsers, ,Multiple Parsers in the Same
 Program}.
 @end deffn
 
 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
 parser file contains just @code{#define} directives and static variable
 @deffn {Directive} %no-parser
 Do not include any C code in the parser file; generate tables only.  The
 parser file contains just @code{#define} directives and static variable


@@ -4845,6 +4887,28 @@ exp:    @dots{}
 @end group
 @end example
 
 @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
+discovers the mistake only by testing the code.
+
+The @code{%no-default-prec;} declaration makes it easier to discover
+this kind of problem systematically.  It causes rules that lack a
+@code{%prec} modifier to have no precedence, even if the last terminal
+symbol mentioned in their components has a declared precedence.
+
+If @code{%no-default-prec;} is in effect, you must specify @code{%prec}
+for all rules that participate in precedence conflict resolution.
+Then you will see any shift/reduce conflict until you tell Bison how
+to resolve it, either by changing your grammar or by adding an
+explicit precedence.  This will probably add declarations to the
+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
 @cindex finite-state machine
 @node Parser States
 @section Parser States
 @cindex finite-state machine


@@ -6165,7 +6229,7 @@ compatibility with @acronym{POSIX}:
 
 @example
 #! /bin/sh
 
 @example
 #! /bin/sh

-bison -y "$@"
+bison -y "$@@"

 @end example
 @end table
 
 @end example
 @end table
 


@@ -6356,7 +6420,7 @@ are addressed.
 
 @menu
 * Parser Stack Overflow::      Breaking the Stack Limits
 
 @menu
 * Parser Stack Overflow::      Breaking the Stack Limits

-* How Can I Reset @code{yyparse}::    @code{yyparse} Keeps some State
+* How Can I Reset the Parser:: @code{yyparse} Keeps some State

 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * C++ Parsers::                Compiling Parsers with C++ Compilers
 * Implementing Loops::         Control Flow in the Calculator
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 * C++ Parsers::                Compiling Parsers with C++ Compilers
 * Implementing Loops::         Control Flow in the Calculator


@@ -6373,29 +6437,29 @@ message.  What can I do?
 This question is already addressed elsewhere, @xref{Recursion,
 ,Recursive Rules}.
 
 This question is already addressed elsewhere, @xref{Recursion,
 ,Recursive Rules}.
 

-@node How Can I Reset @code{yyparse}
-@section How Can I Reset @code{yyparse}
+@node How Can I Reset the Parser
+@section How Can I Reset the Parser

 
 

-The following phenomenon gives raise to several incarnations,
-resulting in the following typical questions:
+The following phenomenon has several symptoms, resulting in the
+following typical questions:

 
 @display
 I invoke @code{yyparse} several times, and on correct input it works
 properly; but when a parse error is found, all the other calls fail
 
 @display
 I invoke @code{yyparse} several times, and on correct input it works
 properly; but when a parse error is found, all the other calls fail

-too.  How can I reset @code{yyparse}'s error flag?
+too.  How can I reset the error flag of @code{yyparse}?

 @end display
 
 @noindent
 or
 
 @display
 @end display
 
 @noindent
 or
 
 @display

-My parser includes support for a @samp{#include} like feature, in
+My parser includes support for an @samp{#include}-like feature, in

 which case I run @code{yyparse} from @code{yyparse}.  This fails
 although I did specify I needed a @code{%pure-parser}.
 @end display
 
 which case I run @code{yyparse} from @code{yyparse}.  This fails
 although I did specify I needed a @code{%pure-parser}.
 @end display
 

-These problems are not related to Bison itself, but with the Lex
-generated scanners.  Because these scanners use large buffers for
+These problems typically come not from Bison itself, but from
+Lex-generated scanners.  Because these scanners use large buffers for

 speed, they might not notice a change of input file.  As a
 demonstration, consider the following source file,
 @file{first-line.l}:
 speed, they might not notice a change of input file.  As a
 demonstration, consider the following source file,
 @file{first-line.l}:


@@ -6409,20 +6473,20 @@ demonstration, consider the following source file,
 .*\n    ECHO; return 1;
 %%
 int
 .*\n    ECHO; return 1;
 %%
 int

-yyparse (const char *file)
+yyparse (char const *file)

 {
   yyin = fopen (file, "r");
   if (!yyin)
     exit (2);
   /* One token only. */
   yylex ();
 {
   yyin = fopen (file, "r");
   if (!yyin)
     exit (2);
   /* One token only. */
   yylex ();

-  if (!fclose (yyin))
+  if (fclose (yyin) != 0)

     exit (3);
   return 0;
 }
 
 int
     exit (3);
   return 0;
 }
 
 int

-main ()
+main (void)

 {
   yyparse ("input");
   yyparse ("input");
 {
   yyparse ("input");
   yyparse ("input");


@@ -6439,7 +6503,7 @@ input:2: World!
 @end verbatim
 
 @noindent
 @end verbatim
 
 @noindent

-then instead of getting twice the first line, you get:
+then instead of getting the first line twice, you get:

 
 @example
 $ @kbd{flex -ofirst-line.c first-line.l}
 
 @example
 $ @kbd{flex -ofirst-line.c first-line.l}


@@ -6449,12 +6513,20 @@ input:1: Hello,
 input:2: World!
 @end example
 
 input:2: World!
 @end example
 

-Therefore, whenever you change @code{yyin}, you must tell the Lex
-generated scanner to discard its current buffer, and to switch to the
-new one.  This depends upon your implementation of Lex, see its
-documentation for more.  For instance, in the case of Flex, a simple
-call @samp{yyrestart (yyin)} suffices after each change to
-@code{yyin}.
+Therefore, whenever you change @code{yyin}, you must tell the
+Lex-generated scanner to discard its current buffer and switch to the
+new one.  This depends upon your implementation of Lex; see its
+documentation for more.  For Flex, it suffices to call
+@samp{YY_FLUSH_BUFFER} after each change to @code{yyin}.  If your
+Flex-generated scanner needs to read from several input streams to
+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
 
 @node Strings are Destroyed
 @section Strings are Destroyed


@@ -6546,9 +6618,9 @@ but how can I implement loops?
 @end display
 
 Although very pedagogical, the examples included in the document blur
 @end display
 
 Although very pedagogical, the examples included in the document blur

-the distinction to make between the parser ---whose job is to recover
+the distinction to make between the parser---whose job is to recover

 the structure of a text and to transmit it to subsequent modules of
 the structure of a text and to transmit it to subsequent modules of

-the program--- and the processing (such as the execution) of this
+the program---and the processing (such as the execution) of this

 structure.  This works well with so called straight line programs,
 i.e., precisely those that have a straightforward execution model:
 execute simple instructions one after the others.
 structure.  This works well with so called straight line programs,
 i.e., precisely those that have a straightforward execution model:
 execute simple instructions one after the others.


@@ -6773,6 +6845,14 @@ parsing.  @xref{Parser Function, ,The Parser Function @code{yyparse}}.
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 
 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.
 @xref{Decl Summary}.
 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.


@@ -6826,6 +6906,14 @@ 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
 
 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
 parser file.  @xref{Decl Summary}.
 @deffn {Directive} %no-lines
 Bison declaration to avoid generating @code{#line} directives in the
 parser file.  @xref{Decl Summary}.