Hledger.Utils.Debug

Helpers for debug output and pretty-printing (using pretty-simple, with which there may be some overlap). This module also exports Debug.Trace.

dbg0-dbg9 will pretty-print values to stderr if the program was run with a sufficiently high --debug=N argument. (--debug with no argument means --debug=1; dbg0 always prints).

The debugLevel global is set once at startup using unsafePerformIO. In GHCI, this happens only on the first run of :main, so if you want to change the debug level without restarting GHCI, save a dummy change in Debug.hs and do a :reload. (Sometimes it's more convenient to temporarily add dbg0's and :reload.)

In hledger, debug levels are used as follows:

Debug level: What to show: ------------ --------------------------------------------------------- 0 normal command output only (no warnings, eg) 1 (--debug) useful warnings, most common troubleshooting info, eg valuation 2 common troubleshooting info, more detail 3 report options selection 4 report generation 5 report generation, more detail 6 input file reading 7 input file reading, more detail 8 command line parsing 9 any other rarely needed / more in-depth info

Pretty printing

pprint :: Show a => a -> IO ()

Pretty print. Generic alias for pretty-simple's pPrint.

pshow :: Show a => a -> String

Pretty show. Generic alias for pretty-simple's pShow.

Tracing

traceWith :: Show a => (a -> String) -> a -> a

Like traceShowId, but uses a custom show function to render the value. traceShowIdWith was too much of a mouthful.

Pretty tracing

ptrace :: Show a => a -> a

Pretty trace. Easier alias for traceShowId + pShow.

Debug-level-aware tracing

debugLevel :: Int

Global debug level, which controls the verbosity of debug output on the console. The default is 0 meaning no debug output. The --debug command line flag sets it to 1, or --debug=N sets it to a higher value (note: not --debug N for some reason). This uses unsafePerformIO and can be accessed from anywhere and before normal command-line processing. When running with :main in GHCI, you must touch and reload this module to see the effect of a new --debug option. {--} {--}

traceAt :: Int -> String -> a -> a

Trace (print to stderr) a string if the global debug level is at or above the specified level. At level 0, always prints. Otherwise, uses unsafePerformIO.

traceAtWith :: Int -> (a -> String) -> a -> a

Trace (print to stderr) a showable value using a custom show function, if the global debug level is at or above the specified level. At level 0, always prints. Otherwise, uses unsafePerformIO.

ptraceAt :: Show a => Int -> String -> a -> a

Pretty-print a label and a showable value to the console if the global debug level is at or above the specified level. At level 0, always prints. Otherwise, uses unsafePerformIO.

ptraceAtWith :: Show a => Int -> (a -> String) -> a -> a

Like ptraceAt, but takes a custom show function instead of a label.

Easiest form (recommended)

dbg0 :: Show a => String -> a -> a

Pretty-print a label and the showable value to the console, then return it.

dbg1 :: Show a => String -> a -> a

Pretty-print a label and the showable value to the console when the global debug level is >= 1, then return it. Uses unsafePerformIO.

dbg2 :: Show a => String -> a -> a

dbg3 :: Show a => String -> a -> a

dbg4 :: Show a => String -> a -> a

dbg5 :: Show a => String -> a -> a

dbg6 :: Show a => String -> a -> a

dbg7 :: Show a => String -> a -> a

dbg8 :: Show a => String -> a -> a

dbg9 :: Show a => String -> a -> a

dbgExit :: Show a => String -> a -> a

Like dbg0, but also exit the program. Uses unsafePerformIO.

More control

dbg0With :: Show a => (a -> String) -> a -> a

Like dbg0, but takes a custom show function instead of a label.

dbg1With :: Show a => (a -> String) -> a -> a

dbg2With :: Show a => (a -> String) -> a -> a

dbg3With :: Show a => (a -> String) -> a -> a

dbg4With :: Show a => (a -> String) -> a -> a

dbg5With :: Show a => (a -> String) -> a -> a

dbg6With :: Show a => (a -> String) -> a -> a

dbg7With :: Show a => (a -> String) -> a -> a

dbg8With :: Show a => (a -> String) -> a -> a

dbg9With :: Show a => (a -> String) -> a -> a

For standalone lines in IO blocks

ptraceAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m ()

Like ptraceAt, but convenient to insert in an IO monad and enforces monadic sequencing (plus convenience aliases). XXX These have a bug; they should use traceIO, not trace, otherwise GHC can occasionally over-optimise (cf lpaste a few days ago where it killed/blocked a child thread).

dbg0IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg1IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg2IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg3IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg4IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg5IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg6IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg7IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg8IO :: (MonadIO m, Show a) => String -> a -> m ()

dbg9IO :: (MonadIO m, Show a) => String -> a -> m ()

Trace to a file

plog :: Show a => String -> a -> a

Log a label and a pretty-printed showable value to ./debug.log, then return it. Can fail, see plogAt.

plogAt :: Show a => Int -> String -> a -> a

Log a label and a pretty-printed showable value to ./debug.log, if the global debug level is at or above the specified level. At level 0, always logs. Otherwise, uses unsafePerformIO. Tends to fail if called more than once too quickly, at least when built with -threaded ("Exception: debug.log: openFile: resource busy (file is locked)").

Trace the state of hledger parsers

traceParse :: String -> TextParser m ()

Print the provided label (if non-null) and current parser state (position and next input) to the console. See also megaparsec's dbg.

dbgparse :: Int -> String -> TextParser m ()

Convenience alias for traceParseAt

module Debug.Trace