Chapter 9: Invoking Bisonc++

9.1: Bisonc++ options

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 (/); 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 bisonc++ cannot modify (e.g., a parser class header file exists, but doesn't define a name space, but a --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 bisonc++ currently does not handle the opposite error condition: if a previously used option is omitted, then bisonc++ does not detect the inconsistency. In those cases compilation errors may be generated.

--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=filename (-b)
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 base.h. It is generated, unless otherwise indicated (see --no-baseclass-header and --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 #include "filename".
--baseclass-preinclude=pathname (-H)
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 std::string value type might be used. Since the string header file is not by default included in 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 `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=pathname (-B)
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., /usr/share/bisonc++/ plus bisonc++base.h).
--class-header=filename (-c)
Filename defines the name of the file to contain the parser class. Defaults to the name of the parser class plus the suffix .h
It is an error if this option is used and an already existing implementation header file does not contain #include "filename".
--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.
It is an error if this option is used and an already existing parser-class header file does not define class `className' and/or if an already existing implementation header file does not define members of the class `className'.
--class-skeleton=pathname (-C)
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., /usr/share/bisonc++/ plus 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 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.
--filenames=filename (-f)
Filename is a generic file name that is used for all header files generated by bisonc++. Options defining specific file names are also available (which then, in turn, overrule 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.
--help (-h)
Write basic usage information to the standard output stream and terminate.
--implementation-header=filename (-i)
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 .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=pathname (-I)
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., /usr/share/bisonc++/ plus 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 also shows 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 identifier
Define all of the code generated by bisonc++ in the name space identifier. By default no name space is defined. If this options is used the implementation header is provided with a commented out 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 namespace identifier.
--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. When the construction of this file is suppressed, modifications of these terminal tokens are not communicated to the lexical scanner.
--no-decoration (-D)
Do not include the user-defined actions when generating the parser's 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.
--no-lines
Do not put #line preprocessor directives in the file containing the parser's parse function. By default the file containing the parser's parse function also contains #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 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=pathname (-P)
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., /usr/share/bisonc++/ plus bisonc++.cc).
--parsefun-source=filename (-p)
Filename defines the name of the source file to contain the parser member function parse. Defaults to parse.cc.
--polymorphic-skeleton=pathame (-M)
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., /usr/share/bisonc++/ plus bisonc++polymorphic).
--polymorphic-inline-skeleton=pathname (-m)
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., /usr/share/bisonc++/ plus 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__ can thus easily be controlled from print, using, e.g., a variable that set by the program using the parser generated by bisonc++.
This option does not show the tokens returned and text matched by bisonc++ itself when it is 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=pathname (-s)
Pathname defines the path name to the file defining the scanner's class interface (e.g., "../scanner/scanner.h"). When this option is used the parser's member int lex() is predefined as
```
    int Parser::lex()
    {
        return d_scanner.lex();
    }
                
```
and an object Scanner d_scanner is composed into the parser (but see also option scanner-class-name). The example shows the function that's called by default. When the --flex option (or %flex directive) is specified 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 bisonc++ surrounds pathname by double quotes (using, e.g., #include "pathname"). When pathname is surrounded by pointed brackets #include <pathname> is included.
It is an error if this option is used and an already existing parser class header file does not include `pathname'.
--scanner-class-name scannerClassName
Defines the name of the scanner class, declared by the pathname header file that is specified at the scanner option or directive. By default the class name Scanner is used.
It is an error if this option is used and either the scanner option was not provided, or the parser class interface in an already existing parser class header file does not declare a scanner class d_scanner object.
--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()"
                
```
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.
--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. This option can be overridden by the specific skeleton-specifying options (-B -C, -H, -I, -M and -m).
--target-directory=pathname
Pathname defines the directory where generated files should be written. By default this is the directory where bisonc++ is called.
--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.10.01
Copyright (c) GPL 2005-2015. 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).
   --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.
   --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-decoration (-D): do not include the user-defined actions when
           generating the parser's tt(parse) member.
   --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-class-name=<scanner class name>:
           specifies the name of the scanner class: this option is
           only interpreted if --scanner (or %scanner) is also used.
   --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.