hhy5277 / 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

See release notes

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. Some features have been primarily developed to support the new apg-exp pattern-matching application. A general description of how APG works is given here.

apg-exp 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

For command line usage:

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, version 3.0.0, Copyright (C) 2017 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'

For the GUI version:

git clone https://github.com/ldthomas/apg-js2.git apg
cd apg
(double click the apg.html file)

Examples

See apg-js2-examples for examples of running JavaScript APG 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 © 2017 Lowell D. Thomas, all rights reserved

License

Released with the BSD-3-Clause license.