.TH "bisonc++" "1" "2005\-2024" "bisonc++\&.6\&.08\&.00" "bisonc++ parser generator"

.PP 
.SH "NAME"
bisonc++ \- Generate a C++ parser class and parsing function
.PP 
.SH "SYNOPSIS"
\fBbisonc++\fP [OPTIONS] \fIgrammar\-file\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fBBisonc++\fP derives from previous work on \fBbison\fP by Alain Coetmeur
(coetmeur@icdc\&.fr), who created in the early \(cq\&90s a \fBC++\fP class encapsulating
the \fIyyparse\fP function as generated by the GNU\-\fBbison\fP parser generator\&.
.PP 
Initial versions of \fBbisonc++\fP (up to version 0\&.92) wrapped Alain\(cq\&s program in
a program offering a more modern user\-interface, removing all old\-style
(\fBC\fP) \fI%define\fP directives from \fBbison++\fP\(cq\&s input specification file
(see below for an in\-depth discussion of the differences between \fBbison++\fP
and \fBbisonc++\fP)\&. Starting with version 0\&.98, \fBbisonc++\fP is a complete rebuilt of
the parser generator, closely following descriptions given in Aho, Sethi and
Ullman\(cq\&s \fIDragon Book\fP\&. Since version 0\&.98 \fBbisonc++\fP is a \fBC++\fP program, rather
than a \fBC\fP program generating \fBC++\fP code\&.
.PP 
\fBBisonc++\fP expands the concepts initially implemented in \fBbison\fP and
\fBbison++\fP, offering a cleaner setup of the generated parser class\&. The
parser class is derived from a base\-class, mainly containing the parser\(cq\&s
token\- and type\-definitions as well as several member functions which should
not be modified by the programmer\&. 
.PP 
Most of these base\-class members might also be defined directly in the
parser class, but were defined in the parser\(cq\&s base\-class\&. This design results
in a very lean parser class, declaring only members that are actually defined
by the programmer or that have to be defined by \fBbisonc++\fP itself (e\&.g\&., the
member function \fIparse\fP as well as some support functions requiring access
to facilities that are only available in the parser class itself, rather than
in the parser\(cq\&s base class)\&.  
.PP 
This design does not require any virtual members: the members which are
not involved in the actual parsing process may always be (re)implemented
directly by the programmer\&. Thus there is no need to apply or define virtual
member functions\&.
.PP 
Before version 5\&.00\&.00 \fBbisonc++\fP offered one single manual page\&. The advantage
of one man\-page is of course that you never have to look for which manual page
contains which information\&. But on the other hand, \fBbisonc++\fP\(cq\&s man\-page grew into
a huge man\-page of about 2000 lines in which it was hard to find your
way\&. From release 5\&.00\&.00 onward, three man\-pages\&. The index below relates
manual pages to their specific contents\&.
.PP 
\fBOverview of the contents of bisonc++\(cq\&s man\-pages\fP
.PP 
This man\-page concentrates on the \fIbisonc++\fP program itself, offering
the following sections:
.PP 
.IP o 
\fBDESCRIPTION\fP: a short description of \fBbisonc++\fP and its roots;
.IP o 
\fBFROM BISONC++ < 6\&.00\&.00 TO BISONC++ >= 6\&.00\&.00\fP: required
modifications when re\-generating parsers; 
.IP o 
\fBOPTIONS\fP: options supported by \fBbisonc++\fP\&.
.IP o 
\fBQUICK START\fP: a quick start overview about how to use \fBbisonc++\fP;
.IP o 
\fBGENERATED FILES\fP: files generated by \fBbisonc++\fP and their purposes
.IP o 
\fBFILES\fP: skeleton files used by \fBbisonc++\fP;
.IP o 
\fBSEE ALSO\fP: references to other programs and documentation;
.IP o 
\fBBUGS\fP: some additional stuff that should not qualify as bugs\&.
.IP o 
\fBABOUT bisonc++\fP: Some history;
.IP o 
\fBAUTHOR\fP: at the end of this man\-page\&.
)
.PP 
The \fBbisonc++input\fP(7) man\-page covers the details of the
grammar\-specification file\&. This man\-page offers these sections:
.IP o 
\fBDESCRIPTION\fP: a short description of \fBbisonc++\fP and its grammar
file(s);
.IP o 
\fBDIRECTIVES\fP: \fBbisonc++\fP\(cq\&s grammar\-specification directives;
.IP o 
\fBPOLYMORPHIC SEMANTIC VALUES\fP: how to use polymorphic semantic
values in parsers generated by \fBbisonc++\fP;
.IP o 
\fBDOLLAR NOTATIONS\fP: available $\-shorthand notations with single,
union, and polymorphic semantic value types\&.
.IP o 
\fBRESTRICTIONS ON TOKEN NAMES\fP: name restrictions for user\-defined
symbols;
.IP o 
\fBOBSOLETE SYMBOLS\fP: symbols available to \fBbison\fP(1), but not
to \fBbisonc++\fP;
.IP o 
\fBUSING SYMBOLIC TOKENS IN CLASSES OTHER THAN THE PARSER CLASS\fP;
how to refer to tokens defined in the grammar; 
.IP o 
\fBEXAMPLE\fP: an example of using \fBbisonc++\fP;
.IP o 
\fBSEE ALSO\fP: references to other programs and documentation;
.IP o 
\fBAUTHOR\fP: at the end of this man\-page\&.

.PP 
The \fBbisonc++api\fP(3) describes the application programmer\(cq\&s
interface, containing these sections:
.IP o 
\fBDESCRIPTION\fP: a short description of \fBbisonc++\fP and its application
programmer\(cq\&s interface;
.IP o 
\fBPUBLIC SYMBOLS\fP: constructor, enums, members, and types that can
be used by calling software;
.IP o 
\fBPRIVATE ENUMS AND \-TYPES\fP: enumerations and types only
available to the \fIParser\fP class;
.IP o 
\fBPRIVATE MEMBER FUNCTIONS\fP: member functions that are only
available to the \fIParser\fP class;
.IP o 
\fBPRIVATE DATA MEMBERS\fP: data members that are only available to
the \fIParser\fP class;
.IP o 
\fBTYPES AND VARIABLES IN THE ANONYMOUS NAMESPACE\fP: an overview of
the types and variables that are used to define and store the
grammar\-tables generated by \fBbisonc++\fP;
.IP o 
\fBSEE ALSO\fP: references to other programs and documentation;
.IP o 
\fBAUTHOR\fP: at the end of this man\-page\&.

.PP 
.SH "FROM BISONC++ < 6\&.00\&.00 TO BISONC++ >= 6\&.00\&.00"

.PP 
This section is only relevant when re\-generating parser code previously
generated by \fBbisonc++\fP versions before 6\&.00\&.00\&. 
.PP 
\fBBisonc++\fP version 6\&.00\&.00 generates code that significantly differs from code
generated by earlier versions\&. The identifiers of all members (both data and
functions) that are generated by \fBbisonc++\fP and accessible to the generated
parser\-class end in an underscore character\&. Member functions whose
identifiers end in an underscore are `owned\(cq\& by \fBbisonc++\fP, are rewritten each
time \fBbisonc++\fP is run, and should not be modified\&. Some members are defined as
members of the generated parser\-class, and are declared in the parser class
header file (e\&.g\&., \fIparser\&.h\fP) and some members are given default
implementations in the parser\(cq\&s internal header file (e\&.g\&.,
\fIparser\&.ih\fP)\&. Once generated, these files are left alone by
\fBbisonc++\fP\&. Therefore, when using \fBbisonc++\fP version 6\&.00\&.00 or beyond to re\-generate a
parser which was originally generated by an earlier \fBbisonc++\fP version, the
existing parser header and internal header files need some minor
modifications: 
.IP o 
\fIvoid error(char const *)\fP was changed to \fIvoid error()\fP\&. A
default implementation is provided in the parser\(cq\&s internal header file\&. The
current implementation directly inserts the text \fISyntax error\fP into the
standard output stream;
.IP o 
\fIvoid exceptionHandler_(std::exception const &exc)\fP was changed to
\fIvoid exceptionHandler(std::exception const &exc)\fP\&. A
default implementation is provided in the parser\(cq\&s internal header file, and
only its trailing underscore characters need to be removed;
.IP o 
\fIint lookup(bool recovery)\fP: remove this member declaration from the
previously generated parser class;
.IP o 
The following members are declared without a trailing underscore
character in the generated parser class\&. An underscore character should
be added to their identifiers: \fIexecuteAction, errorRecovery, nextToken\fP\&.
.IP o 
The member \fIvoid nextCycle_()\fP must be declared in the private
section of the generated parser class\&.

.PP 
Previously, several data members of the parser\(cq\&s base class were directly
accessible to the parser class\&. \fBBisonc++\fP version 6\&.00\&.00 restricts access to
those members\&.  They can still be read, but no longer modified by the parser
class\&. This applies to the following members:
.IP o 
\fId_token_\fP: use \fIint token_()\fP instead;
.IP o 
\fId_state_\fP: use \fIsize_t state_()\fP instead;

.PP 
.SH "OPTIONS"
Where available, single letter options are listed between parentheses
beyond their associated long\-option variants\&. Single letter options require
arguments if their associated long options also require arguments\&. Options
affecting the class\- or implementation header files are ignored if these
files already exist\&. Options accepting a `filename\(cq\& do not accept path names,
i\&.e\&., they cannot contain directory separators (\fI/\fP); options accepting a
\(cq\&pathname\(cq\& may contain directory separators\&.
.PP 
Some options may cause errors\&. This happens when they conflict with the
contents of a file which \fBbisonc++\fP cannot modify (e\&.g\&., a parser class header file
exists, but doesn\(cq\&t define a namespace, but a \fI\-\-namespace\fP option was
specified)\&.
.PP 
To solve the error the offending option could be omitted; the existing file
could be removed; or the existing file could be hand\-edited according to the
option\(cq\&s specification\&. 
.PP 
Note that \fBbisonc++\fP currently does not handle the opposite error condition: if a
previously used option is omitted, then \fBbisonc++\fP does not report an
inconsistency\&. In those cases compilation errors may be observed\&.
.PP 
.IP o 
\fB\-\-analyze\-only\fP (\fB\-A\fP)
.br 
Only analyze the grammar\&. No files are (re)written\&. This option can
be used to test the grammatic correctness of modification `in
situ\(cq\&, without overwriting previously generated files\&. If the
grammar contains syntactic errors only syntax analysis is 
performed\&.
.IP 
.IP o 
\fB\-\-baseclass\-header\fP=\fIfilename\fP (\fB\-b\fP)
.br 
\fIFilename\fP defines the name of the file to contain the parser\(cq\&s
base class\&. This class defines, e\&.g\&., the parser\(cq\&s symbolic
tokens\&. Defaults to the name of the parser class plus the suffix
\fIbase\&.h\fP\&. It is generated, unless otherwise indicated (see
\fI\-\-no\-baseclass\-header\fP and \fI\-\-dont\-rewrite\-baseclass\-header\fP
below)\&.
.IP 
It is an error if this option is used and an already
existing parser class header file does not contain \fI#include
\(dq\&filename\(dq\&\fP\&.
.IP 
.IP o 
\fB\-\-baseclass\-preinclude\fP=\fIpathname\fP (\fB\-H\fP)
.br 
\fIPathname\fP defines  the path to the file preincluded in the
parser\(cq\&s base\-class header\&. This option is needed in situations
where the base class header file refers to types which might not
yet be known\&. E\&.g\&., with polymorphic semantic values a
\fIstd::string\fP value type might be used\&. Since the \fIstring\fP
header file is not by default included in \fIparserbase\&.h\fP we
somehow need to inform the compiler about this and possibly other
headers\&. The suggested procedure is to use a pre\-include header
file declaring the required types\&. By default `\fIheader\fP\(cq\& is
surrounded by double quotes: \fI#include \(dq\&header\(dq\&\fP is used when
the option \fI\-H header\fP is specified\&.  When the argument is
surrounded by pointed brackets \fI#include <header>\fP is
included\&. In the latter case, quotes might be required to escape
interpretation by the shell (e\&.g\&., using \fI\-H \(cq\&<header>\(cq\&\fP)\&.
.IP 
.IP o 
\fB\-\-baseclass\-skeleton\fP=\fIpathname\fP (\fB\-B\fP)
.br 
\fIPathname\fP defines the path name to the file containing the
skeleton of the parser\(cq\&s base class\&. It defaults to the
installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++base\&.h\fP)\&.
.IP 
.IP o 
\fB\-\-class\-header\fP=\fIfilename\fP (\fB\-c\fP)
.br 
\fIFilename\fP defines the name of the file to contain the parser
class\&. Defaults to the name of the parser class plus the suffix
\fI\&.h\fP
.IP 
It is an error if this option is used and an already
existing implementation header file does not contain \fI#include
\(dq\&filename\(dq\&\fP\&.
.IP 
.IP o 
\fB\-\-class\-name\fP \fIclassName\fP 
.br 
Defines the name of the \fBC++\fP class that is generated\&.  If
neither this option, nor the \fI%class\-name\fP directory is
specified, then the default class name (\fIParser\fP) is used\&.
.IP 
It is an error if this option is used and \fIclassName\fP differs
from the name of the class that is defined in an already existing
parser\-class header file and/or if an already existing
implementation header file does not define members of the class
\fI`className\(cq\&\fP\&.
.IP 
.IP o 
\fB\-\-class\-skeleton\fP=\fIpathname\fP (\fB\-C\fP)
.br 
\fIPathname\fP defines the path name to the file containing the
skeleton of the parser class\&. It defaults to the
installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++\&.h\fP)\&.
.IP 
.IP o 
\fB\-\-construction\fP
.br 
Details about the construction of the parsing tables are written to
the same file as written by the \fI\-\-verbose\fP option (i\&.e\&.,
\fI<grammar>\&.output\fP, where \fI<grammar>\fP is the input file read
by \fBbisonc++\fP)\&. This information is primarily useful for developers\&. It
augments the information written to the verbose grammar output
file, generated by the \fI\-\-verbose\fP option\&.
.IP 
.IP o 
\fB\-\-debug\fP
.br 
Provide the generated \fIparse\fP and its support functions with
debugging code, optionally showing the actual parsing process on
the standard output stream\&. When included, the debugging output is
active by default, but its activity may be controlled using the
\fIsetDebug(bool on\-off)\fP member\&. \fBBisonc++\fP does not use \fI#ifdef
DEBUG\fP macros\&. Rerun \fBbisonc++\fP without the \fI\-\-debug\fP option to
remove the debugging code\&.
.IP 
Note that this option does \fInot\fP show the actions of \fBbisonc++\fP\(cq\&s own
parser, its own lexical scanner or merely the numbers of the
case\-entries executed by the parser\(cq\&s \fIparse\fP function\&. If that
is what you want, use the \fI\-\-own\-debug, \-\-action\-cases,
\-\-scanner\-debug\fP and/or \fI\-\-own\-tokens\fP options\&.
.IP 
When polymorphic semantic values
are used (see section
\fBPOLYMORPHIC SEMANTIC VALUES\fP)
then the generated parser might attempt to retrieve an incorrect
polymorphic value\&. In that case a fatal error is generated, ending
\fBbisonc++\fP\(cq\&s run\&. The error message itself cannot refer to the action
block where the error occurred\&. If this situation is encountered,
rerun \fBbisonc++\fP, specifying \fI\-\-debug\fP and call
\fIparser\&.setDebug(Parser::ACTIONCASES)\fP: as a debugging aid the
generated parser then shows the executeAction switch\(cq\&s case entry
numbers just before their execution\&.
.IP 
.IP o 
\fB\-\-default\-actions\fP=\fIoff|quiet|warn\fP (\fB\-d\fP)
.br 
When \fIwarn\fP is specified (which is the default) an action block
executing \fI$$ = $1\fP (or \fI$$ = STYPE_{}\fP for empty production
rules) is added to production rules that do not explicitly define
their own final action blocks, while issuing a warning\&. When
\fIquiet\fP is specified these action blocks are silently added\&. It
is an error when the types of $$ and $1 differ (but it is OK if
neither $$ nor $1 is associated with a specific type)\&. When
\fIoff\fP is specified no action blocks are added (issuing a warning
unless the option/directive \fItag\-mismatches off\fP has been 
specified)\&.
.IP 
.IP o 
\fB\-\-error\-verbose\fP
.br 
When a syntactic error is reported, the generated parse function
dumps the parser\(cq\&s state stack to the standard output
stream\&. The stack dump shows on separate lines a stack index
followed by the state stored at the indicated stack element\&. The
first stack element is the stack\(cq\&s top element\&.
.IP 
.IP o 
\fB\-\-filenames\fP=\fIfilename\fP (\fB\-f\fP)
.br 
\fIFilename\fP is a generic file name that is used for all header
files generated by \fBbisonc++\fP\&. Options defining specific file names are
also available (which then, in turn, overrule the name specified
by this option)\&.
.IP 
.IP o 
\fB\-\-flex\fP
.br 
\fBBisonc++\fP generates code calling \fId_scanner\&.yylex()\fP to obtain the
next lexical token, and calling \fId_scanner\&.YYText()\fP for the
matched text, unless overruled by options or directives explicitly
defining these functions\&. By default, the interface defined by
\fBflexc++\fP(1) is used\&. This option is only interpreted if the
\fI\-\-scanner\fP option or \fI%scanner\fP directive is also used\&.
.IP 
.IP o 
\fB\-\-help\fP (\fB\-h\fP)
.br 
Write basic usage information to the standard output stream and
terminate\&. 
.IP 
.IP o 
\fB\-\-implementation\-header\fP=\fIfilename\fP (\fB\-i\fP)
.br 
\fIFilename\fP defines the name of the file to contain the
implementation header\&. It defaults to the name of the generated
parser class plus the suffix \fI\&.ih\fP\&.
.IP 
The implementation header should contain all directives and
declarations \fIonly\fP used by the implementations of the parser\(cq\&s
member functions\&. It is the only header file that is included by
the source file containing \fIparse\fP\(cq\&s implementation\&. User
defined implementation of other class members may use the same
convention, thus concentrating all directives and declarations
that are required for the compilation of other source files
belonging to the parser class in one header file\&.
.IP 
.IP o 
\fB\-\-implementation\-skeleton\fP=\fIpathname\fP (\fB\-I\fP)
.br 
\fIPathname\fP defines the path name to the file containing the
skeleton of the implementation header\&. t defaults to the
installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++\&.ih\fP)\&.
.IP 
.IP o 
\fB\-\-insert\-stype\fP
.br 
This option is only effective if the \fIdebug\fP option (or
\fI%debug\fP directive) has been specified\&. When \fIinsert\-stype\fP
has been specified the parsing function\(cq\&s debug output also shows
selected semantic values\&. It should only be used if objects or
variables of the semantic value type \fISTYPE_\fP can be inserted
into \fIostreams\fP\&.
.IP 
.IP o 
\fB\-\-max\-inclusion\-depth\fP=\fIvalue\fP
.br 
Set the maximum number of nested grammar files\&. Defaults to 10\&.
.IP 
.IP o 
\fB\-\-namespace\fP \fIidentifier\fP 
.br 
Define all of the code generated by \fBbisonc++\fP in the namespace
\fIidentifier\fP\&. By default no namespace is defined\&. If this
options is used the implementation header is provided with a
commented out \fIusing namespace\fP declaration for the specified
namespace\&. In addition, the parser and parser base class
header files also use the specified namespace to define their
include guard directives\&.
.IP 
It is an error if this option is used and an already existing
parser\-class header file and/or implementation header file does
not define \fInamespace identifier\fP\&.
.IP 
.IP o 
\fB\-\-no\-baseclass\-header\fP
.br 
Do not write the file containing the parser class\(cq\& base class, even
if that file doesn\(cq\&t yet exist\&. By default the file containing the
parser\(cq\&s base class is (re)written each time \fBbisonc++\fP is called\&. Note
that this option should normally be avoided, as the base class
defines the symbolic terminal tokens that are returned by the
lexical scanner\&. When the construction of this file is suppressed,
modifications of these terminal tokens are not communicated to the
lexical scanner\&.
.IP 
.IP o 
\fB\-\-no\-decoration\fP (\fB\-D\fP)
.br 
Do not include user\-defined or default actions when generating the
parser\(cq\&s \fIparse\fP member\&. This effectively generates a parser
which merely performs syntax checks, without performing the
actions which are normally executed when rules have been
matched\&. This may be useful in situations where a (partially or
completely) decorated grammar is reorganized, and the syntactic
correctness of the modified grammar must be verified, or in
situations where the grammar has already been decorated, but
functions which are called from the rules\(cq\&s actions have not yet
been impleemented\&.
.IP 
.IP o 
\fB\-\-no\-lines\fP
.br 
Do not put \fI#line\fP preprocessor directives in the file containing
the parser\(cq\&s \fIparse\fP function\&. By default the file containing
the parser\(cq\&s \fIparse\fP function also contains \fI#line\fP
preprocessor directives\&. This option allows the compiler and
debuggers to associate errors with lines in your grammar
specification file, rather than with the source file containing
the \fIparse\fP function itself\&.
.IP 
.IP o 
\fB\-\-no\-parse\-member\fP
.br 
Do not write the file containing the parser\(cq\&s predefined parser
member functions, even if that file doesn\(cq\&t yet exist\&. By default
the file containing the parser\(cq\&s \fIparse\fP member function is
(re)written each time \fBbisonc++\fP is called\&. Note that this option
should normally be avoided, as this file contains parsing
tables which are altered whenever the grammar definition is
modified\&. 
.IP 
.IP o 
\fB\-\-own\-debug\fP
.br 
Displays the actions performed by \fBbisonc++\fP\(cq\&s parser when it processes
the grammar specification file(s) (lots of output!)\&. This implies
the \fI\-\-verbose\fP option\&.
.IP 
.IP o 
\fB\-\-own\-tokens\fP (\fB\-T\fP)
.br 
The tokens returned as well as the text matched by \fBbisonc++\fP\(cq\&s lexcial
scanner are shown when this option is used\&.
.IP 
This option does \fInot\fP result in the \fIgenerated\fP parsing
function displaying returned tokens and matched text\&. If that is
what you want, use the \fI\-\-print\-tokens\fP option\&.
.IP 
.IP o 
\fB\-\-parsefun\-skeleton\fP=\fIpathname\fP (\fB\-P\fP)
.br 
\fIPathname\fP defines the path name of the file containing the
parsing member function\(cq\&s skeleton\&. It defaults to the
installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++\&.cc\fP)\&.
.IP 
.IP o 
\fB\-\-parsefun\-source\fP=\fIfilename\fP (\fB\-p\fP)
.br 
\fIFilename\fP defines the name of the source file to contain the
parser member function \fIparse\fP\&. Defaults to \fIparse\&.cc\fP\&.
.IP 
.IP o 
\fB\-\-polymorphic\-code\-skeleton\fP=\fIpathname\fP (\fB\-L\fP)
.br 
\fIPathname\fP defines the path name of the file containing the
non\-template members of the polymorphic Base class\&.  It defaults
to the installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++polymorphic\&.code\fP)\&.
.IP 
.IP o 
\fB\-\-polymorphic\-skeleton\fP=\fIpathame\fP (\fB\-M\fP)
.br 
\fIPathname\fP defines the path name of the file containing the
skeleton of the polymorphic template classes\&. It defaults to the
installation\-defined default path name (e\&.g\&.,
\fI/usr/share/bisonc++/\fP plus \fIbisonc++polymorphic\fP)\&.
.IP 
.IP o 
\fB\-\-print\-tokens\fP (\fB\-t\fP)
.br 
The generated parsing function implements a function \fIprint_\fP
displaying (on the standard output stream) the tokens returned by
the parser\(cq\&s scanner as well as the corresponding matched
text\&. This implementation is suppressed when the parsing function
is generated without using this option\&. The member \fIprint_\fP is
called from \fIParser::print\fP, which is defined in\-line in the the
parser\(cq\&s class header\&. Calling \fIParser::print_\fP can thus easily
be controlled from \fIprint\fP, using, e\&.g\&., a variable that set by
the program using the parser generated by \fBbisonc++\fP\&.
.IP 
This option does \fInot\fP show the tokens returned and text matched
by \fBbisonc++\fP itself when it is reading its input file(s)\&. If
that is what you want, use the \fI\-\-own\-tokens\fP option\&.
.IP 
.IP o 
\fB\-\-prompt\fP
.br 
When adding debugging code (using the \fIdebug\fP option or
directive) the debug information is displayed continuously while
the parser processes its input\&. When using the \fIprompt\fP option
(or directive) the generated parser displays a prompt (a question
mark) at each step of the parsing process\&. Caveat: when using this
option the parser\(cq\&s input cannot be provided at the parser\(cq\&s
standard input stream\&.
.IP 
.IP o 
\fB\-\-required\-tokens\fP=\fInumber\fP
.br 
Following a syntactic error, require at least \fInumber\fP
successfully processed tokens before another syntactic error can
be reported\&. By default \fInumber\fP is zero\&.
.IP 
.IP o 
\fB\-\-scanner\fP=\fIpathname\fP (\fB\-s\fP)
.br 
\fIPathname\fP defines the path name to the file defining the
scanner\(cq\&s class interface (e\&.g\&., \fI\(dq\&\&.\&./scanner/scanner\&.h\(dq\&\fP)\&. When
this option is used the parser\(cq\&s member \fIint lex()\fP is
predefined as
.nf 

    int Parser::lex()
    {
        return d_scanner\&.lex();
    }
                
.fi 
and an object \fIScanner d_scanner\fP is composed into the parser
(but see also option \fIscanner\-class\-name\fP)\&. The example shows
the function that\(cq\&s called by default\&. When the \fI\-\-flex\fP option
(or \fI%flex\fP directive) is specified the function
\fId_scanner\&.yylex()\fP is called\&. Any other function to call can be
specified using the \fI\-\-scanner\-token\-function\fP option (or
\fI%scanner\-token\-function\fP directive)\&.
.IP 
By default \fBbisonc++\fP surrounds \fIpathname\fP by double quotes (using,
e\&.g\&., \fI#include \(dq\&pathname\(dq\&\fP)\&.  When \fIpathname\fP is surrounded
by pointed brackets \fI#include <pathname>\fP is included\&.
.IP 
It is an error if this option is used and an already existing
parser class header file does not include \fI`pathname\(cq\&\fP\&.
.IP 
.IP o 
\fB\-\-scanner\-class\-name\fP \fIscannerClassName\fP 
.br 
Defines the name of the scanner class, declared by the \fIpathname\fP
header file that is specified at the \fIscanner\fP option or 
directive\&. By default the class name \fIScanner\fP is used\&.
.IP 
It is an error if this option is used and either the
\fIscanner\fP option was not provided, or the parser class interface
in an already existing parser class header file does not declare a
scanner class \fId_scanner\fP object\&.
.IP 
.IP o 
\fB\-\-scanner\-debug\fP
.br 
Show de scanner\(cq\&s matched rules and returned tokens\&. This
extensively displays the rules and tokens matched and returned by
\fBbisonc++\fP\(cq\&s scanner, instead of just showing the tokens and matched
text which are received by \fBbisonc++\fP\&. If you want the latter, use the
option \fI\-\-own\-tokens\fP\&.
.IP 
.IP o 
\fB\-\-scanner\-matched\-text\-function\fP=\fIfunction\-call\fP
.br 
The scanner function returning the text that was matched at the
last call of the scanner\(cq\&s token function\&. A complete function
call expression should be provided (including a scanner object, if
used)\&. This option overrules the \fId_scanner\&.matched()\fP call used
by default when the \fI%scanner\fP directive is specified, and it
overrules the \fId_scanner\&.YYText()\fP call used when the \fI%flex\fP
directive is provided\&. Example:
.nf 

    \-\-scanner\-matched\-text\-function \(dq\&myScanner\&.matchedText()\(dq\&
                
.fi 

.IP 
.IP o 
\fB\-\-scanner\-token\-function\fP=\fIfunction\-call\fP
.br 
The scanner function returning the next token, called from the
parser\(cq\&s \fIlex\fP function\&. A complete function
call expression should be provided (including a scanner object, if
used)\&. This option overrules the \fId_scanner\&.lex()\fP call used
by default when the \fI%scanner\fP directive is specified, and it
overrules the \fId_scanner\&.yylex()\fP call used when the \fI%flex\fP
directive is provided\&. Example:
.nf 

    \-\-scanner\-token\-function \(dq\&myScanner\&.nextToken()\(dq\&
                
.fi 

.IP 
It is an error if this option is used and the scanner token
function is not called from the code in an already
existing implementation header\&.
.IP 
.IP o 
\fB\-\-show\-filenames\fP
.br 
Writes the names of the generated files to the standard error
stream\&.
.IP 
.IP o 
\fB\-\-skeleton\-directory\fP=\fIdirectory\fP (\fB\-S\fP)
.br 
Specifies the directory containing the skeleton files\&. In addition
to specifying a common names for the skeleton files the locations
of individual skeleton files can be specified using the options
(\fI\-B \-C, \-H, \-I, \-L\fP and \fI\-M\fP)\&.
.IP 
.IP o 
\fB\-\-stack\-expansion\fP(size)
.br 
Defines the number of elements to be added to the generated
parser\(cq\&s semantic value stack when it must be enlarged\&. By default
10 elements are added to the stack\&. This option/directive is
interpreted only once, and only if \fIsize\fP at least equals the
default stack expansion size of 10\&.
.IP 
.IP o 
\fB\-\-tag\-mismatches\fP \fIoff|on\fP
.br 
When \fIon\fP is specified (which is the default), a warning is
issued if no $$ assignment was detected in an action block, or if
adding a default $$ = \&.\&.\&. action was suppressed (cf\&.  the
\fIdefault\-actions off\fP option or directive)\&.
.IP 
.IP o 
\fB\-\-target\-directory\fP=\fIpathname\fP 
.br 
\fIPathname\fP defines the directory where generated files should be
written\&.  By default this is the directory where \fBbisonc++\fP is
called\&. 
.IP 
.IP o 
\fB\-\-thread\-safe\fP
.br 
Only used with polymorphic semantic values, and then only required
when the parser is used in multiple threads: it ensures that each
thread\(cq\&s polymorphic code only accesses its own parser\(cq\&s error
counting variable\&.
.IP 
.IP o 
\fB\-\-token\-class\fP=\fIclassname\fP (\fB\-K\fP)
.br 
\fIClassname\fP defines the name of the \fITokens\fP class that is
defined when \fItoken\-path\fP (see below) is specified\&. If
\fItoken\-path\fP isn\(cq\&t specified then this option is ignored\&. By
default the class name \fITokens\fP is used\&.
.IP 
.IP o 
\fB\-\-token\-namespace\fP=\fInamespace\fP (\fB\-K\fP)
.br 
If \fItoken\-path\fP is specified (see below) then \fInamespace\fP
defines the namespace of the \fITokens\fP class\&. By default no
namespace is used\&.
.IP 
.IP o 
\fB\-\-token\-path\fP=\fIpathname\fP (\fB\-F\fP)
.br 
\fIPathname\fP defines the path name of the file to contain the
\fIstruct Tokens\fP defining the enumeration \fITokens_\fP containing
the symbolic tokens of the generated grammar\&. If this option is
specified the \fIParserBase\fP class is derived from it, thus making
the tokens available to the generated parser class\&. The name of
the \fIstruct Tokens\fP can be altered using the \fItoken\-class\fP
directive or option\&. By default (if \fItoken_path\fP is not
specified) the tokens are defined as the \fIenum Tokens_\fP in the
\fIParserBase\fP class\&.  If \fIpathname\fP doesn\(cq\&t exist it is created
by \fBbisonc++\fP\&. If the \fIpathname\fP file already exists it is rewritten
at each new run of \fBbisonc++\fP\&.
.IP 
.IP o 
\fB\-\-usage\fP
.br 
Writes basic usage information to the standard output stream and
terminates\&. 
.IP 
.IP o 
\fB\-\-verbose\fP (\fB\-V\fP)
.br 
Writes a file containing verbose descriptions of the parser states
and what is done for each type of look\-ahead token in that state\&.
This file also describes all conflicts detected in the grammar,
both those resolved by operator precedence and those that remain
unresolved\&.  It is not created by default, but if requested the
information is written on \fI<grammar>\&.output\fP, where
\fI<grammar>\fP is the grammar specification file passed to \fBbisonc++\fP\&.
.IP 
.IP o 
\fB\-\-version\fP (\fB\-v\fP)
.br 
Displays \fBbisonc++\fP\(cq\&s version number and terminates\&.
.IP 
.SH "QUICK START"

.PP 
\fBBisonc++\fP may be used as follows:
.IP o 
First, define a grammar\&. The reader is referred to \fBbisonc++\fP\(cq\&s manual and
other sources (like Aho, Sethi and Ullman\(cq\&s book) for details about how to
define and decorate grammars\&.
.IP o 
No `macro style\(cq\& \fI%define\fP declarations are required\&. Instead, the
normal practice of defining class members in source files and declaring them
in class header files can be followed when using \fBbisonc++\fP\&.  \fBBisonc++\fP concentrates on
its main tasks: defining a parser class and implementing the parsing function
\fIint parse\fP, leaving all other parts of the parser class\(cq\& definition to the
programmer\&.
.IP o 
Having defined a grammar and (usually) some directives \fBbisonc++\fP is
run, generating the essential elements of a parser class\&. See the next section
for details about the files generated by \fBbisonc++\fP\&.
.IP o 
Next, members required in addition to the \fBbisonc++\fP\-generated member
\fIparse\fP and its support functions must be implemented by the programmer, and
declared in the parser\(cq\&s class header\&.  At the very least a member \fIint lex\fP
must be defined (a default implementation can be generated by \fBbisonc++\fP)\&.
.IP o 
The generated parser can now be used in a program\&. A very simple
example would be:
.nf 

    int main()
    {
        Parser parser;
        return parser\&.parse();
    }
        
.fi 

.PP 
.SH "GENERATED FILES"

.PP 
\fBBisonc++\fP may create the following files:
.IP o 
A file containing the implementation of the member function \fIparse\fP
and its support functions\&. The member \fIparse\fP is a public member that can be
called to parse a token\-sequence according to a specified LALR1 type of
grammar\&. By default the implementations of these members are written on the
file \fIparse\&.cc\fP\&. The programmer should not modify the contents of this file;
it is rewritten every time \fBbisonc++\fP is called\&.
.IP o 
A file containing an initial setup of the parser class, containing
the declaration of the public member \fIparse\fP and of its (private) support
members\&. New members may safely be declared in the parser class, as it is only
created by \fBbisonc++\fP if not yet existing, using the filename \fI<parser\-class>\&.h\fP
(where \fI<parser\-class>\fP is the the name of the defined parser class)\&.
.IP o 
A file containing the parser class\(cq\& \fIbase class\fP\&. This base
class should not be modified by the programmer\&. It contains types defined by
\fBbisonc++\fP, as well as several (protected) data members and member functions, which
should not be redefined by the programmer\&. All symbolic parser terminal tokens
are defined in this class, thereby escalating these definitions to a separate
class (cf\&. Lakos, (2001)), which in turn prevents circular dependencies
between the lexical scanner and the parser (here, circular dependencies may
easily be encountered, as the parser needs access to the lexical scanner class
when defining the lexical scanner as one of its data members, whereas the
lexical scanner needs access to the parser class to know about the grammar\(cq\&s
symbolic terminal tokens; escalation is a way out of such circular
dependencies)\&. By default this file is (re)written any time \fBbisonc++\fP is called,
using the filename \fI<parser\-class>base\&.h\fP\&.
.IP o 
A file containing an \fIimplementation header\fP\&. The
implementation header rather than the parser\(cq\&s class header file should be
included by the parser\(cq\&s source files implementing member functions declared
by the programmer\&. The implementation header first includes the parser class\(cq\&s
header file, and then provides default in\-line implementations for its members
\fIerror\fP and \fIprint\fP (which may be altered by the programmer)\&. The member
\fIlex\fP may also receive a standard in\-line implementation\&. Alternatively, its
implementation can be provided by the programmer (see below)\&.  Any directives
and/or namespace directives required for the proper compilation of the
parser\(cq\&s additional member functions should be declared next\&. The
implementation header is included by the file defining \fIparse\fP\&. By default
the implementation header is created if not yet existing, receiving the
filename \fI<parser\-class>\&.ih\fP\&.
.IP o 
A verbose description of the generated parser\&. This file is
comparable to the verbose output file originally generated by \fBbison++\fP\&. It
is generated when the option \fI\-\-verbose\fP or \fI\-V\fP is provided\&. If so, \fBbisonc++\fP
writes the file \fI<grammar>\&.output\fP, where \fI<grammar>\fP is the name of the
file containing the grammar definition\&.

.PP 
.SH "FILES"
.IP o 
\fBbisonc++base\&.h\fP: skeleton of the parser\(cq\&s base class;
.IP o 
\fBbisonc++\&.h\fP: skeleton of the parser class;
.IP o 
\fBbisonc++\&.ih\fP: skeleton of the implementation header;
.IP o 
\fBbisonc++\&.cc\fP: skeleton of the member \fIparse\fP;
.IP o 
\fBbisonc++polymorphic\fP: skeleton of the declarations used by
\fI%polymorphic\fP;
.IP o 
\fBbisonc++polymorphic\&.code\fP: skeleton of the non\-inline
implementations of the members declared in \fBbisonc++polymorphic\fP\&.
.IP o 
\fBdebugdecl\&.in\fP: skeleton declaring members of the parser\(cq\&s base
class that are only required when the \fIdebug\fP option or directive
was specified\&.
.IP o 
\fBdebugfunctions1\&.in\fP: skeleton defining the members declared in
\fIdebugdecl\&.in\fP\&.
.IP o 
\fBdebugfunctions2\&.in\fP: skeleton implementing \fIsymbol_\fP, which is
only needed when the \fIprint\-tokens\fP option or directive was
specified\&. 
.IP o 
\fBdebugfunctions3\&.in\fP: skeleton implementing \fIerrorVerbose_\fP,
which is only needed when the \fIerror\-verbose\fP option or directive was
specified\&.
.IP o 
\fBdebugincludes\&.in\fP: skeleton specifying the header files
\fI#include\fP directives that are required  when the \fIdebug\fP option
or directive was specified\&.
.IP o 
\fBdebuglookup\&.in\fP: skeleton containing extra code required in the
\fIParser::lookup\fP member when the \fIdebug\fP option of directive was
specified\&.
.IP o 
\fBlex\&.in\fP: skeleton implementing the \fIParser::lex\fP function\&.
.IP o 
\fBltypedata\&.in\fP: skeleton declaring the location variables
.IP o 
\fBltype\&.in\fP: skeleton defining the default or user defined
\fILTYPE_\fP\&.
.IP o 
\fBprint\&.in\fP: skeleton implementing the actions of \fIParser::print\fP
if the \fIprint\-tokens\fP option or directive was specified\&.

.PP 
.SH "SEE ALSO"
\fBbison\fP(1), \fBbison++\fP(1), 
\fBbisonc++api\fP(3), \fBbisonc++input\fP(7),
\fBbison\&.info\fP (using texinfo),
\fBflexc++\fP(1),
\fBhttps://fbb\-git\&.gitlab\&.io/bisoncpp/\fP
.PP 
Lakos, J\&. (2001) \fBLarge Scale C++ Software Design\fP, Addison Wesley\&.
.br 
Aho, A\&.V\&., Sethi, R\&., Ullman, J\&.D\&. (1986) \fBCompilers\fP, Addison Wesley\&.
.PP 
.SH "BUGS"

.PP 
Parser\-class header files (e\&.g\&., Parser\&.h) and parser\-class internal
header files (e\&.g\&., Parser\&.ih) generated with bisonc++ < 6\&.00\&.00 require
several minor hand\-modifications when re\-generating the parser with \fBbisonc++\fP
>= 6\&.00\&.00\&. See the earlier section \fBFROM BISONC++ < 6\&.00\&.00 TO BISONC++
>= 6\&.00\&.00\fP for details\&.
.PP 
To avoid collisions with names defined by the parser\(cq\&s (base) class, the
following identifiers should not be used as token names:
.IP o 
Identifiers ending in an underscore;
.IP o 
Any of the following identifiers: \fIABORT, ACCEPT, ERROR, 
debug, error\fP, or \fIsetDebug\fP\&.

.PP 
.SH "ABOUT bisonc++"

.PP 
\fBBisonc++\fP was based on \fBbison++\fP, originally developed by Alain
Coetmeur (coetmeur@icdc\&.fr), R&D department (RDT), Informatique\-CDC, France,
who based his work on \fBbison\fP, GNU version 1\&.21\&. 
.PP 
\fBBisonc++\fP version 0\&.98 and beyond is a complete rewrite of an LALR\-1 parser
generator, closely following the construction process as described in Aho,
Sethi and Ullman\(cq\&s (1986) book \fBCompilers\fP (i\&.e\&., the \fIDragon book\fP)\&.  It
uses the same grammar specification as \fBbison\fP and \fBbison++\fP, and it uses
practically the same options and directives as \fBbisonc++\fP versions earlier than
0\&.98\&. Variables, declarations and macros that are obsolete were removed\&. 
.PP 
Compared to \fIbison\fP and \fIbison++\fP, the number and functions of the
various \fI%define\fP declarations was thoroughly modified\&. All of
\fIbison\(cq\&s %define\fP declarations were replaced by their (former) first
arguments\&. Furthermore, `macro\-style\(cq\& declarations are not supported or
required\&. Finally, all directives only use lower\-case characters and do not
contain underscore characters (but sometimes hyphens)\&. E\&.g\&., \fI%define DEBUG\fP
is now declared as \fI%debug\fP; \fI%define LSP_NEEDED\fP is now declared as
\fI%lsp\-needed\fP (note the hyphen)\&.
.PP 
.SH "AUTHOR"

.PP 
Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&.
.PP