Data.GenValidity

A class of types for which valid values can be generated to be valid.

How to instantiate GenValid

Step 1: Try to instantiate GenValid without overriding any functions. It is possible that, if few values are valid or if validity checking is expensive, the resulting generator is too slow. In that case, go to Step 2.

Step 2: Consider using genValidStructurallyWithoutExtraChecking and shrinkValidStructurallyWithoutExtraFiltering to speed up generation. This only works if your type has a derived or trivial Validity instance.

Step 3: If that still is not fast enough, consider writing your own generator and shrinking function. Make sure to generate any possible valid value, but only valid values.

A note about Arbitrary

If you also write Arbitrary instances for GenValid types, it may be best to simply use

instance Arbitrary A where
  arbitrary = genValid
  shrink = shrinkValid

Generate a valid value by generating all the sub parts using the Generic instance, and trying that until a valid value has been generated

genValidStructurally = genValidStructurallyWithoutExtraChecking `suchThat` isValid

This is probably the function that you are looking for. If you do use this function to override genValid, you probably also want to use shrinkValidStructurally to override shrinkValid.

Generate a valid value by generating all the sub parts using the Generic instance,

This generator is _not_ guaranteed to generate a valid value.

This is probably _not_ the function that you are looking for when overriding genValid _unless_ the type in question has no _extra_ validity constraints on top of the validity of its sub parts.

Shrink a term to any of its immediate valid subterms, and also recursively shrink all subterms, and then filtering out the results that are not valid.

shrinkValidStructurally = filter isValid . shrinkValidStructurallyWithoutExtraFiltering

This is probably the function that you are looking for.

Shrink a term to any of its immediate valid subterms, and also recursively shrink all subterms.

This shrinking function is _not_ guaranteed to shrink to valid values.

This is probably _not_ the function that you are looking for when overriding shrinkValid _unless_ the type in question has no _extra_ validity constraints on top of the validity of its sub parts.

A class of types that have additional invariants defined upon them

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

Right identity

x <> mempty = x

Left identity

mempty <> x = x

Associativity

x <> (y <> z) = (x <> y) <> z

(

Semigroup

law)

Concatenation

mconcat = foldr (<>) mempty

You can alternatively define mconcat instead of mempty, in which case the laws are:

Unit

mconcat (pure x) = x

Multiplication

mconcat (join xss) = mconcat (fmap mconcat xss)

Subclass

mconcat (toList xs) = sconcat xs

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 newtypes and make those instances of Monoid, e.g. Data.Semigroup.Sum and Data.Semigroup.Product.

NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

The class of semigroups (types with an associative binary operation).

Instances should satisfy the following:

Associativity

x <> (y <> z) = (x <> y) <> z

You can alternatively define sconcat instead of (<>), in which case the laws are:

Unit

sconcat (pure x) = x

Multiplication

sconcat (join xss) = sconcat (fmap sconcat xss)

Check whether a value is valid.

The result of validating a value.

mempty means the value was valid.

This type intentionally doesn't have a Validity instance to make sure you can never accidentally use annotate or delve twice.

Declare a sub-part as a necessary part for validation, and annotate it with a name.

Example:

validate (a, b) =
    mconcat
        [ annotate a "The first element of the tuple"
        , annotate b "The second element of the tuple"
        ]

Check that a given invariant holds.

The given string should describe the invariant, not the violation.

Example:

check (x < 5) "x is strictly smaller than 5"

instead of

check (x < 5) "x is greater than 5"

validate a given value.

This function returns either all the reasons why the given value is invalid, in the form of a list of ValidationChains, or it returns Right with the input value, as evidence that it is valid.

Note: You may want to use prettyValidation instead, if you want to display these ValidationChains to a user.

Construct a valid element from an unchecked element

Construct a valid element from an unchecked element, throwing error on invalid elements.

check, but with the arguments flipped

Decorate a validation with a location

Decorate a piecewise validation of a list with their location in the list

decorateList, but specifically for Strings

decorateString = decorateList

annotate, but with the arguments flipped.

Construct a trivially invalid Validation

Example:

data Wrong
    = Wrong
    | Fine
    deriving (Show, Eq)

instance Validity Wrong where
    validate w =
        case w of
            Wrong -> invalid "Wrong"
            Fine -> valid

Check whether a value is not valid.

isInvalid = not . isValid

Validate a given value

This function will return a nice error if the value is invalid. It will return the original value in Right if it was valid, as evidence that it has been validated.

Render a Validation in a somewhat pretty way.

This function will return Nothing if the Validation concerned a valid value.

Declare any value to be valid in validation

trivialValidation a = seq a mempty

Check if a Validation concerns a valid value.

All immediate validSubterms of a term.