Control.Exception.Optic

Common optics

non' :: Prism' a () -> Iso' (Maybe a) a

Generate an isomorphism between Maybe (a | isnt p a) and a.

non' p generalizes non (p # ()) to take any unit Prism

unlifted :: MonadUnliftIO m => Grate (m a) (m b) (IO a) (IO b)

Unlift an action into an IO context.

liftIO ≡ coview unlifted

>>> let catchA = catch @ArithException
>>> zipsWith unlifted (flip catchA . const) (throwIO Overflow) (print "caught")
"caught" 

exmapped :: Exception e1 => Exception e2 => Setter s s e1 e2

Map one exception into another as proposed in the paper "A semantics for imprecise exceptions".

>>> handles (only Overflow) (\_ -> return "caught") $ assert False (return "uncaught") & (exmapped ..~ \ (AssertionFailed _) -> Overflow)
"caught"

exmapped :: Exception e => Setter s s SomeException e

exception :: Exception e => Prism' SomeException e

Focus on whether a given exception has occurred.

pattern Exception :: forall a. Exception a => a -> SomeException

Derived operators

throws :: MonadIO m => Exception e => AReview e b -> b -> m r

Throw an exception described by an optic.

throws o e `seq` x  ≡ throws o e

throws_ :: MonadIO m => Exception e => AReview e () -> m r

Variant of throws for error constructors with no arguments.

throwsTo :: MonadIO m => Exception e => ThreadId -> AReview e b -> b -> m ()

Raise an Exception specified by an optic in the target thread.

throwsTo thread o ≡ throwTo thread . review o

tries :: MonadUnliftIO m => Exception ex => AOption e ex e -> m a -> m (Either e a)

Test for synchronous exceptions that match a given optic.

In the style of 'safe-exceptions' this function rethrows async exceptions synchronously in order to preserve async behavior,

tries :: MonadUnliftIO m => AOption e SomeException e -> m a -> m (Either e a)
tries exception :: MonadUnliftIO m => Exception e => m a -> m (Either e a)

tries_ :: MonadUnliftIO m => Exception ex => AOption e ex e -> m a -> m (Maybe a)

A variant of tries that returns synchronous exceptions.

catches :: MonadUnliftIO m => Exception ex => AOption e ex e -> m a -> (e -> m a) -> m a

Catch synchronous exceptions that match a given optic.

Rethrows async exceptions synchronously in order to preserve async behavior.

catches :: MonadUnliftIO m => AOption e SomeException e -> m a -> (e -> m a) -> m a
catches exception :: MonadUnliftIO m => Exception e => m a -> (e -> m a) -> m a

>>> catches (only Overflow) (throwIO Overflow) (\_ -> return "caught")
"caught"

catches_ :: MonadUnliftIO m => Exception ex => AOption e ex e -> m a -> m a -> m a

Catch synchronous exceptions that match a given optic, discarding the match.

>>> catches_ (only Overflow) (throwIO Overflow) (return "caught")
"caught"

handles :: MonadUnliftIO m => Exception ex => AOption e ex e -> (e -> m a) -> m a -> m a

Flipped variant of catches.

>>> handles (only Overflow) (\_ -> return "caught") $ throwIO Overflow
"caught"

handles_ :: MonadUnliftIO m => Exception ex => AOption e ex e -> m a -> m a -> m a

Flipped variant of catches_.

>>> handles_ (only Overflow) (return "caught") $ throwIO Overflow
"caught"

ioException :: Prism' SomeException IOException

Exceptions that occur in the IO Monad.

An IOException records a more specific error type, a descriptive string and possibly the handle that was used when the error was flagged.

IO Error Fields

ioeLocation :: Lens' IOException String

Where the error happened.

ioeDescription :: Lens' IOException String

Error type specific information.

ioeHandle :: Lens' IOException (Maybe Handle)

The handle used by the action flagging this error.

ioeFileName :: Lens' IOException (Maybe FilePath)

fileName the error is related to.

ioeErrno :: Lens' IOException (Maybe CInt)

errno leading to this error, if any.

ioeErrorType :: Lens' IOException IOErrorType

IO Error Types

alreadyExists :: Prism' IOErrorType ()

TODO: Document

noSuchThing :: Prism' IOErrorType ()

TODO: Document

resourceBusy :: Prism' IOErrorType ()

TODO: Document

resourceExhausted :: Prism' IOErrorType ()

TODO: Document

eof :: Prism' IOErrorType ()

TODO: Document

illegalOperation :: Prism' IOErrorType ()

TODO: Document

permissionDenied :: Prism' IOErrorType ()

TODO: Document

userError :: Prism' IOErrorType ()

TODO: Document

unsatisfiedConstraints :: Prism' IOErrorType ()

TODO: Document

systemError :: Prism' IOErrorType ()

TODO: Document

protocolError :: Prism' IOErrorType ()

TODO: Document

otherError :: Prism' IOErrorType ()

TODO: Document

invalidArgument :: Prism' IOErrorType ()

TODO: Document

inappropriateType :: Prism' IOErrorType ()

TODO: Document

hardwareFault :: Prism' IOErrorType ()

TODO: Document

unsupportedOperation :: Prism' IOErrorType ()

TODO: Document

Async Exceptions

sync :: Exception e => Prism' e e

Focus on whether an exception is synchronous.

async :: Exception e => Prism' e e

Focus on whether an exception is asynchronous.

asyncException :: Exception e => Prism' SomeException e

Focus on whether a given asynchronous exception has occurred.

pattern AsyncException :: forall a. Exception a => a -> SomeException

timeExpired :: Prism' IOErrorType ()

TODO: Document

resourceVanished :: Prism' IOErrorType ()

TODO: Document

interrupted :: Prism' IOErrorType ()

TODO: Document

stackOverflow :: Prism' AsyncException ()

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.

heapOverflow :: Prism' AsyncException ()

The program's heap usage has exceeded its limit.

See Exception for more information.

threadKilled :: Prism' AsyncException ()

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

userInterrupt :: Prism' AsyncException ()

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

Arithmetic exceptions

overflow :: Prism' ArithException ()

Detect arithmetic overflow.

underflow :: Prism' ArithException ()

Detect arithmetic underflow.

lossOfPrecision :: Prism' ArithException ()

Detect arithmetic loss of precision.

divideByZero :: Prism' ArithException ()

Detect division by zero.

denormal :: Prism' ArithException ()

Detect whether a FLOP was performed on a subnormal number.

ratioZeroDenominator :: Prism' ArithException ()

Detect zero denominators.

Array Exceptions

indexOutOfBounds :: Prism' ArrayException String

Detect attempts to index an array outside its declared bounds.

undefinedElement :: Prism' ArrayException String

Detect attempts to evaluate an element of an array that has not been initialized.

Miscellaneous Exceptions

illegal :: Profunctor p => t -> Optic' p t ()

assertionFailed :: Prism' AssertionFailed String

nonTermination :: Prism' NonTermination ()

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.

nestedAtomically :: Prism' NestedAtomically ()

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

blockedIndefinitelyOnMVar :: Prism' BlockedIndefinitelyOnMVar ()

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

blockedIndefinitelyOnSTM :: Prism' BlockedIndefinitelyOnSTM ()

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.

deadlock :: Prism' Deadlock ()

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

noMethodError :: Prism' NoMethodError String

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

patternMatchFail :: Prism' PatternMatchFail String

A pattern match failed.

recConError :: Prism' RecConError String

An uninitialised record field was used.

recSelError :: Prism' RecSelError String

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.

recUpdError :: Prism' RecUpdError String

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.

errorCall :: Prism' ErrorCall String

Thrown when the user calls error.

allocationLimitExceeded :: Prism' AllocationLimitExceeded ()

This thread has exceeded its allocation limit.