    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 require arguments. Options
affecting the class header or implementation header file are ignored if these
files already exist. Options accepting a `filename' do not accept path names,
i.e., they cannot contain directory separators (tt(/)); options accepting a
'pathname' may contain directory separators. 

Some options may generate errors. This happens when an option 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) option was provided). 

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's specification. Note that bic() currently does not handle the opposite
error condition: if a previously used option is omitted, then bic() does not
detect the inconsistency. In those cases compilation errors may be generated.


COMMENT(
    class header:           warn for class-name mismatch
                            warn for not including baseclass-header
                            warn for namespace mismatch
                            if the 'scanner' option was provided:
                                warn for missing "scanner" include-spec
                                warn for missing Scanner d_scanner spec.

    implementation header:  warn for class-name mismatch 
                                (in inline defined members)
                            warn for not including the class header
                            warn for namespace mismatch
                            warn for a mismatch in the scanner-token-function
                                     name
END)


    itemization(
    it() loption(analyze-only) (soption(A))nl()
           Only analyze the grammar. No files are (re)written. This option can
            be used to test the grammatic correctness of modification `in
            situ', without overwriting previously generated files. If the
            grammar contains syntactic errors only syntax analysis is 
            performed.

    it() lsoption(baseclass-header)(b)(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). It is generated, unless otherwise indicated (see
            tt(--no-baseclass-header) and tt(--dont-rewrite-baseclass-header)
            below).

           It is an error if this option is used and an already
            existing parser class header file does not contain tt(#include
            "filename").

    it() label(PREINCLUDE) lsoption(baseclass-preinclude)(H)(pathname)nl()
           tt(Pathname) defines  the path to the file preincluded in the
            parser'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
            tt(std::string) value type might be used. Since the tt(string)
            header file is not by default included in tt(parserbase.h) 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 `tt(header)' is
            surrounded by double quotes: tt(#include "header") is used when
            the option tt(-H header) is specified.  When the argument is
            surrounded by pointed brackets tt(#include <header>) is
            included. In the latter case, quotes might be required to escape
            interpretation by the shell (e.g., using tt(-H '<header>')).

    it() lsoption(baseclass-skeleton)(B)(pathname)nl() 
           tt(Pathname) defines the path name to the file containing the
            skeleton of the parser's base class. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++base.h)).

    it() lsoption(class-header)(c)(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)

           It is an error if this option is used and an already
            existing implementation header file does not contain tt(#include
            "filename").

    it() loption(class-name) tt(className) nl()
           Defines the name of the bf(C++) class that is generated.  If
            neither this option, nor the tt(%class-name) directory is
            specified, then the default class name (tt(Parser)) is used.

           It is an error if this option 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() lsoption(class-skeleton)(C)(pathname)nl()
           tt(Pathname) 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.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.h)).

    it() loption(construction)nl() 
           Details about the construction of the parsing tables are written to
            the same file as written by the tt(--verbose) option (i.e.,
            tt(<grammar>.output), where tt(<grammar>) is the input file read
            by bic(). This information is primarily useful for developers. It
            augments the information written to the verbose grammar output
            file, generated by the tt(--verbose) option.

    it() loption(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. An tt(#ifdef DEBUG) macro is not supported by
            bic(). Rerun bic() without the tt(--debug) option to remove the
            debugging code.

    it() label(ERRORVERBOSE)loption(error-verbose)nl()
           When a syntactic error is reported, the generated parse function
            dumps the parser'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's top element.

    it() lsoption(filenames)(f)(filename)nl()
           tt(Filename) is a generic file name that is used for all header
            files generated by bic(). Options defining specific file names are
            also available (which then, in turn, overrule the name specified
            by this option).

    it() loption(flex)nl() 
           Bic() generates code calling tt(d_scanner.yylex()) to obtain the
            next lexical token, and calling tt(d_scanner.YYText()) for the
            matched text, unless overruled by options or directives explicitly
            defining these functions. By default, the interface defined by
            bf(flexc++)(1) is used. This option is only interpreted if the
            tt(--scanner) option or tt(%scanner) directive is also used.

    it() loption(help) (soption(h))nl()
            Write basic usage information to the standard output stream and
            terminate. 

    it() lsoption(implementation-header)(i)(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(.hh).

           The implementation header should contain all directives and
            declarations em(only) used by the implementations of 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.

    it() lsoption(implementation-skeleton)(I)(pathname)nl()
           tt(Pathname) 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.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.hh)).

    it() loption(insert-stype)nl()
           This option is only effective if the tt(debug) option (or
            tt(%debug) directive) has also been specified. When
            tt(insert-stype) has been specified the parsing function's debug
            output also shows selected semantic values. It should only be used
            if objects or variables of the semantic value type tt(STYPE__) can
            be inserted into tt(ostreams).

    it() label(MAXDEPTH) laoption(max-inclusion-depth)(value)nl()
           Set the maximum number of nested grammar files. Defaults to 10.

    it() loption(namespace) tt(identifier) nl()
           Define all of the code generated by bic() in the name space
            tt(identifier). By default no name space is defined. If this
            options 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 option is used and an already existing
            parser-class header file and/or implementation header file does
            not define tt(namespace identifier).

    it() loption(no-baseclass-header)nl()
           Do not write the file containing the parser class' base class, even
            if that file doesn't yet exist. By default the file containing the
            parser's base class is (re)written each time bic() 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.

    it() loption(no-decoration) (soption(D))nl()
           Do not include the user-defined actions when generating the
            parser's tt(parse) member. This effectively generates a parser
            which merely performs semantic 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 syntactical
            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's actions have not yet
            been impleemented.

    it() loption(no-lines)nl() 
           Do not put tt(#line) preprocessor directives in the file containing
            the parser's tt(parse) function. By default the file containing
            the parser's tt(parse) function also contains tt(#line)
            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 tt(parse) function itself.

    it() loption(no-parse-member)nl()
           Do not write the file containing the parser's predefined parser
            member functions, even if that file doesn't yet exist. By default
            the file containing the parser's tt(parse) member function is
            (re)written each time bic() 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. 

    it() loption(own-debug)nl()
           Extensively displays the actions performed by bic()'s parser when
            it processes the grammar specification file(s). This implies the
            tt(--verbose) option.

    it() loption(own-tokens) (soption(T))nl()
           The tokens returned as well as the text matched when bic() reads
            its input files(s) are shown when this option is used.

           This option does em(not) result in the generated parsing function
            displaying returned tokens and matched text. If that is what you
            want, use the tt(--print-tokens) option.

    it() lsoption(parsefun-skeleton)(P)(pathname)nl()
           tt(Pathname) defines the path name of the file containing the
            parsing member function's skeleton. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.cc)).

    it() lsoption(parsefun-source)(p)(filename)nl()
           tt(Filename) defines the name of the source file to contain the
            parser member function tt(parse). Defaults to tt(parse.cc).

    it() lsoption(polymorphic-skeleton)(M)(pathame)nl()
           tt(Pathname) 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.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic)).

    it() lsoption(polymorphic-inline-skeleton)(m)(pathname)nl()
           tt(Pathname) defines the path name of the file containing the
            skeleton of the inline implementations of the members of the
            polymorphic template classes.  It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic)).

    it() loption(print-tokens) (soption(t))nl()
           The generated parsing function implements a function tt(print__)
            displaying (on the standard output stream) the tokens returned by
            the parser'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 tt(print__)) is
            called from tt(Parser::print), which is defined in-line in the the
            parser's class header. Calling tt(Parser::print__) can thus easily
            be controlled from tt(print), using, e.g., a variable that set by
            the program using the parser generated by bic().

           This option does em(not) show the tokens returned and text matched
            by bic() itself when it is reading its input file(s). If
            that is what you want, use the tt(--own-tokens) option.

    it() label(REQUIRED) laoption(required-tokens)(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() label(SCANOPT) lsoption(scanner)(s)(pathname)nl()
           tt(Pathname) defines the path name to the file defining the
            scanner's class interface (e.g., tt("../scanner/scanner.h")). When
            this option is used the parser's member tt(int lex()) is
            predefined as
           verb(
    int Parser::lex()
    {
        return d_scanner.lex();
    }
                )
           and an object tt(Scanner d_scanner) is composed into the parser
            (but see also option tt(scanner-class-name)). The example shows
            the function that's called by default. When the tt(--flex) option
            (or tt(%flex) directive) is specified 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).

           By default bic() surrounds tt(pathname) by double quotes (using,
            e.g., tt(#include "pathname")).  When tt(pathname) is surrounded
            by pointed brackets tt(#include <pathname>) is included.

           It is an error if this option is used and an already existing
            parser class header file does not include tt(`pathname').

    it() loption(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 option is used and either the
            tt(scanner) option 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() loption(scanner-debug)nl() 
           Show de scanner's matched rules and returned tokens. This offers an
            extensive display of the rules and tokens matched and returned by
            bic()'s scanner, not of just the tokens and matched text received
            by bic(). If that is what you want use the tt(--own-tokens)
            option.

    it() laoption(scanner-matched-text-function)(function-call)nl() 
           The scanner function returning the text that was matched at the
            last call of the scanner's token function. A complete function
            call expression should be provided (including a scanner object, if
            used). This option overrules the tt(d_scanner.matched()) call used
            by default when the tt(%scanner) directive is specified, and it
            overrules the tt(d_scanner.YYText()) call used when the tt(%flex)
            directive is provided. Example:
           verb(
    --scanner-matched-text-function "myScanner.matchedText()"
                )

    it() laoption(scanner-token-function)(function-call)nl() 
           The scanner function returning the next token, called from the
            parser's tt(lex) function. A complete function
            call expression should be provided (including a scanner object, if
            used). This option overrules the tt(d_scanner.lex()) call used
            by default when the tt(%scanner) directive is specified, and it
            overrules the tt(d_scanner.yylex()) call used when the tt(%flex)
            directive is provided. Example:
           verb(
    --scanner-token-function "myScanner.nextToken()"
                )

           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.

    it() loption(show-filenames)nl() 
           Writes the names of the generated files to the standard error
            stream.

    it() lsoption(skeleton-directory)(S)(directory)nl() 
           Specifies the directory containing the skeleton files. This option
            can be overridden by the specific skeleton-specifying options
            (tt(-B -C, -H, -I, -M) and tt(-m)).

    it() laoption(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. 

    it() loption(thread-safe)nl() 
           No static data are modified, making bic() thread-safe.

    it() loption(usage)nl()
            Write basic usage information to the standard output stream and
            terminate. 

    it() loption(verbose) (soption(V))nl() 
           Write 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 tt(<grammar>.output), where
            tt(<grammar>) is the grammar specification file passed to bic().

    it() loption(version) (soption(v))nl()
            Display bic()'s version number and terminate.

    )
