package tezos-error-monad

The encoding for errors.

Note that this encoding has a few peculiarities, some of which may impact your code. These peculiarities are due to the type error being an extensible variant.

Because the error type is an extensible variant, you must register an encoding for each error constructor you add to error. This is done via register_error_kind.

Because the error type is an extensible variant, with dynamically registered errors (see peculiarity above), there are no tags associated with each error. This does not affect the JSON encoding, but it does impose restrictions on the binary encoding. The chosen workaround is to encode errors as JSON and to encode the JSON to binary form. As a result, errors can be somewhat large in binary: they include field names and such.

Because the error type is an extensible variant, with dynamically registered errors (see peculiarity above), the encoding must be recomputed when a new error is registered. This is achieved by the means of a Data_encoding.delayed combinator: the encoding is recomputed on-demand. There is a caching mechanism so that, in the case where no new errors have been registered since the last use, the last result is used.

This last peculiarity imposes a limit on the use of error_encoding itself. Specifically, it is invalid to use error_encoding inside the ~json argument of a Data_encoding.splitted. This is because splitted evaluates the delayed combinator once-and-for-all to produce a json encoding. (Note that the following data-encoding combinators use splitted internally: Data_encoding.Compact.make, Data_encoding.assoc, and Data_encoding.lazy_encoding. As a result, it is invalid to use error_encoding within the arguments of these combinators as well.)

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

Classify an error using the registered kinds

Catch all error when 'serializing' an error.

Catch all error when 'deserializing' an error.

An error serializer

Error information

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

Retrieves information of registered errors

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

Same as register_error_kind but for a wrapped error monad. The codec is defined in the module parameter. It makes the category of the error Wrapped instead of Main.

Pretty-prints the top error of a trace

A serializer for result of a given type

record_trace err res is either res if res is Ok _, or it is Error (Trace.cons err tr) if res is Error tr.

In other words, record_trace err res enriches the trace that is carried by res (if it is carrying a trace) with the error err. It leaves res untouched if res is not carrying a trace.

You can use this to add high-level information to potential low-level errors. E.g.,

record_trace
   Failure_to_load_config
   (load_data_from_file config_encoding config_file_name)

Note that record_trace takes a fully evaluated error err as argument. It means that, whatever the value of the result res, the error err is evaluated. This is not an issue if the error is a simple expression (a literal or a constructor with simple parameters). However, for any expression that is more complex (e.g., one that calls a function) you should prefer record_trace_eval.

trace is identical to record_trace but applies to a promise. More formally, trace err p is a promise that resolves to Ok v if p resolves to Ok v, or it resolves to Error (Trace.cons err tr) if res resolves to Error tr.

In other words, trace err p enriches the trace that p resolves to (if it does resolve to a trace) with the error err. It leaves the value that p resolves to untouched if it is not a trace.

You can use this to add high-level information to potential low-level errors.

Note that, like record_trace, trace takes a fully evaluated error as argument. For a similar reason as explained there, you should only use trace with simple expressions (literal or constructor with simple parameters) and prefer trace_eval for any other expression (such as ones that include functions calls).

record_trace_eval is identical to record_trace except that the error that enriches the trace is wrapped in a function that is evaluated only if it is needed. More formally record_trace_eval mkerr res is res if res is Ok _, or it is Error (Trace.cons (mkerr ()) tr) if res is Error tr.

You can achieve the same effect by hand with

match res with
| Ok _ -> res
| Error tr -> Error (Trace.cons (mkerr ()) tr)

Prefer record_trace_eval over record_trace when the enriching error is expensive to compute or heavy to allocate.

trace_eval is identical to trace except that the error that enriches the trace is wrapped in a function that is evaluated only if and when it is needed. More formally trace_eval mkerr p is a promise that resolves to Ok v if p resolves to Ok v, or it resolves to Error (Trace.cons err tr) if p resolves to Error tr and then mkerr () resolves to err.

You can achieve the same effect by hand with

p >>= function
| Ok _ -> p
| Error tr ->
   mkerr () >>= fun err ->
   Lwt.return (Error (Trace.cons err tr))

Note that the evaluation of the error can be arbitrarily delayed. Avoid using references and other mutable values in the function mkerr.

Prefer trace_eval over trace when the enriching error is expensive to compute or heavy to allocate or when evaluating it requires the use of Lwt.

error_unless flag err is Ok () if b is true, it is Error (Trace.make err) otherwise.

error_when flag err is Error (Trace.make err) if b is true, it is Ok () otherwise.

fail_unless flag err is Lwt.return @@ Ok () if b is true, it is Lwt.return @@ Error (Trace.make err) otherwise.

fail_when flag err is Lwt.return @@ Error (Trace.make err) if b is true, it is Lwt.return @@ Ok () otherwise.

unless b f is f () if b is false and it is a promise already resolved to Ok () otherwise.

You can use unless to avoid having to write an if statement that you then need to populate entirely to satisfy the type-checker. E.g, you can write unless b f instead of if not b then f () else return_unit.

when_ b f is f () if b is true and it is a promise already resolved to Ok () otherwise.

You can use when_ to avoid having to write an if statement that you then need to populate entirely to satisfy the type-checker. E.g, you can write when_ b f instead of if b then f () else return_unit.

Wrapper around Lwt_utils.dont_wait