buffer-apg-js
Version:
JavaScript APG, an ABNF Parser Generator
131 lines (130 loc) • 5.04 kB
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><script src="./apg-js/dist/apg-exp-bundle.js" charset="utf-8"></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>