DELETEMACRO(file)

NOUSERMACRO(LALR setDebug ParserBase ABORT throw ACCEPT debug error lex print
            parse setLoc api file exceptionHandler)

includefile(../../release.yo)

htmlstyle(body)(color: #27408B; background: #FFFAF0)

whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)

DEFINEMACRO(itx)(0)()
DEFINEMACRO(itemlist)(1)(ARG1)

DEFINEMACRO(bic)(0)(bf(bisonc++))
DEFINEMACRO(b)(0)(bf(bisonc++))
DEFINEMACRO(Bic)(0)(bf(Bisonc++))
DEFINEMACRO(Cpp)(0)(bf(C++))
DEFINEMACRO(prot)(0)(tt((prot)))
DEFINEMACRO(itt)(1)(it() tt(ARG1))

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(bisonc++api)(3)(_CurYrs_)(bisonc++._CurVers_)
        (bisonc++ API)

COMMENT( man-request, larger title )
manpagename(bisonc++)
    (Application programmer's interface of bisonc++ generated classes)

COMMENT( all other: add after () )

manpagesection(DESCRIPTION)

    Bic() derives from bf(bison++)(1), originally derived from
bf(bison)(1). Like these programs bic() generates a parser for an LALR(1)
grammar. Bic() generates bf(C++) code: an expandable bf(C++) class.

Refer to bf(bisonc++)(1) for a general overview. This manual page covers the
application programmer's interface of classes generated by bic(). It contains
the following sections:

    itemization(
    it() bf(DESCRIPTION): this section;
    it() bf(PUBLIC SYMBOLS): constructor, enums, members, and types that can
           be used by calling software;
    it() bf(PRIVATE ENUMS AND -TYPES): enumerations and types only
           available to the tt(Parser) class;
    it() bf(PRIVATE MEMBER FUNCTIONS): member functions that are only
           available to the tt(Parser) class;
    it() bf(PRIVATE DATA MEMBERS): data members that are only available to
           the tt(Parser) class;
    it() bf(TYPES AND VARIABLES IN THE ANONYMOUS NAMESPACE): an overview of
           the types and variables that are used to define and store the
           grammar-tables generated by bic();
    it() bf(SEE ALSO): references to other programs and documentation;
    it() bf(AUTHOR): at the end of this man-page.
    )

    All identifiers ending in an underscore character are reserved for
bic(). 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 (tt(error, exceptionHandler, lex)) 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's internal header file (e.g., tt(Parser.ih)) may not be
redefined or masked by user-provided code.

manpagesection(UNDERSCORES)

    includefile(../manual/underscores.yo)

manpagesection(PUBLIC SYMBOLS)

    includefile(../manual/class/public.yo)
    
manpagesection(PRIVATE ENUMS AND -TYPES)

    includefile(../manual/class/privenum.yo)

manpagesection(PRIVATE MEMBER FUNCTIONS)

    includefile(../manual/class/privmembers.yo)

manpagesection(PRIVATE DATA MEMBERS)

    The following data members can be used by members of parser classes
generated by bic(). All data members are actually protected members inherited
from the parser's base class.
    itemization(
    it() bf(size_t d_acceptedTokens_):nl()
       Counts the number of accepted tokens since the start of the tt(parse())
        function or since the last detected syntactic error. It is initialized
        to tt(d_requiredTokens_) to allow an early error to be detected as
        well. 
    it() bf(bool d_actionCases_):nl()
       When the tt(debug) option has been specified, this variable (tt(false)
        by default) determines whether the number of action block which is
        about to be executed by the parser's member tt(executeAction) will be
        displayed to the standard output stream.
    it() bf(bool d_debug_):nl()
       When the tt(debug) option has been specified, this variable (tt(true)
        by default) determines whether debug information is actually
        displayed.
    it() bf(LTYPE_ d_loc_):nl()
       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 tt(%lsp-needed, %ltype) or tt(%locationstruct) has
        been defined. nl()
       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 tt(d_loc_), tt(d_loc_)'s address should be passed
        to the scanner. This can be realized, for example, by defining a
        member tt(void setLoc(STYPE_ *)) in the lexical scanner, which is
        then called from the parser's constructor as follows:
       verb(
            d_scanner.setSLoc(&d_loc_);
       )
       Subsequently, the lexical scanner may assign a value to the parser's
        tt(d_loc_) variable through the pointer to tt(d_loc_) stored inside
        the lexical scanner.

    it() bf(size_t d_nErrors_):nl()
       The number of errors counted by tt(parse). It is initialized by the
        parser's base class initializer, and is updated while tt(parse)
        executes. When tt(parse) has returned it contains the total number
        of errors counted by tt(parse). Errors are not counted if suppressed
        (i.e., if tt(d_acceptedTokens_) is less than tt(d_requiredTokens_)).

    it() bf(size_t d_requiredTokens_):nl()
       Defines the minimum number of accepted tokens that the tt(parse)
        function must have processed before a syntactic error can be
        generated. 

    it() bf(STYPE_ d_val_):nl()
       The semantic value of a returned token or nonterminal symbol. With
        nonterminal tokens it is assigned a value through the action rule's
        symbol tt($$). 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 tt(d_val_),
        tt(d_val_)'s address should be passed to the scanner. This can be
        realized, for example, by passing tt(d_val_)'s address to the lexical
        scanner's constructor.

       Subsequently, the lexical scanner may assign a value to the parser's
        tt(d_val_) variable through the pointer to tt(d_val_) stored in a
        data member of the lexical scanner.

       Note that in some cases this approach em(must) 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's action only takes place following the
        retrieval of the next token, thus losing the initially matched token
        text. 

       If tt(STYPE) is a polymorphic semantic value, specific requirements for
        assigning values to  tt(d_val_) apply.
        IFDEF(MANUAL)((cf.  section ref(POLYTYPE)))().
    )

manpagesection(BUGS)

    With bic() version 6.00.00 the following members were modified. Where
necessary alternatives are mentioned:

    itemization(
    it() bf(bool Base::debug() const): use the tt(d_debug_) data member;
    it() bf(void error(char const *)): replaced by bf(void error+nop()());
    it() bf(void exceptionHandler_(std::exception const &exc)): omit the final
        underscores: bf(void exceptionHandler(std::exception const
        &exc))
     it() bf(void executeAction+nop()(int)): add one underscore to the
        declaration in the parser class interface: bf(void
        executeAction_+nop()(int))
    it() bf(int lookup+nop()(bool)): omit this member from the parser class
        interface.
    it() bf(void nextCycle_+nop()(int)): add this member declaration to the
        parser class interface.
    it() bf(void nextToken+nop()(int)): add one underscore to the declaration
        in the parser class interface: bf(void nextToken_+nop()(int))

    it() bf(size_t d_nextToken_): removed from the interface.
    it() bf(int d_state_): use tt(state_()).
    it() bf(int d_token_): use tt(token_()).
    it() bf(LTYPE_ d_vsp_): removed from the interface. Use tt(vsp_+nop()())
        instead. 
    )


manpagesection(TYPES AND VARIABLES IN THE ANONYMOUS NAMESPACE)
    
    includefile(../manual/class/anonymous.yo)

manpagesection(SEE ALSO)
    DEFINESYMBOL(manalso)(bf(bisonc++)(1), bf(bisonc++input)(7))
    includefile(seealso.yo)
    
manpageauthor()

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