D 2016-11-20T05:37:07.435
L PComb
P e4a42ac9116755c6a56865f65c3be078d42c6464
U User
W 6335
<h1><i>PComb: a Parser Combinator library in TypeScript</i></h1>
<div><font size="3">A collection of general and specific-purpose parsers that
can be composed with combinator functions to very powerful effect.</font></div>
<div><i><br>
</i></div>
<h3><i>Parsers</i></h3>
<div><font size="3">A parser is a function that takes a <b>ParserInput</b>, a
<b>ParserOutput </b>and returns a <b>ParseResult</b>.</font></div>
<div>
<ul>
<li><font size="3"><i>lit -- </i>match a literal string of characters,
caselessly</font></li>
<li><font size="3"><i>numeric -- </i>match any single numeric character</font></li>
<li><font size="3"><i>whitespace -- </i>match any single whitespace character</font></li>
</ul></div>
<blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;">
<div>
<h4><i><font size="3">ParseResult</font></i></h4></div>
<div>
<div><font size="3">A <b>ParseResult </b>is a three-element tuple with these
values:</font></div></div></blockquote>
<div>
<div>
<ol>
<ol>
<li><font size="3">a <b>boolean </b>that indicates if the parser successfully
matched the input</font></li>
<li><font size="3">a copy of the <b>ParserInput </b>object that was passed in
with any matched test removed from the text property</font></li>
<li><font size="3">a copy of the <b>ParserOutput </b>object that was passed in
with any matched text appended to the matched array </font></li>
</ol>
</ol></div></div>
<blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;">
<div>
<div>
<h4><i><font size="3">ParserInput</font></i></h4></div></div>
<div>
<div><font size="3">The code that uses PComb must provide input to the library
with a class that implements the <b>ParserInput </b>interface:</font></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre>export interface ParserInput {</pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre></pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre> /** What is the text that is being parsed? */</pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre></pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre> text: string;</pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre></pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre> copy(): ParserInput;</pre>
</font></i></div></div>
<div>
<div><i><font face="Courier New" size="3">
<pre></pre>
</font></i></div></div>
<div>
<div><i><font size="3"><font face="Courier New"></font>
<pre><font face="Courier New">}</font></pre>
</font></i></div></div></blockquote>
<blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;">
<div>
<div><i><font size="3">
<h4>ParserOutput</h4></font></i></div></div>
<div>
<div>
<div><font size="3">Similarly to <b>ParserInput</b>, a class that implements
<b>ParserOutput </b>is provided by the calling code to record the units of text
that have been matched by individual parser as well to record any state that is
specific to the particular use:</font></div></div></div>
<div>
<div><i><font size="3">
<div>
<pre>export interface ParserOutput {</pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre></pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre> /** The text that was matched by the parser. */</pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre></pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre> matched: Array<string>;</pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre></pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre> copy(): ParserOutput;</pre>
</div></font></i></div></div>
<div>
<div><i><font size="3">
<div>
<pre></pre>
</div></font></i></div></div>
<div>
<div><i><font size="3"></font>
<div>
<pre><font size="3">}</font></pre>
</div></i></div></div></blockquote>
<div>
<div><i></i></div>
<h3><i>Combinators</i></h3></div>
<div><font size="3">A combinator is a higher-order function that takes one or
more <b>Parser </b>functions as input and produces a new function that wraps
and executes them in some particular way.</font></div>
<div>
<ul>
<li><font size="3"><i>or -- </i>matches one of a list of parsers. After one
Parser matches the input, the <b>or </b>exits with a success result.</font></li>
<li><font size="3"><i>and -- </i>match all of the listed parsers in order. If
one fails to match, the <b>and </b>exits with a failure result.</font></li>
<li><font size="3"><i>opt -- </i>optionally match a parser; always produces a
success result.</font></li>
<li><font size="3"><i>all -- </i>match the given single parser until matching
fails; return all matches as a single match. If the given Parser does not match
at least once, returns a failure result.</font></li>
<li><font size="3"><i>any -- </i>collect all input as a single match up to the
point that the provided parser matches. Always successful.</font></li>
<li><font size="3"><i>exact -- </i>require that the given parser consume all
available input; otherwise, parsing fails.</font></li>
<li><font size="3"><i>apply -- </i>execute the given <b>ParserAction</b> if
the given parser succeeds.</font></li>
</ul></div>
<h3><i>ParserAction</i></h3>
<div><font size="3">A <b>ParserAction </b>is a function that takes a string of
matched characters and a <b>ParserOutput </b>and returns a <b>ParserOutput</b>:</font></div>
<pre><i><font face="Courier New" size="3">export type ParserAction = (matchedText: string, output: ParserOutput) => ParserOutput;</font></i></pre>
<p><font size="3">If such a function is provided to a <b>Parser</b>, it will be
executed on a successful match. The returned <b>ParserOutput </b>object then
becomes the return value for the <b>Parser</b>. This mechanism allows calling
code to have use-specific state that is recorded and mutated on parser
matching.</font></p>
<p><font size="3"><br>
</font></p>
<p><font size="3">Interested?
<a href="/user/acrossland/repository/pcomb/wiki?name=Getting+Started">Get
Started</a> or check out the [API Reference].</font></p>
Z 6f92db8f9baf308d47fe8b9b1b80d3fe