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


-- | Combinators for working with sums
--   
--   Combinators for working with sums.
@package either
@version 5.0.2


-- | 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

-- | Maybe produce a <a>Left</a>, otherwise produce a <a>Right</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToLeft "default" (Just 12)
--   Left 12
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeToLeft "default" Nothing
--   Right "default"
--   </pre>
maybeToLeft :: b -> Maybe a -> Either a b

-- | Maybe produce a <a>Right</a>, otherwise produce a <a>Left</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToRight "default" (Just 12)
--   Right 12
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeToRight "default" Nothing
--   Left "default"
--   </pre>
maybeToRight :: b -> Maybe a -> Either b a

-- | 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
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; swapEither (Left "error")
--   Right "error"
--   </pre>
swapEither :: Either e a -> Either a e


-- | 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)
vap :: Semigroup m => Either m (a -> b) -> Either m a -> Either m b
ealt :: Validation e a -> Validation e a -> Validation e a
vapm :: Monoid m => Either m (a -> b) -> Either m a -> Either m b
apm :: Monoid m => Validation m (a -> b) -> Validation m a -> Validation m b
instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Data.Either.Validation.Validation e a)
instance (GHC.Classes.Ord e, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.Either.Validation.Validation e a)
instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Either.Validation.Validation e a)
instance GHC.Base.Functor (Data.Either.Validation.Validation e)
instance GHC.Base.Semigroup e => Data.Functor.Bind.Class.Apply (Data.Either.Validation.Validation e)
instance GHC.Base.Semigroup e => GHC.Base.Applicative (Data.Either.Validation.Validation e)
instance GHC.Base.Semigroup e => Data.Functor.Alt.Alt (Data.Either.Validation.Validation e)
instance (GHC.Base.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 GHC.Base.Semigroup e => GHC.Base.Semigroup (Data.Either.Validation.Validation e a)
instance GHC.Base.Monoid e => GHC.Base.Monoid (Data.Either.Validation.Validation e a)
