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


-- | An Either monad transformer
--   
--   Drop in alternative to ExceptT. Uses a pattern synonym to maintain
--   compatibility with the old EitherT types but is actually ExceptT under
--   the covers.
@package transformers-either
@version 0.1.0


-- | This monad transformer extends <a>Control.Monad.Trans.Except</a> with
--   a more familar <a>Either</a> naming.
module Control.Monad.Trans.Either

-- | Type alias for <a>ExceptT</a>
type EitherT = ExceptT

-- | Constructor for computations in the either monad. (The inverse of
--   <a>runEitherT</a>).
newEitherT :: m (Either x a) -> EitherT x m a

-- | Extractor for computations in the either monad. (The inverse of
--   <a>newEitherT</a>).
runEitherT :: EitherT x m a -> m (Either x a)

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

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

-- | Constructor for right computations.
right :: Monad m => a -> EitherT x m a
mapEitherT :: (m (Either x a) -> n (Either y b)) -> EitherT x m a -> EitherT y n b

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

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

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

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

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

-- | Hoist <a>Either</a> m into an <a>Either</a> n.
hoistEitherT :: (forall b. m b -> n b) -> EitherT x m a -> EitherT x n a

-- | Try an <a>IO</a> action inside an <a>EitherT</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>EitherT</a>
--   transformer. Exceptions other than <a>IOException</a> will escape the
--   EitherT transformer.
--   
--   Note: <tt>IOError</tt> is a type synonym for <a>IOException</a>.
handleIOEitherT :: MonadIO m => (IOException -> x) -> IO a -> EitherT x m a

-- | Try any monad action and catch the specified exception, wrapping it to
--   convert it to the error type of the <a>EitherT</a> transformer.
--   Exceptions other that the specified exception type will escape the
--   <a>EitherT</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>
handleEitherT :: (MonadCatch m, Exception e) => (e -> x) -> m a -> EitherT 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>EitherT</a> transformer.
--   Exceptions not explicitly handled by the provided handlers will escape
--   the <a>EitherT</a> transformer.
handlesEitherT :: (Foldable f, MonadCatch m) => f (Handler m x) -> m a -> EitherT x m a

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

-- | Flipped <a>handleIOEitherT</a>.
catchIOEitherT :: MonadIO m => IO a -> (IOException -> x) -> EitherT x m a

-- | Flipped <a>handleEitherT</a>.
catchEitherT :: (MonadCatch m, Exception e) => m a -> (e -> x) -> EitherT x m a

-- | Flipped <a>handlesEitherT</a>.
catchesEitherT :: (Foldable f, MonadCatch m) => m a -> f (Handler m x) -> EitherT x m a

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

-- | Acquire a resource in <a>EitherT</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.
bracketEitherT :: Monad m => EitherT e m a -> (a -> EitherT e m b) -> (a -> EitherT e m c) -> EitherT e m c

-- | Acquire a resource in EitherT and then perform an action with it,
--   cleaning up afterwards regardless of <a>left</a> or exception.
--   
--   Like <a>bracketEitherT</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 => EitherT e m a -> (a -> EitherT e m c) -> (a -> EitherT e m b) -> EitherT e m b

module Control.Monad.Trans.Either.Exit

-- | orDieWithCode with an exit code of 1 in case of an error
orDie :: (e -> Text) -> EitherT 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) -> EitherT e IO a -> IO a