apg-exp
Version:
(Deprecated: use apg-js instead.) Pattern-matching alternative to RegExp. Replaces the regular expression syntax with ABNF. Adds APG parser features such as User Defined Terminals (hand-written pattern matchers) and access to the AST.
133 lines (132 loc) • 5.21 kB
HTML
<html lang="en">
<head>
<title>apg-exp</title>
<meta charset="utf-8">
<link rel="stylesheet" href="./css/BrightSide.css" type="text/css" />
<script type="text/javascript" src="./import.js"></script>
</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>
<a href="https://github.com/ldthomas/apg-js2-exp"><b>apg-exp</b></a> 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 <a href="https://github.com/ldthomas/apg-js2">APG</a> as the underlying parser generator.
For usage of <b>APG</b> refer to the <a href="https://github.com/ldthomas/apg-js2">GitHub repository</a>
and <a href="http://coasttocoastresearch.com/docjs2/apg/index.html">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-js2-examples">repository</a> and
<a href="http://coasttocoastresearch.com/docjs2/apg-examples/index.html">documentation</a>.
</p>
<p>
For pattern syntax, refer to the <a href="https://github.com/ldthomas/apg-js2/blob/master/SABNF.md">SABNF</a> guide.
</p>
<p>
The <b>apg-exp</b> constructor can be acquired from <a href="https://github.com/ldthomas/apg-js2-exp">GitHub</a> or
<a href="https://www.npmjs.com/~ldthomas">npm</a>.
In a <a href="https://nodejs.org/en/">node.js</a> project use:
<pre>npm install apg-exp --save
var ApgExp = require("apg-exp");</pre>
</p>
<p>
To acquire the pre-defined constructor variable <kbd>ApgExp</kbd> in a web page use:
<pre>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></pre>
</p>
<p>
In either 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>
<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>
</html>