Catch exceptions that match a given Prism (or any Fold, really).

>>> catching _AssertionFailed (assert False (return "uncaught")) $ \ _ -> return "caught"
"caught"

catching :: MonadCatch m => Prism' SomeException a     -> m r -> (a -> m r) -> m r
catching :: MonadCatch m => Lens' SomeException a      -> m r -> (a -> m r) -> m r
catching :: MonadCatch m => Traversal' SomeException a -> m r -> (a -> m r) -> m r
catching :: MonadCatch m => Iso' SomeException a       -> m r -> (a -> m r) -> m r
catching :: MonadCatch m => Getter SomeException a     -> m r -> (a -> m r) -> m r
catching :: MonadCatch m => Fold SomeException a       -> m r -> (a -> m r) -> m r

Catch exceptions that match a given Prism (or any Getter), discarding the information about the match. This is particularly useful when you have a Prism' e () where the result of the Prism or Fold isn't particularly valuable, just the fact that it matches.

>>> catching_ _AssertionFailed (assert False (return "uncaught")) $ return "caught"
"caught"

catching_ :: MonadCatch m => Prism' SomeException a     -> m r -> m r -> m r
catching_ :: MonadCatch m => Lens' SomeException a      -> m r -> m r -> m r
catching_ :: MonadCatch m => Traversal' SomeException a -> m r -> m r -> m r
catching_ :: MonadCatch m => Iso' SomeException a       -> m r -> m r -> m r
catching_ :: MonadCatch m => Getter SomeException a     -> m r -> m r -> m r
catching_ :: MonadCatch m => Fold SomeException a       -> m r -> m r -> m r

A version of catching with the arguments swapped around; useful in situations where the code for the handler is shorter.

>>> handling _NonTermination (\_ -> return "caught") $ throwIO NonTermination
"caught"

handling :: MonadCatch m => Prism' SomeException a     -> (a -> m r) -> m r -> m r
handling :: MonadCatch m => Lens' SomeException a      -> (a -> m r) -> m r -> m r
handling :: MonadCatch m => Traversal' SomeException a -> (a -> m r) -> m r -> m r
handling :: MonadCatch m => Iso' SomeException a       -> (a -> m r) -> m r -> m r
handling :: MonadCatch m => Fold SomeException a       -> (a -> m r) -> m r -> m r
handling :: MonadCatch m => Getter SomeException a     -> (a -> m r) -> m r -> m r

A version of catching_ with the arguments swapped around; useful in situations where the code for the handler is shorter.

>>> handling_ _NonTermination (return "caught") $ throwIO NonTermination
"caught"

handling_ :: MonadCatch m => Prism' SomeException a     -> m r -> m r -> m r
handling_ :: MonadCatch m => Lens' SomeException a      -> m r -> m r -> m r
handling_ :: MonadCatch m => Traversal' SomeException a -> m r -> m r -> m r
handling_ :: MonadCatch m => Iso' SomeException a       -> m r -> m r -> m r
handling_ :: MonadCatch m => Getter SomeException a     -> m r -> m r -> m r
handling_ :: MonadCatch m => Fold SomeException a       -> m r -> m r -> m r

A variant of try that takes a Prism (or any Fold) to select which exceptions are caught (c.f. tryJust, catchJust). If the Exception does not match the predicate, it is re-thrown.

trying :: MonadCatch m => Prism'     SomeException a -> m r -> m (Either a r)
trying :: MonadCatch m => Lens'      SomeException a -> m r -> m (Either a r)
trying :: MonadCatch m => Traversal' SomeException a -> m r -> m (Either a r)
trying :: MonadCatch m => Iso'       SomeException a -> m r -> m (Either a r)
trying :: MonadCatch m => Getter     SomeException a -> m r -> m (Either a r)
trying :: MonadCatch m => Fold       SomeException a -> m r -> m (Either a r)

A version of trying that discards the specific exception thrown.

trying_ :: MonadCatch m => Prism'     SomeException a -> m r -> m (Maybe r)
trying_ :: MonadCatch m => Lens'      SomeException a -> m r -> m (Maybe r)
trying_ :: MonadCatch m => Traversal' SomeException a -> m r -> m (Maybe r)
trying_ :: MonadCatch m => Iso'       SomeException a -> m r -> m (Maybe r)
trying_ :: MonadCatch m => Getter     SomeException a -> m r -> m (Maybe r)
trying_ :: MonadCatch m => Fold       SomeException a -> m r -> m (Maybe r)

Throw an Exception described by a Prism. Exceptions may be thrown from purely functional code, but may only be caught within the IO Monad.

throwing l ≡ reviews l throw

throwing :: Prism' SomeException t -> t -> r
throwing :: Iso' SomeException t   -> t -> r

Similar to throwing but specialised for the common case of error constructors with no arguments.

data MyError = Foo | Bar
makePrisms ''MyError
throwing_ _Foo :: MonadError MyError m => m a

A variant of throwing that can only be used within the IO Monad (or any other MonadCatch instance) to throw an Exception described by a Prism.

Although throwingM has a type that is a specialization of the type of throwing, the two functions are subtly different:

throwing l e `seq` x  ≡ throwing e
throwingM l e `seq` x ≡ x

The first example will cause the Exception e to be raised, whereas the second one won't. In fact, throwingM will only cause an Exception to be raised when it is used within the MonadCatch instance. The throwingM variant should be used in preference to throwing to raise an Exception within the Monad because it guarantees ordering with respect to other monadic operations, whereas throwing does not.

throwingM l ≡ reviews l throw

throwingM :: MonadThrow m => Prism' SomeException t -> t -> m r
throwingM :: MonadThrow m => Iso' SomeException t   -> t -> m r

throwingTo raises an Exception specified by a Prism in the target thread.

throwingTo thread l ≡ reviews l (throwTo thread)

throwingTo :: ThreadId -> Prism' SomeException t -> t -> m a
throwingTo :: ThreadId -> Iso' SomeException t   -> t -> m a

This Setter can be used to purely map over the Exceptions an arbitrary expression might throw; it is a variant of mapException in the same way that mapped is a variant of fmap.

'mapException' ≡ 'over' 'mappedException'

This view that every Haskell expression can be regarded as carrying a bag of Exceptions is detailed in “A Semantics for Imprecise Exceptions” by Peyton Jones & al. at PLDI ’99.

The following maps failed assertions to arithmetic overflow:

>>> handling _Overflow (\_ -> return "caught") $ assert False (return "uncaught") & mappedException %~ \ (AssertionFailed _) -> Overflow
"caught"

This is a type restricted version of mappedException, which avoids the type ambiguity in the input Exception when using set.

The following maps any exception to arithmetic overflow:

>>> handling _Overflow (\_ -> return "caught") $ assert False (return "uncaught") & mappedException' .~ Overflow
"caught"

Traverse the strongly typed Exception contained in SomeException where the type of your function matches the desired Exception.

exception :: (Applicative f, Exception a)
          => (a -> f a) -> SomeException -> f SomeException

Both exceptions and Control.Exception provide a Handler type.

This lets us write combinators to build handlers that are agnostic about the choice of which of these they use.

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.

Due to their richer structure relative to other exceptions, these have a more carefully overloaded signature.

Arithmetic exceptions.

Handle arithmetic _Overflow.

_Overflow ≡ _ArithException . _Overflow

_Overflow :: Prism' ArithException ArithException
_Overflow :: Prism' SomeException  ArithException

Handle arithmetic _Underflow.

_Underflow ≡ _ArithException . _Underflow

_Underflow :: Prism' ArithException ArithException
_Underflow :: Prism' SomeException  ArithException

Handle arithmetic loss of precision.

_LossOfPrecision ≡ _ArithException . _LossOfPrecision

_LossOfPrecision :: Prism' ArithException ArithException
_LossOfPrecision :: Prism' SomeException  ArithException

Handle division by zero.

_DivideByZero ≡ _ArithException . _DivideByZero

_DivideByZero :: Prism' ArithException ArithException
_DivideByZero :: Prism' SomeException  ArithException

Handle exceptional _Denormalized floating pure.

_Denormal ≡ _ArithException . _Denormal

_Denormal :: Prism' ArithException ArithException
_Denormal :: Prism' SomeException  ArithException

_RatioZeroDenominator ≡ _ArithException . _RatioZeroDenominator

_RatioZeroDenominator :: Prism' ArithException ArithException
_RatioZeroDenominator :: Prism' SomeException  ArithException

Exceptions generated by array operations.

An attempt was made to index an array outside its declared bounds.

_IndexOutOfBounds ≡ _ArrayException . _IndexOutOfBounds

_IndexOutOfBounds :: Prism' ArrayException String
_IndexOutOfBounds :: Prism' SomeException  String

An attempt was made to evaluate an element of an array that had not been initialized.

_UndefinedElement ≡ _ArrayException . _UndefinedElement

_UndefinedElement :: Prism' ArrayException String
_UndefinedElement :: Prism' SomeException  String

assert was applied to False.

Asynchronous exceptions.

The current thread's stack exceeded its limit. Since an Exception has been raised, the thread's stack will certainly be below its limit again, but the programmer should take remedial action immediately.

_StackOverflow :: Prism' AsyncException ()
_StackOverflow :: Prism' SomeException  ()

The program's heap is reaching its limit, and the program should take action to reduce the amount of live data it has.

Notes:

• It is undefined which thread receives this Exception.
• GHC currently does not throw HeapOverflow exceptions.

_HeapOverflow :: Prism' AsyncException ()
_HeapOverflow :: Prism' SomeException  ()

This Exception is raised by another thread calling killThread, or by the system if it needs to terminate the thread for some reason.

_ThreadKilled :: Prism' AsyncException ()
_ThreadKilled :: Prism' SomeException  ()

This Exception is raised by default in the main thread of the program when the user requests to terminate the program via the usual mechanism(s) (e.g. Control-C in the console).

_UserInterrupt :: Prism' AsyncException ()
_UserInterrupt :: Prism' SomeException  ()

Thrown when the runtime system detects that the computation is guaranteed not to terminate. Note that there is no guarantee that the runtime system will notice whether any given computation is guaranteed to terminate or not.

Thrown when the program attempts to call atomically, from the STM package, inside another call to atomically.

The thread is blocked on an MVar, but there are no other references to the MVar so it can't ever continue.

The thread is waiting to retry an STM transaction, but there are no other references to any TVars involved, so it can't ever continue.

There are no runnable threads, so the program is deadlocked. The Deadlock Exception is raised in the main thread only.

A class method without a definition (neither a default definition, nor a definition in the appropriate instance) was called.

A pattern match failed.

An uninitialised record field was used.

A record selector was applied to a constructor without the appropriate field. This can only happen with a datatype with multiple constructors, where some fields are in one constructor but not another.

A record update was performed on a constructor without the appropriate field. This can only happen with a datatype with multiple constructors, where some fields are in one constructor but not another.

This is thrown when the user calls error.

This thread has exceeded its allocation limit.

An expression that didn't typecheck during compile time was called. This is only possible with -fdefer-type-errors.

Compaction found an object that cannot be compacted. Functions cannot be compacted, nor can mutable objects or pinned objects.

This Exception is thrown by lens when the user somehow manages to rethrow an internal HandlingException.