expressive, composable parser combinators
npm install unparse-jsAnother parser combinator library for Javascript? Don't we have enough of those already???
That depends on what we want out of a parser library. My preferences are for parsers that:
- simple and clear definition of the parse model:
- inputs
- outputs
- backtracking
- (non)-deterministic
- prioritized choice
- no magic. Magic operators are often convenient, but it's more important --
and useful in the long run -- to be able to easily implement the magic in
terms of the model.
- doesn't hide important details -- but also doesn't force you to worry about
them unless you need to.
- provides not just complex parsers, but also the primitive. What are the most
basic parsers, out of which bigger ones are built?
- make parser composition easy. This means there needs to be
powerful operations for combining parsers, such as sequencing, monadic
sequencing, choice, and repetition.
- doesn't treat lexing as a special case. Lexing is no different from any
other kind of parsing, except for the complexity of the language (sometimes).
- compositional semantics. Parser behavior should be consistent -- it must not
depend on what context the parser is in.
- works with the language, not against it. Parsers should be able to take
advantage of a language's features and capabilities for abstraction --
including functions and objects. This means that it's easy to create new
parsers, as well as combinators, using the language's facilities.
- the result value of a successful parser is important. You have full control
over what value is generated. You don't have to deal with a parse tree
crammed with tons of useless junk or a mess of nested tuples. Generating the
result should be clean and simple.
- errors are a key aspect of useful parsers. How and when are they created,
and with what information (position, message explaining the reason)? Once
an error is created, how is it propagated? How do errors interact with the
parse model -- backtracking -- and with parser composition?
These are the issues that UnParse-js addresses and that differentiate it from
other parser libraries. Read on for more information!
UnParse-js is a library for building complex parsers. Parsers are created and
manipulated as Javascript objects, and are invoked using their parse method,
which takes two arguments:
- the token sequence that is being parsed
- the parsing state
The return value is one of three possible results:
- success, including:
- the remaining tokens
- new state
- result value
- failure, which indicates that the match failed
- error, which means that something bad happened and includes error information
Successful parses allow parsing to continue; failures allow parsing to backtrack
and try a different alternative; errors abort parsing immediately with relevant
error information to accurately indicate what and where the problem was.
UnParse-js supports monadic parsing, as well as combinators based on the Applicative,
Functor, MonadError, Alternative, and Traversable typeclasses, if you're familiar
with Haskell. It also supports lookahead and optional parses.
Best of all, since parsers are ordinary Javascript objects, they play by the rules.
You don't need any special knowledge or syntax to use them, they work just fine
with functions and classes, and you can put them in data structures.
UnParse-js avoids magic -- the kind of magic that makes it easy to do really simple
things, but hard to deal with actual real-world problems in a clean, sane way.
This allows UnParse-js to stay simple and focused and free of arbitrary restrictions.
You don't need to worry about it mucking with things behind your back!
Publishing a new version to npm:
- update version string in index.js
- update version number in package.json
- push code to github
- create annotated tag: git tag -a
- add release notes to tag in github
- npm publish
Found a bug? Need help figuring something out? Want a new feature? Feel free
to report anything using the github issue tracker, or email me directly at
mfenwick100 at gmail dot com