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


-- | An either monad transformer
--   
--   An either monad transformer
@package either
@version 4.5


-- | Monoidal <a>Validation</a> sibling to <a>Either</a>.
module Data.Either.Validation

-- | <a>Validation</a> is <a>Either</a> with a Left that is a <a>Monoid</a>
data Validation e a
Failure :: e -> Validation e a
Success :: a -> Validation e a
_Success :: Prism (Validation c a) (Validation c b) a b
_Failure :: Prism (Validation a c) (Validation b c) a b
eitherToValidation :: Either e a -> Validation e a
validationToEither :: Validation e a -> Either e a

-- | <a>Validation</a> is isomorphic to <a>Either</a>
_Validation :: Iso (Validation e a) (Validation g b) (Either e a) (Either g b)
instance (GHC.Show.Show a, GHC.Show.Show e) => GHC.Show.Show (Data.Either.Validation.Validation e a)
instance (GHC.Classes.Ord a, GHC.Classes.Ord e) => GHC.Classes.Ord (Data.Either.Validation.Validation e a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq e) => GHC.Classes.Eq (Data.Either.Validation.Validation e a)
instance GHC.Base.Functor (Data.Either.Validation.Validation e)
instance Data.Semigroup.Semigroup e => GHC.Base.Applicative (Data.Either.Validation.Validation e)
instance Data.Functor.Alt.Alt (Data.Either.Validation.Validation e)
instance (Data.Semigroup.Semigroup e, GHC.Base.Monoid e) => GHC.Base.Alternative (Data.Either.Validation.Validation e)
instance Data.Foldable.Foldable (Data.Either.Validation.Validation e)
instance Data.Traversable.Traversable (Data.Either.Validation.Validation e)
instance Data.Bifunctor.Bifunctor Data.Either.Validation.Validation
instance Data.Bifoldable.Bifoldable Data.Either.Validation.Validation
instance Data.Bitraversable.Bitraversable Data.Either.Validation.Validation
instance Data.Semigroup.Semigroup e => Data.Semigroup.Semigroup (Data.Either.Validation.Validation e a)
instance GHC.Base.Monoid e => GHC.Base.Monoid (Data.Either.Validation.Validation e a)


-- | Functions for probing and unwrapping values inside of <a>Either</a>.
--   
--   Most of these combinators are provided for pedagogical purposes and
--   exist in more general forms in other libraries. To that end
--   alternative definitions are supplied below.
module Data.Either.Combinators

-- | The <a>isLeft</a> function returns <a>True</a> iff its argument is of
--   the form <tt><a>Left</a> _</tt>.
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>isLeft</a> ≡ has _Left
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isLeft (Left 12)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isLeft (Right 12)
--   False
--   </pre>
isLeft :: Either a b -> Bool

-- | The <a>isRight</a> function returns <a>True</a> iff its argument is of
--   the form <tt><a>Right</a> _</tt>.
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>isRight</a> ≡ has _Right
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isRight (Left 12)
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isRight (Right 12)
--   True
--   </pre>
isRight :: Either a b -> Bool

-- | Extract the left value or a default.
--   
--   <pre>
--   <a>fromLeft</a> b ≡ <a>either</a> <a>id</a> (<a>const</a> b)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft "hello" (Right 42)
--   "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft "hello" (Left "world")
--   "world"
--   </pre>
fromLeft :: a -> Either a b -> a

-- | Extract the right value or a default.
--   
--   <pre>
--   <a>fromRight</a> b ≡ <a>either</a> (<a>const</a> b) <a>id</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromRight "hello" (Right "world")
--   "world"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromRight "hello" (Left 42)
--   "hello"
--   </pre>
fromRight :: b -> Either a b -> b

-- | Extracts the element out of a <a>Left</a> and throws an error if its
--   argument take the form <tt><a>Right</a> _</tt>.
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>fromLeft'</a> x ≡ x^?!_Left
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft' (Left 12)
--   12
--   </pre>
fromLeft' :: Either a b -> a

-- | Extracts the element out of a <a>Right</a> and throws an error if its
--   argument take the form <tt><a>Left</a> _</tt>.
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>fromRight'</a> x ≡ x^?!_Right
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromRight' (Right 12)
--   12
--   </pre>
fromRight' :: Either a b -> b

-- | The <a>mapBoth</a> function takes two functions and applies the first
--   if iff the value takes the form <tt><a>Left</a> _</tt> and the second
--   if the value takes the form <tt><a>Right</a> _</tt>.
--   
--   Using <tt>Data.Bifunctor</tt>:
--   
--   <pre>
--   <a>mapBoth</a> = bimap
--   </pre>
--   
--   Using <tt>Control.Arrow</tt>:
--   
--   <pre>
--   <a>mapBoth</a> = (<a>+++</a>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapBoth (*2) (*3) (Left 4)
--   Left 8
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapBoth (*2) (*3) (Right 4)
--   Right 12
--   </pre>
mapBoth :: (a -> c) -> (b -> d) -> Either a b -> Either c d

-- | The <a>mapLeft</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Left</a> _</tt>.
--   
--   Using <tt>Data.Bifunctor</tt>:
--   
--   <pre>
--   <a>mapLeft</a> = first
--   </pre>
--   
--   Using <tt>Control.Arrow</tt>:
--   
--   <pre>
--   <a>mapLeft</a> = (<a>left</a>)
--   </pre>
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>mapLeft</a> = over _Left
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapLeft (*2) (Left 4)
--   Left 8
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapLeft (*2) (Right "hello")
--   Right "hello"
--   </pre>
mapLeft :: (a -> c) -> Either a b -> Either c b

-- | The <a>mapRight</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Right</a> _</tt>.
--   
--   Using <tt>Data.Bifunctor</tt>:
--   
--   <pre>
--   <a>mapRight</a> = second
--   </pre>
--   
--   Using <tt>Control.Arrow</tt>:
--   
--   <pre>
--   <a>mapRight</a> = (<a>right</a>)
--   </pre>
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>mapRight</a> = over _Right
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapRight (*2) (Left "hello")
--   Left "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapRight (*2) (Right 4)
--   Right 8
--   </pre>
mapRight :: (b -> c) -> Either a b -> Either a c

-- | The <a>whenLeft</a> function takes an <a>Either</a> value and a
--   function which returns a monad. The monad is only executed when the
--   given argument takes the form <tt><a>Left</a> _</tt>, otherwise it
--   does nothing.
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>whenLeft</a> ≡ forOf_ _Left
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenLeft (Left 12) print
--   12
--   </pre>
whenLeft :: Applicative m => Either a b -> (a -> m ()) -> m ()

-- | The <a>whenRight</a> function takes an <a>Either</a> value and a
--   function which returns a monad. The monad is only executed when the
--   given argument takes the form <tt><a>Right</a> _</tt>, otherwise it
--   does nothing.
--   
--   Using <tt>Data.Foldable</tt>:
--   
--   <pre>
--   <a>whenRight</a> ≡ <tt>forM_</tt>
--   </pre>
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>whenRight</a> ≡ forOf_ _Right
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenRight (Right 12) print
--   12
--   </pre>
whenRight :: Applicative m => Either a b -> (b -> m ()) -> m ()

-- | A synonym of <a>whenRight</a>.
unlessLeft :: Applicative m => Either a b -> (b -> m ()) -> m ()

-- | A synonym of <a>whenLeft</a>.
unlessRight :: Applicative m => Either a b -> (a -> m ()) -> m ()

-- | Maybe get the <a>Left</a> side of an <a>Either</a>.
--   
--   <pre>
--   <a>leftToMaybe</a> ≡ <a>either</a> <a>Just</a> (<a>const</a> <a>Nothing</a>)
--   </pre>
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>leftToMaybe</a> ≡ preview _Left
--   <a>leftToMaybe</a> x ≡ x^?_Left
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; leftToMaybe (Left 12)
--   Just 12
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; leftToMaybe (Right 12)
--   Nothing
--   </pre>
leftToMaybe :: Either a b -> Maybe a

-- | Maybe get the <a>Right</a> side of an <a>Either</a>.
--   
--   <pre>
--   <a>rightToMaybe</a> ≡ <a>either</a> (<a>const</a> <a>Nothing</a>) <a>Just</a>
--   </pre>
--   
--   Using <tt>Control.Lens</tt>:
--   
--   <pre>
--   <a>rightToMaybe</a> ≡ preview _Right
--   <a>rightToMaybe</a> x ≡ x^?_Right
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rightToMaybe (Left 12)
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rightToMaybe (Right 12)
--   Just 12
--   </pre>
rightToMaybe :: Either a b -> Maybe b

-- | Generalize <tt>Either e</tt> as <tt>MonadError e m</tt>.
--   
--   If the argument has form <tt>Left e</tt>, an error is produced in the
--   monad via <a>throwError</a>. Otherwise, the <tt>Right a</tt> part is
--   forwarded.
eitherToError :: (MonadError e m) => Either e a -> m a

-- | Swap the <a>Left</a> and <a>Right</a> sides of an <a>Either</a>.
--   
--   <pre>
--   &gt;&gt;&gt; swapEither (Right 3)
--   Left 3
--   
--   &gt;&gt;&gt; swapEither (Left "error")
--   Right "error"
--   </pre>
swapEither :: Either e a -> Either a e


-- | This module provides a minimalist <a>Either</a> monad transformer.

-- | <i>Deprecated: Use <a>Control.Monad.Trans.Except</a> from transformers
--   or transformers-compat instead.</i>
module Control.Monad.Trans.Either

-- | <a>EitherT</a> is a version of <a>ErrorT</a> that does not require a
--   spurious <a>Error</a> instance for the <a>Left</a> case.
--   
--   <a>Either</a> is a perfectly usable <a>Monad</a> without such a
--   constraint. <tt>ErrorT</tt> is not the generalization of the current
--   <a>Either</a> monad, it is something else.
--   
--   This is necessary for both theoretical and practical reasons. For
--   instance an apomorphism is the generalized anamorphism for this Monad,
--   but it cannot be written with <tt>ErrorT</tt>.
--   
--   In addition to the combinators here, the <tt>errors</tt> package
--   provides a large number of combinators for working with this type.
newtype EitherT e m a
EitherT :: m (Either e a) -> EitherT e m a
[runEitherT] :: EitherT e m a -> m (Either e a)

-- | Given a pair of actions, one to perform in case of failure, and one to
--   perform in case of success, run an <a>EitherT</a> and get back a
--   monadic result.
eitherT :: Monad m => (a -> m c) -> (b -> m c) -> EitherT a m b -> m c

-- | Map over both failure and success.
bimapEitherT :: Functor m => (e -> f) -> (a -> b) -> EitherT e m a -> EitherT f m b

-- | Map the unwrapped computation using the given function.
--   
--   <pre>
--   <a>runEitherT</a> (<a>mapEitherT</a> f m) = f (<a>runEitherT</a> m)
--   </pre>
mapEitherT :: (m (Either e a) -> n (Either e' b)) -> EitherT e m a -> EitherT e' n b

-- | Lift an <a>Either</a> into an <a>EitherT</a>
hoistEither :: Monad m => Either e a -> EitherT e m a

-- | Acquire a resource in <a>EitherT</a> and then perform an action with
--   it, cleaning up afterwards regardless of error. Like <a>bracket</a>,
--   but acting only in <a>EitherT</a>.
bracketEitherT :: Monad m => EitherT e m a -> (a -> EitherT e m b) -> (a -> EitherT e m c) -> EitherT e m c

-- | Version of <a>bracketEitherT</a> which discards the result from the
--   initial action.
bracketEitherT_ :: Monad m => EitherT e m a -> EitherT e m b -> EitherT e m c -> EitherT e m c

-- | Analogous to <a>Left</a>. Equivalent to <a>throwError</a>.
left :: Monad m => e -> EitherT e m a

-- | Analogous to <a>Right</a>. Equivalent to <a>return</a>.
right :: Monad m => a -> EitherT e m a

-- | Monad transformer version of <a>swapEither</a>.
swapEitherT :: (Functor m) => EitherT e m a -> EitherT a m e

-- | Map over failure
firstEitherT :: Functor m => (e -> f) -> EitherT e m a -> EitherT f m a
instance GHC.Show.Show (m (Data.Either.Either e a)) => GHC.Show.Show (Control.Monad.Trans.Either.EitherT e m a)
instance GHC.Read.Read (m (Data.Either.Either e a)) => GHC.Read.Read (Control.Monad.Trans.Either.EitherT e m a)
instance GHC.Classes.Eq (m (Data.Either.Either e a)) => GHC.Classes.Eq (Control.Monad.Trans.Either.EitherT e m a)
instance GHC.Classes.Ord (m (Data.Either.Either e a)) => GHC.Classes.Ord (Control.Monad.Trans.Either.EitherT e m a)
instance Control.Monad.Morph.MFunctor (Control.Monad.Trans.Either.EitherT e)
instance Control.Monad.Morph.MMonad (Control.Monad.Trans.Either.EitherT e)
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => Data.Functor.Bind.Class.Apply (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Trans.Either.EitherT e m)
instance (GHC.Base.Monad m, GHC.Base.Monoid e) => GHC.Base.Alternative (Control.Monad.Trans.Either.EitherT e m)
instance (GHC.Base.Monad m, GHC.Base.Monoid e) => GHC.Base.MonadPlus (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => Data.Semigroup.Semigroup (Control.Monad.Trans.Either.EitherT e m a)
instance (GHC.Base.Monad m, Data.Semigroup.Semigroup e) => Data.Functor.Alt.Alt (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => Data.Functor.Bind.Class.Bind (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.Either.EitherT e m)
instance GHC.Base.Monad m => Control.Monad.Error.Class.MonadError e (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Trans.Either.EitherT e)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Writer.Class.MonadWriter s m => Control.Monad.Writer.Class.MonadWriter s (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Random.Class.MonadRandom m => Control.Monad.Random.Class.MonadRandom (Control.Monad.Trans.Either.EitherT e m)
instance Data.Foldable.Foldable m => Data.Foldable.Foldable (Control.Monad.Trans.Either.EitherT e m)
instance (GHC.Base.Functor f, Control.Monad.Free.Class.MonadFree f m) => Control.Monad.Free.Class.MonadFree f (Control.Monad.Trans.Either.EitherT e m)
instance (GHC.Base.Monad f, Data.Traversable.Traversable f) => Data.Traversable.Traversable (Control.Monad.Trans.Either.EitherT e f)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Control.Monad.Trans.Either.EitherT e m)
instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Either.EitherT e)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Either.EitherT e m)