bos

Basic OS interaction for OCaml
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library bos_setup
Module Bos_setup . R
include module type of struct include Rresult.R end

Result value combinators.

Results

type ('a, 'b) t = ( 'a, 'b ) Rresult.result

The type for results.

val ok : 'a -> ( 'a, 'b ) Rresult.result

ok v is Ok v.

val error : 'b -> ( 'a, 'b ) Rresult.result

error e is Error e.

val reword_error : ( 'b -> 'c ) -> ( 'a, 'b ) Rresult.result -> ( 'a, 'c ) Rresult.result

reword_error reword r is:

  • r if r = Ok v
  • Error (reword e) if r = Error e
val get_ok : ( 'a, 'b ) Rresult.result -> 'a

get_ok r is v if r = Ok v and raises Invalid_argument otherwise.

val get_error : ( 'a, 'b ) Rresult.result -> 'b

get_error r is e if r = Error e and raises Invalid_argument otherwise.

Composing results

val bind : ( 'a, 'b ) Rresult.result -> ( 'a -> ( 'c, 'b ) Rresult.result ) -> ( 'c, 'b ) Rresult.result

bind r f is f v if r = Ok v and r if r = Error _.

val map : ( 'a -> 'c ) -> ( 'a, 'b ) Rresult.result -> ( 'c, 'b ) Rresult.result

map f r is bind (fun v -> ret (f v)) r.

val join : ( ( 'a, 'b ) Rresult.result, 'b ) Rresult.result -> ( 'a, 'b ) Rresult.result

join r is v if r = Ok v and r otherwise.

val (>>=) : ( 'a, 'b ) Rresult.result -> ( 'a -> ( 'c, 'b ) Rresult.result ) -> ( 'c, 'b ) Rresult.result

r >>= f is bind r f.

val (>>|) : ( 'a, 'b ) Rresult.result -> ( 'a -> 'c ) -> ( 'c, 'b ) Rresult.result

r >>| f is map r f.

module Infix = Rresult.R.Infix

Infix operators.

Error messages

type msg = [
| `Msg of string
]

The type for (error) messages.

val msg : string -> [> msg ]

msg s is `Msg s.

val msgf : ( 'a, Format.formatter, unit, [> msg ] ) format4 -> 'a

msgf fmt ... formats a message according to fmt.

val pp_msg : Format.formatter -> msg -> unit

pp_msg ppf m prints m on ppf.

val error_msg : string -> ( 'a, [> msg ] ) Rresult.result

error_msg s is error (`Msg s).

val error_msgf : ( 'a, Format.formatter, unit, ( 'b, [> msg ] ) Rresult.result ) format4 -> 'a

error_msgf fmt ... is an error message formatted according to fmt.

val reword_error_msg : ?replace:bool -> ( string -> msg ) -> ( 'a, msg ) Rresult.result -> ( 'a, [> msg ] ) Rresult.result

reword_error_msg ~replace reword r is like reword_error except if replace is false (default), the result of reword old_msg is concatened, on a new line to the old message.

val error_to_msg : pp_error:( Format.formatter -> 'b -> unit ) -> ( 'a, 'b ) Rresult.result -> ( 'a, [> msg ] ) Rresult.result

error_to_msg ~pp_error r converts errors in r with pp_error to an error message.

val error_msg_to_invalid_arg : ( 'a, msg ) Rresult.result -> 'a

err_msg_to_invalid_arg r is v if r = Ok v and

  • raises Invalid_argument

    with the error message otherwise.

val open_error_msg : ( 'a, msg ) Rresult.result -> ( 'a, [> msg ] ) Rresult.result

open_error_msg r allows to combine a closed error message variant with other variants.

val failwith_error_msg : ( 'a, msg ) Rresult.result -> 'a

failwith_error_msg r raises Failure m if r is Error (`Msg m).

Trapping unexpected exceptions

Getting rid of null was not enough.

type exn_trap = [
| `Exn_trap of exn * Printexc.raw_backtrace
]

The type for exception traps.

val pp_exn_trap : Format.formatter -> exn_trap -> unit

pp_exn_trap ppf bt prints bt on ppf.

val trap_exn : ( 'a -> 'b ) -> 'a -> ( 'b, [> exn_trap ] ) Rresult.result

trap_exn f v is f v and traps any exception that may occur as an exception trap error.

val error_exn_trap_to_msg : ( 'a, exn_trap ) Rresult.result -> ( 'a, [> msg ] ) Rresult.result

error_exn_trap_to_msg r converts exception trap errors in r to an error message.

val open_error_exn_trap : ( 'a, exn_trap ) Rresult.result -> ( 'a, [> exn_trap ] ) Rresult.result

open_error_exn_trap r allows to combine a closed exception trap error variant with other variants.

Pretty printing

val pp : ok:( Format.formatter -> 'a -> unit ) -> error:( Format.formatter -> 'b -> unit ) -> Format.formatter -> ( 'a, 'b ) Rresult.result -> unit

pp ~ok ~error ppf r prints r on ppf using ok and error according to r.

val dump : ok:( Format.formatter -> 'a -> unit ) -> error:( Format.formatter -> 'b -> unit ) -> Format.formatter -> ( 'a, 'b ) Rresult.result -> unit

dump ~ok ~error formats an OCaml result value using ok or error according to case, no parentheses are added.

Predicates and comparison

val is_ok : ( 'a, 'b ) Rresult.result -> bool

is_ok r is true iff r = Ok _.

val is_error : ( 'a, 'b ) Rresult.result -> bool

is_error r is true iff r = Error _.

val equal : ok:( 'a -> 'a -> bool ) -> error:( 'b -> 'b -> bool ) -> ( 'a, 'b ) Rresult.result -> ( 'a, 'b ) Rresult.result -> bool

equal ~ok ~error r r' tests r and r' for equality using ok and error.

val compare : ok:( 'a -> 'a -> int ) -> error:( 'b -> 'b -> int ) -> ( 'a, 'b ) Rresult.result -> ( 'a, 'b ) Rresult.result -> int

compare ~ok ~error r r' totally orders r and r' using ok and error.

Converting

val to_option : ( 'a, 'b ) Rresult.result -> 'a option

to_option r is Some v if r = Ok v and None otherwise.

val of_option : none:( unit -> ( 'a, 'b ) Rresult.result ) -> 'a option -> ( 'a, 'b ) Rresult.result

of_option ~none r is Ok v if r = Some v and none () otherwise.

val to_presult : ( 'a, 'b ) Rresult.result -> [> `Ok of 'a | `Error of 'b ]

to_presult r is r as a polymorphic variant result value.

val of_presult : [< `Ok of 'a | `Error of 'b ] -> ( 'a, 'b ) Rresult.result

of_presult pr is pr as a result value.

Ignoring errors

Warning. Using these functions is, most of the time, a bad idea.

val ignore_error : use:( 'b -> 'a ) -> ( 'a, 'b ) Rresult.result -> 'a

ignore_error ~use r is v if r = Ok v and use e if r = Error e.

val kignore_error : use:( 'b -> ( 'a, 'c ) Rresult.result ) -> ( 'a, 'b ) Rresult.result -> ( 'a, 'c ) Rresult.result

kignore_error ~use r is r if r = Ok v and use e if r = Error e.