@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
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
@example
%pure-parser
-%push-parser
+%define api.push_pull "push"
@end example
There is a major notable functional difference between the pure push parser
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
@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}.
+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
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++
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.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
@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
(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}.
-@end deffn
-
@deffn {Directive} %require "@var{version}"
Require version @var{version} or higher of Bison. @xref{Require Decl, ,
Require a Version of Bison}.
@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)
@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}.
@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)
@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)
@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)
@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
@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}
@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
@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}.
-@end deffn
-
@deffn {Directive} %require "@var{version}"
Require version @var{version} or higher of Bison. @xref{Require Decl, ,
Require a Version of Bison}.
projects / bison.git / blobdiff