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


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


-- | 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 (Eq e, Eq a) => Eq (Validation e a)
instance (Ord e, Ord a) => Ord (Validation e a)
instance (Show e, Show a) => Show (Validation e a)
instance Monoid e => Monoid (Validation e a)
instance Semigroup e => Semigroup (Validation e a)
instance Bitraversable Validation
instance Bifoldable Validation
instance Bifunctor Validation
instance Traversable (Validation e)
instance Foldable (Validation e)
instance (Semigroup e, Monoid e) => Alternative (Validation e)
instance Alt (Validation e)
instance Semigroup e => Applicative (Validation e)
instance Functor (Validation e)


-- | 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> ≡ <a>either</a> <a>id</a>
--   </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> 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


-- | This module provides a minimalist <a>Either</a> monad transformer.
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

-- | 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
instance MonadBaseControl b m => MonadBaseControl b (EitherT e m)
instance MonadTransControl (EitherT e)
instance MonadBase b m => MonadBase b (EitherT e m)
instance (Monad f, Traversable f) => Traversable (EitherT e f)
instance (Functor f, MonadFree f m) => MonadFree f (EitherT e m)
instance Foldable m => Foldable (EitherT e m)
instance MonadRandom m => MonadRandom (EitherT e m)
instance MonadWriter s m => MonadWriter s (EitherT e m)
instance MonadState s m => MonadState s (EitherT e m)
instance MonadReader r m => MonadReader r (EitherT e m)
instance MonadCont m => MonadCont (EitherT e m)
instance MonadIO m => MonadIO (EitherT e m)
instance MonadTrans (EitherT e)
instance MonadFix m => MonadFix (EitherT e m)
instance MonadCatch m => MonadCatch (EitherT e m)
instance MonadThrow m => MonadThrow (EitherT e m)
instance Monad m => MonadError e (EitherT e m)
instance Monad m => Monad (EitherT e m)
instance Monad m => Bind (EitherT e m)
instance (Monad m, Semigroup e) => Alt (EitherT e m)
instance Monad m => Semigroup (EitherT e m a)
instance (Monad m, Monoid e) => MonadPlus (EitherT e m)
instance (Monad m, Monoid e) => Alternative (EitherT e m)
instance Monad m => Applicative (EitherT e m)
instance Monad m => Apply (EitherT e m)
instance Monad m => Functor (EitherT e m)
instance Ord (m (Either e a)) => Ord (EitherT e m a)
instance Eq (m (Either e a)) => Eq (EitherT e m a)
instance Read (m (Either e a)) => Read (EitherT e m a)
instance Show (m (Either e a)) => Show (EitherT e m a)