Up

# ModuleG = Q.Generator

### Signature

type 'a t = 'a Q.gen

An `'a t` a generates values of type `'a` with a specific probability distribution.

type 'a obs
include Monad.S with type 'a t := 'a t
type 'a t
include Monad_intf.S_without_syntax with type 'a t := 'a t
type 'a t

A monad is an abstraction of the concept of sequencing of computations. A value of type 'a monad represents a computation that returns a value of type 'a.

include Monad_intf.Infix with type 'a t := 'a t
type 'a t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t

`t >>= f` returns a computation that sequences the computations represented by two monad elements. The resulting computation first does `t` to yield a value `v`, and then runs the computation returned by `f v`.

val (>>|) : 'a t -> ('a -> 'b) -> 'b t

`t >>| f` is `t >>= (fun a -> return (f a))`.

val bind : 'a t -> ('a -> 'b t) -> 'b t

`bind t f` = `t >>= f`

val return : 'a -> 'a t

`return v` returns the (trivial) computation that returns v.

val map : 'a t -> f:('a -> 'b) -> 'b t

`map t ~f` is t >>| f.

val join : 'a t t -> 'a t

`join t` is `t >>= (fun t' -> t')`.

val ignore_m : 'a t -> unit t

`ignore_m t` is `map t ~f:(fun _ -> ())`. `ignore_m` used to be called `ignore`, but we decided that was a bad name, because it shadowed the widely used `Pervasives.ignore`. Some monads still do `let ignore = ignore_m` for historical reasons.

val all : 'a t list -> 'a list t
val all_ignore : unit t list -> unit t
include Monad_intf.Syntax with type 'a t := 'a t
type 'a t
module Let_syntax : sig .. end
val singleton : 'a -> 'a t
val doubleton : 'a -> 'a -> 'a t
val of_list : 'a list -> 'a t

Produce any of the given values, weighted equally.

`of_list [ v1 ; ... ; vN ] = union [ singleton v1 ; ... ; singleton vN ]`

val union : 'a t list -> 'a t

Combine arbitary generators, weighted equally.

` union [ g1 ; ... ; gN ] = weighted_union [ (1.0, g1) ; ... ; (1.0, gN) ] `

val of_sequence : ?p:float -> 'a Sequence.t -> 'a t

Generator for the values from a potentially infinite sequence. Chooses each value with probability `p`, or continues with probability `1-p`. Defaults to `p=0.25`.

val tuple2 : 'a t -> 'b t -> ('a * 'b) t
val tuple3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
val tuple4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t
val tuple5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('a * 'b * 'c * 'd * 'e) t
val tuple6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('a * 'b * 'c * 'd * 'e * 'f) t
val variant2 : 'a t -> 'b t -> [
| `A of 'a
| `B of 'b
] t
val variant3 : 'a t -> 'b t -> 'c t -> [
| `A of 'a
| `B of 'b
| `C of 'c
] t
val variant4 : 'a t -> 'b t -> 'c t -> 'd t -> [
| `A of 'a
| `B of 'b
| `C of 'c
| `D of 'd
] t
val variant5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> [
| `A of 'a
| `B of 'b
| `C of 'c
| `D of 'd
| `E of 'e
] t
val variant6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> [
| `A of 'a
| `B of 'b
| `C of 'c
| `D of 'd
| `E of 'e
| `F of 'f
] t
val size : int t

`size` produces a geometric distribution (think "radioactive decay") starting at 0 and increasing with probability 0.75. It produces natural numbers and is weighted toward low values, making it a good default for, e.g., data structure sizes.

val fn : ?branching_factor:int t -> 'a obs -> 'b t -> ('a -> 'b) t

Generators for functions; take observers for inputs and a generator for outputs. The observer splits the space of possible inputs into a number of "buckets"; each randomly generated function applies the observer to an input, and produces a different output value for each bucket.

The `?branching_factor` argument determines how many branches the function's decision tree has, and thus how many categories of inputs it can distinguish. If absent, `branching_factor` defaults to a geometric distribution similar to `size` but capped by the maximum branching factor of the domain observers.

val fn2 : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c t -> ('a -> 'b -> 'c) t
val fn3 : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd t -> ('a -> 'b -> 'c -> 'd) t
val fn4 : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e t -> ('a -> 'b -> 'c -> 'd -> 'e) t
val fn5 : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e obs -> 'f t -> ('a -> 'b -> 'c -> 'd -> 'e -> 'f) t
val fn6 : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e obs -> 'f obs -> 'g t -> ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g) t
val compare_fn : ?branching_factor:int t -> 'a obs -> ('a -> 'a -> int) t

Generator for comparison functions; result is guaranteed to be a partial order.

val equal_fn : ?branching_factor:int t -> 'a obs -> ('a -> 'a -> bool) t

Generator for equality functions; result is guaranteed to be an equivalence relation.

type ('a, 'b) fn_with_sexp = ('a -> 'b) * (unit -> Quickcheck_intf.Sexp.t)

Generators for functions, annotated with sexps that describe the functions. Intended for debugging purposes. These generators each produce a `fn_with_sexp`, whose description can be extracted using `fn_sexp`.

val sexp_of_fn_with_sexp : ('a -> Sexplib.Sexp.t) -> ('b -> Sexplib.Sexp.t) -> ('a, 'b) fn_with_sexp -> Sexplib.Sexp.t
val fn_sexp : (_, _) fn_with_sexp -> Quickcheck_intf.Sexp.t
val compare_fn_with_sexp : ?branching_factor:int t -> 'a obs -> ('a, 'a -> int) fn_with_sexp t
val equal_fn_with_sexp : ?branching_factor:int t -> 'a obs -> ('a, 'a -> bool) fn_with_sexp t
val fn_with_sexp : ?branching_factor:int t -> 'a obs -> 'b t -> sexp_of_rng:('b -> Quickcheck_intf.Sexp.t) -> ('a, 'b) fn_with_sexp t
val fn2_with_sexp : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c t -> sexp_of_rng:('c -> Quickcheck_intf.Sexp.t) -> ('a, 'b -> 'c) fn_with_sexp t
val fn3_with_sexp : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd t -> sexp_of_rng:('d -> Quickcheck_intf.Sexp.t) -> ('a, 'b -> 'c -> 'd) fn_with_sexp t
val fn4_with_sexp : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e t -> sexp_of_rng:('e -> Quickcheck_intf.Sexp.t) -> ('a, 'b -> 'c -> 'd -> 'e) fn_with_sexp t
val fn5_with_sexp : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e obs -> 'f t -> sexp_of_rng:('f -> Quickcheck_intf.Sexp.t) -> ('a, 'b -> 'c -> 'd -> 'e -> 'f) fn_with_sexp t
val fn6_with_sexp : ?branching_factor:int t -> 'a obs -> 'b obs -> 'c obs -> 'd obs -> 'e obs -> 'f obs -> 'g t -> sexp_of_rng:('g -> Quickcheck_intf.Sexp.t) -> ('a, 'b -> 'c -> 'd -> 'e -> 'f -> 'g) fn_with_sexp t
val filter_map : 'a t -> f:('a -> 'b option) -> 'b t

`filter_map t ~f` produces `y` for every `x` in `t` such that `f x = Some y`. `filter t ~f` produces every `x` in `t` such that `f x = true`.

Caveat: Use `filter` and `filter_map` sparingly. Every time `f` rejects a value, it counts as a failed attempt to produce a value. Too many failures can cause Quickcheck to take a long time to generate values, or fail a test if it fails more times than the maximum configured number of attempts.

val filter : 'a t -> f:('a -> bool) -> 'a t
val recursive : ('a t -> 'a t) -> 'a t

Fixed-point generator. For example, the following produces a naive generator for natural numbers:

``````
recursive (fun t ->
union [ singleton 0 ; t >>| Int.succ ])
``````
module Choice : sig .. end
`'a Choice.t` represents the choice of a value from a generator.
val bind_choice : 'a t -> ('a Choice.t -> 'b t) -> 'b t

`bind_choice t f` is like `bind t f`, except `f` is passed an `'a Choice.t` and can thus use subsets of `t` by using `Choice.gen` with the `~keep` option.

`bind t f` is equal to `bind_choice t (fun c -> f (Choice.value c))`, although `bind` is cheaper than `bind_choice`.

val failure : _ t

Empty generator that is guaranteed to fail to produce a value.

val weighted_union : (float * 'a t) list -> 'a t

`weighted_union alist` produces a generator that combines the distributions of each `t` in `alist` with the associated weights, which must be finite positive floating point values.

val of_fun : (unit -> 'a t) -> 'a t

`of_fun f` produces a generator that lazily applies `f`.

`f` *MUST* be deterministic or else random value generation will fail. However, it is recommended that `f` not be memoized. Instead, spread out the work of generating a whole distribution over many `of_fun` calls combined with `weighted_union`. This allows lazily generated generators to be garbage collected after each test and the relevant portions cheaply recomputed in subsequent tests, rather than accumulating without bound over time.

val choose : 'a t -> random_float_between_zero_and_one:(unit -> float) -> max_attempts:int -> [
| `No_choices_remain
| `Ran_out_of_attempts
| `Choice of 'a Choice.t
]

`choose t ~random_float_between_zero_and_one` makes a choice in `t` at random, using `random_float_between_zero_and_one` to produce random floats between 0. (inclusive) and 1. (exclusive) for each weighted choice. If `t` has been fully explored, it produces ``No_choices_remain`. Otherwise it produces ``Choice c` for some choice `c` in `t`.

val inspect : 'a t -> [
| `Failure
| `Singleton of 'a
| `Weighted_union of (float * 'a t) list
]

`inspect t` produces a concrete representation of the outermost constructor of `t`. It is possible to explore `t` further with recursive calls to `inspect`; however, be aware that `t` may be infinite.