package matrix
Module Matrix_terminfoSource
Terminal descriptions from the terminfo database.
A terminal description says what a kind of terminal can do and which bytes do it. The kind is named by a terminal type, such as the value of TERM. A description is a set of capabilities, each a boolean, a number or a string. The boolean am says the cursor wraps at the right margin, and xenl that a line feed right after that wrap is ignored. The number colors counts the colors, and the string cup holds the bytes that move the cursor, with the row and the column as parameters. terminfo(5) lists the standard capabilities, and user_caps(5) the user-defined ones that programs agree on, such as RGB (direct color), Smulx (styled underlines) and BE (bracketed paste).
The database is compiled. Each description is a file in one of term(5)'s formats, the legacy one (magic number 0432) or the one of ncurses 6.1 with 32-bit numbers (01036). Either may end with the extended section, which holds the user-defined capabilities and their names. of_string reads such a file. Finding the file for a terminal type is left to Tty.terminfo, so that this library links no unix.
A description is the database's statement about a kind of terminal. It may be missing, as for a new terminal reached over ssh, and it often leaves out what the terminal does, such as direct color. Where a terminal answers a query, its answer is better evidence.
A program reads a description with of_string, reads its capabilities by name (Capabilities), evaluates a string's parameters with expand, and cuts the result at its delays with pieces before it writes it. Every function is pure but expand, which changes the static variables it is given (vars).
This function gives the bytes that move the cursor to row and col, from 0, on a terminal that t describes. For xterm's description, row = 4 and col = 9 give "\027[5;10H":
let cursor_to t ~row ~col =
Option.map
(fun cup -> Matrix_terminfo.(expand cup [ Int row; Int col ]))
(Matrix_terminfo.string t "cup")Descriptions
The type for terminal descriptions.
of_string bytes is the description compiled in bytes, the contents of a file of the database, or Error why, where why says why bytes is not one. A capability that the description cancels reads as absent. The booleans, numbers and strings past the standard ones that the compiled format orders (term.h's) are ignored, as a library older than the database ignores them.
names t is the terminal types t describes, the primary one first. The last of several names is a description in words, such as "xterm with 256 colors".
Capabilities
A capability is named by its short name, terminfo(5)'s "Capname", such as cup for cursor_address, or by its user-defined name, such as RGB. A name has one type, and is read with the function of that type.
number t name is the numeric capability name of t, if t has it.
flags t is the boolean capabilities t has, the standard ones first in the compiled order, then the user-defined ones.
numbers t is t's numeric capabilities, ordered as flags.
strings t is t's string capabilities, ordered as flags.
Parameters
A string capability that takes parameters says how to write them in a small stack language of % codes (terminfo(5), "Parameterized Strings"). xterm's cup is
\E[%i%p1%d;%p2%dH
which adds one to the row and the column (%i), then writes each in decimal. The codes are printf(3)'s conversions %d, %o, %x, %X and %s with their flags, width and precision (%:-5d), %c, %%, the parameters %p1 to %p9, the variables %P and %g, the constants %'c' and %{nn}, %l, the arithmetic, bitwise and logical operators, %i, and the conditional %? c %t then %e else %; with its else-ifs. The static variables A to Z keep their values from one expansion to the next (vars). The dynamic variables a to z start at 0 in each expansion.
Where terminfo(5) leaves a case open, or ncurses' tparm(3x) departs from it, expand does what tparm does, since those are the bytes every curses program sends for the same description.
- Numbers are C ints. Arithmetic wraps at 32 bits,
%/and%mby zero give0, and%o,%xand%Xprint a negative number as unsigned. - A missing stack operand is
0, or""for%sand%l. A string popped as a number is0, and a number popped as a string is"". - The flags
#and space are read anywhere before the conversion, and-only after a:.+is the addition operator in every position. A width or precision over 10000, or a second., drops the flags, the width and the precision. %cof0writes the byte 0200, which a C string can hold. Of another value it writes the low byte.%iadds one to the first two numeric parameters once, however often it is written.%'c'and%{nn}skip the character after the constant, whatever it is, where terminfo(5) puts the closing quote or brace.- An unknown code writes nothing, and a
%that ends the string is dropped. - A string with no
%pcode, as termcap wrote them (\E[%d;%dH), has its parameters pushed for it, at most two, the first on top.%ithen also sets the stack's two lowest slots, from the bottom, to the incremented first and second parameters, so\E[%i%d;%dRon4and9is\E[10;5R.
The type for sets of static variables. A terminal's strings may share them, one setting a variable that another reads (the Wyse 350's sgr and setf do), so a set holds the state of one terminal.
expand ~vars s params is s with its % codes evaluated on params, as the language says. The first parameter is %p1, a parameter not given is 0, and parameters past the ninth are ignored. The static variables are vars, which expand changes, or a fresh set when vars is not given. The delays of s stay in the result (pieces).
Delays
type piece = | Text of string| Delay of {}(*
*)$<ms>in a string. A terminal too slow to keep up needsmsmilliseconds before what follows, times the number of lines the operation affects ifper_line(*). The delay is advisory on a terminal with flow control (xon), unlessmandatory(/), as the pause of the visible bell between reversing the screen and back is.
The type for the parts of a string to send, bytes and delays.