Version 1.49a.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index c5fa3b4f1071e66a07810d98f3a979a3b77f55cb..866f7968db1ab4bb0c1ca313d85e58546315deda 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -766,7 +766,7 @@ general form of a Bison grammar file is as follows:
 
 @example
 %@{
 
 @example
 %@{

-@var{Prologue (declarations)}
+@var{Prologue}

 %@}
 
 @var{Bison declarations}
 %@}
 
 @var{Bison declarations}


@@ -774,7 +774,7 @@ general form of a Bison grammar file is as follows:
 %%
 @var{Grammar rules}
 %%
 %%
 @var{Grammar rules}
 %%

-@var{Epilogue (additional code)}
+@var{Epilogue}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -2043,7 +2043,7 @@ Comments enclosed in @samp{/* @dots{} */} may appear in any of the sections.
 @cindex Prologue
 @cindex declarations
 
 @cindex Prologue
 @cindex declarations
 

-The @var{prologue} section contains macro definitions and
+The @var{Prologue} section contains macro definitions and

 declarations of functions and variables that are used in the actions in the
 grammar rules.  These are copied to the beginning of the parser file so
 that they precede the definition of @code{yyparse}.  You can use
 declarations of functions and variables that are used in the actions in the
 grammar rules.  These are copied to the beginning of the parser file so
 that they precede the definition of @code{yyparse}.  You can use


@@ -2079,8 +2079,8 @@ if it is the first thing in the file.
 @cindex epilogue
 @cindex C code, section for additional
 
 @cindex epilogue
 @cindex C code, section for additional
 

-The @var{epilogue} is copied verbatim to the end of the parser file, just as
-the @var{prologue} is copied to the beginning.  This is the most convenient
+The @var{Epilogue} is copied verbatim to the end of the parser file, just as
+the @var{Prologue} is copied to the beginning.  This is the most convenient

 place to put anything that you want to have in the parser file but which need
 not come before the definition of @code{yyparse}.  For example, the
 definitions of @code{yylex} and @code{yyerror} often go here.
 place to put anything that you want to have in the parser file but which need
 not come before the definition of @code{yyparse}.  For example, the
 definitions of @code{yylex} and @code{yyerror} often go here.


@@ -2218,11 +2218,9 @@ files before compiling them.
 
 The symbol @code{error} is a terminal symbol reserved for error recovery
 (@pxref{Error Recovery}); you shouldn't use it for any other purpose.
 
 The symbol @code{error} is a terminal symbol reserved for error recovery
 (@pxref{Error Recovery}); you shouldn't use it for any other purpose.

-In particular, @code{yylex} should never return this value.
-The default value of the error token is 256, so in the
-unlikely event that you need to use a character token with numeric
-value 256 you must reassign the error token's value with a
-@code{%token} declaration.
+In particular, @code{yylex} should never return this value.  The default
+value of the error token is 256, unless you explicitly assigned 256 to
+one of your tokens with a @code{%token} declaration.

 
 @node Rules
 @section Syntax of Grammar Rules
 
 @node Rules
 @section Syntax of Grammar Rules


@@ -2505,6 +2503,18 @@ the addition-expression just recognized by the rule.  If there were a
 useful semantic value associated with the @samp{+} token, it could be
 referred to as @code{$2}.
 
 useful semantic value associated with the @samp{+} token, it could be
 referred to as @code{$2}.
 

+Note that the vertical-bar character @samp{|} is really a rule
+separator, and actions are attached to a single rule.  This is a
+difference with tools like Flex, for which @samp{|} stands for either
+``or'', or ``the same action as that of the next rule''.  In the
+following example, the action is triggered only when @samp{b} is found:
+
+@example
+@group
+a-or-b: 'a'|'b'   @{ a_or_b_found = 1; @};
+@end group
+@end example
+

 @cindex default action
 If you don't specify an action for a rule, Bison supplies a default:
 @w{@code{$$ = $1}.}  Thus, the value of the first symbol in the rule becomes
 @cindex default action
 If you don't specify an action for a rule, Bison supplies a default:
 @w{@code{$$ = $1}.}  Thus, the value of the first symbol in the rule becomes


@@ -4948,7 +4958,6 @@ clear the flag.
 
 @node Debugging
 @chapter Debugging Your Parser
 
 @node Debugging
 @chapter Debugging Your Parser

-@findex YYDEBUG

 @findex yydebug
 @cindex debugging
 @cindex tracing the parser
 @findex yydebug
 @cindex debugging
 @cindex tracing the parser


@@ -4956,15 +4965,32 @@ clear the flag.
 If a Bison grammar compiles properly but doesn't do what you want when it
 runs, the @code{yydebug} parser-trace feature can help you figure out why.
 
 If a Bison grammar compiles properly but doesn't do what you want when it
 runs, the @code{yydebug} parser-trace feature can help you figure out why.
 

-To enable compilation of trace facilities, you must define the macro
-@code{YYDEBUG} to a nonzero value when you compile the parser.  You
-could use @samp{-DYYDEBUG=1} as a compiler option or you could put
-@samp{#define YYDEBUG 1} in the prologue of the grammar file
-(@pxref{Prologue, , The Prologue}).  Alternatively, use the @samp{-t}
-option when you run Bison (@pxref{Invocation, ,Invoking Bison}) or the
-@code{%debug} declaration (@pxref{Decl Summary, ,Bison Declaration
-Summary}).  We suggest that you always define @code{YYDEBUG} so that
-debugging is always possible.
+There are several means to enable compilation of trace facilities:
+
+@table @asis
+@item the macro @code{YYDEBUG}
+@findex YYDEBUG
+Define the macro @code{YYDEBUG} to a nonzero value when you compile the
+parser.  This is compliant with POSIX Yacc.  You could use
+@samp{-DYYDEBUG=1} as a compiler option or you could put @samp{#define
+YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
+Prologue}).
+
+@item the option @option{-t}, @option{--debug}
+Use the @samp{-t} option when you run Bison (@pxref{Invocation,
+,Invoking Bison}).  This is POSIX compliant too.
+
+@item the directive @samp{%debug}
+@findex %debug
+Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
+Declaration Summary}).  This is a Bison extension, which will prove
+useful when Bison will output parsers for languages that don't use a
+preprocessor.  Useless POSIX and Yacc portability matter to you, this is
+the preferred solution.
+@end table
+
+We suggest that you always enable the debug option so that debugging is
+always possible.

 
 The trace facility outputs messages with macro calls of the form
 @code{YYFPRINTF (stderr, @var{format}, @var{args})} where
 
 The trace facility outputs messages with macro calls of the form
 @code{YYFPRINTF (stderr, @var{format}, @var{args})} where


@@ -5307,6 +5333,22 @@ would instead be named @file{foo_tab.c}.
 @cindex symbols in Bison, table of
 
 @table @code
 @cindex symbols in Bison, table of
 
 @table @code

+@item @@$
+In an action, the location of the left-hand side of the rule.
+  @xref{Locations, , Locations Overview}.
+
+@item @@@var{n}
+In an action, the location of the @var{n}-th symbol of the right-hand
+side of the rule.  @xref{Locations, , Locations Overview}.
+
+@item $$
+In an action, the semantic value of the left-hand side of the rule.
+@xref{Actions}.
+
+@item $@var{n}
+In an action, the semantic value of the @var{n}-th symbol of the
+right-hand side of the rule.  @xref{Actions}.
+

 @item error
 A token name reserved for error recovery.  This token may be used in
 grammar rules so as to allow the Bison parser to recognize an error in
 @item error
 A token name reserved for error recovery.  This token may be used in
 grammar rules so as to allow the Bison parser to recognize an error in


@@ -5332,6 +5374,10 @@ read, by making @code{yyparse} return 0 immediately.
 Macro to discard a value from the parser stack and fake a look-ahead
 token.  @xref{Action Features, ,Special Features for Use in Actions}.
 
 Macro to discard a value from the parser stack and fake a look-ahead
 token.  @xref{Action Features, ,Special Features for Use in Actions}.
 

+@item YYDEBUG
+Macro to define to equip the parser with tracing code. @xref{Debugging,
+,Debugging Your Parser}.
+

 @item YYERROR
 Macro to pretend that a syntax error has just been detected: call
 @code{yyerror} and then perform normal error recovery if possible
 @item YYERROR
 Macro to pretend that a syntax error has just been detected: call
 @code{yyerror} and then perform normal error recovery if possible


@@ -5505,6 +5551,8 @@ Bison declaration to specify several possible data types for semantic
 values.  @xref{Union Decl, ,The Collection of Value Types}.
 @end table
 
 values.  @xref{Union Decl, ,The Collection of Value Types}.
 @end table
 

+@sp 1
+

 These are the punctuation and delimiters used in Bison input:
 
 @table @samp
 These are the punctuation and delimiters used in Bison input:
 
 @table @samp