| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Hledger.Utils.Debug
Description
Here are fancier versions of Debug.Trace, with these features:
- unsafePerformIO-based for easy usage in pure code, IO code, and program startup code
- reasonably short and memorable function names
- pretty-printing haskell values, with or without colour, using pretty-simple
- enabling/disabling debug output with --debug
- multiple debug verbosity levels, from 1 to 9
- sending debug output to stderr or to a log file
- enabling logging based on program name
The basic "trace" functions print to stderr. This debug output will be interleaved with the program's normal output, which can be useful for understanding when code executes.
The Log functions log to a file instead.
The need for these is arguable, since a technically savvy user can redirect
stderr output to a log file, eg: CMD 2>debug.log.
But here is how they currently work:
The "traceLog" functions log to the program's debug log file,
which is PROGNAME.log in the current directory,
where PROGNAME is the program name returned by getProgName.
When using this logging feature you should call withProgName explicitly
at the start of your program to ensure a stable program name,
otherwise it can change to "interactive" eg when running in GHCI.
Eg: main = withProgName MYPROG $ do ....
The OrLog functions can either print to stderr or log to a file.
- By default, they print to stderr.
- If the program name has been set (with @withProgName) to something ending with ".log", they log to that file instead. This can be useful for programs which should never print to stderr, eg TUI programs like hledger-ui.
The At functions produce output only when the program was run with a
sufficiently high debug level, as set by a --debug[=N] command line option.
N ranges from 1 (least debug output) to 9 (most debug output),
--debug with no argument means 1.
The "dbgN*" functions are intended to be the most convenient API, to be embedded at points of interest in your code. They combine the conditional output of At, the conditional logging of OrLog, pretty printing, and short searchable function names.
Parsing the command line, detecting program name, and file logging is done with unsafePerformIO. If you are working in GHCI, changing the debug level requires editing and reloading this file (sometimes it's more convenient to add a dbg0 temporarily).
In hledger, debug levels are used as follows:
Debug level: What to show: ------------ --------------------------------------------------------- 0 normal command output only (no warnings, eg) 1 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
We don't yet have the ability to select debug output by topic. For now, here are some standardish topic strings to search for in hledger debug messages:
acct arg budget calc csv journalFinalise multiBalanceReport opts precision price q style val
Synopsis
- debugLevel :: Int
- traceWith :: (a -> String) -> a -> a
- traceAt :: Int -> String -> a -> a
- traceAtWith :: Int -> (a -> String) -> a -> a
- ptrace :: Show a => a -> a
- ptraceAt :: Show a => Int -> String -> a -> a
- ptraceAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m ()
- traceLog :: String -> a -> a
- traceLogAt :: Int -> String -> a -> a
- traceLogIO :: MonadIO m => String -> m ()
- traceLogAtIO :: MonadIO m => Int -> String -> m ()
- traceLogWith :: (a -> String) -> a -> a
- traceLogAtWith :: Int -> (a -> String) -> a -> a
- ptraceLogAt :: Show a => Int -> String -> a -> a
- ptraceLogAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m ()
- traceOrLog :: String -> a -> a
- traceOrLogAt :: Int -> String -> a -> a
- ptraceOrLogAt :: Show a => Int -> String -> a -> a
- ptraceOrLogAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m ()
- traceOrLogAtWith :: 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
- 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 ()
- dbg0With :: (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
- lbl_ :: String -> String -> String -> String
- trace :: String -> a -> a
- traceIO :: String -> IO ()
- traceShowId :: Show a => a -> a
Documentation
debugLevel :: Int Source #
The programs debug output verbosity. 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 (the = is required). Uses unsafePerformIO.
When running in GHCI, changing this requires reloading this module.
Tracing to stderr
traceWith :: (a -> String) -> a -> a Source #
Trace a value with the given show function before returning it.
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.
ptrace :: Show a => a -> a Source #
Pretty-trace a showable value before returning it. Like Debug.Trace.traceShowId, but pretty-printing and easier to type.
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.
ptraceAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m () Source #
Like ptraceAt, but convenient to insert in an IO monad and enforces monadic sequencing.
Logging to PROGNAME.log
traceLog :: String -> a -> a Source #
Log a string to the debug log before returning the second argument. Uses unsafePerformIO.
traceLogAt :: Int -> String -> a -> a Source #
Log a string to the 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.
traceLogIO :: MonadIO m => String -> m () Source #
Like traceLog but sequences properly in IO.
traceLogAtIO :: MonadIO m => Int -> String -> m () Source #
Like traceLogAt, but convenient to use in IO.
traceLogWith :: (a -> String) -> a -> a Source #
Log a value to the debug log with the given show function before returning it.
traceLogAtWith :: Int -> (a -> String) -> a -> a Source #
Log a string to the 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.
ptraceLogAt :: Show a => Int -> String -> a -> a Source #
Pretty-log a label and showable value to the debug log, if the global debug level is at or above the specified level. At level 0, always prints. Otherwise, uses unsafePerformIO.
ptraceLogAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m () Source #
Like ptraceAt, but convenient to insert in an IO monad and enforces monadic sequencing.
Tracing or logging based on shouldLog
traceOrLog :: String -> a -> a Source #
Trace or log a string depending on shouldLog, before returning the second argument.
traceOrLogAt :: Int -> String -> a -> a Source #
Trace or log a string depending on shouldLog, when global debug level is at or above the specified level, before returning the second argument.
ptraceOrLogAt :: Show a => Int -> String -> a -> a Source #
Pretty-trace or log depending on shouldLog, when global debug level is at or above the specified level.
ptraceOrLogAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m () Source #
Like ptraceOrLogAt, but convenient in IO.
traceOrLogAtWith :: Int -> (a -> String) -> a -> a Source #
Trace or log, with a show function, depending on shouldLog.
Pretty tracing/logging in pure code
dbg0 :: Show a => String -> a -> a Source #
Pretty-trace to stderr (or log to debug log) a label and showable value, then return it.
dbg1 :: Show a => String -> a -> a Source #
Pretty-trace to stderr (or log to debug log) a label and showable value if the --debug level is high enough, then return the value. Uses unsafePerformIO.
dbgExit :: Show a => String -> a -> a Source #
Like dbg0, but also exit the program. Uses unsafePerformIO.
Pretty tracing/logging in IO
dbg0IO :: (MonadIO m, Show a) => String -> a -> m () Source #
Like dbgN, but convenient to use in IO.
Tracing/logging with a show function
dbg0With :: (a -> String) -> a -> a Source #
Like dbgN, but taking a show function instead of a label.
Utilities
lbl_ :: String -> String -> String -> String Source #
Helper for producing debug messages: concatenates a name (eg a function name), short description of the value being logged, and string representation of the value.
Re-exports
The trace function outputs the trace message given as its first argument,
before returning the second argument as its result.
For example, this returns the value of f x and outputs the message to stderr.
Depending on your terminal (settings), they may or may not be mixed.
>>>let x = 123; f = show>>>trace ("calling f with x = " ++ show x) (f x)calling f with x = 123 "123"
The trace function should only be used for debugging, or for monitoring
execution. The function is not referentially transparent: its type indicates
that it is a pure function but it has the side effect of outputting the
trace message.
The traceIO function outputs the trace message from the IO monad.
This sequences the output with respect to other IO actions.
Since: base-4.5.0.0
traceShowId :: Show a => a -> a #
Like traceShow but returns the shown value instead of a third value.
>>>traceShowId (1+2+3, "hello" ++ "world")(6,"helloworld") (6,"helloworld")
Since: base-4.7.0.0