Result value combinators.
These are rough design guidelines, don't forget to think.
Use error messages if:
Your error messages don't need to be localized, e.g. scripts, command line programs. The errors don't need to be processed. They are just meant to be logged at certain point in your program. If the above doesn't hold and your errors need to be processed for localization or error recovery then use a custom error type in your result values.
If your module has specific errors then define an error type, and a result type that tags this error type with the library name (or any other tag that may make sense, see for example R:exn
module Mod : sig
type error = ...
type 'a result = ('a, [`Mod of error]) Rresult.result
val pp_error : Format.formatter -> [`Mod of error] -> unit
val open_error : 'a result -> ('a, [> `Mod of error]) Rresult.result
val error_to_msg : 'a result -> ('a, Rresult.R.msg) Rresult.result
val f : ... -> 'a result
endIf your library has generic errors that may be useful in other context or shared among modules and to be composed together, then define your error type itself as being a variant and return these values without tagging them.
module Mod : sig
type error = [`Generic of ... | ... ]
type 'a result = ('a, error) Rresult.result
val pp_error : Format.formatter -> error -> unit
val open_error : 'a result -> ('a, [> error]) Rresult.result
val error_to_msg : 'a result -> ('a, Rresult.R.msg) Rresult.result
val f : ... -> 'a result
endIn the latter case it may still be useful to provide a function to tag these errors whenever they reach a certain point of the program. For this the following function could be added to Mod:
val pack_error : 'a result -> ('a, [> `Mod of error]) Rresult.resultYou should then provide the following functions aswell, so that the packed error composes well in the system:
val pp_pack_error : Format.formatter -> [ `Mod of error] -> unit
val open_pack_error : ('a, [ `Mod of error]) Rresult.result ->
('a, [> `Mod of error]) Rresult.result
val error_pack_to_msg : ('a, [ `Mod of error]) Rresult.result ->
('a, Rresult.R.msg) Rresult.result