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


-- | Validity typeclass
--   
--   For more info, see <a>the readme</a>.
--   
--   Note: There are companion instance packages for this library:
--   
--   <ul>
--   <li><a>validity-aeson</a></li>
--   <li><a>validity-bytestring</a></li>
--   <li><a>validity-containers</a></li>
--   <li><a>validity-path</a></li>
--   <li><a>validity-scientific</a></li>
--   <li><a>validity-text</a></li>
--   <li><a>validity-time</a></li>
--   <li><a>validity-unordered-containers</a></li>
--   <li><a>validity-uuid</a></li>
--   <li><a>validity-vector</a></li>
--   </ul>
@package validity
@version 0.4.0.2


-- | <tt>Validity</tt> is used to specify additional invariants upon values
--   that are not enforced by the type system.
--   
--   Let's take an example. Suppose we were to implement a type
--   <tt>Prime</tt> that represents prime integers.
--   
--   If you were to completely enforce the invariant that the represented
--   number is a prime, then we could use <a>Natural</a> and only store the
--   index of the given prime in the infinite sequence of prime numbers.
--   This is very safe but also very expensive if we ever want to use the
--   number, because we would have to calculcate all the prime numbers
--   until that index.
--   
--   Instead we choose to implement <tt>Prime</tt> by a <tt>newtype Prime =
--   Prime Int</tt>. Now we have to maintain the invariant that the
--   <tt>Int</tt> that we use to represent the prime is in fact positive
--   and a prime.
--   
--   The <tt>Validity</tt> typeclass allows us to specify this invariant
--   (and enables testing via the <tt>genvalidity</tt> libraries:
--   <a>https://hackage.haskell.org/package/genvalidity</a> ):
--   
--   <pre>
--   instance Validity Prime where
--       validate (Prime n) = isPrime n &lt;?@&gt; "The 'Int' is prime."
--       isValid (Prime n) = isPrime n
--   </pre>
--   
--   If certain typeclass invariants exist, you can make these explicit in
--   the validity instance as well. For example, 'Fixed a' is only valid if
--   <tt>a</tt> has an <a>HasResolution</a> instance, so the correct
--   validity instance is <tt>HasResolution a =&gt; Validity (Fixed
--   a)</tt>.
module Data.Validity

-- | A class of types that have additional invariants defined upon them
--   that aren't enforced by the type system
--   
--   <h3>Purpose</h3>
--   
--   <a>validate</a> checks whether a given value is a valid value and
--   reports all reasons why the given value is not valid if that is the
--   case.
--   
--   <a>isValid</a> only checks whether a given value is a valid value of
--   its type.
--   
--   <h3>Instantiating <a>Validity</a></h3>
--   
--   To instantiate <a>Validity</a>, one has to implement both
--   <a>isValid</a> and <a>validate</a>. Start by implementing
--   <a>validate</a>. Use the helper functions below to define all the
--   reasons why a given value would be a valid value of its type. Then
--   define `isValid = isValidbyValidating' for now.
--   
--   Example:
--   
--   <pre>
--   newtype Even = Even Int
--   
--   instance Validity Even
--       validate (Event i)
--         even i &lt;?@&gt; "The contained 'Int' is even."
--       isValid = isValidByValidating
--   </pre>
--   
--   If it turns out that, at this point, <a>isValid</a> is too slow for
--   your taste, you can replace the implementation of <a>isValid</a> by a
--   custom implementation. However, it is important that this
--   <a>isValid</a> implementation has exactly the same semantics as
--   <tt>isValidbyValidating</tt>.
--   
--   Example:
--   
--   <pre>
--   newtype Even = Even Int
--   
--   instance Validity Even
--       validate (Event i)
--         even i &lt;?@&gt; "The contained 'Int' is even."
--       isValid (Event i) = even i
--   </pre>
--   
--   <h3>Semantics</h3>
--   
--   <a>isValid</a> should be an underapproximation of actual validity.
--   
--   This means that if <a>isValid</a> is not a perfect representation of
--   actual validity, for safety reasons, it should never return
--   <a>True</a> for invalid values, but it may return <a>False</a> for
--   valid values.
--   
--   For example:
--   
--   <pre>
--   isValid = const False
--   </pre>
--   
--   is a valid implementation for any type, because it never returns
--   <a>True</a> for invalid values.
--   
--   <pre>
--   isValid (Even i) = i == 2
--   </pre>
--   
--   is a valid implementation for <tt>newtype Even = Even Int</tt>, but
--   
--   <pre>
--   isValid (Even i) = even i || i == 1
--   </pre>
--   
--   is not because it returns <a>True</a> for an invalid value: '1'.
--   
--   <h3>Automatic instances with <a>Generic</a></h3>
--   
--   An instance of this class can be made automatically if the type in
--   question has a <a>Generic</a> instance. This instance will try to use
--   <a>isValid</a> to on all structural sub-parts of the value that is
--   being checked for validity.
--   
--   Example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   data MyType = MyType
--       { myDouble :: Double
--       { myString :: String
--       } deriving (Show, Eq, Generic)
--   
--   instance Validity MyType
--   </pre>
--   
--   generates something like:
--   
--   <pre>
--   instance Validity MyType where
--       isValid (MyType d s)
--           = isValid d &amp;&amp; isValid s
--       validate (MyType d s)
--           = d &lt;?!&gt; "myDouble"
--          &lt;&gt; s &lt;?!&gt; "myString"
--   </pre>
class Validity a where validate = gValidate . from isValid = gIsValid . from
validate :: Validity a => a -> Validation
validate :: (Validity a, Generic a, GValidity (Rep a)) => a -> Validation
isValid :: Validity a => a -> Bool
isValid :: (Validity a, Generic a, GValidity (Rep a)) => a -> Bool

-- | Declare any value to be valid.
--   
--   <pre>
--   triviallyValid a = seq a True
--   </pre>
triviallyValid :: a -> Bool

-- | Declare any value to be valid in validation
--   
--   <pre>
--   trivialValidation a = seq a mempty
--   </pre>
trivialValidation :: a -> Validation

-- | Implement <a>isValid</a> by using <a>validate</a> and checking that
--   there are no reasons that the value is invalid.
isValidByValidating :: Validity a => a -> Bool

-- | Check that a given invariant holds.
--   
--   The given string should describe the invariant, not the violation.
--   
--   Example:
--   
--   <pre>
--   check (x &lt; 5) "x is strictly smaller than 5"
--   </pre>
--   
--   instead of
--   
--   <pre>
--   check (x &lt; 5) "x is greater than 5"
--   </pre>
check :: Bool -> String -> Validation

-- | Infix operator for <a>annotate</a>
--   
--   Example:
--   
--   <pre>
--   validate (a, b) =
--       mconcat
--           [ a &lt;?!&gt; "The first element of the tuple"
--           , b &lt;?!&gt; "The second element of the tuple"
--           ]
--   </pre>
(<?!>) :: Validity a => a -> String -> Validation
infixr 0 <?!>

-- | Declare a sub-part as a necessary part for validation, and annotate it
--   with a name.
--   
--   Example:
--   
--   <pre>
--   validate (a, b) =
--       mconcat
--           [ annotate a "The first element of the tuple"
--           , annotate b "The second element of the tuple"
--           ]
--   </pre>
annotate :: Validity a => a -> String -> Validation

-- | Infix operator for <a>check</a>
--   
--   Example:
--   
--   <pre>
--   x &lt; 5 &lt;?@&gt; "x is strictly smaller than 5"
--   </pre>
(<?@>) :: Bool -> String -> Validation
infixr 0 <?@>

-- | Implement <a>validate</a> by using <a>isValid</a> and using the given
--   string as the reason if the value is invalid.
validateByChecking :: Validity a => String -> a -> Validation

-- | Implement <a>validate</a> by using <a>isValid</a> and using the given
--   name to define the reason if the value is invalid.
--   
--   <pre>
--   validateByCheckingName name = validateByChecking $ unwords ["The", name, "valid."]
--   </pre>
validateByCheckingName :: Validity a => String -> a -> Validation

-- | Implement <a>validate</a> by using <a>isValid</a> and using a default
--   reason if the value is invalid.
--   
--   <pre>
--   validateByCheckingDefault = validateByChecking "The value is valid."
--   </pre>
validateByCheckingDefault :: Validity a => a -> Validation

-- | Check whether <a>isInvalid</a> is not valid.
--   
--   <pre>
--   isInvalid = not . isValid
--   </pre>
isInvalid :: Validity a => a -> Bool

-- | Construct a valid element from an unchecked element
constructValid :: Validity a => a -> Maybe a

-- | Construct a valid element from an unchecked element, throwing
--   <a>error</a> on invalid elements.
constructValidUnsafe :: (Show a, Validity a) => a -> a
newtype Validation
Validation :: [ValidationChain] -> Validation
[unValidation] :: Validation -> [ValidationChain]
data ValidationChain
Violated :: String -> ValidationChain
Location :: String -> ValidationChain -> ValidationChain

-- | validate a given value.
--   
--   This function returns either all the reasons why the given value is
--   invalid, in the form of a list of <a>ValidationChain</a>s, or it
--   returns <a>Right</a> with the input value, as evidence that it is
--   valid.
--   
--   Note: You map want to use <a>prettyValidation</a> instead, if you want
--   to display these <a>ValidationChain</a>s to a user.
checkValidity :: Validity a => a -> Either [ValidationChain] a

-- | validate a given value, and return a nice error if the value is
--   invalid.
prettyValidation :: Validity a => a -> Either String a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>mappend mempty x = x</pre></li>
--   <li><pre>mappend x mempty = x</pre></li>
--   <li><pre>mappend x (mappend y z) = mappend (mappend x y) z</pre></li>
--   <li><pre>mconcat = <a>foldr</a> mappend mempty</pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
class Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid. For most types, the default definition
--   for <a>mconcat</a> will be used, but the function is included in the
--   class definition so that an optimized version can be provided for
--   specific types.
mconcat :: Monoid a => [a] -> a
instance GHC.Generics.Generic Data.Validity.Validation
instance GHC.Classes.Eq Data.Validity.Validation
instance GHC.Show.Show Data.Validity.Validation
instance GHC.Generics.Generic Data.Validity.ValidationChain
instance GHC.Classes.Eq Data.Validity.ValidationChain
instance GHC.Show.Show Data.Validity.ValidationChain
instance Data.Validity.Validity Data.Validity.ValidationChain
instance Data.Validity.Validity Data.Validity.Validation
instance GHC.Base.Monoid Data.Validity.Validation
instance (Data.Validity.Validity a, Data.Validity.Validity b) => Data.Validity.Validity (a, b)
instance (Data.Validity.Validity a, Data.Validity.Validity b) => Data.Validity.Validity (Data.Either.Either a b)
instance (Data.Validity.Validity a, Data.Validity.Validity b, Data.Validity.Validity c) => Data.Validity.Validity (a, b, c)
instance (Data.Validity.Validity a, Data.Validity.Validity b, Data.Validity.Validity c, Data.Validity.Validity d) => Data.Validity.Validity (a, b, c, d)
instance (Data.Validity.Validity a, Data.Validity.Validity b, Data.Validity.Validity c, Data.Validity.Validity d, Data.Validity.Validity e) => Data.Validity.Validity (a, b, c, d, e)
instance (Data.Validity.Validity a, Data.Validity.Validity b, Data.Validity.Validity c, Data.Validity.Validity d, Data.Validity.Validity e, Data.Validity.Validity f) => Data.Validity.Validity (a, b, c, d, e, f)
instance Data.Validity.Validity a => Data.Validity.Validity [a]
instance Data.Validity.Validity a => Data.Validity.Validity (Data.List.NonEmpty.NonEmpty a)
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Base.Maybe a)
instance Data.Validity.Validity ()
instance Data.Validity.Validity GHC.Types.Bool
instance Data.Validity.Validity GHC.Types.Ordering
instance Data.Validity.Validity GHC.Types.Char
instance Data.Validity.Validity GHC.Types.Int
instance Data.Validity.Validity GHC.Types.Word
instance Data.Validity.Validity GHC.Word.Word8
instance Data.Validity.Validity GHC.Word.Word16
instance Data.Validity.Validity GHC.Word.Word32
instance Data.Validity.Validity GHC.Word.Word64
instance Data.Validity.Validity GHC.Types.Float
instance Data.Validity.Validity GHC.Types.Double
instance Data.Validity.Validity GHC.Integer.Type.Integer
instance Data.Validity.Validity GHC.Natural.Natural
instance Data.Validity.Validity GHC.Real.Rational
instance Data.Fixed.HasResolution a => Data.Validity.Validity (Data.Fixed.Fixed a)
instance Data.Validity.GValidity GHC.Generics.U1
instance Data.Validity.GValidity GHC.Generics.V1
instance (Data.Validity.GValidity a, Data.Validity.GValidity b) => Data.Validity.GValidity (a GHC.Generics.:*: b)
instance (Data.Validity.GValidity a, Data.Validity.GValidity b) => Data.Validity.GValidity (a GHC.Generics.:+: b)
instance (Data.Validity.GValidity a, GHC.Generics.Datatype c) => Data.Validity.GValidity (GHC.Generics.M1 GHC.Generics.D c a)
instance (Data.Validity.GValidity a, GHC.Generics.Constructor c) => Data.Validity.GValidity (GHC.Generics.M1 GHC.Generics.C c a)
instance (Data.Validity.GValidity a, GHC.Generics.Selector c) => Data.Validity.GValidity (GHC.Generics.M1 GHC.Generics.S c a)
instance Data.Validity.Validity a => Data.Validity.GValidity (GHC.Generics.K1 GHC.Generics.R a)


-- | Relative validity
module Data.RelativeValidity

-- | A class of types that have additional invariants defined upon them
--   that aren't enforced by the type system
--   
--   If there is a <tt>Validity a</tt> instance as well, then <tt>a
--   <a>isValidFor</a> b</tt> should imply <tt>isValid a</tt> for any
--   <tt>b</tt>.
--   
--   If there is a <tt>Validity b</tt> instance as well, then <tt>a
--   <a>isValidFor</a> b</tt> should imply <tt>isValid b</tt> for any
--   <tt>a</tt>.
class RelativeValidity a b
isValidFor :: RelativeValidity a b => a -> b -> Bool
isInvalidFor :: RelativeValidity a b => a -> b -> Bool