megaparsec-9.7.0: Monadic parser combinators

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

Text.Megaparsec.Debug

Description

Debugging helpers.

Since: 7.0.0

Synopsis

- class MonadParsec e s m => MonadParsecDbg e s (m :: Type -> Type) where
  - dbg :: Show a => String -> m a -> m a
- dbg' :: MonadParsecDbg e s m => String -> m a -> m a

# Documentation

class MonadParsec e s m => MonadParsecDbg e s (m :: Type -> Type) where #

Type class describing parser monads that can trace during evaluation.

Since: 9.3.0

Methods

dbg #

Arguments

:: Show a |
=> String | Debugging label
-> m a | Parser to debug
-> m a | Parser that prints debugging messages

``dbg` label p` parser works exactly like `p`, but when it's evaluated it 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.

Note: up until the version 9.3.0 this was a non-polymorphic function that worked only in `ParsecT`. It was first introduced in the version 7.0.0.

#### Instances

Instances details

MonadParsecDbg e s m => MonadParsecDbg e s (IdentityT m) # |
Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> IdentityT m a -> IdentityT m a #
MonadParsecDbg e s m => MonadParsecDbg e s (ReaderT r m) # |
Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> ReaderT r m a -> ReaderT r m a #

(Show st, MonadParsecDbg e s m) => MonadParsecDbg e s (StateT st m) #

`dbg (p :: StateT st m)` prints state after running `p`:

    >>> p = modify succ >> dbg "a" (single 'a' >> modify succ)
    >>> parseTest (runStateT p 0) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (STATE: 2)
    ((),2)

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> StateT st m a -> StateT st m a #

(Show st, MonadParsecDbg e s m) => MonadParsecDbg e s (StateT st m) #

`dbg (p :: StateT st m)` prints state after running `p`:

    >>> p = modify succ >> dbg "a" (single 'a' >> modify succ)
    >>> parseTest (runStateT p 0) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (STATE: 2)
    ((),2)

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> StateT st m a -> StateT st m a #

(Monoid w, Show w, MonadParsecDbg e s m) => MonadParsecDbg e s (WriterT w m) #

`dbg (p :: WriterT st m)` prints only log produced by `p`:

    >>> p = tell [0] >> dbg "a" (single 'a' >> tell [1])
    >>> parseTest (runWriterT p) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (LOG: [1])
    ((),[0,1])

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> WriterT w m a -> WriterT w m a #

(Monoid w, Show w, MonadParsecDbg e s m) => MonadParsecDbg e s (WriterT w m) #

`dbg (p :: WriterT st m)` prints only log produced by `p`:

    >>> p = tell [0] >> dbg "a" (single 'a' >> tell [1])
    >>> parseTest (runWriterT p) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (LOG: [1])
    ((),[0,1])

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> WriterT w m a -> WriterT w m a #
(VisualStream s, ShowErrorComponent e) => MonadParsecDbg e s (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> ParsecT e s m a -> ParsecT e s m a #

(Monoid w, Show w, Show st, MonadParsecDbg e s m) => MonadParsecDbg e s (RWST r w st m) #

`RWST` works like `StateT` inside a `WriterT`: subparser's log and its final state is printed:

    >>> p = tell [0] >> modify succ >> dbg "a" (single 'a' >> tell [1] >> modify succ)
    >>> parseTest (runRWST p () 0) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (STATE: 2) (LOG: [1])
    ((),2,[0,1])

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> RWST r w st m a -> RWST r w st m a #

(Monoid w, Show w, Show st, MonadParsecDbg e s m) => MonadParsecDbg e s (RWST r w st m) #

`RWST` works like `StateT` inside a `WriterT`: subparser's log and its final state is printed:

    >>> p = tell [0] >> modify succ >> dbg "a" (single 'a' >> tell [1] >> modify succ)
    >>> parseTest (runRWST p () 0) "a"
    a> IN: 'a'
    a> MATCH (COK): 'a'
    a> VALUE: () (STATE: 2) (LOG: [1])
    ((),2,[0,1])

Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> RWST r w st m a -> RWST r w st m a #

dbg' #

Arguments

:: MonadParsecDbg e s m |
=> String | Debugging label
-> m a | Parser to debug
-> m a | Parser that prints debugging messages

Just like `dbg`, but doesn't require the return value of the parser to be `Show`-able.

Since: 9.1.0