-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Extensible optionally-pure exceptions
--
@package exceptions
@version 0.7
-- | This module supports monads that can throw extensible exceptions. The
-- exceptions are the very same from Control.Exception, and the
-- operations offered very similar, but here they are not limited to
-- IO.
--
-- This code is in the style of both transformers and mtl, and is
-- compatible with them, though doesn't mimic the module structure or
-- offer the complete range of features in those packages.
--
-- This is very similar to ErrorT and MonadError, but
-- based on features of Control.Exception. In particular, it
-- handles the complex case of asynchronous exceptions by including
-- mask in the typeclass. Note that the extensible extensions
-- feature relies on the RankNTypes language extension.
module Control.Monad.Catch
-- | A class for monads in which exceptions may be thrown.
--
-- Instances should obey the following law:
--
--
-- throwM e >> x = throwM e
--
--
-- In other words, throwing an exception short-circuits the rest of the
-- monadic computation.
class Monad m => MonadThrow m
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | A class for monads which allow exceptions to be caught, in particular
-- exceptions which were thrown by throwM.
--
-- Instances should obey the following law:
--
--
-- catch (throwM e) f = f e
--
--
-- Note that the ability to catch an exception does not guarantee
-- that we can deal with all possible exit points from a computation.
-- Some monads, such as continuation-based stacks, allow for more than
-- just a success/failure strategy, and therefore catch
-- cannot be used by those monads to properly implement a function
-- such as finally. For more information, see MonadMask.
class MonadThrow m => MonadCatch m
catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
-- | A class for monads which provide for the ability to account for all
-- possible exit points from a computation, and to mask asynchronous
-- exceptions. Continuation-based monads, and stacks such as ErrorT e
-- IO which provide for multiple failure modes, are invalid
-- instances of this class.
--
-- Note that this package does provide a MonadMask
-- instance for CatchT. This instance is only valid if
-- the base monad provides no ability to provide multiple exit. For
-- example, IO or Either would be invalid base monads,
-- but Reader or State would be acceptable.
--
-- Instances should ensure that, in the following code:
--
--
-- f `finally` g
--
--
-- The action g is called regardless of what occurs within
-- f, including async exceptions.
class MonadCatch m => MonadMask m
mask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b
uninterruptibleMask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b
-- | Like mask, but does not pass a restore action to the
-- argument.
mask_ :: MonadMask m => m a -> m a
-- | Like uninterruptibleMask, but does not pass a restore
-- action to the argument.
uninterruptibleMask_ :: MonadMask m => m a -> m a
-- | Catches all exceptions, and somewhat defeats the purpose of the
-- extensible exception system. Use sparingly.
catchAll :: MonadCatch m => m a -> (SomeException -> m a) -> m a
-- | Catch all IOError (eqv. IOException) exceptions. Still
-- somewhat too general, but better than using catchAll. See
-- catchIf for an easy way of catching specific IOErrors
-- based on the predicates in System.IO.Error.
catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a
-- | A more generalized way of determining which exceptions to catch at run
-- time.
catchJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
-- | Catch exceptions only if they pass some predicate. Often useful with
-- the predicates for testing IOError values in
-- System.IO.Error.
catchIf :: (MonadCatch m, Exception e) => (e -> Bool) -> m a -> (e -> m a) -> m a
-- | Generalized version of Handler
data Handler m a
Handler :: (e -> m a) -> Handler m a
-- | Catches different sorts of exceptions. See Control.Exception's
-- catches
catches :: (Foldable f, MonadCatch m) => m a -> f (Handler m a) -> m a
-- | Flipped catch. See Control.Exception's handle.
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
-- | Flipped catchAll
handleAll :: MonadCatch m => (SomeException -> m a) -> m a -> m a
-- | Flipped catchIOError
handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a
-- | Flipped catchJust. See Control.Exception's
-- handleJust.
handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
-- | Flipped catchIf
handleIf :: (MonadCatch m, Exception e) => (e -> Bool) -> (e -> m a) -> m a -> m a
-- | Similar to catch, but returns an Either result. See
-- Control.Exception's try.
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)
-- | A variant of try that takes an exception predicate to select
-- which exceptions are caught. See Control.Exception's
-- tryJust
tryJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
-- | Run an action only if an exception is thrown in the main action. The
-- exception is not caught, simply rethrown.
onException :: MonadCatch m => m a -> m b -> m a
-- | Generalized abstracted pattern of safe resource acquisition and
-- release in the face of exceptions. The first action "acquires" some
-- value, which is "released" by the second action at the end. The third
-- action "uses" the value and its result is the result of the
-- bracket.
--
-- If an exception occurs during the use, the release still happens
-- before the exception is rethrown.
bracket :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Version of bracket without any value being passed to the second
-- and third actions.
bracket_ :: MonadMask m => m a -> m b -> m c -> m c
-- | Perform an action with a finalizer action that is run, even if an
-- exception occurs.
finally :: MonadMask m => m a -> m b -> m a
-- | Like bracket, but only performs the final action if there was
-- an exception raised by the in-between computation.
bracketOnError :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | 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, Typeable)
--
-- 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
-- deriving Typeable
--
-- 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
-- deriving Typeable
--
-- 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 (Typeable, 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
--
class (Typeable * e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
-- | 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.
data SomeException :: *
SomeException :: e -> SomeException
instance Monad m => Functor (Handler m)
instance MonadThrow m => MonadThrow (ContT r m)
instance MonadCatch m => MonadCatch (ExceptT e m)
instance MonadThrow m => MonadThrow (ExceptT e m)
instance (Error e, MonadCatch m) => MonadCatch (ErrorT e m)
instance (Error e, MonadThrow m) => MonadThrow (ErrorT e m)
instance MonadCatch m => MonadCatch (MaybeT m)
instance MonadThrow m => MonadThrow (MaybeT m)
instance MonadCatch m => MonadCatch (ListT m)
instance MonadThrow m => MonadThrow (ListT m)
instance (MonadMask m, Monoid w) => MonadMask (RWST r w s m)
instance (MonadCatch m, Monoid w) => MonadCatch (RWST r w s m)
instance (MonadThrow m, Monoid w) => MonadThrow (RWST r w s m)
instance (MonadMask m, Monoid w) => MonadMask (RWST r w s m)
instance (MonadCatch m, Monoid w) => MonadCatch (RWST r w s m)
instance (MonadThrow m, Monoid w) => MonadThrow (RWST r w s m)
instance (MonadMask m, Monoid w) => MonadMask (WriterT w m)
instance (MonadCatch m, Monoid w) => MonadCatch (WriterT w m)
instance (MonadThrow m, Monoid w) => MonadThrow (WriterT w m)
instance (MonadMask m, Monoid w) => MonadMask (WriterT w m)
instance (MonadCatch m, Monoid w) => MonadCatch (WriterT w m)
instance (MonadThrow m, Monoid w) => MonadThrow (WriterT w m)
instance MonadMask m => MonadMask (ReaderT r m)
instance MonadCatch m => MonadCatch (ReaderT r m)
instance MonadThrow m => MonadThrow (ReaderT r m)
instance MonadMask m => MonadMask (StateT s m)
instance MonadCatch m => MonadCatch (StateT s m)
instance MonadThrow m => MonadThrow (StateT s m)
instance MonadMask m => MonadMask (StateT s m)
instance MonadCatch m => MonadCatch (StateT s m)
instance MonadThrow m => MonadThrow (StateT s m)
instance MonadMask m => MonadMask (IdentityT m)
instance MonadCatch m => MonadCatch (IdentityT m)
instance MonadThrow m => MonadThrow (IdentityT m)
instance MonadCatch STM
instance MonadThrow STM
instance MonadMask IO
instance MonadCatch IO
instance MonadThrow IO
instance e ~ SomeException => MonadThrow (Either e)
instance MonadThrow Maybe
instance MonadThrow []
-- | This module supplies a 'pure' monad transformer that can be used for
-- mock-testing code that throws exceptions, so long as those exceptions
-- are always thrown with throwM.
--
-- Do not mix CatchT with IO. Choose one or the other for
-- the bottom of your transformer stack!
module Control.Monad.Catch.Pure
-- | Add Exception handling abilities to a Monad.
--
-- This should never be used in combination with IO. Think
-- of CatchT as an alternative base monad for use with mocking
-- code that solely throws exceptions via throwM.
--
-- Note: that IO monad has these abilities already, so stacking
-- CatchT on top of it does not add any value and can possibly be
-- confusing:
--
--
-- >>> (error "Hello!" :: IO ()) `catch` (\(e :: ErrorCall) -> liftIO $ print e)
-- Hello!
--
--
--
-- >>> runCatchT $ (error "Hello!" :: CatchT IO ()) `catch` (\(e :: ErrorCall) -> liftIO $ print e)
-- *** Exception: Hello!
--
--
--
-- >>> runCatchT $ (throwM (ErrorCall "Hello!") :: CatchT IO ()) `catch` (\(e :: ErrorCall) -> liftIO $ print e)
-- Hello!
--
newtype CatchT m a
CatchT :: m (Either SomeException a) -> CatchT m a
runCatchT :: CatchT m a -> m (Either SomeException a)
type Catch = CatchT Identity
runCatch :: Catch a -> Either SomeException a
-- | Map the unwrapped computation using the given function.
--
--
-- runCatchT (mapCatchT f m) = f (runCatchT m)
--
mapCatchT :: (m (Either SomeException a) -> n (Either SomeException b)) -> CatchT m a -> CatchT n b
instance MonadRWS r w s m => MonadRWS r w s (CatchT m)
instance MonadWriter w m => MonadWriter w (CatchT m)
instance MonadReader e m => MonadReader e (CatchT m)
instance MonadState s m => MonadState s (CatchT m)
instance Monad m => MonadMask (CatchT m)
instance Monad m => MonadCatch (CatchT m)
instance Monad m => MonadThrow (CatchT m)
instance MonadIO m => MonadIO (CatchT m)
instance MonadTrans CatchT
instance Monad m => MonadPlus (CatchT m)
instance Monad m => Alternative (CatchT m)
instance (Monad m, Traversable m) => Traversable (CatchT m)
instance Foldable m => Foldable (CatchT m)
instance MonadFix m => MonadFix (CatchT m)
instance Monad m => Monad (CatchT m)
instance Monad m => Applicative (CatchT m)
instance Monad m => Functor (CatchT m)