bisonc++(1)

bisonc++ parser generator
(bisonc++.6.00.00.tar.gz)

2005-2017

NAME

bisonc++ - Generate a C++ parser class and parsing function

SYNOPSIS

bisonc++ [OPTIONS] grammar-file

DESCRIPTION

Bisonc++ derives from previous work on bison by Alain Coetmeur (coetmeur@icdc.fr), who created in the early '90s a C++ class encapsulating the yyparse function as generated by the GNU-bison parser generator.

Initial versions of bisonc++ (up to version 0.92) wrapped Alain's program in a program offering a more modern user-interface, removing all old-style (C) %define directives from bison++'s input specification file (see below for an in-depth discussion of the differences between bison++ and bisonc++). Starting with version 0.98, bisonc++ is a complete rebuilt of the parser generator, closely following descriptions given in Aho, Sethi and Ullman's Dragon Book. Since version 0.98 bisonc++ is a C++ program, rather than a C program generating C++ code.

Bisonc++ expands the concepts initially implemented in bison and bison++, offering a cleaner setup of the generated parser class. The parser class is derived from a base-class, mainly containing the parser's token- and type-definitions as well as several member functions which should not be modified by the programmer.

Most of these base-class members might also be defined directly in the parser class, but were defined in the parser's base-class. This design results in a very lean parser class, declaring only members that are actually defined by the programmer or that have to be defined by bisonc++ itself (e.g., the member function parse as well as some support functions requiring access to facilities that are only available in the parser class itself, rather than in the parser's base class).

This design does not require any virtual members: the members which are not involved in the actual parsing process may always be (re)implemented directly by the programmer. Thus there is no need to apply or define virtual member functions.

Before version 5.00.00 bisonc++ offered one single manual page. The advantage of one man-page is of course that you never have to look for which manual page contains which information. But on the other hand, bisonc++'s man-page grew into a huge man-page of about 2000 lines in which it was hard to find your way. From release 5.00.00 onward, three man-pages. The index below relates manual pages to their specific contents.

Overview of the contents of bisonc++'s man-pages

This man-page concentrates on the bisonc++ program itself, offering the following sections:

files used by bisonc++;
  • SEE ALSO: references to other programs and documentation;
  • BUGS: some additional stuff that should not qualify as bugs.
  • ABOUT bisonc++: Some history;
  • AUTHOR: at the end of this man-page. )

    The bisonc++input(7) man-page covers the details of the grammar-specification file. This man-page offers these sections:

    The bisonc++api(3) describes the application programmer's interface, containing these sections:

    FROM BISONC++ < 6.00.00 TO BISONC++ >= 6.00.00

    This section is only relevant when re-generating parser code previously generated by bisonc++ versions before 6.00.00.

    Bisonc++ version 6.00.00 generates code that significantly differs from code generated by earlier versions. The identifiers of all members (both data and functions) that are generated by bisonc++ and accessible to the generated parser-class end in two underscore characters. Member functions whose identifiers end in two underscores are `owned' by bisonc++, are rewritten each time bisonc++ is run, and should not be modified. Some members are defined as members of the generated parser-class, and are declared in the parser class header file (e.g., parser.h) and some members are given default implementations in the parser's internal header file (e.g., parser.ih). Once generated, these files are left alone by bisonc++. Therefore, when using bisonc++ version 6.00.00 or beyond to re-generate a parser which was originally generated by an earlier bisonc++ version, the existing parser header and internal header files need some minor modifications:

    Previously, several data members of the parser's base class were directly accessible to the parser class. Bisonc++ version 6.00.00 restricts access to those members. They can still be read, but no longer modified by the parser class. This applies to the following members:

    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.

    QUICK START

    Bisonc++ may be used as follows:

    GENERATED FILES

    Bisonc++ may create the following files:

    FILES

    SEE ALSO

    bison(1), bison++(1), bisonc++api(3), bisonc++input(7), bison.info (using texinfo), flexc++(1), https://fbb-git.github.io/bisoncpp/

    Lakos, J. (2001) Large Scale C++ Software Design, Addison Wesley.
    Aho, A.V., Sethi, R., Ullman, J.D. (1986) Compilers, Addison Wesley.

    BUGS

    Parser-class header files (e.g., Parser.h) and parser-class internal header files (e.g., Parser.ih) generated with bisonc++ < 6.00.00 require several minor hand-modifications when re-generating the parser with bisonc++ >= 6.00.00. See the earlier section FROM BISONC++ < 6.00.00 TO BISONC++ >= 6.00.00 for details.

    To avoid collisions with names defined by the parser's (base) class, the following identifiers should not be used as token names:

    ABOUT bisonc++

    Bisonc++ was based on bison++, originally developed by Alain Coetmeur (coetmeur@icdc.fr), R&D department (RDT), Informatique-CDC, France, who based his work on bison, GNU version 1.21.

    Bisonc++ version 0.98 and beyond is a complete rewrite of an LALR-1 parser generator, closely following the construction process as described in Aho, Sethi and Ullman's (1986) book Compilers (i.e., the Dragon book). It uses the same grammar specification as bison and bison++, and it uses practically the same options and directives as bisonc++ versions earlier than 0.98. Variables, declarations and macros that are obsolete were removed.

    Compared to bison and bison++, the number and functions of the various %define declarations was thoroughly modified. All of bison's %define declarations were replaced by their (former) first arguments. Furthermore, `macro-style' declarations are not supported or required. Finally, all directives only use lower-case characters and do not contain underscore characters (but sometimes hyphens). E.g., %define DEBUG is now declared as %debug; %define LSP_NEEDED is now declared as %lsp-needed (note the hyphen).

    AUTHOR

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