+Bison will warn if a @var{variable} is defined multiple times.
+
+Omitting @code{"@var{value}"} is always equivalent to specifying it as
+@code{""}.
+
+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:
+
+@enumerate
+@item @code{"@var{value}"} is @code{"true"}
+
+@item @code{"@var{value}"} is omitted (or is @code{""}).
+This is equivalent to @code{"true"}.
+
+@item @code{"@var{value}"} is @code{"false"}.
+
+@item @var{variable} is never defined.
+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:
+
+@table @code
+@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
+@c api.pure
+
+@item api.push_pull
+@findex %define api.push_pull
+
+@itemize @bullet
+@item Language(s): C (deterministic parsers 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
+@c api.push_pull
+
+@item error-verbose
+@findex %define error-verbose
+@itemize
+@item Languages(s):
+all.
+@item Purpose:
+Enable the generation of more verbose error messages than a instead of
+just plain @w{@code{"syntax error"}}. @xref{Error Reporting, ,The Error
+Reporting Function @code{yyerror}}.
+@item Accepted Values:
+Boolean
+@item Default Value:
+@code{false}
+@end itemize
+@c error-verbose
+
+
+@item lr.default_reductions
+@cindex default reductions
+@findex %define lr.default_reductions
+@cindex delayed syntax errors
+@cindex syntax errors delayed
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Specifies the kind of states that are permitted to
+contain default reductions.
+That is, in such a state, Bison declares the reduction with the largest
+lookahead set to be the default reduction and then removes that
+lookahead set.
+The advantages of default reductions are discussed below.
+The disadvantage is that, when the generated parser encounters a
+syntactically unacceptable token, the parser might then perform
+unnecessary default reductions before it can detect the syntax error.
+
+(This feature is experimental.
+More user feedback will help to stabilize it.)
+
+@item Accepted Values:
+@itemize
+@item @code{"all"}.
+For @acronym{LALR} and @acronym{IELR} parsers (@pxref{Decl
+Summary,,lr.type}) by default, all states are permitted to contain
+default reductions.
+The advantage is that parser table sizes can be significantly reduced.
+The reason Bison does not by default attempt to address the disadvantage
+of delayed syntax error detection is that this disadvantage is already
+inherent in @acronym{LALR} and @acronym{IELR} parser tables.
+That is, unlike in a canonical @acronym{LR} state, the lookahead sets of
+reductions in an @acronym{LALR} or @acronym{IELR} state can contain
+tokens that are syntactically incorrect for some left contexts.
+
+@item @code{"consistent"}.
+@cindex consistent states
+A consistent state is a state that has only one possible action.
+If that action is a reduction, then the parser does not need to request
+a lookahead token from the scanner before performing that action.
+However, the parser only recognizes the ability to ignore the lookahead
+token when such a reduction is encoded as a default reduction.
+Thus, if default reductions are permitted in and only in consistent
+states, then a canonical @acronym{LR} parser reports a syntax error as
+soon as it @emph{needs} the syntactically unacceptable token from the
+scanner.
+
+@item @code{"accepting"}.
+@cindex accepting state
+By default, the only default reduction permitted in a canonical
+@acronym{LR} parser is the accept action in the accepting state, which
+the parser reaches only after reading all tokens from the input.
+Thus, the default canonical @acronym{LR} parser reports a syntax error
+as soon as it @emph{reaches} the syntactically unacceptable token
+without performing any extra reductions.
+@end itemize
+
+@item Default Value:
+@itemize
+@item @code{"accepting"} if @code{lr.type} is @code{"canonical LR"}.
+@item @code{"all"} otherwise.
+@end itemize
+@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
+@c lr.keep_unreachable_states
+
+@item lr.type
+@findex %define lr.type
+@cindex @acronym{LALR}
+@cindex @acronym{IELR}
+@cindex @acronym{LR}
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Specifies the type of parser tables within the
+@acronym{LR}(1) family.
+(This feature is experimental.
+More user feedback will help to stabilize it.)
+
+@item Accepted Values:
+@itemize
+@item @code{"LALR"}.
+While Bison generates @acronym{LALR} parser tables by default for
+historical reasons, @acronym{IELR} or canonical @acronym{LR} is almost
+always preferable for deterministic parsers.
+The trouble is that @acronym{LALR} parser tables can suffer from
+mysterious conflicts and thus may not accept the full set of sentences
+that @acronym{IELR} and canonical @acronym{LR} accept.
+@xref{Mystery Conflicts}, for details.
+However, there are at least two scenarios where @acronym{LALR} may be
+worthwhile:
+@itemize
+@cindex @acronym{GLR} with @acronym{LALR}
+@item When employing @acronym{GLR} parsers (@pxref{GLR Parsers}), if you
+do not resolve any conflicts statically (for example, with @code{%left}
+or @code{%prec}), then the parser explores all potential parses of any
+given input.
+In this case, the use of @acronym{LALR} parser tables is guaranteed not
+to alter the language accepted by the parser.
+@acronym{LALR} parser tables are the smallest parser tables Bison can
+currently generate, so they may be preferable.
+
+@item Occasionally during development, an especially malformed grammar
+with a major recurring flaw may severely impede the @acronym{IELR} or
+canonical @acronym{LR} parser table generation algorithm.
+@acronym{LALR} can be a quick way to generate parser tables in order to
+investigate such problems while ignoring the more subtle differences
+from @acronym{IELR} and canonical @acronym{LR}.
+@end itemize
+
+@item @code{"IELR"}.
+@acronym{IELR} is a minimal @acronym{LR} algorithm.
+That is, given any grammar (@acronym{LR} or non-@acronym{LR}),
+@acronym{IELR} and canonical @acronym{LR} always accept exactly the same
+set of sentences.
+However, as for @acronym{LALR}, the number of parser states is often an
+order of magnitude less for @acronym{IELR} than for canonical
+@acronym{LR}.
+More importantly, because canonical @acronym{LR}'s extra parser states
+may contain duplicate conflicts in the case of non-@acronym{LR}
+grammars, the number of conflicts for @acronym{IELR} is often an order
+of magnitude less as well.
+This can significantly reduce the complexity of developing of a grammar.
+
+@item @code{"canonical LR"}.
+@cindex delayed syntax errors
+@cindex syntax errors delayed
+The only advantage of canonical @acronym{LR} over @acronym{IELR} is
+that, for every left context of every canonical @acronym{LR} state, the
+set of tokens accepted by that state is the exact set of tokens that is
+syntactically acceptable in that left context.
+Thus, the only difference in parsing behavior is that the canonical
+@acronym{LR} parser can report a syntax error as soon as possible
+without performing any unnecessary reductions.
+@xref{Decl Summary,,lr.default_reductions}, for further details.
+Even when canonical @acronym{LR} behavior is ultimately desired,
+@acronym{IELR}'s elimination of duplicate conflicts should still
+facilitate the development of a grammar.
+@end itemize
+
+@item Default Value: @code{"LALR"}
+@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
projects / bison.git / blobdiff