License	BSD-3-Clause
Maintainer	Jamie Willis, Gigaparsec Maintainers
Stability	stable
Safe Haskell	Trustworthy
Language	Haskell2010

Text.Gigaparsec.Debug

Description

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

Synopsis

debug :: String -> Parsec a -> Parsec a
debugWith :: DebugConfig -> String -> Parsec a -> Parsec a
debugConfig :: DebugConfig
data DebugConfig = DebugConfig {
- ascii :: !Bool
- breakPoint :: !Break
- watchedRegs :: ![WatchedReg]
- handle :: !Handle
}
data WatchedReg = Show a => WatchedReg String (Ref r a)
data Break
- = OnEntry
- | OnExit
- | Always
- | Never

Documentation

debug :: String -> Parsec a -> Parsec a Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

Show a => WatchedReg
Fields String the name of the register (Ref r a) the register itself

data Break Source #

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)