headerphoto

ApgExp Constructor

apg-exp is a pattern-matching engine designed to have the look and feel of JavaScript's RegExp but to use the SABNF syntax (a superset of ABNF) for pattern definitions.

apg-exp uses APG as the underlying parser generator. For usage of APG refer to the GitHub repository and documentation. A large number of examples of APG usage can be found in the examples repository and documentation.

For pattern syntax, refer to the SABNF guide.

The apg-exp constructor can be acquired from GitHub or npm. In a node.js project use:

npm install apg-exp --save
var ApgExp = require("apg-exp");

To acquire the pre-defined constructor variable ApgExp in a web page use:

git clone https://github.com/ldthomas/apg-js2-exp.git repo
<script src="./repo/apgexp.js" charset="utf-8"></script>
/* or for the minimized version */  
<script src="./repo/apgexp-min.js" charset="utf-8"></script>

In either case, it will be assumed throughout the remainder of this guide that the apg-exp constructor is available in the user's code as ApgExp.

Syntax

var exp = new ApgExp(pattern[, flags[, nodeHits[, treeDepth]]])

Parameters

  • pattern: string or object
    • string - a valid SABNF pattern syntax
    • object - an instantiated APG parser object
  • flags: string, any of the characters "gyud"
    • default - Sets lastIndex to zero after each match attempt.
    • g - global Advances lastIndex after each successful match.
    • y - sticky Anchors the search to lastIndex. Advances lastIndex on each successful match.
    • u - unicode Returns matched patterns as integer arrays of character codes, rather than strings
    • d - debug Adds the APG trace object to exp.
  • nodeHits: integer > 0: default: Infinity
    • Constrains the maximum number of parser steps taken to nodeHits. Can be used to protect against "exponential-time" or "catestrophic-backtracking" pattern syntaxes.
  • treeDepth: integer > 0: default: Infinity
    • Constrains the maximum parse tree depth to treeDepth. Can be used to protect against "exponential-time" or "catestrophic-backtracking" pattern syntaxes.

Return

Returns the instantiated apg-exp object.

An ApgExpError exception is thrown on any encountered error.

Examples

Pattern syntax as a string:

var exp = new ApgExp('pattern = "abc"\n');
var result = exp.test("abc"); /* result -> true */
    result = exp.test("xyz"); /* result -> false */

Pattern syntax as an object:

/* example.bnf file */
pattern = "abc"\n
/* generate APG parser */
npm install apg -g
apg -in example.bnf -js example.js
/* application */    
var pattern = require("./example.js");
var obj = new pattern();    
var exp = new ApgExp(obj);
var result = exp.test("abc"); /* result -> true */
    result = exp.test("xyz"); /* result -> false */