bnf-plus-plus

bnf-plus-plus copied to clipboard

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 <[email protected]>

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 [email protected].

REPORTING BUGS Report bugs to [email protected].

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)