Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-17 16:23:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: finish splitting apart the manual's Decl Summary section.

Browse Source 
Suggested by Akim Demaille at
<http://lists.gnu.org/archive/html/bison-patches/2009-05/msg00013.html>.
* doc/bison.texinfo (Decl Summary): Extract most of the %define
entry into...
(%define Summary): ... this new subsection, and update all
cross-references.  For readability of the patches, rewriting of
the text so it makes sense as a separate subsection will come in a
later patch.  Moreover, the majority of the text describing the
various new LR features should likely move to another new section
somewhere.
(cherry picked from commit 2f4518a126)

Conflicts:

	doc/bison.texinfo
This commit is contained in:
Joel E. Denny
2011-02-06 12:41:24 -05:00
parent e0c072223c
commit 35c1e5f0cd
2 changed files with 287 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
ChangeLog
View File

@@ -1,3 +1,17 @@
2011-02-06 Joel E. Denny <joeldenny@joeldenny.org>
doc: finish splitting apart the manual's Decl Summary section.
Suggested by Akim Demaille at
<http://lists.gnu.org/archive/html/bison-patches/2009-05/msg00013.html>.
* doc/bison.texinfo (Decl Summary): Extract most of the %define
entry into...
(%define Summary): ... this new subsection, and update all
cross-references. For readability of the patches, rewriting of
the text so it makes sense as a separate subsection will come in a
later patch. Moreover, the majority of the text describing the
various new LR features should likely move to another new section
somewhere.
2011-02-06 Joel E. Denny <joeldenny@joeldenny.org> 2011-02-06 Joel E. Denny <joeldenny@joeldenny.org>
doc: begin to split apart the manual's Decl Summary section. doc: begin to split apart the manual's Decl Summary section.

542
doc/bison.texinfo
View File

@@ -228,6 +228,7 @@ Bison Declarations
* Pure Decl:: Requesting a reentrant parser. * Pure Decl:: Requesting a reentrant parser.
* Push Decl:: Requesting a push parser. * Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations. * Decl Summary:: Table of all Bison declarations.
* %define Summary:: Defining variables to adjust Bison's behavior.
* %code Summary:: Inserting code into the parser source. * %code Summary:: Inserting code into the parser source.
Parser C-Language Interface Parser C-Language Interface
@@ -485,7 +486,7 @@ restrictions of LALR(1), which is hard to explain simply.
more information on this. more information on this.
As an experimental feature, you can escape these additional restrictions by As an experimental feature, you can escape these additional restrictions by
requesting IELR(1) or canonical LR(1) parser tables. 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 GLR parsing
@cindex generalized LR (GLR) parsing @cindex generalized LR (GLR) parsing
@@ -4199,6 +4200,7 @@ and Context-Free Grammars}).
* Pure Decl:: Requesting a reentrant parser. * Pure Decl:: Requesting a reentrant parser.
* Push Decl:: Requesting a push parser. * Push Decl:: Requesting a push parser.
* Decl Summary:: Table of all Bison declarations. * Decl Summary:: Table of all Bison declarations.
* %define Summary:: Defining variables to adjust Bison's behavior.
* %code Summary:: Inserting code into the parser source. * %code Summary:: Inserting code into the parser source.
@end menu @end menu
@@ -4789,7 +4791,7 @@ within a certain time period.
Normally, Bison generates a pull parser. Normally, Bison generates a pull parser.
The following Bison declaration says that you want the parser to be a push 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 @example
%define api.push-pull push %define api.push-pull push
@@ -4955,6 +4957,195 @@ parse.trace}.
@xref{Tracing, ,Tracing Your Parser}. @xref{Tracing, ,Tracing Your Parser}.
@end deffn @end deffn
@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} %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{%code Summary}.
@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{%define
Summary,,api.pure}), 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 %define Summary
@subsection %define Summary
@deffn {Directive} %define @var{variable} @deffn {Directive} %define @var{variable}
@deffnx {Directive} %define @var{variable} @var{value} @deffnx {Directive} %define @var{variable} @var{value}
@deffnx {Directive} %define @var{variable} "@var{value}" @deffnx {Directive} %define @var{variable} "@var{value}"
@@ -5170,21 +5361,19 @@ More user feedback will help to stabilize it.)
@item Accepted Values: @item Accepted Values:
@itemize @itemize
@item @code{all}. @item @code{all}.
This is the traditional Bison behavior. This is the traditional Bison behavior. The main advantage is a
The main advantage is a significant decrease in the size of the parser significant decrease in the size of the parser tables. The
tables. disadvantage is that, when the generated parser encounters a
The disadvantage is that, when the generated parser encounters a
syntactically unacceptable token, the parser might then perform syntactically unacceptable token, the parser might then perform
unnecessary default reductions before it can detect the syntax error. unnecessary default reductions before it can detect the syntax error.
Such delayed syntax error detection is usually inherent in Such delayed syntax error detection is usually inherent in LALR and
LALR and IELR parser tables anyway due to IELR parser tables anyway due to LR state merging (@pxref{%define
LR state merging (@pxref{Decl Summary,,lr.type}). Summary,,lr.type}). Furthermore, the use of @code{%nonassoc} can
Furthermore, the use of @code{%nonassoc} can contribute to delayed contribute to delayed syntax error detection even in the case of
syntax error detection even in the case of canonical LR. canonical LR. As an experimental feature, delayed syntax error
As an experimental feature, delayed syntax error detection can be detection can be overcome in all cases by enabling LAC (@pxref{%define
overcome in all cases by enabling LAC (@pxref{Decl Summary,,parse.lac}, for details, including a discussion of the
Summary,,parse.lac}, for details, including a discussion of the effects effects of delayed syntax error detection).
of delayed syntax error detection).
@item @code{consistent}. @item @code{consistent}.
@cindex consistent states @cindex consistent states
@@ -5332,21 +5521,20 @@ This can significantly reduce the complexity of developing of a grammar.
@cindex syntax errors delayed @cindex syntax errors delayed
@cindex LAC @cindex LAC
@findex %nonassoc @findex %nonassoc
While inefficient, canonical LR parser tables can be an While inefficient, canonical LR parser tables can be an interesting
interesting means to explore a grammar because they have a property that means to explore a grammar because they have a property that IELR and
IELR and LALR tables do not. LALR tables do not. That is, if @code{%nonassoc} is not used and
That is, if @code{%nonassoc} is not used and default reductions are left default reductions are left disabled (@pxref{%define
disabled (@pxref{Decl Summary,,lr.default-reductions}), then, for every Summary,,lr.default-reductions}), then, for every left context of
left context of every canonical LR state, the set of tokens every canonical LR state, the set of tokens accepted by that state is
accepted by that state is guaranteed to be the exact set of tokens that guaranteed to be the exact set of tokens that is syntactically
is syntactically acceptable in that left context. acceptable in that left context. It might then seem that an advantage
It might then seem that an advantage of canonical LR parsers of canonical LR parsers in production is that, under the above
in production is that, under the above constraints, they are guaranteed constraints, they are guaranteed to detect a syntax error as soon as
to detect a syntax error as soon as possible without performing any possible without performing any unnecessary reductions. However, IELR
unnecessary reductions. parsers using LAC (@pxref{%define Summary,,parse.lac}) are also able
However, IELR parsers using LAC (@pxref{Decl to achieve this behavior without sacrificing @code{%nonassoc} or
Summary,,parse.lac}) are also able to achieve this behavior without default reductions.
sacrificing @code{%nonassoc} or default reductions.
@end itemize @end itemize
@item Default Value: @code{lalr} @item Default Value: @code{lalr}
@@ -5450,16 +5638,17 @@ error messages are enabled, the parser must then discover the list of
expected tokens, so it performs a separate exploratory parse for each expected tokens, so it performs a separate exploratory parse for each
token in the grammar. token in the grammar.
There is one subtlety about the use of LAC. That is, when in There is one subtlety about the use of LAC. That is, when in a
a consistent parser state with a default reduction, the parser will not consistent parser state with a default reduction, the parser will not
attempt to fetch a token from the scanner because no lookahead is needed attempt to fetch a token from the scanner because no lookahead is
to determine the next parser action. Thus, whether default reductions needed to determine the next parser action. Thus, whether default
are enabled in consistent states (@pxref{Decl reductions are enabled in consistent states (@pxref{%define
Summary,,lr.default-reductions}) affects how soon the parser detects a Summary,,lr.default-reductions}) affects how soon the parser detects a
syntax error: when it @emph{reaches} an erroneous token or when it syntax error: when it @emph{reaches} an erroneous token or when it
eventually @emph{needs} that token as a lookahead. The latter behavior eventually @emph{needs} that token as a lookahead. The latter
is probably more intuitive, so Bison currently provides no way to behavior is probably more intuitive, so Bison currently provides no
achieve the former behavior while default reductions are fully enabled. way to achieve the former behavior while default reductions are fully
enabled.
Thus, when LAC is in use, for some fixed decision of whether Thus, when LAC is in use, for some fixed decision of whether
to enable default reductions in consistent states, canonical to enable default reductions in consistent states, canonical
@@ -5530,186 +5719,7 @@ Boolean.
@end table @end table
@end deffn @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{%code Summary}.
@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 %code Summary @node %code Summary
@subsection %code Summary @subsection %code Summary
@@ -7328,16 +7338,14 @@ the two contexts causes a conflict later. In parser terminology, this
occurrence means that the grammar is not LALR(1). occurrence means that the grammar is not LALR(1).
For many practical grammars (specifically those that fall into the For many practical grammars (specifically those that fall into the
non-LR(1) class), the limitations of LALR(1) result in non-LR(1) class), the limitations of LALR(1) result in difficulties
difficulties beyond just mysterious reduce/reduce conflicts. beyond just mysterious reduce/reduce conflicts. The best way to fix
The best way to fix all these problems is to select a different parser all these problems is to select a different parser table generation
table generation algorithm. algorithm. Either IELR(1) or canonical LR(1) would suffice, but the
Either IELR(1) or canonical LR(1) would suffice, but former is more efficient and easier to debug during development.
the former is more efficient and easier to debug during development. @xref{%define Summary,,lr.type}, for details. (Bison's IELR(1) and
@xref{Decl Summary,,lr.type}, for details. canonical LR(1) implementations are experimental. More user feedback
(Bison's IELR(1) and canonical LR(1) implementations will help to stabilize them.)
are experimental.
More user feedback will help to stabilize them.)
If you instead wish to work around LALR(1)'s limitations, you If you instead wish to work around LALR(1)'s limitations, you
can often fix a mysterious conflict by identifying the two parser states can often fix a mysterious conflict by identifying the two parser states
@@ -8311,12 +8319,11 @@ compatibility with previous versions of Bison.
@item the variable @samp{parse.trace} @item the variable @samp{parse.trace}
@findex %define parse.trace @findex %define parse.trace
Add the @samp{%define parse.trace} directive (@pxref{Decl Summary, Add the @samp{%define parse.trace} directive (@pxref{%define
,Bison Declaration Summary}), or pass the @option{-Dparse.trace} option Summary,,parse.trace}), or pass the @option{-Dparse.trace} option
(@pxref{Bison Options}). This is a Bison extension, which is especially (@pxref{Bison Options}). This is a Bison extension, which is especially
useful for languages that don't use a preprocessor. Unless useful for languages that don't use a preprocessor. Unless POSIX and Yacc
POSIX and Yacc portability matter to you, this is the portability matter to you, this is the preferred solution.
preferred solution.
@end table @end table
We suggest that you always enable the trace option so that debugging is We suggest that you always enable the trace option so that debugging is
@@ -8559,7 +8566,7 @@ compiled. @xref{Tracing, ,Tracing Your Parser}.
@itemx -F @var{name}[=@var{value}] @itemx -F @var{name}[=@var{value}]
@itemx --force-define=@var{name}[=@var{value}] @itemx --force-define=@var{name}[=@var{value}]
Each of these is equivalent to @samp{%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: definitions for the same @var{name} as follows:
@itemize @itemize
@@ -8777,10 +8784,9 @@ The C++ deterministic parser is selected using the skeleton directive,
When run, @command{bison} will create several entities in the @samp{yy} When run, @command{bison} will create several entities in the @samp{yy}
namespace. namespace.
@findex %define api.namespace @findex %define api.namespace
Use the @samp{%define api.namespace} directive to change the namespace Use the @samp{%define api.namespace} directive to change the namespace name,
name, see see @ref{%define Summary,,api.namespace}. The various classes are generated
@ref{Decl Summary}. in the following files:
The various classes are generated in the following files:
@table @file @table @file
@item position.hh @item position.hh
@@ -8853,7 +8859,7 @@ limitations reported in the previous section, and in particular, object
types can be used without pointers. types can be used without pointers.
To enable variant-based semantic values, set @code{%define} variable To enable variant-based semantic values, set @code{%define} variable
@code{variant} (@pxref{Decl Summary, , variant}). Once this defined, @code{variant} (@pxref{%define Summary,, variant}). Once this defined,
@code{%union} is ignored, and instead of using the name of the fields of the @code{%union} is ignored, and instead of using the name of the fields of the
@code{%union} to ``type'' the symbols, use genuine types. @code{%union} to ``type'' the symbols, use genuine types.
@@ -9507,9 +9513,9 @@ The code between @samp{%code @{} and @samp{@}} is output in the
@noindent @noindent
The token numbered as 0 corresponds to end of file; the following line The token numbered as 0 corresponds to end of file; the following line
allows for nicer error messages referring to ``end of file'' instead of allows for nicer error messages referring to ``end of file'' instead of
``$end''. Similarly user friendly names are provided for each symbol. ``$end''. Similarly user friendly names are provided for each symbol. To
To avoid name clashes in the generated files (@pxref{Calc++ Scanner}), avoid name clashes in the generated files (@pxref{Calc++ Scanner}), prefix
prefix tokens with @code{TOK_} (@pxref{Decl Summary,, api.tokens.prefix}). tokens with @code{TOK_} (@pxref{%define Summary,,api.tokens.prefix}).
@comment file: calc++-parser.yy @comment file: calc++-parser.yy
@example @example
@@ -10891,8 +10897,7 @@ Precedence}.
@deffn {Directive} %define @var{define-variable} @deffn {Directive} %define @var{define-variable}
@deffnx {Directive} %define @var{define-variable} @var{value} @deffnx {Directive} %define @var{define-variable} @var{value}
@deffnx {Directive} %define @var{define-variable} "@var{value}" @deffnx {Directive} %define @var{define-variable} "@var{value}"
Define a variable to adjust Bison's behavior. Define a variable to adjust Bison's behavior. @xref{%define Summary}.
@xref{Decl Summary,,%define}.
@end deffn @end deffn
@deffn {Directive} %defines @deffn {Directive} %defines
@@ -11022,8 +11027,9 @@ Bison declaration to assign precedence to token(s), but no associativity
@end deffn @end deffn
@deffn {Directive} %pure-parser @deffn {Directive} %pure-parser
Deprecated version of @samp{%define api.pure} (@pxref{Decl Summary, ,%define}), Deprecated version of @samp{%define api.pure} (@pxref{%define
for which Bison is more careful to warn about unreasonable usage. Summary,,api.pure}), for which Bison is more careful to warn about
unreasonable usage.
@end deffn @end deffn
@deffn {Directive} %require "@var{version}" @deffn {Directive} %require "@var{version}"
@@ -11297,8 +11303,8 @@ committee document contributing to what became the Algol 60 report.
@xref{Language and Grammar, ,Languages and Context-Free Grammars}. @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
@item Consistent State @item Consistent State
A state containing only one possible action. A state containing only one possible action. @xref{%define
@xref{Decl Summary,,lr.default-reductions}. Summary,,lr.default-reductions}.
@item Context-free grammars @item Context-free grammars
Grammars specified as rules that can be applied regardless of context. Grammars specified as rules that can be applied regardless of context.
@@ -11309,11 +11315,10 @@ Grammars}.
@item Default Reduction @item Default Reduction
The reduction that a parser should perform if the current parser state The reduction that a parser should perform if the current parser state
contains no other action for the lookahead token. contains no other action for the lookahead token. In permitted parser
In permitted parser states, Bison declares the reduction with the states, Bison declares the reduction with the largest lookahead set to
largest lookahead set to be the default reduction and removes that be the default reduction and removes that lookahead set.
lookahead set. @xref{%define Summary,,lr.default-reductions}.
@xref{Decl Summary,,lr.default-reductions}.
@item Dynamic allocation @item Dynamic allocation
Allocation of memory that occurs during execution, rather than at Allocation of memory that occurs during execution, rather than at
@@ -11346,18 +11351,16 @@ for example, `expression' or `declaration' in C@.
@xref{Language and Grammar, ,Languages and Context-Free Grammars}. @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
@item IELR(1) @item IELR(1)
A minimal LR(1) parser table generation algorithm. A minimal LR(1) parser table generation algorithm. That is, given any
That is, given any context-free grammar, IELR(1) generates context-free grammar, IELR(1) generates parser tables with the full
parser tables with the full language recognition power of canonical language recognition power of canonical LR(1) but with nearly the same
LR(1) but with nearly the same number of parser states as number of parser states as LALR(1). This reduction in parser states
LALR(1). is often an order of magnitude. More importantly, because canonical
This reduction in parser states is often an order of magnitude. LR(1)'s extra parser states may contain duplicate conflicts in the
More importantly, because canonical LR(1)'s extra parser case of non-LR(1) grammars, the number of conflicts for IELR(1) is
states may contain duplicate conflicts in the case of often an order of magnitude less as well. This can significantly
non-LR(1) grammars, the number of conflicts for reduce the complexity of developing of a grammar. @xref{%define
IELR(1) is often an order of magnitude less as well. Summary,,lr.type}.
This can significantly reduce the complexity of developing of a grammar.
@xref{Decl Summary,,lr.type}.
@item Infix operator @item Infix operator
An arithmetic operator that is placed between the operands on which it An arithmetic operator that is placed between the operands on which it
@@ -11368,11 +11371,12 @@ A continuous flow of data between devices or programs.
@item LAC (Lookahead Correction) @item LAC (Lookahead Correction)
A parsing mechanism that fixes the problem of delayed syntax error A parsing mechanism that fixes the problem of delayed syntax error
detection, which is caused by LR state merging, default reductions, and detection, which is caused by LR state merging, default reductions,
the use of @code{%nonassoc}. Delayed syntax error detection results in and the use of @code{%nonassoc}. Delayed syntax error detection
unexpected semantic actions, initiation of error recovery in the wrong results in unexpected semantic actions, initiation of error recovery
syntactic context, and an incorrect list of expected tokens in a verbose in the wrong syntactic context, and an incorrect list of expected
syntax error message. @xref{Decl Summary,,parse.lac}. tokens in a verbose syntax error message. @xref{%define
Summary,,parse.lac}.
@item Language construct @item Language construct
One of the typical usage schemas of the language. For example, one of One of the typical usage schemas of the language. For example, one of