ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Utils.Trace

Description

Tracing utilities

Synopsis

- pprTrace :: String -> SDoc -> a -> a
- pprTraceM :: Applicative f => String -> SDoc -> f ()
- pprTraceDebug :: String -> SDoc -> a -> a
- pprTraceIt :: Outputable a => String -> a -> a
- pprTraceWith :: String -> (a -> SDoc) -> a -> a
- pprSTrace :: HasCallStack => SDoc -> a -> a
- pprTraceException :: ExceptionMonad m => String -> SDoc -> m a -> m a
- warnPprTrace :: HasCallStack => Bool -> String -> SDoc -> a -> a
- warnPprTraceM :: (Applicative f, HasCallStack) => Bool -> String -> SDoc -> f ()
- pprTraceUserWarning :: HasCallStack => SDoc -> a -> a
- trace :: String -> a -> a

# Documentation

pprTrace :: String -> SDoc -> a -> a #

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

pprTraceM :: Applicative f => String -> SDoc -> f () #

pprTraceDebug :: String -> SDoc -> a -> a #

pprTraceIt :: Outputable a => String -> a -> a #

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

pprTraceWith :: String -> (a -> SDoc) -> a -> a #

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

pprSTrace :: HasCallStack => SDoc -> a -> a #

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

pprTraceException :: ExceptionMonad m => String -> SDoc -> m a -> m a #

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

warnPprTrace :: HasCallStack => Bool -> String -> SDoc -> a -> a #

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

warnPprTraceM :: (Applicative f, HasCallStack) => Bool -> String -> SDoc -> f () #

pprTraceUserWarning :: HasCallStack => SDoc -> a -> a #

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.

trace :: String -> a -> a #

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.