-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Lighweight pure data validation based on Applicative -- -- Lighweight pure data validation based on Applicative. The library -- provides the following Either-like data type with suitable instances -- like Semigroup to accumulate validation errors in the Failure -- branch : -- --

--   data Validation e a
--       = Failure e
--       | Success a
--

@package validation-micro @version 0.1.0.0 -- | Lightweight pure data validation based on Applicative functors. -- -- Validation allows to accumulate all errors instead of -- short-circuting on the first error so you can display all possible -- errors at once. -- -- Common use-cases include: -- --

Validating each input of a form with multiple inputs.
Performing multiple validations of a single value.

-- -- Validation provides modular and composable -- interface which means that you can implement validations for different -- pieces of your data independently, and then combine smaller parts into -- the validation of a bigger type. The below table illustrates main ways -- to combine two Validations: -- -- TODO: table -- -- In other words, instances of different standard typeclasses provide -- various semantics which can be useful in different use-cases: -- --

Semigroup: accumulate both Failure and -- Success with <>.
Monoid: Success that stores mempty.
Functor: change the type inside Success.
Bifunctor: change both Failure and -- Success.
Applicative: apply function to values inside Success -- and accumulate errors inside Failure.
Alternative: return the first Success or accumulate -- all errors inside Failure.

module Validation.Micro -- | Validation is a sum type for storing either all validation -- failures or validation success. Unlike Either, which returns -- only the first error, Validation accumulates all errors using -- the Semigroup typeclass. -- -- Usually type variables in Validation e a are used as -- follows: -- --

e: is a list or set of failure messages or values of some -- error data type.
a: is some domain type denoting successful validation -- result.

-- -- Some typical use-cases: -- --

```
Validation [String] User
```
- Either -- list of String error messages or a validated value of a custom -- User type.
```
Validation (NonEmpty UserValidationError)
--   User
```
- Similar to previous example, but list of failures -- guaranteed to be non-empty in case of validation failure, and it -- stores values of some custom error type.

data Validation e a -- | Validation failure. The e type is supposed to implement the -- Semigroup instance. Failure :: e -> Validation e a -- | Successful validation result of type a. Success :: a -> Validation e a -- | Predicate on if the given Validation is Failure. -- --

--   >>> isFailure (Failure 'e')
--   True
--   
--   >>> isFailure (Success 'a')
--   False
--

isFailure :: Validation e a -> Bool -- | Predicate on if the given Validation is Success. -- --

--   >>> isSuccess (Success 'a')
--   True
--   
--   >>> isSuccess (Failure 'e')
--   False
--

isSuccess :: Validation e a -> Bool -- | Transforms the value of the given Validation into x -- using provided functions that can transform Failure and -- Success value into the resulting type respectively. -- --

--   >>> let myValidation = validation (<> " world!") (show . (* 10))
--   
--   >>> myValidation (Success 100)
--   "1000"
--   
--   >>> myValidation (Failure "Hello")
--   "Hello world!"
--

validation :: (e -> x) -> (a -> x) -> Validation e a -> x -- | Filters out all Failure values into the new list of es -- from the given list of Validations. -- -- Note that the order is preserved. -- --

--   >>> failures [Failure "Hello", Success 1, Failure "world", Success 2, Failure "!" ]
--   ["Hello","world","!"]
--

failures :: [Validation e a] -> [e] -- | Filters out all Success values into the new list of as -- from the given list of Validations. -- -- Note that the order is preserved. -- --

--   >>> successes [Failure "Hello", Success 1, Failure "world", Success 2, Failure "!" ]
--   [1,2]
--

successes :: [Validation e a] -> [a] -- | Redistributes the given list of Validations into two lists of -- es and es, where the first list contains all values -- of Failures and the second one — Successes -- correspondingly. -- -- Note that the order is preserved. -- --

--   >>> partitionValidations [Failure "Hello", Success 1, Failure "world", Success 2, Failure "!" ]
--   (["Hello","world","!"],[1,2])
--

partitionValidations :: [Validation e a] -> ([e], [a]) -- | Returns the contents of a Failure-value or a default value -- otherwise. -- --

--   >>> fromFailure "default" (Failure "failure")
--   "failure"
--   
--   >>> fromFailure "default" (Success 1)
--   "default"
--

fromFailure :: e -> Validation e a -> e -- | Returns the contents of a Success-value or a default value -- otherwise. -- --

--   >>> fromSuccess 42 (Success 1)
--   1
--   
--   >>> fromSuccess 42 (Failure "failure")
--   42
--

fromSuccess :: a -> Validation e a -> a -- | NB Validation is not a monad though bindValidation :: Validation e a -> (a -> Validation e b) -> Validation e b -- | Create a Failure of NonEmpty list with a single given -- error. -- --

--   >>> failure "I am a failure"
--   Failure ("I am a failure" :| [])
--

failure :: e -> Validation (NonEmpty e) a -- | Returns a Failure in case of the given predicate is -- True. Returns Success () otherwise. -- --

--   >>> let shouldFail = (==) "I am a failure"
--   
--   >>> failureIf (shouldFail "I am a failure") "I told you so"
--   Failure ("I told you so" :| [])
--   
--   >>> failureIf (shouldFail "I am NOT a failure") "okay"
--   Success ()
--

failureIf :: Bool -> e -> Validation (NonEmpty e) () -- | Returns a Failure unless the given predicate is True. -- Returns Success () in case of the predicate is -- satisfied. -- -- Similar to failureIf with the reversed predicate. -- --

--   failureUnless p ≡ failureIf (not p)
--

-- --

--   >>> let shouldFail = (==) "I am a failure"
--   
--   >>> failureUnless (shouldFail "I am a failure") "doesn't matter"
--   Success ()
--   
--   >>> failureUnless (shouldFail "I am NOT a failure") "I told you so"
--   Failure ("I told you so" :| [])
--

failureUnless :: Bool -> e -> Validation (NonEmpty e) () -- |

Combinators

-- -- We are providing several functions for better integration with the -- Either related code in this section. -- -- Transform a Validation into an Either. -- --

--   >>> validationToEither (Success "whoop")
--   Right "whoop"
--

-- --

--   >>> validationToEither (Failure "nahh")
--   Left "nahh"
--

validationToEither :: Validation e a -> Either e a -- | Transform an Either into a Validation. -- --

--   >>> eitherToValidation (Right "whoop")
--   Success "whoop"
--

-- --

--   >>> eitherToValidation (Left "nahh")
--   Failure "nahh"
--

eitherToValidation :: Either e a -> Validation e a -- | Validate all given checks in a Foldable. Returns the -- Success of the start element when all checks are successful. -- -- A basic example of usage could look like this: -- --

--   > let validatePassword = validateAll
--           [ validateEmptyPassword
--           , validateShortPassword
--           ]
--   
--   > validateAll "VeryStrongPassword"
--   Success "VeryStrongPassword"
--   
--   > validateAll ""
--   Failure (EmptyPassword :| [ShortPassword])
--

validateAll :: (Foldable f, Semigroup e) => f (a -> Validation e b) -> a -> Validation e a -- | Applies the given action to Validation if it is Success -- and returns the result. In case of Failure the default value is -- returned. -- --

--   >>> whenSuccess "bar" (Failure "foo") (\a -> "success!" <$ print a)
--   "bar"
--

-- --

--   >>> whenSuccess "bar" (Success 42) (\a -> "success!" <$ print a)
--   42
--   "success!"
--

whenSuccess :: Applicative f => x -> Validation e a -> (a -> f x) -> f x -- | Applies the given action to Validation if it is Failure -- and returns the result. In case of Success the default value is -- returned. -- --

--   >>> whenFailure "bar" (Failure 42) (\a -> "foo" <$ print a)
--   42
--   "foo"
--

-- --

--   >>> whenFailure "bar" (Success 42) (\a -> "foo" <$ print a)
--   "bar"
--

whenFailure :: Applicative f => x -> Validation e a -> (e -> f x) -> f x -- | Applies given action to the Validation content if it is -- Success. -- -- Similar to whenSuccess but the default value is (). -- --

--   >>> whenSuccess_ (Failure "foo") print
--   
--   >>> whenSuccess_ (Success 42) print
--   42
--

whenSuccess_ :: Applicative f => Validation e a -> (a -> f ()) -> f () -- | Applies given action to the Validation content if it is -- Failure. -- -- Similar to whenFailure but the default value is (). -- --

--   >>> whenFailure_ (Success 42) putStrLn
--   
--   >>> whenFailure_ (Failure "foo") putStrLn
--   foo
--

whenFailure_ :: Applicative f => Validation e a -> (e -> f ()) -> f () -- | Monadic version of whenSuccess. Applies monadic action to the -- given Validation in case of Success. Returns the -- resulting value, or provided default. -- --

--   >>> whenSuccessM "bar" (pure $ Failure "foo") (\a -> "success!" <$ print a)
--   "bar"
--

-- --

--   >>> whenSuccessM "bar" (pure $ Success 42) (\a -> "success!" <$ print a)
--   42
--   "success!"
--

whenSuccessM :: Monad m => x -> m (Validation e a) -> (a -> m x) -> m x -- | Monadic version of whenFailure. Applies monadic action to the -- given Validation in case of Failure. Returns the -- resulting value, or provided default. -- --

--   >>> whenFailureM "bar" (pure $ Failure 42) (\a -> "foo" <$ print a)
--   42
--   "foo"
--

-- --

--   >>> whenFailureM "bar" (pure $ Success 42) (\a -> "foo" <$ print a)
--   "bar"
--

whenFailureM :: Monad m => x -> m (Validation e a) -> (e -> m x) -> m x -- | Monadic version of whenSuccess_. Applies monadic action to the -- given Validation in case of Success. Similar to -- whenSuccessM but the default is (). -- --

--   >>> whenSuccessM_ (pure $ Failure "foo") print
--   
--   >>> whenSuccessM_ (pure $ Success 42) print
--   42
--

whenSuccessM_ :: Monad m => m (Validation e a) -> (a -> m ()) -> m () -- | Monadic version of whenFailure_. Applies monadic action to the -- given Validation in case of Failure. Similar to -- whenFailureM but the default is (). -- --

--   >>> whenFailureM_ (pure $ Success 42) putStrLn
--   
--   >>> whenFailureM_ (pure $ Failure "foo") putStrLn
--   foo
--

whenFailureM_ :: Monad m => m (Validation e a) -> (e -> m ()) -> m () -- | Maps Failure of Validation to Just. -- --

--   >>> failureToMaybe (Failure True)
--   Just True
--   
--   >>> failureToMaybe (Success "aba")
--   Nothing
--

failureToMaybe :: Validation e a -> Maybe e -- | Maps Success of Validation to Just. -- --

--   >>> successToMaybe (Failure True)
--   Nothing
--   
--   >>> successToMaybe (Success "aba")
--   Just "aba"
--

successToMaybe :: Validation e a -> Maybe a -- | Maps Just to Failure In case of Nothing it wraps -- the given default value into Success. -- --

--   >>> maybeToFailure True (Just "aba")
--   Failure "aba"
--   
--   >>> maybeToFailure True Nothing
--   Success True
--

maybeToFailure :: a -> Maybe e -> Validation e a -- | Maps Just to Success. In case of Nothing it wraps -- the given default value into Failure -- --

--   >>> maybeToSuccess True (Just "aba")
--   Success "aba"
--   
--   >>> maybeToSuccess True Nothing
--   Failure True
--

maybeToSuccess :: e -> Maybe a -> Validation e a instance Control.DeepSeq.NFData e => Control.DeepSeq.NFData1 (Validation.Micro.Validation e) instance (Control.DeepSeq.NFData e, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Validation.Micro.Validation e a) instance (Data.Data.Data e, Data.Data.Data a) => Data.Data.Data (Validation.Micro.Validation e a) instance GHC.Generics.Generic1 (Validation.Micro.Validation e) instance GHC.Generics.Generic (Validation.Micro.Validation e a) instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Validation.Micro.Validation e a) instance (GHC.Classes.Ord e, GHC.Classes.Ord a) => GHC.Classes.Ord (Validation.Micro.Validation e a) instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Validation.Micro.Validation e a) instance GHC.Base.Functor (Validation.Micro.Validation e) instance (GHC.Base.Semigroup e, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Validation.Micro.Validation e a) instance (GHC.Base.Semigroup e, GHC.Base.Monoid a) => GHC.Base.Monoid (Validation.Micro.Validation e a) instance GHC.Base.Semigroup e => GHC.Base.Applicative (Validation.Micro.Validation e) instance GHC.Base.Monoid e => GHC.Base.Alternative (Validation.Micro.Validation e) instance Data.Foldable.Foldable (Validation.Micro.Validation e) instance Data.Traversable.Traversable (Validation.Micro.Validation e) instance Data.Bifunctor.Bifunctor Validation.Micro.Validation instance Data.Bifoldable.Bifoldable Validation.Micro.Validation instance Data.Bitraversable.Bitraversable Validation.Micro.Validation instance Control.DeepSeq.NFData2 Validation.Micro.Validation