+@itemize
+@item Languages(s): all
+
+@item Purpose:
+Add a prefix to the token names when generating their definition in the
+target language. For instance
+
+@example
+%token FILE for ERROR
+%define api.tokens.prefix "TOK_"
+%%
+start: FILE for ERROR;
+@end example
+
+@noindent
+generates the definition of the symbols @code{TOK_FILE}, @code{TOK_for},
+and @code{TOK_ERROR} in the generated source files. In particular, the
+scanner must use these prefixed token names, while the grammar itself
+may still use the short names (as in the sample rule given above). The
+generated informational files (@file{*.output}, @file{*.xml},
+@file{*.dot}) are not modified by this prefix. See @ref{Calc++ Parser}
+and @ref{Calc++ Scanner}, for a complete example.
+
+@item Accepted Values:
+Any string. Should be a valid identifier prefix in the target language,
+in other words, it should typically be an identifier itself (sequence of
+letters, underscores, and ---not at the beginning--- digits).
+
+@item Default Value:
+empty
+@end itemize
+@c api.tokens.prefix
+
+
+@c ================================================== lex_symbol
+@item variant
+@findex %define lex_symbol
+
+@itemize @bullet
+@item Language(s):
+C++
+
+@item Purpose:
+When variant-based semantic values are enabled (@pxref{C++ Variants}),
+request that symbols be handled as a whole (type, value, and possibly
+location) in the scanner. @xref{Complete Symbols}, for details.
+
+@item Accepted Values:
+Boolean.
+
+@item Default Value:
+@code{false}
+@end itemize
+@c lex_symbol
+
+
+@c ================================================== lr.default-reductions
+
+@item lr.default-reductions
+@cindex default reductions
+@findex %define lr.default-reductions
+@cindex delayed syntax errors
+@cindex syntax errors delayed
+@cindex LAC
+@findex %nonassoc
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Specify the kind of states that are permitted to
+contain default reductions.
+That is, in such a state, Bison selects the reduction with the largest
+lookahead set to be the default parser action and then removes that
+lookahead set.
+(The ability to specify where default reductions should be used is
+experimental.
+More user feedback will help to stabilize it.)
+
+@item Accepted Values:
+@itemize
+@item @code{all}.
+This is the traditional Bison behavior.
+The main advantage is a significant decrease in the size of the parser
+tables.
+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.
+Such delayed syntax error detection is usually inherent in
+LALR and IELR parser tables anyway due to
+LR state merging (@pxref{Decl Summary,,lr.type}).
+Furthermore, the use of @code{%nonassoc} can contribute to delayed
+syntax error detection even in the case of canonical LR.
+As an experimental feature, delayed syntax error detection can be
+overcome in all cases by enabling LAC (@pxref{Decl
+Summary,,parse.lac}, for details, including a discussion of the effects
+of delayed syntax error detection).
+
+@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 recognizes the ability to ignore the lookahead token
+in this way only when such a reduction is encoded as a default
+reduction.
+Thus, if default reductions are permitted only in consistent states,
+then a canonical LR parser that does not employ
+@code{%nonassoc} detects a syntax error as soon as it @emph{needs} the
+syntactically unacceptable token from the scanner.
+
+@item @code{accepting}.
+@cindex accepting state
+In the accepting state, the default reduction is actually the accept
+action.
+In this case, a canonical LR parser that does not employ
+@code{%nonassoc} detects a syntax error as soon as it @emph{reaches} the
+syntactically unacceptable token in the input.
+That is, it does not perform 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
+
+@c ============================================ lr.keep-unreachable-states
+
+@item lr.keep-unreachable-states
+@findex %define lr.keep-unreachable-states
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Request 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
+
+@c ================================================== lr.type
+
+@item lr.type
+@findex %define lr.type
+@cindex LALR
+@cindex IELR
+@cindex LR
+
+@itemize @bullet
+@item Language(s): all
+
+@item Purpose: Specify the type of parser tables within the
+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 LALR parser tables by default for
+historical reasons, IELR or canonical LR is almost
+always preferable for deterministic parsers.
+The trouble is that LALR parser tables can suffer from
+mysterious conflicts and thus may not accept the full set of sentences
+that IELR and canonical LR accept.
+@xref{Mystery Conflicts}, for details.
+However, there are at least two scenarios where LALR may be
+worthwhile:
+@itemize
+@cindex GLR with LALR
+@item When employing 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 LALR parser tables is guaranteed not
+to alter the language accepted by the parser.
+LALR parser tables are the smallest parser tables Bison can
+currently generate, so they may be preferable.
+Nevertheless, once you begin to resolve conflicts statically,
+GLR begins to behave more like a deterministic parser, and so
+IELR and canonical LR can be helpful to avoid
+LALR's mysterious behavior.
+
+@item Occasionally during development, an especially malformed grammar
+with a major recurring flaw may severely impede the IELR or
+canonical LR parser table generation algorithm.
+LALR can be a quick way to generate parser tables in order to
+investigate such problems while ignoring the more subtle differences
+from IELR and canonical LR.
+@end itemize
+
+@item @code{ielr}.
+IELR is a minimal LR algorithm.
+That is, given any grammar (LR or non-LR),
+IELR and canonical LR always accept exactly the same
+set of sentences.
+However, as for LALR, the number of parser states is often an
+order of magnitude less for IELR than for canonical
+LR.
+More importantly, because canonical LR's extra parser states
+may contain duplicate conflicts in the case of non-LR
+grammars, the number of conflicts for 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
+@cindex LAC
+@findex %nonassoc
+While inefficient, canonical LR parser tables can be an
+interesting means to explore a grammar because they have a property that
+IELR and LALR tables do not.
+That is, if @code{%nonassoc} is not used and default reductions are left
+disabled (@pxref{Decl Summary,,lr.default-reductions}), then, for every
+left context of every canonical LR state, the set of tokens
+accepted by that state is guaranteed to be the exact set of tokens that
+is syntactically acceptable in that left context.
+It might then seem that an advantage of canonical LR parsers
+in production is that, under the above constraints, they are guaranteed
+to detect a syntax error as soon as possible without performing any
+unnecessary reductions.
+However, IELR parsers using LAC (@pxref{Decl
+Summary,,parse.lac}) are also able to achieve this behavior without
+sacrificing @code{%nonassoc} or default reductions.
+@end itemize
+
+@item Default Value: @code{lalr}
+@end itemize
+
+
+@c ================================================== namespace
+@item namespace
+@findex %define namespace
+Obsoleted by @code{api.namespace}
+@c namespace
+
+
+@c ================================================== parse.assert
+@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 (@pxref{C++ Variants}), 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
+
+
+@c ================================================== parse.error
+@item parse.error
+@findex %define parse.error
+@itemize
+@item Languages(s):
+all
+@item Purpose:
+Control the kind of error messages passed to the error reporting
+function. @xref{Error Reporting, ,The Error Reporting Function
+@code{yyerror}}.
+@item Accepted Values:
+@itemize
+@item @code{simple}
+Error messages passed to @code{yyerror} are simply @w{@code{"syntax
+error"}}.
+@item @code{verbose}
+Error messages report the unexpected token, and possibly the expected
+ones.
+@end itemize
+
+@item Default Value:
+@code{simple}
+@end itemize
+@c parse.error
+
+
+@c ================================================== parse.lac
+@item parse.lac
+@findex %define parse.lac
+@cindex LAC
+@cindex lookahead correction
+
+@itemize
+@item Languages(s): C
+
+@item Purpose: Enable LAC (lookahead correction) to improve
+syntax error handling.
+
+Canonical LR, IELR, and LALR can suffer
+from a couple of problems upon encountering a syntax error. First, the
+parser might perform additional parser stack reductions before
+discovering the syntax error. Such reductions perform user semantic
+actions that are unexpected because they are based on an invalid token,
+and they cause error recovery to begin in a different syntactic context
+than the one in which the invalid token was encountered. Second, when
+verbose error messages are enabled (with @code{%error-verbose} or
+@code{#define YYERROR_VERBOSE}), the expected token list in the syntax
+error message can both contain invalid tokens and omit valid tokens.
+
+The culprits for the above problems are @code{%nonassoc}, default
+reductions in inconsistent states, and parser state merging. Thus,
+IELR and LALR suffer the most. Canonical
+LR can suffer only if @code{%nonassoc} is used or if default
+reductions are enabled for inconsistent states.
+
+LAC is a new mechanism within the parsing algorithm that
+completely solves these problems for canonical LR,
+IELR, and LALR without sacrificing @code{%nonassoc},
+default reductions, or state mering. Conceptually, the mechanism is
+straight-forward. Whenever the parser fetches a new token from the
+scanner so that it can determine the next parser action, it immediately
+suspends normal parsing and performs an exploratory parse using a
+temporary copy of the normal parser state stack. During this
+exploratory parse, the parser does not perform user semantic actions.
+If the exploratory parse reaches a shift action, normal parsing then
+resumes on the normal parser stacks. If the exploratory parse reaches
+an error instead, the parser reports a syntax error. If verbose syntax
+error messages are enabled, the parser must then discover the list of
+expected tokens, so it performs a separate exploratory parse for each
+token in the grammar.
+
+There is one subtlety about the use of LAC. That is, when in
+a consistent parser state with a default reduction, the parser will not
+attempt to fetch a token from the scanner because no lookahead is needed
+to determine the next parser action. Thus, whether default reductions
+are enabled in consistent states (@pxref{Decl
+Summary,,lr.default-reductions}) affects how soon the parser detects a
+syntax error: when it @emph{reaches} an erroneous token or when it
+eventually @emph{needs} that token as a lookahead. The latter behavior
+is probably more intuitive, so Bison currently provides no way to
+achieve the former behavior while default reductions are fully enabled.
+
+Thus, when LAC is in use, for some fixed decision of whether
+to enable default reductions in consistent states, canonical
+LR and IELR behave exactly the same for both
+syntactically acceptable and syntactically unacceptable input. While
+LALR still does not support the full language-recognition
+power of canonical LR and IELR, LAC at
+least enables LALR's syntax error handling to correctly
+reflect LALR's language-recognition power.
+
+Because LAC requires many parse actions to be performed twice,
+it can have a performance penalty. However, not all parse actions must
+be performed twice. Specifically, during a series of default reductions
+in consistent states and shift actions, the parser never has to initiate
+an exploratory parse. Moreover, the most time-consuming tasks in a
+parse are often the file I/O, the lexical analysis performed by the
+scanner, and the user's semantic actions, but none of these are
+performed during the exploratory parse. Finally, the base of the
+temporary stack used during an exploratory parse is a pointer into the
+normal parser state stack so that the stack is never physically copied.
+In our experience, the performance penalty of LAC has proven
+insignificant for practical grammars.
+
+@item Accepted Values: @code{none}, @code{full}
+
+@item Default Value: @code{none}
+@end itemize
+@c parse.lac
+
+@c ================================================== parse.trace
+@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 implementation
+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
+@c parse.trace
+
+@c ================================================== variant
+@item variant
+@findex %define variant
+
+@itemize @bullet
+@item Language(s):
+C++
+
+@item Purpose:
+Request variant-based semantic values.
+@xref{C++ Variants}.
+
+@item Accepted Values:
+Boolean.
+
+@item Default Value:
+@code{false}
+@end itemize
+@c variant
+
+
+@end table
+@end deffn
+@c ---------------------------------------------------------- %define
+
+@deffn {Directive} %defines
+Write a parser header file containing macro definitions for the token
+type names defined in the grammar as well as a few other declarations.
+If the parser implementation file is named @file{@var{name}.c} then
+the parser header file is named @file{@var{name}.h}.
+
+For C parsers, the parser header file 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 parser header file declares
+@code{yylval} as an external variable. @xref{Pure Decl, ,A Pure
+(Reentrant) Parser}.
+
+If you have also used locations, the parser header file 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 parser header 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 grammar 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 @samp{%define api.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
+implementation file. Ordinarily Bison writes these commands in the
+parser implementation 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
+implementation file, treating it as an independent source file in its
+own right.
+@end deffn
+
+@deffn {Directive} %output "@var{file}"
+Specify @var{file} for the parser implementation file.
+@end deffn
+
+@deffn {Directive} %pure-parser
+Deprecated version of @samp{%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 implementation 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
projects / bison.git / blobdiff