package console-eio

Build not yet checked
  1. Overview
  2. Docs
Eio backend for console

Install

dune-project
 Dependency

Authors

Maintainers

Sources

console-0.10.1.tbz
sha256=37ad65f6833c65814b0673f009f6b656c5194608ca03519da2e63e1051d54f6e
sha512=7677067f1a3244779cdbc5c90a8b0e1eba30c3fd58281584ea3d4c46c3e219eef0668588ca0e2938799c61a3fa831ce2146eac73717214d7baf96b497bfcd892

doc/index.html

console-eio

Progress rows for OCaml command-line tools, run with Eio.

console-eio shows the tasks of a program (Console.Task) as progress rows on the terminal. On a pipe or in a CI log it prints plain lines instead. The smallest program:

let build root =
  Console.Task.run root "compile" (fun step ->
      Console.Task.set_items step ~count:1 ~total:2;
      Console.Task.log step "ocamlopt parser.ml";
      Console.Task.set_items step ~count:2 ~total:2)

let main () =
  Eio_main.run @@ fun env ->
  Console_eio.run ~clock:(Eio.Stdenv.mono_clock env) ~label:"Building" build

The program's entry point is then let () = main ().

The tutorial builds a whole command step by step, with options for colour and theme, a table, progress rows and a test of its output.

What Console_eio.run does

Console_eio.run makes the root of the work and passes it to the function, finds out whether the output is a terminal, and how large it is, and redraws the progress rows ten times a second. It hands each line the program prints, and each Logs message, to the task current where it is printed, or prints it above the rows outside any task (where text goes).

The terminal is given back as run found it when the function returns or raises, when its fiber is cancelled, and when the program exits or is stopped by Ctrl-C or SIGTERM.

Running tasks

  • The work succeeds when the function returns and fails when it raises, unless the function ended the root itself, with a message, and the tasks still running end with it. An exception the function raises still reaches the caller.
  • A Console_eio.run called inside another one, or in a fiber beside it, gets the task current where it is called, or the root, so a library can start one without knowing whether its caller did. The display closes once the last of them ends.
  • Call the functions of tasks only from the domain that runs them. A Logs message logged in another domain that Eio runs, such as one of an Eio.Executor_pool, is passed to that domain and printed above the rows.
  • What print_string, Printf or a child process writes on the terminal goes past console and garbles the rows, so print it through Console_eio.with_output.
  • Console_eio.Prompt asks a question, or a password without echoing it, and takes the rows off the screen while it asks.

Modules

  • Console_eio: runs a display and decides on colour for the outputs the program left alone.
  • Console_eio.Prompt: questions asked on the terminal, a line, a yes or no, or a password.

The widgets, the themes and the rules of the display are in the console package: Console.