package travesty

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

Or-error monad extensions.

This module contains various extensions for Base's Or_error monad, including monadic traversal over successful values and monad extensions.

type 'a t = 'a Base.Or_error.t

Defined to let this module be used directly in chaining operations etc.

Travesty signatures

Monad extensions for Or_error.

include Travesty.Monad_exts_types.S with type 'a t := 'a t

Haskell-style operators

val then_m : _ t -> 'a t -> 'a t

then_m x y sequentially composes the actions x and y as with >>=, but, rather than using the returned value of x, it instead just returns y.

val (>>) : _ t -> 'a t -> 'a t

x >> y is then_m x y.

val compose_m : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

compose_m f g is the Kleisli composition of f and g.

val (>=>) : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

x >=> y is k_compose x y.

Guarded monadic computations

val map_when_m : ?otherwise:('a -> 'a t) -> bool -> 'a -> f:('a -> 'a t) -> 'a t

map_when_m ?otherwise condition ~f a is f a when condition is true, and otherwise a (by default, return) otherwise.

val when_m : ?otherwise:(unit -> unit t) -> bool -> f:(unit -> unit t) -> unit t

when_m ?otherwise condition ~f is f () when condition is true, and otherwise () (by default, return) otherwise.

val map_unless_m : ?otherwise:('a -> 'a t) -> bool -> 'a -> f:('a -> 'a t) -> 'a t

map_unless_m ?otherwise condition ~f a is f a when condition is false, and otherwise a (by default, return) otherwise.

val unless_m : ?otherwise:(unit -> unit t) -> bool -> f:(unit -> unit t) -> unit t

unless_m ?otherwise condition ~f is f () when condition is false, and otherwise () (by default, return) otherwise.

Executing monadic effects in the middle of pipelines

val tee_m : 'a -> f:('a -> unit t) -> 'a t

tee_m val ~f executes f val for its monadic action, then returns val.

Example (using an extended Or_error):

let fail_if_negative x =
  On_error.when_m (Int.is_negative x)
    ~f:(fun () -> Or_error.error_string "value is negative!")
in
Or_error.(
  42 |> tee_m ~f:fail_if_negative >>| (fun x -> x * x)
) (* Ok (1764) *)
val tee : 'a -> f:('a -> unit) -> 'a t

tee val ~f behaves as tee, but takes a non-monadic f.

Example (using an extended Or_error):

let print_if_negative x =
  if Int.negative x then Stdio.print_string "value is negative!"
in
Or_error.(
  try_get_value ()
  >>= tee ~f:print_if_negative
  >>= try_use_value ()
)

Or_error is a bi-traversable type, with the right type fixed to Error.t. (This is backwards from Haskell conventions, but matches the position Error.t takes in Result in Base.

include Travesty.Bi_traversable_types.S1_left with type 'l t := 'l t and type right = Base.Error.t
include Travesty.Generic_types.Bi_left with type 'l t := 'l t with type right = Base.Error.t
type right = Base.Error.t

Fixed type of right elements.

include Travesty.Bi_traversable_types.Generic with type ('l, 'r) t := 'l t and type 'l left := 'l and type 'r right := right
include Travesty.Generic_types.Bi_generic with type ('l, 'r) t := 'l t with type 'l left := 'l with type 'r right := right

We can do non-monadic bi-mapping operations.

include Travesty.Bi_mappable_types.Generic with type ('l, 'r) t := 'l t and type 'l left := 'l and type 'r right := right
include Travesty.Bi_mappable_types.Basic_generic with type ('l, 'r) t := 'l t with type 'l left := 'l with type 'r right := right
include Travesty.Generic_types.Bi_generic with type ('l, 'r) t := 'l t with type 'l left := 'l with type 'r right := right
val bi_map : 'l1 t -> left:('l1 -> 'l2) -> right:(right -> right) -> 'l2 t

bi_map c ~left ~right maps left over every 'l1 left, and right over every 'r1 right, in c.

val map_left : 'l1 t -> f:('l1 -> 'l2) -> 'l2 t

map_left c ~f maps f over the left type of c only.

val map_right : 'l t -> f:(right -> right) -> 'l t

map_right c ~f maps f over the right type of c only.

module On_monad (M : Base.Monad.S) : Travesty.Bi_traversable_types.Generic_on_monad with type ('l, 'r) t := 'l t and type 'l left := 'l and type 'r right := right and module M := M

On_monad implements monadic bi-traversal operators for a given monad M.

module With_errors : Travesty.Bi_traversable_types.Generic_on_monad with type ('l, 'r) t := 'l t and type 'l left := 'l and type 'r right := right and module M := Base.Or_error

With_errors specialises On_monad to the error_monad.

module On_ok : Travesty.Traversable_types.S1 with type 'a t = 'a t

On_ok is shorthand for Traverse1_left on this module.

Shortcuts for combining errors

These functions are just shorthand for mapping over a list, then using the various combine_errors functions in Base.

Prefer using these, where possible, over the analogous functions in T_list.With_errors; these ones correctly merge errors.

val combine_map : 'a list -> f:('a -> 'b t) -> 'b list t

combine_map xs ~f is short for map xs ~f followed by combine_errors.

val combine_map_unit : 'a list -> f:('a -> unit t) -> unit t

combine_map_unit xs ~f is short for map xs ~f followed by combine_errors_unit.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct