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


-- | A data-type like Either but with an accumulating Applicative
--   
--   
--   A data-type like Either but with differing properties and type-class
--   instances.
--   
--   Library support is provided for this different representation, include
--   <a>lens</a>-related functions for converting between each and
--   abstracting over their similarities.
--   
--   <ul>
--   <li><a>Validation</a></li>
--   </ul>
--   
--   The <a>Validation</a> data type is isomorphic to <a>Either</a>, but
--   has an instance of <a>Applicative</a> that accumulates on the error
--   side. That is to say, if two (or more) errors are encountered, they
--   are appended using a <a>Semigroup</a> operation.
--   
--   As a consequence of this <a>Applicative</a> instance, there is no
--   corresponding <a>Bind</a> or <a>Monad</a> instance. <a>Validation</a>
--   is an example of, "An applicative functor that is not a monad."
@package validation
@version 1


-- | A data type similar to <tt>Data.Either</tt> that accumulates failures.
module Data.Validation

-- | An <tt>Validation</tt> is either a value of the type <tt>err</tt> or
--   <tt>a</tt>, similar to <a>Either</a>. However, the <a>Applicative</a>
--   instance for <tt>Validation</tt> <i>accumulates</i> errors using a
--   <a>Semigroup</a> on <tt>err</tt>. In contrast, the
--   <tt>Applicative</tt> for <tt>Either</tt> returns only the first error.
--   
--   A consequence of this is that <tt>Validation</tt> has no <a>Bind</a>
--   or <a>Monad</a> instance. This is because such an instance would
--   violate the law that a Monad's <a>ap</a> must equal the
--   <tt>Applicative</tt>'s <a>&lt;*&gt;</a>
--   
--   An example of typical usage can be found <a>here</a>.
data Validation err a
Failure :: err -> Validation err a
Success :: a -> Validation err a

-- | <a>validate</a>s the <tt>a</tt> with the given predicate, returning
--   <tt>e</tt> if the predicate does not hold.
--   
--   This can be thought of as having the less general type:
--   
--   <pre>
--   validate :: e -&gt; (a -&gt; Bool) -&gt; a -&gt; Validation e a
--   </pre>
validate :: Validate v => e -> (a -> Bool) -> a -> v e a

-- | <a>validationNel</a> is <a>liftError</a> specialised to
--   <a>NonEmpty</a> lists, since they are a common semigroup to use.
validationNel :: Either e a -> Validation (NonEmpty e) a

-- | Converts from <a>Either</a> to <a>Validation</a>.
fromEither :: Either e a -> Validation e a

-- | <a>liftError</a> is useful for converting an <a>Either</a> to an
--   <a>Validation</a> when the <tt>Left</tt> of the <a>Either</a> needs to
--   be lifted into a <a>Semigroup</a>.
liftError :: (b -> e) -> Either b a -> Validation e a

-- | <a>validation</a> is the catamorphism for <tt>Validation</tt>.
validation :: (e -> c) -> (a -> c) -> Validation e a -> c

-- | Converts from <a>Validation</a> to <a>Either</a>.
toEither :: Validation e a -> Either e a

-- | <tt>v <a>orElse</a> a</tt> returns <tt>a</tt> when <tt>v</tt> is
--   Failure, and the <tt>a</tt> in <tt>Success a</tt>.
--   
--   This can be thought of as having the less general type:
--   
--   <pre>
--   orElse :: Validation e a -&gt; a -&gt; a
--   </pre>
orElse :: Validate v => v e a -> a -> a

-- | Return the <tt>a</tt> or run the given function over the <tt>e</tt>.
--   
--   This can be thought of as having the less general type:
--   
--   <pre>
--   valueOr :: (e -&gt; a) -&gt; Validation e a -&gt; a
--   </pre>
valueOr :: Validate v => (e -> a) -> v e a -> a

-- | <a>ensure</a> leaves the validation unchanged when the predicate
--   holds, or fails with <tt>e</tt> otherwise.
--   
--   This can be thought of as having the less general type:
--   
--   <pre>
--   ensure :: e -&gt; (a -&gt; Bool) -&gt; Validation e a -&gt; Validation e a
--   </pre>
ensure :: Validate v => e -> (a -> Bool) -> v e a -> v e a

-- | <a>codiagonal</a> gets the value out of either side.
codiagonal :: Validation a a -> a

-- | Run a function on anything with a Validate instance (usually Either)
--   as if it were a function on Validation
--   
--   This can be thought of as having the type
--   
--   <pre>
--   (Either e a -&gt; Either e' a') -&gt; Validation e a -&gt; Validation e' a'
--   </pre>
validationed :: Validate v => (v e a -> v e' a') -> Validation e a -> Validation e' a'

-- | <tt>bindValidation</tt> binds through an Validation, which is useful
--   for composing Validations sequentially. Note that despite having a
--   bind function of the correct type, Validation is not a monad. The
--   reason is, this bind does not accumulate errors, so it does not agree
--   with the Applicative instance.
--   
--   There is nothing wrong with using this function, it just does not make
--   a valid <tt>Monad</tt> instance.
bindValidation :: Validation e a -> (a -> Validation e b) -> Validation e b

-- | This prism generalises <a>_Left</a>. It targets the failure case of
--   either <a>Either</a> or <a>Validation</a>.
_Failure :: Validate f => Prism (f e1 a) (f e2 a) e1 e2

-- | This prism generalises <a>_Right</a>. It targets the success case of
--   either <a>Either</a> or <a>Validation</a>.
_Success :: Validate f => Prism (f e a) (f e b) a b

-- | The <tt>Validate</tt> class carries around witnesses that the type
--   <tt>f</tt> is isomorphic to Validation, and hence isomorphic to
--   Either.
class Validate f
_Validation :: Validate f => Iso (f e a) (f g b) (Validation e a) (Validation g b)
_Either :: Validate f => Iso (f e a) (f g b) (Either e a) (Either g b)

-- | <a>revalidate</a> converts between any two instances of
--   <a>Validate</a>.
revalidate :: (Validate f, Validate g) => Iso (f e1 s) (f e2 t) (g e1 s) (g e2 t)
instance GHC.Generics.Generic (Data.Validation.Validation err a)
instance (Data.Data.Data err, Data.Data.Data a) => Data.Data.Data (Data.Validation.Validation err a)
instance (GHC.Show.Show err, GHC.Show.Show a) => GHC.Show.Show (Data.Validation.Validation err a)
instance (GHC.Classes.Ord err, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.Validation.Validation err a)
instance (GHC.Classes.Eq err, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Validation.Validation err a)
instance Data.Validation.Validate Data.Validation.Validation
instance Data.Validation.Validate Data.Either.Either
instance GHC.Base.Functor (Data.Validation.Validation err)
instance GHC.Base.Semigroup err => Data.Functor.Bind.Class.Apply (Data.Validation.Validation err)
instance GHC.Base.Semigroup err => GHC.Base.Applicative (Data.Validation.Validation err)
instance Data.Functor.Alt.Alt (Data.Validation.Validation err)
instance Data.Foldable.Foldable (Data.Validation.Validation err)
instance Data.Traversable.Traversable (Data.Validation.Validation err)
instance Data.Bifunctor.Bifunctor Data.Validation.Validation
instance Data.Bifoldable.Bifoldable Data.Validation.Validation
instance Data.Bitraversable.Bitraversable Data.Validation.Validation
instance GHC.Base.Semigroup e => GHC.Base.Semigroup (Data.Validation.Validation e a)
instance GHC.Base.Monoid e => GHC.Base.Monoid (Data.Validation.Validation e a)
instance Control.Lens.Iso.Swapped Data.Validation.Validation
instance (Control.DeepSeq.NFData e, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Data.Validation.Validation e a)
