Generic.Random

Simple GHC.Generics-based arbitrary generators.

For more information:

• Generic.Random.Tutorial
• http://blog.poisson.chat/posts/2018-01-05-generic-random-tour.html
• https://byorgey.wordpress.com/2016/09/20/the-generic-random-library-part-1-simple-generic-arbitrary-instances/

Arbitrary implementations

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 fields of type [t] with listOf' arbitrary.

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 fields of type [t] with listOf' arbitrary.

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

Equivalent to genericArbitrary' uniform.

genericArbitraryU :: Gen a

N.B.: This replaces fields of type [t] with listOf' arbitrary.

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

genericArbitrary with explicit generators.

Example

genericArbitraryG customGens (17 % 19 % ())

where, for example to override generators for String and Int fields,

customGens :: GenList '[String, Int]
customGens =
  (filter (/= '\NUL') <$> arbitrary) :@
  (getNonNegative <$> arbitrary) :@
  Nil

Note on multiple matches

If the list contains multiple matching types for a field x of type a (i.e., either a or Field "x" a), the generator for the first match will be picked.

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.

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

General generic generator with custom options.

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.

Minimal complete definition

baseCase

Methods

baseCase :: Gen a

Generator of base cases.

Instances

BaseCaseSearching Nat a 0 => BaseCase a

Overlappable

Methods

baseCase :: Gen a

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)

Methods

(%) :: W (First' (Weights a)) -> 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)

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 => W (First' w) -> Prec' w -> w infixr 1

A binary constructor for building up trees of weights.

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

Uniform distribution.

Full options

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

Type-level options for GArbitrary.

Instances

HasGenerators (Options s g)

Methods

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

type SetGens g (Options s _g)

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

type GeneratorsOf (Options _s g)

type GeneratorsOf (Options _s g) = g

type SizingOf (Options s _g)

type SizingOf (Options s _g) = s

type SizedOpts = Options Sized ()

sizedOpts :: SizedOpts

Default options for sized generators.

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

sizedOptsDef :: SizedOptsDef

Default options overriding the list generator using listOf'.

type UnsizedOpts = Options Unsized ()

unsizedOpts :: UnsizedOpts

Default options for unsized generators.

data Sizing

Whether to decrease the size parameter before generating fields.

Constructors

Sized

Unsized

setSized :: Options s g -> Options Sized g

setUnsized :: Options s g -> Options Unsized g

data a :+ b infixr 1

Heterogeneous list of generators.

Constructors

a :+ b infixr 1

Instances

ArbitraryOr fg g sel a => ArbitraryOr fg ((:+) b g) sel a

Methods

arbitraryOr :: proxy sel -> fg -> (b :+ g) -> Gen a

ArbitraryOr fg ((:+) (Gen a) g) sel a

Methods

arbitraryOr :: proxy sel -> fg -> (Gen a :+ g) -> Gen a

ArbitraryOr fg fg (Nothing Symbol) a => ArbitraryOr fg ((:+) (Gen1 f) g) sel (f a)

Methods

arbitraryOr :: proxy sel -> fg -> (Gen1 f :+ g) -> Gen (f a)

ArbitraryOr fg ((:+) (Gen1_ k f) g) sel (f a)

Methods

arbitraryOr :: proxy sel -> fg -> (Gen1_ k f :+ g) -> Gen (f a)

ArbitraryOr fg ((:+) (FieldGen n a) g) (Just Symbol n) a

Methods

arbitraryOr :: proxy (Just Symbol n) -> fg -> (FieldGen n a :+ g) -> Gen a

newtype FieldGen (s :: Symbol) a

A generator which overrides a specific field named s.

Available only for base >= 4.9.

Constructors

FieldGen

Fields

• unFieldGen :: Gen a

Instances

ArbitraryOr fg ((:+) (FieldGen n a) g) (Just Symbol n) a

Methods

arbitraryOr :: proxy (Just Symbol n) -> fg -> (FieldGen n a :+ g) -> Gen a

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

Field constructor with the field name given via a proxy.

newtype Gen1 f

Generators for containers of kind * -> *, parameterized by the generator for each element.

Constructors

Gen1

Fields

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

Instances

ArbitraryOr fg fg (Nothing Symbol) a => ArbitraryOr fg ((:+) (Gen1 f) g) sel (f a)

Methods

arbitraryOr :: proxy sel -> fg -> (Gen1 f :+ g) -> Gen (f a)

newtype Gen1_ f

Generators for unary type constructors that are not containers.

Constructors

Gen1_

Fields

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

Instances

ArbitraryOr fg ((:+) (Gen1_ k f) g) sel (f a)

Methods

arbitraryOr :: proxy sel -> fg -> (Gen1_ k f :+ g) -> Gen (f a)

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

Public classes

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

Generic Arbitrary

Instances

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

class UniformWeight_ (Rep a) => GUniformWeight a

Derived uniform distribution of constructors for a.

Instances

UniformWeight_ (Rep a) => GUniformWeight 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.