BNF++(1)                          User Commands                            BNF++(1)



NAME
       bnf++ - C++ langugage parser generator for BNF syntax

DESCRIPTION
       BNF++ is a parser generator. It accepts BNF syntax grammar at input and
       generates parser class written in C++.

       BNF++  useful  to  generate  parsers from RFC definitions of syntax.
       RFC uses Augmented Backus-Naur Form (ABNF) notation specified in RFC2234
       (ftp://ftp.rfc-editor.org/in-notes/rfc2234.txt).
       With small changes, this notation can be rewritten in syntax acceptable
       by BNF++.  *Note BNF syntax::, for details.

       Any BNF++ entity becomes a virtual method of parser class. It can be
       overloaded in derived classes. Overloading of base methods (char comparison,
       substring search, eoi detection or etc) also supported.  It is possible
       to use user defined methods in any part of syntax definition (they declared
       as abstract in parser). *Note Parser::, for details.

       BNF++ parsers use STL string container as input (planned to add STL stream
       input possibility).
       
       (c) virtan <virtan@virtan.com>

   Usage:
              bnf++ [--user-value[=type]] [--with-template] [--output=filename_wo_ext]
                    [--templates-dir=dir] [--debug] source

OPTIONS
       --user-value[=type] add definition of additional argument for user
              value to all methods of parser (for non-template parsers also specify
              it's type)

       --with-template
              generate template for parser class template parameters are string and
              user value if exists

       --output=filename_wo_ext specify name for output files (without
              extension) if omitted bnf++ will use parser's classname

       --debug
              make parser with debug output: during execution parser prints the name
              of each called method to std::cerr

BNF SYNTAX
       BNF++ uses the following syntax of input BNF.

       Whole document consist of four parts: "above lines", class definition, bnf grammar
       and "below lines".

       "Above lines" and "below lines" are strings of free text which are directly passed
       to result header file (at head and tail accordingly).

       The class definition is a string of syntax:

            class name_of_class ;

       BNF grammar part contains any number of assignment rules. All of them has syntax:

            <entity> ::= <entity_body> ;

       The  entity in syntax above is a name of grammar entity (became a function member
       in parser class). Each entity defines possible structure of input which can be parsed.
       The entity_body is a sequence of expressions. Entity_body is an expression itself.
       Expressions uses the following logic:

          sequence    <expr1> <expr2> <expr3>   expression consist of
          .           ...                       specified expressions
          .                                     in specified order
          alternative <expr1> | <expr2> |       expression consist of any
          .           <expr3> | ...             (checked in order of given) of
          .                                     expressions
          grouping    ( <expression> )          grouping of expressions
          .                                     (useful with alternatives,
          .                                     repetition, option, etc)
          option      [ <expression> ]          optionality of expression
          repetition  { <expression> }          repetition of expression (1 or
          .                                     more times of repeat)

       Expression can be or include terminals. Possible terminals:

          .            any symbol
          'c'          specified symbol
          "abc"        string of symbols
          !            "not" - inversing of following expression item
          <a-z0-9_->   range of acceptable symbols (like [] in regexp)
          eoi          end of input status (has zero length)

       Spaces are not neccessary, when not ambiguous. Escaping in symbols and strings as in C.
       Ranges acceps backslash-octal-value escaping.

PARSER
       Generated parser is a C++ class (or template of classes).

       Constructor accepts constant reference to string and start/end position.

       Class contains service, parser, auxiliary and abstract methods.

       Service methods are used to detect terminals or end of input.

       Parser methods have same names as bnf entities and used to detect
       correspondent pattern.

       Auxiliary methods usually called from parser methods. They exist due to
       construction logic of parser methods code.

       Abstract methods are not defined in parser class. They are entities not
       defined in BNF++ syntax file. To use such entities it is needed to instantiate
       from parser class and define them.

       Template version of parser class lets specify type of string container
       and type of user value.

       User value is transparent variable which bypassed throw any service, parser,
       auxiliary or abstract method. Usually it is used to collect values of
       specified entities.

            Note: When using templates remember that definitions of template
            class methods must be included with their declarations together.

RUNNING
       To run BNF++ just type

       `bnf++ [--user-value[=type]] [--with-template] [--output=filename_wo_ext]
              [--debug] source'

       The only needed argument is BNF++ syntax source.

       Result header and C++ source filenames are constructed using class name if
       --output argument not specified. Extensions .h and .cc added to header and
       C++ source files accordingly.

       Argument --with-template turns template generation on.

       Argument --user-value addes user value to all members. When not using template
       generation, Type is a type of user value variable (default: int).

       The --debug argument addes debug information printing in each member of
       parser class (entering and leaving of method and result).

EXAMPLE
       BNF++ parser itself based on BNF++ syntax grammar. See sources
       (http://www.virtan.com/projects/bnf++/).

       There are:

       `bnf++.bnf++'
            BNF++ grammar. Defines bnf_plusplus_parser class.

       `bnf++parser.h, bnf++parser.cc'
            Generated parser. The bnf_plusplus_parser class itself.

       `bnf++gen.h, bnf++gen.cc'
            Derived class. Inherits bnf_plusplus_parser class.

TO DO
       Plans for future:

         1. Change realization of range checking to bit-field tables.

         2. Add checking (and removing) of duplicate auxiliary functions.

         3. Research of enhance compilation optimization.

         4. Stream input support.

AUTHOR
       Written by virtan <virtan@virtan.com>.

REPORTING BUGS
       Report bugs to <bnf_plusplus.bugs@virtan.com>.

COPYRIGHT
       Copyright (C) 2005 Free Software Foundation, Inc.  This is free software;
       see the source for copying conditions. There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
       The full documentation for bnf++ is maintained as a Texinfo manual. If the info
       and bnf++ programs are properly installed at your site, the command

              info bnf++

       should give you access to the complete manual.



bnf++ version 1.1                  July 2005                                   BNF++(1)