GHC.Exception

base-4.14.0.0: Basic libraries

Copyright | (c) The University of Glasgow 1998-2002
License | see libraries/base/LICENSE
Maintainer | cvs-ghc@haskell.org
Stability | internal
Portability | non-portable (GHC extensions)
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.Exception

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

module GHC.Exception.Type

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

data ErrorCall Source #

This is thrown when the user calls `error`. The first `String` is the argument given to `error`, second `String` is the location.

Constructors

ErrorCallWithLocation String String |

Bundled Patterns

pattern ErrorCall :: String -> ErrorCall |

#### Instances

Instances details

Eq ErrorCall # | Since: base-4.7.0.0
Instance details Defined in GHC.Exception Methods (==) :: ErrorCall -> ErrorCall -> Bool Source # (/=) :: ErrorCall -> ErrorCall -> Bool Source #
Ord ErrorCall # | Since: base-4.7.0.0
Instance details Defined in GHC.Exception Methods compare :: ErrorCall -> ErrorCall -> Ordering Source # (<) :: ErrorCall -> ErrorCall -> Bool Source # (<=) :: ErrorCall -> ErrorCall -> Bool Source # (>) :: ErrorCall -> ErrorCall -> Bool Source # (>=) :: ErrorCall -> ErrorCall -> Bool Source # max :: ErrorCall -> ErrorCall -> ErrorCall Source # min :: ErrorCall -> ErrorCall -> ErrorCall Source #
Show ErrorCall # | Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods showsPrec :: Int -> ErrorCall -> ShowS Source # show :: ErrorCall -> String Source # showList :: [ErrorCall] -> ShowS Source #
Exception ErrorCall # | Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods toException :: ErrorCall -> SomeException Source # fromException :: SomeException -> Maybe ErrorCall Source # displayException :: ErrorCall -> String Source #

errorCallException :: String -> SomeException Source #

errorCallWithCallStackException :: String -> CallStack -> SomeException Source #

data CallStack Source #

`CallStack`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` 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:

1. If there is a `CallStack` in scope -- i.e. the enclosing function has a `HasCallStack` constraint -- GHC will append the new call-site to the existing `CallStack`.
2. If there is no `CallStack` 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` constraint for the enclosing definition (subject to the monomorphism restriction).
3. If there is no `CallStack` in scope and the enclosing definition has an explicit type signature, GHC will solve the `HasCallStack` constraint for the singleton `CallStack` containing just the current call-site.

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

#### Instances

Instances details

IsList CallStack # | Be aware that 'fromList . toList = id' only for unfrozen `CallStack`s, since `toList` removes frozenness information. Since: base-4.9.0.0
Instance details Defined in GHC.Exts Associated Types type Item CallStack Source # Methods fromList :: [Item CallStack] -> CallStack Source # fromListN :: Int -> [Item CallStack] -> CallStack Source # toList :: CallStack -> [Item CallStack] Source #
Show CallStack # | Since: base-4.9.0.0
Instance details Defined in GHC.Show Methods showsPrec :: Int -> CallStack -> ShowS Source # show :: CallStack -> String Source # showList :: [CallStack] -> ShowS Source #
type Item CallStack # |
Instance details Defined in GHC.Exts type Item CallStack = (String, SrcLoc)

fromCallSiteList :: [([Char], SrcLoc)] -> CallStack Source #

Convert a list of call-sites to a `CallStack`.

Since: base-4.9.0.0

getCallStack :: CallStack -> [([Char], SrcLoc)] Source #

Extract a list of call-sites from the `CallStack`.

The list is ordered by most recent call.

Since: base-4.8.1.0

prettyCallStack :: CallStack -> String Source #

Pretty print a `CallStack`.

Since: base-4.9.0.0

prettyCallStackLines :: CallStack -> [String] Source #

showCCSStack :: [String] -> [String] Source #

data SrcLoc Source #

A single location in the source code.

Since: base-4.8.1.0

Constructors

SrcLoc |
Fields srcLocPackage :: [Char] srcLocModule :: [Char] srcLocFile :: [Char] srcLocStartLine :: Int srcLocStartCol :: Int srcLocEndLine :: Int srcLocEndCol :: Int

#### Instances

Instances details

Eq SrcLoc # | Since: base-4.9.0.0
Instance details Defined in GHC.Stack.Types Methods (==) :: SrcLoc -> SrcLoc -> Bool Source # (/=) :: SrcLoc -> SrcLoc -> Bool Source #
Show SrcLoc # | Since: base-4.9.0.0
Instance details Defined in GHC.Show Methods showsPrec :: Int -> SrcLoc -> ShowS Source # show :: SrcLoc -> String Source # showList :: [SrcLoc] -> ShowS Source #

prettySrcLoc :: SrcLoc -> String Source #

Pretty print a `SrcLoc`.

Since: base-4.9.0.0