Text.Gigaparsec.Debug

This module contains the very useful debugging combinators debug and debugWith, as well as breakpoints that can be used to pause parsing execution.

Since: 0.2.1.0

Documentation

debug :: String -> Parsec a -> Parsec a

This combinator allows this parser to be debugged by providing a trace through the execution.

When this combinator is entered, it will print the name assigned to the parser to the console, as well as the current input context for a few characters that follow. This parser is then executed. If it succeeded, this combinator again reports the name along with "Good" and the input context. If it failed, it reports the name along with "Bad" and the input context.

debugWith :: DebugConfig -> String -> Parsec a -> Parsec a

This combinator allows this parser to be debugged by providing a trace through the execution. An additional DebugConfig is provided to customise behaviour.

When this combinator is entered, it will print the name assigned to the parser to the configured handle, as well as the current input context for a few characters that follow. This parser is then executed. If it succeeded, this combinator again reports the name along with "Good" and the input context. If it failed, it reports the name along with "Bad" and the input context.

When breakpoints are enabled within the config, the execution of the combinator will pause on either entry, exit, or both. The parse is resumed by entering any character on standard input.

debugConfig :: DebugConfig

The plain configuration used by the debug combinator itself. It will have coloured terminal output (if available), never pause the parsing execution, not track any registers, and print its output to stdout.

data DebugConfig

Configuration that allows for customising the behaviour of a debugWith combinator.

Constructors

DebugConfig

Fields

• ascii :: !Bool

  should the output of the combinator be in plain uncoloured ascii?

• breakPoint :: !Break

  should parsing execution be paused when entering or leaving this combinator?

• watchedRegs :: ![WatchedReg]

  what registers should have their values tracked during debugging?

• handle :: !Handle

  where should the output of the combinator be sent?

data WatchedReg

This type allows for a specified register to be watched by a debug combinator. The contents of the register must be Showable, and it should be given a name to identify it within the print-out. Registers containing different types can be simultaneously tracked, which is why this datatype is existential.

Constructors

forall r a.Show a => WatchedReg

Fields

• String

  the name of the register

• (Ref r a)

  the register itself

data Break

This is used by DebugConfig to specify whether the parsing should be paused when passing through a debugWith combinator.

Constructors

OnEntry

pause the parsing just after entering a debug combinator

OnExit

pause the parsing just after leaving a debug combinator

Always

pause the parsing both just after entry and exit of a debug combinator

Never

do not pause execution when passing through (default)