Visual BNF User's Manual
========================

Parser generator info
---------------------
Visual BNF generates LR(1) tables which are very fast when parsing and generating
syntax trees. Whole generator was written in .NET Framework with use of C# language.
This tool generates LR(1) tables and other lookup tables in output assembly (dll)
which is very easy to use by .NET framework 2.0 applications just by referencing
assembly.


What to do with parser generators
---------------------------------
Common tasks to use parser generator is for:
1) Generating new compilers and new languages support
2) Parsing weird input like emails or urls
3) Parsing mathematical expressions
4) Interpreting programs
5) Parsing scripts, batches (for example in games - programming mods and bots)
6) Parsing commandlines
...and much more other things.


Visual BNF language syntax
--------------------------
Writing BNF code for your language can be divided into four steps:
1) Writing parameters
example of parameter:
'Entry' = "BNF";

List of parameters available in VBNF:
'Entry' = "BNF";
'CaseInsensitive' = "True";

it means that 'Entry' is a parameter and this parameter defines an entry point for starting
production, default entry point is 'BNF' so you do not need to specify it.

2) Writing productions
example of production:
BNF ::= A | B "int" | NULL;

it means that 'BNF' is a production and it expects 'A' production or 'B' production
followed by 'int' terminal or just this production can be empty.

3) Writing charsets
example of charset:
{Ident} = {Letter} + ["_"];
-or-
{HexDigit} = {Digit} + ["abcdefABCDEF"];
-or-
{HexDigit} = {Digit} + ["a-fA-F"]
-or-
{LowerCaseLetters} = ["a-z"]
-or-
{AllExceptLetters} = ["^a-zA-Z"]    -> the sign '^' must be first there

it means that 'Ident' is a charset and it defines charset range as whole alphabet plus
an underscore, so 'Ident' can be a 'R' char or 's' char or '_' char.

there is default predefined charsets (can be substituted again) as:

{EOF}, {HT}, {LF}, {VT}, {FF}, {CR}, {Space}, {NBSP}, {Digit}, {Letter}, {Alphanumeric},
{Printable}, {Whitespace}, {ControlCharacters}, {LetterExtended}, {PrintableExtended}
and {All}, also there is many unicode language charsets as:

{LatinExtended}, {Greek}, {Cyrillic}, {CyrillicSupplementary}, {Armenian},
{Hebrew}, {Arabic}, {Syriac}, {Thaana}, {Devanagari}, {Bengali}, {Germukhi},
{Gujarati}, {Oriya}, {Tamil}, {Telugu}, {Kannada}, {Malayalam}, {Sinhala}, {Thai},
{Lao}, {Tibetan}, {Myanmar}, {Georgian}, {HangulJamo}, {Ethiopic}, {Cherokee}, {Ogham},
{Runic}, {Tagalog}, {Hanunoo}, {Buhid}, {Tagbanwa}, {Khmer}, {Mongolian},
{LatinExtendedAdditional}, {GreekExtended}, {Hiragana}, {Katakana}, {Bopomofo},
{Kanbun} and {BopomofoExtended}

Note: {EOF} and {Whitespace} charsets are used by predefined 'Eof' and 'Whitespace' terminals,
you can redefine them of course.


4) Writing terminals
example of terminal:
IDENTIFIER = {Ident}({Ident} | {Digit})*;
-or-
NULL_TERMINAL = "NULL";
-or-
LETTER = ["abcdefghijklmnopqrstuvwxyz"];

it means that 'IDENTIFIER' is a terminal and it expects {Ident} charset first and then
{Ident} or {Digit} charsets in loop. char '*' is a none, one, or more instances,
'+' is a one or more instances and '?' is none or one instance.

Note: 'Eof' and 'Whitespace' terminals are used internally for tokenizer, you can redefine
them of course.


Example of BNF syntax which is actually used by Visual BNF
----------------------------------------------------------
BNF ::= SYNTAX BNF | SYNTAX;
SYNTAX ::= PARAMS | CHARSETS | TERMINALS | PRODS;
PARAMS ::= "'" IDENTIFIER "'" "=" QUOTEDSTRING ";";
CHARSETS ::= "{" IDENTIFIER "}" "=" CHARSETS2 ";";
CHARSETS2 ::= NAMED_CHARSETS CHARSET_OP CHARSETS2 | CUSTOM_CHARSETS CHARSET_OP CHARSETS2 | NAMED_CHARSETS | CUSTOM_CHARSETS;
NAMED_CHARSETS ::= "{" IDENTIFIER "}";
CUSTOM_CHARSETS ::= "[" QUOTEDSTRING "]";
CHARSET_OP ::= "+" | "-";
TERMINALS ::= IDENTIFIER "=" TERM_ARG_OR ";";
TERM_ARG_OR ::= TERM_ARG_AND "|" TERM_ARG_OR | TERM_ARG_AND;
TERM_ARG_AND ::= TERM_ARG TERM_ARG_AND | TERM_ARG;
TERM_ARG ::= (QUOTEDSTRING | NAMED_CHARSETS | CUSTOM_CHARSETS | TERM_EXPR) TERM_OP;
TERM_OP ::= "?" | "+" | "*" | NULL;
TERM_EXPR ::= "(" TERM_ARG_OR ")";
PRODS ::= IDENTIFIER "::=" EXPR ";";
EXPR ::= OR;
OR ::= AND "|" OR | AND;
AND ::= OBJECT AND | OBJECT;
OBJECT ::= "(" EXPR ")" | "[" EXPR "]" | IDENTIFIER | QUOTEDSTRING | NULL_TERMINAL;
{Ident} = {Letter} + ["_"];
{Quoted} = {Printable} - ["\""] - ["\\"];
{HexDigit} = {Digit} + ["abcdefABCDEF"];
IDENTIFIER = {Ident}({Ident} | {Digit})*;
regular = ({Quoted} |
"\\" ({Quoted} | "0" | "\"" | "\\" |
["xX"] {HexDigit} {HexDigit} {HexDigit} {HexDigit}))+;
NULL_TERMINAL = "NULL";
QUOTEDSTRING = "\"" ({Quoted} |
"\\" ({Quoted} | "0" | "\"" | "\\" |
["xX"] {HexDigit} {HexDigit} {HexDigit} {HexDigit}))* "\"";

Warnings and Errors defined in VBNF
-----------------------------------
1) Scanner and Parser Info (these SCxxxx infos can be used in integrated application using VBNF)
a) SC0001 - invalid token
b) SC0002 - token expected
c) SC0003 - unexpected token
d) SC0004 - token expected
e) SC0005 - invalid expression term

2) SExxxx - semantic info

3) GExxxx - lalr table generation info
shift/reduce or reduce/reduce errors
see these terms at wikipedia to learn more info about


Application integration with Visual BNF generated assemblies
------------------------------------------------------------
To integrate your application with parsing tables and parsing engine you need two assemblies:
1) VisualBNFEngine.dll
which contains LRParser, Scanner, Tree, TreeSearch and other classes to use by your application.

2) Generated parse table assembly (generated as a build result of Visual BNF with your grammar)
which contains LR tables and other lookup tables which is used by VisualBNFEngine assembly


Using parsing framework library generated by Visual BNF with your application
-----------------------------------------------------------------------------
Visual BNF comes with example project that shows application integration.


Information for GUI compiler developers
---------------------------------------
Visual BNF API class provides support for developers who want to use Visual BNF compiler
in their compiler application, see class InterOpCompiler in VisualBNFAPI.dll
You can create your own IDE, that works same as Visual BNF application by this API


example:
--------

// note to add bnf.snk in your project!
InteropCompiler interopCompiler = new InteropCompiler();
string text = "BNF ::= \"test\" | \"visual\";";
if (interopCompiler.CheckSyntax(text))
{
  // use interopCompiler.Errors instance to obtain errors and interopCompiler.MaxErrors, use Dynamic
  // write out value from parse tree
  // note, use TreeSearch Intralogic.Compilers.VisualBNF.TreeSearch class to walk the tree
  Console.WriteLine(interopCompiler.Tree.ChildNodes[0].ValueName);
                
  if (interopCompiler.Compile(text))
  {                {
    // use interopCompiler.dynamicCompiler to see internal parse tables;
    if (interopCompiler.TestOutputGrammar("visual", false))
    {
      // write out value from parse tree
      // note, use TreeSearch Intralogic.Compilers.VisualBNF.TreeSearch class to walk the tree
      Console.WriteLine(interopCompiler.Tree.ChildNodes[0].ValueName);

      // generate parse table
      interopCompiler.GenerateParseTable("test.dll");
    }
  }
}

If you want to sell your product which contains VisualBNFAPI.dll then you need
a license from Intralogic.



Visual BNF Requirements
-----------------------
.NET Framework 2.0 runtime
.NET Framework SDK (csc compiler) or Visual Studio 2005 express or standard edition


===============================================================================================
Further information will be available on Intralogic website at http://www.intralogic.eu
If you have some questions about Visual BNF feel free to send us email at support@intralogic.eu

Copyright(c) 2007 Intralogic, all rights reserved.