• Table of Contents
• Previous Chapter

Chapter 9: Invoking Bisonc++

9.1: Bisonc++ options

• --analyze-only (-A)
  Only analyze the grammar. No files are (re)written. This option can be used to test the grammatical correctness of modification `in situ', without overwriting previously generated files. If the grammar contains syntactic errors only syntax analysis is performed.
• --baseclass-preinclude=header (-H)
  Use header as the pathname to the file preincluded in the parser's base-class header. This option is useful in situations where the base class header file refers to types which might not yet be known. E.g., with %union a std::string * field might be used. Since the class std::string might not yet be known to the compiler once it processes the base class header file we need a way to inform the compiler about these classes and types. The suggested procedure is to use a pre-include header file declaring the required types. By default header will be surrounded by double quotes (using, e.g., #include "header"). When the argument is surrounded by pointed brackets #include <header> will be included. In the latter case, quotes might be required to escape interpretation by the shell (e.g., using -H '<header>').
• --baseclass-header=header (-b)
  Use header as the pathname of the file containing 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-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 containing the parser class. Defaults to the name of the parser class plus the suffix .h
• --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. The environment variable BISON_SIMPLE_H is not inspected anymore.
• --construction
  This option may be specified to write details about the construction of the parsing tables to the standard output stream. This information is primarily useful for developers, and augments the information written to the verbose grammar output file, produced 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. Note that no #ifdef DEBUG macros are used anymore. By rerunning bisonc++() without the --debug option an equivalent parser is generated not containing 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).
• --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 containing 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.
• --include-only
  All grammar files will be concatenated to the standard output stream in their order of processing. Following this, bisonc++ terminates.
• --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 specified if objects or variables of the semantic value type STYPE__ can be inserted into ostreams.
• --lines (-l)
  Put #line preprocessor directives in the file containing the parser's parse() function. By including this option the compiler and debuggers will associate errors with lines in your grammar specification file, rather than with the source file containing the parse() function itself.
• --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. This option is primarily useful in combination with the %lines directive, to suppress that directive. It also overrides option --lines, though.
• --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.
• --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. The environment variable BISON_SIMPLE is not inspected anymore.
• --parsefun-source=source (-p)
  Define source as the name of the source file containing the parser member function parse(). Defaults to parse.cc.
• --required-tokens=value
  Whenever a syntactic error is detected during the parsing process the next few tokens that are received by the parsing function may easily cause yet another (spurious) syntactic error. The option --required-tokens (as well as the directive %requireed-tokens) can be used to specify the number of tokens that must have been successfully processed before the parsing function reports another syntactic error. By default the number of required tokens is initialized to 0.
• --print=matched-text-function
  The print option provides an implementation of the Parser class's print function displaying the current token value and the text matched by the lexical scanner as received by the generated parse function. The option value matched-text-function must be set to a function call expression returning the matched text. E.g.,

  
      --print="d_scanner.YYText()"
                  
  

  If the matched text needs editing (e.g., newlines should be displayed as \n) then a wrapper function around the `real' function returning the text as matched by the scanner may be specified here.
• --scanner=header (-s)
  Use header as the pathname to the file defining a class Scanner, offering a member int yylex() producing the next token from the input stream to be analyzed by the parser generated by bisonc++(). When this option is used the parser's member int lex() will be predefined as

  
      int lex()
      {
          return d_scanner.yylex();
      }
                  
  

  and an object Scanner d_scanner will be composed into the parser. The d_scanner object will be constructed using its default constructor. If another constructor is required, the parser class may be provided with an appropriate (overloaded) parser constructor after having constructed the default parser class header file using bisonc++(). By default header will be surrounded by double quotes (using, e.g., #include "header"). When the argument is surrounded by pointed brackets #include <header> will be included. In the latter case, quotes might be required to escape interpretation by the shell (e.g., using -s '<header>').
• --scanner-debug
  Show de scanner's matched rules and returned tokens.
• --scanner-token-function=function-call
  The scanner function returning the next token, called from the generated parser's lex function. A complete function call expression should be provided (including a scanner object, if used). This option overrules the d_scanner.yylex() call used by default when the %scanner directive is specified. Example:

  
      --scanner-token-function="d_scanner.lex()"
                  
  

• --show-filenames
  Write the names of the files that are generated to the standard error stream.
• --skeleton-directory=directory
  Specifies the directory containing the skeleton files to use. This option can be overridden by the specific skeleton-specifying options (-B -C, -H, and -I).
• --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. By default it will not be created, but if requested it will receive the filename <grammar>.output, where <grammar> is the name of the file containing the grammar definition (i.e, the file passed as argument to bisonc++()).
• --version (-v)
  Display bisonc++()'s version number and terminate.

9.2: Bisonc++ usage

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

LALR(1) Parser Generator V 2.7.0
Copyright (c) GPL 2005-2010. 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 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.
   --lines (-l): 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().
   --parser-skeleton=<parserskel> (-P):
           location of the parse function's skeleton.
   --parsefun-source=<source> (-p):
           filename holding the parse function's source.
   --print=<scanner match function>:
           the print() member displays the tokens and their matched
           text, retrieved by <scanner match function>.
   --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: show the rules and returned tokens returned by
           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.

• Table of Contents
• Previous Chapter