Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
This module presents the same interface as
Control.Exception.Annotated, but uses MonadUnliftIO
instead of
MonadCatch
or MonadThrow
.
Since: 0.1.2.0
Synopsis
- data AnnotatedException exception = AnnotatedException {
- annotations :: [Annotation]
- exception :: exception
- new :: e -> AnnotatedException e
- throwWithCallStack :: forall e m a. (MonadIO m, Exception e, HasCallStack) => e -> m a
- checkpoint :: forall m a. MonadUnliftIO m => Annotation -> m a -> m a
- checkpointMany :: forall m a. MonadUnliftIO m => [Annotation] -> m a -> m a
- checkpointCallStack :: (MonadCatch m, HasCallStack) => m a -> m a
- checkpointCallStackWith :: forall m a. (MonadUnliftIO m, HasCallStack) => [Annotation] -> m a -> m a
- catch :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
- catches :: forall m a. MonadUnliftIO m => m a -> [Handler m a] -> m a
- tryAnnotated :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> m (Either (AnnotatedException e) a)
- try :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
- check :: Exception e => AnnotatedException SomeException -> Maybe (AnnotatedException e)
- hide :: Exception e => AnnotatedException e -> AnnotatedException SomeException
- annotatedExceptionCallStack :: AnnotatedException exception -> Maybe CallStack
- addCallStackToException :: CallStack -> AnnotatedException exception -> AnnotatedException exception
- data Annotation where
- Annotation :: AnnC a => a -> Annotation
- newtype CallStackAnnotation = CallStackAnnotation {
- unCallStackAnnotation :: [(String, SrcLoc)]
- class (Typeable e, Show e) => Exception e where
- toException :: e -> SomeException
- fromException :: SomeException -> Maybe e
- displayException :: e -> String
- data SomeException = Exception e => SomeException e
- throw :: forall e m a. (MonadIO m, Exception e) => e -> m a
- data Handler (m :: Type -> Type) a = Exception e => Handler (e -> m a)
- class Monad m => MonadIO (m :: Type -> Type) where
- class MonadIO m => MonadUnliftIO (m :: Type -> Type) where
- withRunInIO :: ((forall a. m a -> IO a) -> IO b) -> m b
The Main Type
data AnnotatedException exception Source #
The AnnotatedException
type wraps an exception
with
a [
. This can provide a sort of a manual stack trace with
programmer provided data.Annotation
]
Since: 0.1.0.0
AnnotatedException | |
|
Instances
new :: e -> AnnotatedException e Source #
Attach an empty [
to an exception.Annotation
]
Since: 0.1.0.0
throwWithCallStack :: forall e m a. (MonadIO m, Exception e, HasCallStack) => e -> m a Source #
Like throwWithCallStack
, but uses MonadIO
instead of
MonadThrow
.
Since: 0.1.2.0
Annotating Exceptions
checkpoint :: forall m a. MonadUnliftIO m => Annotation -> m a -> m a Source #
Like checkpoint
, but uses MonadUnliftIO
instead of MonadCatch
.
Since: 0.1.2.0
checkpointMany :: forall m a. MonadUnliftIO m => [Annotation] -> m a -> m a Source #
Like checkpointMany
, but uses MonadUnliftIO
instead of
MonadCatch
.
Since: 0.1.2.0
checkpointCallStack :: (MonadCatch m, HasCallStack) => m a -> m a Source #
checkpointCallStackWith :: forall m a. (MonadUnliftIO m, HasCallStack) => [Annotation] -> m a -> m a Source #
Like checkpointCallStackWith
, but uses MonadUnliftIO
instead of
MonadCatch
.
Since: 0.1.2.0
Handling Exceptions
catch :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a Source #
Like catch
, but uses MonadUnliftIO
instead of MonadCatch
.
Since: 0.1.2.0
catches :: forall m a. MonadUnliftIO m => m a -> [Handler m a] -> m a Source #
Like catches
, bt uses MonadUnliftIO
instead of MonadCatch
.
Since: 0.1.2.0
tryAnnotated :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> m (Either (AnnotatedException e) a) Source #
Like tryAnnotated
but uses MonadUnliftIO
instead of MonadCatch
.
Since: 0.1.2.0
try :: forall e m a. (MonadUnliftIO m, Exception e) => m a -> m (Either e a) Source #
Like try
but uses MonadUnliftIO
instead of MonadCatch
.
Since: 0.1.2.0
Manipulating Annotated Exceptions
check :: Exception e => AnnotatedException SomeException -> Maybe (AnnotatedException e) Source #
Call fromException
on the underlying Exception
, attaching the
annotations to the result.
Since: 0.1.0.0
hide :: Exception e => AnnotatedException e -> AnnotatedException SomeException Source #
Call toException
on the underlying Exception
.
Since: 0.1.0.0
annotatedExceptionCallStack :: AnnotatedException exception -> Maybe CallStack Source #
Retrieves the CallStack
from an AnnotatedException
if one is present.
Since: 0.1.0.0
addCallStackToException :: CallStack -> AnnotatedException exception -> AnnotatedException exception Source #
Adds a CallStack
to the given AnnotatedException
. This function will
search through the existing annotations, and it will not add a second
CallStack
to the list.
Since: 0.1.0.0
Re-exports from Data.Annotation
data Annotation where Source #
An Annotation
is a wrapper around a value that includes a Typeable
constraint so we can later unpack it. It is essentially a 'Dynamic, but
we also include Show
and Eq
so it's more useful.
Since: 0.1.0.0
Annotation :: AnnC a => a -> Annotation |
Instances
Eq Annotation Source # | Since: 0.1.0.0 |
Defined in Data.Annotation (==) :: Annotation -> Annotation -> Bool # (/=) :: Annotation -> Annotation -> Bool # | |
Show Annotation Source # | Since: 0.1.0.0 |
Defined in Data.Annotation showsPrec :: Int -> Annotation -> ShowS # show :: Annotation -> String # showList :: [Annotation] -> ShowS # | |
IsString Annotation Source # | Since: 0.1.0.0 |
Defined in Data.Annotation fromString :: String -> Annotation # |
newtype CallStackAnnotation Source #
A wrapper type for putting a CallStack
into an Annotation
. We need
this because CallStack
does not have an Eq
instance.
Since: 0.1.0.0
Instances
Eq CallStackAnnotation Source # | |
Defined in Data.Annotation (==) :: CallStackAnnotation -> CallStackAnnotation -> Bool # (/=) :: CallStackAnnotation -> CallStackAnnotation -> Bool # | |
Show CallStackAnnotation Source # | |
Defined in Data.Annotation showsPrec :: Int -> CallStackAnnotation -> ShowS # show :: CallStackAnnotation -> String # showList :: [CallStackAnnotation] -> ShowS # |
Re-exports from Control.Exception.Safe
class (Typeable e, Show e) => Exception e where #
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
Nothing
toException :: e -> SomeException #
fromException :: SomeException -> Maybe e #
displayException :: e -> String #
Render this exception value in a human-friendly manner.
Default implementation:
.show
Since: base-4.8.0.0
Instances
data SomeException #
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
.
Exception e => SomeException e |
Instances
Show SomeException | Since: base-3.0 |
Defined in GHC.Exception.Type showsPrec :: Int -> SomeException -> ShowS # show :: SomeException -> String # showList :: [SomeException] -> ShowS # | |
Exception SomeException | Since: base-3.0 |
Defined in GHC.Exception.Type |
class Monad m => MonadIO (m :: Type -> Type) where #
Monads in which IO
computations may be embedded.
Any monad built by applying a sequence of monad transformers to the
IO
monad will be an instance of this class.
Instances should satisfy the following laws, which state that liftIO
is a transformer of monads:
Instances
MonadIO IO | Since: base-4.9.0.0 |
Defined in Control.Monad.IO.Class | |
MonadIO Q | |
Defined in Language.Haskell.TH.Syntax | |
MonadIO m => MonadIO (IdentityT m) | |
Defined in Control.Monad.Trans.Identity | |
(Error e, MonadIO m) => MonadIO (ErrorT e m) | |
Defined in Control.Monad.Trans.Error | |
MonadIO m => MonadIO (ReaderT r m) | |
Defined in Control.Monad.Trans.Reader |
class MonadIO m => MonadUnliftIO (m :: Type -> Type) where #
Monads which allow their actions to be run in IO
.
While MonadIO
allows an IO
action to be lifted into another
monad, this class captures the opposite concept: allowing you to
capture the monadic context. Note that, in order to meet the laws
given below, the intuition is that a monad must have no monadic
state, but may have monadic context. This essentially limits
MonadUnliftIO
to ReaderT
and IdentityT
transformers on top of
IO
.
Laws. For any value u
returned by askUnliftIO
, it must meet the
monad transformer laws as reformulated for MonadUnliftIO
:
unliftIO u . return = return
unliftIO u (m >>= f) = unliftIO u m >>= unliftIO u . f
Instances of MonadUnliftIO
must also satisfy the idempotency law:
askUnliftIO >>= \u -> (liftIO . unliftIO u) m = m
This law showcases two properties. First, askUnliftIO
doesn't change
the monadic context, and second, liftIO . unliftIO u
is equivalent to
id
IF called in the same monadic context as askUnliftIO
.
Since: unliftio-core-0.1.0.0
withRunInIO :: ((forall a. m a -> IO a) -> IO b) -> m b #
Convenience function for capturing the monadic context and running an IO
action with a runner function. The runner function is used to run a monadic
action m
in IO
.
Since: unliftio-core-0.1.0.0
Instances
MonadUnliftIO IO | |
Defined in Control.Monad.IO.Unlift | |
MonadUnliftIO m => MonadUnliftIO (IdentityT m) | |
Defined in Control.Monad.IO.Unlift | |
MonadUnliftIO m => MonadUnliftIO (ReaderT r m) | |
Defined in Control.Monad.IO.Unlift |