The AnnotatedException type wraps an exception with a [Annotation]. This can provide a sort of a manual stack trace with programmer provided data.

Since: 0.1.0.0

Annotate the underlying exception with a CallStack.

Since: 0.2.0.0

Like throwWithCallStack, but uses MonadIO instead of MonadThrow.

Since: 0.1.2.0

Like checkpoint, but uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Like checkpointMany, but uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Like checkpointCallStack, but uses MonadUnliftIO instead of MonadCatch.

Since: 0.2.0.2

Like checkpointCallStackWith, but uses MonadUnliftIO instead of MonadCatch.

Deprecated in 0.2.0.0 as it is now an alias for checkpointMany.

Since: 0.1.2.0

Like catch, but uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Like catches, bt uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Like tryAnnotated but uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Like try but uses MonadUnliftIO instead of MonadCatch.

Since: 0.1.2.0

Call fromException on the underlying Exception, attaching the annotations to the result.

Since: 0.1.0.0

Call toException on the underlying Exception.

Since: 0.1.0.0

Retrieves the CallStack from an AnnotatedException if one is present.

The library maintains an internal check that a single CallStack is present in the list, so this only returns the first one found. If you have added a CallStack directly to the [Annotation], then this will likely break.

Since: 0.1.0.0

Adds a CallStack to the given AnnotatedException. This function will search through the existing annotations, and it will not add a second CallStack to the list. Instead, it will append the contents of the given CallStack to the existing one.

This mirrors the behavior of the way HasCallStack actually works.

Since: 0.1.0.0

An Annotation is a wrapper around a value that includes a Typeable constraint so we can later unpack it. It is essentially a Dynamic, but we also include Show so that you can always fall back to simply showing the Annotation if it is otherwise unrecognized.

Since: 0.1.0.0

A wrapper type for putting a CallStack into an Annotation. We need this because CallStack does not have an Eq instance.

Deprecated in 0.2.0.0 since you can just put a CallStack directly in an Annotation now that we have no need for an Eq constraint on it.

Since: 0.1.0.0

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

Like throw, but uses MonadIO instead of MonadThrow.

Since: 0.1.2.0

Generalized version of Handler

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Monads which allow their actions to be run in IO.

While MonadIO allows an IO action to be lifted into another monad, this class captures the opposite concept: allowing you to capture the monadic context. Note that, in order to meet the laws given below, the intuition is that a monad must have no monadic state, but may have monadic context. This essentially limits MonadUnliftIO to ReaderT and IdentityT transformers on top of IO.

Laws. For any function run provided by withRunInIO, it must meet the monad transformer laws as reformulated for MonadUnliftIO:

• run . return = return

• run (m >>= f) = run m >>= run . f

Instances of MonadUnliftIO must also satisfy the following laws:

Identity law

withRunInIO (\run -> run m) = m

Inverse law

withRunInIO (\_ -> m) = liftIO m

As an example of an invalid instance, a naive implementation of MonadUnliftIO (StateT s m) might be

withRunInIO inner =
  StateT $ \s ->
    withRunInIO $ \run ->
      inner (run . flip evalStateT s)

This breaks the identity law because the inner run m would throw away any state changes in m.

Since: unliftio-core-0.1.0.0