| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Hledger.Utils.Debug
Description
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
Synopsis
- pprint :: Show a => a -> IO ()
- pprint' :: Show a => a -> IO ()
- pshow :: Show a => a -> String
- pshow' :: Show a => a -> String
- useColorOnStdout :: Bool
- useColorOnStderr :: Bool
- traceWith :: Show a => (a -> String) -> a -> a
- ptrace :: Show a => a -> a
- debugLevel :: Int
- traceAt :: Int -> String -> a -> a
- traceAtWith :: Int -> (a -> String) -> a -> a
- ptraceAt :: Show a => Int -> String -> a -> a
- ptraceAtWith :: Show a => Int -> (a -> String) -> a -> a
- dbg0 :: Show a => String -> a -> a
- dbg1 :: Show a => String -> a -> a
- 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
- dbg0With :: Show a => (a -> String) -> a -> a
- 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
- ptraceAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m ()
- 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 ()
- traceParse :: String -> TextParser m ()
- dbgparse :: Int -> String -> TextParser m ()
- dlogTrace :: String -> a -> a
- dlogTraceAt :: Int -> String -> a -> a
- dlogAt :: Show a => Int -> String -> a -> a
- dlog0 :: Show a => String -> a -> a
- dlog1 :: Show a => String -> a -> a
- dlog2 :: Show a => String -> a -> a
- dlog3 :: Show a => String -> a -> a
- dlog4 :: Show a => String -> a -> a
- dlog5 :: Show a => String -> a -> a
- dlog6 :: Show a => String -> a -> a
- dlog7 :: Show a => String -> a -> a
- dlog8 :: Show a => String -> a -> a
- dlog9 :: Show a => String -> a -> a
- module Debug.Breakpoint
- module Debug.Trace
Pretty printing
useColorOnStdout :: Bool Source #
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. {-# OPTIONS_GHC -fno-cse #-} {-# NOINLINE useColorOnStdout #-}
useColorOnStderr :: Bool Source #
Like useColorOnStdout, but checks for ANSI color support on stderr, and is not affected by -o/--output-file. {-# OPTIONS_GHC -fno-cse #-} {-# NOINLINE useColorOnStdout #-}
Tracing
traceWith :: Show a => (a -> String) -> a -> a Source #
Like traceShowId, but uses a custom show function to render the value. traceShowIdWith was too much of a mouthful.
Pretty tracing
Debug-level-aware tracing
debugLevel :: Int Source #
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.
{-# OPTIONS_GHC -fno-cse #-}
traceAt :: Int -> String -> a -> a Source #
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 Source #
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 Source #
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 Source #
Like ptraceAt, but takes a custom show function instead of a label.
Easiest form (recommended)
dbg0 :: Show a => String -> a -> a Source #
Pretty-print a label and the showable value to the console, then return it.
dbg1 :: Show a => String -> a -> a Source #
Pretty-print a label and the showable value to the console when the global debug level is >= 1, then return it. Uses unsafePerformIO.
dbgExit :: Show a => String -> a -> a Source #
Like dbg0, but also exit the program. Uses unsafePerformIO. {-# NOINLINE dbgExit #-}
More control
dbg0With :: Show a => (a -> String) -> a -> a Source #
Like dbg0, but takes a custom show function instead of a label.
For standalone lines in IO blocks
ptraceAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m () Source #
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).
Trace the state of hledger parsers
traceParse :: String -> TextParser m () Source #
Print the provided label (if non-null) and current parser state (position and next input) to the console. See also megaparsec's dbg.
Debug-logging to a file
dlogTrace :: String -> a -> a Source #
Log a string to ./debug.log before returning the second argument. Uses unsafePerformIO. {-# NOINLINE dlogTrace #-}
dlogTraceAt :: Int -> String -> a -> a Source #
Log a string to ./debug.log before returning the second argument, if the global debug level is at or above the specified level. At level 0, always logs. Otherwise, uses unsafePerformIO.
dlogAt :: Show a => Int -> String -> a -> a Source #
Log a label and pretty-printed showable value to "./debug.log", if the global debug level is at or above the specified level. At level 0, always prints. Otherwise, uses unsafePerformIO.
dlog0 :: Show a => String -> a -> a Source #
Pretty-print a label and the showable value to ./debug.log if at or above a certain debug level, then return it.
Re-exports
module Debug.Breakpoint
module Debug.Trace