* Table of Symbols:: All the keywords of the Bison language are explained.
* Glossary:: Basic concepts are explained.
* Copying This Manual:: License for copying this manual.
+* Bibliography:: Publications cited in this manual.
* Index:: Cross-references to the text.
@detailmenu
* Pure Decl:: Requesting a reentrant parser.
* Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations.
+* %define Summary:: Defining variables to adjust Bison's behavior.
+* %code Summary:: Inserting code into the parser source.
Parser C-Language Interface
more information on this.
As an experimental feature, you can escape these additional restrictions by
requesting IELR(1) or canonical LR(1) parser tables.
-@xref{Decl Summary,,lr.type}, to learn how.
+@xref{%define Summary,,lr.type}, to learn how.
@cindex GLR parsing
@cindex generalized LR (GLR) parsing
purpose of the code and thus the location(s) where Bison should
generate it. For C/C++, the qualifier can be omitted for the default
location, or it can be one of @code{requires}, @code{provides},
-@code{top}. @xref{Decl Summary,,%code}.
+@code{top}. @xref{%code Summary}.
Look again at the example of the previous section:
* Pure Decl:: Requesting a reentrant parser.
* Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations.
+* %define Summary:: Defining variables to adjust Bison's behavior.
+* %code Summary:: Inserting code into the parser source.
@end menu
@node Require Decl
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}):
+parser (@pxref{%define Summary,,api.push-pull}):
@example
%define api.push-pull push
directives:
@deffn {Directive} %code @{@var{code}@}
+@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
@findex %code
-This is the unqualified form of the @code{%code} directive.
-It inserts @var{code} verbatim at a language-dependent default location in the
-output@footnote{The default location is actually skeleton-dependent;
- writers of non-standard skeletons however should choose the default location
- consistently with the behavior of the standard Bison skeletons.}.
+Insert @var{code} verbatim into the output parser source at the
+default location or at the location specified by @var{qualifier}.
+@xref{%code Summary}.
+@end deffn
-@cindex Prologue
-For C/C++, the default location is the parser implementation file
-after the usual contents of the parser header file. Thus,
-@code{%code} replaces the traditional Yacc prologue,
-@code{%@{@var{code}%@}}, for most purposes. For a detailed
-discussion, see @ref{Prologue Alternatives}.
+@deffn {Directive} %debug
+In the parser implementation file, define the macro @code{YYDEBUG} to
+1 if it is not already defined, so that the debugging facilities are
+compiled. @xref{Tracing, ,Tracing Your Parser}.
+@end deffn
-For Java, the default location is inside the parser class.
+@deffn {Directive} %define @var{variable}
+@deffnx {Directive} %define @var{variable} @var{value}
+@deffnx {Directive} %define @var{variable} "@var{value}"
+Define a variable to adjust Bison's behavior. @xref{%define Summary}.
@end deffn
-@deffn {Directive} %code @var{qualifier} @{@var{code}@}
-This is the qualified form of the @code{%code} directive.
-If you need to specify location-sensitive verbatim @var{code} that does not
-belong at the default location selected by the unqualified @code{%code} form,
-use this form instead.
+@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}.
-@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
-where Bison should generate it.
-Not all @var{qualifier}s are accepted for all target languages.
-Unaccepted @var{qualifier}s produce an error.
-Some of the accepted @var{qualifier}s are:
+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}.
-@itemize @bullet
-@item requires
@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{%code Summary}.
+@end deffn
-@itemize @bullet
-@item Language(s): C, C++
+@deffn {Directive} %defines @var{defines-file}
+Same as above, but save in the file @var{defines-file}.
+@end deffn
-@item Purpose: This is the best place to write dependency code required for
-@code{YYSTYPE} and @code{YYLTYPE}.
-In other words, it's the best place to define types referenced in @code{%union}
-directives, and it's the best place to override Bison's default @code{YYSTYPE}
-and @code{YYLTYPE} definitions.
+@deffn {Directive} %destructor
+Specify how the parser should reclaim the memory associated to
+discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
+@end deffn
-@item Location(s): The parser header file and the parser implementation file
-before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
-definitions.
-@end itemize
+@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
-@item provides
-@findex %code provides
+@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.
-@itemize @bullet
-@item Language(s): C, C++
+This directive is experimental and its effect may be modified in future
+releases.
+@end deffn
-@item Purpose: This is the best place to write additional definitions and
-declarations that should be provided to other modules.
+@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
-@item Location(s): The parser header file and the parser implementation
-file after the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and
-token definitions.
-@end itemize
+@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
-@item top
-@findex %code top
+@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
-@itemize @bullet
-@item Language(s): C, C++
+@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
-@item Purpose: The unqualified @code{%code} or @code{%code requires}
-should usually be more appropriate than @code{%code top}. However,
-occasionally it is necessary to insert code much nearer the top of the
-parser implementation file. For example:
+@deffn {Directive} %output "@var{file}"
+Specify @var{file} for the parser implementation file.
+@end deffn
-@smallexample
-%code top @{
- #define _GNU_SOURCE
- #include <stdio.h>
-@}
-@end smallexample
+@deffn {Directive} %pure-parser
+Deprecated version of @code{%define api.pure} (@pxref{%define
+Summary,,api.pure}), for which Bison is more careful to warn about
+unreasonable usage.
+@end deffn
-@item Location(s): Near the top of the parser implementation file.
-@end itemize
+@deffn {Directive} %require "@var{version}"
+Require version @var{version} or higher of Bison. @xref{Require Decl, ,
+Require a Version of Bison}.
+@end deffn
-@item imports
-@findex %code imports
+@deffn {Directive} %skeleton "@var{file}"
+Specify the skeleton to use.
-@itemize @bullet
-@item Language(s): Java
+@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.
-@item Purpose: This is the best place to write Java import directives.
+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
-@item Location(s): The parser Java file after any Java package directive and
-before any class definitions.
-@end itemize
-@end itemize
+@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.
-@cindex Prologue
-For a detailed discussion of how to use @code{%code} in place of the
-traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
+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} %debug
-In the parser implementation file, define the macro @code{YYDEBUG} to
-1 if it is not already defined, so that the debugging facilities are
-compiled. @xref{Tracing, ,Tracing Your Parser}.
+@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 %define Summary
+@subsection %define Summary
+
+There are many features of Bison's behavior that can be controlled by
+assigning the feature a single value. For historical reasons, some
+such features are assigned values by dedicated directives, such as
+@code{%start}, which assigns the start symbol. However, newer such
+features are associated with variables, which are assigned by the
+@code{%define} directive:
+
@deffn {Directive} %define @var{variable}
@deffnx {Directive} %define @var{variable} @var{value}
@deffnx {Directive} %define @var{variable} "@var{value}"
-Define a variable to adjust Bison's behavior.
+Define @var{variable} to @var{value}.
-It is an error if a @var{variable} is defined by @code{%define} multiple
-times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}.
+@var{value} must be placed in quotation marks if it contains any
+character other than a letter, underscore, period, or non-initial dash
+or digit. Omitting @code{"@var{value}"} entirely is always equivalent
+to specifying @code{""}.
-@var{value} must be placed in quotation marks if it contains any character
-other than a letter, underscore, period, or non-initial dash or digit.
+It is an error if a @var{variable} is defined by @code{%define}
+multiple times, but see @ref{Bison Options,,-D
+@var{name}[=@var{value}]}.
+@end deffn
-Omitting @code{"@var{value}"} entirely is always equivalent to specifying
-@code{""}.
+The rest of this section summarizes variables and values that
+@code{%define} accepts.
-Some @var{variable}s take Boolean values.
-In this case, Bison will complain if the variable definition does not meet one
-of the following four conditions:
+Some @var{variable}s take Boolean values. 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 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
+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).
+Such delayed syntax error detection is usually inherent in LALR and
+IELR parser tables anyway due to LR state merging (@pxref{%define
+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{%define
+Summary,,parse.lac}, for details, including a discussion of the
+effects of delayed syntax error detection).
@item @code{consistent}.
@cindex consistent states
@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.
+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{%define
+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{%define Summary,,parse.lac}) are also able
+to achieve this behavior without sacrificing @code{%nonassoc} or
+default reductions.
@end itemize
@item Default Value: @code{lalr}
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
+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{%define
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.
+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
@end itemize
@end itemize
-@end deffn
-
-@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}.
+@node %code Summary
+@subsection %code Summary
+@findex %code
+@cindex Prologue
-Unless your parser is pure, the parser header file declares
-@code{yylval} as an external variable. @xref{Pure Decl, ,A Pure
-(Reentrant) Parser}.
+The @code{%code} directive inserts code verbatim into the output
+parser source at any of a predefined set of locations. It thus serves
+as a flexible and user-friendly alternative to the traditional Yacc
+prologue, @code{%@{@var{code}%@}}. This section summarizes the
+functionality of @code{%code} for the various target languages
+supported by Bison. For a detailed discussion of how to use
+@code{%code} in place of @code{%@{@var{code}%@}} for C/C++ and why it
+is advantageous to do so, @pxref{Prologue Alternatives}.
-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}.
+@deffn {Directive} %code @{@var{code}@}
+This is the unqualified form of the @code{%code} directive. It
+inserts @var{code} verbatim at a language-dependent default location
+in the parser implementation.
-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}.
+For C/C++, the default location is the parser implementation file
+after the usual contents of the parser header file. Thus, the
+unqualified form replaces @code{%@{@var{code}%@}} for most purposes.
-@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}.
+For Java, the default location is inside the parser class.
@end deffn
-@deffn {Directive} %defines @var{defines-file}
-Same as above, but save in the file @var{defines-file}.
+@deffn {Directive} %code @var{qualifier} @{@var{code}@}
+This is the qualified form of the @code{%code} directive.
+@var{qualifier} identifies the purpose of @var{code} and thus the
+location(s) where Bison should insert it. That is, if you need to
+specify location-sensitive @var{code} that does not belong at the
+default location selected by the unqualified @code{%code} form, use
+this form instead.
@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
+For any particular qualifier or for the unqualified form, if there are
+multiple occurrences of the @code{%code} directive, Bison concatenates
+the specified code in the order in which it appears in the grammar
+file.
-@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
+Not all qualifiers are accepted for all target languages. Unaccepted
+qualifiers produce an error. Some of the accepted qualifiers are:
-@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.
+@itemize @bullet
+@item requires
+@findex %code requires
-This directive is experimental and its effect may be modified in future
-releases.
-@end deffn
+@itemize @bullet
+@item Language(s): C, C++
-@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
+@item Purpose: This is the best place to write dependency code required for
+@code{YYSTYPE} and @code{YYLTYPE}.
+In other words, it's the best place to define types referenced in @code{%union}
+directives, and it's the best place to override Bison's default @code{YYSTYPE}
+and @code{YYLTYPE} definitions.
-@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
+@item Location(s): The parser header file and the parser implementation file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
+definitions.
+@end itemize
-@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
+@item provides
+@findex %code provides
-@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
+@itemize @bullet
+@item Language(s): C, C++
-@deffn {Directive} %output "@var{file}"
-Specify @var{file} for the parser implementation file.
-@end deffn
+@item Purpose: This is the best place to write additional definitions and
+declarations that should be provided to other modules.
-@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
+@item Location(s): The parser header file and the parser implementation
+file after the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and
+token definitions.
+@end itemize
-@deffn {Directive} %require "@var{version}"
-Require version @var{version} or higher of Bison. @xref{Require Decl, ,
-Require a Version of Bison}.
-@end deffn
+@item top
+@findex %code top
-@deffn {Directive} %skeleton "@var{file}"
-Specify the skeleton to use.
+@itemize @bullet
+@item Language(s): C, C++
-@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.
+@item Purpose: The unqualified @code{%code} or @code{%code requires}
+should usually be more appropriate than @code{%code top}. However,
+occasionally it is necessary to insert code much nearer the top of the
+parser implementation file. For example:
-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
+@smallexample
+%code top @{
+ #define _GNU_SOURCE
+ #include <stdio.h>
+@}
+@end smallexample
-@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.
+@item Location(s): Near the top of the parser implementation file.
+@end itemize
-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{"\"\\\\/\""}.
+@item imports
+@findex %code imports
-When you specify @code{%token-table}, Bison also generates macro
-definitions for macros @code{YYNTOKENS}, @code{YYNNTS}, and
-@code{YYNRULES}, and @code{YYNSTATES}:
+@itemize @bullet
+@item Language(s): Java
-@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
+@item Purpose: This is the best place to write Java import directives.
-@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
+@item Location(s): The parser Java file after any Java package directive and
+before any class definitions.
+@end itemize
+@end itemize
-@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
+Though we say the insertion locations are language-dependent, they are
+technically skeleton-dependent. Writers of non-standard skeletons
+however should choose their locations consistently with the behavior
+of the standard Bison skeletons.
@node Multiple Parsers
occurrence means that the grammar is not LALR(1).
For many practical grammars (specifically those that fall into the
-non-LR(1) class), the limitations of LALR(1) result in
-difficulties beyond just mysterious reduce/reduce conflicts.
-The best way to fix all these problems is to select a different parser
-table generation algorithm.
-Either IELR(1) or canonical LR(1) would suffice, but
-the former is more efficient and easier to debug during development.
-@xref{Decl Summary,,lr.type}, for details.
-(Bison's IELR(1) and canonical LR(1) implementations
-are experimental.
-More user feedback will help to stabilize them.)
+non-LR(1) class), the limitations of LALR(1) result in difficulties
+beyond just mysterious reduce/reduce conflicts. The best way to fix
+all these problems is to select a different parser table generation
+algorithm. Either IELR(1) or canonical LR(1) would suffice, but the
+former is more efficient and easier to debug during development.
+@xref{%define Summary,,lr.type}, for details. (Bison's IELR(1) and
+canonical LR(1) implementations are experimental. More user feedback
+will help to stabilize them.)
If you instead wish to work around LALR(1)'s limitations, you
can often fix a mysterious conflict by identifying the two parser states
@end example
For a more detailed exposition of LALR(1) parsers and parser
-generators, please see:
-Frank DeRemer and Thomas Pennello, Efficient Computation of
-LALR(1) Look-Ahead Sets, @cite{ACM Transactions on
-Programming Languages and Systems}, Vol.@: 4, No.@: 4 (October 1982),
-pp.@: 615--649 @uref{http://doi.acm.org/10.1145/69622.357187}.
+generators, @pxref{Bibliography,,DeRemer 1982}.
@node Generalized LR Parsing
@section Generalized LR (GLR) Parsing
grammar, in particular, it is only slightly slower than with the
deterministic LR(1) Bison parser.
-For a more detailed exposition of GLR parsers, please see: Elizabeth
-Scott, Adrian Johnstone and Shamsa Sadaf Hussain, Tomita-Style
-Generalised LR Parsers, Royal Holloway, University of
-London, Department of Computer Science, TR-00-12,
-@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps},
-(2000-12-24).
+For a more detailed exposition of GLR parsers, @pxref{Bibliography,,Scott
+2000}.
@node Memory Management
@section Memory Management, and How to Avoid Memory Exhaustion
@itemx -F @var{name}[=@var{value}]
@itemx --force-define=@var{name}[=@var{value}]
Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
-(@pxref{Decl Summary, ,%define}) except that Bison processes multiple
+(@pxref{%define Summary}) except that Bison processes multiple
definitions for the same @var{name} as follows:
@itemize
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:
+Use the @samp{%define namespace} directive to change the namespace
+name, see @ref{%define Summary,,namespace}. The various classes are
+generated in the following files:
@table @file
@item position.hh
driver's header needs detailed knowledge about the parser class (in
particular its inner types), it is the parser's header which will simply
use a forward declaration of the driver.
-@xref{Decl Summary, ,%code}.
+@xref{%code Summary}.
@comment file: calc++-parser.yy
@example
@deffn {Directive} %code @{@var{code}@}
@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
-Insert @var{code} verbatim into output parser source.
-@xref{Decl Summary,,%code}.
+Insert @var{code} verbatim into the output parser source at the
+default location or at the location specified by @var{qualifier}.
+@xref{%code Summary}.
@end deffn
@deffn {Directive} %debug
@deffn {Directive} %define @var{define-variable}
@deffnx {Directive} %define @var{define-variable} @var{value}
@deffnx {Directive} %define @var{define-variable} "@var{value}"
-Define a variable to adjust Bison's behavior.
-@xref{Decl Summary,,%define}.
+Define a variable to adjust Bison's behavior. @xref{%define Summary}.
@end deffn
@deffn {Directive} %defines
@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.
+Deprecated version of @code{%define api.pure} (@pxref{%define
+Summary,,api.pure}), for which Bison is more careful to warn about
+unreasonable usage.
@end deffn
@deffn {Directive} %require "@var{version}"
@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
@item Consistent State
-A state containing only one possible action.
-@xref{Decl Summary,,lr.default-reductions}.
+A state containing only one possible action. @xref{%define
+Summary,,lr.default-reductions}.
@item Context-free grammars
Grammars specified as rules that can be applied regardless of context.
@item Default Reduction
The reduction that a parser should perform if the current parser state
-contains no other action for the lookahead token.
-In permitted parser states, Bison declares the reduction with the
-largest lookahead set to be the default reduction and removes that
-lookahead set.
-@xref{Decl Summary,,lr.default-reductions}.
+contains no other action for the lookahead token. In permitted parser
+states, Bison declares the reduction with the largest lookahead set to
+be the default reduction and removes that lookahead set.
+@xref{%define Summary,,lr.default-reductions}.
@item Dynamic allocation
Allocation of memory that occurs during execution, rather than at
@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
@item IELR(1)
-A minimal LR(1) parser table generation algorithm.
-That is, given any context-free grammar, IELR(1) generates
-parser tables with the full language recognition power of canonical
-LR(1) but with nearly the same number of parser states as
-LALR(1).
-This reduction in parser states is often an order of magnitude.
-More importantly, because canonical LR(1)'s extra parser
-states may contain duplicate conflicts in the case of
-non-LR(1) grammars, the number of conflicts for
-IELR(1) is often an order of magnitude less as well.
-This can significantly reduce the complexity of developing of a grammar.
-@xref{Decl Summary,,lr.type}.
+A minimal LR(1) parser table generation algorithm. That is, given any
+context-free grammar, IELR(1) generates parser tables with the full
+language recognition power of canonical LR(1) but with nearly the same
+number of parser states as LALR(1). This reduction in parser states
+is often an order of magnitude. More importantly, because canonical
+LR(1)'s extra parser states may contain duplicate conflicts in the
+case of non-LR(1) grammars, the number of conflicts for IELR(1) is
+often an order of magnitude less as well. This can significantly
+reduce the complexity of developing of a grammar. @xref{%define
+Summary,,lr.type}.
@item Infix operator
An arithmetic operator that is placed between the operands on which it
@item LAC (Lookahead Correction)
A parsing mechanism that fixes the problem of delayed syntax error
-detection, which is caused by LR state merging, default reductions, and
-the use of @code{%nonassoc}. Delayed syntax error detection results in
-unexpected semantic actions, initiation of error recovery in the wrong
-syntactic context, and an incorrect list of expected tokens in a verbose
-syntax error message. @xref{Decl Summary,,parse.lac}.
+detection, which is caused by LR state merging, default reductions,
+and the use of @code{%nonassoc}. Delayed syntax error detection
+results in unexpected semantic actions, initiation of error recovery
+in the wrong syntactic context, and an incorrect list of expected
+tokens in a verbose syntax error message. @xref{%define
+Summary,,parse.lac}.
@item Language construct
One of the typical usage schemas of the language. For example, one of
@appendix Copying This Manual
@include fdl.texi
+@node Bibliography
+@unnumbered Bibliography
+
+@table @asis
+@item [Denny 2008]
+Joel E. Denny and Brian A. Malloy, IELR(1): Practical LR(1) Parser Tables
+for Non-LR(1) Grammars with Conflict Resolution, in @cite{Proceedings of the
+2008 ACM Symposium on Applied Computing} (SAC'08), ACM, New York, NY, USA,
+pp.@: 240--245. @uref{http://dx.doi.org/10.1145/1363686.1363747}
+
+@item [Denny 2010 May]
+Joel E. Denny, PSLR(1): Pseudo-Scannerless Minimal LR(1) for the
+Deterministic Parsing of Composite Languages, Ph.D. Dissertation, Clemson
+University, Clemson, SC, USA (May 2010).
+@uref{http://proquest.umi.com/pqdlink?did=2041473591&Fmt=7&clientId=79356&RQT=309&VName=PQD}
+
+@item [Denny 2010 November]
+Joel E. Denny and Brian A. Malloy, The IELR(1) Algorithm for Generating
+Minimal LR(1) Parser Tables for Non-LR(1) Grammars with Conflict Resolution,
+in @cite{Science of Computer Programming}, Vol.@: 75, Issue 11 (November
+2010), pp.@: 943--979. @uref{http://dx.doi.org/10.1016/j.scico.2009.08.001}
+
+@item [DeRemer 1982]
+Frank DeRemer and Thomas Pennello, Efficient Computation of LALR(1)
+Look-Ahead Sets, in @cite{ACM Transactions on Programming Languages and
+Systems}, Vol.@: 4, No.@: 4 (October 1982), pp.@:
+615--649. @uref{http://dx.doi.org/10.1145/69622.357187}
+
+@item [Knuth 1965]
+Donald E. Knuth, On the Translation of Languages from Left to Right, in
+@cite{Information and Control}, Vol.@: 8, Issue 6 (December 1965), pp.@:
+607--639. @uref{http://dx.doi.org/10.1016/S0019-9958(65)90426-2}
+
+@item [Scott 2000]
+Elizabeth Scott, Adrian Johnstone, and Shamsa Sadaf Hussain,
+@cite{Tomita-Style Generalised LR Parsers}, Royal Holloway, University of
+London, Department of Computer Science, TR-00-12 (December 2000).
+@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps}
+@end table
+
@node Index
@unnumbered Index
@bye
-@c Local Variables:
-@c fill-column: 76
-@c End:
-
@c LocalWords: texinfo setfilename settitle setchapternewpage finalout texi FSF
@c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex FSF's
@c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry Naur
@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
@c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett
@c LocalWords: subdirectory Solaris nonassociativity
+
+@c Local Variables:
+@c ispell-dictionary: "american"
+@c fill-column: 76
+@c End:
projects / bison.git / blobdiff