Megaparsec uses some type-level machinery to provide flexibility without
compromising on type safety. Thus type signatures are sometimes necessary
to avoid ambiguous types. If you're seeing a error message that reads
like “Type variable e0 is ambiguous …”, you need to give an explicit
signature to your parser to resolve the ambiguity. It's a good idea to
provide type signatures for all top-level definitions.

parseMaybe p input runs the parser p on input and returns the
result inside Just on success and Nothing on failure. This function
also parses eof, so if the parser doesn't consume all of its input, it
will fail.

The function is supposed to be useful for lightweight parsing, where
error messages (and thus file name) are not important and entire input
should be parsed. For example, it can be used when parsing of a single
number according to a specification of its format is desired.

runParser p file input runs parser p on the input stream of
tokens input, obtained from source file. The file is only used in
error messages and may be the empty string. Returns either a ParseError
(Left) or a value of type a (Right).

The function is similar to runParser with the difference that it
accepts and returns parser state. This allows to specify arbitrary
textual position at the beginning of parsing, for example. This is the
most general way to run a parser over the Identity monad.

runParserT p file input runs parser p on the input list of tokens
input, obtained from source file. The file is only used in error
messages and may be the empty string. Returns a computation in the
underlying monad m that returns either a ParseError (Left) or a
value of type a (Right).

The parser try p behaves like parser p, except that it
backtracks the parser state when p fails (either consuming input or
not).

This combinator is used whenever arbitrary look ahead is needed. Since
it pretends that it hasn't consumed any input when p fails, the
(<|>) combinator will try its second alternative even if the first
parser failed while consuming input.

For example, here is a parser that is supposed to parse the word “let”
or the word “lexical”:

What happens here? The first parser consumes “le” and fails (because it
doesn't see a “t”). The second parser, however, isn't tried, since the
first parser has already consumed some input! try fixes this behavior
and allows backtracking to work:

Please note that as of Megaparsec 4.4.0, string backtracks
automatically (see tokens), so it does not need try. However, the
examples above demonstrate the idea behind try so well that it was
decided to keep them. You still need to use try when your
alternatives are complex, composite parsers.

If p in lookAhead p succeeds (either consuming input or not)
the whole parser behaves like p succeeded without consuming anything
(parser state is not updated as well). If p fails, lookAhead has no
effect, i.e. it will fail consuming input if p fails consuming input.
Combine with try if this is undesirable.

withRecovery r p allows continue parsing even if parser p
fails. In this case r is called with the actual ParseError as its
argument. Typical usage is to return a value signifying failure to
parse this particular object and to consume some part of the input up
to the point where the next object starts.

Note that if r fails, original error message is reported as if
without withRecovery. In no way recovering parser r can influence
error messages.

observing p allows to “observe” failure of the p parser, should
it happen, without actually ending parsing, but instead getting the
ParseError in Left. On success parsed value is returned in Right
as usual. Note that this primitive just allows you to observe parse
errors as they happen, it does not backtrack or change how the p
parser works in any way.

The parser token test mrep accepts a token t with result x
when the function test t returns Right x. mrep may provide
representation of the token to report in error messages when input
stream in empty.

This is the most primitive combinator for accepting tokens. For
example, the satisfy parser is implemented as:

The parser tokens test parses a chunk of input and returns it.
Supplied predicate test is used to check equality of given and parsed
chunks after a candidate chunk of correct length is fetched from the
stream.

Note that beginning from Megaparsec 4.4.0, this is an auto-backtracking
primitive, which means that if it fails, it never consumes any input.
This is done to make its consumption model match how error messages for
this primitive are reported (which becomes an important thing as user
gets more control with primitives like withRecovery):

Extract the specified number of tokens from the input stream and
return them packed as a chunk of stream. If there is not enough tokens
in the stream, a parse error will be signaled. It's guaranteed that if
the parser succeeds, the requested number of tokens will be returned.

Return both the result of a parse and a chunk of input that was
consumed during parsing. This relies on the change of the
stateTokensProcessed value to evaluate how many tokens were consumed.
If you mess with it manually in the argument parser, prepare for
troubles.

Specify how to process ParseErrors that happen inside of this
wrapper. As a side effect of the current implementation changing
errorPos with this combinator will also change the final statePos in
the parser state (try to avoid that because statePos will go out of
sync with factual position in the input stream, which is probably OK if
you finish parsing right after that, but be warned).

Debugging

dbg label p parser works exactly like p, but when it's evaluated
it also prints information useful for debugging. The label is only used
to refer to this parser in the debugging output. This combinator uses the
trace function from Debug.Trace under the hood.

Typical usage is to wrap every sub-parser in misbehaving parser with
dbg assigning meaningful labels. Then give it a shot and go through the
print-out. As of current version, this combinator prints all available
information except for hints, which are probably only interesting to
the maintainer of Megaparsec itself and may be quite verbose to output in
general. Let me know if you would like to be able to see hints in the
debugging output.

The output itself is pretty self-explanatory, although the following
abbreviations should be clarified (they are derived from the low-level
source code):

COK—“consumed OK”. The parser consumed input and succeeded.

CERR—“consumed error”. The parser consumed input and failed.

EOK—“empty OK”. The parser succeeded without consuming input.

EERR—“empty error”. The parser failed without consuming input.

Finally, it's not possible to lift this function into some monad
transformers without introducing surprising behavior (e.g. unexpected
state backtracking) or adding otherwise redundant constraints (e.g.
Show instance for state), so this helper is only available for
ParsecT monad, not MonadParsec in general.