parcom is a consise Parser Combinator library in the style of Haskell’s parsec and Rust’s nom.
parcom operates strictly on strings, not streamed byte data, but is otherwise “zero copy” in that extracted substrings of the original input are not reallocated.
parcom has no dependencies.
- Compatibility
- API
- Writing your own Parsers
| SBCL | ✅ |
| ECL | ✅ |
| Clasp | ❓ |
| ABCL | ✅ |
| CCL | ✅ |
| Clisp | ✅ |
| Allegro | ✅ |
| LispWorks | ❓ |
The examples below use (in-package :parcom) for brevity, but it’s assumed that you’ll use a local nickname like pc in your actual code. Further, most examples run the parsers with parse, but occasionally funcall is used instead to demonstrate what the remaining input would be after the parse succeeded. You will generally be using parse in your own code.
All parsers have the function signature string -> parser, where parser is a struct that holds the value of the parsing success alongside the remaining input string.
Of course, a parser might fail, in which case a failure struct is returned:
In general though we call parse to fully run some combined parsers and yield the final output:
parse otherwise ignores any final, unconsumed input. It will also raise a Condition if the parsing failed.
A “parser” is a function that consumes some specific input and yields a single result.
Parse a given character.
Parse the given string.
Parse any character.
Parse any character expect the one you don’t want.
Parse a hex character of any case.
Recognize the end of the input.
Parse a positive integer into a fixnum.
Parse a positive or negative integer into a fixnum.
Parse a positive or negative floating point number into a float.
Matches a single newline character.
Parse 0 or more ASCII whitespace and tab characters.
Parse 1 or more ASCII whitespace and tab characters.
Parse 0 or more ASCII whitespace, tabs, newlines, and carriage returns.
Parse 1 or more ASCII whitespace, tabs, newlines, and carriage returns.
These always yield a substring borrowed directly from the original input.
Take n characters from the input.
Take characters while some predicate holds.
take-while1 is like take-while, but must yield at least one character.
Consume the rest of the input. Always succeeds.
“Combinators” combine child parsers together to form compound results. They allow us to express intent like “parse this then that” and “parse this, then maybe that, but only if…” etc.
Run multiple parsers one after another, but yield the value of the rightmost one. right is an alias.
Run multiple parsers one after another, but yield the value of the leftmost one. left is an alias.
Combination of parsers yielding all results as a list. all is an alias.
This library does not offer a currying mechanism, so the technique usually available in Haskell of fmap’ing a function over chain of <*> must be done instead with apply:
Run some parser, but substitute its inner value with something else if parsing was successful. instead is an alias.
Accept the results of the first parser from a group to succeed. Can combine as many parsers as you want.
Yield nil if the parser failed, but don’t fail the whole process nor consume any input.
A main parser flanked by two other ones. Only the value of the main parser is kept. Good for parsing backets, parentheses, etc.
many parses 0 or more occurrences of a parser. many1 demands that at least one parse succeeds or a Condition will be raised.
sep parses 0 or more instances of a parser separated by some sep parser. sep1 demands that at least one parse succeeds or a Condition will be raised.
Critically, if a separator is detected, the parent parser must also then succeed or the entire combination fails. For example, this will not parse due to the ! on the end:
For more lenient behaviour regarding the separator, see sep-end.
The same as sep, but the separator may appear at the end of the final “parent”. Likewise, sep-end1 demands that at least one parse of the parent succeeds.
Parse some parser 0 or more times, but throw away all the results.
Yield the value of a parser, but don’t consume the input.
Apply a parser a given number of times and collect the results as a list.
If the given parser was successful, return the consumed input as a string instead.
Is a given string empty?
Is a given character a number from 0 to 9?
Apply a pure function to the inner contents of a parser.
Yield a function that ignores its input and returns some original seed.
By depending on the optional parcom/json system, you can parse simple JSON or include parcom-compatible JSON parsers into your own custom parsing code.
(in-package :parcom/json) is used below for brevity, but it’s assumed that in your own code you will use a nickname, perhaps pj.
If you don’t care about the individual parsers per se and just want to simply parse some JSON, use parse.
Conversions:
| true | T |
| false | NIL |
| Array | Vector |
| Object | Hash Table |
| Number | double-float |
| String | String |
| null | :NULL |
As with the parent parcom library, parcom/json works strictly off of strings and makes no attempt to be clever or high-performance. For a more “industrial strength” JSON parsing library, see jzon. The strength of parcom/json is in its simplicity and light weight.
Attempt to parse any JSON value. Analogous to parse from the main library.
Non-ascii and unicode characters are supported:
Parse any kind of JSON (the actual parser).
There are other subparsers exposed, but they are left out here for brevity. Please consult the source code if you need them.
The whole point of Parser Combinators is that it becomes simple to write your own parsing functions. Recall that a “fully realized” parser has the signature string -> parser. In the simplest case, a parser of yours could look like:
Wherein you utilize the combinators provided by this library to build up composite parsers that are useful to you.
You can also parameterize your parsers, similar to parsers like take or combinators like count:
So, if your parser is parameterized by some initial argument, it has to return a lambda that accepts an input string.
You can use fail within more complex hand-written parsers to explicitly fail with your own diagnostics:
Notice the usage of parser-value to access the current inner success value of the parser result. parser-input is likewise used to access the remaining input.
English (US) ·