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 is included in the apg-js. In a node.js project use: 

npm install apg-js
var apgExp = require("apg-js").apgExp;

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

<script src="./apg-js/dist/apg-exp-bundle.js" charset="utf-8"></script>

In any 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.

For many examples of its use see apg-js-examples at either GitHub or npmjs

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