μparse
A tiny parser combinator library.
μparse is a minimal parser combinator library, providing only a very basic set of functions for consuming text and building up more complicated pattern matchers. It is specifically not focused on providing a breadth of combinators, monadic APIs, or deep error reporting.
Installation
Install using npm:
$ npm install --save uparse
Usage
μparse exposes two base combinators for consuming text:
str
and char
.
These combinators consume a string and a character respectively. In addition we
have a number of combinators for building up more interesting parsers:
seq
, rep
,
opt
, alt
, and
ref
. Lastly, parse
takes a parser
and a string to apply the parser to. Matches return a nested object structure
containing the matched substring values, while misses return null
.
See the API section for more information on each of these functions.
var P = ; var number = Palt // Either 0 P // Or a digit 0-9 followed by zero or more digits 0-9 P;var number = PaltP P; P;//=> null P;//=> null P;//=> null P;//=> { alt://-> { seq://-> [ { char: '2' },//-> { rep: [ { char: '0' }, { char: '1' }, { char: '7' } ] } ] } }
API
WARNING: Unstable
This API hasn't been fully vetted yet, and is subject to change before 1.0.0.
parse(parser, string)
The parse
function accepts a μparse parser (see below) and a string to
apply the parser to. If the parser successfully matches the string, the details
of what was matched are returned. Otherwise, the return value is null
.
str(string, [formatter])
The str
combinator accepts a string and an optional formatter function and
returns a parser that consumes the exact string given.
The formatter function may be specified to map the return value of a success.
By default, matches on str
will return { str: 'the matched text' }
.
var hello = P; P;//=> { str: "hello" } P;//=> null
char(characterClass, [formatter])
The char
combinator accepts a character class (e.g., " ", "0-9", "a-z", etc.)
and an optional formatter function and returns a parser that consumes a single
character that matches the given character class.
The formatter function may be specified to map the return value of a success.
By default, matches on char
will return { char: 'c' }
, where 'c'
is the
matched character.
var digit = P; P;//=> { char: "3" } P;//=> null
seq(parsers, [formatter])
The seq
combinator accepts an array of parsers and an optional formatter
function and returns a parser that matches against each of the given parsers in
turn. The parser only succeeds if the entire parser sequence succeeds, in the
order given.
The optional formatter function may be specified to map the return value of a
success. By default, matches on seq
will return
{ seq: [<results of inner parsers>] }
.
var helloWorld = P; P;//=> { seq: [ { str: "hello" },//-> { str: " world" } ] } P;//=> null
rep(parser, n, [formatter])
The rep
combinator accepts a parser, a number of minimum times to match the
parser, and an optional formatter function. The returned parser matches the
given parser repeatedly, as many times as possible. The parser only succeeds if
the number of successful matches meets the minimum number specified.
rep
may be familiar to those who are familiar with regular expression *
and
+
operators. To replicate these operators, n
should be specified as 0
or
1
respectively.
The formatter function may be specified to map the return value of a success.
By default, matches on rep
will return
{ rep: [<results of inner parsers>] }
.
var number = P; P;//=> { rep: [ { char: "4" },//-> { char: "2" } ] } P;//=> null
opt(parser, [formatter])
The opt
combinator accepts a parser and an optional formatter function and
returns a parser that succeeds if the given parser matches zero or one times.
The formatter function may be specified to map the return value of a success.
By default, matches on opt
will return
{ opt: <results of optional parser> }
, where <results of optional parser>
will be exactly that if matched once, and null
if matched 0 times.
var maybePlus = P; P;//=> { opt: { str: "+" } } P;//=> { opt: null } P;//=> null
alt(parsers, [formatter])
The alt
combinator accepts an array of parsers and an optional formatter
function and returns a parser that matches against each of the given parsers in
turn, immediately succeeding and consuming the match for the first parser that
succeeds.
The optional formatter function may be specified to map the return value of a
success. By default, matches on alt
will return
{ alt: <result of matched parser> }
.
var unit = PaltP P P; P;//=> { alt: { str: "celsius" } } P;//=> null
ref(context, name)
The final combinator, ref
, is very different from the others, and exists to
solve the problem of defining parsers for recursive patterns. The ref
combinator accepts a context object and the name of a key on the context
object. The returned parser will then lazily look up the given name on the
context object, treating the corresponding value to be the parser to use at
evaluation time when needed.
var context = hello: P ;contexthelloRef = P; P;//=> { str: "hello" } P;//=> null
License
MIT