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 errput on the console. The default is 0 meaning no debug errput. 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 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

useColorOnStdout :: Bool

Check the IO environment to see if ANSI colour codes should be used on stdout. This is done using unsafePerformIO so it can be used anywhere, eg in low-level debug utilities, which should be ok since we are just reading. The logic is: use color if the program was started with --color=yes|always or ( the program was not started with --color=no|never and a NO_COLOR environment variable is not defined and stdout supports ANSI color and -o/--output-file was not used or is "-" ). Caveats: When running code in GHCI, this module must be reloaded to see a change. {--} {--}

useColorOnStderr :: Bool

Like useColorOnStdout, but checks for ANSI color support on stderr, and is not affected by -o/--output-file. {--} {--}

dlog :: Show a => a -> a

Log a pretty-printed showable value to "./debug.log". Uses unsafePerformIO.