package progress
Install
dune-project
Dependency
Authors
Maintainers
Sources
sha256=3dfd00bd4def773239159b17781d02fdbfd8ea191801681a94aa0a5be1d06b7c
sha512=fd64ff8a819b2db2460c06b7fbd5663e2a1941f9e2d4e9b921a3d5f24509fe3be543521fbe1bb6baedad9f62b579aae933efac3903db03a27385233f5461f09c
doc/progress/Progress/index.html
Module ProgressSource
A library for displaying progress bars, including support for rendering multiple bars at once. Start by describing of a sequence of progress bars, then begin rendering them.
(** Description: "⠼️ [###########--------------------] 37/100" *)
let bar ~total =
let open Progress.Line in
list [ spinner (); bar total; count_to total ]
(** Rendering: get access to a function [f] for reporting progress. *)
let run () =
Progress.with_reporter (bar ~total:100) (fun f ->
for i = 1 to 100 do
(* ... do some work ... *)
f 1 (* report some progress *)
done)See Progress_engine for an equivalent API that is portable to non-Unix platforms.
Preliminaries
Some basic types used throughout the rest of the library:
Description
Describing a progress line is done via the Line DSL. Individual lines can be stacked vertically via Multi.
Pre-provided lines
val counter :
?style:[ `ASCII | `UTF8 | `Custom of Line.Bar_style.t ] ->
?message:string ->
?pp:int64 Printer.t ->
int64 ->
int64 Line.tcounter total is a progress bar of the form:
<message?> <count?> MM:SS [########..............................] XX%where each reported value contributes cumulatively towards an eventual total of total. ?style specifies the Bar_style.t to use for rendering the bar, and ?pp is used to pretty-print the <count> segment, if passed. (For example, Units.Bytes.of_int64 can be used for totals measured in bytes.)
Rendering
Once you have a description of the progress bar to be rendered (either a Line.t or a Multi.t), begin rendering it by using with_reporter or with_reporters respectively.
A reporter for values of type 'a. In this library, each progress line has its own reporting function.
with_reporters line f begins rendering line and calls f with the reporting function. Once f returns, the display is finalised. Note: attempting to use the reporting function after f has returned will raise a Finalised exception.
with_reporters bars f begins rendering bars and passes the corresponding reporting functions to f. Once f returns, the display is finalised.
Examples
- Reading a file into memory and displaying a single progress bar:
let read_file path buffer =
let total = file_size path and in_channel = open_in path in
try
with_reporter (counter ~total ()) @@ fun report ->
let rec aux offset =
let bytes_read = really_read buffer offset in
report bytes_read;
aux (offset + bytes_read)
in
aux 0
with End_of_file -> close_in in_channel- Sending data to multiple clients, with one progress bar each:
let multi_bar_rendering () =
with_reporters
Multi.(line bar_a ++ line bar_b ++ line bar_c)
(fun report_a report_b report_c ->
for i = 1 to 1000 do
report_a (transfer_bytes client_a);
report_b (transfer_bytes client_b);
report_c (transfer_bytes client_c)
done)Logging during rendering
interject_with f executes the function f while temporarily suspending the rendering of any active progress bar display. This can be useful when printing to stdout / stderr, to avoid any interference from the rendering of progress bars. If using the Logs library, consider using reporter and instrument_reporter instead.
Note: the caller must ensure that the terminal cursor is left in an appropriate position to resume rendering. In practice, this means that any printing to the terminal should be terminated with a newline character and flushed.
Extensions to the Logs library designed to cooperate with progress bar rendering:
val logs_reporter :
?pp_header:(Logs.level * string option) Fmt.t ->
?app:Format.formatter ->
?dst:Format.formatter ->
unit ->
Logs.reporterreporter is like Logs_fmt.reporter but produces a reporter that suspends any ongoing progress bar rendering while displaying log entries, ensuring that log entries in the terminal are never overwritten by the renderer.
instrument_reporter r wraps the synchronous reporter r to ensure that any progress bar rendering is suspended while messages are being constructed for r.
Note: to ensure that log entries are not overwritten by the Progress renderer, r must flush any log entries to the terminal synchronously: as soon as they are reported. This is true of the Logs reporters built by Logs.format_reporter and Logs_fmt.reporter. An asynchronous reporter should use interject_with to delimit its flushing action instead.
Manual lifecycle management
Functions for explicitly starting and stopping the process of rendering a bar; useful when the code doing the progress reporting cannot be conveniently delimited inside with_reporter. All Displays must be properly finalised, and it is not possible to interleave rendering of displays.