Module Mavryk_stdlib_unix.Animation

val make_with_animation : Stdlib.Format.formatter -> make:('seed -> ('result, 'failure) Stdlib.result Lwt.t) -> on_retry:(Mtime.Span.t -> 'failure -> 'seed Lwt.t) -> 'seed -> 'result Lwt.t

make_with_animation is meant to be used to execute time consuming functions that can be interrupted. Typically proof-of-work tasks. Whilst doing so, it displays a progress animation on the provided formatter (assumes support for '\b`). The animations leave the terminal clean.

make_with_animation ppf ~make ~on_retry seed behaves as follows: (a) if make seed is Ok v (completion of the task), then it returns v (b) if make seed is Error r (task is incomplete), then (b.1) on_retry t r is evaluated where t is the time elapsed during the call to make, and then (b.2) the result is used to attempt the task again.

type progress_display_mode =
  1. | Auto
  2. | Always
  3. | Never
val progress_display_mode_enum : (string * progress_display_mode) list

This list associates each progress_display_mode constructor with its textual representation. The main use case of this list is enum combinator, e.g. from cmdliner or data_encoding libraries.

val progress_display_mode_encoding : progress_display_mode Data_encoding.t
val number_of_frames : int

The number of steps that the animation cycles through.

val display_progress : ?every:int -> ?out:Lwt_unix.file_descr -> progress_display_mode:progress_display_mode -> pp_print_step:(Stdlib.Format.formatter -> int -> unit) -> ((unit -> unit Lwt.t) -> 'a Lwt.t) -> 'a Lwt.t

display_progress ?every ?out ~progress_display_mode ~pp_print_step f calls pp_print_step when the first argument of f is called and increments the number of steps which will be given to pp_print_step.

If every is passed, it is instead displayed whenever nb_step mod every = 0 (defaults to 1). Each time pp_print_step is called, the previous output will be erased and replaced by the new output.

progress_display_mode determines whether progress animation should be displayed to the given out. When Auto, animation is displayed based on isatty result. When Always, animation is always displayed in the out. When Never, animation isn't displayed in the out.

pp_print_step must only write on a single-line with no carriage return.

  • raises Invalid_argument

    if the given every is less than 1.

val three_dots : ?out:Lwt_unix.file_descr -> progress_display_mode:progress_display_mode -> msg:string -> (unit -> 'a Lwt.t) -> 'a Lwt.t

three_dots ?out msg prints the given msg, on the given output, followed by the "three dots" animation. It returns a canceller that must be called once the animation must be terminated.