package matrix
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3
doc/matrix.cli/Matrix_cli/index.html
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")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.
The type for adapters. An adapter is mutable and must not be used by two threads in parallel.
adapter styling is an adapter for styling, at the start of a stream.
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.
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.
Tables, how their columns share a width and where their rows and cells go.