Generic.Random

GHC.Generics-based arbitrary generators.

Basic usage

data Foo = A | B | C  -- some generic data type
  deriving Generic

Derive instances of Arbitrary.

instance Arbitrary Foo where
  arbitrary = genericArbitrary uniform  -- give a distribution of constructors

Or derive standalone generators (the fields must still be instances of Arbitrary, or use custom generators).

genFoo :: Gen Foo
genFoo = genericArbitrary uniform

For more information:

• Generic.Random.Tutorial
• http://blog.poisson.chat/posts/2018-01-05-generic-random-tour.html

Arbitrary implementations

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

Arguments

:: GArbitrary UnsizedOpts a

=> Weights a

List of weights for every constructor

-> Gen a

Pick a constructor with a given distribution, and fill its fields with recursive calls to arbitrary.

Example

genericArbitrary (2 % 3 % 5 % ()) :: Gen a

Picks the first constructor with probability 2/10, the second with probability 3/10, the third with probability 5/10.

genericArbitraryU :: (GArbitrary UnsizedOpts a, GUniformWeight a) => Gen a

Pick every constructor with equal probability. Equivalent to genericArbitrary uniform.

genericArbitraryU :: Gen a

genericArbitrarySingle :: (GArbitrary UnsizedOpts a, Weights_ (Rep a) ~ L c0) => Gen a

arbitrary for types with one constructor. Equivalent to genericArbitraryU, with a stricter type.

genericArbitrarySingle :: Gen a

genericArbitraryRec

Arguments

:: GArbitrary SizedOptsDef a

=> Weights a

List of weights for every constructor

-> Gen a

Decrease size at every recursive call, but don't do anything different at size 0.

genericArbitraryRec (7 % 11 % 13 % ()) :: Gen a

N.B.: This replaces the generator for fields of type [t] with listOf' arbitrary instead of listOf arbitrary (i.e., arbitrary for lists).

genericArbitrary'

Arguments

:: (GArbitrary SizedOptsDef a, BaseCase a)

=> Weights a

List of weights for every constructor

-> Gen a

Decrease size to ensure termination for recursive types, looking for base cases once the size reaches 0.

genericArbitrary' (17 % 19 % 23 % ()) :: Gen a

N.B.: This replaces the generator for fields of type [t] with listOf' arbitrary instead of listOf arbitrary (i.e., arbitrary for lists).

genericArbitraryU' :: (GArbitrary SizedOptsDef a, BaseCase a, GUniformWeight a) => Gen a

Equivalent to genericArbitrary' uniform.

genericArbitraryU' :: Gen a

N.B.: This replaces the generator for fields of type [t] with listOf' arbitrary instead of listOf arbitrary (i.e., arbitrary for lists).

With custom generators

Note about incoherence

The custom generator feature relies on incoherent instances, which can lead to surprising behaviors for parameterized types.

Example

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.

genericArbitraryG :: GArbitrary (SetGens genList UnsizedOpts) a => genList -> Weights a -> Gen a

genericArbitrary with explicit generators.

Example

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)

Note on multiple matches

Multiple generators may match a given field: the first will be chosen.

genericArbitraryUG :: (GArbitrary (SetGens genList UnsizedOpts) a, GUniformWeight a) => genList -> Gen a

genericArbitraryU with explicit generators. See also genericArbitraryG.

genericArbitrarySingleG :: (GArbitrary (SetGens genList UnsizedOpts) a, Weights_ (Rep a) ~ L c0) => genList -> Gen a

genericArbitrarySingle with explicit generators. See also genericArbitraryG.

genericArbitraryRecG

Arguments

:: GArbitrary (SetGens genList SizedOpts) a

=> genList

-> Weights a

List of weights for every constructor

-> Gen a

genericArbitraryRec with explicit generators. See also genericArbitraryG.

Specifying finite distributions

data Weights a

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

Instances

WeightBuilder (Weights_ (Rep a)) => WeightBuilder' (Weights a)

Defined in Generic.Random.Internal.Generic

Methods

(%) :: forall (c :: Symbol). c ~ First' (Weights a) => W c -> Prec' (Weights a) -> Weights a

data W (c :: Symbol)

Type of a single weight, tagged with the name of the associated constructor for additional compile-time checking.

((9 :: W "Leaf") % (8 :: W "Node") % ())

Instances

Num (W c)

Defined in Generic.Random.Internal.Generic

Methods

(+) :: W c -> W c -> W c

(-) :: W c -> W c -> W c

(*) :: W c -> W c -> W c

negate :: W c -> W c

abs :: W c -> W c

signum :: W c -> W c

fromInteger :: Integer -> W c

(%) :: (WeightBuilder' w, c ~ First' w) => W c -> Prec' w -> w infixr 1

A binary constructor for building up trees of weights.

uniform :: UniformWeight_ (Rep a) => Weights a

Uniform distribution.

Custom generators

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 Gen, providing more ways to select the fields the generator than by simply comparing types:

• Gen a: override fields of type a;
• 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.

data a :+ b infixr 1

Heterogeneous list of generators.

Constructors

a :+ b infixr 1

Instances

FindGen 'Shift s b g a => FindGen 'Shift s () (b :+ g) a

Examine the next candidate

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy 'Shift, Proxy s, FullGenListOf s) -> () -> (b :+ g) -> Gen a

FindGen 'Shift s g (h :+ gs) a => FindGen 'Shift s (g :+ h) gs a

This can happen if the generators form a tree rather than a list, for whatever reason.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy 'Shift, Proxy s, FullGenListOf s) -> (g :+ h) -> gs -> Gen a

newtype FieldGen (s :: Symbol) a

Custom generator for record fields named s.

If there is a field named s with a different type, this will result in a type error.

Constructors

FieldGen

Fields

• unFieldGen :: Gen a

Instances

a ~ a' => FindGen ('MatchCoh 'True) s (FieldGen sn a) gs a'

Matching custom generator for field s.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('MatchCoh 'True), Proxy s, FullGenListOf s) -> FieldGen sn a -> gs -> Gen a'

a ~ a' => FindGen ('Match 'INCOHERENT) ('S _fg _coh '(con, i, 'Just s)) (FieldGen s a) gs a'

Matching custom generator for field s.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('Match 'INCOHERENT), Proxy ('S _fg _coh '(con, i, 'Just s)), FullGenListOf ('S _fg _coh '(con, i, 'Just s))) -> FieldGen s a -> gs -> Gen a'

fieldGen :: proxy s -> Gen a -> FieldGen s a

FieldGen constructor with the field name given via a proxy.

newtype ConstrGen (c :: Symbol) (i :: Nat) a

Custom generator for the i-th field of the constructor named c. Fields are 0-indexed.

Constructors

ConstrGen

Fields

• unConstrGen :: Gen a

Instances

a ~ a' => FindGen ('MatchCoh 'True) s (ConstrGen c i a) gs a'

Matching custom generator for i-th field of constructor c.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('MatchCoh 'True), Proxy s, FullGenListOf s) -> ConstrGen c i a -> gs -> Gen a'

a ~ a' => FindGen ('Match 'INCOHERENT) ('S _fg _coh '('Just c, i, s)) (ConstrGen c i a) gs a'

Matching custom generator for i-th field of constructor c.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('Match 'INCOHERENT), Proxy ('S _fg _coh '('Just c, i, s)), FullGenListOf ('S _fg _coh '('Just c, i, s))) -> ConstrGen c i a -> gs -> Gen a'

constrGen :: proxy '(c, i) -> Gen a -> ConstrGen c i a

ConstrGen constructor with the constructor name given via a proxy.

newtype Gen1 f

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.

Constructors

Gen1

Fields

• unGen1 :: forall a. Gen a -> Gen (f a)

Instances

(f x ~ a', FindGen 'Shift ('S fg coh (DummySel :: (Maybe Symbol, Nat, Maybe Symbol))) () fg x) => FindGen ('MatchCoh 'True) ('S fg coh _sel) (Gen1 f) gs a'

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('MatchCoh 'True), Proxy ('S fg coh _sel), FullGenListOf ('S fg coh _sel)) -> Gen1 f -> gs -> Gen a'

FindGen 'Shift ('S fg coh (DummySel :: (Maybe Symbol, Nat, Maybe Symbol))) () fg a => FindGen ('Match 'INCOHERENT) ('S fg coh _sel) (Gen1 f) gs (f a)

Matching custom generator for container f. Start the search for containee a, discarding field information.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('Match 'INCOHERENT), Proxy ('S fg coh _sel), FullGenListOf ('S fg coh _sel)) -> Gen1 f -> gs -> Gen (f a)

newtype Gen1_ f

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.

Constructors

Gen1_

Fields

• unGen1_ :: forall a. Gen (f a)

Instances

f x ~ a' => FindGen ('MatchCoh 'True) s (Gen1_ f) gs a'

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('MatchCoh 'True), Proxy s, FullGenListOf s) -> Gen1_ f -> gs -> Gen a'

FindGen ('Match 'INCOHERENT) s (Gen1_ f) gs (f a)

Matching custom generator for non-container f.

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy ('Match 'INCOHERENT), Proxy s, FullGenListOf s) -> Gen1_ f -> gs -> Gen (f a)

Helpful combinators

listOf' :: Gen a -> Gen [a]

An alternative to listOf that divides the size parameter by the length of the list. The length follows a geometric distribution of parameter 1/(sqrt size + 1).

listOf1' :: Gen a -> Gen [a]

An alternative to 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).

vectorOf' :: Int -> Gen a -> Gen [a]

An alternative to vectorOf that divides the size parameter by the length of the list.

Base cases for recursive types

withBaseCase :: Gen a -> Gen a -> Gen a

Run the first generator if the size is positive. Run the second if the size is zero.

defaultGen `withBaseCase` baseCaseGen

class BaseCase a where

Custom instances can override the default behavior.

Methods

baseCase :: Gen a

Generator of base cases.

Instances

BaseCaseSearching a 0 => BaseCase a

Overlappable

Defined in Generic.Random.Internal.BaseCase

Methods

baseCase :: Gen a

Full options

data Options (c :: Coherence) (s :: Sizing) (genList :: Type)

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 (<+)).

Instances

HasGenerators (Options c s g)

Defined in Generic.Random.Internal.Generic

Methods

generators :: Options c s g -> GeneratorsOf (Options c s g)

type SetOptions (g :: Type) (Options c s _g)

Defined in Generic.Random.Internal.Generic

type SetOptions (g :: Type) (Options c s _g) = Options c s g

type SetOptions (c :: Coherence) (Options _c s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (c :: Coherence) (Options _c s g) = Options c s g

type SetOptions (s :: Sizing) (Options c _s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (s :: Sizing) (Options c _s g) = Options c s g

type SetGens g (Options c s _g)

Defined in Generic.Random.Internal.Generic

type SetGens g (Options c s _g) = Options c s g

type GeneratorsOf (Options _c _s g)

Defined in Generic.Random.Internal.Generic

type GeneratorsOf (Options _c _s g) = g

type CoherenceOf (Options c _s _g)

Defined in Generic.Random.Internal.Generic

type CoherenceOf (Options c _s _g) = c

type SetUnsized (Options c s g)

Defined in Generic.Random.Internal.Generic

type SetUnsized (Options c s g) = Options c 'Unsized g

type SetSized (Options c s g)

Defined in Generic.Random.Internal.Generic

type SetSized (Options c s g) = Options c 'Sized g

type SizingOf (Options _c s _g)

Defined in Generic.Random.Internal.Generic

type SizingOf (Options _c s _g) = s

genericArbitraryWith :: GArbitrary opts a => opts -> Weights a -> Gen a

General generic generator with custom options.

Setters

type family SetOptions (x :: k) (o :: Type) :: Type

Setter for Options.

This subsumes the other setters: SetSized, SetUnsized, SetGens.

Since: 1.4.0.0

Instances

type SetOptions (g :: Type) (Options c s _g)

Defined in Generic.Random.Internal.Generic

type SetOptions (g :: Type) (Options c s _g) = Options c s g

type SetOptions (c :: Coherence) (Options _c s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (c :: Coherence) (Options _c s g) = Options c s g

type SetOptions (s :: Sizing) (Options c _s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (s :: Sizing) (Options c _s g) = Options c s g

type (<+) o x = SetOptions x o infixl 1

Infix flipped synonym for Options.

Since: 1.4.0.0

setOpts :: forall x o. Coercible o (SetOptions x o) => o -> SetOptions x o

Coerce an Options value between types with the same representation.

Since: 1.4.0.0

Size modifiers

data Sizing

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.

Constructors

Sized

Decrease the size parameter when running generators for fields

Unsized

Don't touch the size parameter

Instances

type SetOptions (s :: Sizing) (Options c _s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (s :: Sizing) (Options c _s g) = Options c s g

type family SetSized (o :: Type) :: Type

Instances

type SetSized (Options c s g)

Defined in Generic.Random.Internal.Generic

type SetSized (Options c s g) = Options c 'Sized g

type family SetUnsized (o :: Type) :: Type

Instances

type SetUnsized (Options c s g)

Defined in Generic.Random.Internal.Generic

type SetUnsized (Options c s g) = Options c 'Unsized g

setSized :: Options c s g -> Options c 'Sized g

setUnsized :: Options c s g -> Options c 'Unsized g

Custom generators

type family SetGens (g :: Type) opts

Instances

type SetGens g (Options c s _g)

Defined in Generic.Random.Internal.Generic

type SetGens g (Options c s _g) = Options c s g

setGenerators :: genList -> Options c s g0 -> Options c s genList

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

Coherence options

data Coherence

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.

Details

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:

• https://downloads.haskell.org/ghc/latest/docs/html/users_guide/glasgow_exts.html#overlapping-instances

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

Since: 1.4.0.0

Constructors

INCOHERENT

Match custom generators incoherently.

COHERENT

Match custom generators coherently by default (can be manually bypassed with Incoherent).

Instances

type SetOptions (c :: Coherence) (Options _c s g)

Defined in Generic.Random.Internal.Generic

type SetOptions (c :: Coherence) (Options _c s g) = Options c s g

newtype Incoherent g

Match this generator incoherently when the INCOHERENT option is set.

Constructors

Incoherent g

Instances

FindGen ('Match 'INCOHERENT) s g gs a => FindGen 'Shift s (Incoherent g) gs a

Defined in Generic.Random.Internal.Generic

Methods

findGen :: (Proxy 'Shift, Proxy s, FullGenListOf s) -> Incoherent g -> gs -> Gen a

Common options

type SizedOpts = Options 'INCOHERENT 'Sized ()

sizedOpts :: SizedOpts

Default options for sized generators.

type SizedOptsDef = Options 'INCOHERENT 'Sized (Gen1 [] :+ ())

sizedOptsDef :: SizedOptsDef

Default options overriding the list generator using listOf'.

type UnsizedOpts = Options 'INCOHERENT 'Unsized ()

unsizedOpts :: UnsizedOpts

Default options for unsized generators.

Advanced options

See Coherence

type CohUnsizedOpts = Options 'COHERENT 'Unsized ()

Like UnsizedOpts, but using coherent instances by default.

Since: 1.4.0.0

cohUnsizedOpts :: CohUnsizedOpts

Like unsizedOpts, but using coherent instances by default.

type CohSizedOpts = Options 'COHERENT 'Sized ()

Like SizedOpts, but using coherent instances by default.

Since: 1.4.0.0

cohSizedOpts :: CohSizedOpts

Like sizedOpts but using coherent instances by default.

Generic classes

class (Generic a, GA opts (Rep a)) => GArbitrary opts a

Generic Arbitrary

Instances

(Generic a, GA opts (Rep a)) => GArbitrary opts a

Defined in Generic.Random.Internal.Generic

class UniformWeight_ (Rep a) => GUniformWeight a

Derived uniform distribution of constructors for a.

Instances

UniformWeight_ (Rep a) => GUniformWeight a

Defined in Generic.Random.Internal.Generic