messy for Bison to handle straightforwardly.
* Debugging:: Understanding or debugging Bison parsers.
* Invocation:: How to run Bison (to produce the parser source file).
+* C++ Language Interface:: Creating C++ parser objects.
+* FAQ:: Frequently Asked Questions
* Table of Symbols:: All the keywords of the Bison language are explained.
* Glossary:: Basic concepts are explained.
-* FAQ:: Frequently Asked Questions
* Copying This Manual:: License for copying this manual.
* Index:: Cross-references to the text.
Writing @acronym{GLR} Parsers
-* Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars
-* Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities
-* Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler
+* Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars
+* Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities
+* Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler
Examples
Bison Declarations
+* Require Decl:: Requiring a Bison version.
* Token Decl:: Declaring terminal symbols.
* Precedence Decl:: Declaring terminals with precedence and associativity.
* Union Decl:: Declaring the set of all semantic value types.
which reads tokens.
* Error Reporting:: You must supply a function @code{yyerror}.
* Action Features:: Special features for use in actions.
+* Internationalization:: How to let the parser speak in the user's
+ native language.
The Lexical Analyzer Function @code{yylex}
* Reduce/Reduce:: When two rules are applicable in the same situation.
* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
* Generalized LR Parsing:: Parsing arbitrary context-free grammars.
-* Stack Overflow:: What happens when stack gets full. How to avoid it.
+* Memory Management:: What happens when memory is exhausted. How to avoid it.
Operator Precedence
* Option Cross Key:: Alphabetical list of long options.
* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
+C++ Language Interface
+
+* C++ Parsers:: The interface to generate C++ parser classes
+* A Complete C++ Example:: Demonstrating their use
+
+C++ Parsers
+
+* C++ Bison Interface:: Asking for C++ parser generation
+* C++ Semantic Values:: %union vs. C++
+* C++ Location Values:: The position and location classes
+* C++ Parser Interface:: Instantiating and running the parser
+* C++ Scanner Interface:: Exchanges between yylex and parse
+
+A Complete C++ Example
+
+* Calc++ --- C++ Calculator:: The specifications
+* Calc++ Parsing Driver:: An active parsing context
+* Calc++ Parser:: A parser class
+* Calc++ Scanner:: A pure C++ Flex scanner
+* Calc++ Top Level:: Conducting the band
+
Frequently Asked Questions
-* Parser Stack Overflow:: Breaking the Stack Limits
+* Memory Exhausted:: Breaking the Stack Limits
* How Can I Reset the Parser:: @code{yyparse} Keeps some State
* Strings are Destroyed:: @code{yylval} Loses Track of Strings
-* C++ Parsers:: Compiling Parsers with C++ Compilers
* Implementing Gotos/Loops:: Control Flow in the Calculator
Copying This Manual
@cindex @acronym{GLR} parsing
@cindex generalized @acronym{LR} (@acronym{GLR}) parsing
@cindex ambiguous grammars
-@cindex non-deterministic parsing
+@cindex nondeterministic parsing
Parsers for @acronym{LALR}(1) grammars are @dfn{deterministic}, meaning
roughly that the next grammar rule to apply at any point in the input is
(called a @dfn{look-ahead}) of the remaining input. A context-free
grammar can be @dfn{ambiguous}, meaning that there are multiple ways to
apply the grammar rules to get the same inputs. Even unambiguous
-grammars can be @dfn{non-deterministic}, meaning that no fixed
+grammars can be @dfn{nondeterministic}, meaning that no fixed
look-ahead always suffices to determine the next grammar rule to apply.
With the proper declarations, Bison is also able to parse these more
general context-free grammars, using a technique known as @acronym{GLR}
merged result.
@menu
-* Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars
-* Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities
-* Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler
+* Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars
+* Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities
+* Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler
@end menu
@node Simple GLR Parsers
arrange for it to call @code{yyparse} or the parser will never run.
@xref{Interface, ,Parser C-Language Interface}.
-If your code defines a C preprocessor macro @code{_} (a single
-underscore), Bison assumes that it can be used to translate
-English-language strings to the user's preferred language using a
-function-like syntax, e.g., @code{_("syntax error")}. Otherwise,
-Bison defines a no-op macro by that name that merely returns its
-argument, so strings are not translated.
-
-Aside from @code{_} and the token type names and the symbols in the actions you
+Aside from the token type names and the symbols in the actions you
write, all symbols defined in the Bison parser file itself
begin with @samp{yy} or @samp{YY}. This includes interface functions
such as the lexical analyzer function @code{yylex}, the error reporting
This also includes numerous identifiers used for internal purposes.
Therefore, you should avoid using C identifiers starting with @samp{yy}
or @samp{YY} in the Bison grammar file except for the ones defined in
-this manual.
+this manual. Also, you should avoid using the C identifiers
+@samp{malloc} and @samp{free} for anything other than their usual
+meanings.
In some cases the Bison parser file includes system headers, and in
those cases your code should respect the identifiers reserved by those
-headers. On some non-@acronym{GNU} hosts, @code{<alloca.h>},
+headers. On some non-@acronym{GNU} hosts, @code{<alloca.h>}, @code{<malloc.h>},
@code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
-declare memory allocators and related types. Other system headers may
+declare memory allocators and related types. @code{<libintl.h>} is
+included if message translation is in use
+(@pxref{Internationalization}). Other system headers may
be included if you define @code{YYDEBUG} to a nonzero value
(@pxref{Tracing, ,Tracing Your Parser}).
convert it into a parser file:
@example
-bison @var{file_name}.y
+bison @var{file}.y
@end example
@noindent
In this example the file was called @file{rpcalc.y} (for ``Reverse Polish
-@sc{calc}ulator''). Bison produces a file named @file{@var{file_name}.tab.c},
+@sc{calc}ulator''). Bison produces a file named @file{@var{file}.tab.c},
removing the @samp{.y} from the original file name. The file output by
Bison contains the source code for @code{yyparse}. The additional
functions in the input file (@code{yylex}, @code{yyerror} and @code{main})
It is easy to add new operators to the infix calculator as long as they are
only single-character literals. The lexical analyzer @code{yylex} passes
-back all nonnumber characters as tokens, so new grammar rules suffice for
+back all nonnumeric characters as tokens, so new grammar rules suffice for
adding a new operator. But we want something more flexible: built-in
functions whose syntax has this form:
The function @code{yylex} must now recognize variables, numeric values, and
the single-character arithmetic operators. Strings of alphanumeric
-characters with a leading non-digit are recognized as either variables or
+characters with a leading letter are recognized as either variables or
functions depending on what the symbol table says about them.
The string is passed to @code{getsym} for look up in the symbol table. If
in the other source files that need it. @xref{Invocation, ,Invoking Bison}.
If you want to write a grammar that is portable to any Standard C
-host, you must use only non-null character tokens taken from the basic
+host, you must use only nonnull character tokens taken from the basic
execution character set of Standard C@. This set consists of the ten
digits, the 52 lower- and upper-case English letters, and the
characters in the following C-language string:
Grammars}).
@menu
+* Require Decl:: Requiring a Bison version.
* Token Decl:: Declaring terminal symbols.
* Precedence Decl:: Declaring terminals with precedence and associativity.
* Union Decl:: Declaring the set of all semantic value types.
* Decl Summary:: Table of all Bison declarations.
@end menu
+@node Require Decl
+@subsection Require a Version of Bison
+@cindex version requirement
+@cindex requiring a version of Bison
+@findex %require
+
+You may require the minimum version of Bison to process the grammar. If
+the requirement is not met, @command{bison} exits with an error (exit
+status 63).
+
+@example
+%require "@var{version}"
+@end example
+
@node Token Decl
@subsection Token Type Names
@cindex declaring token type names
For instance, if your locations use a file name, you may use
@example
-%parse-param @{ const char *filename @};
+%parse-param @{ char const *file_name @};
%initial-action
@{
- @@$.begin.filename = @@$.end.filename = filename;
+ @@$.initialize (file_name);
@};
@end example
@cindex freeing discarded symbols
@findex %destructor
-Some symbols can be discarded by the parser. For instance, during error
-recovery (@pxref{Error Recovery}), embarrassing symbols already pushed
-on the stack, and embarrassing tokens coming from the rest of the file
-are thrown away until the parser falls on its feet. If these symbols
-convey heap based information, this memory is lost. While this behavior
-can be tolerable for batch parsers, such as in compilers, it is not for
-possibly ``never ending'' parsers such as shells, or implementations of
-communication protocols.
+During error recovery (@pxref{Error Recovery}), symbols already pushed
+on the stack and tokens coming from the rest of the file are discarded
+until the parser falls on its feet. If the parser runs out of memory,
+or if it returns via @code{YYABORT} or @code{YYACCEPT}, all the
+symbols on the stack must be discarded. Even if the parser succeeds, it
+must discard the start symbol.
-The @code{%destructor} directive allows for the definition of code that
-is called when a symbol is thrown away.
+When discarded symbols convey heap based information, this memory is
+lost. While this behavior can be tolerable for batch parsers, such as
+in traditional compilers, it is unacceptable for programs like shells or
+protocol implementations that may parse and execute indefinitely.
+
+The @code{%destructor} directive defines code that is called when a
+symbol is automatically discarded.
@deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
@findex %destructor
-Declare that the @var{code} must be invoked for each of the
-@var{symbols} that will be discarded by the parser. The @var{code}
-should use @code{$$} to designate the semantic value associated to the
-@var{symbols}. The additional parser parameters are also available
-(@pxref{Parser Function, , The Parser Function @code{yyparse}}).
-
-@strong{Warning:} as of Bison 1.875, this feature is still considered as
-experimental, as there was not enough user feedback. In particular,
-the syntax might still change.
+Invoke @var{code} whenever the parser discards one of the @var{symbols}.
+Within @var{code}, @code{$$} designates the semantic value associated
+with the discarded symbol. The additional parser parameters are also
+available (@pxref{Parser Function, , The Parser Function
+@code{yyparse}}).
@end deffn
For instance:
@end smallexample
@noindent
-guarantees that when a @code{STRING} or a @code{string} will be discarded,
+guarantees that when a @code{STRING} or a @code{string} is discarded,
its associated memory will be freed.
-Note that in the future, Bison might also consider that right hand side
-members that are not mentioned in the action can be destroyed. For
-instance, in:
-
-@smallexample
-comment: "/*" STRING "*/";
-@end smallexample
-
-@noindent
-the parser is entitled to destroy the semantic value of the
-@code{string}. Of course, this will not apply to the default action;
-compare:
-
-@smallexample
-typeless: string; // $$ = $1 does not apply; $1 is destroyed.
-typefull: string; // $$ = $1 applies, $1 is not destroyed.
-@end smallexample
-
@sp 1
@cindex discarded symbols
@item
incoming terminals during the second phase of error recovery,
@item
-the current look-ahead when the parser aborts (either via an explicit
-call to @code{YYABORT}, or as a consequence of a failed error recovery).
+the current look-ahead and the entire stack (except the current
+right-hand side symbols) when the parser returns immediately, and
+@item
+the start symbol, when the parser succeeds.
@end itemize
+The parser can @dfn{return immediately} because of an explicit call to
+@code{YYABORT} or @code{YYACCEPT}, or failed error recovery, or memory
+exhaustion.
+
+Right-hand size symbols of a rule that explicitly triggers a syntax
+error via @code{YYERROR} are not discarded automatically. As a rule
+of thumb, destructors are invoked only when user actions cannot manage
+the memory.
@node Expect Decl
@subsection Suppressing Conflict Warnings
%expect @var{n}
@end example
-Here @var{n} is a decimal integer. The declaration says there should be
-no warning if there are @var{n} shift/reduce conflicts and no
-reduce/reduce conflicts. The usual warning is
-given if there are either more or fewer conflicts, or if there are any
-reduce/reduce conflicts.
+Here @var{n} is a decimal integer. The declaration says there should
+be @var{n} shift/reduce conflicts and no reduce/reduce conflicts.
+Bison reports an error if the number of shift/reduce conflicts differs
+from @var{n}, or if there are any reduce/reduce conflicts.
-For normal @acronym{LALR}(1) parsers, reduce/reduce conflicts are more serious,
-and should be eliminated entirely. Bison will always report
-reduce/reduce conflicts for these parsers. With @acronym{GLR} parsers, however,
-both shift/reduce and reduce/reduce are routine (otherwise, there
-would be no need to use @acronym{GLR} parsing). Therefore, it is also possible
-to specify an expected number of reduce/reduce conflicts in @acronym{GLR}
-parsers, using the declaration:
+For normal @acronym{LALR}(1) parsers, reduce/reduce conflicts are more
+serious, and should be eliminated entirely. Bison will always report
+reduce/reduce conflicts for these parsers. With @acronym{GLR}
+parsers, however, both kinds of conflicts are routine; otherwise,
+there would be no need to use @acronym{GLR} parsing. Therefore, it is
+also possible to specify an expected number of reduce/reduce conflicts
+in @acronym{GLR} parsers, using the declaration:
@example
%expect-rr @var{n}
@item
Add an @code{%expect} declaration, copying the number @var{n} from the
-number which Bison printed.
+number which Bison printed. With @acronym{GLR} parsers, add an
+@code{%expect-rr} declaration as well.
@end itemize
-Now Bison will stop annoying you if you do not change the number of
-conflicts, but it will warn you again if changes in the grammar result
-in more or fewer conflicts.
+Now Bison will warn you if you introduce an unexpected conflict, but
+will keep silent otherwise.
@node Start Decl
@subsection The Start-Symbol
A @dfn{reentrant} program is one which does not alter in the course of
execution; in other words, it consists entirely of @dfn{pure} (read-only)
code. Reentrancy is important whenever asynchronous execution is possible;
-for example, a non-reentrant program may not be safe to call from a signal
-handler. In systems with multiple threads of control, a non-reentrant
+for example, a nonreentrant program may not be safe to call from a signal
+handler. In systems with multiple threads of control, a nonreentrant
program must be called only within interlocks.
Normally, Bison generates a parser which is not reentrant. This is
@end deffn
@deffn {Directive} %destructor
-Specifying how the parser should reclaim the memory associated to
+Specify how the parser should reclaim the memory associated to
discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
@end deffn
declarations.
This option also tells Bison to write the C code for the grammar actions
-into a file named @file{@var{filename}.act}, in the form of a
+into a file named @file{@var{file}.act}, in the form of a
brace-surrounded body fit for a @code{switch} statement.
@end deffn
file in its own right.
@end deffn
-@deffn {Directive} %output="@var{filename}"
-Specify the @var{filename} for the parser file.
+@deffn {Directive} %output="@var{file}"
+Specify @var{file} for the parser file.
@end deffn
@deffn {Directive} %pure-parser
(Reentrant) Parser}).
@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} %token-table
Generate an array of token names in the parser file. The name of the
array is @code{yytname}; @code{yytname[@var{i}]} is the name of the
@code{"error"}, and @code{"$undefined"}; after these come the symbols
defined in the grammar file.
-For single-character literal tokens and literal string tokens, the name
-in the table includes the single-quote or double-quote characters: for
-example, @code{"'+'"} is a single-character literal and @code{"\"<=\""}
-is a literal string token. All the characters of the literal string
-token appear verbatim in the string found in the table; even
-double-quote characters are not escaped. For example, if the token
-consists of three characters @samp{*"*}, its string in @code{yytname}
-contains @samp{"*"*"}. (In C, that would be written as
-@code{"\"*\"*\""}).
+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
which reads tokens.
* Error Reporting:: You must supply a function @code{yyerror}.
* Action Features:: Special features for use in actions.
+* Internationalization:: How to let the parser speak in the user's
+ native language.
@end menu
@node Parser Function
The value returned by @code{yyparse} is 0 if parsing was successful (return
is due to end-of-input).
-The value is 1 if parsing failed (return is due to a syntax error).
+The value is 1 if parsing failed because of invalid input, i.e., input
+that contains a syntax error or that causes @code{YYABORT} to be
+invoked.
+
+The value is 2 if parsing failed due to memory exhaustion.
@end deftypefun
In an action, you can cause immediate return from @code{yyparse} by using
table. The index of the token in the table is the token type's code.
The name of a multicharacter token is recorded in @code{yytname} with a
double-quote, the token's characters, and another double-quote. The
-token's characters are not escaped in any way; they appear verbatim in
-the contents of the string in the table.
+token's characters are escaped as necessary to be suitable as input
+to Bison.
-Here's code for looking up a token in @code{yytname}, assuming that the
-characters of the token are stored in @code{token_buffer}.
+Here's code for looking up a multicharacter token in @code{yytname},
+assuming that the characters of the token are stored in
+@code{token_buffer}, and assuming that the token does not contain any
+characters like @samp{"} that require escaping.
@smallexample
for (i = 0; i < YYNTOKENS; i++)
@subsection Semantic Values of Tokens
@vindex yylval
-In an ordinary (non-reentrant) parser, the semantic value of the token must
+In an ordinary (nonreentrant) parser, the semantic value of the token must
be stored into the global variable @code{yylval}. When you are using
just one data type for semantic values, @code{yylval} has that type.
Thus, if the type is @code{int} (the default), you might write this in
Section}), then Bison provides a more verbose and specific error message
string instead of just plain @w{@code{"syntax error"}}.
-The parser can detect one other kind of error: stack overflow. This
-happens when the input contains constructions that are very deeply
+The parser can detect one other kind of error: memory exhaustion. This
+can happen when the input contains constructions that are very deeply
nested. It isn't likely you will encounter this, since the Bison
-parser extends its stack automatically up to a very large limit. But
-if overflow happens, @code{yyparse} calls @code{yyerror} in the usual
-fashion, except that the argument string is @w{@code{"parser stack
-overflow"}}.
+parser normally extends its stack automatically up to a very large limit. But
+if memory is exhausted, @code{yyparse} calls @code{yyerror} in the usual
+fashion, except that the argument string is @w{@code{"memory exhausted"}}.
+
+In some cases diagnostics like @w{@code{"syntax error"}} are
+translated automatically from English to some other language before
+they are passed to @code{yyerror}. @xref{Internationalization}.
The following definition suffices in simple programs:
@vindex yynerrs
The variable @code{yynerrs} contains the number of syntax errors
-encountered so far. Normally this variable is global; but if you
+reported so far. Normally this variable is global; but if you
request a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser})
then it is a local variable which only the actions can access.
Tracking Locations}.
@end deffn
+@node Internationalization
+@section Parser Internationalization
+@cindex internationalization
+@cindex i18n
+@cindex NLS
+@cindex gettext
+@cindex bison-po
+
+A Bison-generated parser can print diagnostics, including error and
+tracing messages. By default, they appear in English. However, Bison
+also supports outputting diagnostics in the user's native language.
+To make this work, the user should set the usual environment
+variables. @xref{Users, , The User's View, gettext, GNU
+@code{gettext} utilities}. For
+example, the shell command @samp{export LC_ALL=fr_CA.UTF-8} might set
+the user's locale to French Canadian using the @acronym{UTF}-8
+encoding. The exact set of available locales depends on the user's
+installation.
+
+The maintainer of a package that uses a Bison-generated parser enables
+the internationalization of the parser's output through the following
+steps. Here we assume a package that uses @acronym{GNU} Autoconf and
+@acronym{GNU} Automake.
+
+@enumerate
+@item
+@cindex bison-i18n.m4
+Into the directory containing the @acronym{GNU} Autoconf macros used
+by the package---often called @file{m4}---copy the
+@file{bison-i18n.m4} file installed by Bison under
+@samp{share/aclocal/bison-i18n.m4} in Bison's installation directory.
+For example:
+
+@example
+cp /usr/local/share/aclocal/bison-i18n.m4 m4/bison-i18n.m4
+@end example
+
+@item
+@findex BISON_I18N
+@vindex BISON_LOCALEDIR
+@vindex YYENABLE_NLS
+In the top-level @file{configure.ac}, after the @code{AM_GNU_GETTEXT}
+invocation, add an invocation of @code{BISON_I18N}. This macro is
+defined in the file @file{bison-i18n.m4} that you copied earlier. It
+causes @samp{configure} to find the value of the
+@code{BISON_LOCALEDIR} variable, and it defines the source-language
+symbol @code{YYENABLE_NLS} to enable translations in the
+Bison-generated parser.
+
+@item
+In the @code{main} function of your program, designate the directory
+containing Bison's runtime message catalog, through a call to
+@samp{bindtextdomain} with domain name @samp{bison-runtime}.
+For example:
+
+@example
+bindtextdomain ("bison-runtime", BISON_LOCALEDIR);
+@end example
+
+Typically this appears after any other call @code{bindtextdomain
+(PACKAGE, LOCALEDIR)} that your package already has. Here we rely on
+@samp{BISON_LOCALEDIR} to be defined as a string through the
+@file{Makefile}.
+
+@item
+In the @file{Makefile.am} that controls the compilation of the @code{main}
+function, make @samp{BISON_LOCALEDIR} available as a C preprocessor macro,
+either in @samp{DEFS} or in @samp{AM_CPPFLAGS}. For example:
+
+@example
+DEFS = @@DEFS@@ -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
+@end example
+
+or:
+
+@example
+AM_CPPFLAGS = -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
+@end example
+
+@item
+Finally, invoke the command @command{autoreconf} to generate the build
+infrastructure.
+@end enumerate
+
@node Algorithm
@chapter The Bison Parser Algorithm
* Reduce/Reduce:: When two rules are applicable in the same situation.
* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
* Generalized LR Parsing:: Parsing arbitrary context-free grammars.
-* Stack Overflow:: What happens when stack gets full. How to avoid it.
+* Memory Management:: What happens when memory is exhausted. How to avoid it.
@end menu
@node Look-Ahead
;
@end example
+For a more detailed exposition of @acronym{LALR}(1) parsers and parser
+generators, please see:
+Frank DeRemer and Thomas Pennello, Efficient Computation of
+@acronym{LALR}(1) Look-Ahead Sets, @cite{@acronym{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}.
+
@node Generalized LR Parsing
@section Generalized @acronym{LR} (@acronym{GLR}) Parsing
@cindex @acronym{GLR} parsing
@cindex generalized @acronym{LR} (@acronym{GLR}) parsing
@cindex ambiguous grammars
-@cindex non-deterministic parsing
+@cindex nondeterministic parsing
Bison produces @emph{deterministic} parsers that choose uniquely
when to reduce and which reduction to apply
context-free grammar in cubic worst-case time. However, Bison currently
uses a simpler data structure that requires time proportional to the
length of the input times the maximum number of stacks required for any
-prefix of the input. Thus, really ambiguous or non-deterministic
+prefix of the input. Thus, really ambiguous or nondeterministic
grammars can require exponential time and space to process. Such badly
behaving examples, however, are not generally of practical interest.
-Usually, non-determinism in a grammar is local---the parser is ``in
+Usually, nondeterminism in a grammar is local---the parser is ``in
doubt'' only for a few tokens at a time. Therefore, the current data
structure should generally be adequate. On @acronym{LALR}(1) portions of a
grammar, in particular, it is only slightly slower than with the default
@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps},
(2000-12-24).
-@node Stack Overflow
-@section Stack Overflow, and How to Avoid It
+@node Memory Management
+@section Memory Management, and How to Avoid Memory Exhaustion
+@cindex memory exhaustion
+@cindex memory management
@cindex stack overflow
@cindex parser stack overflow
@cindex overflow of parser stack
-The Bison parser stack can overflow if too many tokens are shifted and
+The Bison parser stack can run out of memory if too many tokens are shifted and
not reduced. When this happens, the parser function @code{yyparse}
-returns a nonzero value, pausing only to call @code{yyerror} to report
-the overflow.
+calls @code{yyerror} and then returns 2.
Because Bison parsers have growing stacks, hitting the upper limit
usually results from using a right recursion instead of a left
@vindex YYMAXDEPTH
By defining the macro @code{YYMAXDEPTH}, you can control how deep the
-parser stack can become before a stack overflow occurs. Define the
+parser stack can become before memory is exhausted. Define the
macro with a value that is an integer. This value is the maximum number
of tokens that can be shifted (and not reduced) before overflow.
The stack space allowed is not necessarily allocated. If you specify a
-large value for @code{YYMAXDEPTH}, the parser actually allocates a small
+large value for @code{YYMAXDEPTH}, the parser normally allocates a small
stack at first, and then makes it bigger by stages as needed. This
increasing allocation happens automatically and silently. Therefore,
you do not need to make @code{YYMAXDEPTH} painfully small merely to save
unless you are assuming C99 or some other target language or compiler
that allows variable-length arrays. The default is 200.
-Do not allow @code{YYINITDEPTH} to be a value so large that arithmetic
-overflow would occur when calculating the size of the stack space.
-Also, do not allow @code{YYINITDEPTH} to be greater than
-@code{YYMAXDEPTH}.
+Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
@c FIXME: C++ output.
Because of semantical differences between C and C++, the
-@acronym{LALR}(1) parsers in C produced by Bison by compiled as C++
-cannot grow. In this precise case (compiling a C parser as C++) you are
-suggested to grow @code{YYINITDEPTH}. In the near future, a C++ output
-output will be provided which addresses this issue.
+@acronym{LALR}(1) parsers in C produced by Bison cannot grow when compiled
+by C++ compilers. In this precise case (compiling a C parser as C++) you are
+suggested to grow @code{YYINITDEPTH}. The Bison maintainers hope to fix
+this deficiency in a future release.
@node Error Recovery
@chapter Error Recovery
Here @var{infile} is the grammar file name, which usually ends in
@samp{.y}. The parser file's name is made by replacing the @samp{.y}
-with @samp{.tab.c}. Thus, the @samp{bison foo.y} filename yields
-@file{foo.tab.c}, and the @samp{bison hack/foo.y} filename yields
-@file{hack/foo.tab.c}. It's also possible, in case you are writing
+with @samp{.tab.c} and removing any leading directory. Thus, the
+@samp{bison foo.y} file name yields
+@file{foo.tab.c}, and the @samp{bison hack/foo.y} file name yields
+@file{foo.tab.c}. It's also possible, in case you are writing
C++ code instead of C in your grammar file, to name it @file{foo.ypp}
or @file{foo.y++}. Then, the output files will take an extension like
the given one as input (respectively @file{foo.tab.cpp} and
@file{foo.tab.c++}).
-This feature takes effect with all options that manipulate filenames like
+This feature takes effect with all options that manipulate file names like
@samp{-o} or @samp{-d}.
For example :
@itemx --version
Print the version number of Bison and exit.
+@item --print-localedir
+Print the name of the directory containing locale-dependent data.
+
@need 1750
@item -y
@itemx --yacc
file containing verbose descriptions of the grammar and
parser. @xref{Decl Summary}.
-@item -o @var{filename}
-@itemx --output=@var{filename}
-Specify the @var{filename} for the parser file.
+@item -o @var{file}
+@itemx --output=@var{file}
+Specify the @var{file} for the parser file.
-The other output files' names are constructed from @var{filename} as
+The other output files' names are constructed from @var{file} as
described under the @samp{-v} and @samp{-d} options.
@item -g
@item --graph=@var{graph-file}
The behavior of @var{--graph} is the same than @samp{-g}. The only
difference is that it has an optional argument which is the name of
-the output graph filename.
+the output graph file.
@end table
@node Option Cross Key
\line{ --no-lines \leaderfill -l}
\line{ --no-parser \leaderfill -n}
\line{ --output \leaderfill -o}
+\line{ --print-localedir}
\line{ --token-table \leaderfill -k}
\line{ --verbose \leaderfill -v}
\line{ --version \leaderfill -V}
--no-lines -l
--no-parser -n
--output=@var{outfile} -o @var{outfile}
+--print-localedir
--token-table -k
--verbose -v
--version -V
int yyparse (void);
@end example
-@c ================================================= Invoking Bison
+@c ================================================= C++ Bison
+
+@node C++ Language Interface
+@chapter C++ Language Interface
+
+@menu
+* C++ Parsers:: The interface to generate C++ parser classes
+* A Complete C++ Example:: Demonstrating their use
+@end menu
+
+@node C++ Parsers
+@section C++ Parsers
+
+@menu
+* C++ Bison Interface:: Asking for C++ parser generation
+* C++ Semantic Values:: %union vs. C++
+* C++ Location Values:: The position and location classes
+* C++ Parser Interface:: Instantiating and running the parser
+* C++ Scanner Interface:: Exchanges between yylex and parse
+@end menu
+
+@node C++ Bison Interface
+@subsection C++ Bison Interface
+@c - %skeleton "lalr1.cc"
+@c - Always pure
+@c - initial action
+
+The C++ parser @acronym{LALR}(1) skeleton is named @file{lalr1.cc}. To select
+it, you may either pass the option @option{--skeleton=lalr1.cc} to
+Bison, or include the directive @samp{%skeleton "lalr1.cc"} in the
+grammar preamble. When run, @command{bison} will create several
+files:
+@table @file
+@item position.hh
+@itemx location.hh
+The definition of the classes @code{position} and @code{location},
+used for location tracking. @xref{C++ Location Values}.
+
+@item stack.hh
+An auxiliary class @code{stack} used by the parser.
+
+@item @var{file}.hh
+@itemx @var{file}.cc
+The declaration and implementation of the C++ parser class.
+@var{file} is the name of the output file. It follows the same
+rules as with regular C parsers.
+
+Note that @file{@var{file}.hh} is @emph{mandatory}, the C++ cannot
+work without the parser class declaration. Therefore, you must either
+pass @option{-d}/@option{--defines} to @command{bison}, or use the
+@samp{%defines} directive.
+@end table
+
+All these files are documented using Doxygen; run @command{doxygen}
+for a complete and accurate documentation.
+
+@node C++ Semantic Values
+@subsection C++ Semantic Values
+@c - No objects in unions
+@c - YSTYPE
+@c - Printer and destructor
+
+The @code{%union} directive works as for C, see @ref{Union Decl, ,The
+Collection of Value Types}. In particular it produces a genuine
+@code{union}@footnote{In the future techniques to allow complex types
+within pseudo-unions (similar to Boost variants) might be implemented to
+alleviate these issues.}, which have a few specific features in C++.
+@itemize @minus
+@item
+The type @code{YYSTYPE} is defined but its use is discouraged: rather
+you should refer to the parser's encapsulated type
+@code{yy::parser::semantic_type}.
+@item
+Non POD (Plain Old Data) types cannot be used. C++ forbids any
+instance of classes with constructors in unions: only @emph{pointers}
+to such objects are allowed.
+@end itemize
+
+Because objects have to be stored via pointers, memory is not
+reclaimed automatically: using the @code{%destructor} directive is the
+only means to avoid leaks. @xref{Destructor Decl, , Freeing Discarded
+Symbols}.
+
+
+@node C++ Location Values
+@subsection C++ Location Values
+@c - %locations
+@c - class Position
+@c - class Location
+@c - %define "filename_type" "const symbol::Symbol"
+
+When the directive @code{%locations} is used, the C++ parser supports
+location tracking, see @ref{Locations, , Locations Overview}. Two
+auxiliary classes define a @code{position}, a single point in a file,
+and a @code{location}, a range composed of a pair of
+@code{position}s (possibly spanning several files).
+
+@deftypemethod {position} {std::string*} file
+The name of the file. It will always be handled as a pointer, the
+parser will never duplicate nor deallocate it. As an experimental
+feature you may change it to @samp{@var{type}*} using @samp{%define
+"filename_type" "@var{type}"}.
+@end deftypemethod
+
+@deftypemethod {position} {unsigned int} line
+The line, starting at 1.
+@end deftypemethod
+
+@deftypemethod {position} {unsigned int} lines (int @var{height} = 1)
+Advance by @var{height} lines, resetting the column number.
+@end deftypemethod
+
+@deftypemethod {position} {unsigned int} column
+The column, starting at 0.
+@end deftypemethod
+
+@deftypemethod {position} {unsigned int} columns (int @var{width} = 1)
+Advance by @var{width} columns, without changing the line number.
+@end deftypemethod
+
+@deftypemethod {position} {position&} operator+= (position& @var{pos}, int @var{width})
+@deftypemethodx {position} {position} operator+ (const position& @var{pos}, int @var{width})
+@deftypemethodx {position} {position&} operator-= (const position& @var{pos}, int @var{width})
+@deftypemethodx {position} {position} operator- (position& @var{pos}, int @var{width})
+Various forms of syntactic sugar for @code{columns}.
+@end deftypemethod
+
+@deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p})
+Report @var{p} on @var{o} like this:
+@samp{@var{file}:@var{line}.@var{column}}, or
+@samp{@var{line}.@var{column}} if @var{file} is null.
+@end deftypemethod
+
+@deftypemethod {location} {position} begin
+@deftypemethodx {location} {position} end
+The first, inclusive, position of the range, and the first beyond.
+@end deftypemethod
+
+@deftypemethod {location} {unsigned int} columns (int @var{width} = 1)
+@deftypemethodx {location} {unsigned int} lines (int @var{height} = 1)
+Advance the @code{end} position.
+@end deftypemethod
+
+@deftypemethod {location} {location} operator+ (const location& @var{begin}, const location& @var{end})
+@deftypemethodx {location} {location} operator+ (const location& @var{begin}, int @var{width})
+@deftypemethodx {location} {location} operator+= (const location& @var{loc}, int @var{width})
+Various forms of syntactic sugar.
+@end deftypemethod
+
+@deftypemethod {location} {void} step ()
+Move @code{begin} onto @code{end}.
+@end deftypemethod
+
+
+@node C++ Parser Interface
+@subsection C++ Parser Interface
+@c - define parser_class_name
+@c - Ctor
+@c - parse, error, set_debug_level, debug_level, set_debug_stream,
+@c debug_stream.
+@c - Reporting errors
+
+The output files @file{@var{output}.hh} and @file{@var{output}.cc}
+declare and define the parser class in the namespace @code{yy}. The
+class name defaults to @code{parser}, but may be changed using
+@samp{%define "parser_class_name" "@var{name}"}. The interface of
+this class is detailed below. It can be extended using the
+@code{%parse-param} feature: its semantics is slightly changed since
+it describes an additional member of the parser class, and an
+additional argument for its constructor.
+
+@defcv {Type} {parser} {semantic_value_type}
+@defcvx {Type} {parser} {location_value_type}
+The types for semantics value and locations.
+@end defcv
+
+@deftypemethod {parser} {} parser (@var{type1} @var{arg1}, ...)
+Build a new parser object. There are no arguments by default, unless
+@samp{%parse-param @{@var{type1} @var{arg1}@}} was used.
+@end deftypemethod
+
+@deftypemethod {parser} {int} parse ()
+Run the syntactic analysis, and return 0 on success, 1 otherwise.
+@end deftypemethod
+
+@deftypemethod {parser} {std::ostream&} debug_stream ()
+@deftypemethodx {parser} {void} set_debug_stream (std::ostream& @var{o})
+Get or set the stream used for tracing the parsing. It defaults to
+@code{std::cerr}.
+@end deftypemethod
+
+@deftypemethod {parser} {debug_level_type} debug_level ()
+@deftypemethodx {parser} {void} set_debug_level (debug_level @var{l})
+Get or set the tracing level. Currently its value is either 0, no trace,
+or nonzero, full tracing.
+@end deftypemethod
+
+@deftypemethod {parser} {void} error (const location_type& @var{l}, const std::string& @var{m})
+The definition for this member function must be supplied by the user:
+the parser uses it to report a parser error occurring at @var{l},
+described by @var{m}.
+@end deftypemethod
+
+
+@node C++ Scanner Interface
+@subsection C++ Scanner Interface
+@c - prefix for yylex.
+@c - Pure interface to yylex
+@c - %lex-param
+
+The parser invokes the scanner by calling @code{yylex}. Contrary to C
+parsers, C++ parsers are always pure: there is no point in using the
+@code{%pure-parser} directive. Therefore the interface is as follows.
+
+@deftypemethod {parser} {int} yylex (semantic_value_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...)
+Return the next token. Its type is the return value, its semantic
+value and location being @var{yylval} and @var{yylloc}. Invocations of
+@samp{%lex-param @{@var{type1} @var{arg1}@}} yield additional arguments.
+@end deftypemethod
+
+
+@node A Complete C++ Example
+@section A Complete C++ Example
+
+This section demonstrates the use of a C++ parser with a simple but
+complete example. This example should be available on your system,
+ready to compile, in the directory @dfn{../bison/examples/calc++}. It
+focuses on the use of Bison, therefore the design of the various C++
+classes is very naive: no accessors, no encapsulation of members etc.
+We will use a Lex scanner, and more precisely, a Flex scanner, to
+demonstrate the various interaction. A hand written scanner is
+actually easier to interface with.
+
+@menu
+* Calc++ --- C++ Calculator:: The specifications
+* Calc++ Parsing Driver:: An active parsing context
+* Calc++ Parser:: A parser class
+* Calc++ Scanner:: A pure C++ Flex scanner
+* Calc++ Top Level:: Conducting the band
+@end menu
+
+@node Calc++ --- C++ Calculator
+@subsection Calc++ --- C++ Calculator
+
+Of course the grammar is dedicated to arithmetics, a single
+expression, possibly preceded by variable assignments. An
+environment containing possibly predefined variables such as
+@code{one} and @code{two}, is exchanged with the parser. An example
+of valid input follows.
+
+@example
+three := 3
+seven := one + two * three
+seven * seven
+@end example
+
+@node Calc++ Parsing Driver
+@subsection Calc++ Parsing Driver
+@c - An env
+@c - A place to store error messages
+@c - A place for the result
+
+To support a pure interface with the parser (and the scanner) the
+technique of the ``parsing context'' is convenient: a structure
+containing all the data to exchange. Since, in addition to simply
+launch the parsing, there are several auxiliary tasks to execute (open
+the file for parsing, instantiate the parser etc.), we recommend
+transforming the simple parsing context structure into a fully blown
+@dfn{parsing driver} class.
+
+The declaration of this driver class, @file{calc++-driver.hh}, is as
+follows. The first part includes the CPP guard and imports the
+required standard library components, and the declaration of the parser
+class.
+
+@comment file: calc++-driver.hh
+@example
+#ifndef CALCXX_DRIVER_HH
+# define CALCXX_DRIVER_HH
+# include <string>
+# include <map>
+# include "calc++-parser.hh"
+@end example
+
+
+@noindent
+Then comes the declaration of the scanning function. Flex expects
+the signature of @code{yylex} to be defined in the macro
+@code{YY_DECL}, and the C++ parser expects it to be declared. We can
+factor both as follows.
+
+@comment file: calc++-driver.hh
+@example
+// Announce to Flex the prototype we want for lexing function, ...
+# define YY_DECL \
+ int yylex (yy::calcxx_parser::semantic_type* yylval, \
+ yy::calcxx_parser::location_type* yylloc, \
+ calcxx_driver& driver)
+// ... and declare it for the parser's sake.
+YY_DECL;
+@end example
+
+@noindent
+The @code{calcxx_driver} class is then declared with its most obvious
+members.
+
+@comment file: calc++-driver.hh
+@example
+// Conducting the whole scanning and parsing of Calc++.
+class calcxx_driver
+@{
+public:
+ calcxx_driver ();
+ virtual ~calcxx_driver ();
+
+ std::map<std::string, int> variables;
+
+ int result;
+@end example
+
+@noindent
+To encapsulate the coordination with the Flex scanner, it is useful to
+have two members function to open and close the scanning phase.
+members.
+
+@comment file: calc++-driver.hh
+@example
+ // Handling the scanner.
+ void scan_begin ();
+ void scan_end ();
+ bool trace_scanning;
+@end example
+
+@noindent
+Similarly for the parser itself.
+
+@comment file: calc++-driver.hh
+@example
+ // Handling the parser.
+ void parse (const std::string& f);
+ std::string file;
+ bool trace_parsing;
+@end example
+
+@noindent
+To demonstrate pure handling of parse errors, instead of simply
+dumping them on the standard error output, we will pass them to the
+compiler driver using the following two member functions. Finally, we
+close the class declaration and CPP guard.
+
+@comment file: calc++-driver.hh
+@example
+ // Error handling.
+ void error (const yy::location& l, const std::string& m);
+ void error (const std::string& m);
+@};
+#endif // ! CALCXX_DRIVER_HH
+@end example
+
+The implementation of the driver is straightforward. The @code{parse}
+member function deserves some attention. The @code{error} functions
+are simple stubs, they should actually register the located error
+messages and set error state.
+
+@comment file: calc++-driver.cc
+@example
+#include "calc++-driver.hh"
+#include "calc++-parser.hh"
+
+calcxx_driver::calcxx_driver ()
+ : trace_scanning (false), trace_parsing (false)
+@{
+ variables["one"] = 1;
+ variables["two"] = 2;
+@}
+
+calcxx_driver::~calcxx_driver ()
+@{
+@}
+
+void
+calcxx_driver::parse (const std::string &f)
+@{
+ file = f;
+ scan_begin ();
+ yy::calcxx_parser parser (*this);
+ parser.set_debug_level (trace_parsing);
+ parser.parse ();
+ scan_end ();
+@}
+
+void
+calcxx_driver::error (const yy::location& l, const std::string& m)
+@{
+ std::cerr << l << ": " << m << std::endl;
+@}
+
+void
+calcxx_driver::error (const std::string& m)
+@{
+ std::cerr << m << std::endl;
+@}
+@end example
+
+@node Calc++ Parser
+@subsection Calc++ Parser
+
+The parser definition file @file{calc++-parser.yy} starts by asking for
+the C++ LALR(1) skeleton, the creation of the parser header file, and
+specifies the name of the parser class. Because the C++ skeleton
+changed several times, it is safer to require the version you designed
+the grammar for.
+
+@comment file: calc++-parser.yy
+@example
+%skeleton "lalr1.cc" /* -*- C++ -*- */
+%require "2.1a"
+%defines
+%define "parser_class_name" "calcxx_parser"
+@end example
+
+@noindent
+Then come the declarations/inclusions needed to define the
+@code{%union}. Because the parser uses the parsing driver and
+reciprocally, both cannot include the header of the other. Because the
+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.
+
+@comment file: calc++-parser.yy
+@example
+%@{
+# include <string>
+class calcxx_driver;
+%@}
+@end example
+
+@noindent
+The driver is passed by reference to the parser and to the scanner.
+This provides a simple but effective pure interface, not relying on
+global variables.
+
+@comment file: calc++-parser.yy
+@example
+// The parsing context.
+%parse-param @{ calcxx_driver& driver @}
+%lex-param @{ calcxx_driver& driver @}
+@end example
+
+@noindent
+Then we request the location tracking feature, and initialize the
+first location's file name. Afterwards new locations are computed
+relatively to the previous locations: the file name will be
+automatically propagated.
+
+@comment file: calc++-parser.yy
+@example
+%locations
+%initial-action
+@{
+ // Initialize the initial location.
+ @@$.begin.filename = @@$.end.filename = &driver.file;
+@};
+@end example
+
+@noindent
+Use the two following directives to enable parser tracing and verbose
+error messages.
+
+@comment file: calc++-parser.yy
+@example
+%debug
+%error-verbose
+@end example
+
+@noindent
+Semantic values cannot use ``real'' objects, but only pointers to
+them.
+
+@comment file: calc++-parser.yy
+@example
+// Symbols.
+%union
+@{
+ int ival;
+ std::string *sval;
+@};
+@end example
+
+@noindent
+The code between @samp{%@{} and @samp{%@}} after the introduction of the
+@samp{%union} is output in the @file{*.cc} file; it needs detailed
+knowledge about the driver.
+
+@comment file: calc++-parser.yy
+@example
+%@{
+# include "calc++-driver.hh"
+%@}
+@end example
+
+
+@noindent
+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 ``$end''. Similarly user friendly named are provided for each
+symbol. Note that the tokens names are prefixed by @code{TOKEN_} to
+avoid name clashes.
+
+@comment file: calc++-parser.yy
+@example
+%token END 0 "end of file"
+%token ASSIGN ":="
+%token <sval> IDENTIFIER "identifier"
+%token <ival> NUMBER "number"
+%type <ival> exp "expression"
+@end example
+
+@noindent
+To enable memory deallocation during error recovery, use
+@code{%destructor}.
+
+@comment file: calc++-parser.yy
+@example
+%printer @{ debug_stream () << *$$; @} "identifier"
+%destructor @{ delete $$; @} "identifier"
+
+%printer @{ debug_stream () << $$; @} "number" "expression"
+@end example
+
+@noindent
+The grammar itself is straightforward.
+
+@comment file: calc++-parser.yy
+@example
+%%
+%start unit;
+unit: assignments exp @{ driver.result = $2; @};
+
+assignments: assignments assignment @{@}
+ | /* Nothing. */ @{@};
+
+assignment: "identifier" ":=" exp @{ driver.variables[*$1] = $3; @};
+
+%left '+' '-';
+%left '*' '/';
+exp: exp '+' exp @{ $$ = $1 + $3; @}
+ | exp '-' exp @{ $$ = $1 - $3; @}
+ | exp '*' exp @{ $$ = $1 * $3; @}
+ | exp '/' exp @{ $$ = $1 / $3; @}
+ | "identifier" @{ $$ = driver.variables[*$1]; @}
+ | "number" @{ $$ = $1; @};
+%%
+@end example
+
+@noindent
+Finally the @code{error} member function registers the errors to the
+driver.
+
+@comment file: calc++-parser.yy
+@example
+void
+yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
+ const std::string& m)
+@{
+ driver.error (l, m);
+@}
+@end example
+
+@node Calc++ Scanner
+@subsection Calc++ Scanner
+
+The Flex scanner first includes the driver declaration, then the
+parser's to get the set of defined tokens.
+
+@comment file: calc++-scanner.ll
+@example
+%@{ /* -*- C++ -*- */
+# include <cstdlib>
+# include <errno.h>
+# include <limits.h>
+# include <string>
+# include "calc++-driver.hh"
+# include "calc++-parser.hh"
+%@}
+@end example
+
+@noindent
+Because there is no @code{#include}-like feature we don't need
+@code{yywrap}, we don't need @code{unput} either, and we parse an
+actual file, this is not an interactive session with the user.
+Finally we enable the scanner tracing features.
+
+@comment file: calc++-scanner.ll
+@example
+%option noyywrap nounput batch debug
+@end example
+
+@noindent
+Abbreviations allow for more readable rules.
+
+@comment file: calc++-scanner.ll
+@example
+id [a-zA-Z][a-zA-Z_0-9]*
+int [0-9]+
+blank [ \t]
+@end example
+
+@noindent
+The following paragraph suffices to track locations accurately. Each
+time @code{yylex} is invoked, the begin position is moved onto the end
+position. Then when a pattern is matched, the end position is
+advanced of its width. In case it matched ends of lines, the end
+cursor is adjusted, and each time blanks are matched, the begin cursor
+is moved onto the end cursor to effectively ignore the blanks
+preceding tokens. Comments would be treated equally.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+# define YY_USER_ACTION yylloc->columns (yyleng);
+%@}
+%%
+%@{
+ yylloc->step ();
+%@}
+@{blank@}+ yylloc->step ();
+[\n]+ yylloc->lines (yyleng); yylloc->step ();
+@end example
+
+@noindent
+The rules are simple, just note the use of the driver to report errors.
+It is convenient to use a typedef to shorten
+@code{yy::calcxx_parser::token::identifier} into
+@code{token::identifier} for instance.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+ typedef yy::calcxx_parser::token token;
+%@}
+
+[-+*/] return yytext[0];
+":=" return token::ASSIGN;
+@{int@} @{
+ errno = 0;
+ long n = strtol (yytext, NULL, 10);
+ if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
+ driver.error (*yylloc, "integer is out of range");
+ yylval->ival = n;
+ return token::NUMBER;
+@}
+@{id@} yylval->sval = new std::string (yytext); return token::IDENTIFIER;
+. driver.error (*yylloc, "invalid character");
+%%
+@end example
+
+@noindent
+Finally, because the scanner related driver's member function depend
+on the scanner's data, it is simpler to implement them in this file.
+
+@comment file: calc++-scanner.ll
+@example
+void
+calcxx_driver::scan_begin ()
+@{
+ yy_flex_debug = trace_scanning;
+ if (!(yyin = fopen (file.c_str (), "r")))
+ error (std::string ("cannot open ") + file);
+@}
+
+void
+calcxx_driver::scan_end ()
+@{
+ fclose (yyin);
+@}
+@end example
+
+@node Calc++ Top Level
+@subsection Calc++ Top Level
+
+The top level file, @file{calc++.cc}, poses no problem.
+
+@comment file: calc++.cc
+@example
+#include <iostream>
+#include "calc++-driver.hh"
+
+int
+main (int argc, char *argv[])
+@{
+ calcxx_driver driver;
+ for (++argv; argv[0]; ++argv)
+ if (*argv == std::string ("-p"))
+ driver.trace_parsing = true;
+ else if (*argv == std::string ("-s"))
+ driver.trace_scanning = true;
+ else
+ @{
+ driver.parse (*argv);
+ std::cout << driver.result << std::endl;
+ @}
+@}
+@end example
+
+@c ================================================= FAQ
@node FAQ
@chapter Frequently Asked Questions
are addressed.
@menu
-* Parser Stack Overflow:: Breaking the Stack Limits
+* Memory Exhausted:: Breaking the Stack Limits
* How Can I Reset the Parser:: @code{yyparse} Keeps some State
* Strings are Destroyed:: @code{yylval} Loses Track of Strings
-* C++ Parsers:: Compiling Parsers with C++ Compilers
* Implementing Gotos/Loops:: Control Flow in the Calculator
@end menu
-@node Parser Stack Overflow
-@section Parser Stack Overflow
+@node Memory Exhausted
+@section Memory Exhausted
@display
-My parser returns with error with a @samp{parser stack overflow}
+My parser returns with error with a @samp{memory exhausted}
message. What can I do?
@end display
@end example
-@node C++ Parsers
-@section C++ Parsers
-
-@display
-How can I generate parsers in C++?
-@end display
-
-We are working on a C++ output for Bison, but unfortunately, for lack of
-time, the skeleton is not finished. It is functional, but in numerous
-respects, it will require additional work which @emph{might} break
-backward compatibility. Since the skeleton for C++ is not documented,
-we do not consider ourselves bound to this interface, nevertheless, as
-much as possible we will try to keep compatibility.
-
-Another possibility is to use the regular C parsers, and to compile them
-with a C++ compiler. This works properly, provided that you bear some
-simple C++ rules in mind, such as not including ``real classes'' (i.e.,
-structure with constructors) in unions. Therefore, in the
-@code{%union}, use pointers to classes.
-
-
@node Implementing Gotos/Loops
@section Implementing Gotos/Loops
@end deffn
@deffn {Directive} %destructor
-Specifying how the parser should reclaim the memory associated to
+Specify how the parser should reclaim the memory associated to
discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
@end deffn
@end deffn
@deffn {Directive} %nonassoc
-Bison declaration to assign non-associativity to token(s).
+Bison declaration to assign nonassociativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
-@deffn {Directive} %output="@var{filename}"
+@deffn {Directive} %output="@var{file}"
Bison declaration to set the name of the parser file. @xref{Decl
Summary}.
@end deffn
@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
@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} %right
Bison declaration to assign right associativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@deffn {Macro} YYINITDEPTH
Macro for specifying the initial size of the parser stack.
-@xref{Stack Overflow}.
+@xref{Memory Management}.
@end deffn
@deffn {Function} yylex
@end deffn
@deffn {Macro} YYMAXDEPTH
-Macro for specifying the maximum size of the parser stack. @xref{Stack
-Overflow}.
+Macro for specifying the maximum size of the parser stack. @xref{Memory
+Management}.
@end deffn
@deffn {Variable} yynerrs
-Global variable which Bison increments each time there is a syntax error.
+Global variable which Bison increments each time it reports a syntax error.
(In a pure parser, it is a local variable within @code{yyparse}.)
@xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
@end deffn
reserved for future Bison extensions. If not defined,
@code{YYSTACK_USE_ALLOCA} defaults to 0.
-If you define @code{YYSTACK_USE_ALLOCA} to 1, it is your
-responsibility to make sure that @code{alloca} is visible, e.g., by
-using @acronym{GCC} or by including @code{<stdlib.h>}. Furthermore,
-in the all-too-common case where your code may run on a host with a
+In the all-too-common case where your code may run on a host with a
limited stack and with unreliable stack-overflow checking, you should
set @code{YYMAXDEPTH} to a value that cannot possibly result in
unchecked stack overflow on any of your target hosts when
projects / bison.git / blobdiff