octez-proto-libs 20.1 · OCaml Package

Tezos Protocol Implementation - Error Monad

Error classification

type error_category = [

| `Branch
(*
Errors that may not happen in another context
*)
| `Temporary
(*
Errors that may not happen in a later context
*)
| `Permanent
(*
Errors that will happen no matter the context
*)

]

Categories of error

Custom error handling for economic protocols.

type error = ..

val pp : Format.formatter -> error -> unit

val error_encoding : error Data_encoding.t

A JSON error serializer

val json_of_error : error -> Data_encoding.json

val error_of_json : Data_encoding.json -> error

type error_info = {

category : error_category;
id : string;
title : string;
description : string;
schema : Data_encoding.json_schema;

}

Error information

val pp_info : Format.formatter -> error_info -> unit

val get_registered_errors : unit -> error_info list

Retrieves information of registered errors

val register_error_kind : 
  error_category ->
  id:string ->
  title:string ->
  description:string ->
  ?pp:(Format.formatter -> 'err -> unit) ->
  'err Data_encoding.t ->
  (error -> 'err option) ->
  ('err -> error) ->
  unit

For other modules to register specialized error serializers

val classify_errors : error list -> error_category

Classify an error using the registered kinds

Monad definition

type 'a tzresult = ('a, error list) Pervasives.result

The error monad wrapper type, the error case holds a stack of error, initialized by the first call to fail and completed by each call to trace as the stack is rewound. The most general error is thus at the top of the error stack, going down to the specific error that actually caused the failure.

val result_encoding : 'a Data_encoding.t -> 'a tzresult Data_encoding.encoding

A JSON serializer for result of a given type

val ok : 'a -> 'a tzresult

Successful result

val return : 'a -> 'a tzresult Lwt.t

Successful return

val return_unit : unit tzresult Lwt.t

Successful return of ()

val return_none : 'a option tzresult Lwt.t

Successful return of None

val return_some : 'a -> 'a option tzresult Lwt.t

return_some x is a successful return of Some x

val return_nil : 'a list tzresult Lwt.t

Successful return of []

val return_true : bool tzresult Lwt.t

Successful return of true

val return_false : bool tzresult Lwt.t

Successful return of false

val error : error -> 'a tzresult

Erroneous result

val fail : error -> 'a tzresult Lwt.t

Erroneous return

val (>>?) : 'a tzresult -> ('a -> 'b tzresult) -> 'b tzresult

Non-Lwt bind operator

val (>>=?) : 
  'a tzresult Lwt.t ->
  ('a -> 'b tzresult Lwt.t) ->
  'b tzresult Lwt.t

Bind operator

val (>>=) : 'a Lwt.t -> ('a -> 'b Lwt.t) -> 'b Lwt.t

Lwt's bind reexported

val (>|=) : 'a Lwt.t -> ('a -> 'b) -> 'b Lwt.t

val (>>|?) : 'a tzresult Lwt.t -> ('a -> 'b) -> 'b tzresult Lwt.t

To operator

val (>|?) : 'a tzresult -> ('a -> 'b) -> 'b tzresult

Non-Lwt to operator

val record_trace : error -> 'a tzresult -> 'a tzresult

Enrich an error report (or do nothing on a successful result) manually

val trace : error -> 'b tzresult Lwt.t -> 'b tzresult Lwt.t

Automatically enrich error reporting on stack rewind

val record_trace_eval : (unit -> error tzresult) -> 'a tzresult -> 'a tzresult

Same as record_trace, for unevaluated error

val trace_eval : 
  (unit -> error tzresult Lwt.t) ->
  'b tzresult Lwt.t ->
  'b tzresult Lwt.t

Same as trace, for unevaluated Lwt error

val fail_unless : bool -> error -> unit tzresult Lwt.t

Erroneous return on failed assertion

val fail_when : bool -> error -> unit tzresult Lwt.t

Erroneous return on successful assertion

In-monad list iterators

val iter_s : ('a -> unit tzresult Lwt.t) -> 'a list -> unit tzresult Lwt.t

A List.iter in the monad

val iter_p : ('a -> unit tzresult Lwt.t) -> 'a list -> unit tzresult Lwt.t

val map_s : ('a -> 'b tzresult Lwt.t) -> 'a list -> 'b list tzresult Lwt.t

A List.map in the monad

val map_p : ('a -> 'b tzresult Lwt.t) -> 'a list -> 'b list tzresult Lwt.t

val map2 : ('a -> 'b -> 'c tzresult) -> 'a list -> 'b list -> 'c list tzresult

A List.map2 in the monad

val map2_s : 
  ('a -> 'b -> 'c tzresult Lwt.t) ->
  'a list ->
  'b list ->
  'c list tzresult Lwt.t

A List.map2 in the monad

val filter_map_s : 
  ('a -> 'b option tzresult Lwt.t) ->
  'a list ->
  'b list tzresult Lwt.t

A List.filter_map in the monad

val fold_left_s : 
  ('a -> 'b -> 'a tzresult Lwt.t) ->
  'a ->
  'b list ->
  'a tzresult Lwt.t

A List.fold_left in the monad

val fold_right_s : 
  ('a -> 'b -> 'b tzresult Lwt.t) ->
  'a list ->
  'b ->
  'b tzresult Lwt.t

A List.fold_right in the monad

package octez-proto-libs

Error classification

Monad definition

In-monad list iterators