$ npm install mona-parser
$ bower install mona
Note that the
bower version requires manually building the release.
You can also download a prebuilt
UMD version of
mona from the
return monasplitEndline eol;return monasplitcell monastring",";return monaorquotedCellmonatextmonanoneOf",\n\r";return monabetweenmonastring'"'monastring'"'monatextquotedChar;return monaormonanoneOf'"'monaandmonastring'""'monavalue'"';var str = monastring;return monaorstr"\n\r"str"\r\n"str"\n"str"\r""end of line";return monaparsecsv text;parseCSV'foo,"bar"\n"b""az",quux\n';// => [['foo', 'bar'], ['b"az', 'quux']]
Writing parsers with
mona involves writing a number of individually-testable
parser constructors which return parsers that
mona.parse() can then
execute. These smaller parsers are then combined in various ways, even provided
as part of libraries, in order to compose much larger, intricate parsers.
mona tries to do a decent job at reporting parsing failures when and where
they happen, and provides a number of facilities for reporting errors in a
- Short, readable, composable parsers
- Includes a library of useful parsers and combinators
- Returns arbitrary data from parsers, not necessarily a plain parse tree
- Human-readable error messages with source locations
- Facilities for improving your own parsers' error reports
- Supports context-sensitive parsing (see
- Supports asynchronous, incremental parsing with
- Node.js stream API support with
parseStream, including piping support
- Heavy test coverage (see
- Small footprint (less that 4kb gzipped and minified)
- Fully documented API
Documentation of the latest released version is
available here. Docs are also included with
npm release. You can build the docs yourself by running
npm install && make docs in the root of the source directory.
The documentation is currently organized as if
mona had multiple modules,
although all modules' APIs are exported through a single module/namespace,
mona. That means that
mona/api.parse() is available through
mona works by composing functions called
parsers. These functions are
created by so-called
parser constructors. Most of the
mona API exposes these
There are three primitive parsers in mona:
value()- results in its single argument, without consuming input.
fail()- fails unconditionally, without consuming input.
token()- consumes a single token, or character, from the input.
Simply creating a parser is not enough to execute a parser, though. We need to
parse function, to actually execute the parser on an input string:
monaparsemonavalue"foo" ""; // => "foo"monaparsemonafail ""; // => throws an exceptionmonaparsemonatoken "a"; // => "a"monaparsemonatoken ""; // => error, unexpected eof
These three parsers do not seem to get us much of anywhere, so we introduce our
bind() accepts a parser as its first argument,
and a function as its second argument. The function will be called with the
parser's result value only if the parser succeeds. The function must then
return another parser, which will be used to determine
monaparsemonabindmonatokenif character === "a"return monavalue"found an 'a'!";elsereturn monafail;"a"; // => "found an 'a'!"
bind(), of course, is just the beginning. Now that we know we can combine
parsers, we can play with some of
mona's fancier parsers and combinators. For
or combinator resolves to the first parser that succeeds, in the
order they were provided, or fails if none of those parsers succeeded:
monaparsemonaormonafail"nope"monafail"nope again"monavalue"this one!""";// => "this one!"
monaparsemonaormonafail"nope"monavalue"this one!"monavalue"but not this one""";// => "this one!"
and() is another basic combinator. It succeeds only if all its parsers
succeed, and resolves to the value of the last parser. Otherwise, it fails with
the first failed parser's error.
monaparsemonaandmonavalue"foo"monavalue"bar""";// => "bar"
Finally, there's the
not() combinator. It's important to note that, regardless
of its argument's result,
not() will not consume input... it must be combined
with something that does.
monaparsemonaandmonanotmonatoken monavalue"end of input" "";// => "end of input"
string() parser might come in handy: It results in a string matching a given
monaparsemonastring"foo" "foo";// => "foo"
And can of course be combined with some combinator to provide an alternative value:
monapparsemonaandmonastring"foo" monavalue"got a foo!" "foo";// => "got a foo!"
is() parser can also be used to succeed or fail depending on whether the
next token matches a particular predicate:
monaparsemonais return x === "a"; "a";// => "a"
Writing parsers by composing functions is perfectly fine and natural, and you
might get quite a feel for it, but sometimes it's nice to have something that
feels a bit more procedural. For situations like that, you can use
return monasequence// The s() function passed into `sequence()`'s callback// must be used to execute any parsers within the sequence.var open = smonastring"(";// open === "(" if the `string()` parser succeeds.var data = smonatoken;var close = smonastring")";// The `sequence()` callback must return another parser, just like `bind()`.// Also like `bind()`, it can `return fail()` to fail the parser.return monavaluedata;;monaparseparenthesized "(a)";// => "a"
We can generalize this parser into a combinator by accepting an arbitrary parser as an input:
return monasequencevar open = smonastring"(";var data = sparser; // Use the parser here!var close = smonastring")";return monavaluedata;;monaparseparenthesizedmonastring"foo!" "(foo!)";// => "foo!"
Note that if the given parser consumes closing parentheses, this will fail:
monaparseparenthesizedmonastring"something)" "(something)";// => error, unexpected EOF
Once you've got the basics down, you can explore
mona's API for more interesting parsers. A
variety of useful parsers are available for use, such as
collects the results of a parser into an array until the parser fails, or
float(), which parses a floating-point number and returns the actual
number. For more examples on how to use
mona to create parsers for actual
formats, take a look in the
examples/ directory included with the project,
which includes examples for
npm version includes a build/ directory with both pre-built and
minified UMD versions of
are loadable by both AMD and
CommonJS module systems. UMD will define
window.mona if neither AMD or CommonJS are used. To generate these files
bower, or if you fetched
mona from source, simply run:
$ npm install...dev dependencies installed...$ make
build/mona.min.js in your application.