package core

  1. Overview
  2. Docs
package core
Legend:
Library
Module
Module type
Parameter
Class
Class type

This module can be used to safely expose functions and values in signatures that should only be used in unit tests.

Under the hood, 'a t = 'a Lazy.t and the only thing that ever forces them is the force function below which should only be called in unit tests.

For example, suppose in some module, type t is actually an int. You want to keep the type definition opaque, but use the underlying representation in unit tests. You could write in the ml:

let test_to_int t = Only_in_test.return t
let test_of_int n = Only_in_test.return n

You would then expose in the mli:

type t
val test_to_int : t -> int Only_in_test.t
val test_of_int : int -> t Only_in_test.t

Finally, if you have specific values that you might want to use in unit tests, but that have top-level side-effects or take too long to compute, you can delay the side-effects or computation until the unit tests are run by writing, e.g.:

let (test_special_value : t Only_in_test.t) = Only_in_test.of_thunk (fun () -> factorial 100)

instead of

let (test_special_value : t Only_in_test.t) = Only_in_test.return (factorial 100)

type 'a t
include Base.Monad.S with type 'a t := '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)).

module Monad_infix : sig ... end
val bind : 'a t -> f:('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 Caml.ignore. Some monads still do let ignore = ignore_m for historical reasons.

val all : 'a t list -> 'a list t
val all_unit : unit t list -> unit t

Like all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.

module Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

val of_thunk : (Base.Unit.t -> 'a) -> 'a t
val force : 'a t -> 'a