.TH "bisonc++api" "3" "2005\-2024" "bisonc++\&.6\&.08\&.00" "bisonc++ API" .PP .SH "NAME" bisonc++ \- Application programmer\(cq\&s interface of bisonc++ generated classes .PP .SH "DESCRIPTION" .PP \fBBisonc++\fP derives from \fBbison++\fP(1), originally derived from \fBbison\fP(1)\&. Like these programs \fBbisonc++\fP generates a parser for an LALR(1) grammar\&. \fBBisonc++\fP generates \fBC++\fP code: an expandable \fBC++\fP class\&. .PP Refer to \fBbisonc++\fP(1) for a general overview\&. This manual page covers the application programmer\(cq\&s interface of classes generated by \fBbisonc++\fP\&. It contains the following sections: .PP .IP o \fBDESCRIPTION\fP: this section; .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 All identifiers ending in an underscore character are reserved for \fBbisonc++\fP\&. Member functions ending in an underscore character must not be redefined\&. Data members ending in an underscore character are available in the generated parser class, and may be modified by user\-defined members of the parser class\&. Some members like (\fIerror, exceptionHandler, lex\fP) are defined in the parser class and must remain present, but their implementations may be altered by the user\&. Members for which no default implementation is provided in the parser\(cq\&s internal header file (e\&.g\&., \fIParser\&.ih\fP) may not be redefined or masked by user\-provided code\&. .PP .SH "UNDERSCORES" .PP Starting with version 6\&.02\&.00 \fBbisonc++\fP reserved identifiers no longer end in two underscore characters, but in one\&. This modification was necessary because according to the \fBC++\fP standard identifiers having two or more consecutive underscore characters are reserved by the language\&. In practice this could require some minor modifications of existing source files using \fBbisonc++\fP\(cq\&s facilities, most likely limited to changing \fITokens__\fP into \fITokens_\fP and changing \fIMeta__\fP into \fIMeta_\fP\&. .PP The complete list of affected names is: .IP "Enums:" .RS DebugMode_, ErrorRecovery_, Return_, Tag_, Tokens_ .RE .IP "Enums values:" .RS PARSE_ABORT_, PARSE_ACCEPT_, UNEXPECTED_TOKEN_, sizeofTag_ .RE .IP "Type / namespace designators:" .RS Meta_, PI_, STYPE_ .RE .IP "Member functions:" .RS clearin_, errorRecovery_, errorVerbose_, executeAction_, lex_, lookup_, nextCycle_, nextToken_, popToken_, pop_, print_, pushToken_, push_, recovery_, redoToken_, reduce_, savedToken_, shift_, stackSize_, startRecovery_, state_, token_, top_, vs_, .RE .IP "Protected data members:" .RS d_acceptedTokens_, d_actionCases_, d_debug_, d_nErrors_, d_requiredTokens_, d_val_, idOfTag_, s_nErrors_ .RE .PP .SH "PUBLIC SYMBOLS" .PP Parser classes generated by \fBbisonc++\fP offer the following public constructor, enums, members and types (in the following overview parser class\-name prefixes (e\&.g\&., \fIParser::\fP) prefixes were omitted): .IP o Constructors: the generated parser class merely defines the default constructor\&. Copy and move constructors are not available\&. The default constructor is a real default: it is declared as such in the parser\(cq\&s header file\&. Additional constructors can easily be added to the parser class\(cq\&s interface\&. Since the initialization of the parser\(cq\&s base class is performed by the parser base class\(cq\&s default constructor, constructors that are added to the generated parser class automatically call the base class constructor, so additional constructors do not have to explicitly initialize the parser\(cq\&s base class\&. .IP .IP o \fBDebugMode_\fP: .br The values of this \fIenum\fP are used to configure the type of debug information that will be displayed (assuming that the \fIdebug\fP option/directive was specified when \fBbisonc++\fP generated the parser\(cq\&s code)\&. It has three values: .IP \fIOFF\fP: no debug information is displayed when the generated parser\(cq\&s \fIparse\fP function is called; .IP \fION\fP: extensive debug information about the parsing process is displayed when the generated parser\(cq\&s \fIparse\fP function is called; .IP \fIACTIONCASES\fP: just before executing the grammar\(cq\&s action blocks the action block number is written to the standard output stream\&. These action block numbers refer to case labels of the switch that is defined in the parser\(cq\&s \fIexecuteAction\fP function\&. It is commonly used to find the action block where a fatal semantic value mismatch was observed\&. .IP The \fIbit_or\fP operator can be used to combine \fION\fP and \fIACTIONCASES\fP (see the member function \fIsetDebug(DebugMode_ mode)\fP below)\&. .IP .IP o \fBLTYPE_\fP: .br The parser\(cq\&s location type (user\-definable)\&. Available only when either \fI%lsp\-needed, %ltype\fP or \fI%locationstruct\fP has been declared\&. .IP .IP o \fBSTYPE_\fP: .br The parser\(cq\&s stack\-type (user\-definable), defaults to \fBint\fP\&. .IP .IP o \fBTokens_\fP: .br The enumeration type of all the symbolic tokens defined in the grammar file (i\&.e\&., \fBbisonc++\fP\(cq\&s input file)\&. The scanner should be prepared to return these symbolic tokens\&. Note that, since the symbolic tokens are defined in the parser\(cq\&s class and not in the scanner\(cq\&s class, the lexical scanner must prefix the parser\(cq\&s class name to the symbolic token names when they are returned\&. E\&.g\&., \fIreturn Parser::IDENT\fP should be used rather than \fIreturn IDENT\fP\&. .IP .IP o \fBint parse()\fP: .br The parser\(cq\&s parsing member function\&. It returns 0 when parsing was successfully completed; 1 if errors were encountered while parsing the input\&. .IP .IP o \fBvoid setDebug(bool mode)\fP: .br This member can be used to activate or deactivate the debug\-code compiled into the parsing function\&. It is always defined but is only operational if the \fIdebug\fP directive option was specified when \fBbisonc++\fP generated the \fIparse\fP function\&. If so, it is \fInot\fP active by default; to activate the debug output call \fIsetDebug(true)\fP, to suppress the debug output call \fIsetDebug(false)\fP\&. .IP .IP o \fBvoid setDebug(DebugMode_ mode)\fP: .br This member can also be used to activate or deactivate the debug\-code compiled into the parsing function\&. Like \fIsetDebug(bool)\fP it is always defined but only operational if the \fIdebug\fP directive option was specified when \fBbisonc++\fP generated the \fIparse\fP function\&. If so, it is \fInot\fP active by default; to activate, call \fIsetDebug(Parser::ON), setDebug(Parser::ACTIONCASES)\fP, or \fIsetDebug(Parser::ON | Parser::ACTIONCASES)\fP\&. To suppress the debug code output call \fIsetDebug(Parser_::OFF)\fP or simply \fIsetDebug(false)\fP\&. .PP When the \fI%polymorphic\fP directive is used: .IP o \fBMeta_\fP: .br Templates and classes that are required for implementing the polymorphic semantic values are all declared in the \fIMeta_\fP namespace\&. The \fIMeta_\fP namespace itself is nested under the namespace that may have been declared by the \fI%namespace\fP directive\&. .IP .IP o \fBTag_\fP: .br The (strongly typed) \fIenum class Tag_\fP contains all the tag\-identifiers specified by the \fI%polymorphic\fP directive\&. It is declared outside of the Parser\(cq\&s class, but within the namespace that may have been declared by the \fI%namespace\fP directive\&. .PP .SH "PRIVATE ENUMS AND \-TYPES" .PP The following enumerations and types can be used by members of parser classes generated by \fBbisonc++\fP\&. They are actually protected members inherited from the parser\(cq\&s base class\&. .IP o \fBBase::ErrorRecovery_\fP: .br This enumeration defines one values: .nf UNEXPECTED_TOKEN_ .fi When the parsing process throws \fIUNEXPECTED_TOKEN_\fP the recovery procedure is started (i\&.e\&., it is started whenever a syntactic error is encountered or \fIERROR\fP\fI()\fP is called)\&. .IP The recovery procedure consists of (1) looking for the first state on the state\-stack having an error\-production, followed by (2) handling all state transitions that are possible without retrieving a terminal token\&. Then, in the state requiring a terminal token and starting with the initial unexpected token (3) all subsequent terminal tokens are ignored until a token is retrieved which is a continuation token in that state\&. .IP If the error recovery procedure fails (i\&.e\&., if no acceptable token is ever encountered) error recovery falls back to the default recovery mode: the parsing process terminates\&. .IP .IP o \fBBase::Return_\fP: .br This enumeration defines two values: .nf PARSE_ACCEPT = 0, PARSE_ABORT = 1 .fi (which are also used as the \fIparse\fP function\(cq\&s return values)\&. .PP When the \fI%polymorphic\fP directive is used: .IP o \fBMeta_::sizeofTag_\fP: .br \fIsizeofTag_\fP defines the number of tags that were defined for polymorphic semantic values\&. .PP .SH "PRIVATE MEMBER FUNCTIONS" .PP The following members can be used by members of parser classes generated by \fBbisonc++\fP\&. When prefixed by \fIBase::\fP they are actually protected members inherited from the parser\(cq\&s base class\&. These members are shown below\&. Following the description of those members several more are listed: those members are used during the parsing process, andshould not be modified or masked by user\-defined code\&. .PP .IP o \fBvoid Base::ABORT() const throw(Return_)\fP: .br This member can be called from any member function (called from any of the parser\(cq\&s action blocks) to indicate a failure while parsing thus terminating the parsing function with an error value 1\&. Note that this offers a marked extension and improvement of the macro \fIYYABORT\fP defined by \fBbison++\fP in that \fIYYABORT\fP could not be called from outside of the parsing member function\&. .IP .IP o \fBvoid Base::ACCEPT() const throw(Return_)\fP: .br This member can be called from any member function (called from any of the parser\(cq\&s action blocks) to indicate successful parsing and thus terminating the parsing function\&. Note that this offers a marked extension and improvement of the macro \fIYYACCEPT\fP defined by \fBbison++\fP in that \fIYYACCEPT\fP could not be called from outside of the parsing member function\&. .IP .IP o \fBvoid Base::ERROR() const throw(ErrorRecovery_)\fP: .br This member can be called from any member function (called from any of the parser\(cq\&s action blocks) to generate an error, and results in the parser executing its error recovery code\&. Note that this offers a marked extension and improvement of the macro \fIYYERROR\fP defined by \fBbison++\fP in that \fIYYERROR\fP could not be called from outside of the parsing member function\&. .IP .IP o \fBvoid error()\fP: .br By default implemented inline in the \fIparser\&.ih\fP internal header file, it writes a simple message to the standard error stream\&. It is called when a syntactic error is encountered, and its default implementation may safely be altered\&. .IP .IP o \fBvoid exceptionHandler(std::exception const &exc)\fP: .br This member\(cq\&s default implementation is provided inline in the \fIparser\&.ih\fP internal header file\&. It consists of a mere \fIthrow\fP statement, rethrowing a caught exception\&. .IP The \fIparse\fP member function\(cq\&s body essentially consists of a \fIwhile\fP statement, in which the next token is obtained via the parser\(cq\&s \fIlex\fP member\&. This token is then processed according to the current state of the parsing process\&. This may result in executing actions over which the parsing process has no control and which may result in exceptions being thrown\&. .IP Such exceptions do not necessarily have to terminate the parsing process: they could be thrown by code, linked to the parser, that simply checks for semantic errors (like divisions by zero) throwing exceptions if such errors are observed\&. .IP The member \fIexceptionHandler\fP receives and may handle such exceptions without necessarily ending the parsing process\&. It receives any \fIstd::exception\fP thrown by the parser\(cq\&s actions, as though the action block itself was surrounded by a \fItry \&.\&.\&. catch\fP statement\&. It is of course still possible to use an explicit \fItry \&.\&.\&. catch\fP statement within action blocks\&. However, \fIexceptionHandler\fP can be used to factor out code that is common to various action blocks\&. .IP The next example shows an explicit implementation of \fIexceptionHandler\fP: any \fIstd::exception\fP thrown by the parser\(cq\&s action blocks is caught, showing the exception\(cq\&s message, and increasing the parser\(cq\&s error count\&. After this parsing continues as if no exception had been thrown: .nf void Parser::exceptionHandler(std::exception const &exc) { std::cout << exc\&.what() << \(cq\&\en\(cq\&; ++d_nErrors_; } .fi .IP .IP o \fBint lex()\fP: .br By default implemented inline in the \fIparser\&.ih\fP internal header file, it can be pre\-implemented by \fBbisonc++\fP using the \fIscanner\fP option or directive (see above); alternatively it \fImust\fP be implemented by the programmer\&. It interfaces to the lexical scanner, and should return the next token produced by the lexical scanner, either as a plain character or as one of the symbolic tokens defined in the \fIParser::Tokens_\fP enumeration\&. Zero or negative token values are interpreted as `end of input\(cq\&\&. .IP .IP o \fBvoid print()\fP: .br By default implemented inline in the \fIparser\&.ih\fP internal header file, this member calls \fIprint_\fP to display the last received token and corresponding matched text\&. The \fIprint_\fP member is only implemented if the \fI\-\-print\-tokens\fP option or \fI%print\-tokens\fP directive was used when the parsing function was generated\&. Calling \fIprint_\fP from \fIprint\fP is unconditional, but can easily be controlled by the using program, by defining, e\&.g\&., a command\-line option\&. .IP .IP o \fBsize_t stackSize_() const\fP: .br Returns the current number of elements in the parser\(cq\&s state\-stack\&. .IP .IP o \fBsize_t state_() const\fP: .br Returns the current parsing\-state\&. .IP .IP o \fBbool Base::recovery_() const\fP: .br Returns \fItrue\fP while recovering from a syntax error\&. .IP .IP o \fBint Base::token_() const\fP: .br Returns the currently considered token\&. .PP The following members are required during the parsing process\&. They should not be modified or masked by user\-defined code: .PP .IP o \fBBase::ParserBase()\fP .IP o \fBvoid Base::clearin_()()\fP .IP o \fBvoid errorRecovery_()\fP .IP o \fBvoid Base::errorVerbose_()\fP .IP o \fBvoid executeAction_(int)\fP .IP o \fBint lex_(int token)\fP .IP o \fBint Base::lookup()\fP .IP o \fBLTYPE_ const &lsp_(int) const\fP .br (only available when \fI%lsp\-needed, %ltype\fP or \fI%locationstruct\fP was specified)\&. .IP o \fBvoid nextCycle_()\fP .IP o \fBvoid nextToken_()\fP .IP o \fBvoid Base::pop_()\fP .IP o \fBvoid Base::popToken_()\fP .IP o \fBvoid print_()()\fP .IP o \fBvoid Base::push_()\fP .IP o \fBvoid Base::pushToken_()\fP .IP o \fBvoid Base::shift_(int state)\fP .IP o \fBvoid Base::redoToken_(int rule)\fP .IP o \fBvoid Base::reduce_(int rule)\fP .IP o \fBvoid Base::savedToken_()\fP .IP o \fBvoid Base::symbol_()\fP .IP o \fBvoid Base::startRecovert_()\fP .IP o \fBvoid Base::top_()\fP .IP o \fBint Base::token_() const\fP .IP o \fBvoid Base::vs_(int idx)\fP .PP .SH "PRIVATE DATA MEMBERS" .PP The following data members can be used by members of parser classes generated by \fBbisonc++\fP\&. All data members are actually protected members inherited from the parser\(cq\&s base class\&. .IP o \fBsize_t d_acceptedTokens_\fP: .br Counts the number of accepted tokens since the start of the \fIparse()\fP function or since the last detected syntactic error\&. It is initialized to \fId_requiredTokens_\fP to allow an early error to be detected as well\&. .IP o \fBbool d_actionCases_\fP: .br When the \fIdebug\fP option has been specified, this variable (\fIfalse\fP by default) determines whether the number of action block which is about to be executed by the parser\(cq\&s member \fIexecuteAction\fP will be displayed to the standard output stream\&. .IP o \fBbool d_debug_\fP: .br When the \fIdebug\fP option has been specified, this variable (\fItrue\fP by default) determines whether debug information is actually displayed\&. .IP o \fBLTYPE_ d_loc_\fP: .br The location type value associated with a terminal token\&. It can be used by, e\&.g\&., lexical scanners to pass location information of a matched token to the parser in parallel with a returned token\&. It is available only when \fI%lsp\-needed, %ltype\fP or \fI%locationstruct\fP has been defined\&. .br Lexical scanners may be offered the facility to assign a value to this variable in parallel with a returned token\&. In order to allow a scanner access to \fId_loc_\fP, \fId_loc_\fP\(cq\&s address should be passed to the scanner\&. This can be realized, for example, by defining a member \fIvoid setLoc(STYPE_ *)\fP in the lexical scanner, which is then called from the parser\(cq\&s constructor as follows: .nf d_scanner\&.setSLoc(&d_loc_); .fi Subsequently, the lexical scanner may assign a value to the parser\(cq\&s \fId_loc_\fP variable through the pointer to \fId_loc_\fP stored inside the lexical scanner\&. .IP .IP o \fBsize_t d_nErrors_\fP: .br The number of errors counted by \fIparse\fP\&. It is initialized by the parser\(cq\&s base class initializer, and is updated while \fIparse\fP executes\&. When \fIparse\fP has returned it contains the total number of errors counted by \fIparse\fP\&. Errors are not counted if suppressed (i\&.e\&., if \fId_acceptedTokens_\fP is less than \fId_requiredTokens_\fP)\&. .IP .IP o \fBsize_t d_requiredTokens_\fP: .br Defines the minimum number of accepted tokens that the \fIparse\fP function must have processed before a syntactic error can be generated\&. .IP .IP o \fBSTYPE_ d_val_\fP: .br The semantic value of a returned token or nonterminal symbol\&. With nonterminal tokens it is assigned a value through the action rule\(cq\&s symbol \fI$$\fP\&. Lexical scanners may be offered the facility to assign a semantic value to this variable in parallel with a returned token\&. In order to allow a scanner access to \fId_val_\fP, \fId_val_\fP\(cq\&s address should be passed to the scanner\&. This can be realized, for example, by passing \fId_val_\fP\(cq\&s address to the lexical scanner\(cq\&s constructor\&. .IP Subsequently, the lexical scanner may assign a value to the parser\(cq\&s \fId_val_\fP variable through the pointer to \fId_val_\fP stored in a data member of the lexical scanner\&. .IP Note that in some cases this approach \fImust\fP be used to make the correct semantic value available to the parser\&. In particular, when a grammar state defines multiple reductions, depending on the next token, the reduction\(cq\&s action only takes place following the retrieval of the next token, thus losing the initially matched token text\&. .IP If \fISTYPE\fP is a polymorphic semantic value, specific requirements for assigning values to \fId_val_\fP apply\&. \&. .PP .SH "BUGS" .PP With \fBbisonc++\fP version 6\&.00\&.00 the following members were modified\&. Where necessary alternatives are mentioned: .PP .IP o \fBbool Base::debug() const\fP: use the \fId_debug_\fP data member; .IP o \fBvoid error(char const *)\fP: replaced by \fBvoid error()\fP; .IP o \fBvoid exceptionHandler_(std::exception const &exc)\fP: omit the final underscores: \fBvoid exceptionHandler(std::exception const &exc)\fP .IP o \fBvoid executeAction(int)\fP: add one underscore to the declaration in the parser class interface: \fBvoid executeAction_(int)\fP .IP o \fBint lookup(bool)\fP: omit this member from the parser class interface\&. .IP o \fBvoid nextCycle_(int)\fP: add this member declaration to the parser class interface\&. .IP o \fBvoid nextToken(int)\fP: add one underscore to the declaration in the parser class interface: \fBvoid nextToken_(int)\fP .IP .IP o \fBsize_t d_nextToken_\fP: removed from the interface\&. .IP o \fBint d_state_\fP: use \fIstate_()\fP\&. .IP o \fBint d_token_\fP: use \fItoken_()\fP\&. .IP o \fBLTYPE_ d_vsp_\fP: removed from the interface\&. Use \fIvsp_()\fP instead\&. .PP .SH "TYPES AND VARIABLES IN THE ANONYMOUS NAMESPACE" .PP In the file defining the \fIparse\fP function the following types and variables are defined in the anonymous namespace\&. These are mentioned here for the sake of completeness, and are not normally accessible to other parts of the parser\&. .PP .IP o \fBchar const author[]\fP: .br Defining the name and e\-mail address of \fBBisonc++\fP\(cq\&s author\&. .IP .IP o \fBReserved_\fP: .br This enumeration defines some token values used internally by the parsing functions\&. They are: .nf UNDETERMINED_ = \-2, EOF_ = \-1, errTok_ = 256, .fi These tokens are used by the parser to determine whether another token should be requested from the lexical scanner, and to handle error\-conditions\&. .IP .IP o \fBStateType\fP: .br This enumeration defines several additional token values used internally by the parsing functions\&. They are: .nf NORMAL, ERR_ITEM, REQ_TOKEN, ERR_REQ, // ERR_ITEM | REQ_TOKEN DEF_RED, // state having default reduction ERR_DEF, // ERR_ITEM | DEF_RED REQ_DEF, // REQ_TOKEN | DEF_RED ERR_REQ_DEF // ERR_ITEM | REQ_TOKEN | DEF_RED .fi These tokens are used by the parser to define the types of the various states of the analyzed grammar\&. .IP .IP o \fBStateTransition\fP This enumeration only defines a single symbolic constant: \fIACCEPT_\fP, which is used in the state transition tables to indicate that the \fIaccepting state\fP has been reached\&. .IP .IP o \fBPI_\fP (Production Info): .br This \fIstruct\fP provides information about production rules\&. It has two fields: \fId_nonTerm\fP is the identification number of the production\(cq\&s nonterminal, \fId_size\fP represents the number of elements of the productin rule\&. .IP .IP o \fBstatic PI_ s_productionInfo\fP: .br Used internally by the parsing function\&. .IP .IP o \fBSR_\fP (Shift\-Reduce Info): .br This \fIstruct\fP provides the shift/reduce information for the various grammatic states\&. \fISR_\fP values are collected in arrays, one array per grammatic state\&. These array, named \fIs_\fP\fI\fP, where tt is a state number are defined in the anonymous namespace as well\&. The \fISR_\fP elements consist of two unions, defining fields that are applicable to, respectively, the first, intermediate and the last array elements\&. .br The first element of each array consists of (1st field) a \fIStateType\fP and (2nd field) the index of the last array element; intermediate elements consist of (1st field) a symbol value and (2nd field) (if negative) the production rule number reducing to the indicated symbol value or (if positive) the next state when the symbol given in the 1st field is the current token; the last element of each array consists of (1st field) a placeholder for the current token and (2nd field) the (negative) rule number to reduce to by default or the (positive) number of an error\-state to go to when an erroneous token has been retrieved\&. If the 2nd field is zero, no error or default action has been defined for the state, and error\-recovery is attepted\&. .IP .IP o \fBSTACK_EXPANSION_\fP: .br An enumeration value specifying the number of additional elements that are added to the state\- and semantic value stacks when full\&. .IP .IP o \fBstatic SR_ s_[]\fP: .br Here, \fI\fP is a numerical value representing a state number\&. Used internally by the parsing function\&. .IP .IP o \fBstatic SR_ *s_state[]\fP: .br Used internally by the parsing function\&. .PP .SH "SEE ALSO" \fBbison\fP(1), \fBbison++\fP(1), \fBbisonc++\fP(1), \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 "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&.