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


-- | Type classes and monads for unchecked extensible exceptions.
--   
--   This package provides type classes, a monad and a monad transformer
--   that support unchecked extensible exceptions as well as asynchronous
--   exceptions. It is compatible with the transformers package.
@package exception-transformers
@version 0.4.0.2


module Control.Monad.Exception

-- | 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 :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: Exception e => 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 :: *
class (Monad m) => MonadException m where act `finally` sequel = do { a <- act `onException` sequel; _ <- sequel; return a }

-- | Throw an exception.
throw :: (MonadException m, Exception e) => e -> m a

-- | Catch an exception.
catch :: (MonadException m, Exception e) => m a -> (e -> m a) -> m a

-- | Run a computation and always perform a second, final computation even
--   if an exception is raised. If a short-circuiting monad transformer
--   such as ErrorT or MaybeT is used to transform a MonadException monad,
--   then the implementation of <tt>finally</tt> for the transformed monad
--   must guarantee that the final action is also always performed when any
--   short-circuiting occurs.
finally :: MonadException m => m a -> m b -> m a

-- | If an exception is raised by the computation, then perform a final
--   action and re-raise the exception.
onException :: MonadException m => m a -> m b -> m a
class (MonadIO m, MonadException m) => MonadAsyncException m

-- | Executes a computation with asynchronous exceptions <i>masked</i>. The
--   argument passed to <a>mask</a> is a function that takes as its
--   argument another function, which can be used to restore the prevailing
--   masking state within the context of the masked computation.
mask :: MonadAsyncException m => ((forall a. m a -> m a) -> m b) -> m b

-- | When you want to acquire a resource, do some work with it, and then
--   release the resource, it is a good idea to use <a>bracket</a>, because
--   <a>bracket</a> will install the necessary exception handler to release
--   the resource in the event that an exception is raised during the
--   computation. If an exception is raised, then <a>bracket</a> will
--   re-raise the exception (after performing the release).
bracket :: MonadAsyncException m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | A variant of <a>bracket</a> where the return value from the first
--   computation is not required.
bracket_ :: MonadAsyncException m => m a -> m b -> m c -> m c
newtype ExceptionT m a
ExceptionT :: m (Either SomeException a) -> ExceptionT m a
[runExceptionT] :: ExceptionT m a -> m (Either SomeException a)
mapExceptionT :: (m (Either SomeException a) -> n (Either SomeException b)) -> ExceptionT m a -> ExceptionT n b

-- | Lift the result of running a computation in a monad transformed by
--   <a>ExceptionT</a> into another monad that supports exceptions.
liftException :: MonadException m => Either SomeException a -> m a
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Exception.ExceptionT
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Exception.ExceptionT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Exception.ExceptionT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Control.Monad.Exception.ExceptionT m)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Applicative (Control.Monad.Exception.ExceptionT m)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Alternative (Control.Monad.Exception.ExceptionT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Exception.ExceptionT m)
instance GHC.Base.Monad m => Control.Monad.Exception.MonadException (Control.Monad.Exception.ExceptionT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Exception.ExceptionT m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Exception.ExceptionT m)
instance Control.Monad.Exception.MonadException GHC.Types.IO
instance Control.Monad.Exception.MonadAsyncException GHC.Types.IO
instance Control.Monad.Exception.MonadException GHC.Conc.Sync.STM
instance (Control.Monad.Exception.MonadException m, Control.Monad.Trans.Error.Error e) => Control.Monad.Exception.MonadException (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.Except.ExceptT e' m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadException m) => Control.Monad.Exception.MonadException (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadException m) => Control.Monad.Exception.MonadException (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Exception.MonadException m => Control.Monad.Exception.MonadException (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadException m) => Control.Monad.Exception.MonadException (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadException m) => Control.Monad.Exception.MonadException (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Exception.MonadAsyncException m, Control.Monad.Trans.Error.Error e) => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Except.ExceptT e' m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadAsyncException m) => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadAsyncException m) => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Exception.MonadAsyncException m => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadAsyncException m) => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Exception.MonadAsyncException m) => Control.Monad.Exception.MonadAsyncException (Control.Monad.Trans.Writer.Strict.WriterT w m)