UNPKG

buffer-apg-js

Version:

JavaScript APG, an ABNF Parser Generator

131 lines (130 loc) 5.04 kB
<!DOCTYPE html> <html lang="en"> <head> <title>apg-exp</title> <meta charset="utf-8"> <link rel="stylesheet" href="./css/BrightSide.css" type="text/css" /> </head> <body> <div id="wrap"> <div id="header"></div> <div id="content-wrap"> <img src="./images/PointLobosCropped.jpg" width="820" height="120" alt="headerphoto" class="no-border" /> <div id="sidebar"></div> <div id="main-2col"> <h1>apgExp Constructor</h1> <p> </p> <p> <b>apg-exp</b> is a pattern-matching engine designed to have the look and feel of JavaScript's <a href="http://www.w3schools.com/jsref/jsref_obj_regexp.asp">RegExp</a> but to use the <a href="https://github.com/ldthomas/apg-js2/blob/master/SABNF.md">SABNF</a> syntax (a superset of <a href="https://tools.ietf.org/html/rfc5234">ABNF</a>) for pattern definitions. </p> <p> <b>apg-exp</b> uses APG as the underlying parser generator. For usage of <b>APG</b> refer to the <a href="https://github.com/ldthomas/apg-js">GitHub repository</a> and <a href="https://sabnf.com/documentation-2/">documentation</a>. A large number of examples of <b>APG</b> usage can be found in the examples <a href="https://github.com/ldthomas/apg-js-examples">repository</a> and <a href="https://sabnf.com/documentation-2/">documentation</a>. </p> <p> For pattern syntax, refer to the <a href="https://sabnf.com/docs/doc7.0/index.html">SABNF</a> guide. </p> <p> The <b>apg-exp</b> constructor is included in the <a href="https://www.npmjs.com/package/apg-js">apg-js</a>. In a <a href="https://nodejs.org/en/">node.js</a> project use: <pre>npm install apg-js var apgExp = require("apg-js").apgExp;</pre> </p> <p> To acquire the pre-defined constructor variable <kbd>apgExp</kbd> in a web page use: <pre>&lt;script src="./apg-js/dist/apg-exp-bundle.js" charset="utf-8">&lt;/script></pre> </p> <p> In any case, it will be assumed throughout the remainder of this guide that the <b>apg-exp</b> constructor is available in the user's code as <kbd>apgExp</kbd>. </p> <p>For many examples of its use see <kbd>apg-js-examples</kbd> at either <a href="https://github.com/ldthomas/apg-js-examples">GitHub</a> or <a href="https://www.npmjs.com/package/apg-js-examples">npmjs</a></p> <h3>Syntax</h3> <p> <pre>var exp = new apgExp(pattern[, flags[, nodeHits[, treeDepth]]])</pre> </p> <h3>Parameters</h3> <p> <ul> <li> <b>pattern:</b> string or object </li> <ul> <li>string - a valid SABNF pattern syntax</li> <li>object - an instantiated <b>APG</b> parser object</li> </ul> <li> <b><a href="./flags.html">flags</a>:</b> string, any of the characters "gyud" </li> <ul> <li>default - Sets <kbd><a href="./lastIndex.html">lastIndex</a></kbd> to zero after each match attempt.</li> <li>g - <a href="./global.html">global</a> Advances lastIndex after each successful match. </li> <li>y - <a href="./sticky.html">sticky</a> Anchors the search to <kbd>lastIndex</kbd>. Advances <kbd>lastIndex</kbd> on each successful match.</li> <li>u - <a href="./unicode.html">unicode</a> Returns matched patterns as integer arrays of character codes, rather than strings</li> <li>d - <a href="./debug.html">debug</a> Adds the <b>APG</b> trace object to exp.</li> </ul> <ul> </ul> <li> <b><a href="./nodeHits.html">nodeHits</a>:</b> integer > 0: default: <kbd>Infinity</kbd> </li> <ul> <li>Constrains the maximum number of parser steps taken to nodeHits. Can be used to protect against "exponential-time" or "catestrophic-backtracking" pattern syntaxes.</li> </ul> <li> <b><a href="./nodeHits.html">treeDepth</a>:</b> integer > 0: default: <kbd>Infinity</kbd> </li> <ul> <li>Constrains the maximum parse tree depth to treeDepth. Can be used to protect against "exponential-time" or "catestrophic-backtracking" pattern syntaxes.</li> </ul> </ul> </p> <h3>Return</h3> <p> Returns the instantiated <b>apg-exp</b> object. </p> <p> An <a href="./apgExpError.html">ApgExpError</a> exception is thrown on any encountered error. </p> <h3>Examples</h3> <p> Pattern syntax as a string: <pre>var exp = new apgExp('pattern = "abc"\n'); var result = exp.test("abc"); /* result -> true */ result = exp.test("xyz"); /* result -> false */</pre> </p> <p> Pattern syntax as an object: <pre>/* 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 */</pre> </p> </div> </div> <div id="footer"></div> </div> </body> <script type="text/javascript" src="./import.js"></script> </html>