Parsec.el

#+TITLE: parsec.el

A parser combinator library for Emacs Lisp similar to Haskell's Parsec library.

• Overview

This work is based on [[https://github.com/jwiegley/][John Wiegley]]'s [[https://github.com/jwiegley/emacs-pl][emacs-pl]]. The original [[https://github.com/jwiegley/emacs-pl][emacs-pl]] is awesome, but I found following problems when I tried to use it:

• It only contains a very limited set of combinators
• Some of its functions (combinators) have different behaviors than their Haskell counterparts
• It can't show error messages when parsing fails

So I decided to make a new library on top of it. This library, however, contains most of the parser combinators in =Text.Parsec.Combinator=, which should be enough in most use cases. Of course more combinators can be added if necessary! Most of the parser combinators have the same behavior as their Haskell counterparts. =parsec.el= also comes with a simple error handling mechanism so that it can display an error message showing how the parser fails.

So we can

• use these parser combinators to write parsers easily from scratch in Emacs Lisp like what we can do in Haskell
• port existing Haskell program using Parsec to its equivalent Emacs Lisp program easily

• Parsing Functions & Parser Combinators

  We compare the functions and macros defined in this library with their Haskell counterparts, assuming you're already familiar with Haskell's Parsec. If you don't have any experience with parser combinators, look at the docstrings of these functions and macros and try them to see the results! They are really easy to learn and use!

  The Usage column for each function/combinator in the following tables is much simplified. Check the docstring of the function/combinator to see the full description.

** Basic Parsing Functions These parsing functions are used as the basic building block for a parser. By default, their return value is a string.

| parsec.el | Haskell's Parsec | Usage | |------------------------+------------------+-------------------------------------------------------| | parsec-ch | char | parse a character | | parsec-any-ch | anyChar | parse an arbitrary character | | parsec-satisfy | satisfy | parse a character satisfying a predicate | | parsec-newline | newline | parse '\n' | | parsec-crlf | crlf | parse '\r\n' | | parsec-eol | eol | parse newline or CRLF | | parsec-eof, parsec-eob | eof | parse end of file | | parsec-eol-or-eof | N/A | parse EOL or EOF | | parsec-re | N/A | parse using a regular expression | | parsec-one-of | oneOf | parse one of the characters | | parsec-none-of | noneOf | parse any character other than the supplied ones | | parsec-str | N/A | parse a string but consume input only when successful | | parsec-string | string | parse a string and consume input for partial matches | | parsec-num | N/A | parse a number | | parsec-letter | letter | parse a letter | | parsec-digit | digit | parse a digit |

Note:

• =parsec-str= and =parsec-string= are different. =parsec-string= behaves the same as =string= in Haskell, and =parsec-str= is more like combining =string= and =try= in Haskell. Personally I found =parsec-str= easier to use because =parsec-str= is "atomic", which is similar to =parsec-ch=.
• Use the power of regular expressions provided by =parsec-re= and simplify the parser!

** Parser Combinators These combinators can be used to combine different parsers.

| parsec.el | Haskell's Parsec | Usage | |---------------------------+------------------+--------------------------------------------------------------| | parsec-or | choice | try the parsers until one succeeds | | parsec-try | try | try parser and consume no input when an error occurs | | parsec-lookahead | lookahead | try parser and consume no input when successful | | parsec-peek | try && lookahead | try parser without comsuming any input | | parsec-peek-p | try && lookahead | same as parsec-peek except the return value for failure | | parsec-with-error-message | <?> (similar) | use the new error message when an error occurs | | parsec-many | many | apply the parser zero or more times | | parsec-many1 | many1 | apply the parser one or more times | | parsec-many-till | manyTill | apply parser zero or more times until end succeeds | | parsec-until | N/A | parse until end succeeds | | parsec-not-followed-by | notFollowedBy | succeed when the parser fails | | parsec-endby | endby | apply parser zero or more times, separated and ended by end | | parsec-sepby | sepby | apply parser zero or more times, separated by sep | | parsec-between | between | apply parser between open and close | | parsec-count | count | apply parser n times | | parsec-option | option | apply parser, if it fails, return opt | | parsec-optional | N/A | apply parser zero or one time and return the result | | parsec-optional* | optional | apply parser zero or one time and discard the result | | parsec-optional-maybe | optionMaybe | apply parser zero or one time and return the result in Maybe |

Note:

• =parsec-or= can also be used to replace =<|>=.
• =parsec-with-error-message= is slightly different from =<?>=. It will replace the error message even when the input is consumed.
• By default, =parsec-many-till= behaves as Haskell's =manyTill=. However, =parsec-many-till= and =parsec-until= can accept an optional argument to specify which part(s) to be returned. You can use =:both= or =:end= as the optional argument to change the default behavior. See the docstrings for more information.

** Parser Utilities These utilities can be used together with parser combinators to build a parser and ease the translation process if you're trying to port an existing Haskell program.

| parsec.el | Haskell's Parsec | Usage | |----------------------------------+------------------+---------------------------------------------------------| | parsec-and | do block | try all parsers and return the last result | | parsec-return | do block | try all parsers and return the first result | | parsec-ensure | N/A | quit the parsing when an error occurs | | parsec-ensure-with-error-message | N/A | quit the parsing when an error occurs with new message | | parsec-collect | sequence | try all parsers and collect the results into a list | | parsec-collect* | N/A | try all parsers and collect non-nil results into a list | | parsec-start | parse | entry point | | parsec-parse | parse | entry point (same as parsec-start) | | parsec-with-input | parse | perform parsers on input | | parsec-from-maybe | fromMaybe | retrieve value from Maybe | | parsec-maybe-p | N/A | is a Maybe value or not | | parsec-query | N/A | change the parser's return value |

** Variants that Return a String

By default, the macros/functions that return multiple values will put the values into a list. These macros/functions are:

• =parsec-many=
• =parsec-many1=
• =parsec-many-till=
• =parsec-until=
• =parsec-count=
• =parsec-collect= and =parsec-collect*=

They all have a variant that returns a string by concatenating the results in the list:

• =parsec-many-as-string= or =parsec-many-s=
• =parsec-many1-as-string= or =parsec-many1-s=
• =parsec-many-till-as-string= or =parsec-many-till-s=
• =parsec-until-as-string= or =parsec-until-s=
• =parsec-collect-as-string= or =parsec-collect-s=
• =parsec-count-as-string= or =parsec-count-s=

The =-s= and =-as-string= variants are the same, except the =-s= variants have a shorter name. Using these =-s= functions are recommended if you're dealing with strings very frequently in your code. These va