-- 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.12.1.0


-- | <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) = check (isPrime n) "The 'Int' is prime."
--   </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
class Validity a
validate :: Validity a => a -> Validation
($dmvalidate) :: (Validity a, Generic a, GValidity (Rep a)) => a -> Validation

-- | Declare any value to be valid in validation
--   
--   <pre>
--   trivialValidation a = seq a mempty
--   </pre>
trivialValidation :: a -> Validation
genericValidate :: (Generic a, GValidity (Rep a)) => a -> Validation

-- | 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

-- | <a>check</a>, but with the arguments flipped
declare :: String -> Bool -> Validation

-- | 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

-- | <a>annotate</a>, but with the arguments flipped.
delve :: Validity a => String -> a -> Validation

-- | Decorate a validation with a location
decorate :: String -> Validation -> Validation

-- | Decorate a piecewise validation of a list with their location in the
--   list
decorateList :: [a] -> (a -> Validation) -> Validation

-- | <a>decorateList</a>, but specifically for <a>String</a>s
--   
--   <pre>
--   decorateString = decorateList
--   </pre>
decorateString :: String -> (Char -> Validation) -> Validation

-- | Construct a trivially invalid <a>Validation</a>
--   
--   Example:
--   
--   <pre>
--   data Wrong
--       = Wrong
--       | Fine
--       deriving (Show, Eq)
--   
--   instance Validity Wrong where
--       validate w =
--           case w of
--               Wrong -&gt; invalid "Wrong"
--               Fine -&gt; valid
--   </pre>
invalid :: String -> Validation
valid :: Validation
validateCharNotUtf16SurrogateCodePoint :: Char -> Validation
isUtf16SurrogateCodePoint :: Char -> Bool
validateCharNotLineSeparator :: Char -> Validation
isLineSeparator :: Char -> Bool
validateStringSingleLine :: String -> Validation
isSingleLine :: String -> Bool
validateNotNaN :: RealFloat a => a -> Validation
validateNotInfinite :: RealFloat a => a -> Validation
validateRatioNotNaN :: Integral a => Ratio a -> Validation
validateRatioNotInfinite :: Integral a => Ratio a -> Validation
validateRatioNormalised :: Integral a => Ratio a -> Validation

-- | Check whether a value is valid.
isValid :: Validity a => a -> Bool

-- | Check whether a value 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

-- | The result of validating a value.
--   
--   <a>mempty</a> means the value was valid.
--   
--   This type intentionally doesn't have a <a>Validity</a> instance to
--   make sure you can never accidentally use <a>annotate</a> or
--   <a>delve</a> twice.
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 may 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

-- | Check if a <a>Validation</a> concerns a valid value.
validationIsValid :: Validation -> Bool

-- | Validate a given value
--   
--   This function will return a nice error if the value is invalid. It
--   will return the original value in <a>Right</a> if it was valid, as
--   evidence that it has been validated.
prettyValidate :: Validity a => a -> Either String a

-- | Render a <a>Validation</a> in a somewhat pretty way.
--   
--   This function will return <a>Nothing</a> if the <a>Validation</a>
--   concerned a valid value.
prettyValidation :: Validation -> Maybe String

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Right identity</i> <tt>x <a>&lt;&gt;</a> <a>mempty</a> =
--   x</tt></li>
--   <li><i>Left identity</i> <tt><a>mempty</a> <a>&lt;&gt;</a> x =
--   x</tt></li>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a>
--   law)</li>
--   <li><i>Concatenation</i> <tt><a>mconcat</a> = <a>foldr</a>
--   (<a>&lt;&gt;</a>) <a>mempty</a></tt></li>
--   </ul>
--   
--   You can alternatively define <a>mconcat</a> instead of <a>mempty</a>,
--   in which case the laws are:
--   
--   <ul>
--   <li><i>Unit</i> <tt><a>mconcat</a> (<a>pure</a> x) = x</tt></li>
--   <li><i>Multiplication</i> <tt><a>mconcat</a> (<a>join</a> xss) =
--   <a>mconcat</a> (<a>fmap</a> <a>mconcat</a> xss)</tt></li>
--   <li><i>Subclass</i> <tt><a>mconcat</a> (<tt>toList</tt> xs) =
--   <a>sconcat</a> xs</tt></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.
--   <a>Sum</a> and <a>Product</a>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello world" &lt;&gt; mempty
--   "Hello world"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mempty &lt;&gt; [1, 2, 3]
--   [1,2,3]
--   </pre>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = (<a>&lt;&gt;</a>)</tt> since
--   <i>base-4.11.0.0</i>. Should it be implemented manually, since
--   <a>mappend</a> is a synonym for (<a>&lt;&gt;</a>), it is expected that
--   the two functions are defined the same way. In a future GHC release
--   <a>mappend</a> will be removed from <a>Monoid</a>.
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.
--   
--   <pre>
--   &gt;&gt;&gt; mconcat ["Hello", " ", "Haskell", "!"]
--   "Hello Haskell!"
--   </pre>
mconcat :: Monoid a => [a] -> a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt></li>
--   </ul>
--   
--   You can alternatively define <a>sconcat</a> instead of
--   (<a>&lt;&gt;</a>), in which case the laws are:
--   
--   <ul>
--   <li><i>Unit</i> <tt><a>sconcat</a> (<a>pure</a> x) = x</tt></li>
--   <li><i>Multiplication</i> <tt><a>sconcat</a> (<a>join</a> xss) =
--   <a>sconcat</a> (<a>fmap</a> <a>sconcat</a> xss)</tt></li>
--   </ul>
class Semigroup a

-- | An associative operation.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &lt;&gt; [4,5,6]
--   [1,2,3,4,5,6]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Just [1, 2, 3] &lt;&gt; Just [4, 5, 6]
--   Just [1,2,3,4,5,6]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putStr "Hello, " &lt;&gt; putStrLn "World!"
--   Hello, World!
--   </pre>
(<>) :: Semigroup a => a -> a -> a

-- | Reduce a non-empty list with <a>&lt;&gt;</a>
--   
--   The default definition should be sufficient, but this can be
--   overridden for efficiency.
--   
--   <h4><b>Examples</b></h4>
--   
--   For the following examples, we will assume that we have:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.List.NonEmpty (NonEmpty (..))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sconcat $ "Hello" :| [" ", "Haskell", "!"]
--   "Hello Haskell!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sconcat $ Just [1, 2, 3] :| [Nothing, Just [4, 5, 6]]
--   Just [1,2,3,4,5,6]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sconcat $ Left 1 :| [Right 2, Left 3, Right 4]
--   Right 2
--   </pre>
sconcat :: Semigroup a => NonEmpty a -> a

-- | Repeat a value <tt>n</tt> times.
--   
--   The default definition will raise an exception for a multiplier that
--   is <tt>&lt;= 0</tt>. This may be overridden with an implementation
--   that is total. For monoids it is preferred to use
--   <tt>stimesMonoid</tt>.
--   
--   By making this a member of the class, idempotent semigroups and
--   monoids can upgrade this to execute in &lt;math&gt; by picking
--   <tt>stimes = <a>stimesIdempotent</a></tt> or <tt>stimes =
--   <a>stimesIdempotentMonoid</a></tt> respectively.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; stimes 4 [1]
--   [1,1,1,1]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stimes 5 (putStr "hi!")
--   hi!hi!hi!hi!hi!
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stimes 3 (Right ":)")
--   Right ":)"
--   </pre>
stimes :: (Semigroup a, Integral b) => b -> a -> a
infixr 6 <>
instance GHC.Classes.Eq Data.Validity.Validation
instance GHC.Classes.Eq Data.Validity.ValidationChain
instance (Data.Validity.GValidity a, Data.Validity.GValidity b) => Data.Validity.GValidity (a GHC.Internal.Generics.:*: b)
instance (Data.Validity.GValidity a, Data.Validity.GValidity b) => Data.Validity.GValidity (a GHC.Internal.Generics.:+: b)
instance Data.Validity.Validity a => Data.Validity.GValidity (GHC.Internal.Generics.K1 GHC.Internal.Generics.R a)
instance (Data.Validity.GValidity a, GHC.Internal.Generics.Datatype c) => Data.Validity.GValidity (GHC.Internal.Generics.M1 GHC.Internal.Generics.D c a)
instance (Data.Validity.GValidity a, GHC.Internal.Generics.Constructor c) => Data.Validity.GValidity (GHC.Internal.Generics.M1 GHC.Internal.Generics.C c a)
instance (Data.Validity.GValidity a, GHC.Internal.Generics.Selector c) => Data.Validity.GValidity (GHC.Internal.Generics.M1 GHC.Internal.Generics.S c a)
instance Data.Validity.GValidity GHC.Internal.Generics.U1
instance Data.Validity.GValidity GHC.Internal.Generics.V1
instance GHC.Internal.Generics.Generic Data.Validity.Validation
instance GHC.Internal.Generics.Generic Data.Validity.ValidationChain
instance GHC.Internal.Base.Monoid Data.Validity.Validation
instance GHC.Internal.Base.Semigroup Data.Validity.Validation
instance GHC.Internal.Show.Show Data.Validity.Validation
instance GHC.Internal.Show.Show Data.Validity.ValidationChain
instance Data.Validity.Validity (f a) => Data.Validity.Validity (GHC.Internal.Data.Semigroup.Internal.Alt f a)
instance Data.Validity.Validity GHC.Types.Bool
instance Data.Validity.Validity GHC.Types.Char
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Data.Functor.Const.Const a b)
instance Data.Validity.Validity GHC.Types.Double
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance (Data.Validity.Validity a, Data.Validity.Validity b) => Data.Validity.Validity (GHC.Internal.Data.Either.Either a b)
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Data.Monoid.First a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Semigroup.First a)
instance Data.Fixed.HasResolution a => Data.Validity.Validity (Data.Fixed.Fixed a)
instance Data.Validity.Validity GHC.Types.Float
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Data.Functor.Identity.Identity a)
instance Data.Validity.Validity GHC.Types.Int
instance Data.Validity.Validity GHC.Internal.Int.Int16
instance Data.Validity.Validity GHC.Internal.Int.Int32
instance Data.Validity.Validity GHC.Internal.Int.Int64
instance Data.Validity.Validity GHC.Internal.Int.Int8
instance Data.Validity.Validity GHC.Num.Integer.Integer
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Data.Monoid.Last a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Semigroup.Last a)
instance Data.Validity.Validity a => Data.Validity.Validity [a]
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Maybe.Maybe a)
instance Data.Validity.Validity GHC.Num.Natural.Natural
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Internal.Base.NonEmpty a)
instance Data.Validity.Validity GHC.Types.Ordering
instance (Data.Validity.Validity a, GHC.Classes.Ord a, GHC.Internal.Num.Num a, GHC.Internal.Real.Integral a) => Data.Validity.Validity (GHC.Internal.Real.Ratio a)
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 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 ()
instance Data.Validity.Validity Data.Validity.ValidationChain
instance Data.Validity.Validity GHC.Types.Word
instance Data.Validity.Validity GHC.Internal.Word.Word16
instance Data.Validity.Validity GHC.Internal.Word.Word32
instance Data.Validity.Validity GHC.Internal.Word.Word64
instance Data.Validity.Validity GHC.Internal.Word.Word8
