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


-- | A library for creating type safe validations.
--   
--   A library for creating type safe validations using typeclasses.
@package data-validation
@version 0.1.2.0

module Data.Validation.Internal

-- | A type that holds aggregated validation failures.
data VCtx f a

-- | A value that is assumed to be valid.
ValidCtx :: a -> VCtx f a

-- | A value that has failures but can continue to be validated.
DisputedCtx :: [f] -> Map [Name] [f] -> a -> VCtx f a

-- | A value that has failures and cannot be validated further.
RefutedCtx :: [f] -> Map [Name] [f] -> VCtx f a

-- | Takes the failures from the second parameter and adds them to the
--   first.
aggregateFailures :: VCtx f a -> VCtx f b -> VCtx f a

-- | Takes the failures from the right-hand-side, if any, and adds them to
--   the left-hand-side.
(<!) :: VCtx f a -> VCtx f b -> VCtx f a
testMatch :: Eq a => f -> a -> a -> Maybe f
instance (GHC.Classes.Eq a, GHC.Classes.Eq f) => GHC.Classes.Eq (Data.Validation.Internal.VCtx f a)
instance (GHC.Show.Show a, GHC.Show.Show f) => GHC.Show.Show (Data.Validation.Internal.VCtx f a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Data.Validation.Internal.VCtx f a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Validation.Internal.VCtx f a)
instance GHC.Base.Functor (Data.Validation.Internal.VCtx f)
instance GHC.Base.Applicative (Data.Validation.Internal.VCtx f)
instance GHC.Base.Monad (Data.Validation.Internal.VCtx f)

module Data.Validation

-- | A type that holds either validation failures or a validated value.
data Proof f a

-- | A validated value.
Valid :: a -> Proof f a

-- | Global and field validation failures.
Invalid :: [f] -> Map [Name] [f] -> Proof f a

-- | Converts a <a>VCtx</a> to a <a>Proof</a>.
--   
--   Internally, this library uses the <a>VCtx</a> type to track validation
--   failures. This is because a validation failure can be partial. For
--   instance, checking that a password has a special character can happen
--   even if the check for a numeric character has already failed. This
--   allows validation to discover as many failures as possible.
--   
--   However, once validation is complete, the result becomes binary. The
--   validation has either succeeded or failed. In order to convert from a
--   <a>VCtx</a> to a <a>Proof</a>, use the <a>fromVCtx</a> function.
fromVCtx :: VCtx f a -> Proof f a

-- | A type for storing a value to validate and, optionally, its field
--   name.
data ValueCtx a

-- | The <a>Field</a> constructor represents a value that is named.
Field :: Name -> a -> ValueCtx a

-- | The <a>Global</a> constructor represents a value that is not named.
Global :: a -> ValueCtx a

-- | Accessor for a <tt>ValueCtx'</tt>s value.
getValue :: ValueCtx a -> a

-- | Replaces the existing value with a new one without changing the name,
--   if one exists.
setValue :: ValueCtx a -> b -> ValueCtx b

-- | Performs some given validation using a <a>Field</a> with a given name
--   and value.
withField :: Name -> a -> (ValueCtx a -> VCtx f (ValueCtx b)) -> VCtx f b

-- | Performs some given validation using a <a>Global</a> with a given
--   value.
withValue :: a -> (ValueCtx a -> VCtx f (ValueCtx b)) -> VCtx f b

-- | A type class that represents a value that can be validated.
--   
--   The parameters represent the following:
--   
--   <ul>
--   <li><tt>f</tt>: the type of validation failures.</li>
--   <li><tt>a</tt>: the unvalidated type or view model.</li>
--   <li><tt>b</tt>: the validated type.</li>
--   </ul>
class Validatable f a b | a -> f b
validation :: Validatable f a b => a -> VCtx f b

-- | Runs the validations for a given value and returns the proof.
validate :: Validatable f a b => a -> Proof f b

-- | Adds a validation failure to the result and ends validation.
refute :: ValueCtx a -> f -> VCtx f b

-- | Adds validation failures to the result and ends validation.
refuteMany :: ValueCtx a -> [f] -> VCtx f b

-- | Performs a validation using a given function and handles the result.
--   If the result is `Left f`, a validation failure is added to the result
--   and validation ends. If the result is `Right b`, validation continues
--   with the new value.
refuteWith :: (a -> Either f b) -> ValueCtx a -> VCtx f (ValueCtx b)

-- | Performs a validation using a given function and handles the result.
--   If the result is <a>Invalid</a>, the validation failures are added to
--   the result and validation ends. If the result is `Valid b`, validation
--   continues with the new value.
refuteWithProof :: (a -> Proof f b) -> ValueCtx a -> VCtx f (ValueCtx b)

-- | Adds a validation failure to the result and continues validation.
dispute :: ValueCtx a -> f -> VCtx f (ValueCtx a)

-- | Adds validation failures to the result and continues validation.
disputeMany :: ValueCtx a -> [f] -> VCtx f (ValueCtx a)

-- | Performs a validation using a given function and handles the result.
--   If the result is `Just f`, a validation failure is added to the result
--   and validation continues. If the result is <a>Nothing</a>, validation
--   continues with no failure.
disputeWith :: (a -> Maybe f) -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Similar to <a>disputeWith</a> except that the given failure is added
--   if the given function returns False.
disputeWithFact :: f -> (a -> Bool) -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a <a>Maybe</a> value is a <a>Just</a>. If not, it adds the
--   given failure to the result and validation end.
isRequired :: f -> ValueCtx (Maybe a) -> VCtx f (ValueCtx a)

-- | Checks that a <a>Maybe</a> value is a <a>Just</a> when some condition
--   is true. If the condition is met and the value is <a>Just</a>, it adds
--   the given failure to the result and validation continues.
isRequiredWhen :: f -> Bool -> ValueCtx (Maybe a) -> VCtx f (ValueCtx (Maybe a))

-- | Checks that a <a>Maybe</a> value is a <a>Just</a> when some condition
--   is false. If the condition is not met and the value is <a>Just</a>, it
--   adds the given failure to the result and validation continues.
isRequiredUnless :: f -> Bool -> ValueCtx (Maybe a) -> VCtx f (ValueCtx (Maybe a))

-- | Checks that a <a>Either</a> value is a <a>Left</a>. If not, it adds
--   the given failure to the result and validation end.
isLeft :: f -> ValueCtx (Either a b) -> VCtx f (ValueCtx a)

-- | Checks that a <a>Either</a> value is a <a>Right</a>. If not, it adds
--   the given failure to the result and validation end.
isRight :: f -> ValueCtx (Either a b) -> VCtx f (ValueCtx b)

-- | Checks that the <a>Foldable</a> is empty. If not, it adds the given
--   failure to the result and validation continues.
isNull :: Foldable t => f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that the <a>Foldable</a> is not empty. If empty, it adds the
--   given failure to the result and validation continues.
isNotNull :: Foldable t => f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that a <a>Foldable</a> has a length equal to or greater than
--   the given value. If not, it adds the given failure to the result and
--   validation continues.
minLength :: Foldable t => Int -> f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that a <a>Foldable</a> has a length equal to or less than the
--   given value. If not, it adds the given failure to the result and
--   validation continues.
maxLength :: Foldable t => Int -> f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that a <a>Foldable</a> has a length equal to the given value.
--   If not, it adds the given failure to the result and validation
--   continues.
isLength :: Foldable t => Int -> f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that a value is equal to another. If not, it adds the given
--   failure to the result and validation continues.
isEqual :: Eq a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a value is not equal to another. If equal, it adds the
--   given failure to the result and validation continues.
isNotEqual :: Eq a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a value is less than another. If not, it adds the given
--   failure to the result and validation continues.
isLessThan :: Ord a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a value is less than or equal to another. If not, it adds
--   the given failure to the result and validation continues.
isLessThanOrEqual :: Ord a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a value is greater than another. If not, it adds the given
--   failure to the result and validation continues.
isGreaterThan :: Ord a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a value is greater than or equal to another. If not, it
--   adds the given failure to the result and validation continues.
isGreaterThanOrEqual :: Ord a => a -> f -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Checks that a <a>Foldable</a> has a given element. If not, it adds the
--   given failure to the result and validation continues.
hasElem :: (Foldable t, Eq a) => a -> f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | Checks that a <a>Foldable</a> does not have a given element. If it has
--   element, it adds the given failure to the result and validation
--   continues.
doesNotHaveElem :: (Foldable t, Eq a) => a -> f -> ValueCtx (t a) -> VCtx f (ValueCtx (t a))

-- | If any element is valid, the entire value is valid.
ifAny :: (a -> Maybe f) -> ValueCtx [a] -> VCtx f (ValueCtx [a])

-- | Every element must be valid.
ifAll :: (a -> Maybe f) -> ValueCtx [a] -> VCtx f (ValueCtx [a])

-- | Validate each element with a given function.
ifEach :: (a -> Either f b) -> ValueCtx [a] -> VCtx f (ValueCtx [b])

-- | Validate each element with a given function.
ifEachProven :: (a -> Proof f b) -> ValueCtx [a] -> VCtx f (ValueCtx [b])

-- | Checks that two fields are equal. If not, it adds the given failure to
--   the result and validation continues.
isMatch :: Eq a => f -> VCtx f a -> ValueCtx a -> VCtx f (ValueCtx a)

-- | Validates a value that implements <a>Validatable</a> and includes any
--   failures under the parent field.
--   
--   Consider the following example:
--   
--   <pre>
--   data ContactVM = ContactVM { phoneNumber :: String }
--   data Contact = ...
--   instance Validatable MyFailureType ContactVM Contact where
--     ...
--   
--   data UserCreatableVM
--     = UserCreatableVM
--     { userCreatableVMEmailAddress         :: String
--     , userCreatableVMConfirmEmailAddress  :: String
--     , userCreatableVMPassword             :: String
--     , userCreatableVMConfirmPassword      :: String
--     , userCreatableVMContact              :: ContactVM
--     }
--   data UserCreatable = ...
--   
--   instance Validatable MyFailureType UserCreatableVM UserCreatable where
--     validation u =
--       let vc = withField 'userCreatableVMContact (userCreatableVMContact u) $
--             validateField                                                      -- (1)
--           ...
--       in pure UserCreatable &lt;*&gt; ve &lt;*&gt; vp &lt;*&gt; vc &lt;! vce &lt;! vcp
--   
--   </pre>
--   
--   In line (1), the <a>validateField</a> function uses the
--   <a>Validatable</a> instance on <tt>ContactVM</tt> to validate the
--   type. All field specific validation failures are stored in a map where
--   the key is the name of the field. However, in this case, there are the
--   fields in the <tt>ContactVM</tt> and the parent field in
--   <tt>UserCreatableVM</tt>. These names need to be combined so that the
--   consumer can see if any errors came from nested fields. Using the
--   <a>validateField</a> function, any validation failures found in the
--   <tt>ContactVM</tt> value have field names that include the parent
--   field. A <tt>ContactVM</tt> with an invalid phone number might have a
--   result like this: `Invalid [] [(['phoneNumber],
--   [InvalidPhoneNumber])]` where `['phoneNumber]` is the key to the map.
--   The <tt>validationField</tt> merges this with the
--   <tt>UserCreatable</tt> result to create something like this: `Invalid
--   [] [(['contact, 'phoneNumber], [InvalidPhoneNumber])]`. This allows
--   the consumer to determine exactly what field caused the failure.
validateField :: Validatable f a b => ValueCtx a -> VCtx f (ValueCtx b)

-- | Allows for validation of an optional value. See `Validating Complex
--   Types` for an example.
optional :: Maybe a -> (a -> VCtx f b) -> VCtx f (Maybe b)

-- | Allows for validation of an optional value. See `Validating Complex
--   Types` for an example.
whenJust :: (ValueCtx a -> VCtx f (ValueCtx b)) -> ValueCtx (Maybe a) -> VCtx f (ValueCtx (Maybe b))

-- | Takes the failures from the second parameter and adds them to the
--   first.
aggregateFailures :: VCtx f a -> VCtx f b -> VCtx f a

-- | Takes the failures from the right-hand-side, if any, and adds them to
--   the left-hand-side.
(<!) :: VCtx f a -> VCtx f b -> VCtx f a

-- | tests if a <a>Proof</a> is valid.
isValid :: Proof f a -> Bool

-- | tests if a <a>Proof</a> is invalid.
isInvalid :: Proof f a -> Bool

-- | Flatten a list of proofs into a proof of the list
flattenProofs :: [Proof f a] -> Proof f [a]

-- | A type that holds aggregated validation failures.
data VCtx f a

-- | An abstract type representing names in the syntax tree.
--   
--   <a>Name</a>s can be constructed in several ways, which come with
--   different name-capture guarantees (see
--   <a>Language.Haskell.TH.Syntax#namecapture</a> for an explanation of
--   name capture):
--   
--   <ul>
--   <li>the built-in syntax <tt>'f</tt> and <tt>''T</tt> can be used to
--   construct names, The expression <tt>'f</tt> gives a <tt>Name</tt>
--   which refers to the value <tt>f</tt> currently in scope, and
--   <tt>''T</tt> gives a <tt>Name</tt> which refers to the type <tt>T</tt>
--   currently in scope. These names can never be captured.</li>
--   <li><a>lookupValueName</a> and <a>lookupTypeName</a> are similar to
--   <tt>'f</tt> and <tt>''T</tt> respectively, but the <tt>Name</tt>s are
--   looked up at the point where the current splice is being run. These
--   names can never be captured.</li>
--   <li><a>newName</a> monadically generates a new name, which can never
--   be captured.</li>
--   <li><a>mkName</a> generates a capturable name.</li>
--   </ul>
--   
--   Names constructed using <tt>newName</tt> and <tt>mkName</tt> may be
--   used in bindings (such as <tt>let x = ...</tt> or <tt>x -&gt;
--   ...</tt>), but names constructed using <tt>lookupValueName</tt>,
--   <tt>lookupTypeName</tt>, <tt>'f</tt>, <tt>''T</tt> may not.
data Name

-- | Generate a capturable name. Occurrences of such names will be resolved
--   according to the Haskell scoping rules at the occurrence site.
--   
--   For example:
--   
--   <pre>
--   f = [| pi + $(varE (mkName "pi")) |]
--   ...
--   g = let pi = 3 in $f
--   </pre>
--   
--   In this case, <tt>g</tt> is desugared to
--   
--   <pre>
--   g = Prelude.pi + 3
--   </pre>
--   
--   Note that <tt>mkName</tt> may be used with qualified names:
--   
--   <pre>
--   mkName "Prelude.pi"
--   </pre>
--   
--   See also <a>dyn</a> for a useful combinator. The above example could
--   be rewritten using <a>dyn</a> as
--   
--   <pre>
--   f = [| pi + $(dyn "pi") |]
--   </pre>
mkName :: String -> Name

-- | The name without its module prefix.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; nameBase ''Data.Either.Either
--   "Either"
--   
--   &gt;&gt;&gt; nameBase (mkName "foo")
--   "foo"
--   
--   &gt;&gt;&gt; nameBase (mkName "Module.foo")
--   "foo"
--   </pre>
nameBase :: Name -> String
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Validation.ValueCtx a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Validation.ValueCtx a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq f) => GHC.Classes.Eq (Data.Validation.Proof f a)
instance (GHC.Show.Show a, GHC.Show.Show f) => GHC.Show.Show (Data.Validation.Proof f a)
instance GHC.Base.Functor Data.Validation.ValueCtx
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Data.Validation.Proof f a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Validation.Proof f a)
instance GHC.Base.Functor (Data.Validation.Proof f)
instance GHC.Base.Applicative (Data.Validation.Proof f)
instance GHC.Base.Monad (Data.Validation.Proof f)

module Data.Validation.Transforms

-- | A type that represents a validated type.
data V

-- | A type that represents an unvalidated type, often called a View Model.
data VM

-- | A type that represents a validation transformaion. The unvalidated
--   type is the first parameter which is used when <a>VM</a> is passed in.
--   The second parameter is the validated type which is used when <a>V</a>
--   is passed in.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   data ThingV v 
--     = Thing 
--     { emailAddress :: VT v String EmailAddress
--     , confirmEmailAddress :: VT v String () 
--     }
--   type ThingVM = ThingV VM -- A <tt>Thing</tt> view model.
--   type Thing = ThingV V    -- A validated <tt>Thing</tt>.
--   </pre>
type family VT v a b