package matrix
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3
doc/matrix.terminal/Matrix_terminal/Caps/index.html
Module Matrix_terminal.CapsSource
Terminal capabilities, derived from evidence.
Terminal capabilities, derived from evidence.
The capabilities of a terminal (t) are the facts a program needs about it, such as whether it shows 24-bit color or reports focus changes. They are learned from three sources. An answer is what the terminal that does the work, the one that draws the screen and reads the keyboard, replies to a query. Inside a multiplexer that is the multiplexer. An identity is the name and version of the terminal, which it reports or the environment names. A guess comes from the environment alone. The sources disagree, and an answer can arrive late, so the capabilities are a function, derive, of the evidence gathered so far (evidence), and a later answer can take back what an earlier guess gave.
A program learns the capabilities in these steps:
envreads the environment once, andevidencemakes the evidence before any answer.askgives the bytes of the first batch of queries,Probe, which the program writes to the terminal, and ofWidths, which it writes on rows it owns.- The program adds each reply to the evidence with
add,cursorandanswered, andderivegives the capabilities so far. nextgives the batch to send after an answered one, until it isNone.
This is what the environment alone gives, before the terminal answers:
let caps =
Matrix_terminal.Caps.(
derive (evidence (env Sys.getenv_opt ~win32:Sys.win32)))Precedence
Each fact is taken from the first source that has it:
- User policy, which the person running the program decides.
MATRIX_FORCE_UNICODEandMATRIX_FORCE_WCWIDTHset the width method,MATRIX_GRAPHICShow pictures are sent (graphics), andVHS_RECORD(a recording) asks for the plain widths and no kitty protocols. - Corrections keyed on the terminal's identity, for a terminal that answers but is known to do otherwise, each with its reason. Ghostty from 1.3 widens graphemes past what mode 2027 describes, and Konsole draws sixel in a way pictures cannot use (
graphics). - The answer of the terminal that does the work.
- Identity, what a terminal of that name and version is known to do.
- Guesses from the environment,
TERM,COLORTERM, the platform and the description the terminfo database has forTERM(env). A description only ever adds a fact, direct color (RGB,Tc, orsetrgbfwithsetrgbb), 256 colors (colors), bracketed paste (BE), focus reporting (fe), synchronized output (Syncas mode 2026) or an eager wrap (amwithoutxenl). Descriptions leave out direct color and synchronized output for most terminals that have them, and a terminal other than the oneTERMnames (over ssh, or in a multiplexer) may have no description here, so a description's silence takes nothing away. - The default,
false,None,`Ansi16or`Wcwidth, or the facts the caller assumes in place of the environment (assume).
Inside tmux, questions about drawing and keys go to tmux itself, which answers or stays silent. tmux answers no mode query before 3.6, and none for mode 2026 before 3.7, so its facts then come from its identity, by version. It brackets the pastes it passes to a pane from 1.7 and handles focus reporting from 1.8, and it synchronizes a pane's output from 3.7. It has no mode 2027. A question about the terminal outside, such as kitty graphics, which tmux passes through untouched, is wrapped for tmux's passthrough, and only once passthrough is known to be on. tmux drops wrapped queries unless its allow-passthrough option is set, which it is not by default since 3.3.
The environment describes the terminal the process started in, which is not always the one it talks to. TERM_PROGRAM survives into ssh sessions, GNU screen, zellij and tmux. So the environment gives an identity only when the terminal is directly attached, that is, when none of SSH_CONNECTION, SSH_CLIENT, SSH_TTY, TMUX, STY and ZELLIJ is set and TERM starts with none of tmux, screen and zellij. An identity the terminal reports itself (XTVERSION) is an answer and holds everywhere.
Batches
Queries go in batches, each ending with a primary device attributes query (DA1), which every terminal answers, but for Widths, which its last cursor position report answers. A terminal answers in order, so the DA1 reply says that the batch has been answered. The kitty keyboard protocol states it as "If an answer for the device attributes is received without getting back an answer for the progressive enhancement the terminal does not support this protocol" ("Detection of support"). A query still silent when its batch's DA1 reply comes is answered "no" where its protocol says so (kitty graphics), and stays unknown otherwise, since a terminal without DECRQM says nothing of its modes. The program writes the batches, waits for their DA1 replies and passes the replies here.
Capabilities
type t = {colors : [ `Ansi16 | `Ansi256 | `Truecolor ];(*The colors the terminal shows, the 16 of its palette's first entries, the 256 of its whole palette, or any 24-bit color. No query tells it. 24-bit color comes from kitty's identity, a
*)COLORTERMoftruecoloror24bit, aTERMthat ends in-direct, a Windows console, or the description's direct color. 256 colors come from aTERMthat contains256color, or a description with 256 colors or more (colors). Any other terminal gets 16.dumb : bool;(*The terminal performs no control function and shows only text, as a printer does.
*)TERMsays so when it is unset,dumborunknown, outside a Windows console, which has noTERM.eager_wrap : bool;(*The terminal moves the cursor to the next line as soon as it prints a character in the last column, where a VT100 waits for the next character, so that a line as wide as the screen and its line end take one row. The description says so with
*)amand withoutxenl(terminfo(5), "Glitches and Brain Damage"). A Windows console waits, sinceTty.enable_vthas it wait. A program that must keep the cursor on its row writes nothing in the last column of such a terminal.lifts_resting_cursor : bool;(*When its width changes, the terminal moves a cursor that rests in the first column of a row other than its first up to the row above, so the next line printed lands on the line before it. WezTerm does (its issue 7994, "Width resize corrupts cursor position when it is at column 0 on a non-first line"), so its identity, or a
*)TERMthat names it, gives this. A program that keeps the cursor on a row of its own rests it in the second column of such a terminal.kitty_keyboard : int option;(*
*)Some flagswhen the terminal has answered the kitty keyboard protocol's query, with the enhancement flags it last reported. It isNoneunderVHS_RECORD.kitty_graphics : bool;(*The kitty graphics protocol, from the answer to its query or kitty's identity. Silence before the DA1 reply of the batch that asked says the terminal does not have it.
*)bracketed_paste : bool;(*Bracketed paste (mode 2004), from the mode's report, kitty's identity, tmux from 1.7, a Windows console, or the description's
*)BE.focus_tracking : bool;(*The terminal handles focus reporting (mode 1004), from the mode's report, tmux from 1.8, or the description's
*)fe. When reports come is up to the terminal. tmux sends a pane the focus changes only while itsfocus-eventsoption is on.unicode_width : Matrix_text.width_method;(*How the terminal measures text, which its answer for mode 2027 (grapheme cluster mode, "Unicode in Terminals") tells, as a DECRPM setting (VT510). Set, permanently set and reset give
*)`Unicode, since a terminal that answers reset has the mode and a program can set it (grapheme_mode). Permanently reset gives`Wcwidth, since with the mode off a terminal behaves "as if this specification was not implemented at all". A terminal that answers "not recognized", or does not answer, does not have the mode and measures each character by itself, as wcwidth does, so it gets`Wcwidthunless its identity orTERMsays otherwise. kitty answers "not recognized" and places grapheme clusters, so its identity gives`Unicode.grapheme_mode : bool option;(*Mode 2027 as the terminal answered.
*)Some falsesays the mode is reset and a program can set it. A program must set it only then, sinceMatrix_terminal.reset_stateresets it.Some truesays the mode is set or permanently set.Nonewhen the terminal does not have the mode, has it permanently reset, or has not answered.sgr_pixels : bool;(*SGR pixel mouse reports (mode 1016), from the mode's report.
*)color_scheme_updates : bool;(*Color scheme change reports (mode 2031), from the mode's report.
*)explicit_width : bool;explicit_cursor_positioning : bool;(*The terminal may measure a grapheme otherwise than the program, so a renderer places the cursor after each wide grapheme. It comes from the identity of tmux or alacritty, or from any multiplexer.
*)scaled_text : bool;sixel : bool;graphics : [ `Kitty | `Sixel | `Blocks ];(*How the terminal is sent pictures (
*)Matrix_screen).MATRIX_GRAPHICSset tokitty,sixelorblocksdecides it. Otherwise it is`Kittywhen the terminal that does the work, or the terminal outside tmux through its passthrough, haskitty_graphicsand is kitty from 0.28 or Ghostty, the terminals known to draw the protocol's Unicode placeholders. It is`Sixelwhen the terminal hassixel, answers at least 252 color registers toProbeor does not answer their query, and is not Konsole, which erases the text under an image and deletes the image when text lands on its top row. It is`Blocksotherwise.sync : bool;(*Synchronized output (mode 2026), from the mode's report, tmux from 3.7, the identity of Ghostty, kitty, WezTerm, Alacritty or iTerm, a
*)TERMthat names one of them, or the description'sSync.hyperlinks : bool;(*OSC 8 hyperlinks. No query tells it. It comes from the identity of tmux, Ghostty, kitty, WezTerm, Alacritty or iTerm, a
*)TERMthat names one of the five terminals, aCOLORTERMoftruecoloror24bit, or a Windows console.notification : [ `Osc9 | `Osc777 ];(*The form of desktop notification the terminal shows. No query tells it. iTerm2's OSC 9 is the one most terminals read: iTerm2, kitty ("kitty also supports the legacy OSC 9 protocol developed by iTerm2", its "Desktop notifications"), WezTerm and foot (their lists of escape sequences). rxvt-unicode reads only OSC 777, an extension of its own, so a
*)TERMthat starts withrxvtgives`Osc777. Any other terminal gets`Osc9.meta_sends_escape : bool option;(*xterm's metaSendsEscape (mode 1036) as the terminal answered.
*)Some falsesays the mode is reset and a program can set it. A program must set it only then, sinceMatrix_terminal.reset_stateresets it. While the mode is reset, Alt sends the key's character with its high bit set.Some truesays the mode is set or permanently set.Nonewhen the terminal does not have the mode, has it permanently reset, or has not answered.multiplexer : [ `Tmux | `Screen ] option;(*The multiplexer between the program and the terminal. When the terminal has answered XTVERSION, it is tmux if the name reported contains
*)tmux, and none otherwise. Before that it is tmux whenTMUXis set, GNU screen whenSTYis set, and else asTERMstarts, withtmuxorscreen.identity : (string * string) option;(*The terminal's name and version, from XTVERSION, or, when the terminal is directly attached, from
*)TERM_PROGRAMandTERM_PROGRAM_VERSION,"kitty"whenKITTY_WINDOW_IDis set, or"termux"withTERMUX_VERSION.
}The type for capabilities.
Environment
The type for the environment variables that bear on capabilities.
env ~terminfo getenv ~win32 is the environment, read once through getenv, such as Sys.getenv_opt, where an empty value counts as unset. terminfo is the description of TERM, if there is one (Tty.terminfo finds it). win32 says the terminal is a Windows console.
variable env name is the value env read for name, one of the variables that decide a styling (Ansi.Styling.variables), and None for any other name. So a run decides its styling (Ansi.Styling.decide) from the environment its capabilities come from.
Evidence
The type for what is known of a terminal, its environment and the answers received so far.
assume caps is evidence with no environment, in which every fact that no answer gives is as caps says.
derive ev is the capabilities ev gives, by the Precedence.
Questions
type batch = | Probe(*The startup batch, to the terminal that does the work. It starts with S7C1T, so that no reply comes with 8-bit controls. It asks for the reports of modes 1016, 2027, 2031, 1004, 2004, 2026 and 1036, XTVERSION, the kitty keyboard flags, and, unless a multiplexer is in the way, kitty graphics, then the cell's size in pixels (
*)CSI 16 t) and the number of sixel color registers (XTSMGRAPHICS), and ends with DA1. It writes nothing on the screen.| Widths(*The measure of text sizing (OSC 66), to the terminal that does the work. It writes two spaces with OSC 66 from the first column of the cursor's row, one of width 1 and one of scale 2, each after a carriage return and followed by a cursor position report. It then returns to the first column and erases from there to the end of the screen. A program must write it with the cursor on a row that it owns with every row below it, at least two, since a space of scale 2 is two rows high.
*)| Passthrough(*DA1 alone, wrapped for tmux, which is answered only when tmux passes it on.
*)| Outer(*Questions about the terminal outside tmux, wrapped for tmux, the kitty graphics query and XTVERSION, then DA1.
*)
The type for batches of queries.
ask ev b is the bytes of b and the replies it owes the decoder (Matrix_input.Decoder.expect).
cursor ev b ~index ~row ~col is ev with the indexth cursor position report that b asked for, from 0, at row and col, from 0.
answered ev b ~attributes is ev once the DA1 that ends b is answered with attributes. What b asked and was not answered is then known not to be there, where its protocol says that silence means so. For Widths, which its last cursor position report answers, answered ev Widths ~attributes is ev.