megaparsec-7.0.5: Monadic parser combinators

Copyright | © 2015–2019 Megaparsec contributors
License | FreeBSD
Maintainer | Mark Karpov <markkarpov92@gmail.com>
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

Text.Megaparsec.Debug

Description

Debugging helpers.

Since: 7.0.0

Synopsis

- dbg :: forall e s m a. (Stream s, ShowErrorComponent e, Show a) => String -> ParsecT e s m a -> ParsecT e s m a

# Documentation

dbg Source #

Arguments

:: (Stream s, ShowErrorComponent e, Show a) |
=> String | Debugging label
-> ParsecT e s m a | Parser to debug
-> ParsecT e s m a | Parser that prints debugging messages

``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 any instance of `MonadParsec` in general.