- Table of Contents
- Previous Chapter

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

- --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 `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 ``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 the generated `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 `setDebug(bool on-off)` member. Bisonc++ does not use `#ifdef DEBUG` macros. Rerun bisonc++ without the `--debug` option to remove the debugging code.

  Note that this option does not show the actions of bisonc++'s own parser, its own lexical scanner or merely the numbers of the case-entries executed by the parser's `parse` function. If that is what you want, use the `--own-debug, --action-cases, --scanner-debug` and/or `--own-tokens` options.

  When polymorphic semantic values are used (see section 4.6.1) then the generated parser might attempt to retrieve an incorrect polymorphic value. In that case a fatal error is generated, ending bisonc++'s run. The error message itself cannot refer to the action block where the error occurred. If this situation is encountered, rerun bisonc++, specifying `--debug` and call `parser.setDebug(Parser::ACTIONCASES)`: as a debugging aid the generated parser then shows the executeAction switch's case entry numbers just before their execution.

- --default-actions=`off|quiet|warn` (-d)
  When `warn` is specified (which is the default) an action block executing `$$ = $1` (or `$$ = 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 `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 `off` is specified no action blocks are added (issuing a warning unless the option/directive `tag-mismatches off` has been specified).

- --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 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 namespace `identifier`. By default no namespace is defined. If this options is used the implementation header is provided with a commented out `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 `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 user-defined or default actions when generating the parser's `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.

- --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
  Displays the actions performed by bisonc++'s parser when it processes the grammar specification s (lots of output!). This implies the `--verbose` option.

- --own-tokens (-T)
  The tokens returned as well as the text matched by bisonc++'s lexcial scanner 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-code-skeleton=`pathname` (-L)
  `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., `/usr/share/bisonc++/` plus `bisonc++polymorphic.code`).

- --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`).

- --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.

- --prompt
  When adding debugging code (using the `debug` option or directive) the debug information is displayed continuously while the parser processes its input. When using the `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.

- --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 extensively displays the rules and tokens matched and returned by bisonc++'s scanner, instead of just showing the tokens and matched text which are received by bisonc++. If you want the latter, use the option `--own-tokens`.

- --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. In addition to specifying a common names for the skeleton files the locations of individual skeleton files can be specified using the options (`-B -C, -H, -I, -L` and `-M`).

- --stack-expansion(size)
  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 `size` at least equals the default stack expansion size of 10.

- --tag-mismatches `off|on`
  When `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 `default-actions off` option or directive).

- --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
  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.

- --token-class=`classname` (-K)
  `Classname` defines the name of the `Tokens` class that is defined when the `token-path` option (see below) is specified. If the `token-path` option isn't specified then this option is ignord. If `token-class` is specified but `token-path` isn't then the class name `Tokens` is used.

- --token-namespace=`namespace` (-K)
  If the `token-path` option is specified (see below) then `namespace` defines the namespace of the `Tokens` class. By default no namespace is used.

- --token-path=`pathname` (-F)
  `Pathname` defines the path name of the file to contain the `struct Tokens` defining the enumeration `Tokens_` containing the symbolic tokens of the generated grammar. If this option is specified the `ParserBase` class is derived from it, thus making the tokens available to the generated parser class. The name of the `struct Tokens` can be altered using the `token-class` option. By default (if `token_path` is not specified) the tokens are defined as the `enum Tokens_` in the `ParserBase` class. If `pathname` doesn't exist it is created by bisonc++. If the `pathname` file already exists it is rewritten.

- --usage
  Writes basic usage information to the standard output stream and terminates.

- --verbose (-V)
  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 `<grammar>.output`, where `<grammar>` is the grammar specification file passed to bisonc++.

- --version (-v)
  Displays bisonc++'s version number and terminates.

## 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 6.04.00
    Copyright (c) GPL 2005-2020. 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-header=<header> (-b):
               filename holding the base class definition.

       --baseclass-preinclude=<header> (-H):
               preinclude header in the base-class header file.  Use [header] to
               include <header>, otherwise \"header\" will be included.

       --baseclass-skeleton=<skeleton> (-B):
               location of the baseclass header skeleton.

       --class-header=<header> (-c):
               filename holding the parser class definition.

       --class-name=<name>:
               the name of the generated C++ class.

       --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.

       --default-actions=<off|quiet|warn|std> (-d):
               unless 'off', add a $$ = $1 action block to production rules not
               defining final action blocks.

       --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).

       --flex:
               use the traditional `flex' interface.

       --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.

       --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 corresponding matched text,
               received from its lexcial scanner.

       --parsefun-skeleton=<parserskel> (-P):
               location of the parse function's skeleton.

       --parsefun-source=<source> (-p):
               filename holding the parse function's source.

       --polymorphic-code-skeleton=<skeleton> (-L):
               location of the non-inline polymorphic 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.

       --prompt:
               in combination with --debug: show a prompt before performing the
               next parse-cycle (caveat: the lexical scanner should not read from
               the standard input).

       --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-matched-text-function=<function call>:
               specifies the function to call returning the text matched by the
               lexical scanner when returning a token

       --scanner-token-function=<scanner token function>:
               specifies the function to call by the parser's lex() function
               returning the next token returned by the lexcial scanner (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.

       --tag-mismatches=<off|on>:
               unless 'off', issue a warning if no $$ statement was detected in an
               action block, or if no default $$ = $1 action can be added to a
               production rule without final action block, or if run-time a
               tag-mismatch is observed.

       --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:
               provide thread-safe access by polymorphic semantic values to the
               generated code's error-counter.

       --usage: produce this information (and terminate).

       --verbose (-V):
               generate verbose description of the analyzed grammar.

       --version (-v):
               display bisonc++'s version and terminate.

- Table of Contents
- Previous Chapter