| Safe Haskell | Safe-Inferred | 
|---|---|
| Language | Haskell2010 | 
Distribution.Compat.Stack
Synopsis
- type WithCallStack a = HasCallStack => a
- data CallStack
- annotateCallStackIO :: WithCallStack (IO a -> IO a)
- withFrozenCallStack :: HasCallStack => (HasCallStack => a) -> a
- withLexicalCallStack :: (a -> WithCallStack (IO b)) -> WithCallStack (a -> IO b)
- callStack :: HasCallStack => CallStack
- prettyCallStack :: CallStack -> String
- parentSrcLocPrefix :: WithCallStack String
Documentation
type WithCallStack a = HasCallStack => a #
CallStacks are a lightweight method of obtaining a
 partial call-stack at any point in the program.
A function can request its call-site with the HasCallStack constraint.
 For example, we can define
putStrLnWithCallStack :: HasCallStack => String -> IO ()
as a variant of putStrLn that will get its call-site and print it,
 along with the string given as argument. We can access the
 call-stack inside putStrLnWithCallStack with callStack.
putStrLnWithCallStack :: HasCallStack => String -> IO () putStrLnWithCallStack msg = do putStrLn msg putStrLn (prettyCallStack callStack)
Thus, if we call putStrLnWithCallStack we will get a formatted call-stack
 alongside our string.
>>>putStrLnWithCallStack "hello"hello CallStack (from HasCallStack): putStrLnWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
GHC solves HasCallStack constraints in three steps:
- If there is a CallStackin scope -- i.e. the enclosing function has aHasCallStackconstraint -- GHC will append the new call-site to the existingCallStack.
- If there is no CallStackin scope -- e.g. in the GHCi session above -- and the enclosing definition does not have an explicit type signature, GHC will infer aHasCallStackconstraint for the enclosing definition (subject to the monomorphism restriction).
- If there is no CallStackin scope and the enclosing definition has an explicit type signature, GHC will solve theHasCallStackconstraint for the singletonCallStackcontaining just the current call-site.
CallStacks do not interact with the RTS and do not require compilation
 with -prof. On the other hand, as they are built up explicitly via the
 HasCallStack constraints, they will generally not contain as much
 information as the simulated call-stacks maintained by the RTS.
A CallStack is a [(String, SrcLoc)]. The String is the name of
 function that was called, the SrcLoc is the call-site. The list is
 ordered with the most recently called function at the head.
NOTE: The intrepid user may notice that HasCallStack is just an
 alias for an implicit parameter ?callStack :: CallStack. This is an
 implementation detail and should not be considered part of the
 CallStack API, we may decide to change the implementation in the
 future.
Since: base-4.8.1.0
annotateCallStackIO :: WithCallStack (IO a -> IO a) #
This function is for when you *really* want to add a call
 stack to raised IO, but you don't have a
 Verbosity so you can't use
 annotateIO.  If you have a Verbosity,
 please use that function instead.
withFrozenCallStack :: HasCallStack => (HasCallStack => a) -> a Source #
Perform some computation without adding new entries to the CallStack.
Since: base-4.9.0.0
withLexicalCallStack :: (a -> WithCallStack (IO b)) -> WithCallStack (a -> IO b) #
callStack :: HasCallStack => CallStack Source #
parentSrcLocPrefix :: WithCallStack String #
Give the *parent* of the person who invoked this;
 so it's most suitable for being called from a utility function.
 You probably want to call this using withFrozenCallStack; otherwise
 it's not very useful.  We didn't implement this for base-4.8.1
 because we cannot rely on freezing to have taken place.