package console

Build not yet checked
  1. Overview
  2. Docs
Colours, tables, trees and progress rows for the terminal

Install

dune-project
 Dependency

Authors

Maintainers

Sources

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

doc/console/Console/index.html

Module ConsoleSource

Colours, tables, trees and progress rows for command-line tools.

Console prints into the normal scrollback of the terminal, as make or ls do. While work runs, it redraws only the rows of a Display. For a program that takes over the whole screen, use a full-screen library instead. Windows consoles are not supported.

A View.t is text in a Style.t: colours, bold, italic and so on. The widgets (Table, Tree, Panel, Rule and Bar) lay out views and print with Format. A Theme gives them one look.

The view of each widget is a view. It is laid out only when it is printed, in the room it is given (View.fit). So a table can go in a panel, the panel in a cell of another table, next to a tree (View.hcat) or in the view of a display. Each of them is drawn in the theme of the formatter that prints it. Console_eio.run runs a Display.

Guarantees.

  • Widths are counted in terminal cells, the way the terminal draws the text. A wide character, such as a Chinese character or an emoji, takes two cells. An accent added to a letter takes none.
  • A widget printed by View.pp is no wider than the formatter's margin. In a room, it is no wider than the room. It ends without a line end, so "%a@." prints it on lines of its own.
  • A view holds only text that can be printed. A line end in it starts a new line, and any other control character becomes a space. So text from the caller cannot move the cursor or change colours.
  • A printer turns off every style that it turns on, before the line ends.
  • Text cut to fit is cut between two characters, and ends with an ellipsis.
  • On a formatter that is not Fmt.utf_8, the widgets draw their frames, lines, bars, spinners, marks and ellipses in ASCII.
  • The guarantees of a live region are those of Display.

The repository's INVARIANTS.md lists each guarantee and the tests that check it.

Text is in colour when its formatter is set to colour (Fmt.set_style_renderer), with the colours that its Color.depth allows. Console_tty.setup, in the console.tty library, sets both for standard output and standard error. It reads the terminal and the environment, and follows the rules of Env. A program without Unix applies those rules itself.

Quick start

Styled text

open Console

let demo_styled () =
  let style = Style.(bold + fg Color.green) in
  Fmt.pr "%a@." View.pp (View.styled style (View.text "Success!"))

Tables

open Console

let demo_table () =
  let table =
    Table.(
      view ~border:Border.rounded
        [
          column (View.text "Name"); column ~align:`Right (View.text "Age");
        ]
        [
          [ View.text "Alice"; View.text "30" ];
          [ View.text "Bob"; View.text "25" ];
        ])
  in
  Fmt.pr "%a@." View.pp table

Trees

open Console

let demo_tree () =
  let tree =
    Tree.v (View.text "src")
      [
        Tree.v (View.text "lib") [ Tree.v (View.text "parser.ml") [] ];
        Tree.v (View.text "test") [];
      ]
  in
  Fmt.pr "%a@." View.pp (Tree.view tree)

Panels

open Console

let demo_panel () =
  let panel =
    Panel.view ~title:(View.text "Status")
      (View.text "All systems operational")
  in
  Fmt.pr "%a@." View.pp panel

Progress

A program reports its work as Tasks under a root. It calls Console_eio.run once to show them, and Console_eio.run passes the root to the code that does the work:

open Console

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

Console_eio.run ~clock ~label:"Building" build_step runs it, where clock is Eio.Stdenv.mono_clock env. A library can call Console_eio.run itself: a run inside another run gets the task that is current where it is called.

Modules

Sourcemodule Color : sig ... end

Terminal colours, by name, by palette number or as RGB.

Sourcemodule Style : sig ... end

Bold, italic, underline and colours, combined with +.

Sourcemodule Border : sig ... end

Frames for tables and panels.

Sourcemodule Guide : sig ... end

The lines that connect the branches of a tree.

Sourcemodule Theme : sig ... end

One look for every widget.

Sourcemodule Env : sig ... end

How a formatter prints, from the environment: colour, depth and UTF-8.

Sourcemodule Room : sig ... end

Where and when a view is laid out: its width, height, time and theme.

Sourcemodule View : sig ... end

What console prints: styled text and every widget, laid out in a room.

Sourcemodule Spinner : sig ... end

Spinners for work of unknown length.

Sourcemodule Bar : sig ... end

Bars, for progress and for figures: horizontal, vertical, sparklines and charts.

Sourcemodule Panel : sig ... end

Text in a frame, with an optional title.

Sourcemodule Table : sig ... end

Tables with headers and aligned columns.

Sourcemodule Tree : sig ... end

Trees, drawn like the output of tree.

Sourcemodule Rule : sig ... end

Horizontal lines with an optional label.

Sourcemodule Task : sig ... end

The work a program reports: tasks under a root, with no drawing.

Sourcemodule Display : sig ... end

A view redrawn in place: the live region.

Sourcemodule Progress : sig ... end

How tasks show: rows, lines, only failures or JSON.

Sourcemodule Decimal : sig ... end

Numbers with a fixed count of decimals, the same on every platform.