GHC.Utils.Trace

If debug output is on, show some SDoc on the screen

A version of pprTrace that is useful for quick debugging:

fooBar x y
  | cond      = body1
  | otherwise = body2
  where
    !_ = pprTrace_ "fooBar" $
         vcat [ text "x:" + ppr x
              , text "y:" + ppr y
              , text "cond:" + ppr cond
              ]

pprTraceIt desc x is equivalent to pprTrace desc (ppr x) x

pprTraceWith desc f x is equivalent to pprTrace desc (f x) x. This allows you to print details from the returned value as well as from ambient variables.

If debug output is on, show some SDoc on the screen along with a call stack when available.

pprTraceException desc x action runs action, printing a message if it throws an exception.

Just warn about an assertion failure, recording the given file and line number.

For when we want to show the user a non-fatal WARNING so that they can report a GHC bug, but don't want to panic.

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.