Chapter 9: Invoking Bisonc++

9.1: Bisonc++ options

If available, single letter options are listed between parentheses following their associated long-option variants. Single letter options require arguments if their associated long options require arguments as well. Options affecting the class header or implementation header file are ignored if these files already exist.

--analyze-only (-A)
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.
--baseclass-header=header (-b)
Use header as the pathname 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 base.h. It is generated, unless otherwise indicated (see --no-baseclass-header and --dont-rewrite-baseclass-header below).
--baseclass-preinclude=header (-H)
Use header as the pathname 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 a std::string value type might be used. Since the string header file is not by default included in parserbase.h we need a way 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 `header' is surrounded by double quotes: #include "header" is used when the option -H header is specified. When the argument is surrounded by pointed brackets #include <header> is included. In the latter case, quotes might be required to escape interpretation by the shell (e.g., using -H '<header>').
--baseclass-skeleton=skeleton (-B)
Use skeleton as the pathname of the file containing the skeleton of the parser's base class. Its filename defaults to bisonc++base.h.
--class-header=header (-c)
Use header as the pathname of the file to contain the parser class. Defaults to the name of the parser class plus the suffix .h
--class-name className
Defines the name of the C++ class that is generated. If neither this option, nor the %class-name directory is specified, then the default class name (Parser) is used.
--class-skeleton=skeleton (-C)
Use skeleton as the pathname of the file containing the skeleton of the parser class. Its filename defaults to bisonc++.h.
--construction
Details about the construction of the parsing tables are written to the same file as written by the --verbose option (i.e., <grammar>.output, where <grammar> is the input file read by bisonc++. This information is primarily useful for developers. It augments the information written to the verbose grammar output file, generated by the --verbose option.
--debug
Provide 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 setDebug(bool on-off) member. An #ifdef DEBUG macro is not supported by bisonc++. Rerun bisonc++ without the --debug option to remove the debugging code.
--error-verbose
When a syntactic error is reported, the generated parse function will dump 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.
--filenames=filename (-f)
Specify a filename to use for all files produced by bisonc++. Specific options overriding particular filenames are also available (which then, in turn, overide the name specified by this option).
--flex
Bisonc++ generates code calling d_scanner.yylex() to obtain the next lexical token, and calling d_scanner.YYText() for the matched text, unless overruled by options or directives explicitly defining these functions. By default, the interface defined by flexc++(1) is used. This option is only interpreted if the --scanner option or %scanner directive is also used.
--force-class-header
By default the generated class header is not overwritten once it has been created. This option can be used to force the (re)writing of the file containing the parser's class.
--force-implementation-header
By default the generated implementation header is not overwritten once it has been created. This option can be used to force the (re)writing of the implementation header file.
--help (-h)
Write basic usage information to the standard output stream and terminate.
--implementation-header=header (-i)
Use header as the pathname of the file to contain the implementation header. Defaults to the name of the generated parser class plus the suffix .ih. The implementation header should contain all directives and declarations 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 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.
--implementation-skeleton=skeleton (-I)
Use skeleton as the pathname of the file containing the skeleton of the implementation header. Its filename defaults to bisonc++.ih.
--insert-stype
This option is only effective if the debug option (or %debug directive) has also been specified. When insert-stype has been specified the parsing function's debug output will also show selected semantic values. It should only be used if objects or variables of the semantic value type STYPE__ can be inserted into ostreams.
--max-inclusion-depth=value
Set the maximum number of nested grammar files. Defaults to 10.
--namespace=namespace (-n)
Define the parser base class, the paser class and the parser implentations in the namespace namespace. By default no namespace is defined. If this options is used the implementation header will contain a commented out using namespace declaration for the requested namespace.
--no-baseclass-header
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 bisonc++ 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. By suppressing the construction of this file any modification in these terminal tokens will not be communicated to the lexical scanner.
--no-lines
Do not put #line preprocessor directives in the file containing the parser's parse function. By default #line preprocessor directives are placed in the file containing the parser's parse function. 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 parse function itself.
--no-parse-member
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 parse member function is (re)written each time bisonc++ 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.
--own-debug
Extensively displays the actions performed by bisonc++'s parser when it processes the grammar specification s. This implies the --verbose option.
--own-tokens (-T)
The tokens returned as well as the text matched when bisonc++ reads its input files(s) are shown when this option is used.
This option does not result in the generated parsing function displaying returned tokens and matched text. If that is what you want, use the --print-tokens option.
--parsefun-skeleton=skeleton (-P)
Use skeleton as the pathname of the file containing the parsing member function's skeleton. Its filename defaults to bisonc++.cc.
--parsefun-source=source (-p)
Define source as the name of the source file to contain the parser member function parse. Defaults to parse.cc.
--polymorphic-skeleton=skeleton (-M)
Use skeleton as the pathname of the file containing the skeleton of the polymorphic template classes. Its filename defaults to bisonc++polymorphic.
--polymorphic-inline-skeleton=skeleton (-m)
Use skeleton as the pathname of the file containing the skeleton of the inline implementations of the members of the polymorphic template classes. Its filename defaults to bisonc++polymorphic.
--print-tokens (-t)
The generated parsing function implements a function 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 print__) is called from Parser::print, which is defined in-line in the the parser's class header. Calling Parser::print__, therefore, can also easily be controlled by an option controlled by the program using the parser generated by bisonc++.
This option does not show the tokens returned and text matched by bisonc++ itself when reading its input s. If that is what you want, use the --own-tokens option.
--required-tokens=number
Following a syntactic error, require at least number successfully processed tokens before another syntactic error can be reported. By default number is zero.
--scanner=header (-s)
Use header as the pathname to the file defining a class Scanner. When this option is used the parser's member int lex() is predefined as
```
    int lex()
    {
        return d_scanner.lex();
    }
                
```
and an object Scanner d_scanner is composed into the parser. The example shows the function that's called by default. By specifying the --flex option (or %flex directive) the function d_scanner.yylex() is called. Any other function to call can be specified using the --scanner-token-function option (or %scanner-token-function directive).
By default header is surrounded by double quotes (using, e.g., #include "header"). When the argument is surrounded by pointed brackets #include <header> is included.
--scanner-debug
Show de scanner's matched rules and returned tokens. This offers an extensive display of the rules and tokens matched and returned by bisonc++'s scanner, not of just the tokens and matched text received by bisonc++. If that is what you want use the --own-tokens option.
--scanner-matched-text-function=function-call
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 d_scanner.matched() call used by default when the %scanner directive is specified, and it overrules the d_scanner.YYText() call used when the %flex directive is provided. Example:
```
    --scanner-matched-text-function "myScanner.matchedText()"
                
```
--scanner-token-function=function-call
The scanner function returning the next token, called from the parser's lex function. A complete function call expression should be provided (including a scanner object, if used). This option overrules the d_scanner.lex() call used by default when the %scanner directive is specified, and it overrules the d_scanner.yylex() call used when the %flex directive is provided. Example:
```
    --scanner-token-function "myScanner.nextToken()"
                
```
--show-filenames
Writes the names of the generated files to the standard error stream.
--skeleton-directory=directory (-S)
Specifies the directory containing the skeleton files to use. This option can be overridden by the specific skeleton-specifying options (-B -C, -H, -I, -M and -m).
--target-directory=directory
Specifies the directory where generated files should be written. By default this is the directory of bisonc++'s input file. The --target-directory option does not affect files that were explicitly named (either as option or as directive).
--thread-safe
No static data are modified, making bisonc++ thread-safe.
--usage
Write basic usage information to the standard output stream and terminate.
--verbose (-V)
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 <grammar>.output, where <grammar> is the grammar specification file passed to bisonc++.
--version (-v)
Display bisonc++'s version number and terminate.

9.2: Bisonc++ usage

When bisonc++ is called without any arguments it generates the following usage information:


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

LALR(1) Parser Generator V 4.01.00
Copyright (c) GPL 2005-2012. NO WARRANTY.
Designed after `bison++' (1.21.9-1) by Alain Coetmeur <coetmeur@icdc.fr>

Usage: bisonc++ [OPTIONS] file
Where:
  [OPTIONS] - zero or more optional arguments (int options between
              parentheses. Short options require arguments if their
              long option variants do too):
   --analyze-only (-A): only analyze the grammar; except for possibly
           the verbose grammar description file no files are written.
   --baseclass-preinclude=<header> (-H):
           preinclude header in the base-class header file.
           Use [header] to include <header>, otherwise "header"
           will be included.
   --baseclass-header=<header> (-b):
           filename holding the base class definition.
   --baseclass-skeleton=<skeleton> (-B):
           location of the baseclass header skeleton.
   --class-header=<header> (-c):
           filename holding the parser class definition.
   --class-skeleton=<skeleton> (-C):
           location of the class header skeleton.
   --construction: write details about the grammar analysis to stdout.
   --debug: generates debug output statements in the generated parse
           function's source.
   --error-verbose: the parse function will dump the parser's state
           stack to stdout when a syntactic error is reported
   --filenames=<filename> (-f):
           filename of output files (overruling the default filename).
   --force-class-header: overwrite an existing class header file.
   --force-implementation-header: overwrite an existing implementation
           header file.
   --help (-h): produce this information (and terminate).
   --implementation-header=<header> (-i):
           filename holding the implementation header.
   --implementation-skeleton=<skeleton> (-I):
           location of the implementation header skeleton.
   --include-only: catenate all grammar files in their order of
           processing to the standard output stream and terminate.
   --insert-stype: show selected semantic values in the output generated
           by --debug. Ignored unless --debug was specified.
   --no-lines: don't put #line directives in generated output.
   --max-inclusion-depth=<value>:
           sets the maximum number of nested grammar files (default: 10).
   --namespace=<namespace>, (-n):
           define the parser in the mentioned namespace.
   --no-baseclass-header: don't create the parser's base class header.
   --no-lines: don't put #line directives in generated output,
           overruling the %lines directive.
   --no-parse-member: don't create the member parse().
   --own-debug:
           bisonc++ displays the actions of its parser while processing
           its input file(s) (implies --verbose).
   --own-tokens (-t):
           bisonc++ displays the tokens and their corresponding
           matched text it received from its lexcial scanner.
   --parser-skeleton=<parserskel> (-P):
           location of the parse function's skeleton.
   --parsefun-source=<source> (-p):
           filename holding the parse function's source.
   --polymorphic-inline-skeleton=<skeleton> (-m):
           location of the polymorphic inline functions skeleton.
   --polymorphic-skeleton=<skeleton> (-M):
           location of the polymorphic semantic values skeleton.
   --print-tokens (-t):
           the print() member of the generated parser class displays
           the tokens and their corresponding matched text.
   --required-tokens=<value>:
           minimum number of successfully processed tokens between
           errors (default: 0).
   --scanner=<header-file> (-s):
           include `header-file' declaring the class Scanner, and call
           d_scanner.yylex() from Parser::lex().
   --scanner-debug: extensive display of the actions of bisonc++'s scanner
   --scanner-token-function=<scanner token function>:
           define the function called from lex() returning the next
           token returned (by default d_scanner.yylex() when --scanner
           is used)
   --show-filenames: show the names of the used/generated files on
           the standard error stream.
   --skeleton-directory=<skeleton-directory> (-S):
           location of the skeleton directory.
   --thread-safe: no static data are modified, making bisonc++'s
           generated code thread-safe.
   --usage: produce this information (and terminate).
   --verbose (-V):
           generate verbose description of the analyzed grammar.
   --version (-v):
           display bisonc++'s version and terminate.