hledger-lib-1.30: A reusable library providing the core functionality of hledger

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hledger.Utils.Debug

Contents

- Tracing to stderr
- Logging to PROGNAME.log
- Tracing or logging based on shouldLog
- Pretty tracing/logging in pure code
- Pretty tracing/logging in IO
- Tracing/logging with a show function
- Re-exports

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

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

traceOrLogAt :: Int -> String -> a -> a Source #

ptraceOrLogAt :: Show a => Int -> String -> a -> a Source #

ptraceOrLogAtIO :: (MonadIO m, Show a) => Int -> String -> a -> m () Source #

traceOrLogAtWith :: Int -> (a -> String) -> a -> a Source #

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

# Tracing/logging with a show function

dbg0With :: (a -> String) -> a -> a Source #

Like dbgN, but taking a show function instead of a label.

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

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

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

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

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

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

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

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

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

# Re-exports

trace :: String -> a -> a Source #

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.

traceIO :: String -> IO () Source #

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

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