-- 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
validate :: (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.Generics.Generic Data.Validity.ValidationChain
instance GHC.Classes.Eq Data.Validity.ValidationChain
instance GHC.Show.Show Data.Validity.ValidationChain
instance GHC.Generics.Generic Data.Validity.Validation
instance GHC.Classes.Eq Data.Validity.Validation
instance GHC.Show.Show Data.Validity.Validation
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Functor.Identity.Identity a)
instance Data.Validity.Validity (f a) => Data.Validity.Validity (Data.Semigroup.Internal.Alt f a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Semigroup.Internal.Dual a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Semigroup.First a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Semigroup.Last a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Monoid.First a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Monoid.Last a)
instance Data.Validity.Validity a => Data.Validity.Validity (Data.Functor.Const.Const a b)
instance Data.Validity.Validity Data.Validity.ValidationChain
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 (GHC.Base.NonEmpty a)
instance Data.Validity.Validity a => Data.Validity.Validity (GHC.Maybe.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.Int.Int8
instance Data.Validity.Validity GHC.Int.Int16
instance Data.Validity.Validity GHC.Int.Int32
instance Data.Validity.Validity GHC.Int.Int64
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.Num.Integer.Integer
instance Data.Validity.Validity GHC.Num.Natural.Natural
instance (Data.Validity.Validity a, GHC.Classes.Ord a, GHC.Num.Num a, GHC.Real.Integral a) => Data.Validity.Validity (GHC.Real.Ratio a)
instance Data.Fixed.HasResolution a => Data.Validity.Validity (Data.Fixed.Fixed a)
instance Data.Validity.Validity a => Data.Validity.GValidity (GHC.Generics.K1 GHC.Generics.R 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 GHC.Base.Semigroup Data.Validity.Validation
instance GHC.Base.Monoid Data.Validity.Validation
