Wrapper type that tracks exceptions.

Exceptions are tracked in the phantom parameter e. In practice, e will remain polymorphic with only Throws constraints on it.

Note that although m a may be a monad transformer stack, we don't want to be able to lift into Checked because we want to avoid casually lifting something that might throw an exception without tracking the possibility safely.

Convenience type alias for when working directly with IO.

Declares an exception has been thrown.

In Throws exception e the exception parameter is the exception we're declaring has been thrown, and e is a type-level list that contains exception. This list will be solved for by the compiler, so in typical usage you will specify exception concretely leave e polymorphic.

See throws, throwsAll for examples of introducing this constraint, and see catch, handle, catches, and handles for example of removing this constraint.

Finally, note that Allowed is not exported, which prevent users from implementing more instances of Throws and bypassing safety.

A syntactic convenience to expand to multiple Throws.

ThrowsAll '[ExceptionA, ExceptionB, ...] e => ...

expands to

(Throws ExceptionA e, Throws ExceptionB e, ...) => ...

Safely get your m a.

Most importantly, you won't be able to call this function if the phantom parameter l has any Throws constraints on it.

Ignore all type-level markers that an exception hasn't been handled.

This function is provided for completeness, but may you never find a reason to use this.

Throw an exception e.

Note, this delegates to safe-exception's throw.

Throw an exception e.

Note, this delegates to safe-exception's impureThrow.

Start checking some monadic m a, declaring it as throwing nothing yet.

Start checking a monadic m a, declaring it as throwing an exception.

This API is designed for GHC's TypeApplications extension. See throws' for an alternative.

>>> :{
checkedReadFile :: Throws IOException e => FilePath -> CheckedIO e String
checkedReadFile = throws @IOException . readFile
:}

Note that technically, you can use throwsNone and widen the constraints but this can lead to confusing code:

>>> :{
checkedReadFile :: Throws IOException e => FilePath -> CheckedIO e String
checkedReadFile = throwsNone . readFile
:}

See throwsAll if your m a throws more than one exception.

Start checking some monadic m a, declaring it as throwing exceptions. exceptions should be a type-level list.

This API is designed for GHC's TypeApplications extension. See throwsAll' for an alternative.

>>> import qualified Control.Exception as E
>>> :{
readFirst :: ThrowsAll '[IOException, E.ErrorCall] e
          => [FilePath] -> CheckedIO e String
readFirst = throwsAll @'[IOException, E.ErrorCall] . readFile . head
:}

Note that technically, you can use throwsNone and widen the constraints but this can lead to confusing code:

>>> :{
readFirst :: ThrowsAll '[IOException, E.ErrorCall] e
          => [FilePath] -> CheckedIO e String
readFirst = throwsNone . readFile . head
:}

See throwsAll if your m a throws more than one exception.

Same a throws, but called with a proxy instead of a type application.

>>> import qualified Data.Proxy as P
>>> :{
checkedReadFile :: Throws IOException e => FilePath -> CheckedIO e String
checkedReadFile = throws' (P.Proxy :: P.Proxy IOException) . readFile
:}

Same a throwsAll, but called with a proxy instead of a type application.

>>> import qualified Data.Proxy as P
>>> import qualified Control.Exception as E
>>> :{
readFirst :: ThrowsAll '[IOException, E.ErrorCall] e
          => [FilePath] -> CheckedIO e String
readFirst = throwsAll' (P.Proxy :: P.Proxy '[IOException, E.ErrorCall])
    . readFile . head
:}

Throw an asynchronous exception to another thread.

Note, this delegates to safe-exception's throwTo.

Throw a semantically-neutral exception.

Note, this delegates to safe-exception's throwString.

Also, semantically, it's far better to make custom exception types. When everything thrown is a StringException, we can't handle/catch anything with any delicacy.

Catch an exception and return it via an Either.

Note, this delegates to safe-exception's try.

Catch an IOException and return it via an Either.

Note, this delegates to safe-exception's tryAny.

Catch any exception and return it via an Either.

Note, this delegates to safe-exception's tryAny.

Force a computation, catch a exception and return it via an Either.

Note, this delegates to safe-exception's tryDeep.

Force a computation, catch any exception and return it via an Either.

Note, this delegates to safe-exception's tryAnyDeep.

A variant of try using a predicate to select which exceptions to catch.

Note, this delegates to safe-exception's tryJust.

Catch a possibly asynchronous exception and return it via an Either.

Note, this delegates to safe-exception's tryAsync. Also, catching asynchronous is discouraged, but this function is provided for completeness.

Catch an exception with a provided handler.

Note, this delegates to safe-exception's catch.

Catch an IOException with a provided handler.

Note, this delegates to safe-exception's catchIO.

Catch any exception with a provided handler.

Note, this delegates to safe-exception's catchAny.

Force a computation, and catch an exception with a provided handler.

Note, this delegates to safe-exception's catchDeep.

Force a computation, and catch any exception with a provided handler.

Note, this delegates to safe-exception's catchAnyDeep.

A variant of catch using a predicate to select which exceptions to catch.

Note, this delegates to safe-exception's catchJust.

Catch a possibly asynchronous exception with a provided handler.

Note, this delegates to safe-exception's catchAsync. Also, catching asynchronous is discouraged, but this function is provided for completeness.

Flipped catch.

Flipped catchIO.

Flipped catchAny.

Flipped catchDeep.

Flipped catchAnyDeep.

Flipped catchJust.

Flipped catchAsync.

Note, catching asynchronous is discouraged, but this function is provided for completeness.

Used for catches and handles.

Handle many exceptions at once.

Just as with catches, it's important to note that there's a difference between calling

• catches with a single Handler built with many handler functions
• catch multiple times, once for each handler function.

With catches, if one of the handlers throws an exception, that exception is guaranteed to surface. With catch, if a handler throws an exception, it may be handled by a successive call to catch. Fortunately, with exceptions checked at the type-level, the compiler helps makes this explicit.

Note, this delegates to safe-exception's catches.

Same as catches, but forces computation first.

Note, this delegates to safe-exception's catchesDeep.

Same as catches, but includes asynchronous exceptions as well.

Note, this delegates to safe-exception's catchesAsync. Also, catching asynchronous is discouraged, but this function is provided for completeness.

Flipped catches.

Flipped catchesDeep.

Flipped catchesAsync.

Note, catching asynchronous is discouraged, but this function is provided for completeness.

Builds a Handler to use with catches or handles.

You can put more handler functions into the returned Handler with appendHandler, <++>, or <:>.

Chain a handler function into a Handler.

Chain two handler functions together into a Handler.

This can start a right-associative chain of handlers, which you can add to with <:>:

>>> import qualified Control.Exception as E
>>> :{
completeHandler
    :: Handler IO ()
        '[E.IOException, E.ErrorCall, E.ArithException, E.SomeException] e
completeHandler =
         (\(_::E.IOException)    -> throwsNone $ print "handledIO")
    <:>  (\(_::E.ErrorCall)      -> throwsNone $ print "handledError")
    <:>  (\(_::E.ArithException) -> throwsNone $ print "handledArith")
    <::> (\(_::E.SomeException)  -> throwsNone $ print "handledSome")
:}

Infix operator alias for appendHandler

Appends two Handlers.

A trivial empty Handler.

This may not be useful in the common case, but is here for as a convenience.

A specialised variant of bracket with just a computation to run afterward.

Delegates to finally.

Like finally, but finalizes only if an exception has been raised.

Delegates to onException.

Like onException, but provides the handler the thrown exception.

Delegates to withException.

Acquire a resource, run an action with it, and release the resource.

Delegates to bracket.

Bracket an action with one before and after.

Delegates to bracket.

Setup some context, run an action, and run another action upon an error.

Delegates to bracketOnError.

run some setup, run an action, and run another action upon an error.

Delegates to bracketOnError_.

General bracketing.

Delegates to bracketWithError.

Check if the given exception is asynchronous

Since: safe-exceptions-0.1.0.0

Check if the given exception is synchronous

Since: safe-exceptions-0.1.0.0

Convert an exception into an asynchronous exception

For asynchronous exceptions, this is the same as toException. For synchronous exceptions, this will wrap up the exception with AsyncExceptionWrapper

Since: safe-exceptions-0.1.0.0

Convert an exception into a synchronous exception

For synchronous exceptions, this is the same as toException. For asynchronous exceptions, this will wrap up the exception with SyncExceptionWrapper

Since: safe-exceptions-0.1.0.0

Wrap up a synchronous exception to be treated as an asynchronous exception

This is intended to be created via toAsyncException

Since: safe-exceptions-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

Exceptions that occur in the IO monad. An IOException records a more specific error type, a descriptive string and maybe the handle that was used when the error was flagged.

A class for monads which allow exceptions to be caught, in particular exceptions which were thrown by throwM.

Instances should obey the following law:

catch (throwM e) f = f e

Note that the ability to catch an exception does not guarantee that we can deal with all possible exit points from a computation. Some monads, such as continuation-based stacks, allow for more than just a success/failure strategy, and therefore catch cannot be used by those monads to properly implement a function such as finally. For more information, see MonadMask.

A class for monads which provide for the ability to account for all possible exit points from a computation, and to mask asynchronous exceptions. Continuation-based monads are invalid instances of this class.

Instances should ensure that, in the following code:

fg = f `finally` g

The action g is called regardless of what occurs within f, including async exceptions. Some monads allow f to abort the computation via other effects than throwing an exception. For simplicity, we will consider aborting and throwing an exception to be two forms of "throwing an error".

If f and g both throw an error, the error thrown by fg depends on which errors we're talking about. In a monad transformer stack, the deeper layers override the effects of the inner layers; for example, ExceptT e1 (Except e2) a represents a value of type Either e2 (Either e1 a), so throwing both an e1 and an e2 will result in Left e2. If f and g both throw an error from the same layer, instances should ensure that the error from g wins.

Effects other than throwing an error are also overriden by the deeper layers. For example, StateT s Maybe a represents a value of type s -> Maybe (a, s), so if an error thrown from f causes this function to return Nothing, any changes to the state which f also performed will be erased. As a result, g will see the state as it was before f. Once g completes, f's error will be rethrown, so g' state changes will be erased as well. This is the normal interaction between effects in a monad transformer stack.

By contrast, lifted-base's version of finally always discards all of g's non-IO effects, and g never sees any of f's non-IO effects, regardless of the layer ordering and regardless of whether f throws an error. This is not the result of interacting effects, but a consequence of MonadBaseControl's approach.

A class for monads in which exceptions may be thrown.

Instances should obey the following law:

throwM e >> x = throwM e

In other words, throwing an exception short-circuits the rest of the monadic computation.

Superclass for asynchronous exceptions.

Since: base-4.7.0.0

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.

Wrap up an asynchronous exception to be treated as a synchronous exception

This is intended to be created via toSyncException

Since: safe-exceptions-0.1.0.0

The class Typeable allows a concrete representation of a type to be calculated.

Inferred instance of Throws.

Implementation detail enabling catches and handles.

Implementation detail enabling appendHandler and <++>.