libghc-exceptions-doc 0.8.3-3 / usr / share / doc / libghc-exceptions-doc / html / exceptions.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Extensible optionally-pure exceptions
--   
--   Extensible optionally-pure exceptions
@package exceptions
@version 0.8.3


-- | This module supports monads that can throw extensible exceptions. The
--   exceptions are the very same from <a>Control.Exception</a>, and the
--   operations offered very similar, but here they are not limited to
--   <a>IO</a>.
--   
--   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 <a>ErrorT</a> and <tt>MonadError</tt>, but
--   based on features of <a>Control.Exception</a>. In particular, it
--   handles the complex case of asynchronous exceptions by including
--   <a>mask</a> in the typeclass. Note that the extensible exceptions
--   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:
--   
--   <pre>
--   throwM e &gt;&gt; x = throwM e
--   </pre>
--   
--   In other words, throwing an exception short-circuits the rest of the
--   monadic computation.
class Monad m => MonadThrow m

-- | Throw an exception. Note that this throws when this action is run in
--   the monad <tt>m</tt>, not when it is applied. It is a generalization
--   of <a>Control.Exception</a>'s <a>throwIO</a>.
--   
--   Should satisfy the law:
--   
--   <pre>
--   throwM e &gt;&gt; f = throwM e
--   </pre>
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 <a>throwM</a>.
--   
--   Instances should obey the following law:
--   
--   <pre>
--   catch (throwM e) f = f e
--   </pre>
--   
--   Note that the ability to catch an exception does <i>not</i> 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 <tt>catch</tt>
--   <i>cannot</i> be used by those monads to properly implement a function
--   such as <tt>finally</tt>. For more information, see <a>MonadMask</a>.
class MonadThrow m => MonadCatch m

-- | Provide a handler for exceptions thrown during execution of the first
--   action. Note that type of the type of the argument to the handler will
--   constrain which exceptions are caught. See <a>Control.Exception</a>'s
--   <a>catch</a>.
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 <tt>ErrorT e
--   IO</tt> which provide for multiple failure modes, are invalid
--   instances of this class.
--   
--   Note that this package <i>does</i> provide a <tt>MonadMask</tt>
--   instance for <tt>CatchT</tt>. This instance is <i>only</i> valid if
--   the base monad provides no ability to provide multiple exit. For
--   example, <tt>IO</tt> or <tt>Either</tt> would be invalid base monads,
--   but <tt>Reader</tt> or <tt>State</tt> would be acceptable.
--   
--   Instances should ensure that, in the following code:
--   
--   <pre>
--   f `finally` g
--   </pre>
--   
--   The action <tt>g</tt> is called regardless of what occurs within
--   <tt>f</tt>, including async exceptions.
class MonadCatch m => MonadMask m

-- | Runs an action with asynchronous exceptions disabled. The action is
--   provided a method for restoring the async. environment to what it was
--   at the <a>mask</a> call. See <a>Control.Exception</a>'s <a>mask</a>.
mask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>mask</a>, but the masked computation is not interruptible (see
--   <a>Control.Exception</a>'s <a>uninterruptibleMask</a>. WARNING: Only
--   use if you need to mask exceptions around an interruptible operation
--   AND you can guarantee the interruptible operation will only block for
--   a short period of time. Otherwise you render the program/thread
--   unresponsive and/or unkillable.
uninterruptibleMask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>mask</a>, but does not pass a <tt>restore</tt> action to the
--   argument.
mask_ :: MonadMask m => m a -> m a

-- | Like <a>uninterruptibleMask</a>, but does not pass a <tt>restore</tt>
--   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 <a>IOError</a> (eqv. <tt>IOException</tt>) exceptions. Still
--   somewhat too general, but better than using <a>catchAll</a>. See
--   <a>catchIf</a> for an easy way of catching specific <a>IOError</a>s
--   based on the predicates in <a>System.IO.Error</a>.
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 <a>IOError</a> values in
--   <a>System.IO.Error</a>.
catchIf :: (MonadCatch m, Exception e) => (e -> Bool) -> m a -> (e -> m a) -> m a

-- | Generalized version of <a>Handler</a>
data Handler m a
Handler :: (e -> m a) -> Handler m a

-- | Catches different sorts of exceptions. See <a>Control.Exception</a>'s
--   <a>catches</a>
catches :: (Foldable f, MonadCatch m) => m a -> f (Handler m a) -> m a

-- | Flipped <a>catch</a>. See <a>Control.Exception</a>'s <a>handle</a>.
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a

-- | Flipped <a>catchAll</a>
handleAll :: MonadCatch m => (SomeException -> m a) -> m a -> m a

-- | Flipped <a>catchIOError</a>
handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a

-- | Flipped <a>catchJust</a>. See <a>Control.Exception</a>'s
--   <a>handleJust</a>.
handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a

-- | Flipped <a>catchIf</a>
handleIf :: (MonadCatch m, Exception e) => (e -> Bool) -> (e -> m a) -> m a -> m a

-- | Similar to <a>catch</a>, but returns an <a>Either</a> result. See
--   <a>Control.Exception</a>'s <a>try</a>.
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)

-- | A variant of <a>try</a> that takes an exception predicate to select
--   which exceptions are caught. See <a>Control.Exception</a>'s
--   <a>tryJust</a>
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
--   <a>bracket</a>.
--   
--   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 <a>bracket</a> 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 <a>bracket</a>, 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 <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving (Show, Typeable)
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--       deriving Typeable
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--       deriving Typeable
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- 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
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable * e, Show e) => Exception e
toException :: e -> SomeException
fromException :: SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: e -> String

-- | The <tt>SomeException</tt> type is the root of the exception type
--   hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
--   scenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException :: *
[SomeException] :: SomeException
instance Control.Monad.Catch.MonadThrow []
instance Control.Monad.Catch.MonadThrow GHC.Base.Maybe
instance Control.Monad.Catch.MonadThrow Language.Haskell.TH.Syntax.Q
instance Control.Monad.Catch.MonadThrow GHC.Types.IO
instance Control.Monad.Catch.MonadCatch GHC.Types.IO
instance Control.Monad.Catch.MonadMask GHC.Types.IO
instance Control.Monad.Catch.MonadThrow GHC.Conc.Sync.STM
instance Control.Monad.Catch.MonadCatch GHC.Conc.Sync.STM
instance e ~ GHC.Exception.SomeException => Control.Monad.Catch.MonadThrow (Data.Either.Either e)
instance e ~ GHC.Exception.SomeException => Control.Monad.Catch.MonadCatch (Data.Either.Either e)
instance e ~ GHC.Exception.SomeException => Control.Monad.Catch.MonadMask (Data.Either.Either e)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Reader.ReaderT r m)
instance (Control.Monad.Catch.MonadThrow m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Catch.MonadCatch m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Catch.MonadMask m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Catch.MonadThrow m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Control.Monad.Catch.MonadCatch m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Control.Monad.Catch.MonadMask m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Control.Monad.Catch.MonadThrow m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (Control.Monad.Catch.MonadCatch m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (Control.Monad.Catch.MonadMask m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadMask (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (Control.Monad.Catch.MonadThrow m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (Control.Monad.Catch.MonadCatch m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (Control.Monad.Catch.MonadMask m, GHC.Base.Monoid w) => Control.Monad.Catch.MonadMask (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Maybe.MaybeT m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Catch.MonadThrow m) => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Error.ErrorT e m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Catch.MonadCatch m) => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Cont.ContT r m)
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Catch.Handler m)


-- | 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 <a>throwM</a>.
--   
--   Do not mix <a>CatchT</a> with <a>IO</a>. Choose one or the other for
--   the bottom of your transformer stack!
module Control.Monad.Catch.Pure

-- | Add <a>Exception</a> handling abilities to a <a>Monad</a>.
--   
--   This should <i>never</i> be used in combination with <a>IO</a>. Think
--   of <a>CatchT</a> as an alternative base monad for use with mocking
--   code that solely throws exceptions via <a>throwM</a>.
--   
--   Note: that <a>IO</a> monad has these abilities already, so stacking
--   <a>CatchT</a> on top of it does not add any value and can possibly be
--   confusing:
--   
--   <pre>
--   &gt;&gt;&gt; (error "Hello!" :: IO ()) `catch` (\(e :: ErrorCall) -&gt; liftIO $ print e)
--   Hello!
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runCatchT $ (error "Hello!" :: CatchT IO ()) `catch` (\(e :: ErrorCall) -&gt; liftIO $ print e)
--   *** Exception: Hello!
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runCatchT $ (throwM (ErrorCall "Hello!") :: CatchT IO ()) `catch` (\(e :: ErrorCall) -&gt; liftIO $ print e)
--   Hello!
--   </pre>
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.
--   
--   <pre>
--   <a>runCatchT</a> (<a>mapCatchT</a> f m) = f (<a>runCatchT</a> m)
--   </pre>
mapCatchT :: (m (Either SomeException a) -> n (Either SomeException b)) -> CatchT m a -> CatchT n b
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Catch.Pure.CatchT m)
instance Data.Foldable.Foldable m => Data.Foldable.Foldable (Control.Monad.Catch.Pure.CatchT m)
instance (GHC.Base.Monad m, Data.Traversable.Traversable m) => Data.Traversable.Traversable (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Catch.Pure.CatchT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => Control.Monad.Catch.MonadThrow (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => Control.Monad.Catch.MonadCatch (Control.Monad.Catch.Pure.CatchT m)
instance GHC.Base.Monad m => Control.Monad.Catch.MonadMask (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.Reader.Class.MonadReader e m => Control.Monad.Reader.Class.MonadReader e (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Catch.Pure.CatchT m)
instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Catch.Pure.CatchT m)