NOUSERMACRO(yyparse parse lex yylex error setDebug ParserBase throw ACCEPT
        ABORT errok RECOVERING print done prompt Parse yyrestart YYText
        debug setSval setLoc matched specification tag files member)

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(tr)(3)(\
    row(cell(ARG1)cell()\
        cell(ARG2)cell()\
        cell(ARG3)))


DEFINEMACRO(bic)(0)(bf(bisonc++))
DEFINEMACRO(Bic)(0)(bf(Bisonc++))
DEFINEMACRO(Cpp)(0)(bf(C++))
DEFINEMACRO(prot)(0)(tt((prot)))

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

COMMENT( man-request, section, date, distribution file, general name)
manpage(bisonc++)(1)(_CurYrs_)(bisonc++._CurVers_.tar.gz)
        (bisonc++ parser generator)

COMMENT( man-request, larger title )
manpagename(bisonc++)(Generate a C++ parser class and parsing function)

COMMENT( all other: add after () )
manpagesynopsis()
       bf(bisonc++) [OPTIONS] tt(grammar-file)

manpagesection(SECTIONS)
    This manual page contains the following sections:
    description(
    dit(1. DESCRIPTION) overview and short history of of bic();
    dit(2. GENERATED FILES) files bic() may generate;
    dit(3. OPTIONS) Bic()'s command-line options;
    dit(4. DIRECTIVES) Bic()'s grammar-specification directives;
    dit(5. POLYMORPHIC SEMANTIC VALUES) How to use polymorphic semantic values
       in parsers generated by bic();
    dit(6. PUBLIC MEMBERS AND -TYPES) Members and types that can be used by
        calling software;
    dit(7. PRIVATE ENUMS AND -TYPES) Enumerations and types only available
        to the tt(Parser) class;
    dit(8. PRIVATE MEMBER FUNCTIONS) Member functions that are only available
        to the tt(Parser) class;
    dit(9. PRIVATE DATA MEMBERS) Data members that are only available
        to the tt(Parser) class;
    dit(10. 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();
    dit(11. RESTRICTIONS ON TOKEN NAMES) Name restrictions for user-defined
        symbols;
    dit(12. OBSOLETE SYMBOLS) Symbols available to bf(bison)(1), but not to
        bic();
    dit(13. EXAMPLE) Guess what this is?
    dit(14. USING PARSER-CLASS SYMBOLS IN LEXICAL SCANNERS) How to refer to
        tt(Parser) tokens from within a lexical scanner;
    dit(15. FILES) (Skeleton) files used by bic();
    dit(16. SEE ALSO) References to other programs and documentation;
    dit(17. BUGS) Some additional stuff that should not qualify as bugs.
    dit(18. ABOUT bisonc++) More history;
    dit(AUTHOR) At the end of this man-page.
    )

    Looking for a specific section? Search for its number + a dot.

manpagesection(1. DESCRIPTION)

    Bic() derives from previous work on bf(bison) by Alain Coetmeur
(coetmeur@icdc.fr), who created in the early '90s a Cpp() class encapsulating
the tt(yyparse) function as generated by the GNU-bf(bison) parser generator.

    Initial versions of bic() (up to version 0.92) wrapped Alain's program in
a program offering a more modern user-interface, removing all old-style
(bf(C)) tt(%define) directives from bf(bison++)'s input specification file
(see below for an in-depth discussion of the differences between bf(bison++)
and bic()). Starting with version 0.98, bic() represents a complete rebuilt of
the parser generator, closely following descriptions given in Aho, Sethi and
Ullman's em(Dragon Book). Since version 0.98 bic() is a Cpp() program, rather
than a bf(C) program generating bf(C++) code.

    Bic() expands the concepts initially implemented in bf(bison) and
bf(bison++), offering a cleaner setup of the generated parser class. The
parser class is derived from a base-class, mainly containing the parser's
token- and type-definitions as well as several member functions which should
not be modified by the programmer. 

    Most of these base-class members might also be defined directly in the
parser class, but were defined in the parser'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 bic() itself (e.g., the
member function tt(parse) as well as some support functions requiring access
to facilities that are only available in the parser class itself, rather than
in the parser's base class).  

    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.

    In fact, there are only two public members in the parser class generated
by bic(): tt(setDebug) (see below) and tt(parse). Remaining members are
private, and those that can be redefined by the programmer using bic() usually
receive initial, very simple default in-line implementations. The (partial)
exception to this rule is the member function tt(lex), producing the next
lexical token. For tt(lex) either a standardized interface or a mere
declaration is offered (requiring the programmer to provide his/her own 
tt(lex) implementation).

    To enforce a primitive namespace, bf(bison) used a well-known
naming-convention: all its public symbols started with tt(yy) or tt(YY).
bf(Bison++) followed bf(bison) in this respect, even though a class by itself
offers enough protection of its identifiers. Consequently, these tt(yy) and
tt(YY) conventions are now outdated, and bic() does not generate or use
symbols defined in either the parser (base) class or in its member functions
starting with tt(yy) or tt(YY). Instead, following a suggestion by Lakos
(2001), all data members start with tt(d_), and all static data members start
with tt(s_). This convention was not introduced to enforce identifier
protection, but to clarify the storage type of variables. Other (local)
symbols lack specific prefixes. Furthermore, bic() allows its users to define
the parser class in a particular namespace of their own choice.

    Bic() should be used as follows:
    itemization(
    it() As usual, a grammar must be defined. With bic() this is not
different, and the reader is referred to bic()'s manual and other sources
(like Aho, Sethi and Ullman's book) for details about how to specify and
decorate grammars.
    it() The number and function of the various tt(%define) declarations as
used by bf(bison++), however, is greatly modified. Actually, all of
bf(bison)'s tt(%define) declarations were replaced by their (former) first
arguments. Furthermore, `macro-style' declarations are no longer supported or
required. Finally, all directives use lower-case characters only and do not
contain underscore characters (but sometimes hyphens). E.g., tt(%define DEBUG)
is now declared as tt(%debug); tt(%define LSP_NEEDED) is now declared as
tt(%lsp-needed) (note the hyphen).
    it() As noted, no `macro style' tt(%define) declarations are required
anymore. Instead, the normal practice of defining class members in source
files and declaring them in a class header files can be adhered to using
bic().  Basically, bic() concentrates on its main tasks: defining a
parser class and implementing its parsing function tt(int parse),
leaving all other parts of the parser class' definition to the programmer.
    it() Having specified the grammar and (usually) some directives bic() is
able to generate files defining the parser class and to implement the
member function tt(parse) and its support functions. See the next section
for details about the various files that may be generated by bic().
    it() All members (except for the member tt(parse) and its support
functions) must be implemented by the programmer. Additional member functions
should be declared in the parser class' header.  At the very least the member
tt(int lex()) em(must) be implemented (although a standard implementation
can be generated by bic()). The member tt(lex) is called by tt(parse) to
obtain the next available token. The member function tt(void error(char const
*msg)) may also be re-implemented by the programmer, and a basic in-line
implementation is provided by default. The member function tt(error) is called
when tt(parse) detects (syntactic) errors.
    it() The parser can now be used in a program. A very simple example would
be: 
        verb(
    int main()
    {
        Parser parser;
        return parser.parse();
    }
        )
    )

    manpagesection(2. GENERATED FILES)

    Bic() may create the following files:
    itemization(
    it() A file containing the implementation of the member function tt(parse)
and its support functions. The member tt(parse) 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 tt(parse.cc). The programmer should not modify the contents of this file;
it is rewritten every time bic() is called.
    it() A file containing an initial setup of the parser class, containing
the declaration of the public member tt(parse) and of its (private) support
members. New members may safely be declared in the parser class, as it is only
created by bic() if not yet existing, using the filename tt(<parser-class>.h)
(where tt(<parser-class>) is the the name of the defined parser class).
        it() A file containing the parser class' em(base class). This base
class should not be modified by the programmer. It contains types defined by
bic(), 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's
symbolic terminal tokens; escalation is a way out of such circular
dependencies). By default this file is (re)written any time bic() is called,
using the filename tt(<parser-class>base.h).
        it() A file containing an em(implementation header). The
implementation header rather than the parser's class header file should be
included by the parser's source files implementing member functions declared
by the programmer. The implementation header first includes the parser class's
header file, and then provides default in-line implementations for its members
tt(error) and tt(print) (which may be altered by the programmer). The member
tt(lex) 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's additional member functions should be declared next. The
implementation header is included by the file defining tt(parse). By default
the implementation header is created if not yet existing, receiving the
filename tt(<parser-class>.ih).
        it() A verbose description of the generated parser. This file is
comparable to the verbose ouput file originally generated by bf(bison++). It
is generated when the option tt(--verbose) or tt(-V) is provided. If so, bic()
writes the file tt(<grammar>.output), where tt(<grammar>) is the name of the
file containing the grammar definition.
        )

manpagesection(3. OPTIONS)
    includefile(../manual/invoking/options.yo)

manpagesection(4. DIRECTIVES)

    The following directives can be specified in the initial section of the
grammar specification file. When command-line options for directives exist,
they overrule the corresponding directives given in the grammar specification
file.  Directives affecting the class header or implementation header file are
ignored if these files already exist.

    Directives accepting a `filename' do not accept path names, i.e., they
cannot contain directory separators (tt(/)); directives accepting a 'pathname'
may contain directory separators. A 'pathname' using blank characters should
be surrounded by double quotes.

Some directives may generate errors. This happens when a directive
conflicts with the contents of a file which bic() cannot modify (e.g., a
parser class header file exists, but doesn't define a name space, but a
tt(%namespace) directive was provided). 

To solve such errore the offending directive could be omitted, the existing
file could be removed, or the existing file could be hand-edited according to
the directive's specification.


    itemization(
    it() bf(%baseclass-header) tt(filename) nl()
           tt(Filename) defines the name of the file to contain the parser's
            base class. This class defines, e.g., the parser's symbolic
            tokens. Defaults to the name of the parser class plus the suffix
            tt(base.h). This directive is overruled by the
            bf(--baseclass-header) (bf(-b)) command-line option.

           It is an error if this directive is used and an already
            existing parser class header file does not contain tt(#include
            "filename").
    it() bf(%baseclass-preinclude) tt(pathname)nl()
           tt(Pathname) defines the path to the file preincluded by the
            parser's base-class header.  See the description of the
            tt(--baseclass-preinclude) option for details about this
            directive.  By default, bic() surrounds tt(header) by double
            quotes.  However, when tt(header) itself is surrounded by pointed
            brackets tt(#include <header>) is included.
    it() bf(%class-header) tt(filename) nl()
           tt(Filename) defines the name of the file to contain the parser
            class. Defaults to the name of the parser class plus the suffix
            tt(.h) This directive is overruled by the bf(--class-header)
            (bf(-c)) command-line option.

           It is an error if this directive is used and an already
            existing implementation header file does not contain tt(#include
            "filename").
    it() bf(%class-name) tt(parser-class-name) nl()
           Declares the name of the parser class. It defines the name of the
            bf(C++) class that is generated. If no tt(%class-name) is
            specified the default class name tt(Parser) is used.

           It is an error if this directive is used and an already
            existing parser-class header file does not define tt(class
            `className') and/or if an already existing implementation header
            file does not define members of the class tt(`className').
    it() bf(%debug) nl() 
           Provide tt(parse) and its support functions with debugging code,
            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 tt(setDebug(bool
            on-off)) member. No tt(#ifdef DEBUG) macros are used anymore. To
            remove existing debugging code re-run bic() without the
            tt(--debug) option or tt(%debug) declaration.
    it() bf(%error-verbose) nl()    
           This directive can be specified to dump the parser's state stack to
            the standard output stream when the parser encounters a syntactic
            error.  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's top element.
    it() bf(%expect) tt(number) nl()    
           This directive specifies the exact number of shift/reduce and
            reduce/reduce conflicts for which no warnings are to be
            generated. Details of the conflicts are reported in the verbose
            output file (e.g., tt(grammar.output)). If the number of actually
            encountered conflicts deviates from `tt(number)', then this
            directive is ignored.
    it() bf(%filenames) tt(filename) nl()
           tt(Filename) is a generic filename that is used for all header
            files generated by bic().  Options defining specific filenames are
            also available (which then, in turn, overrule the name specified
            by this directive).  This directive is overruled by the
            bf(--filenames) (bf(-f)) command-line option.
    it() bf(%flex) nl()
           When provided, the scanner member returning the matched text is
            called as tt(d_scanner.YYText()), and the scanner member returning
            the next lexical token is called as tt(d_scanner.yylex()). This
            directive is only interpreted if the tt(%scanner) directive is
            also provided.
    it() bf(%implementation-header) tt(filename) nl()
           tt(Filename) defines the name of the file to contain the
            implementation header. It defaults to the name of the generated
            parser class plus the suffix tt(.ih). nl()
           The implementation header should contain all directives and
            declarations that are em(only) used by the parser's member
            functions. It is the only header file that is included by the
            source file containing tt(parse)'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.nl()
           This directive is overruled by the
            bf(--implementation-header) (bf(-i)) command-line option.
    it() bf(%include) tt(pathname) nl() 
           This directive is used to switch to tt(pathname) while processing a
            grammar specification. Unless tt(pathname) defines an absolute
            file-path, tt(pathname) is searched relative to the location of
            bic()'s main grammar specification file (i.e., the grammar file
            that was specified as bic()'s command-line option). This directive
            can be used to split long grammar specification files in shorter,
            meaningful units. After processing tt(pathname) processing
            continues beyond the tt(%include pathname) directive.
    it() bf(%left) tt(terminal ...) nl() 
           Defines the names of symbolic terminal tokens that must be treated
            as left-associative. I.e., in case of a shift/reduce conflict, a
            reduction is preferred over a shift.  Sequences of tt(%left,
            %nonassoc, %right) and tt(%token) directives may be used to define
            the precedence of operators. In expressions, the first used
            directive defines the tokens having the lowest precedence, the
            last used defines the tokens having the highest priority. See also
            tt(%token) below.
    it() bf(%locationstruct) tt(struct-definition) nl() 
           Defines the organization of the location-struct data type
            tt(LTYPE__). This struct should be specified analogously to the
            way the parser's stacktype is defined using tt(%union) (see
            below). The location struct is named tt(LTYPE__). By default (if
            neither tt(locationstruct) nor tt(LTYPE__) is specified) the
            standard location struct (see the next directive) is used:
    it() bf(%lsp-needed) nl()    
           This directive results in bic() generating a parser using 
            the standard location stack.  This stack's default type is:
           verb(
    struct LTYPE__
    {
        int timestamp;
        int first_line;
        int first_column;
        int last_line;
        int last_column;
        char *text;
    };
           )
           Bic() does em(not) provide the elements of the tt(LTYPE__) struct
            with values. Action blocks of production rules may refer to the
            location stack element associated with a production element using
            tt(@) variables, like tt(@1.timestamp, @3.text, @5). The rule's
            location struct itself may be referred to as either tt(d_loc__) or
            tt(@@).
    it() bf(%ltype typename) nl()    
           Specifies a user-defined token location type. 
           If tt(%ltype) is used, tt(typename) should be the name of an
            alternate (predefined) type (e.g., tt(size_t)). It should not be
            used if a tt(%locationstruct) specification is defined (see
            below). Within the parser class, this type is available as the
            type `tt(LTYPE__)'.  All text on the line following tt(%ltype)
            is used for the tt(typename) specification. It should therefore
            not contain comment or any other characters that are not part of
            the actual type definition.
    it() bf(%namespace) tt(namespace) nl()
           Define all of the code generated by bic() in the name space
            tt(namespace). By default no name space is defined. If this
            directive is used the implementation header is provided with a
            commented out tt(using namespace) declaration for the specified
            name space. In addition, the parser and parser base class
            header files also use the specified namespace to define their
            include guard directives.

           It is an error if this directive is used and an already
            existing parser-class header file and/or implementation header
            file does not define tt(namespace identifier).
    it() bf(%negative-dollar-indices) nl()
           Do not generate warnings when zero- or negative dollar-indices are
            used in the grammar's action blocks. Zero or negative
            dollar-indices are commonly used to implement inherited
            attributes, and should normally be avoided. When used, they can be
            specified like tt($-1), or like tt($<type>-1), where tt(type) is
            empty; an tt(STYPE__) tag; or a field-name. However, note that in
            combination with the tt(%polymorphic) directive (see below) only
            the tt($-i) format can be used.
    it() bf(%no-lines) nl() 
           By default tt(#line) preprocessor directives are inserted just
            before action statements in the file containing the parser's
            tt(parse) function. These directives are suppressed by the
            tt(%no-lines) directive.
    it() bf(%nonassoc) tt(terminal ...) nl() Defines the names of symbolic
            terminal tokens that should be treated as non-associative. I.e.,
            in case of a shift/reduce conflict, a reduction is preferred over
            a shift.  Sequences of tt(%left, %nonassoc, %right) and tt(%token)
            directives may be used to define the precedence of operators.  In
            expressions, the first used directive defines the tokens having
            the lowest precedence, the last used defines the tokens having the
            highest priority. See also tt(%token) below.
    it() bf(%parsefun-source) tt(filename) nl()
           tt(Filename) defines the name of the file to contain the parser
            member function tt(parse). Defaults to tt(parse.cc).  This
            directive is overruled by the bf(--parse-source) (bf(-p))
            command-line option.
    it() bf(%polymorphic) tt(polymorphic-specification(s))nl()
           Bison's traditional way of handling multiple semantic values is to
            use a tt(%union) specification (see below). Although tt(%union) is
            supported by bic(), a polymorphic semantic value class is
            preferred due to its improved type safety.

            The tt(%polymorphic) directive defines a polymorphic semantic
            value class and can be used instead of a tt(%union)
            specification. Refer to section bf(POLYMORPHIC SEMANTIC VALUES)
            below or to bic()'s user manual for a detailed description of the
            specification, characteristics, and use of polymorphic semantic
            values.
    it() bf(%prec) tt(token) nl() 
           Overrules the defined precendence of an operator for a particular
            grammatical rule. A well known application of tt(%prec) is:
                verb(
    expression:
        '-' expression %prec UMINUS
        {
            ...
        }
                )
            Here, the default priority and precedence of the `tt(-)' token as
            the subtraction operator is overruled by the precedence and
            priority of the tt(UMINUS) token, which is commonly defined as 
                verb(
    %right UMINUS
                )
            (see below) following, e.g., the tt('*') and tt('/') operators.
    it() bf(%print-tokens) nl()
           The tt(print) directive provides an implementation of the Parser
            class's tt(print__) function displaying the current token value
            and the text matched by the lexical scanner as received by the
            generated tt(parse) function.
    it() bf(%required-tokens) tt(number)nl()
           Following a syntactic error, require at least tt(number)
            successfully processed tokens before another syntactic error can
            be reported. By default tt(number) is zero.
    it() bf(%right) tt(terminal ...) nl() 
           Defines the names of symbolic terminal tokens that should be
            treated as right-associative. I.e., in case of a shift/reduce
            conflict, a shift is preferred over a reduction.  Sequences of
            tt(%left, %nonassoc, %right) and tt(%token) directives may be used
            to define the precedence of operators.  In expressions, the first
            used directive defines the tokens having the lowest precedence,
            the last used defines the tokens having the highest priority. See
            also tt(%token) below.
    it() bf(%scanner) tt(pathname)nl()
           Use tt(pathname) as the path name to the file pre-included in the
            parser's class header. See the description of the tt(--scanner)
            option for details about this directive.  Similar to the convention
            adopted for this argument, tt(pathname) by default is surrounded
            by double quotes.  However, when the argument is surrounded by
            pointed brackets tt(#include <pathname>) is included. This
            directive results in the definition of a composed tt(Scanner
            d_scanner) data member into the generated parser, and in the
            definition of a tt(int lex()) member, returning
            tt(d_scanner.lex()).

            By specifying the tt(%flex) directive the function
            tt(d_scanner.yylex()) is called. Any other function to call can be
            specified using the tt(--scanner-token-function) option (or
            tt(%scanner-token-function) directive).

           It is an error if this directive is used and an already
            existing parser class header file does not include tt(`pathname').
    it() bf(%scanner-class-name) tt(scannerClassName) nl() 
           Defines the name of the scanner class, declared by the tt(pathname)
            header file that is specified at the tt(scanner) option or 
            directive. By default the class name tt(Scanner) is used.

           It is an error if this directive is used and either the
            tt(scanner) directive was not provided, or the parser class
            interface in an already existing parser class header file does not
            declare a scanner class tt(d_scanner) object.
    it() bf(%scanner-matched-text-function) tt(function-call) nl() 
           The scanner function returning the text that was matched by the
            lexical scanner after its token function (see below) has
            returned. A complete function call expression should be provided
            (including a scanner object, if used).  Example: 
                verb(
    %scanner-matched-text-function myScanner.matchedText()
                )
           By specifying the tt(%flex) directive the function
            tt(d_scanner.YYText()) is called.

           If the function call contains white space
            tt(scanner-token-function) should be surrounded by double quotes.
    it() bf(%scanner-token-function) tt(function-call) nl() 
           The scanner function returning the next token, called from the
            generated parser's tt(lex) function. A complete function
            call expression should be provided (including a scanner object, if
            used). Example: 
            verb(
    %scanner-token-function d_scanner.lex()
                )
           If the function call contains white space
            tt(scanner-token-function) should be surrounded by double quotes.

           It is an error if this directive is used and the scanner token
            function is not called from the code in an already
            existing implementation header.
    it() bf(%start) tt(non-terminal) nl()    
            The non-terminal tt(non-terminal) should be used as the grammar's 
            start-symbol. If omitted, the first grammatical rule is used
            as the grammar's starting rule. All syntactically correct
            sentences must be derivable from this starting rule.
    it() bf(%stype typename) nl() 
           The type of the semantic value of non-terminal tokens.  By default
            it is tt(int). tt(%stype, %union,) and tt(%polymorphic) are
            mutually exclusive directives.   

           Within the parser class, the semantic value type is available as
            the type `tt(STYPE__)'. All text on the line following tt(%stype)
            is used for the tt(typename) specification. It should therefore
            not contain comment or any other characters that are not part of
            the actual type definition.
    it() bf(%target-directory pathname) nl() 
           tt(Pathname) defines the directory where generated files should be
            written.  By default this is the directory where bic() is
            called. This directive is overruled by the tt(--target-directory)
            command-line option.
    it() bf(%token) tt(terminal ...) nl()    
           Defines the names of symbolic terminal tokens.  Sequences of
            tt(%left, %nonassoc, %right) and tt(%token) directives may be used
            to define the precedence of operators. In expressions, the first
            used directive defines the tokens having the lowest precedence,
            the last used defines the tokens having the highest priority. See
            also tt(%token) below.nl()
           bf(NOTE:) Symbolic tokens are defined as tt(enum)-values in the
            parser's base class. The names of symbolic tokens may not be equal
            to the names of the members and types defined by bic() itself (see
            the next sections). This requirement is em(not) enforced by bic(),
            but compilation errors may result if this requirement is violated.
    it() bf(%type) tt(<type> non-terminal ...) nl()    
           In combination with tt(%polymorphic) or tt(%union): associate the
            semantic value of a non-terminal symbol with a polymorphic
            semantic value tag or union field defined by these directives.
    it() bf(%union) tt(union-definition) nl()    
           Acts identically to the identically named bf(bison) and bf(bison++)
            declaration.  Bic() generates a union, named tt(STYPE__), as its
            semantic type.  
    it() bf(%weak-tags) nl()
           This directive is ignored unless the tt(%polymorphic)
            directive was specified. It results in the declaration of tt(enum
            Tag__) rather than tt(enum class Tag__). When in doubt, don't use
            this directive.
    )

manpagesection(5. POLYMORPHIC SEMANTIC VALUES)

    The tt(%polymorphic) directive allows bic() to generate a parser using
polymorphic semantic values. The various semantic values are specified as
pairs, consisting of em(tags) (which are bf(C++) identifiers), and bf(C++)
type names. Tags and type names are separated by colons. Multiple tag and type
name combinations are separated by semicolons, and an optional semicolon ends
the final tag/type specification.

Here is an example, defining three semantic values: an tt(int), a
tt(std::string) and a tt(std::vector<double>):
        verb(
    %polymorphic INT: int; STRING: std::string; 
                 VECT: std::vector<double>
        )
    The identifier to the left of the colon is called the em(tag-identifier)
(or simply em(tag)), and the type name to the right of the colon is called the
em(type-name). Since bic() version 4.12.00 the types no longer have to
offer  offer default constructors, but if no default constructor is available
then the option tt(--no-default-action-return) is required.

    When polymorphic type-names refer to types not yet declared by the
parser's base class header, then these types must be declared in a header file
whose location is specified through the tt(%baseclass-preinclude) directive.

    includefile(../manual/grammar/polymorphictype.yo)

    The tt(%polymorphic) directive adds the following definitions and
declarations to the generated base class header and parser source
file (if the tt(%namespace) directive was used then all declared/defined
elements are placed inside the name space that is specified by the
tt(%namespace) directive):
    itemization(
    it() An additional header is included in the parser's base class
header: 
            verb(
    #include <memory>
            )
    it() All semantic value type identifiers are collected in a strongly typed
`tt(Tag__)' enumeration. E.g.,
        verb(
    enum class Tag__
    {
        INT,
        STRING,
        VECT
    };
        )
    it() The name space tt(Meta__) contains almost all of the code
implementing polymorphic values.
    )

    The name space tt(Meta__) contains the following elements:
    itemization(
    it() A polymorphic base class tt(Base). This class is normally not
     explicitly referred to by user-defined code. Refer to by bic()'s
     user manual for a detailed description of this class.

    it() For each of the tag-identifiers specified with the tt(%polymorphic)
     directive a class template tt(Semantic<Tag__>) is defined, containing a
     data element of the type-name matching the tt(Tag__) for which
     tt(Semantic<Tag__>) was derived. 

    The tt(Semantic<Tag__>) classes are normally not explicitly referred to by
     user-defined code. Refer to by bic()'s user manual for a detailed
     description of these classes.

    it() A class tt(SType), derived from tt(std::shared_ptr<Base>). This class
     becomes the parser's semantic value type, offering the following
     members:nl()

        tt(Constructors:) default, copy and move constructors;nl()

        tt(Assignment operators:) copy and move assignment operators declaring 
            tt(SType) or any of the tt(%polymorphic) type-names as their
            right-hand side operands;nl()

        tt(Tag__ tag() const), returning tt(Semantic<Tag__>)'s tt(Tag__)
             value;nl()

        tt(DataType &get<Tag__>()) returns a reference to the semantic value
             stored inside tt(Semantic<Tag__>).

            This member checks for 0-pointers and for tt(Tag__) mismatches
             between the requested and actual tt(Tag__), in that case
             replacing the current tt(Semantic) object pointed to by a new
             tt(Semantic<Tag__>) object of the requested tt(Tag__).

        tt(DataType &data<Tag__>()) returns a reference to the semantic value
             stored inside tt(Semantic<Tag__>).

            This is a (partially) em(unchecking) variant of the corresponing
             tt(get) member, resulting in a em(Segfault) if used when the
             tt(shared_ptr) holds a 0-pointer, compilation may fail in case of
             a mismatch between the requested and actual tt(Tag__).
    )

    Since bic() declares tt(typedef Meta__::SType STYPE__), polymorphic
semantic values can be used without referring to the name space tt(Meta__). 

manpagesection(6. PUBLIC MEMBERS AND -TYPES)

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

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

manpagesection(8. PRIVATE MEMBER FUNCTIONS)

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

manpagesection(9. 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_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(LTYPE__ d_lsp__):nl()
       The location stack pointer.
        Do not modify.
    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_nextToken__):nl()
       A pending token. 
        Do not modify.
    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(int d_state__):nl()
       The current parsing state. 
        Do not modify.
    it() bf(int d_token__):nl()
       The current token.
        Do not modify.
    it() bf(STYPE__ d_val__):nl()
       The semantic value of a returned token or non-terminal symbol. With
        non-terminal 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
        available the correct semantic value 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, direct assignment of
        values to tt(d_val__) is not possible. In that case em(tagged
        assignment) must be 
        used+IFDEF(MANUAL)(, as explained in section ref(POLYTYPE))().

    it() bf(LTYPE__ d_vsp__):nl()
       The semantic value stack pointer. 
        Do not modify.
    )

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

manpagesection(11. RESTRICTIONS ON TOKEN NAMES)

    To avoid collisions with names defined by the parser's (base) class, the
following identifiers should not be used as token names:
    itemization(
    it() Identifiers ending in two underscores;
    it() Any of the following identifiers: tt(ABORT, ACCEPT, ERROR, clearin,
        debug), or tt(setDebug).
    )

manpagesection(12. OBSOLETE SYMBOLS)

    All bf(DECLARATIONS) and bf(DEFINE) symbols not listed above but defined
in bf(bison++) are obsolete with bic(). In particular, there is no tt(%header{
... %}) section anymore. Also, all bf(DEFINE) symbols related to member
functions are now obsolete. There is no need for these symbols anymore as they
can simply be declared in the class header file and defined elsewhere.
                    
manpagesection(13. EXAMPLE)

    Using a fairly worn-out example, we'll construct a simple calculator
below. The basic operators as well as parentheses can be used to specify
expressions, and each expression should be terminated by a newline. The
program terminates when a tt(q) is entered. Empty lines result in a mere
prompt. 

    First an associated grammar is constructed. When a syntactic error is
encountered all tokens are skipped until then next newline and a simple
message is printed using the default tt(error) function. It is assumed that
no semantic errors occur (in particular, no divisions by zero). The grammar is
decorated with actions performed when the corresponding grammatical production
rule is recognized. The grammar itself is rather standard and straightforward,
but note the first part of the specification file, containing various other
directives, among which the tt(%scanner) directive, resulting in a
composed tt(d_scanner) object as well as an implementation of the member
function tt(int lex). In this example, a common tt(Scanner) class
construction strategy was used: the class tt(Scanner) was derived from the
class tt(yyFlexLexer) generated by bf(flex++)(1). The actual process of
constructing a class using bf(flex++)(1) is beyond the scope of this man-page,
but bf(flex++)(1)'s specification file is mentioned below, to further complete
the example. Here is bf(bisonc++)'s input file:

        verbinclude(calculator/parser/grammar)

    Next, bic() processes this file. In the process, bic() generates the
following files from its skeletons:
    itemization(
    it() The parser's base class, which should not be modified by the
         programmer: 

        verbinclude(calculator/parser/parserbase.h)

    it() The parser class tt(parser.h) itself. In the grammar
specification various member functions are used (e.g., tt(done)) and
tt(prompt). These functions are so small that they can very well be
implemented inline. Note that tt(done) calls tt(ACCEPT) to terminate
further parsing. tt(ACCEPT) and related members (e.g., tt(ABORT)) can be
called from any member called by tt(parse). As a consequence, action blocks
could contain mere function calls, rather than several statements, thus
minimizing the need to rerun bic() when an action is modified.

    Once bic() had created tt(parser.h) it was augmented with the required
additional members, resulting in the following final version:

        verbinclude(calculator/parser/parser.h)

    it() To complete the example, the following lexical scanner specification
was used:

        verbinclude(calculator/scanner/lexer)

    it() Since no member functions other than tt(parse) were defined in
separate source files, only tt(parse) includes tt(parser.ih). Since
tt(cerr) is used in the grammar's actions, a tt(using namespace
std) or comparable statement is required. This was effectuated from
tt(parser.ih) Here is the implementation header declaring the standard
namespace:

        verbinclude(calculator/parser/parser.ih)

    The implementation of the parsing member function tt(parse) is basically
irrelevant, since it should not be modified by the programmer. It was written
on the file tt(parse.cc).
    it() Finally, here is the program offering our simple calculator:

        verbinclude(calculator/calculator.cc)
    )

manpagesection(14. USING PARSER-CLASS SYMBOLS IN LEXICAL SCANNERS)

        Note here that although the file tt(parserbase.h), defining the
parser class' base-class, rather than the header file tt(parser.h)
defining the parser class is included, the lexical scanner may simply return
tokens of the class tt(Parser) (e.g., tt(Parser::NUMBER) rather than
tt(ParserBase::NUMBER)). In fact, using a simple tt(#define - #undef)
pair generated by the bic() respectively at the end of the base class header
the file and just before the definition of the parser class itself it is
the possible to assume in the lexical scanner that all symbols defined in the
the parser's base class are actually defined in the parser class itself. It
the should be noted that this feature can only be used to access base class
the tt(enum) and types. The actual parser class is not available by the time
the the lexical scanner is defined, thus avoiding circular class dependencies.
        
manpagesection(15. FILES)
    itemization(
    it() bf(bisonc++base.h): skeleton of the parser's base class;
    it() bf(bisonc++.h): skeleton of the parser class;
    it() bf(bisonc++.ih): skeleton of the implementation header;
    it() bf(bisonc++.cc): skeleton of the member tt(parse);
    it() bf(bisonc++polymorphic): skeleton of the declarations used by
        tt(%polymorphic);
    it() bf(bisonc++polymorphic.inline): skeleton of the inline
        implementations of the members declared in bf(bisonc++polymorphic).
    )

manpagesection(16. SEE ALSO)
    bf(bison)(1), bf(bison++)(1), bf(bison.info) (using texinfo),
    bf(flex++)(1)

    Lakos, J. (2001) bf(Large Scale C++ Software Design), Addison Wesley.nl()
    Aho, A.V., Sethi, R., Ullman, J.D. (1986) bf(Compilers), Addison Wesley.

manpagesection(17. BUGS)

    Parser-class header files (e.g., Parser.h) and parser-class internal
    header files (e.g., Parser.ih) generated with bisonc++ < 4.02.00 require
    two hand-modifications when used in combination with bisonc++ >=
    4.02.00. See the description of tt(exceptionHandler__) for details.

    Discontinued options:
    itemization(
        it() loption(include-only)
        it() loption(namespace)
    )

    To avoid collisions with names defined by the parser's (base) class, the
following identifiers should not be used as token nams:
    itemization(
    it() Identifiers ending in two underscores;
    it() Any of the following identifiers: tt(ABORT, ACCEPT, ERROR, clearin,
        debug, error), or tt(setDebug).
    )

    When re-using files generated by bic() before version 2.0.0, minor
hand-modification might be necessary. The identifiers in the following list
(defined in the parser's base class) now have two underscores affixed to them:
tt(LTYPE, STYPE) and tt(Tokens). When using classes derived from the generated
parser class, the following identifiers are available in such derived classes:
tt(DEFAULT_RECOVERY_MODE, ErrorRecovery, Return, UNEXPECTED_TOKEN, d_debug,
d_loc, d_lsp, d_nErrors, d_nextToken, d_state, d_token, d_val), and tt(d_vsp).
When used in derived classes, they too need two underscores affixed to them.

    The member function tt(void lookup) (< 1.00) was replaced by tt(int
lookup). When regenerating parsers created by early versions of bf(bisonc++)
(versions before version 1.00), tt(lookup)'s prototype should be corrected by
hand, since bf(bisonc++) will not by itself rewrite the parser class's header
file.

    The em(Semantic) parser, mentioned in bf(bison++)(1) is not implemented in
bf(bisonc++)(1). According to bf(bison++)(1) the semantic parser was not
available in bf(bison++) either. It is possible that the em(Pure) parser is
now available through the tt(--thread-safe) option.

manpagesection(18. ABOUT bisonc++)

bf(Bisonc++) was based on bf(bison++), originally developed by Alain
Coetmeur (coetmeur@icdc.fr), R&D department (RDT), Informatique-CDC, France,
who based his work on bf(bison), GNU version 1.21. 

    Bic() 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's (1986) book bf(Compilers) (i.e., the em(Dragon book)).  It
uses the same grammar specification as bf(bison) and bf(bison++), and it uses
practically the same options and directives as bic() versions earlier than
0.98. Variables, declarations and macros that are obsolete were removed. 
    
manpageauthor()

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