Generic.Random.Internal.Generic

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.

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

genericArbitraryU :: Gen a

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

genericArbitrarySingle :: 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 Test.QuickCheck.listOf arbitrary (i.e., arbitrary for lists).

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.

genericArbitraryU with explicit generators. See also genericArbitraryG.

genericArbitrarySingle with explicit generators. See also genericArbitraryG.

genericArbitraryRec with explicit generators. See also genericArbitraryG.

General generic generator with custom options.

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

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

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

A smart constructor to specify a custom distribution. It can be omitted for the % operator is overloaded to insert it.

Uniform distribution.

Derived uniform distribution of constructors for a.

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

Setter for Options.

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

Infix flipped synonym for Options.

Like UnsizedOpts, but using coherent instances by default.

Like SizedOpts, but using coherent instances by default.

Coerce an Options value between types with the same representation.

Default options for unsized generators.

Default options for sized generators.

Default options overriding the list generator using listOf'.

Like unsizedOpts, but using coherent instances by default.

Like sizedOpts but using coherent instances by default.

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.

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

Match this generator incoherently when the COHERENT option is set.

Heterogeneous list of generators.

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#notelists.

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.

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.

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.

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 vectorOf that divides the size parameter by the length of the list.

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

Geometric distribution of parameter 1/(sqrt n + 1) (n >= 0).

Generic Arbitrary

Generic Arbitrary

Given a list of custom generators g :+ gs, find one that applies, or use Arbitrary a by default.

g and gs follow this little state machine:

          g,      gs | result
---------------------+-----------------------------
         (),      () | END
         (), g :+ gs | g, gs
         (),      g  | g, () when g is not (_ :+ _)
     g :+ h,      gs | g, h :+ gs
      Gen a,      gs | END if g matches, else ((), gs)
 FieldGen a,      gs | idem
ConstrGen a,      gs | idem
     Gen1 a,      gs | idem
    Gen1_ a,      gs | idem

Get the name contained in a Meta tag.