DELETEMACRO(file) NOUSERMACRO( setDebug lex yylex matched YYText file exceptionHandler lookup error) includefile(../../release.yo) htmlstyle(body)(color: #27408B; background: #FFFAF0) whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl)) DEFINEMACRO(lsoption)(3)(\ bf(--ARG1)=tt(ARG3) (bf(-ARG2))\ ) DEFINEMACRO(laoption)(2)(\ bf(--ARG1)=tt(ARG2)\ ) DEFINEMACRO(loption)(1)(\ bf(--ARG1)\ ) DEFINEMACRO(soption)(1)(\ bf(-ARG1)\ ) DEFINEMACRO(itx)(0)() DEFINEMACRO(itemlist)(1)(ARG1) DEFINEMACRO(bic)(0)(bf(bisonc++)) DEFINEMACRO(b)(0)(bf(bisonc++)) DEFINEMACRO(Bic)(0)(bf(Bisonc++)) DEFINEMACRO(Cpp)(0)(bf(C++)) DEFINEMACRO(prot)(0)(tt((prot))) DEFINEMACRO(itt)(1)(it() tt(ARG1)) DELETEMACRO(tt) DEFINEMACRO(tt)(1)(em(ARG1)) DEFINEMACRO(manpagetext)(0)() COMMENT( man-request, section, date, distribution file, general name) manpage(bisonc++)(1)(_CurYrs_)(bisonc++._CurVers_) (bisonc++ parser generator) COMMENT( man-request, larger title ) manpagename(bisonc++)(Generate a C++ parser class and parsing function) COMMENT( all other: add after () ) manpagesynopsis() bf(bisonc++) [OPTIONS] tt(grammar-file) manpagesection(DESCRIPTION) Bic() derives from previous work on bf(bison) by Alain Coetmeur (coetmeur@icdc.fr), who created in the early '90s a Cpp() class encapsulating the tt(yyparse) function as generated by the GNU-bf(bison) parser generator. Initial versions of bic() (up to version 0.92) wrapped Alain's program in a program offering a more modern user-interface, removing all old-style (bf(C)) tt(%define) directives from bf(bison++)'s input specification file (see below for an in-depth discussion of the differences between bf(bison++) and bic()). Starting with version 0.98, bic() is a complete rebuilt of the parser generator, closely following descriptions given in Aho, Sethi and Ullman's em(Dragon Book). Since version 0.98 bic() is a Cpp() program, rather than a bf(C) program generating bf(C++) code. Bic() expands the concepts initially implemented in bf(bison) and bf(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 bic() itself (e.g., the member function tt(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 bic() 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, bic()'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. bf(Overview of the contents of bisonc++'s man-pages) This man-page concentrates on the tt(bisonc++) program itself, offering the following sections: itemization( it() bf(DESCRIPTION): a short description of bic() and its roots; it() bf(FROM BISONC++ < 6.00.00 TO BISONC++ >= 6.00.00): required modifications when re-generating parsers; it() bf(OPTIONS): options supported by bic(). it() bf(QUICK START): a quick start overview about how to use bic(); it() bf(GENERATED FILES): files generated by bic() and their purposes it() bf(FILES): skeleton) files used by bic(); it() bf(SEE ALSO): references to other programs and documentation; it() bf(BUGS): some additional stuff that should not qualify as bugs. it() bf(ABOUT bisonc++): Some history; it() bf(AUTHOR): at the end of this man-page. ) The bf(bisonc++input)(7) man-page covers the details of the grammar-specification file. This man-page offers these sections: itemization( it() bf(DESCRIPTION): a short description of bic() and its grammar file(s); it() bf(DIRECTIVES): bic()'s grammar-specification directives; it() bf(POLYMORPHIC SEMANTIC VALUES): how to use polymorphic semantic values in parsers generated by bic(); it() bf(DOLLAR NOTATIONS): available $-shorthand notations with single, union, and polymorphic semantic value types. it() bf(RESTRICTIONS ON TOKEN NAMES): name restrictions for user-defined symbols; it() bf(OBSOLETE SYMBOLS): symbols available to bf(bison)(1), but not to bic(); it() bf(USING SYMBOLIC TOKENS IN CLASSES OTHER THAN THE PARSER CLASS); how to refer to tokens defined in the grammar; it() bf(EXAMPLE): an example of using bic(); it() bf(SEE ALSO): references to other programs and documentation; it() bf(AUTHOR): at the end of this man-page. ) The bf(bisonc++api)(3) describes the application programmer's interface, containing these sections: itemization( it() bf(DESCRIPTION): a short description of bic() and its application programmer's interface; it() bf(PUBLIC SYMBOLS): constructor, enums, members, and types that can be used by calling software; it() bf(PRIVATE ENUMS AND -TYPES): enumerations and types only available to the tt(Parser) class; it() bf(PRIVATE MEMBER FUNCTIONS): member functions that are only available to the tt(Parser) class; it() bf(PRIVATE DATA MEMBERS): data members that are only available to the tt(Parser) class; it() bf(TYPES AND VARIABLES IN THE ANONYMOUS NAMESPACE): an overview of the types and variables that are used to define and store the grammar-tables generated by bic(); it() bf(SEE ALSO): references to other programs and documentation; it() bf(AUTHOR): at the end of this man-page. ) manpagesection(FROM BISONC++ < 6.00.00 TO BISONC++ >= 6.00.00) This section is only relevant when re-generating parser code previously generated by bic() versions before 6.00.00. Bic() 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 bic() and accessible to the generated parser-class end in an underscore character. Member functions whose identifiers end in an underscore are `owned' by bic(), are rewritten each time bic() 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., tt(parser.h)) and some members are given default implementations in the parser's internal header file (e.g., tt(parser.ih)). Once generated, these files are left alone by bic(). Therefore, when using bic() version 6.00.00 or beyond to re-generate a parser which was originally generated by an earlier bic() version, the existing parser header and internal header files need some minor modifications: itemization( itt(void error(char const *)) was changed to tt(void error()). A default implementation is provided in the parser's internal header file. The current implementation directly inserts the text tt(Syntax error) into the standard output stream; itt(void exceptionHandler_(std::exception const &exc)) was changed to tt(void exceptionHandler(std::exception const &exc)). A default implementation is provided in the parser's internal header file, and only its trailing underscore characters need to be removed; itt(int lookup(bool recovery)): remove this member declaration from the previously generated parser class; it() The following members are declared without a trailing underscore character in the generated parser class. An underscore character should be added to their identifiers: tt(executeAction, errorRecovery, nextToken). it() The member tt(void nextCycle_()) must be declared in the private section of the generated parser class. ) Previously, several data members of the parser's base class were directly accessible to the parser class. Bic() 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: itemization( itt(d_token_): use tt(int token_()) instead; itt(d_state_): use tt(size_t state_()) instead; ) manpagesection(OPTIONS) includefile(../manual/invoking/options.yo) manpagesection(QUICK START) Bic() may be used as follows: itemization( it() First, define a plain grammar: no actions, just the rules. Refer to bic()'s manual and other sources (like Aho, Sethi and Ullman's book) for details about how to define and decorate grammars. it() Having defined the grammar and (usually) some directives (advice: always use the tt(%oken-path) directive) bic() is run, generating the essential elements of a parser class. See the next section for details about the files generated by bic(). it() No `macro style' tt(%define) declarations are required. Instead, the normal practice of defining class members in source files and declaring them in class header files can be followed when using bic(). Bic() concentrates on its main tasks: defining a parser class and implementing the parsing function tt(int parse), leaving all other parts of the parser class' definition to the programmer. it() Next, members required in addition to the bic()-generated member tt(parse) and its support functions must be implemented by the programmer, and declared in the parser's class header. At the very least a member tt(int lex) must be defined (a default implementation can be generated by bic()). it() The generated parser can now be used in a program. A very simple example would be: verb( int main() { Parser parser; return parser.parse(); } ) ) manpagesection(GENERATED FILES) Bic() may create the following files: itemization( it() A file containing the implementation of the member function tt(parse) and its support functions. The member tt(parse) is a public member that can be called to parse a token-sequence according to a specified LALR1 type of grammar. By default the implementations of these members are written on the file tt(parse.cc). The programmer should not modify the contents of this file; it is rewritten every time bic() is called. it() A file containing an initial setup of the parser class, containing the declaration of the public member tt(parse) and of its (private) support members. New members may safely be declared in the parser class, as it is only created by bic() if not yet existing, using the filename tt(.h) (where tt() is the the name of the defined parser class). it() A file containing the parser class' em(base class). This base class should not be modified by the programmer. It contains types defined by bic(), as well as several (protected) data members and member functions, which should not be redefined by the programmer. All symbolic parser terminal tokens are defined in this class, thereby escalating these definitions to a separate class (cf. Lakos, (2001)), which in turn prevents circular dependencies between the lexical scanner and the parser (here, circular dependencies may easily be encountered, as the parser needs access to the lexical scanner class when defining the lexical scanner as one of its data members, whereas the lexical scanner needs access to the parser class to know about the grammar's symbolic terminal tokens; escalation is a way out of such circular dependencies). By default this file is (re)written any time bic() is called, using the filename tt(base.h). it() A file containing an em(implementation header). The implementation header rather than the parser's class header file should be included by the parser's source files implementing member functions declared by the programmer. The implementation header first includes the parser class's header file, and then provides default in-line implementations for its members tt(error) and tt(print) (which may be altered by the programmer). The member tt(lex) may also receive a standard in-line implementation. Alternatively, its implementation can be provided by the programmer (see below). Any directives and/or namespace directives required for the proper compilation of the parser's additional member functions should be declared next. The implementation header is included by the file defining tt(parse). By default the implementation header is created if not yet existing, receiving the filename tt(.ih). it() A verbose description of the generated parser. This file is comparable to the verbose output file originally generated by bf(bison++). It is generated when the option tt(--verbose) or tt(-V) is provided. If so, bic() writes the file tt(.output), where tt() is the name of the file containing the grammar definition. ) manpagesection(FILES) itemization( it() bf(bisonc++base.h): skeleton of the parser's base class; it() bf(bisonc++.h): skeleton of the parser class; it() bf(bisonc++.ih): skeleton of the implementation header; it() bf(bisonc++.cc): skeleton of the member tt(parse); it() bf(bisonc++polymorphic): skeleton of the declarations used by tt(%polymorphic); it() bf(bisonc++polymorphic.code): skeleton of the non-inline implementations of the members declared in bf(bisonc++polymorphic). it() bf(debugdecl.in): skeleton declaring members of the parser's base class that are only required when the tt(debug) option or directive was specified. it() bf(debugfunctions1.in): skeleton defining the members declared in tt(debugdecl.in). it() bf(debugfunctions2.in): skeleton implementing tt(symbol_), which is only needed when the tt(print-tokens) option or directive was specified. it() bf(debugfunctions3.in): skeleton implementing tt(errorVerbose_), which is only needed when the tt(error-verbose) option or directive was specified. it() bf(debugincludes.in): skeleton specifying the header files tt(#include) directives that are required when the tt(debug) option or directive was specified. it() bf(debuglookup.in): skeleton containing extra code required in the tt(Parser::lookup) member when the tt(debug) option of directive was specified. it() bf(lex.in): skeleton implementing the tt(Parser::lex) function. it() bf(ltypedata.in): skeleton declaring the location variables it() bf(ltype.in): skeleton defining the default or user defined tt(LTYPE_). it() bf(print.in): skeleton implementing the actions of tt(Parser::print) if the tt(print-tokens) option or directive was specified. ) manpagesection(SEE ALSO) DEFINESYMBOL(manalso)(bf(bisonc++api)(3), bf(bisonc++input)(7)) includefile(seealso.yo) manpagesection(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 bic() >= 6.00.00. See the earlier section bf(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: itemization( it() Identifiers ending in an underscore; it() Any of the following identifiers: tt(ABORT, ACCEPT, ERROR, debug, error), or tt(setDebug). ) manpagesection(ABOUT bisonc++) bf(Bisonc++) was based on bf(bison++), originally developed by Alain Coetmeur (coetmeur@icdc.fr), R&D department (RDT), Informatique-CDC, France, who based his work on bf(bison), GNU version 1.21. Bic() 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 bf(Compilers) (i.e., the em(Dragon book)). It uses the same grammar specification as bf(bison) and bf(bison++), and it uses practically the same options and directives as bic() versions earlier than 0.98. Variables, declarations and macros that are obsolete were removed. Compared to tt(bison) and tt(bison++), the number and functions of the various tt(%define) declarations was thoroughly modified. All of tt(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., tt(%define DEBUG) is now declared as tt(%debug); tt(%define LSP_NEEDED) is now declared as tt(%lsp-needed) (note the hyphen). manpageauthor() Frank B. Brokken (f.b.brokken@rug.nl).