HORIZON HASKELLDocslts/ghc-10.0.x77a86622026-10-31Search packagesCtrl K
Theme: |

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 77a8662 · 2026-10-31

Modulelens-5.3.6Haskell2010

Control.Exception.Lens

Control.Exception provides an example of a large open hierarchy that we can model with prisms and isomorphisms.

Additional combinators for working with IOException results can be found in System.IO.Error.Lens.

The combinators in this module have been generalized to work with MonadCatch instead of just IO. This enables them to be used more easily in Monad transformer stacks.

Contents
  1. Handling
  2. Trying
  3. Throwing
  4. Mapping
  5. Exceptions
  6. Exception Handlers
  7. IOExceptions
  8. Arithmetic Exceptions
  9. Array Exceptions
  10. Assertion Failed
  11. Async Exceptions
  12. Non-Termination
  13. Nested Atomically
  14. Blocked Indefinitely
  15. on MVar
  16. on STM
  17. Deadlock
  18. No Such Method
  19. Pattern Match Failure
  20. Record
  21. Error Call
  22. Allocation Limit Exceeded
  23. Type Error
  24. Compaction Failed
  25. Handling Exceptions
Synopsis
  • Packagelens-5.3.6
  • Exports95
  • LanguageHaskell2010
  • LicenceBSD-2-Clause
  • SourceLens.hs

Handling

valuecatching
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> m r
  4. -> a -> m r
  5. -> m r
Source#

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

Example1 expression
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
valuecatching_
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> m r
  4. -> m r
  5. -> m r
Source#

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.

Example1 expression
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
valuehandling
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> a -> m r
  4. -> m r
  5. -> m r
Source#

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

Example1 expression
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
valuehandling_
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> m r
  4. -> m r
  5. -> m r
Source#

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

Example1 expression
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

Trying

valuetrying
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> m r
  4. -> m (Either a r)
Source#

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)
valuetrying_
  1. :: MonadCatch m
  2. => Getting (First a) SomeException a
  3. -> m r
  4. -> m (Maybe r)
Source#

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)

Throwing

valuethrowingM :: MonadThrow m => AReview SomeException b -> b -> m r
Source#

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 CatchIO.throw

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

Mapping

valuemappedException :: (Exception e, Exception e') => Setter s s e e'
Source#

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:

Example1 expression
handling _Overflow (\_ -> return "caught") $ assert False (return "uncaught") & mappedException %~ \ (AssertionFailed _) -> Overflow"caught"
valuemappedException' :: Exception e' => Setter s s SomeException e'
Source#

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:

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

Exceptions

Exception Handlers

classclass Handleable e (m :: Type -> Type) (h :: Type -> Type) | h -> e m where
Source#

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.

Methods

Instances3Handleable

IOExceptions

classclass AsIOException t where
Source#

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.

Methods

Instances2AsIOException

Arithmetic Exceptions

Array Exceptions

Assertion Failed

classclass AsAssertionFailed t where
Source#

assert was applied to False.

Methods

Instances2AsAssertionFailed

Async Exceptions

Non-Termination

classclass AsNonTermination t where
Source#

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.

Methods

Instances2AsNonTermination

Nested Atomically

classclass AsNestedAtomically t where
Source#

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

Methods

Instances2AsNestedAtomically

Blocked Indefinitely

on MVar

classclass AsBlockedIndefinitelyOnMVar t where
Source#

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

Methods

Instances2AsBlockedIndefinitelyOnMVar

on STM

classclass AsBlockedIndefinitelyOnSTM t where
Source#

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.

Methods

Instances2AsBlockedIndefinitelyOnSTM

Deadlock

classclass AsDeadlock t where
Source#

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

Methods

Instances2AsDeadlock

No Such Method

classclass AsNoMethodError t where
Source#

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

Methods

Instances2AsNoMethodError

Pattern Match Failure

classclass AsPatternMatchFail t where
Source#

A pattern match failed.

Methods

Instances2AsPatternMatchFail

Record

classclass AsRecConError t where
Source#

An uninitialised record field was used.

Methods

Instances2AsRecConError
classclass AsRecSelError t where
Source#

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.

Methods

Instances2AsRecSelError
classclass AsRecUpdError t where
Source#

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.

Methods

Instances2AsRecUpdError

Error Call

classclass AsErrorCall t where
Source#

This is thrown when the user calls error.

Methods

Instances2AsErrorCall

Allocation Limit Exceeded

classclass AsAllocationLimitExceeded t where
Source#

This thread has exceeded its allocation limit.

Methods

Instances2AsAllocationLimitExceeded

Type Error

classclass AsTypeError t where
Source#

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

Methods

Instances2AsTypeError

Compaction Failed

classclass AsCompactionFailed t where
Source#

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

Methods

Instances2AsCompactionFailed

Handling Exceptions

classclass AsHandlingException t where
Source#

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

Methods

Instances2AsHandlingException