* Expect Decl:: Suppressing warnings about parsing conflicts.
* Start Decl:: Specifying the start symbol.
* Pure Decl:: Requesting a reentrant parser.
+* Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations.
Parser C-Language Interface
Copying This Manual
-* GNU Free Documentation License:: License for copying this manual.
+* Copying This Manual:: License for copying this manual.
@end detailmenu
@end menu
exception@dots{}''. The text spells out the exact terms of the
exception.
-@include gpl.texi
+@node Copying
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@include gpl-3.0.texi
@node Concepts
@chapter The Concepts of Bison
* Expect Decl:: Suppressing warnings about parsing conflicts.
* Start Decl:: Specifying the start symbol.
* Pure Decl:: Requesting a reentrant parser.
+* Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations.
@end menu
@code{yylloc} become local variables in @code{yyparse}, and a different
calling convention is used for the lexical analyzer function
@code{yylex}. @xref{Pure Calling, ,Calling Conventions for Pure
-Parsers}, for the details of this. The variable @code{yynerrs} also
-becomes local in @code{yyparse} (@pxref{Error Reporting, ,The Error
+Parsers}, for the details of this. The variable @code{yynerrs}
+becomes local in @code{yyparse} in pull mode but it becomes a member
+of yypstate in push mode. (@pxref{Error Reporting, ,The Error
Reporting Function @code{yyerror}}). The convention for calling
@code{yyparse} itself is unchanged.
You can generate either a pure parser or a nonreentrant parser from any
valid grammar.
+@node Push Decl
+@subsection A Push Parser
+@cindex push parser
+@cindex 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
+each time a new token is made available.
+
+A push parser is typically useful when the parser is part of a
+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 following Bison declaration says that you want the parser to be a push
+parser (@pxref{Decl Summary,,%define api.push_pull}):
+
+@example
+%define api.push_pull "push"
+@end example
+
+In almost all cases, you want to ensure that your push parser is also
+a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}). The only
+time you should create an impure push parser is to have backwards
+compatibility with the impure Yacc pull mode interface. Unless you know
+what you are doing, your declarations should look like this:
+
+@example
+%pure-parser
+%define api.push_pull "push"
+@end example
+
+There is a major notable functional difference between the pure push parser
+and the impure push parser. It is acceptable for a pure push parser to have
+many parser instances, of the same type of parser, in memory at the same time.
+An impure push parser should only use one parser at a time.
+
+When a push parser is selected, Bison will generate some new symbols in
+the generated parser. @code{yypstate} is a structure that the generated
+parser uses to store the parser's state. @code{yypstate_new} is the
+function that will create a new parser instance. @code{yypstate_delete}
+will free the resources associated with the corresponding parser instance.
+Finally, @code{yypush_parse} is the function that should be called whenever a
+token is available to provide the parser. A trivial example
+of using a pure push parser would look like this:
+
+@example
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+ status = yypush_parse (ps, yylex (), NULL);
+@} while (status == YYPUSH_MORE);
+yypstate_delete (ps);
+@end example
+
+If the user decided to use an impure push parser, a few things about
+the generated parser will change. The @code{yychar} variable becomes
+a global variable instead of a variable in the @code{yypush_parse} function.
+For this reason, the signature of the @code{yypush_parse} function is
+changed to remove the token as a parameter. A nonreentrant push parser
+example would thus look like this:
+
+@example
+extern int yychar;
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+ yychar = yylex ();
+ status = yypush_parse (ps);
+@} while (status == YYPUSH_MORE);
+yypstate_delete (ps);
+@end example
+
+That's it. Notice the next token is put into the global variable @code{yychar}
+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{%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{%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
+write your own @code{yypull_parse} function that knows when to quit looking
+for input. An example of using the @code{yypull_parse} function would look
+like this:
+
+@example
+yypstate *ps = yypstate_new ();
+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{%define api.push_pull "both"} as it did for
+@code{%define api.push_pull "push"}.
+
@node Decl Summary
@subsection Bison Declaration Summary
@cindex 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++
Omitting @code{"@var{value}"} is always equivalent to specifying it as
@code{""}.
-Some @var{variable}s may be used as booleans.
+Some @var{variable}s may be used as Booleans.
In this case, Bison will complain if the variable definition does not meet one
of the following four conditions:
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
in C parsers
is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
@code{yylval}, @code{yychar}, @code{yydebug}, and
-(if locations are used) @code{yylloc}. 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}.
+(if locations are used) @code{yylloc}. If you use a push parser,
+@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.
+For C++ parsers, see the @code{%define namespace} documentation in this
+section.
@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
@end deffn
@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
-declarations.
-
-This option also tells Bison to write the C code for the grammar actions
-into a file named @file{@var{file}.act}, in the form of a
-brace-surrounded body fit for a @code{switch} statement.
-@end deffn
-
@deffn {Directive} %no-lines
Don't generate any @code{#line} preprocessor commands in the parser
file. Ordinarily Bison writes these commands in the parser file so that
The precise list of symbols renamed is @code{yyparse}, @code{yylex},
@code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
-@code{yychar} and @code{yydebug}. For example, if you use @samp{-p c},
-the names become @code{cparse}, @code{clex}, and so on.
+@code{yychar} and @code{yydebug}. If you use a push parser,
+@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{-p c}, the names become @code{cparse},
+@code{clex}, and so on.
@strong{All the other variables and macros associated with Bison are not
renamed.} These others are not global; there is no conflict if the same
@menu
* Parser Function:: How to call @code{yyparse} and what it returns.
+* Push Parser Function:: How to call @code{yypush_parse} and what it returns.
+* Pull Parser Function:: How to call @code{yypull_parse} and what it returns.
+* Parser Create Function:: How to call @code{yypstate_new} and what it
+ returns.
+* Parser Delete Function:: How to call @code{yypstate_delete} and what it
+ returns.
* Lexical:: You must supply a function @code{yylex}
which reads tokens.
* Error Reporting:: You must supply a function @code{yyerror}.
exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
@end example
+@node Push Parser Function
+@section The Push Parser Function @code{yypush_parse}
+@findex yypush_parse
+
+You call the function @code{yypush_parse} to parse a single token. 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 int yypush_parse (yypstate *yyps)
+The value returned by @code{yypush_parse} is the same as for yyparse with the
+following exception. @code{yypush_parse} will return YYPUSH_MORE if more input
+is required to finish parsing the grammar.
+@end deftypefun
+
+@node Pull Parser Function
+@section The Pull Parser Function @code{yypull_parse}
+@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{%define api.push_pull "both"}
+declaration is used.
+@xref{Push Decl, ,A Push Parser}.
+
+@deftypefun int yypull_parse (yypstate *yyps)
+The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
+@end deftypefun
+
+@node Parser Create Function
+@section The Parser Create Function @code{yystate_new}
+@findex yypstate_new
+
+You call the function @code{yypstate_new} to create a new parser instance.
+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)
+The fuction will return a valid parser instance if there was memory available
+or NULL if no memory was available.
+@end deftypefun
+
+@node Parser Delete Function
+@section The Parser Delete Function @code{yystate_delete}
+@findex yypstate_delete
+
+You call the function @code{yypstate_delete} to delete a parser instance.
+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)
+This function will reclaim the memory associated with a parser instance.
+After this call, you should no longer attempt to use the parser instance.
+@end deftypefun
@node Lexical
@section The Lexical Analyzer Function @code{yylex}
@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
grammar file. This option causes them to associate errors with the
parser file, treating it as an independent source file in its own right.
-@item -n
-@itemx --no-parser
-Pretend that @code{%no-parser} was specified. @xref{Decl Summary}.
-
@item -S @var{file}
@itemx --skeleton=@var{file}
Specify the skeleton to use, similar to @code{%skeleton}
@item @option{--help} @tab @option{-h}
@item @option{--name-prefix=@var{prefix}} @tab @option{-p @var{name-prefix}}
@item @option{--no-lines} @tab @option{-l}
-@item @option{--no-parser} @tab @option{-n}
@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
@deffn {Variable} yynerrs
Global variable which Bison increments each time it reports a syntax error.
-(In a pure parser, it is a local variable within @code{yyparse}.)
+(In a pure parser, it is a local variable within @code{yyparse}. In a
+pure push parser, it is a member of yypstate.)
@xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
@end deffn
parsing. @xref{Parser Function, ,The Parser Function @code{yyparse}}.
@end deffn
+@deffn {Function} yypstate_delete
+The function to delete a parser instance, produced by Bison in push mode;
+call this function to delete the memory associated with a parser.
+@xref{Parser Delete Function, ,The Parser Delete Function
+@code{yypstate_delete}}.
+@end deffn
+
+@deffn {Function} yypstate_new
+The function to create a parser instance, produced by Bison in push mode;
+call this function to create a new parser.
+@xref{Parser Create Function, ,The Parser Create Function
+@code{yypstate_new}}.
+@end deffn
+
+@deffn {Function} yypull_parse
+The parser function produced by Bison in push mode; call this function to
+parse the rest of the input stream.
+@xref{Pull Parser Function, ,The Pull Parser Function
+@code{yypull_parse}}.
+@end deffn
+
+@deffn {Function} yypush_parse
+The parser function produced by Bison in push mode; call this function to
+parse a single token. @xref{Push Parser Function, ,The Push Parser Function
+@code{yypush_parse}}.
+@end deffn
+
@deffn {Macro} YYPARSE_PARAM
An obsolete macro for specifying the name of a parameter that
@code{yyparse} should accept. The use of this macro is deprecated, and
@node Copying This Manual
@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License:: License for copying this manual.
-@end menu
-
@include fdl.texi
@node Index
projects / bison.git / blobdiff