etsangsplk / apg-js2

JavaScript APG Version 2.0. APG is an ABNF Parser Generator. It generates recursive-descent parsers from a superset of ABNF grammars.

##JavaScript APG

Description:

APG is an acronym for "ABNF Parser Generator". Originally written to generate parsers directly from ABNF syntax (RFC 5234) it has since grown to include a number of additional features requiring additional syntax terms. The resulting syntax is a superset of ABNF or SABNF. This version adds a number of new features to the last, primarily to support the new apg-exp pattern-matching application. A general description of how APG works is given here.

New features:

• Sub-string parsing - the option to parse only a sub-string of the entire input string.
• Positive and negative look around - the ability to look ahead or behind in the string to make parsing decisions based on what is or isn't found.
• Back referencing - phrase matching based on phrases previously matched to other rules or UDTs.
• Beginning and ending of string anchors - parsing decisions based on whether or not the sub-string includes the beginning and/or the ending of the full input string.
• Statistics and limits on the node tree depth and hit count. Recursive-descent parsers can have exponential parsing times for some grammars. Limits can be set to prevent run-away parsing.

Other features:

• User-Defined Terminals (UDTs). These are user-written code snippets for matching phrases that are difficult or impossible to define with the SABNF syntax. They make for an effectively Turing complete parser.
• The use of callback functions to keep the parser's action code separate from the grammar. User-written callback functions provide complete monitoring and flow control of the parser.
• Generation of Abstract Syntax Trees (ASTs) with optional XML formatting.
• Translation of the AST with user-written callback functions.
• Extensive tracing facility with updated output formatting for easier interpretation.
• Statistics gathering for a full picture of parse tree node coverage.
• Extensive attribute generation for an overview of the grammar's characteristics.
• APG and its parsers run as node.js, desktop cli functions.
• Parsers can easily be used in web page applications with tools such as browserify.

More complete explanations of these features can be found in the [SABNF](https://github.com/ldthomas/apg-js2/blob/master/SABNF.md) documentation, in the code file documentation and the [examples](https://github.com/ldthomas/apg-js2-examples).

Installation:
Requires node.js and npm.

git clone https://github.com/ldthomas/apg-js2.git apg
cd apg
npm install -g ./
apg -v

or just

npm install -g apg
apg -v

You should see something like:

JavaScript APG 2.0, Copyright (C) 2016 Lowell D. Thomas, all rights reserved

Note: If there is a name conflict on your system (for example, Automated Password Generator) there are a couple of options for resolving the conflict.

1. Make sure that the npm prefix (npm prefix -g) is left-most in the $PATH variable and clear the cache with
   hash -r
2. If the npm prefix is, say, /my/npm/prefix, create an alias
   alias apg='/my/npm/prefix/bin/apg'
3. You probably know other ways to do it better to your suiting.

APG is meant to be installed globally and used as a command line application. However, if you want a local copy you can use it as follows.

mkdir mylocal
cd mylocal
npm install apg
cd node_modules/apg

To run the locally installed copy:
node main.js args

Examples:
See apg-js2-examples for examples of running JavaScript APG 2.0 and the parsers it generates.

Documentation:
The documentation is in the code in docco format. To generate the documentation, from the package directory:

npm install -g docco
./docco-gen

View docs/index.html in any web browser to get started. Or view it on the APG website

Copyright:
Copyright © 2016 Lowell D. Thomas, all rights reserved

License:
Released with the BSD-3-Clause license.