+@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}.
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+@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 use rules not used 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
+@c namespace
+
+@item parse.assert
+@findex %define parse.assert
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Issue runtime assertions to catch invalid uses.
+In C++, when variants are used, symbols must be constructed and
+destroyed properly. This option checks these constraints.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@end itemize
+@c parse.assert
+
+@item parse.trace
+@findex %define parse.trace
+
+@itemize
+@item Languages(s): C, C++
+
+@item Purpose: Require parser instrumentation for tracing.
+In C/C++, define the macro @code{YYDEBUG} to 1 in the parser file if it
+is not already defined, so that the debugging facilities are compiled.
+@xref{Tracing, ,Tracing Your Parser}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@end itemize
+@end table
+@c parse.trace
+@end deffn
+@c %define
+
+@deffn {Directive} %defines
+Write a header file containing macro definitions for the token type
+names defined in the grammar as well as a few other declarations.
+If the parser output file is named @file{@var{name}.c} then this file
+is named @file{@var{name}.h}.
+
+For C parsers, the output header declares @code{YYSTYPE} unless
+@code{YYSTYPE} is already defined as a macro or you have used a
+@code{<@var{type}>} tag without using @code{%union}.
+Therefore, if you are using a @code{%union}
+(@pxref{Multiple Types, ,More Than One Value Type}) with components that
+require other definitions, or if you have defined a @code{YYSTYPE} macro
+or type definition
+(@pxref{Value Type, ,Data Types of Semantic Values}), you need to
+arrange for these definitions to be propagated to all modules, e.g., by
+putting them in a prerequisite header that is included both by your
+parser and by any other module that needs @code{YYSTYPE}.
+
+Unless your parser is pure, the output header declares @code{yylval}
+as an external variable. @xref{Pure Decl, ,A Pure (Reentrant)
+Parser}.
+
+If you have also used locations, the output header declares
+@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
+the @code{YYSTYPE} macro and @code{yylval}. @xref{Locations, ,Tracking
+Locations}.
+
+This output file is normally essential if you wish to put the definition
+of @code{yylex} in a separate source file, because @code{yylex}
+typically needs to be able to refer to the above-mentioned declarations
+and to the token type codes. @xref{Token Values, ,Semantic Values of
+Tokens}.
+
+@findex %code requires
+@findex %code provides
+If you have declared @code{%code requires} or @code{%code provides}, the output
+header also contains their code.
+@xref{Decl Summary, ,%code}.
+@end deffn
+
+@deffn {Directive} %defines @var{defines-file}
+Same as above, but save in the file @var{defines-file}.
+@end deffn
+
+@deffn {Directive} %destructor
+Specify how the parser should reclaim the memory associated to
+discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
+@end deffn
+
+@deffn {Directive} %file-prefix "@var{prefix}"
+Specify a prefix to use for all Bison output file names. The names are
+chosen as if the input file were named @file{@var{prefix}.y}.
+@end deffn
+
+@deffn {Directive} %language "@var{language}"
+Specify the programming language for the generated parser. Currently
+supported languages include C, C++, and Java.
+@var{language} is case-insensitive.
+
+This directive is experimental and its effect may be modified in future
+releases.
+@end deffn
+
+@deffn {Directive} %locations
+Generate the code processing the locations (@pxref{Action Features,
+,Special Features for Use in Actions}). This mode is enabled as soon as
+the grammar uses the special @samp{@@@var{n}} tokens, but if your
+grammar does not use it, using @samp{%locations} allows for more
+accurate syntax error messages.
+@end deffn
+
+@deffn {Directive} %name-prefix "@var{prefix}"
+Rename the external symbols used in the parser so that they start with
+@var{prefix} instead of @samp{yy}. The precise list of symbols renamed
+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}. 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
+
+@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-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 C compiler and debuggers will associate errors and object code with
+your source file (the grammar file). This directive causes them to
+associate errors with the parser file, treating it an independent source
+file in its own right.
+@end deffn
+
+@deffn {Directive} %output "@var{file}"
+Specify @var{file} for the parser file.
+@end deffn
+
+@deffn {Directive} %pure-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}"
+Require version @var{version} or higher of Bison. @xref{Require Decl, ,
+Require a Version of Bison}.
+@end deffn
+
+@deffn {Directive} %skeleton "@var{file}"
+Specify the skeleton to use.
+
+@c You probably don't need this option unless you are developing Bison.
+@c You should use @code{%language} if you want to specify the skeleton for a
+@c different language, because it is clearer and because it will always choose the
+@c correct skeleton for non-deterministic or push parsers.
+
+If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
+file in the Bison installation directory.
+If it does, @var{file} is an absolute file name or a file name relative to the
+directory of the grammar file.
+This is similar to how most shells resolve commands.
+@end deffn
+
+@deffn {Directive} %token-table
+Generate an array of token names in the parser file. The name of the
+array is @code{yytname}; @code{yytname[@var{i}]} is the name of the
+token whose internal Bison token code number is @var{i}. The first
+three elements of @code{yytname} correspond to the predefined tokens
+@code{"$end"},
+@code{"error"}, and @code{"$undefined"}; after these come the symbols
+defined in the grammar file.
+
+The name in the table includes all the characters needed to represent
+the token in Bison. For single-character literals and literal
+strings, this includes the surrounding quoting characters and any
+escape sequences. For example, the Bison single-character literal
+@code{'+'} corresponds to a three-character name, represented in C as
+@code{"'+'"}; and the Bison two-character literal string @code{"\\/"}
+corresponds to a five-character name, represented in C as
+@code{"\"\\\\/\""}.
+
+When you specify @code{%token-table}, Bison also generates macro
+definitions for macros @code{YYNTOKENS}, @code{YYNNTS}, and
+@code{YYNRULES}, and @code{YYNSTATES}:
+
+@table @code
+@item YYNTOKENS
+The highest token number, plus one.
+@item YYNNTS
+The number of nonterminal symbols.
+@item YYNRULES
+The number of grammar rules,
+@item YYNSTATES
+The number of parser states (@pxref{Parser States}).
+@end table
+@end deffn
+
+@deffn {Directive} %verbose
+Write an extra output file containing verbose descriptions of the
+parser states and what is done for each type of lookahead token in
+that state. @xref{Understanding, , Understanding Your Parser}, for more
+information.
+@end deffn
+
+@deffn {Directive} %yacc
+Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
+including its naming conventions. @xref{Bison Options}, for more.
+@end deffn
+
+
+@node Multiple Parsers
+@section Multiple Parsers in the Same Program
+
+Most programs that use Bison parse only one language and therefore contain
+only one Bison parser. But what if you want to parse more than one
+language with the same program? Then you need to avoid a name conflict
+between different definitions of @code{yyparse}, @code{yylval}, and so on.
+
+The easy way to do this is to use the option @samp{-p @var{prefix}}
+(@pxref{Invocation, ,Invoking Bison}). This renames the interface
+functions and variables of the Bison parser to start with @var{prefix}
+instead of @samp{yy}. You can use this to give each parser distinct
+names that do not conflict.
+
+The precise list of symbols renamed is @code{yyparse}, @code{yylex},
+@code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
+@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
+name is used in different parsers. For example, @code{YYSTYPE} is not
+renamed, but defining this in different ways in different parsers causes
+no trouble (@pxref{Value Type, ,Data Types of Semantic Values}).
+
+The @samp{-p} option works by adding macro definitions to the beginning
+of the parser source file, defining @code{yyparse} as
+@code{@var{prefix}parse}, and so on. This effectively substitutes one
+name for the other in the entire parser file.
+
+@node Interface
+@chapter Parser C-Language Interface
+@cindex C-language interface
+@cindex interface
+
+The Bison parser is actually a C function named @code{yyparse}. Here we
+describe the interface conventions of @code{yyparse} and the other
+functions that it needs to use.
+
+Keep in mind that the parser uses many C identifiers starting with
+@samp{yy} and @samp{YY} for internal purposes. If you use such an
+identifier (aside from those in this manual) in an action or in epilogue
+in the grammar file, you are likely to run into trouble.
+
+@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}.
+* Action Features:: Special features for use in actions.
+* Internationalization:: How to let the parser speak in the user's
+ native language.
+@end menu
+
+@node Parser Function
+@section The Parser Function @code{yyparse}
+@findex yyparse
+
+You call the function @code{yyparse} to cause parsing to occur. This
+function reads tokens, executes actions, and ultimately returns when it
+encounters end-of-input or an unrecoverable syntax error. You can also
+write an action which directs @code{yyparse} to return immediately
+without reading further.
+
+
+@deftypefun int yyparse (void)
+The value returned by @code{yyparse} is 0 if parsing was successful (return
+is due to end-of-input).
+
+The value is 1 if parsing failed because of invalid input, i.e., input
+that contains a syntax error or that causes @code{YYABORT} to be
+invoked.
+
+The value is 2 if parsing failed due to memory exhaustion.
+@end deftypefun
+
+In an action, you can cause immediate return from @code{yyparse} by using
+these macros:
+
+@defmac YYACCEPT
+@findex YYACCEPT
+Return immediately with value 0 (to report success).
+@end defmac
+
+@defmac YYABORT
+@findex YYABORT
+Return immediately with value 1 (to report failure).
+@end defmac
+
+If you use a reentrant parser, you can optionally pass additional
+parameter information to it in a reentrant way. To do so, use the
+declaration @code{%parse-param}:
+
+@deffn {Directive} %parse-param @{@var{argument-declaration}@}
+@findex %parse-param
+Declare that an argument declared by the braced-code
+@var{argument-declaration} is an additional @code{yyparse} argument.
+The @var{argument-declaration} is used when declaring
+functions or prototypes. The last identifier in
+@var{argument-declaration} must be the argument name.
+@end deffn
+
+Here's an example. Write this in the parser:
+
+@example
+%parse-param @{int *nastiness@}
+%parse-param @{int *randomness@}
+@end example
+
+@noindent
+Then call the parser like this:
+
+@example
+@{
+ int nastiness, randomness;
+ @dots{} /* @r{Store proper data in @code{nastiness} and @code{randomness}.} */
+ value = yyparse (&nastiness, &randomness);
+ @dots{}
+@}
+@end example
+
+@noindent
+In the grammar actions, use expressions like this to refer to the data:
+
+@example
+exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
+@end example
+
+@node Push Parser Function
+@section The Push Parser Function @code{yypush_parse}
+@findex yypush_parse
+
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+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
+
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+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
+
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+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 0 if no memory was available.
+In impure mode, it will also return 0 if a parser instance is currently
+allocated.
+@end deftypefun
+
+@node Parser Delete Function
+@section The Parser Delete Function @code{yystate_delete}
+@findex yypstate_delete
+
+(The current push parsing interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+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
projects / bison.git / blobdiff