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


-- | An Except monad transformer with
--   
--   Extra pieces for working with Except
@package transformers-except
@version 0.1.4

module Control.Monad.Trans.Except.Exit

-- | orDieWithCode with an exit code of 1 in case of an error
orDie :: (e -> Text) -> ExceptT e IO a -> IO a

-- | An idiom for failing hard on EitherT errors.
--   
--   <ul>
--   <li>This really dies*. There is no other way to say it.</li>
--   </ul>
--   
--   The reason it lives with command line parser tooling, is that it is
--   the only valid place to actually exit like this. Be appropriately
--   wary.
orDieWithCode :: Int -> (e -> Text) -> ExceptT e IO a -> IO a


-- | This monad transformer extends <a>Control.Monad.Trans.Except</a> with
--   a few more conveniences.
module Control.Monad.Trans.Except.Extra

-- | Constructor for computations in the ExceptT monad. (The inverse of
--   <a>runExceptT</a>).
newExceptT :: m (Either x a) -> ExceptT x m a

-- | The inverse of <a>ExceptT</a>.
runExceptT :: ExceptT e m a -> m (Either e a)

-- | Map over both arguments at the same time.
--   
--   Specialised version of <tt>bimap</tt> for <a>ExceptT</a>.
exceptT :: Monad m => (x -> m b) -> (a -> m b) -> ExceptT x m a -> m b

-- | Constructor for left computations.
left :: Monad m => x -> ExceptT x m a

-- | Constructor for right computations.
right :: Monad m => a -> ExceptT x m 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

-- | Hoist an <a>Either</a> into an <a>ExceptT</a> m.
hoistEither :: Monad m => Either x a -> ExceptT x m a

-- | Map the unwrapped computation using the given function.
bimapExceptT :: Functor m => (x -> y) -> (a -> b) -> ExceptT x m a -> ExceptT y m b

-- | Map the <a>Left</a> unwrapped computation using the given function.
firstExceptT :: Functor m => (x -> y) -> ExceptT x m a -> ExceptT y m a

-- | Map the <a>Right</a> unwrapped computation using the given function.
secondExceptT :: Functor m => (a -> b) -> ExceptT x m a -> ExceptT x m b

-- | Hoist <a>Maybe</a> a into <a>Right</a> a.
hoistMaybe :: Monad m => x -> Maybe a -> ExceptT x m a

-- | Hoist <a>Except</a> m into an <a>Except</a> n.
hoistExceptT :: (forall b. m b -> n b) -> ExceptT x m a -> ExceptT x n a

-- | Try an <a>IO</a> action inside an <a>ExceptT</a>. If the <a>IO</a>
--   action throws an <a>IOException</a>, catch it and wrap it with the
--   provided handler to convert it to the error type of the <a>ExceptT</a>
--   transformer. Exceptions other than <a>IOException</a> will escape the
--   ExceptT transformer.
--   
--   Note: <tt>IOError</tt> is a type synonym for <a>IOException</a>.
handleIOExceptT :: MonadIO m => (IOException -> x) -> IO a -> ExceptT x m a

-- | Try any monad action and catch the specified exception, wrapping it to
--   convert it to the error type of the <a>ExceptT</a> transformer.
--   Exceptions other that the specified exception type will escape the
--   <a>ExceptT</a> transformer.
--   
--   <ul>
--   <li>Warning*: This function should be used with caution! In
--   particular, it is bad practice to catch <a>SomeException</a> because
--   that includes asynchronous exceptions like stack/heap overflow, thread
--   killed and user interrupt. Trying to handle <tt>StackOverflow</tt>,
--   <tt>HeapOverflow</tt> and <tt>ThreadKilled</tt> exceptions could cause
--   your program to crash or behave in unexpected ways.</li>
--   </ul>
handleExceptT :: (MonadCatch m, Exception e) => (e -> x) -> m a -> ExceptT x m a

-- | Try a monad action and catch any of the exceptions caught by the
--   provided handlers. The handler for each exception type needs to wrap
--   it to convert it to the error type of the <a>ExceptT</a> transformer.
--   Exceptions not explicitly handled by the provided handlers will escape
--   the <a>ExceptT</a> transformer.
handlesExceptT :: (Foldable f, MonadCatch m) => f (Handler m x) -> m a -> ExceptT x m a

-- | Handle an error. Equivalent to <tt>handleError</tt> in mtl package.
handleLeftT :: Monad m => (e -> ExceptT e m a) -> ExceptT e m a -> ExceptT e m a

-- | Flipped <a>handleIOExceptT</a>.
catchIOExceptT :: MonadIO m => IO a -> (IOException -> x) -> ExceptT x m a

-- | Flipped <a>handleExceptT</a>.
catchExceptT :: (MonadCatch m, Exception e) => m a -> (e -> x) -> ExceptT x m a

-- | Flipped <a>handlesExceptT</a>.
catchesExceptT :: (Foldable f, MonadCatch m) => m a -> f (Handler m x) -> ExceptT x m a

-- | Flipped <a>handleLeftT</a>.
catchLeftT :: Monad m => ExceptT e m a -> (e -> ExceptT e m a) -> ExceptT e m a

-- | Acquire a resource in <a>ExceptT</a> and then perform an action with
--   it, cleaning up afterwards regardless of <a>left</a>.
--   
--   This function does not clean up in the event of an exception. Prefer
--   <a>bracketExceptionT</a> in any impure setting.
bracketExceptT :: Monad m => ExceptT e m a -> (a -> ExceptT e m b) -> (a -> ExceptT e m c) -> ExceptT e m c

-- | Acquire a resource in ExceptT and then perform an action with it,
--   cleaning up afterwards regardless of <a>left</a> or exception.
--   
--   Like <a>bracketExceptT</a>, but the cleanup is called even when the
--   bracketed function throws an exception. Exceptions in the bracketed
--   function are caught to allow the cleanup to run and then rethrown.
bracketExceptionT :: MonadMask m => ExceptT e m a -> (a -> ExceptT e m c) -> (a -> ExceptT e m b) -> ExceptT e m b

-- | Convert an Either to a Maybe and execute the supplied handler in the
--   Left case.
hushM :: Monad m => Either e a -> (e -> m ()) -> m (Maybe a)

-- | Handle the Left constructor in returned Either.
onLeft :: forall e x m a. Monad m => (e -> ExceptT x m a) -> ExceptT x m (Either e a) -> ExceptT x m a

-- | Handle the Nothing constructor in returned Maybe.
onNothing :: forall x m a. Monad m => ExceptT x m a -> ExceptT x m (Maybe a) -> ExceptT x m a