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


-- | Backported Control.Monad.Except module from mtl
--   
--   This package backports the <a>Control.Monad.Except</a> module from
--   <tt>mtl</tt> (if using <tt>mtl-2.2.0.1</tt> or earlier), which
--   reexports the <tt>ExceptT</tt> monad transformer and the
--   <tt>MonadError</tt> class.
--   
--   This package should only be used if there is a need to use the
--   <tt>Control.Monad.Except</tt> module specifically. If you just want
--   the <tt>mtl</tt> class instances for <tt>ExceptT</tt>, use
--   <tt>transformers-compat</tt> instead, since <tt>mtl-compat</tt> does
--   nothing but reexport the instances from that package.
--   
--   Note that unlike how <tt>mtl-2.2</tt> or later works, the
--   <a>Control.Monad.Except</a> module defined in this package exports all
--   of <tt>ExceptT</tt>'s monad class instances. Therefore, you may have
--   to declare <tt>import Control.Monad.Except ()</tt> at the top of your
--   file to get all of the <tt>ExceptT</tt> instances in scope.
@package mtl-compat
@version 0.2.1.3


-- | <ul>
--   <li><i>Computation type:</i> Computations which may fail or throw
--   exceptions.</li>
--   <li><i>Binding strategy:</i> Failure records information about the
--   cause/location of the failure. Failure values bypass the bound
--   function, other values are used as inputs to the bound function.</li>
--   <li><i>Useful for:</i> Building computations from sequences of
--   functions that may fail or using exception handling to structure error
--   handling.</li>
--   <li><i>Example type:</i> <tt><a>Either</a> String a</tt></li>
--   </ul>
--   
--   The Error monad (also called the Exception monad).
module Control.Monad.Except

-- | The strategy of combining computations that can throw exceptions by
--   bypassing bound functions from the point an exception is thrown to the
--   point that it is handled.
--   
--   Is parameterized over the type of error information and the monad type
--   constructor. It is common to use <tt><a>Either</a> String</tt> as the
--   monad type constructor for an error monad in which error descriptions
--   take the form of strings. In that case and many other common cases the
--   resulting monad is already defined as an instance of the
--   <a>MonadError</a> class. You can also define your own error type
--   and/or use a monad type constructor other than <tt><a>Either</a>
--   <tt>String</tt></tt> or <tt><a>Either</a> <tt>IOError</tt></tt>. In
--   these cases you will have to explicitly define instances of the
--   <a>Error</a> and/or <a>MonadError</a> classes.
class Monad m => MonadError e (m :: * -> *) | m -> e
throwError :: MonadError e m => e -> m a
catchError :: MonadError e m => m a -> (e -> m a) -> m a

-- | A monad transformer that adds exceptions to other monads.
--   
--   <tt>ExceptT</tt> constructs a monad parameterized over two things:
--   
--   <ul>
--   <li>e - The exception type.</li>
--   <li>m - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function yields a computation that produces the
--   given value, while <tt>&gt;&gt;=</tt> sequences two subcomputations,
--   exiting on the first exception.
newtype ExceptT e (m :: * -> *) a :: * -> (* -> *) -> * -> *
ExceptT :: m (Either e a) -> ExceptT e a
runExceptT :: ExceptT e a -> m (Either e a)

-- | The parameterizable exception monad.
--   
--   Computations are either exceptions or normal values.
--   
--   The <a>return</a> function returns a normal value, while
--   <tt>&gt;&gt;=</tt> exits on the first exception.
type Except e = ExceptT e Identity
runExceptT :: ExceptT e m a -> m (Either e a)

-- | Map the unwrapped computation using the given function.
--   
--   <ul>
--   <li><pre><a>runExceptT</a> (<a>mapExceptT</a> f m) = f
--   (<a>runExceptT</a> m)</pre></li>
--   </ul>
mapExceptT :: (m (Either e a) -> n (Either e' b)) -> ExceptT e m a -> ExceptT e' n b

-- | Transform any exceptions thrown by the computation using the given
--   function.
withExceptT :: Functor m => (e -> e') -> ExceptT e m a -> ExceptT e' m a

-- | Extractor for computations in the exception monad. (The inverse of
--   <a>except</a>).
runExcept :: Except e a -> Either e a

-- | Map the unwrapped computation using the given function.
--   
--   <ul>
--   <li><pre><a>runExcept</a> (<a>mapExcept</a> f m) = f (<a>runExcept</a>
--   m)</pre></li>
--   </ul>
mapExcept :: (Either e a -> Either e' b) -> Except e a -> Except e' b

-- | Transform any exceptions thrown by the computation using the given
--   function (a specialization of <a>withExceptT</a>).
withExcept :: (e -> e') -> Except e a -> Except e' a
