-- 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
-- lens-related functions for converting between each and
-- abstracting over their similarities.
--
--
--
-- The Validation data type is isomorphic to Either, but
-- has an instance of Applicative that accumulates on the error
-- side. That is to say, if two (or more) errors are encountered, they
-- are appended using a Semigroup operation.
--
-- As a consequence of this Applicative instance, there is no
-- corresponding Bind or Monad instance. Validation
-- is an example of, "An applicative functor that is not a monad."
@package validation
@version 1.1.3
-- | A data type similar to Data.Either that accumulates failures.
module Data.Validation
-- | A Validation is either a value of the type err or
-- a, similar to Either. However, the Applicative
-- instance for Validation accumulates errors using a
-- Semigroup on err. In contrast, the
-- Applicative for Either returns only the first error.
--
-- A consequence of this is that Validation has no Bind
-- or Monad instance. This is because such an instance would
-- violate the law that a Monad's ap must equal the
-- Applicative's <*>
--
-- An example of typical usage can be found here.
data Validation err a
Failure :: err -> Validation err a
Success :: a -> Validation err a
-- | validates an a producing an updated optional value,
-- returning e in the empty case.
--
-- This can be thought of as having the less general type:
--
--
-- validate :: e -> (a -> Maybe b) -> a -> Validation e b
--
validate :: Validate v => e -> (a -> Maybe b) -> a -> v e b
-- | validationNel is liftError specialised to
-- NonEmpty lists, since they are a common semigroup to use.
validationNel :: Either e a -> Validation (NonEmpty e) a
-- | Converts from Either to Validation.
fromEither :: Either e a -> Validation e a
-- | liftError is useful for converting an Either to an
-- Validation when the Left of the Either needs to
-- be lifted into a Semigroup.
liftError :: (b -> e) -> Either b a -> Validation e a
-- | validation is the catamorphism for Validation.
validation :: (e -> c) -> (a -> c) -> Validation e a -> c
-- | Converts from Validation to Either.
toEither :: Validation e a -> Either e a
-- | v orElse a returns a when v is
-- Failure, and the a in Success a.
--
-- This can be thought of as having the less general type:
--
--
-- orElse :: Validation e a -> a -> a
--
orElse :: Validate v => v e a -> a -> a
-- | Return the a or run the given function over the e.
--
-- This can be thought of as having the less general type:
--
--
-- valueOr :: (e -> a) -> Validation e a -> a
--
valueOr :: Validate v => (e -> a) -> v e a -> a
-- | ensure ensures that a validation remains unchanged upon
-- failure, updating a successful validation with an optional value that
-- could fail with e otherwise.
--
-- This can be thought of as having the less general type:
--
--
-- ensure :: e -> (a -> Maybe b) -> Validation e a -> Validation e b
--
ensure :: Validate v => e -> (a -> Maybe b) -> v e a -> v e b
-- | codiagonal 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
--
--
-- (Either e a -> Either e' a') -> Validation e a -> Validation e' a'
--
validationed :: Validate v => (v e a -> v e' a') -> Validation e a -> Validation e' a'
-- | bindValidation binds through a 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 Monad instance.
bindValidation :: Validation e a -> (a -> Validation e b) -> Validation e b
-- | This prism generalises _Left. It targets the failure case of
-- either Either or Validation.
_Failure :: Validate f => Prism (f e1 a) (f e2 a) e1 e2
-- | This prism generalises _Right. It targets the success case of
-- either Either or Validation.
_Success :: Validate f => Prism (f e a) (f e b) a b
-- | The Validate class carries around witnesses that the type
-- f 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)
-- | revalidate converts between any two instances of
-- Validate.
revalidate :: (Validate f, Validate g) => Iso (f e1 s) (f e2 t) (g e1 s) (g e2 t)
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.Generics.Generic (Data.Validation.Validation err a)
instance (GHC.Classes.Eq err, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Validation.Validation err a)
instance (Data.Data.Data err, Data.Data.Data a) => Data.Data.Data (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 Data.Bifunctor.Swap.Swap Data.Validation.Validation
instance (Control.DeepSeq.NFData e, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Data.Validation.Validation e a)