GHC.Exception (original) (raw)

Description

Exceptions and exception-handling functions.

Synopsis

• module GHC.Exception.Type
• throw :: forall (r :: RuntimeRep). forall (a :: TYPE r). forall e. Exception e => e -> a
• data ErrorCall where
  • ErrorCallWithLocation String String
  • pattern ErrorCall :: String -> ErrorCall
• errorCallException :: String -> SomeException
• errorCallWithCallStackException :: String -> CallStack -> SomeException
• data CallStack
• fromCallSiteList :: [([Char], SrcLoc)] -> CallStack
• getCallStack :: CallStack -> [([Char], SrcLoc)]
• prettyCallStack :: CallStack -> String
• prettyCallStackLines :: CallStack -> [String]
• showCCSStack :: [String] -> [String]
• data SrcLoc = SrcLoc {
  • srcLocPackage :: [Char]
  • srcLocModule :: [Char]
  • srcLocFile :: [Char]
  • srcLocStartLine :: Int
  • srcLocStartCol :: Int
  • srcLocEndLine :: Int
  • srcLocEndCol :: Int
    }
• prettySrcLoc :: SrcLoc -> String

Documentation

throw :: forall (r :: RuntimeRep). forall (a :: TYPE r). forall e. Exception e => e -> a Source #

Throw an exception. Exceptions may be thrown from purely functional code, but may only be caught within the [IO](System-IO.html#t:IO "System.IO") monad.

data ErrorCall Source #

This is thrown when the user calls [error](Prelude.html#v:error "Prelude"). The first String is the argument given to [error](Prelude.html#v:error "Prelude"), second String is the location.

data CallStack Source #

[CallStack](GHC-Exception.html#t:CallStack "GHC.Exception")s 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](GHC-Stack.html#t:HasCallStack "GHC.Stack") 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](GHC-Stack.html#v:callStack "GHC.Stack").

>>> **:{** ****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 :... in interactive:Ghci...

GHC solves [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraints in three steps:

1. If there is a [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") in scope -- i.e. the enclosing function has a [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint -- GHC will append the new call-site to the existing [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception").
2. If there is no [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") in scope -- e.g. in the GHCi session above -- and the enclosing definition does not have an explicit type signature, GHC will infer a [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint for the enclosing definition (subject to the monomorphism restriction).
3. If there is no [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") in scope and the enclosing definition has an explicit type signature, GHC will solve the [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint for the singleton [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") containing just the current call-site.

[CallStack](GHC-Exception.html#t:CallStack "GHC.Exception")s 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](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraints, they will generally not contain as much information as the simulated call-stacks maintained by the RTS.

A [CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") is a [(String, SrcLoc)]. The String is the name of function that was called, the [SrcLoc](GHC-Exception.html#t:SrcLoc "GHC.Exception") 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](GHC-Stack.html#t:HasCallStack "GHC.Stack") is just an alias for an implicit parameter ?callStack :: CallStack. This is an implementation detail and should not be considered part of the[CallStack](GHC-Exception.html#t:CallStack "GHC.Exception") API, we may decide to change the implementation in the future.

Since: base-4.8.1.0

data SrcLoc Source #

A single location in the source code.

Since: base-4.8.1.0