X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/922bdd7ffa913135a33ea9e54e5034cfc15e0436..d9df47b656fd1757f1f36c8f3d823ca9ca5bfe91:/doc/bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 675c27c2..c0fa7f08 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4487,7 +4487,7 @@ may override this restriction with the @code{%start} declaration as follows:
 @subsection A Pure (Reentrant) Parser
 @cindex reentrant parser
 @cindex pure parser
-@findex %pure-parser
+@findex %define api.pure
 
 A @dfn{reentrant} program is one which does not alter in the course of
 execution; in other words, it consists entirely of @dfn{pure} (read-only)
@@ -4503,11 +4503,11 @@ statically allocated variables for communication with @code{yylex},
 including @code{yylval} and @code{yylloc}.)
 
 Alternatively, you can generate a pure, reentrant parser.  The Bison
-declaration @code{%pure-parser} says that you want the parser to be
+declaration @code{%define api.pure} says that you want the parser to be
 reentrant.  It looks like this:
 
 @example
-%pure-parser
+%define api.pure
 @end example
 
 The result is that the communication variables @code{yylval} and
@@ -4528,7 +4528,7 @@ valid grammar.
 @subsection A Push Parser
 @cindex push parser
 @cindex push parser
-@findex %push-parser
+@findex %define api.push_pull
 
 A pull parser is called once and it takes control until all its input 
 is completely parsed.  A push parser, on the other hand, is called 
@@ -4539,12 +4539,12 @@ main event loop in the client's application.  This is typically
 a requirement of a GUI, when the main event loop needs to be triggered 
 within a certain time period.  
 
-Normally, Bison generates a pull parser.  The Bison declaration 
-@code{%push-parser} says that you want the parser to be a push parser.
-It looks like this:
+Normally, Bison generates a pull parser.
+The following Bison declaration says that you want the parser to be a push
+parser (@pxref{Decl Summary,,%define api.push_pull}):
 
 @example
-%push-parser
+%define api.push_pull "push"
 @end example
 
 In almost all cases, you want to ensure that your push parser is also
@@ -4554,8 +4554,8 @@ compatibility with the impure Yacc pull mode interface.  Unless you know
 what you are doing, your declarations should look like this:
 
 @example
-%pure-parser
-%push-parser
+%define api.pure
+%define api.push_pull "push"
 @end example
 
 There is a major notable functional difference between the pure push parser 
@@ -4604,15 +4604,16 @@ for use by the next invocation of the @code{yypush_parse} function.
 
 Bison also supports both the push parser interface along with the pull parser 
 interface in the same generated parser.  In order to get this functionality,
-you should replace the @code{%push-parser} declaration with the 
-@code{%push-pull-parser} declaration.  Doing this will create all of the 
-symbols mentioned earlier along with the two extra symbols, @code{yyparse} 
+you should replace the @code{%define api.push_pull "push"} declaration with the 
+@code{%define api.push_pull "both"} declaration.  Doing this will create all of
+the symbols mentioned earlier along with the two extra symbols, @code{yyparse}
 and @code{yypull_parse}.  @code{yyparse} can be used exactly as it normally 
 would be used.  However, the user should note that it is implemented in the 
-generated parser by calling @code{yypull_parse}.  This makes the 
-@code{yyparse} function that is generated with the @code{%push-pull-parser} 
-declaration slower than the normal @code{yyparse} function.  If the user 
-calls the @code{yypull_parse} function it will parse the rest of the input 
+generated parser by calling @code{yypull_parse}.
+This makes the @code{yyparse} function that is generated with the
+@code{%define api.push_pull "both"} declaration slower than the normal
+@code{yyparse} function.  If the user
+calls the @code{yypull_parse} function it will parse the rest of the input
 stream.  It is possible to @code{yypush_parse} tokens to select a subgrammar 
 and then @code{yypull_parse} the rest of the input stream.  If you would like 
 to switch back and forth between between parsing styles, you would have to 
@@ -4626,9 +4627,9 @@ yypull_parse (ps); /* Will call the lexer */
 yypstate_delete (ps);
 @end example
 
-Adding the @code{%pure-parser} declaration does exactly the same thing to the 
-generated parser with @code{%push-pull-parser} as it did for 
-@code{%push-parser}.
+Adding the @code{%define api.pure} declaration does exactly the same thing to
+the generated parser with @code{%define api.push_pull "both"} as it did for 
+@code{%define api.push_pull "push"}.
 
 @node Decl Summary
 @subsection Bison Declaration Summary
@@ -4725,8 +4726,8 @@ where Bison should generate it.
 Not all values of @var{qualifier} are available for all target languages:
 
 @itemize @bullet
-@findex %code requires
 @item requires
+@findex %code requires
 
 @itemize @bullet
 @item Language(s): C, C++
@@ -4832,6 +4833,133 @@ This is equivalent to @code{"true"}.
 In this case, Bison selects a default value, which may depend on the selected
 target language and/or parser skeleton.
 @end enumerate
+
+Some of the accepted @var{variable}s are:
+
+@itemize @bullet
+@item api.pure
+@findex %define api.pure
+
+@itemize @bullet
+@item Language(s): C
+
+@item Purpose: Request a pure (reentrant) parser program.
+@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{"false"}
+@end itemize
+
+@item api.push_pull
+@findex %define api.push_pull
+
+@itemize @bullet
+@item Language(s): C (LALR(1) only)
+
+@item Purpose: Requests a pull parser, a push parser, or both.
+@xref{Push Decl, ,A Push Parser}.
+
+@item Accepted Values: @code{"pull"}, @code{"push"}, @code{"both"}
+
+@item Default Value: @code{"pull"}
+@end itemize
+
+@item lr.keep_unreachable_states
+@findex %define lr.keep_unreachable_states
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Requests that Bison allow unreachable parser states to remain in
+the parser tables.
+Bison considers a state to be unreachable if there exists no sequence of
+transitions from the start state to that state.
+A state can become unreachable during conflict resolution if Bison disables a
+shift action leading to it from a predecessor state.
+Keeping unreachable states is sometimes useful for analysis purposes, but they
+are useless in the generated parser.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{"false"}
+
+@item Caveats:
+
+@itemize @bullet
+@item Unreachable states may contain conflicts and may reduce rules not
+reduced in any other state.
+Thus, keeping unreachable states may induce warnings that are irrelevant to
+your parser's behavior, and it may eliminate warnings that are relevant.
+Of course, the change in warnings may actually be relevant to a parser table
+analysis that wants to keep unreachable states, so this behavior will likely
+remain in future Bison releases.
+
+@item While Bison is able to remove unreachable states, it is not guaranteed to
+remove other kinds of useless states.
+Specifically, when Bison disables reduce actions during conflict resolution,
+some goto actions may become useless, and thus some additional states may
+become useless.
+If Bison were to compute which goto actions were useless and then disable those
+actions, it could identify such states as unreachable and then remove those
+states.
+However, Bison does not compute which goto actions are useless.
+@end itemize
+@end itemize
+
+@item namespace
+@findex %define namespace
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Specifies the namespace for the parser class.
+For example, if you specify:
+
+@smallexample
+%define namespace "foo::bar"
+@end smallexample
+
+Bison uses @code{foo::bar} verbatim in references such as:
+
+@smallexample
+foo::bar::parser::semantic_type
+@end smallexample
+
+However, to open a namespace, Bison removes any leading @code{::} and then
+splits on any remaining occurrences:
+
+@smallexample
+namespace foo @{ namespace bar @{
+  class position;
+  class location;
+@} @}
+@end smallexample
+
+@item Accepted Values: Any absolute or relative C++ namespace reference without
+a trailing @code{"::"}.
+For example, @code{"foo"} or @code{"::foo::bar"}.
+
+@item Default Value: The value specified by @code{%name-prefix}, which defaults
+to @code{yy}.
+This usage of @code{%name-prefix} is for backward compatibility and can be
+confusing since @code{%name-prefix} also specifies the textual prefix for the
+lexical analyzer function.
+Thus, if you specify @code{%name-prefix}, it is best to also specify
+@code{%define namespace} so that @code{%name-prefix} @emph{only} affects the
+lexical analyzer function.
+For example, if you specify:
+
+@smallexample
+%define namespace "foo"
+%name-prefix "bar::"
+@end smallexample
+
+The parser namespace is @code{foo} and @code{yylex} is referenced as
+@code{bar::lex}.
+@end itemize
+@end itemize
+
 @end deffn
 
 @deffn {Directive} %defines
@@ -4912,9 +5040,9 @@ is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
 @code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, 
 @code{yypstate_new} and @code{yypstate_delete} will 
 also be renamed.  For example, if you use @samp{%name-prefix "c_"}, the 
-names become @code{c_parse}, @code{c_lex}, and so on.  In C++ parsers, 
-it is only the surrounding namespace which is named @var{prefix} instead 
-of @samp{yy}.
+names become @code{c_parse}, @code{c_lex}, and so on.
+For C++ parsers, see the @code{%define namespace} documentation in this
+section.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 @end deffn
 
@@ -4940,18 +5068,8 @@ Specify @var{file} for the parser file.
 @end deffn
 
 @deffn {Directive} %pure-parser
-Request a pure (reentrant) parser program (@pxref{Pure Decl, ,A Pure
-(Reentrant) Parser}).
-@end deffn
-
-@deffn {Directive} %push-parser
-Bison declaration to request a push parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-
-@deffn {Directive} %push-pull-parser
-Bison declaration to request a push and a pull parser.
-@xref{Push Decl, ,A Push Parser}.
+Deprecated version of @code{%define api.pure} (@pxref{Decl Summary, ,%define}),
+for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 
 @deffn {Directive} %require "@var{version}"
@@ -5163,8 +5281,8 @@ exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @findex yypush_parse
 
 You call the function @code{yypush_parse} to parse a single token.  This 
-function is available if either the @code{%push-parser} or 
-@code{%push-pull-parser} declaration is used.  
+function is available if either the @code{%define api.push_pull "push"} or 
+@code{%define api.push_pull "both"} declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun int yypush_parse (yypstate *yyps)
@@ -5178,7 +5296,7 @@ is required to finish parsing the grammar.
 @findex yypull_parse
 
 You call the function @code{yypull_parse} to parse the rest of the input 
-stream.  This function is available if the @code{%push-pull-parser} 
+stream.  This function is available if the @code{%define api.push_pull "both"} 
 declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 
@@ -5191,8 +5309,8 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 @findex yypstate_new
 
 You call the function @code{yypstate_new} to create a new parser instance.  
-This function is available if either the @code{%push-parser} or 
-@code{%push-pull-parser} declaration is used.  
+This function is available if either the @code{%define api.push_pull "push"} or 
+@code{%define api.push_pull "both"} declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun yypstate *yypstate_new (void)
@@ -5205,8 +5323,8 @@ or NULL if no memory was available.
 @findex yypstate_delete
 
 You call the function @code{yypstate_delete} to delete a parser instance.
-This function is available if either the @code{%push-parser} or 
-@code{%push-pull-parser} declaration is used.  
+function is available if either the @code{%define api.push_pull "push"} or 
+@code{%define api.push_pull "both"} declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun void yypstate_delete (yypstate *yyps)
@@ -5394,7 +5512,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}.
 @node Pure Calling
 @subsection Calling Conventions for Pure Parsers
 
-When you use the Bison declaration @code{%pure-parser} to request a
+When you use the Bison declaration @code{%define api.pure} to request a
 pure, reentrant parser, the global communication variables @code{yylval}
 and @code{yylloc} cannot be used.  (@xref{Pure Decl, ,A Pure (Reentrant)
 Parser}.)  In such parsers the two global variables are replaced by
@@ -5445,7 +5563,7 @@ int yylex   (int *nastiness);
 int yyparse (int *nastiness, int *randomness);
 @end example
 
-If @code{%pure-parser} is added:
+If @code{%define api.pure} is added:
 
 @example
 int yylex   (YYSTYPE *lvalp, int *nastiness);
@@ -5453,7 +5571,7 @@ int yyparse (int *nastiness, int *randomness);
 @end example
 
 @noindent
-and finally, if both @code{%pure-parser} and @code{%locations} are used:
+and finally, if both @code{%define api.pure} and @code{%locations} are used:
 
 @example
 int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
@@ -5519,7 +5637,7 @@ Obviously, in location tracking pure parsers, @code{yyerror} should have
 an access to the current location.
 This is indeed the case for the @acronym{GLR}
 parsers, but not for the Yacc parser, for historical reasons.  I.e., if
-@samp{%locations %pure-parser} is passed then the prototypes for
+@samp{%locations %define api.pure} is passed then the prototypes for
 @code{yyerror} are:
 
 @example
@@ -5537,13 +5655,14 @@ void yyerror (int *nastiness, char const *msg);  /* GLR parsers.   */
 Finally, @acronym{GLR} and Yacc parsers share the same @code{yyerror} calling
 convention for absolutely pure parsers, i.e., when the calling
 convention of @code{yylex} @emph{and} the calling convention of
-@code{%pure-parser} are pure.  I.e.:
+@code{%define api.pure} are pure.
+I.e.:
 
 @example
 /* Location tracking.  */
 %locations
 /* Pure yylex.  */
-%pure-parser
+%define api.pure
 %lex-param   @{int *nastiness@}
 /* Pure yyparse.  */
 %parse-param @{int *nastiness@}
@@ -7325,7 +7444,7 @@ with some set of possible lookahead tokens.  When run with
 @example
 state 8
 
-    exp  ->  exp . '+' exp  [$, '+', '-', '/']   (rule 1)
+    exp  ->  exp . '+' exp   (rule 1)
     exp  ->  exp '+' exp .  [$, '+', '-', '/']   (rule 1)
     exp  ->  exp . '-' exp   (rule 2)
     exp  ->  exp . '*' exp   (rule 3)
@@ -7587,6 +7706,9 @@ Print the version number of Bison and exit.
 @item --print-localedir
 Print the name of the directory containing locale-dependent data.
 
+@item --print-datadir
+Print the name of the directory containing skeletons and XSLT.
+
 @item -y
 @itemx --yacc
 Act more like the traditional Yacc command.  This can cause
@@ -7748,6 +7870,7 @@ the corresponding short option.
 @item @option{--no-lines}                   @tab @option{-l}
 @item @option{--output=@var{outfile}}       @tab @option{-o @var{outfile}}
 @item @option{--print-localedir}            @tab
+@item @option{--print-datadir}              @tab
 @item @option{--token-table}                @tab @option{-k}
 @item @option{--verbose}                    @tab @option{-v}
 @item @option{--version}                    @tab @option{-V}
@@ -7813,10 +7936,12 @@ The C++ @acronym{LALR}(1) parser is selected using the language directive,
 @option{--language=c++}.
 @xref{Decl Summary}.
 
-When run, @command{bison} will create several
-entities in the @samp{yy} namespace.  Use the @samp{%name-prefix}
-directive to change the namespace name, see @ref{Decl Summary}.  The
-various classes are generated in the following files:
+When run, @command{bison} will create several entities in the @samp{yy}
+namespace.
+@findex %define namespace
+Use the @samp{%define namespace} directive to change the namespace name, see
+@ref{Decl Summary}.
+The various classes are generated in the following files:
 
 @table @file
 @item position.hh
@@ -7998,7 +8123,7 @@ described by @var{m}.
 
 The parser invokes the scanner by calling @code{yylex}.  Contrary to C
 parsers, C++ parsers are always pure: there is no point in using the
-@code{%pure-parser} directive.  Therefore the interface is as follows.
+@code{%define api.pure} directive.  Therefore the interface is as follows.
 
 @deftypemethod {parser} {int} yylex (semantic_value_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...)
 Return the next token.  Its type is the return value, its semantic
@@ -8750,10 +8875,9 @@ The return type can be changed using @samp{%define "stype"
 @end deftypemethod
 
 
-If @code{%pure-parser} is not specified, the lexer interface
-resides in the same class (@code{YYParser}) as the Bison-generated
-parser. The fields and methods that are provided to
-this end are as follows.
+The lexer interface resides in the same class (@code{YYParser}) as the
+Bison-generated parser.
+The fields and methods that are provided to this end are as follows.
 
 @deftypemethod {YYParser} {void} error (Location @var{l}, String @var{m})
 As explained in @pxref{Java Parser Interface}, this method is defined
@@ -8886,7 +9010,7 @@ or
 @display
 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}.
+although I did specify @code{%define api.pure}.
 @end display
 
 These problems typically come not from Bison itself, but from
@@ -9448,18 +9572,8 @@ Bison declaration to assign a precedence to a specific rule.
 @end deffn
 
 @deffn {Directive} %pure-parser
-Bison declaration to request a pure (reentrant) parser.
-@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
-@end deffn
-
-@deffn {Directive} %push-parser
-Bison declaration to request a push parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-
-@deffn {Directive} %push-pull-parser
-Bison declaration to request a push and a pull parser.
-@xref{Push Decl, ,A Push Parser}.
+Deprecated version of @code{%define api.pure} (@pxref{Decl Summary, ,%define}),
+for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 
 @deffn {Directive} %require "@var{version}"