This syntax extension can add a random generator for a custom type
definition. Adding [@@deriving random]
to the type definition foo
will emit val random_foo : random_state -> foo
. An additional argument
is prepended to the argument list for each type variable in the style of
other deriving
extensions. That is,
type ('a1, ..., 'aN) foo = ... [@@deriving random]
will provide
val random_foo : (random_state -> 'a1) ... (random_state -> 'aN) ->
random_state -> ('a1, ..., 'aN) foo
If you use opam
and don't mind adding another repo, you can install
ppx_deriving_random
with
opam repo add paurkedal https://github.com/paurkedal/opam-repo-paurkedal.git
opam install ppx_deriving_random
For manual installation from a fresh Git checkout, make sure you have OASIS
and ppx_deriving
, then
oasis setup -setup-update dynamic
ocaml setup.ml -configure --prefix your-prefix
make
make install
where your-prefix/lib
is in your findlib path. The syntax extension can
now be enabled with -package ppx_deriving_random.ppx
or by putting
package(ppx_deriving_random.ppx)
in your _tags
. To build the
example:
ocamlfind ocamlopt -linkpkg -package ppx_deriving_random.ppx -package ppx_deriving.show free_magma.ml
The following definitions are assumed to be in scope:
type random_state
(* State passed to the random generators. *)
val random_case : int -> random_state -> int
(* A function used to select a random constructor or row field. The first
argument is the number of cases. The result must be in the range from 0
to the number of cases minus one and should be uniformly distributed. *)
val random_case_30b : random_state -> int
(* When fields are weighted (see below), this is used instead of
random_case. In the returned value, bit 29 and downwards to the desired
precision must be random and bit 30 upwards must be zero. *)
These can be bound to Random.State.t
, Random.State.int
, and
Random.State.bits
, respectively, but this is not done by default since
advanced applications may need to pass additional information in
random_state
or use different random number generators.
References to other types will produce additional calls to correspondingly
named generators. You should provide generators with suitable distributions
for you usage in scope of the type definition. If needed, the generator
used for a particular type reference u
can be overridden with
[@random expr]
, where expr : random_state -> u
. This allows using
different distributions for different instances of the same type. Another
way to tweak the distribution is to define type aliases with custom
random generators.
type 'a free_magma =
| Fm_gen of 'a
| Fm_mul of 'a free_magma * 'a free_magma
[@@deriving random]
will generate
val random_free_magma : (random_state -> 'a) -> random_state -> 'a free_magma
However, there is a problem with the generated function. By default all branches of the variant is equally probable, leading to a possibly diverging computation. This can be fixed by weighing the constructors:
type 'a free_magma =
| Fm_gen of 'a [@weight 3]
| Fm_mul of 'a free_magma * 'a free_magma [@weight 2]
[@@deriving random]
Weights can be int or float constants and defaults to 1. The probability is the weight divided by the sum of weights for the given variant.