package tezos-error-monad

  1. Overview
  2. Docs
package tezos-error-monad
Legend:
Library
Module
Module type
Parameter
Class
Class type

The purpose of this module is to wrap a specific error monad E into a more general error monad Eg.

The user implementing such an interface is responsible to maintain the following assertions

  • The Eg error is extended locally with a specific constructor C
  • unwrapped is equal to the error type of E
  • wrap builds an Eg error value from an E error value
  • unwrap matches on Eg error cases and extracts E error value from C

As a reference implementation, see src/lib_protocol_environment/environment_V3.ml

type unwrapped = ..
include Sig.CORE with type error := unwrapped
type error_category
val string_of_category : error_category -> string
val error_encoding : unwrapped Data_encoding.t
val pp : Format.formatter -> unwrapped -> unit
val register_error_kind : error_category -> id:string -> title:string -> description:string -> ?pp:(Format.formatter -> 'err -> unit) -> 'err Data_encoding.t -> (unwrapped -> 'err option) -> ('err -> unwrapped) -> unit

The error data type is extensible. Each module can register specialized error serializers id unique name of this error. Ex.: overflow_time_counter title more readable name. Ex.: Overflow of time counter description human readable description. Ex.: The time counter overflowed while computing delta increase pp formatter used to pretty print additional arguments. Ex.: The time counter overflowed while computing delta increase. Previous value %d. Delta: %d encoder decoder data encoding for this error. If the error has no value, specify Data_encoding.empty

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

Same as register_error_kind but allow errors to wrap other errors.

The encoding argument is a function which will be given the encoding of errors as argument so that you can encode errors in errors using a fixpoint.

Another difference with register_error_kind is that pp is mandatory.

val classify_error : unwrapped -> Error_classification.t

Classify an error using the registered kinds

type unwrapped += private
  1. | Unclassified of string
    (*

    Catch all error when 'deserializing' an error.

    *)

Catch all error when 'serializing' an error.

type unwrapped += private
  1. | Unregistered_error of Data_encoding.json
val json_of_error : unwrapped -> Data_encoding.json

An error serializer

val error_of_json : Data_encoding.json -> unwrapped

Error documentation

type error_info = {
  1. category : error_category;
  2. id : string;
  3. title : string;
  4. description : string;
  5. schema : Data_encoding.json_schema;
}

Error information

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

find_info_of_error e retrieves the `error_info` associated with the given error `e`.

  • raises [Invalid_argument]

    if the error is a wrapped error from another monad

  • raises [Not_found]

    if the error's constructor has not been registered

val get_registered_errors : unit -> error_info list

Retrieves information of registered errors

val unwrap : error -> unwrapped option

unwrap e returns Some when e matches variant constructor C and None otherwise

val wrap : unwrapped -> error

wrap e returns a general error from a specific unwrapped error e