Module CCResult

module CCResult: sig .. end

Error Monad

Uses the new "result" type from OCaml 4.03.
Since 0.16


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


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_printf 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
Since 1.2
val add_ctxf : ('a, Format.formatter, unit,
('b, string) t -> ('b, string) t)
Pervasives.format4 -> 'a
add_ctxf format_message is similar to CCResult.add_ctx but with Format for printing the message (eagerly). Example:
      add_ctxf "message(number %d, foo: %B)" 42 true (Error "error)"
    

Since 1.2
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
Same as CCResult.map, but also with a function that can transform the error message in case of failure
val iter : ('a -> unit) -> ('a, 'b) t -> unit
Apply the function only in case of Ok
exception Get_error
val get_exn : ('a, 'b) t -> 'a
Extract the value x from Ok x, fails otherwise. You should be careful with this function, and favor other combinators whenever possible.
Raises Get_error if the value is an error.
val get_or : ('a, 'b) 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
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, 'c) 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.
Since 1.2
val is_ok : ('a, 'err) t -> bool
Return true if Ok
Since 1.0
val is_error : ('a, 'err) t -> bool
Return true if Error
Since 1.0

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
Same as CCResult.guard but uses CCResult.of_exn to print the exception.
val guard_str_trace : (unit -> 'a) -> ('a, string) t
Same as CCResult.guard_str but uses CCResult.of_exn_trace instead of CCResult.of_exn so that the stack trace is printed.
val wrap1 : ('a -> 'b) -> 'a -> ('b, exn) t
Same as CCResult.guard but gives the function one argument.
val wrap2 : ('a -> 'b -> 'c) -> 'a -> 'b -> ('c, exn) t
Same as CCResult.guard but gives the function two arguments.
val wrap3 : ('a -> 'b -> 'c -> 'd) -> 'a -> 'b -> 'c -> ('d, exn) t
Same as CCResult.guard but gives the function three arguments.

Applicative


val pure : 'a -> ('a, 'err) t
Synonym of CCResult.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 (M : MONAD) : sig .. end

Conversions


val to_opt : ('a, 'b) t -> 'a option
val of_opt : 'a option -> ('a, string) t
val to_seq : ('a, 'b) t -> 'a sequence
type ('a, 'b) error = [ `Error of 'b | `Ok of 'a ] 
val of_err : ('a, 'b) error -> ('a, 'b) t
Since 0.17
val to_err : ('a, 'b) t -> ('a, 'b) error
Since 0.17

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