Module CCResult

Error Monad

Uses the new "result" type from OCaml 4.03.

type 'a sequence = ('a ‑> unit) ‑> unit
type 'a equal = 'a ‑> 'a ‑> bool
type 'a ord = 'a ‑> 'a ‑> int
type 'a printer = Format.formatter ‑> 'a ‑> unit

Basics

include module type of Result
type ('a, 'b) result = ('a, 'b) Pervasives.result =
| Ok of 'a
| Error of 'b
type (+'good, +'bad) t = ('good, 'bad) Result.result =
| Ok of 'good
| Error of 'bad
val return : 'a ‑> ('a, 'err) t

Successfully return a value.

val fail : 'err ‑> ('a, 'err) t

Fail with an error.

val of_exn : exn ‑> ('a, string) t

of_exn e uses Printexc to print the exception as a string.

val of_exn_trace : exn ‑> ('a, string) t

of_exn_trace e is similar to of_exn e, but it adds the stacktrace to the error message.

Remember to call Printexc.record_backtrace true and compile with the debug flag for this to work.

val fail_printf : ('a, Buffer.t, unit, ('b, string) t) Pervasives.format4 ‑> 'a

fail_printf format uses format to obtain an error message and then returns Error msg.

val fail_fprintf : ('a, Format.formatter, unit, ('b, string) t) Pervasives.format4 ‑> 'a

fail_fprintf format uses format to obtain an error message and then returns Error msg.

val add_ctx : string ‑> ('a, string) t ‑> ('a, string) t

add_ctx msg leaves Ok x untouched, but transforms Error s into Error s' where s' contains the additional context given by msg.

val add_ctxf : ('a, Format.formatter, unit, ('b, string) t ‑> ('b, string) t) Pervasives.format4 ‑> 'a

add_ctxf format_message is similar to add_ctx but with Format for printing the message (eagerly). Example: 

      add_ctxf "message(number %d, foo: %B)" 42 true (Error "error)"
val map : ('a ‑> 'b) ‑> ('a, 'err) t ‑> ('b, 'err) t

Map on success.

val map_err : ('err1 ‑> 'err2) ‑> ('a, 'err1) t ‑> ('a, 'err2) t

Map on the error variant.

val map2 : ('a ‑> 'b) ‑> ('err1 ‑> 'err2) ‑> ('a, 'err1) t ‑> ('b, 'err2) t

Like map, but also with a function that can transform the error message in case of failure.

val iter : ('a ‑> unit) ‑> ('a, _) t ‑> unit

Apply the function only in case of Ok.

exception Get_error
val get_exn : ('a, _) t ‑> 'a

Extract the value x from Ok x, fails otherwise. You should be careful with this function, and favor other combinators whenever possible.

val get_or : ('a, _) t ‑> default:'a ‑> 'a

get_or e ~default returns x if e = Ok x, default otherwise.

val map_or : ('a ‑> 'b) ‑> ('a, 'c) t ‑> default:'b ‑> 'b

map_or f e ~default returns f x if e = Ok x, default otherwise.

val catch : ('a, 'err) t ‑> ok:('a ‑> 'b) ‑> err:('err ‑> 'b) ‑> 'b

catch e ~ok ~err calls either ok or err depending on the value of e.

val flat_map : ('a ‑> ('b, 'err) t) ‑> ('a, 'err) t ‑> ('b, 'err) t
val (>|=) : ('a, 'err) t ‑> ('a ‑> 'b) ‑> ('b, 'err) t
val (>>=) : ('a, 'err) t ‑> ('a ‑> ('b, 'err) t) ‑> ('b, 'err) t

Monadic composition. e >>= f proceeds as f x if e is Ok x or returns e if e is an Error.

val equal : err:'err equal ‑> 'a equal ‑> ('a, 'err) t equal
val compare : err:'err ord ‑> 'a ord ‑> ('a, 'err) t ord
val fold : ok:('a ‑> 'b) ‑> error:('err ‑> 'b) ‑> ('a, 'err) t ‑> 'b

fold ~ok ~error e opens e and, if e = Ok x, returns ok x, otherwise e = Error s and it returns error s.

val fold_ok : ('a ‑> 'b ‑> 'a) ‑> 'a ‑> ('b, _) t ‑> 'a

fold_ok f acc r will compute f acc x if r=Ok x, and return acc otherwise, as if the result were a mere option.

val is_ok : ('a, 'err) t ‑> bool

Return true if Ok.

val is_error : ('a, 'err) t ‑> bool

Return true if Error.

Wrappers

val guard : (unit ‑> 'a) ‑> ('a, exn) t

guard f runs f () and returns its result wrapped in Ok. If f () raises some exception e, then it fails with Error e.

val guard_str : (unit ‑> 'a) ‑> ('a, string) t

Like guard but uses of_exn to print the exception.

val guard_str_trace : (unit ‑> 'a) ‑> ('a, string) t

Like guard_str but uses of_exn_trace instead of of_exn so that the stack trace is printed.

val wrap1 : ('a ‑> 'b) ‑> 'a ‑> ('b, exn) t

Like guard but gives the function one argument.

val wrap2 : ('a ‑> 'b ‑> 'c) ‑> 'a ‑> 'b ‑> ('c, exn) t

Like guard but gives the function two arguments.

val wrap3 : ('a ‑> 'b ‑> 'c ‑> 'd) ‑> 'a ‑> 'b ‑> 'c ‑> ('d, exn) t

Like guard but gives the function three arguments.

Applicative

val pure : 'a ‑> ('a, 'err) t

Synonym of return.

val (<*>) : ('a ‑> 'b, 'err) t ‑> ('a, 'err) t ‑> ('b, 'err) t

a <*> b evaluates a and b, and, in case of success, returns Ok (a b). Otherwise, it fails, and the error of a is chosen over the error of b if both fail.

val join : (('a, 'err) t, 'err) t ‑> ('a, 'err) t

join t, in case of success, returns Ok o from Ok (Ok o). Otherwise, it fails with Error e where e is the unwrapped error of t.

val both : ('a, 'err) t ‑> ('b, 'err) t ‑> ('a * 'b, 'err) t

both a b, in case of success, returns Ok (o, o') with the ok values of a and b. Otherwise, it fails, and the error of a is chosen over the error of b if both fail.

Infix

module Infix : sig ... end

Collections

val map_l : ('a ‑> ('b, 'err) t) ‑> 'a list ‑> ('b list, 'err) t
val fold_l : ('b ‑> 'a ‑> ('b, 'err) t) ‑> 'b ‑> 'a list ‑> ('b, 'err) t
val fold_seq : ('b ‑> 'a ‑> ('b, 'err) t) ‑> 'b ‑> 'a sequence ‑> ('b, 'err) t

Misc

val choose : ('a, 'err) t list ‑> ('a, 'err list) t

choose l selects a member of l that is a Ok _ value, or returns Error l otherwise, where l is the list of errors.

val retry : int ‑> (unit ‑> ('a, 'err) t) ‑> ('a, 'err list) t

retry n f calls f at most n times, returning the first result of f () that doesn't fail. If f fails n times, retry n f fails with the list of successive errors.

module type MONAD : sig ... end

Monadic Operations

module Traverse : functor (M : MONAD) -> sig ... end

Conversions

val to_opt : ('a, _) t ‑> 'a option

Convert a result to an option.

val of_opt : 'a option ‑> ('a, string) t

Convert an option to a result.

val to_seq : ('a, _) t ‑> 'a sequence
type ('a, 'b) error = [
| `Ok of 'a
| `Error of 'b
]
val of_err : ('a, 'b) error ‑> ('a, 'b) t
val to_err : ('a, 'b) t ‑> ('a, 'b) error

IO

val pp : 'a printer ‑> ('a, string) t printer
val pp' : 'a printer ‑> 'e printer ‑> ('a, 'e) t printer

Printer that is generic on the error type.