Where available, single letter options are listed between parentheses beyond their associated long-option variants. Single letter options require arguments if their associated long options also require arguments. Options affecting the class- or implementation header files are ignored if these files already exist. Options accepting a `filename' do not accept path names, i.e., they cannot contain directory separators (tt(/)); options accepting a 'pathname' may contain directory separators. Some options may cause errors. This happens when they conflict with the contents of a file which bic() cannot modify (e.g., a parser class header file exists, but doesn't define a namespace, but a tt(--namespace) option was specified). 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 report an inconsistency. In those cases compilation errors may be observed. 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
) is included. In the latter case, quotes might be required to escape interpretation by the shell (e.g., using tt(-H '
')). 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 tt(className) differs from the name of the class that is defined in an already existing parser-class header file and/or if an already existing implementation header file does not define members of the class 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(.output), where tt() 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 the generated tt(parse) and its support functions with debugging code, optionally showing the actual parsing process on the standard output stream. When included, the debugging output is active by default, but its activity may be controlled using the tt(setDebug(bool on-off)) member. Bic() does not use tt(#ifdef DEBUG) macros. Rerun bic() without the tt(--debug) option to remove the debugging code. Note that this option does em(not) show the actions of bic()'s own parser, its own lexical scanner or merely the numbers of the case-entries executed by the parser's tt(parse) function. If that is what you want, use the tt(--own-debug, --action-cases, --scanner-debug) and/or tt(--own-tokens) options. When polymorphic semantic values are used (see section IFDEF(manpagetext)(\ bf(POLYMORPHIC SEMANTIC VALUES)\ )(\ ref(POLYMORPHIC)\ )) then the generated parser might attempt to retrieve an incorrect polymorphic value. In that case a fatal error is generated, ending bic()'s run. The error message itself cannot refer to the action block where the error occurred. If this situation is encountered, rerun bic(), specifying tt(--debug) and call tt(parser.setDebug(Parser::ACTIONCASES)): as a debugging aid the generated parser then shows the executeAction switch's case entry numbers just before their execution. it() lsoption(default-actions)(d)(off|quiet|warn)nl() When tt(warn) is specified (which is the default) an action block executing tt($$ = $1) (or tt($$ = STYPE_{}) for empty production rules) is added to production rules that do not explicitly define their own final action blocks, while issuing a warning. When tt(quiet) is specified these action blocks are silently added. It is an error when the types of $$ and $1 differ (but it is OK if neither $$ nor $1 is associated with a specific type). When tt(off) is specified no action blocks are added (issuing a warning unless the option/directive tt(tag-mismatches off) has been specified). 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(.ih). 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++.ih)). it() loption(insert-stype)nl() This option is only effective if the tt(debug) option (or tt(%debug) directive) has 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 namespace tt(identifier). By default no namespace is defined. If this options is used the implementation header is provided with a commented out tt(using namespace) declaration for the specified namespace. In addition, the parser and parser base class header files also use the specified namespace to define their include guard directives. 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 user-defined or default actions when generating the parser's tt(parse) member. This effectively generates a parser which merely performs syntax checks, without performing the actions which are normally executed when rules have been matched. This may be useful in situations where a (partially or completely) decorated grammar is reorganized, and the syntactic correctness of the modified grammar must be verified, or in situations where the grammar has already been decorated, but functions which are called from the rules'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() Displays the actions performed by bic()'s parser when it processes the grammar specification file(s) (lots of output!). This implies the tt(--verbose) option. it() loption(own-tokens) (soption(T))nl() The tokens returned as well as the text matched by bic()'s lexcial scanner are shown when this option is used. This option does em(not) result in the em(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-code-skeleton)(L)(pathname)nl() tt(Pathname) defines the path name of the file containing the non-template members of the polymorphic Base class. It defaults to the installation-defined default path name (e.g., tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic.code)). 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() 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() loption(prompt)nl() When adding debugging code (using the tt(debug) option or directive) the debug information is displayed continuously while the parser processes its input. When using the tt(prompt) option (or directive) the generated parser displays a prompt (a question mark) at each step of the parsing process. Caveat: when using this option the parser's input cannot be provided at the parser's standard input stream. 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 ) 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 extensively displays the rules and tokens matched and returned by bic()'s scanner, instead of just showing the tokens and matched text which are received by bic(). If you want the latter, use the option tt(--own-tokens). 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. In addition to specifying a common names for the skeleton files the locations of individual skeleton files can be specified using the options (tt(-B -C, -H, -I, -L) and tt(-M)). it() loption(stack-expansion)(size)nl() Defines the number of elements to be added to the generated parser's semantic value stack when it must be enlarged. By default 10 elements are added to the stack. This option/directive is interpreted only once, and only if tt(size) at least equals the default stack expansion size of 10. it() loption(tag-mismatches) tt(off|on)nl() When tt(on) is specified (which is the default), a warning is issued if no $$ assignment was detected in an action block, or if adding a default $$ = ... action was suppressed (cf. the tt(default-actions off) option or directive). 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() Only used with polymorphic semantic values, and then only required when the parser is used in multiple threads: it ensures that each thread's polymorphic code only accesses its own parser's error counting variable. it() lsoption(token-class)(K)(classname)nl() tt(Classname) defines the name of the tt(Tokens) class that is defined when tt(token-path) (see below) is specified. If tt(token-path) isn't specified then this option is ignored. By default the class name tt(Tokens) is used. it() lsoption(token-namespace)(N)(namespace)nl() If tt(token-path) is specified (see below) then tt(namespace) defines the namespace of the tt(Tokens) class. By default no namespace is used. it() lsoption(token-path)(F)(pathname)nl() tt(Pathname) defines the path name of the file to contain the tt(struct Tokens) defining the enumeration tt(Tokens_) containing the symbolic tokens of the generated grammar. If this option is specified the tt(ParserBase) class is derived from it, thus making the tokens available to the generated parser class. The name of the tt(struct Tokens) can be altered using the tt(token-class) directive or option. By default (i.e., if tt(token_path) is not specified) the tokens are defined as the tt(enum Tokens_) in the tt(ParserBase) class. If tt(pathname) doesn't exist it is created by bic(). If the tt(pathname) file already exists it is rewritten at each new run of bic(). it() loption(usage)nl() Writes basic usage information to the standard output stream and terminates. it() loption(verbose) (soption(V))nl() Writes a file containing verbose descriptions of the parser states and what is done for each type of look-ahead token in that state. This file also describes all conflicts detected in the grammar, both those resolved by operator precedence and those that remain unresolved. It is not created by default, but if requested the information is written on tt(.output), where tt() is the grammar specification file passed to bic(). it() loption(version) (soption(v))nl() Displays bic()'s version number and terminates. )