:: a typeCtrl KGHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27
Modulegeneric-random-1.5.0.1Haskell2010
GHC.Generics-based Test.QuickCheck.arbitrary generators.
{-# LANGUAGE DeriveGeneric #-}
data Foo = A | B | C -- some generic data type
deriving Generic
Derive instances of Test.QuickCheck.Arbitrary.
instance Arbitrary Foo where
arbitrary = genericArbitrary uniform -- Give a distribution of constructors.
shrink = Test.QuickCheck.genericShrink -- Generic shrinking is provided by the QuickCheck library.
Or derive standalone generators (the fields must still be instances of
Test.QuickCheck.Arbitrary, or use custom generators).
genFoo :: Gen Foo
genFoo = genericArbitrary uniform
DerivingVia{-# LANGUAGE DerivingVia, TypeOperators #-}
data Foo = A | B | C
deriving Generic
deriving Arbitrary via (GenericArbitraryU `AndShrinking' Foo)
For more information:
The suffixes for the variants have the following meanings:
U: pick constructors with uniform distribution (equivalent to
passing uniform to the non-U variant).
Single: restricted to types with a single constructor.
G: with custom generators.
Rec: decrease the size at every recursive call (ensuring termination
for (most) recursive types).
': automatic discovery of "base cases" when size reaches 0.
genericArbitrary :: GArbitrary UnsizedOpts a=> Weights aList of weights for every constructor
-> Gen aPick a constructor with a given distribution, and fill its fields with recursive calls to arbitrary.
genericArbitrary (2 % 3 % 5 % ()) :: Gen aPicks the first constructor with probability 2/10,
the second with probability 3/10, the third with probability 5/10.
Pick every constructor with equal probability.
Equivalent to genericArbitrary uniform.
genericArbitraryU :: Gen aarbitrary for types with one constructor. Equivalent to genericArbitraryU, with a stricter type.
genericArbitrarySingle :: Gen agenericArbitraryRec :: GArbitrary SizedOptsDef a=> Weights aList of weights for every constructor
-> Gen aDecrease size at every recursive call, but don't do anything different at size 0.
genericArbitraryRec (7 % 11 % 13 % ()) :: Gen aN.B.: This replaces the generator for fields of type [t] with
listOf' arbitrary instead of Test.QuickCheck.listOf arbitraryarbitrary for
lists).
genericArbitrary' :: (GArbitrary SizedOptsDef a, BaseCase a)=> Weights aList of weights for every constructor
-> Gen aDecrease size to ensure termination for recursive types, looking for base cases once the size reaches 0.
genericArbitrary' (17 % 19 % 23 % ()) :: Gen aN.B.: This replaces the generator for fields of type [t] with
Test.QuickCheck.listOf' arbitrarylistOf arbitrary (i.e., arbitrary for
lists).
Equivalent to genericArbitrary' uniform.
genericArbitraryU' :: Gen aN.B.: This replaces the generator for fields of type [t] with
Test.QuickCheck.listOf' arbitrarylistOf arbitrary (i.e., arbitrary for
lists).
The custom generator feature relies on incoherent instances, which can lead to surprising behaviors for parameterized types.
For example, here is a pair type and a custom generator of Int (always
generating 0).
data Pair a b = Pair a b
deriving (Generic, Show)
customGen :: Gen Int
customGen = pure 0
The following two ways of defining a generator of Pair Int Int are
not equivalent.
The first way is to use genericArbitrarySingleG to define a
Gen (Pair a b) parameterized by types a and b, and then
specialize it to Gen (Pair Int Int).
In this case, the customGen will be ignored.
genPair :: (Arbitrary a, Arbitrary b) => Gen (Pair a b)
genPair = genericArbitrarySingleG customGen
genPair' :: Gen (Pair Int Int)
genPair' = genPair
-- Will generate nonzero pairs
The second way is to define Gen (Pair Int Int) directly using
genericArbitrarySingleG (as if we inlined genPair in genPair'
above.
Then the customGen will actually be used.
genPair2 :: Gen (Pair Int Int)
genPair2 = genericArbitrarySingleG customGen
-- Will only generate (Pair 0 0)
In other words, the decision of whether to use a custom generator
is done by comparing the type of the custom generator with the type of
the field only in the context where genericArbitrarySingleG is being
used (or any other variant with a G suffix).
In the first case above, those fields have types a and b, which are
not equal to Int (or rather, there is no available evidence that they
are equal to Int, even if they could be instantiated as Int later).
In the second case, they both actually have type Int.
genericArbitrary with explicit generators.
genericArbitraryG customGens (17 % 19 % ())where, the generators for String and Int fields are overridden as follows, for example:
customGens :: Gen String :+ Gen Int
customGens =
(filter (/= 'NUL') <$> arbitrary) :+
(getNonNegative <$> arbitrary)
Multiple generators may match a given field: the first will be chosen.
genericArbitraryU with explicit generators. See also genericArbitraryG.
genericArbitrarySingle with explicit generators. See also genericArbitraryG.
genericArbitraryRecG :: GArbitrary (SetGens genList SizedOpts) a=> genList-> Weights aList of weights for every constructor
-> Gen agenericArbitraryRec with explicit generators. See also genericArbitraryG.
Trees of weights assigned to constructors of type a,
rescaled to obtain a probability distribution.
Two ways of constructing them.
(x1 % x2 % ... % xn % ()) :: Weights a
uniform :: Weights a
Using (%), there must be exactly as many weights as
there are constructors.
uniform is equivalent to (1 % ... % 1 % ())
(automatically fills out the right number of 1s).
WeightBuilder (Weights_ (Rep a)) => WeightBuilder' (Weights a)Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericA binary constructor for building up trees of weights.
Uniform distribution.
Custom generators can be specified in a list constructed with (:+),
and passed to functions such as genericArbitraryG to override how certain
fields are generated.
Example:
customGens :: Gen String :+ Gen Int
customGens =
(filter (/= 'NUL') <$> arbitrary) :+
(getNonNegative <$> arbitrary)
There are also different types of generators, other than Test.QuickCheck.Gen, providing
more ways to select the fields the generator than by simply comparing types:
Test.QuickCheck.Gen aa;
Gen1 f: override fields of type f x for some x, requiring a generator for x;
Gen1_ f: override fields of type f x for some x, not requiring a generator for x;
FieldGen s a: override record fields named s, which must have type a;
ConstrGen c i a: override the field at index i of constructor c,
which must have type a (0-indexed);
Multiple generators may match a given field: the first, leftmost generator in the list will be chosen.
Heterogeneous list of generators.
a :+ binfixr 1FindGen 'Shift s b g a => FindGen 'Shift s () (b :+ g) aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericExamine the next candidate
FindGen 'Shift s g (h :+ gs) a => FindGen 'Shift s (g :+ h) gs aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericThis can happen if the generators form a tree rather than a list, for whatever reason.
(TypeLevelGenList a, TypeLevelGenList b) => TypeLevelGenList (a :+ b)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViatype TypeLevelGenList' (a :+ b) = TypeLevelGenList' a :+ TypeLevelGenList' bDefined in generic-random-1.5.0.1 · Generic.Random.DerivingViaCustom generator for record fields named s.
If there is a field named s with a different type,
this will result in a type error.
FieldGenunFieldGen :: Gen aa ~ a' => FindGen ('MatchCoh 'True) s (FieldGen sn a) gs a'Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatching custom generator for field s.
a ~ a' => FindGen ('Match 'INCOHERENT) ('S _fg _coh '(con, i, 'Just s)) (FieldGen s a) gs a'Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatching custom generator for field s.
FieldGen constructor with the field name given via a proxy.
Custom generator for the i-th field of the constructor named c.
Fields are 0-indexed.
ConstrGenunConstrGen :: Gen aa ~ a' => FindGen ('MatchCoh 'True) s (ConstrGen c i a) gs a'Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatching custom generator for i-th field of constructor c.
a ~ a' => FindGen ('Match 'INCOHERENT) ('S _fg _coh '('Just c, i, s)) (ConstrGen c i a) gs a'Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatching custom generator for i-th field of constructor c.
ConstrGen constructor with the constructor name given via a proxy.
Custom generators for "containers" of kind Type -> Type, parameterized
by the generator for "contained elements".
A custom generator Gen1 f will be used for any field whose type has the
form f x, requiring a generator of x. The generator for x will be
constructed using the list of custom generators if possible, otherwise
an instance Arbitrary x will be required.
(f x ~ a', FindGen 'Shift ('S fg coh DummySel) () fg x) => FindGen ('MatchCoh 'True) ('S fg coh _sel) (Gen1 f) gs a'Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericFindGen 'Shift ('S fg coh DummySel) () fg a => FindGen ('Match 'INCOHERENT) ('S fg coh _sel) (Gen1 f) gs (f a)Defined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatching custom generator for container f. Start the search for containee a,
discarding field information.
Custom generators for unary type constructors that are not "containers",
i.e., which don't require a generator of a to generate an f a.
A custom generator Gen1_ f will be used for any field whose type has the
form f x.
An alternative to Test.QuickCheck.listOf that divides the size parameter
by the length of the list.
The length follows a geometric distribution of parameter
1/(sqrt size + 1).
An alternative to Test.QuickCheck.listOf1 (nonempty lists) that divides
the size parameter by the length of the list.
The length (minus one) follows a geometric distribution of parameter
1/(sqrt size + 1).
An alternative to vectorOf that divides the size parameter by the length of the list.
Run the first generator if the size is positive. Run the second if the size is zero.
defaultGen `withBaseCase` baseCaseGenBaseCaseSearching a 0
=> BaseCase aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.BaseCaseOverlappable
Type-level options for GArbitrary.
Note: it is recommended to avoid referring to the Options type
explicitly in code, as the set of options may change in the future.
Instead, use the provided synonyms (UnsizedOpts, SizedOpts, SizedOptsDef)
and the setter SetOptions (abbreviated as (<+)).
HasGenerators (Options c s g)Defined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetGens g (Options c s _g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetOptions c (Options _c s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetOptions g (Options c s _g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetOptions s (Options c _s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetSized (Options c s g) = Options c 'Sized gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetUnsized (Options c s g) = Options c 'Unsized gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype CoherenceOf (Options c _s _g) = cDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype GeneratorsOf (Options _c _s g) = gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SizingOf (Options _c s _g) = sDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericGeneral generic generator with custom options.
Setter for Options.
This subsumes the other setters: SetSized, SetUnsized, SetGens.
type SetOptions c (Options _c s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetOptions g (Options c s _g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetOptions s (Options c _s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericInfix flipped synonym for Options.
Coerce an Options value between types with the same representation.
Whether to decrease the size parameter before generating fields.
The Sized option makes the size parameter decrease in the following way: - Constructors with one field decrease the size parameter by 1 to generate that field. - Constructors with more than one field split the size parameter among all fields; the size parameter is rounded down to then be divided equally.
type SetOptions s (Options c _s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.Generictype SetUnsized (Options c s g) = Options c 'Unsized gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericDefine the set of custom generators.
Note: for recursive types which can recursively appear inside lists or other containers, you may want to include a custom generator to decrease the size when generating such containers.
See also the Note about lists in Generic.Random.Tutorial#notelists.
For custom generators to work with parameterized types, incoherent instances must be used internally. In practice, the resulting behavior is what users want 100% of the time, so you should forget this option even exists.
The default configuration of generic-random does a decent job if we trust GHC implements precisely the instance resolution algorithm as described in the GHC manual:
While that assumption holds in practice, it is overly context-dependent (to know the context leading to a particular choice, we must replay the whole resolution algorithm). In particular, this algorithm may find one solution, but it is not guaranteed to be unique: the behavior of the program is dependent on implementation details.
An notable property to consider of an implicit type system (such as type classes) is coherence: the behavior of the program is stable under specialization.
This sounds nice on paper, but actually leads to surprising behavior for generic implementations with parameterized types, such as generic-random.
To address that, the coherence property can be relaxd by users, by explicitly allowing some custom generators to be chosen incoherently. With appropriate precautions, it is possible to ensure a weaker property which nevertheless helps keep type inference predictable: when a solution is found, it is unique. (This is assuredly weaker, i.e., is not stable under specialization.)
INCOHERENTMatch custom generators incoherently.
COHERENTMatch custom generators coherently by default (can be manually bypassed with Incoherent).
type SetOptions c (Options _c s g) = Options c s gDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericMatch this generator incoherently when the COHERENT option is set.
FindGen ('Match 'INCOHERENT) s g gs a => FindGen 'Shift s (Incoherent g) gs aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericDefault options for sized generators.
Default options overriding the list generator using listOf'.
Default options for unsized generators.
See Coherence
Like UnsizedOpts, but using coherent instances by default.
Like unsizedOpts, but using coherent instances by default.
Like SizedOpts, but using coherent instances by default.
Like sizedOpts but using coherent instances by default.
Generic Arbitrary
(Generic a, GA opts (Rep a)) => GArbitrary opts aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericDerived uniform distribution of constructors for a.
UniformWeight_ (Rep a) => GUniformWeight aDefined in generic-random-1.5.0.1 · Generic.Random.Internal.GenericThese newtypes correspond to the variants of genericArbitrary above.
Pick a constructor with a given distribution, and fill its fields with recursive calls to arbitrary.
data X = ...
deriving Arbitrary via (GenericArbitrary '[2, 3, 5] X)Picks the first constructor with probability 2/10,
the second with probability 3/10, the third with probability 5/10.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitrary.
Eq a => Eq (GenericArbitrary weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitrary weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary UnsizedOpts a, TypeLevelWeights' weights a) => Arbitrary (GenericArbitrary weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaPick every constructor with equal probability.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryU.
Eq a => Eq (GenericArbitraryU a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryU a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary UnsizedOpts a, GUniformWeight a) => Arbitrary (GenericArbitraryU a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaarbitrary for types with one constructor.
Equivalent to GenericArbitraryU, with a stricter type.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitrarySingle.
Eq a => Eq (GenericArbitrarySingle a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitrarySingle a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary UnsizedOpts a, Weights_ (Rep a) ~ L c0) => Arbitrary (GenericArbitrarySingle a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaDecrease size at every recursive call, but don't do anything different at size 0.
data X = ...
deriving Arbitrary via (GenericArbitraryRec '[2, 3, 5] X)N.B.: This replaces the generator for fields of type [t] with
listOf' arbitrary instead of Test.QuickCheck.listOf arbitraryarbitrary for
lists).
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryRec.
Eq a => Eq (GenericArbitraryRec weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryRec weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary SizedOptsDef a, TypeLevelWeights' weights a) => Arbitrary (GenericArbitraryRec weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaGenericArbitrary with explicit generators.
data X = ...
deriving Arbitrary via (GenericArbitraryG CustomGens '[2, 3, 5] X)where, for example, custom generators to override String and Int fields might look as follows:
type CustomGens = CustomString :+ CustomInt
Multiple generators may match a given field: the first will be chosen.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryG.
Eq a => Eq (GenericArbitraryG genList weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryG genList weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary (SetGens genList UnsizedOpts) a, GUniformWeight a, TypeLevelWeights' weights a, TypeLevelGenList genList', genList ~ TypeLevelGenList' genList') => Arbitrary (GenericArbitraryG genList' weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaGenericArbitraryU with explicit generators. See also GenericArbitraryG.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryUG.
Eq a => Eq (GenericArbitraryUG genList a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryUG genList a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary (SetGens genList UnsizedOpts) a, GUniformWeight a, TypeLevelGenList genList', genList ~ TypeLevelGenList' genList') => Arbitrary (GenericArbitraryUG genList' a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViagenericArbitrarySingle with explicit generators. See also GenericArbitraryG.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitrarySingleG.
Eq a => Eq (GenericArbitrarySingleG genList a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitrarySingleG genList a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary (SetGens genList UnsizedOpts) a, Weights_ (Rep a) ~ L c0, TypeLevelGenList genList', genList ~ TypeLevelGenList' genList') => Arbitrary (GenericArbitrarySingleG genList' a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViagenericArbitraryRec with explicit generators. See also genericArbitraryG.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryRecG.
Eq a => Eq (GenericArbitraryRecG genList weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryRecG genList weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary (SetGens genList SizedOpts) a, TypeLevelWeights' weights a, TypeLevelGenList genList', genList ~ TypeLevelGenList' genList') => Arbitrary (GenericArbitraryRecG genList' weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaGeneral generic generator with custom options.
This newtype does no shrinking. To add generic shrinking, use AndShrinking.
Uses genericArbitraryWith.
Eq a => Eq (GenericArbitraryWith opts weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (GenericArbitraryWith opts weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(GArbitrary opts a, TypeLevelWeights' weights a, TypeLevelOpts opts', opts ~ TypeLevelOpts' opts') => Arbitrary (GenericArbitraryWith opts' weights a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaAdd generic shrinking to a newtype wrapper for Arbitrary, using genericShrink.
data X = ...
deriving Arbitrary via (GenericArbitrary '[1,2,3] `AndShrinking' X)
Equivalent to:
instance Arbitrary X where
arbitrary = genericArbitrary (1 % 2 % 3 % ())
shrink = genericShrink
Eq a => Eq (AndShrinking f a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViaShow a => Show (AndShrinking f a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(Arbitrary (f a), Coercible (f a) a, Generic a, RecursivelyShrink (Rep a), GSubterms (Rep a) a) => Arbitrary (AndShrinking f a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViatype family TypeLevelGenList' (a :: k)toGenList :: Proxy a -> TypeLevelGenList' aArbitrary a => TypeLevelGenList (Gen a)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingVia(TypeLevelGenList a, TypeLevelGenList b) => TypeLevelGenList (a :+ b)Defined in generic-random-1.5.0.1 · Generic.Random.DerivingViatype family TypeLevelOpts' (a :: k)toOpts :: Proxy a -> TypeLevelOpts' a