package matrix

  1. Overview
  2. Docs

Module Matrix_cliSource

Output for programs that write to a terminal they do not own.

A command-line program prints its output once and leaves it in the scrollback, at the width of the terminal or of the destination it writes to. It shares the terminal with the shell and the programs around it, and its output may as well go to a pipe or a file. This library holds what such a program decides and lays out, and does no I/O. Matrix_cli_unix writes to the standard outputs with it, redraws a region of rows below the output while the program works, and asks questions at the terminal.

Each destination has a styling (Ansi.Styling.t), which says how the styles a program writes reach it, in colors of some depth, as attributes such as bold without colors, or not at all. Ansi.Styling.decide decides it from the program's choice, the user's environment and the terminal, and Progress decides how the program's progress shows there. An adapter rewrites what a program prints for a styling (Adapting what a program prints), so that printers written for any destination, such as Fmt's, obey the decision. Table and Tree lay out tables and trees. Each is a function of plain values that draws into a grid of cells (Matrix_grid), so a program prints the result with Matrix_grid.to_ansi at its destination's styling, or with Matrix_cli_unix.print_grid, and a full-screen program can draw the same layout into its own frame.

This prints a word in bold red on standard output, as the environment decides for a terminal, where caps are the terminal's capabilities (Matrix_terminal.Caps.derive):

let styling =
  Ansi.Styling.decide Sys.getenv_opt ~tty:(Unix.isatty Unix.stdout)
    ~dumb:caps.dumb caps.colors
in
let a = Matrix_cli.adapter styling in
print_string (Matrix_cli.adapt a "\027[1;31mdone\027[0m\n")
Sourcemodule Progress : sig ... end

How a program's progress shows on a destination.

Adapting what a program prints

A program prints through printers written for any destination, such as Fmt's, which write SGR for colors and attributes when they are asked to. An adapter rewrites the bytes a program prints for a destination of a styling. It writes the styles the program's SGR selects at the styling, so a 24-bit color becomes the nearest of 256 or of 16, `Mono keeps the attributes and `Plain the text alone, and it keeps hyperlinks (OSC 8) unless the styling is `Plain. It drops every other control function but HT and the line ends. A line ends at CR, VT, FF and NEL as at LF, and a run of CRs with the line end after it ends one line. So nothing printed through an adapter moves the cursor up or back along its row. A style is written just before the text it applies to, and closed at each line end and at the end of each piece adapted, so each piece shows the same whatever is written after it. Text from someone else, such as a file name, goes through Ansi.sanitize first, which also removes the characters that reorder or hide text.

Sourcetype adapter

The type for adapters. An adapter is mutable and must not be used by two threads in parallel.

Sourceval adapter : Ansi.Styling.t -> adapter

adapter styling is an adapter for styling, at the start of a stream.

Sourceval adapt : adapter -> string -> string

adapt a s is s adapted, the next piece of a's stream. A control function that s leaves unfinished is completed by the next piece, and the styles s selects apply to the text of the next pieces.

Sourceval formatter : Ansi.Styling.t -> (string -> unit) -> Format.formatter

formatter styling write is a formatter whose output is adapted to styling and given to write at each flush, one call for each flush after which there is something to write. So a record a printer flushes, such as a Logs message or Fmt's "@.", is one write. Its margin is Format's default, which a program sets to its destination's width.

Sourcemodule Table : sig ... end

Tables, how their columns share a width and where their rows and cells go.

Sourcemodule Tree : sig ... end

Trees, the guides that draw them one node per line.