lens-5.2.3: Lenses, Folds and Traversals

Copyright | (C) 2012-16 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | provisional
Portability | Control.Exception
Safe Haskell | Trustworthy
Language | Haskell2010

Control.Exception.Lens

Contents

- Handling
- Trying
- Throwing
- Mapping
- Exceptions
- Exception Handlers
  - IOExceptions
  - Arithmetic Exceptions
  - Array Exceptions
  - Assertion Failed
  - Async Exceptions
  - Non-Termination
  - Nested Atomically
  - Blocked Indefinitely
    - on MVar
    - on STM
  - Deadlock
  - No Such Method
  - Pattern Match Failure
  - Record
  - Error Call
  - Allocation Limit Exceeded
  - Type Error
  - Compaction Failed
- Handling Exceptions

Description

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

Synopsis

- catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r
- catching_ :: MonadCatch m => Getting (First a) SomeException a -> m r -> m r -> m r
- handling :: MonadCatch m => Getting (First a) SomeException a -> (a -> m r) -> m r -> m r
- handling_ :: MonadCatch m => Getting (First a) SomeException a -> m r -> m r -> m r
- trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a r)
- trying_ :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Maybe r)
- throwing :: AReview SomeException b -> b -> r
- throwing_ :: AReview SomeException () -> m x
- throwingM :: MonadThrow m => AReview SomeException b -> b -> m r
- throwingTo :: MonadIO m => ThreadId -> AReview SomeException b -> b -> m ()
- mappedException :: (Exception e, Exception e') => Setter s s e e'
- mappedException' :: Exception e' => Setter s s SomeException e'
- exception :: Exception a => Prism' SomeException a
- pattern Exception :: Exception a => a -> SomeException
- class Handleable e (m :: Type -> Type) (h :: Type -> Type) | h -> e m where
  - handler :: Typeable a => Getting (First a) e a -> (a -> m r) -> h r
  - handler_ :: Typeable a => Getting (First a) e a -> m r -> h r
- class AsIOException t where
  - _IOException :: Prism' t IOException
- pattern IOException_ :: AsIOException s => IOException -> s
- class AsArithException t where
  - _ArithException :: Prism' t ArithException
- _Overflow :: AsArithException t => Prism' t ()
- _Underflow :: AsArithException t => Prism' t ()
- _LossOfPrecision :: AsArithException t => Prism' t ()
- _DivideByZero :: AsArithException t => Prism' t ()
- _Denormal :: AsArithException t => Prism' t ()
- _RatioZeroDenominator :: AsArithException t => Prism' t ()
- pattern ArithException_ :: AsArithException s => ArithException -> s
- pattern Overflow_ :: AsArithException s => s
- pattern Underflow_ :: AsArithException s => s
- pattern LossOfPrecision_ :: AsArithException s => s
- pattern DivideByZero_ :: AsArithException s => s
- pattern Denormal_ :: AsArithException s => s
- pattern RatioZeroDenominator_ :: AsArithException s => s
- class AsArrayException t where
  - _ArrayException :: Prism' t ArrayException
- _IndexOutOfBounds :: AsArrayException t => Prism' t String
- _UndefinedElement :: AsArrayException t => Prism' t String
- pattern ArrayException_ :: AsArrayException s => ArrayException -> s
- pattern IndexOutOfBounds_ :: AsArrayException s => String -> s
- pattern UndefinedElement_ :: AsArrayException s => String -> s
- class AsAssertionFailed t where
  - __AssertionFailed :: Prism' t AssertionFailed
  - _AssertionFailed :: Prism' t String
- pattern AssertionFailed__ :: AsAssertionFailed s => AssertionFailed -> s
- pattern AssertionFailed_ :: AsAssertionFailed s => String -> s
- class AsAsyncException t where
  - _AsyncException :: Prism' t AsyncException
- _StackOverflow :: AsAsyncException t => Prism' t ()
- _HeapOverflow :: AsAsyncException t => Prism' t ()
- _ThreadKilled :: AsAsyncException t => Prism' t ()
- _UserInterrupt :: AsAsyncException t => Prism' t ()
- pattern AsyncException_ :: AsAsyncException s => AsyncException -> s
- pattern StackOverflow_ :: AsAsyncException s => s
- pattern HeapOverflow_ :: AsAsyncException s => s
- pattern ThreadKilled_ :: AsAsyncException s => s
- pattern UserInterrupt_ :: AsAsyncException s => s
- class AsNonTermination t where
  - __NonTermination :: Prism' t NonTermination
  - _NonTermination :: Prism' t ()
- pattern NonTermination__ :: AsNonTermination s => NonTermination -> s
- pattern NonTermination_ :: AsNonTermination s => s
- class AsNestedAtomically t where
  - __NestedAtomically :: Prism' t NestedAtomically
  - _NestedAtomically :: Prism' t ()
- pattern NestedAtomically__ :: AsNestedAtomically s => NestedAtomically -> s
- pattern NestedAtomically_ :: AsNestedAtomically s => s
- class AsBlockedIndefinitelyOnMVar t where
  - __BlockedIndefinitelyOnMVar :: Prism' t BlockedIndefinitelyOnMVar
  - _BlockedIndefinitelyOnMVar :: Prism' t ()
- pattern BlockedIndefinitelyOnMVar__ :: AsBlockedIndefinitelyOnMVar s => BlockedIndefinitelyOnMVar -> s
- pattern BlockedIndefinitelyOnMVar_ :: AsBlockedIndefinitelyOnMVar s => s
- class AsBlockedIndefinitelyOnSTM t where
  - __BlockedIndefinitelyOnSTM :: Prism' t BlockedIndefinitelyOnSTM
  - _BlockedIndefinitelyOnSTM :: Prism' t ()
- pattern BlockedIndefinitelyOnSTM__ :: AsBlockedIndefinitelyOnSTM s => BlockedIndefinitelyOnSTM -> s
- pattern BlockedIndefinitelyOnSTM_ :: AsBlockedIndefinitelyOnSTM s => s
- class AsDeadlock t where
  - __Deadlock :: Prism' t Deadlock
  - _Deadlock :: Prism' t ()
- pattern Deadlock__ :: AsDeadlock s => Deadlock -> s
- pattern Deadlock_ :: AsDeadlock s => s
- class AsNoMethodError t where
  - __NoMethodError :: Prism' t NoMethodError
  - _NoMethodError :: Prism' t String
- pattern NoMethodError__ :: AsNoMethodError s => NoMethodError -> s
- pattern NoMethodError_ :: AsNoMethodError s => String -> s
- class AsPatternMatchFail t where
  - __PatternMatchFail :: Prism' t PatternMatchFail
  - _PatternMatchFail :: Prism' t String
- pattern PatternMatchFail__ :: AsPatternMatchFail s => PatternMatchFail -> s
- pattern PatternMatchFail_ :: AsPatternMatchFail s => String -> s
- class AsRecConError t where
  - __RecConError :: Prism' t RecConError
  - _RecConError :: Prism' t String
- class AsRecSelError t where
  - __RecSelError :: Prism' t RecSelError
  - _RecSelError :: Prism' t String
- class AsRecUpdError t where
  - __RecUpdError :: Prism' t RecUpdError
  - _RecUpdError :: Prism' t String
- pattern RecConError__ :: AsRecConError s => RecConError -> s
- pattern RecConError_ :: AsRecConError s => String -> s
- pattern RecSelError__ :: AsRecSelError s => RecSelError -> s
- pattern RecSelError_ :: AsRecSelError s => String -> s
- pattern RecUpdError__ :: AsRecUpdError s => RecUpdError -> s
- pattern RecUpdError_ :: AsRecUpdError s => String -> s
- class AsErrorCall t where
  - __ErrorCall :: Prism' t ErrorCall
  - _ErrorCall :: Prism' t String
- pattern ErrorCall__ :: AsErrorCall s => ErrorCall -> s
- pattern ErrorCall_ :: AsErrorCall s => String -> s
- class AsAllocationLimitExceeded t where
  - __AllocationLimitExceeded :: Prism' t AllocationLimitExceeded
  - _AllocationLimitExceeded :: Prism' t ()
- pattern AllocationLimitExceeded__ :: AsAllocationLimitExceeded s => AllocationLimitExceeded -> s
- pattern AllocationLimitExceeded_ :: AsAllocationLimitExceeded s => s
- class AsTypeError t where
  - __TypeError :: Prism' t TypeError
  - _TypeError :: Prism' t String
- pattern TypeError__ :: AsTypeError s => TypeError -> s
- pattern TypeError_ :: AsTypeError s => String -> s
- class AsCompactionFailed t where
  - __CompactionFailed :: Prism' t CompactionFailed
  - _CompactionFailed :: Prism' t String
- pattern CompactionFailed__ :: AsCompactionFailed s => CompactionFailed -> s
- pattern CompactionFailed_ :: AsCompactionFailed s => String -> s
- class AsHandlingException t where
  - __HandlingException :: Prism' t HandlingException
  - _HandlingException :: Prism' t ()
- pattern HandlingException__ :: AsHandlingException s => HandlingException -> s
- pattern HandlingException_ :: AsHandlingException s => s

# Handling

catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r #

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

catching_ :: MonadCatch m => Getting (First a) SomeException a -> m r -> 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

handling :: MonadCatch m => Getting (First a) 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     -> (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

handling_ :: MonadCatch m => Getting (First a) 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     -> 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

trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a 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)

trying_ :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Maybe 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)

# Throwing

throwing :: AReview SomeException b -> b -> 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

throwing_ :: AReview SomeException () -> m x #

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

throwingM :: MonadThrow m => AReview SomeException b -> b -> m r #

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 :: MonadIO m => ThreadId -> AReview SomeException b -> b -> m () #

`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

# Mapping

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

This `Setter` can be used to purely map over the `Exception`s 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 `Exception`s 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"

mappedException' :: Exception e' => Setter s s SomeException e' #

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"

# Exceptions

exception :: Exception a => Prism' SomeException a #

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

pattern Exception :: Exception a => a -> SomeException #

# Exception Handlers

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

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.

Minimal complete definition

handler

Methods

handler :: Typeable a => Getting (First a) e a -> (a -> m r) -> h r #

This builds a `Handler` for just the targets of a given `Prism` (or any `Getter`, really).

    catches ... [ handler _AssertionFailed (s -> print $ "Assertion Failed\n" ++ s)
                , handler _ErrorCall (s -> print $ "Error\n" ++ s)
                ]

This works ith both the `Handler` type provided by `Control.Exception`:

    handler :: Getter     SomeException a -> (a -> IO r) -> Handler r
    handler :: Fold       SomeException a -> (a -> IO r) -> Handler r
    handler :: Prism'     SomeException a -> (a -> IO r) -> Handler r
    handler :: Lens'      SomeException a -> (a -> IO r) -> Handler r
    handler :: Traversal' SomeException a -> (a -> IO r) -> Handler r

and with the `Handler` type provided by `Control.Monad.Catch`:

    handler :: Getter     SomeException a -> (a -> m r) -> Handler m r
    handler :: Fold       SomeException a -> (a -> m r) -> Handler m r
    handler :: Prism'     SomeException a -> (a -> m r) -> Handler m r
    handler :: Lens'      SomeException a -> (a -> m r) -> Handler m r
    handler :: Traversal' SomeException a -> (a -> m r) -> Handler m r

and with the `Handler` type provided by `Control.Monad.Error.Lens`:

    handler :: Getter     e a -> (a -> m r) -> Handler e m r
    handler :: Fold       e a -> (a -> m r) -> Handler e m r
    handler :: Prism'     e a -> (a -> m r) -> Handler e m r
    handler :: Lens'      e a -> (a -> m r) -> Handler e m r
    handler :: Traversal' e a -> (a -> m r) -> Handler e m r

handler_ :: Typeable a => Getting (First a) e a -> m r -> h r #

This builds a `Handler` for just the targets of a given `Prism` (or any `Getter`, really). that ignores its input and just recovers with the stated monadic action.

    catches ... [ handler_ _NonTermination (return "looped")
                , handler_ _StackOverflow (return "overflow")
                ]

This works with the `Handler` type provided by `Control.Exception`:

    handler_ :: Getter     SomeException a -> IO r -> Handler r
    handler_ :: Fold       SomeException a -> IO r -> Handler r
    handler_ :: Prism'     SomeException a -> IO r -> Handler r
    handler_ :: Lens'      SomeException a -> IO r -> Handler r
    handler_ :: Traversal' SomeException a -> IO r -> Handler r

and with the `Handler` type provided by `Control.Monad.Catch`:

    handler_ :: Getter     SomeException a -> m r -> Handler m r
    handler_ :: Fold       SomeException a -> m r -> Handler m r
    handler_ :: Prism'     SomeException a -> m r -> Handler m r
    handler_ :: Lens'      SomeException a -> m r -> Handler m r
    handler_ :: Traversal' SomeException a -> m r -> Handler m r

and with the `Handler` type provided by `Control.Monad.Error.Lens`:

    handler_ :: Getter     e a -> m r -> Handler e m r
    handler_ :: Fold       e a -> m r -> Handler e m r
    handler_ :: Prism'     e a -> m r -> Handler e m r
    handler_ :: Lens'      e a -> m r -> Handler e m r
    handler_ :: Traversal' e a -> m r -> Handler e m r

#### Instances

Instances details

Handleable SomeException IO Handler # |
Instance details Defined in Control.Lens.Internal.Exception Methods handler :: Typeable a => Getting (First a) SomeException a -> (a -> IO r) -> Handler r # handler_ :: Typeable a => Getting (First a) SomeException a -> IO r -> Handler r #
Typeable m => Handleable SomeException m (Handler m) # |
Instance details Defined in Control.Lens.Internal.Exception Methods handler :: Typeable a => Getting (First a) SomeException a -> (a -> m r) -> Handler m r # handler_ :: Typeable a => Getting (First a) SomeException a -> m r -> Handler m r #
Handleable e m (Handler e m) # |
Instance details Defined in Control.Monad.Error.Lens Methods handler :: Typeable a => Getting (First a) e a -> (a -> m r) -> Handler e m r # handler_ :: Typeable a => Getting (First a) e a -> m r -> Handler e m r #

## IOExceptions

class AsIOException t where #

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

_IOException :: Prism' t IOException #

Unfortunately the name `ioException` is taken by `base` for throwing IOExceptions.

    _IOException :: Prism' IOException IOException
    _IOException :: Prism' SomeException IOException

Many combinators for working with an `IOException` are available in System.IO.Error.Lens.

#### Instances

Instances details

AsIOException SomeException # |
Instance details Defined in Control.Exception.Lens Methods _IOException :: Prism' SomeException IOException #
AsIOException IOException # |
Instance details Defined in Control.Exception.Lens Methods _IOException :: Prism' IOException IOException #

pattern IOException_ :: AsIOException s => IOException -> s #

## Arithmetic Exceptions

class AsArithException t where #

Arithmetic exceptions.

Methods

_ArithException :: Prism' t ArithException #

    _ArithException :: Prism' ArithException ArithException
    _ArithException :: Prism' SomeException  ArithException

#### Instances

Instances details

AsArithException ArithException # |
Instance details Defined in Control.Exception.Lens Methods _ArithException :: Prism' ArithException ArithException #
AsArithException SomeException # |
Instance details Defined in Control.Exception.Lens Methods _ArithException :: Prism' SomeException ArithException #

_Overflow :: AsArithException t => Prism' t () #

Handle arithmetic `_Overflow`.

    _Overflow ≡ _ArithException . _Overflow

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

_Underflow :: AsArithException t => Prism' t () #

Handle arithmetic `_Underflow`.

    _Underflow ≡ _ArithException . _Underflow

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

_LossOfPrecision :: AsArithException t => Prism' t () #

Handle arithmetic loss of precision.

    _LossOfPrecision ≡ _ArithException . _LossOfPrecision

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

_DivideByZero :: AsArithException t => Prism' t () #

Handle division by zero.

    _DivideByZero ≡ _ArithException . _DivideByZero

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

_Denormal :: AsArithException t => Prism' t () #

Handle exceptional _Denormalized floating pure.

    _Denormal ≡ _ArithException . _Denormal

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

_RatioZeroDenominator :: AsArithException t => Prism' t () #

    _RatioZeroDenominator ≡ _ArithException . _RatioZeroDenominator

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

pattern ArithException_ :: AsArithException s => ArithException -> s #

pattern Overflow_ :: AsArithException s => s #

pattern Underflow_ :: AsArithException s => s #

pattern LossOfPrecision_ :: AsArithException s => s #

pattern DivideByZero_ :: AsArithException s => s #

pattern Denormal_ :: AsArithException s => s #

pattern RatioZeroDenominator_ :: AsArithException s => s #

## Array Exceptions

class AsArrayException t where #

Exceptions generated by array operations.

Methods

_ArrayException :: Prism' t ArrayException #

Extract information about an `ArrayException`.

    _ArrayException :: Prism' ArrayException ArrayException
    _ArrayException :: Prism' SomeException  ArrayException

#### Instances

Instances details

AsArrayException SomeException # |
Instance details Defined in Control.Exception.Lens Methods _ArrayException :: Prism' SomeException ArrayException #
AsArrayException ArrayException # |
Instance details Defined in Control.Exception.Lens Methods _ArrayException :: Prism' ArrayException ArrayException #

_IndexOutOfBounds :: AsArrayException t => Prism' t String #

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

    _IndexOutOfBounds ≡ _ArrayException . _IndexOutOfBounds

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

_UndefinedElement :: AsArrayException t => Prism' t 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

pattern ArrayException_ :: AsArrayException s => ArrayException -> s #

pattern IndexOutOfBounds_ :: AsArrayException s => String -> s #

pattern UndefinedElement_ :: AsArrayException s => String -> s #

## Assertion Failed

class AsAssertionFailed t where #

`assert` was applied to `False`.

Minimal complete definition

__AssertionFailed

Methods

__AssertionFailed :: Prism' t AssertionFailed #

    __AssertionFailed :: Prism' AssertionFailed AssertionFailed
    __AssertionFailed :: Prism' SomeException   AssertionFailed

_AssertionFailed :: Prism' t String #

This `Exception` contains provides information about what assertion failed in the `String`.

    >>> handling _AssertionFailed (\ xs -> "caught" <$ guard ("<interactive>" `isInfixOf` xs) ) $ assert False (return "uncaught")
    "caught"

    _AssertionFailed :: Prism' AssertionFailed String
    _AssertionFailed :: Prism' SomeException   String

#### Instances

Instances details

AsAssertionFailed SomeException # |
Instance details Defined in Control.Exception.Lens Methods __AssertionFailed :: Prism' SomeException AssertionFailed # _AssertionFailed :: Prism' SomeException String #
AsAssertionFailed AssertionFailed # |
Instance details Defined in Control.Exception.Lens Methods __AssertionFailed :: Prism' AssertionFailed AssertionFailed # _AssertionFailed :: Prism' AssertionFailed String #

pattern AssertionFailed__ :: AsAssertionFailed s => AssertionFailed -> s #

pattern AssertionFailed_ :: AsAssertionFailed s => String -> s #

## Async Exceptions

class AsAsyncException t where #

Asynchronous exceptions.

Methods

_AsyncException :: Prism' t AsyncException #

There are several types of `AsyncException`.

    _AsyncException :: Equality' AsyncException AsyncException
    _AsyncException :: Prism'    SomeException  AsyncException

#### Instances

Instances details

AsAsyncException SomeException # |
Instance details Defined in Control.Exception.Lens Methods _AsyncException :: Prism' SomeException AsyncException #
AsAsyncException AsyncException # |
Instance details Defined in Control.Exception.Lens Methods _AsyncException :: Prism' AsyncException AsyncException #

_StackOverflow :: AsAsyncException t => Prism' t () #

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  ()

_HeapOverflow :: AsAsyncException t => Prism' t () #

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  ()

_ThreadKilled :: AsAsyncException t => Prism' t () #

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  ()

_UserInterrupt :: AsAsyncException t => Prism' t () #

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  ()

pattern AsyncException_ :: AsAsyncException s => AsyncException -> s #

pattern StackOverflow_ :: AsAsyncException s => s #

pattern HeapOverflow_ :: AsAsyncException s => s #

pattern ThreadKilled_ :: AsAsyncException s => s #

pattern UserInterrupt_ :: AsAsyncException s => s #

## Non-Termination

class AsNonTermination t where #

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.

Minimal complete definition

__NonTermination

Methods

__NonTermination :: Prism' t NonTermination #

    __NonTermination :: Prism' NonTermination NonTermination
    __NonTermination :: Prism' SomeException  NonTermination

_NonTermination :: Prism' t () #

There is no additional information carried in a `NonTermination` `Exception`.

    _NonTermination :: Prism' NonTermination ()
    _NonTermination :: Prism' SomeException  ()

#### Instances

Instances details

AsNonTermination NonTermination # |
Instance details Defined in Control.Exception.Lens Methods __NonTermination :: Prism' NonTermination NonTermination # _NonTermination :: Prism' NonTermination () #
AsNonTermination SomeException # |
Instance details Defined in Control.Exception.Lens Methods __NonTermination :: Prism' SomeException NonTermination # _NonTermination :: Prism' SomeException () #

pattern NonTermination__ :: AsNonTermination s => NonTermination -> s #

pattern NonTermination_ :: AsNonTermination s => s #

## Nested Atomically

class AsNestedAtomically t where #

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

Minimal complete definition

__NestedAtomically

Methods

__NestedAtomically :: Prism' t NestedAtomically #

    __NestedAtomically :: Prism' NestedAtomically NestedAtomically
    __NestedAtomically :: Prism' SomeException    NestedAtomically

_NestedAtomically :: Prism' t () #

There is no additional information carried in a `NestedAtomically` `Exception`.

    _NestedAtomically :: Prism' NestedAtomically ()
    _NestedAtomically :: Prism' SomeException    ()

#### Instances

Instances details

AsNestedAtomically NestedAtomically # |
Instance details Defined in Control.Exception.Lens Methods __NestedAtomically :: Prism' NestedAtomically NestedAtomically # _NestedAtomically :: Prism' NestedAtomically () #
AsNestedAtomically SomeException # |
Instance details Defined in Control.Exception.Lens Methods __NestedAtomically :: Prism' SomeException NestedAtomically # _NestedAtomically :: Prism' SomeException () #

pattern NestedAtomically__ :: AsNestedAtomically s => NestedAtomically -> s #

pattern NestedAtomically_ :: AsNestedAtomically s => s #

## Blocked Indefinitely

### on MVar

class AsBlockedIndefinitelyOnMVar t where #

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

Minimal complete definition

__BlockedIndefinitelyOnMVar

Methods

__BlockedIndefinitelyOnMVar :: Prism' t BlockedIndefinitelyOnMVar #

    __BlockedIndefinitelyOnMVar :: Prism' BlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar
    __BlockedIndefinitelyOnMVar :: Prism' SomeException             BlockedIndefinitelyOnMVar

_BlockedIndefinitelyOnMVar :: Prism' t () #

There is no additional information carried in a `BlockedIndefinitelyOnMVar` `Exception`.

    _BlockedIndefinitelyOnMVar :: Prism' BlockedIndefinitelyOnMVar ()
    _BlockedIndefinitelyOnMVar :: Prism' SomeException             ()

#### Instances

Instances details

AsBlockedIndefinitelyOnMVar SomeException # |
Instance details Defined in Control.Exception.Lens Methods __BlockedIndefinitelyOnMVar :: Prism' SomeException BlockedIndefinitelyOnMVar # _BlockedIndefinitelyOnMVar :: Prism' SomeException () #
AsBlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar # |
Instance details Defined in Control.Exception.Lens Methods __BlockedIndefinitelyOnMVar :: Prism' BlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar # _BlockedIndefinitelyOnMVar :: Prism' BlockedIndefinitelyOnMVar () #

pattern BlockedIndefinitelyOnMVar__ :: AsBlockedIndefinitelyOnMVar s => BlockedIndefinitelyOnMVar -> s #

pattern BlockedIndefinitelyOnMVar_ :: AsBlockedIndefinitelyOnMVar s => s #

### on STM

class AsBlockedIndefinitelyOnSTM t where #

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.

Minimal complete definition

__BlockedIndefinitelyOnSTM

Methods

__BlockedIndefinitelyOnSTM :: Prism' t BlockedIndefinitelyOnSTM #

    __BlockedIndefinitelyOnSTM :: Prism' BlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM
    __BlockedIndefinitelyOnSTM :: Prism' SomeException            BlockedIndefinitelyOnSTM

_BlockedIndefinitelyOnSTM :: Prism' t () #

There is no additional information carried in a `BlockedIndefinitelyOnSTM` `Exception`.

    _BlockedIndefinitelyOnSTM :: Prism' BlockedIndefinitelyOnSTM ()
    _BlockedIndefinitelyOnSTM :: Prism' SomeException            ()

#### Instances

Instances details

AsBlockedIndefinitelyOnSTM SomeException # |
Instance details Defined in Control.Exception.Lens Methods __BlockedIndefinitelyOnSTM :: Prism' SomeException BlockedIndefinitelyOnSTM # _BlockedIndefinitelyOnSTM :: Prism' SomeException () #
AsBlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM # |
Instance details Defined in Control.Exception.Lens Methods __BlockedIndefinitelyOnSTM :: Prism' BlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM # _BlockedIndefinitelyOnSTM :: Prism' BlockedIndefinitelyOnSTM () #

pattern BlockedIndefinitelyOnSTM__ :: AsBlockedIndefinitelyOnSTM s => BlockedIndefinitelyOnSTM -> s #

pattern BlockedIndefinitelyOnSTM_ :: AsBlockedIndefinitelyOnSTM s => s #

## Deadlock

class AsDeadlock t where #

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

Minimal complete definition

__Deadlock

Methods

__Deadlock :: Prism' t Deadlock #

    __Deadlock :: Prism' Deadlock      Deadlock
    __Deadlock :: Prism' SomeException Deadlock

_Deadlock :: Prism' t () #

There is no information carried in a `Deadlock` `Exception`.

    _Deadlock :: Prism' Deadlock      ()
    _Deadlock :: Prism' SomeException ()

#### Instances

Instances details

AsDeadlock SomeException # |
Instance details Defined in Control.Exception.Lens Methods __Deadlock :: Prism' SomeException Deadlock # _Deadlock :: Prism' SomeException () #
AsDeadlock Deadlock # |
Instance details Defined in Control.Exception.Lens Methods __Deadlock :: Prism' Deadlock Deadlock # _Deadlock :: Prism' Deadlock () #

pattern Deadlock__ :: AsDeadlock s => Deadlock -> s #

pattern Deadlock_ :: AsDeadlock s => s #

## No Such Method

class AsNoMethodError t where #

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

Minimal complete definition

__NoMethodError

Methods

__NoMethodError :: Prism' t NoMethodError #

    __NoMethodError :: Prism' NoMethodError NoMethodError
    __NoMethodError :: Prism' SomeException NoMethodError

_NoMethodError :: Prism' t String #

Extract a description of the missing method.

    _NoMethodError :: Prism' NoMethodError String
    _NoMethodError :: Prism' SomeException String

#### Instances

Instances details

AsNoMethodError NoMethodError # |
Instance details Defined in Control.Exception.Lens Methods __NoMethodError :: Prism' NoMethodError NoMethodError # _NoMethodError :: Prism' NoMethodError String #
AsNoMethodError SomeException # |
Instance details Defined in Control.Exception.Lens Methods __NoMethodError :: Prism' SomeException NoMethodError # _NoMethodError :: Prism' SomeException String #

pattern NoMethodError__ :: AsNoMethodError s => NoMethodError -> s #

pattern NoMethodError_ :: AsNoMethodError s => String -> s #

## Pattern Match Failure

class AsPatternMatchFail t where #

A pattern match failed.

Minimal complete definition

__PatternMatchFail

Methods

__PatternMatchFail :: Prism' t PatternMatchFail #

    __PatternMatchFail :: Prism' PatternMatchFail PatternMatchFail
    __PatternMatchFail :: Prism' SomeException    PatternMatchFail

_PatternMatchFail :: Prism' t String #

Information about the source location of the pattern.

    _PatternMatchFail :: Prism' PatternMatchFail String
    _PatternMatchFail :: Prism' SomeException    String

#### Instances

Instances details

AsPatternMatchFail PatternMatchFail # |
Instance details Defined in Control.Exception.Lens Methods __PatternMatchFail :: Prism' PatternMatchFail PatternMatchFail # _PatternMatchFail :: Prism' PatternMatchFail String #
AsPatternMatchFail SomeException # |
Instance details Defined in Control.Exception.Lens Methods __PatternMatchFail :: Prism' SomeException PatternMatchFail # _PatternMatchFail :: Prism' SomeException String #

pattern PatternMatchFail__ :: AsPatternMatchFail s => PatternMatchFail -> s #

pattern PatternMatchFail_ :: AsPatternMatchFail s => String -> s #

## Record

class AsRecConError t where #

An uninitialised record field was used.

Minimal complete definition

__RecConError

Methods

__RecConError :: Prism' t RecConError #

    __RecConError :: Prism' RecConError   RecConError
    __RecConError :: Prism' SomeException RecConError

_RecConError :: Prism' t String #

Information about the source location where the record was constructed.

    _RecConError :: Prism' RecConError   String
    _RecConError :: Prism' SomeException String

#### Instances

Instances details

AsRecConError RecConError # |
Instance details Defined in Control.Exception.Lens Methods __RecConError :: Prism' RecConError RecConError # _RecConError :: Prism' RecConError String #
AsRecConError SomeException # |
Instance details Defined in Control.Exception.Lens Methods __RecConError :: Prism' SomeException RecConError # _RecConError :: Prism' SomeException String #

class AsRecSelError t where #

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.

Minimal complete definition

__RecSelError

Methods

__RecSelError :: Prism' t RecSelError #

    __RecSelError :: Prism' RecSelError   RecSelError
    __RecSelError :: Prism' SomeException RecSelError

_RecSelError :: Prism' t String #

Information about the source location where the record selection occurred.

    _RecSelError :: Prism' RecSelError   String
    _RecSelError :: Prism' SomeException String

#### Instances

Instances details

AsRecSelError RecSelError # |
Instance details Defined in Control.Exception.Lens Methods __RecSelError :: Prism' RecSelError RecSelError # _RecSelError :: Prism' RecSelError String #
AsRecSelError SomeException # |
Instance details Defined in Control.Exception.Lens Methods __RecSelError :: Prism' SomeException RecSelError # _RecSelError :: Prism' SomeException String #

class AsRecUpdError t where #

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.

Minimal complete definition

__RecUpdError

Methods

__RecUpdError :: Prism' t RecUpdError #

    __RecUpdError :: Prism' RecUpdError   RecUpdError
    __RecUpdError :: Prism' SomeException RecUpdError

_RecUpdError :: Prism' t String #

Information about the source location where the record was updated.

    _RecUpdError :: Prism' RecUpdError   String
    _RecUpdError :: Prism' SomeException String

#### Instances

Instances details

AsRecUpdError RecUpdError # |
Instance details Defined in Control.Exception.Lens Methods __RecUpdError :: Prism' RecUpdError RecUpdError # _RecUpdError :: Prism' RecUpdError String #
AsRecUpdError SomeException # |
Instance details Defined in Control.Exception.Lens Methods __RecUpdError :: Prism' SomeException RecUpdError # _RecUpdError :: Prism' SomeException String #

pattern RecConError__ :: AsRecConError s => RecConError -> s #

pattern RecConError_ :: AsRecConError s => String -> s #

pattern RecSelError__ :: AsRecSelError s => RecSelError -> s #

pattern RecSelError_ :: AsRecSelError s => String -> s #

pattern RecUpdError__ :: AsRecUpdError s => RecUpdError -> s #

pattern RecUpdError_ :: AsRecUpdError s => String -> s #

## Error Call

class AsErrorCall t where #

This is thrown when the user calls `error`.

Minimal complete definition

__ErrorCall

Methods

__ErrorCall :: Prism' t ErrorCall #

    __ErrorCall :: Prism' ErrorCall     ErrorCall
    __ErrorCall :: Prism' SomeException ErrorCall

_ErrorCall :: Prism' t String #

Retrieve the argument given to `error`.

`ErrorCall` is isomorphic to a `String`.

    >>> catching _ErrorCall (error "touch down!") return
    "touch down!"

    _ErrorCall :: Prism' ErrorCall     String
    _ErrorCall :: Prism' SomeException String

#### Instances

Instances details

AsErrorCall ErrorCall # |
Instance details Defined in Control.Exception.Lens Methods __ErrorCall :: Prism' ErrorCall ErrorCall # _ErrorCall :: Prism' ErrorCall String #
AsErrorCall SomeException # |
Instance details Defined in Control.Exception.Lens Methods __ErrorCall :: Prism' SomeException ErrorCall # _ErrorCall :: Prism' SomeException String #

pattern ErrorCall__ :: AsErrorCall s => ErrorCall -> s #

pattern ErrorCall_ :: AsErrorCall s => String -> s #

## Allocation Limit Exceeded

class AsAllocationLimitExceeded t where #

This thread has exceeded its allocation limit.

Minimal complete definition

__AllocationLimitExceeded

Methods

__AllocationLimitExceeded :: Prism' t AllocationLimitExceeded #

    __AllocationLimitExceeded :: Prism' AllocationLimitExceeded AllocationLimitExceeded
    __AllocationLimitExceeded :: Prism' SomeException           AllocationLimitExceeded

_AllocationLimitExceeded :: Prism' t () #

There is no additional information carried in an `AllocationLimitExceeded` `Exception`.

    _AllocationLimitExceeded :: Prism' AllocationLimitExceeded ()
    _AllocationLimitExceeded :: Prism' SomeException           ()

#### Instances

Instances details

AsAllocationLimitExceeded SomeException # |
Instance details Defined in Control.Exception.Lens Methods __AllocationLimitExceeded :: Prism' SomeException AllocationLimitExceeded # _AllocationLimitExceeded :: Prism' SomeException () #
AsAllocationLimitExceeded AllocationLimitExceeded # |
Instance details Defined in Control.Exception.Lens Methods __AllocationLimitExceeded :: Prism' AllocationLimitExceeded AllocationLimitExceeded # _AllocationLimitExceeded :: Prism' AllocationLimitExceeded () #

pattern AllocationLimitExceeded__ :: AsAllocationLimitExceeded s => AllocationLimitExceeded -> s #

pattern AllocationLimitExceeded_ :: AsAllocationLimitExceeded s => s #

## Type Error

class AsTypeError t where #

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

Minimal complete definition

__TypeError

Methods

__TypeError :: Prism' t TypeError #

    __TypeError :: Prism' TypeError     TypeError
    __TypeError :: Prism' SomeException TypeError

_TypeError :: Prism' t String #

Details about the failed type check.

    _TypeError :: Prism' TypeError     String
    _TypeError :: Prism' SomeException String

#### Instances

Instances details

AsTypeError TypeError # |
Instance details Defined in Control.Exception.Lens Methods __TypeError :: Prism' TypeError TypeError # _TypeError :: Prism' TypeError String #
AsTypeError SomeException # |
Instance details Defined in Control.Exception.Lens Methods __TypeError :: Prism' SomeException TypeError # _TypeError :: Prism' SomeException String #

pattern TypeError__ :: AsTypeError s => TypeError -> s #

pattern TypeError_ :: AsTypeError s => String -> s #

## Compaction Failed

class AsCompactionFailed t where #

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

Minimal complete definition

__CompactionFailed

Methods

__CompactionFailed :: Prism' t CompactionFailed #

    __CompactionFailed :: Prism' CompactionFailed CompactionFailed
    __CompactionFailed :: Prism' SomeException    CompactionFailed

_CompactionFailed :: Prism' t String #

Information about why a compaction failed.

    _CompactionFailed :: Prism' CompactionFailed String
    _CompactionFailed :: Prism' SomeException    String

#### Instances

Instances details

AsCompactionFailed SomeException # |
Instance details Defined in Control.Exception.Lens Methods __CompactionFailed :: Prism' SomeException CompactionFailed # _CompactionFailed :: Prism' SomeException String #
AsCompactionFailed CompactionFailed # |
Instance details Defined in Control.Exception.Lens Methods __CompactionFailed :: Prism' CompactionFailed CompactionFailed # _CompactionFailed :: Prism' CompactionFailed String #

pattern CompactionFailed__ :: AsCompactionFailed s => CompactionFailed -> s #

pattern CompactionFailed_ :: AsCompactionFailed s => String -> s #

# Handling Exceptions

class AsHandlingException t where #

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

Minimal complete definition

__HandlingException

Methods

__HandlingException :: Prism' t HandlingException #

    __HandlingException :: Prism' HandlingException HandlingException
    __HandlingException :: Prism' SomeException     HandlingException

_HandlingException :: Prism' t () #

There is no information carried in a `HandlingException`.

    _HandlingException :: Prism' HandlingException ()
    _HandlingException :: Prism' SomeException     ()

#### Instances

Instances details

AsHandlingException SomeException # |
Instance details Defined in Control.Exception.Lens Methods __HandlingException :: Prism' SomeException HandlingException # _HandlingException :: Prism' SomeException () #
AsHandlingException HandlingException # |
Instance details Defined in Control.Exception.Lens Methods __HandlingException :: Prism' HandlingException HandlingException # _HandlingException :: Prism' HandlingException () #

pattern HandlingException__ :: AsHandlingException s => HandlingException -> s #

pattern HandlingException_ :: AsHandlingException s => s #