package matrix
Module Matrix_terminalSource
The modes of a terminal, set by a program and put back when it is done.
A terminal has modes, settings that a program changes by writing control functions to it, such as mouse tracking, bracketed paste or the alternate screen. A handle (t) writes these control functions through an output function that the caller gives, and tracks the modes it has set, so that it writes each change once and reset_state puts back every mode it set. The caller owns all I/O. This library reads no descriptor, waits for nothing, starts no thread and handles no signal, so a program with no operating system under it can use it. The device itself, its settings and its signals belong to Tty.
A handle also holds the terminal's capabilities (Caps), which the caller derives from what the terminal answers and replaces as answers arrive. The handle reads only their multiplexer, to wrap what it writes for the terminal outside the multiplexer.
The life cycle of a handle:
makemakes a handle with the capabilities known so far.- The functions of Modes set modes, and
set_capabilitiesreplaces the capabilities as answers arrive. restore_modeswrites the modes again when the terminal may have reset them, as after the process was stopped and continued.reset_stateputs back every mode the handle set.
Unless a function's doc says otherwise, a function that sets a mode writes its control function only when the mode changes, so a second call with the same value writes nothing. A handle made with ~tty:false writes nothing and tracks the modes all the same. An exception that output raises passes to the caller, and reset_state then still puts back a mode whose control function output was given, since the terminal may have taken it, though the mode's accessor, such as alt_screen, reports it unchanged. A handle must not be used by two threads at once.
This takes the alternate screen and bracketed paste, and puts both back:
let () =
let output s =
print_string s;
flush stdout
in
let caps =
Matrix_terminal.Caps.(
derive (evidence (env Sys.getenv_opt ~win32:Sys.win32)))
in
let t = Matrix_terminal.make ~output caps in
Matrix_terminal.enter_alternate_screen t;
Matrix_terminal.enable_bracketed_paste t true;
Matrix_terminal.reset_state tTypes
The type for mouse tracking modes.
`Offreports nothing.`X10reports presses (mode 9).`Normalreports presses and releases (mode 1000).`Buttonalso reports motion while a button is held (mode 1002).`Anyalso reports motion with no button held (mode 1003).`Sgr_normal,`Sgr_buttonand`Sgr_anyreport as`Normal,`Buttonand`Anydo, in the SGR encoding (mode 1006).`Sgr_normalsets modes 1006 and 1000,`Sgr_buttonalso 1002, and`Sgr_anyalso 1003.
In the modes without SGR the terminal reports each coordinate in one byte, so it reports columns and rows up to 223.
The type for the cursor state a handle tracks. x is the column and y the row of the last move_cursor, both from 1, and visible is the visibility last set.
Capabilities
Handles
The type for handles.
make ~output ~tty caps is a handle that writes through output and holds caps. With ~tty:false (default true) it writes nothing, for an output that is not a terminal or a test. It starts with every mode off, the primary screen, the whole screen as the scrolling region, and the cursor visible at (1, 1) in the block style with the color (1., 1., 1., 1.). It writes nothing and asks the terminal nothing.
Capability access
capabilities t is t's capabilities.
set_capabilities t caps replaces t's capabilities with caps. It writes nothing and changes no mode.
pixel_resolution t is the size of the terminal's text area in pixels, Some (width, height), as set_pixel_resolution last recorded it, or None before it has.
set_pixel_resolution t res records res as t's pixel resolution. It writes nothing.
Modes
Each function below sets or resets one mode, and reset_state resets it if the handle set it.
restore_modes ~skip_focus t writes again the control functions of the modes the handle has set among mouse tracking, focus reporting, bracketed paste, the kitty keyboard flags, modifyOtherKeys, color scheme reports, resize reports and metaSendsEscape, whether or not they changed. It pops the handle's kitty keyboard flags before it pushes them again, so the terminal's stack keeps one entry from the handle. With ~skip_focus:true (default false) it leaves out focus reporting, since a terminal may answer the focus mode with a focus report, and a caller that restores the modes on each focus report would loop.
Mouse tracking
set_mouse_mode t mode sets mouse tracking to mode. When mode differs from the current mode, it first resets every mouse mode, 9, 1000, 1002, 1003, 1015 and 1006, then sets those of mode.
mouse_mode t is the mouse tracking mode last set, initially `Off.
Bracketed paste
enable_bracketed_paste t b sets bracketed paste (mode 2004) if b, and resets it otherwise.
bracketed_paste_enabled t is true iff t has set bracketed paste.
Focus reporting
enable_focus_reporting t b sets focus reporting (mode 1004) if b, and resets it otherwise.
focus_reporting_enabled t is true iff t has set focus reporting.
Kitty keyboard
enable_kitty_keyboard ~flags t b pushes flags on the terminal's stack of kitty keyboard flags if b, and pops the handle's entry otherwise. flags defaults to 0b00101, and its bits are
- bit 0, disambiguate escape codes;
- bit 1, report event types (press, repeat and release);
- bit 2, report alternate keys;
- bit 3, report all keys as escape codes;
- bit 4, report associated text.
A push while the handle has other flags pushed pops them first, so the handle has at most one entry on the stack and one pop removes it.
kitty_keyboard_enabled t is true iff t has pushed kitty keyboard flags.
modifyOtherKeys
enable_modify_other_keys t b sets xterm's modifyOtherKeys to 1 (CSI > 4 ; 1 m) if b, and to 0 otherwise.
modify_other_keys_enabled t is true iff t has set modifyOtherKeys.
Reports and Alt
enable_color_scheme_reports t b sets color scheme reports (mode 2031) if b, and resets them otherwise. While they are set, the terminal sends CSI ? 997 ; 1 n (dark) or CSI ? 997 ; 2 n (light) when its scheme changes.
enable_resize_reports t b sets in-band resize reports (mode 2048) if b, and resets them otherwise. While they are set, the terminal sends CSI 48 ; rows ; cols ; height ; width t once when the mode is set and on every resize.
enable_meta_sends_escape t b sets xterm's metaSendsEscape (mode 1036) if b, and resets it otherwise. While it is set, Alt with a key sends ESC and then the key. A caller must set it only where the terminal has it reset (Caps.t.meta_sends_escape is Some false), since reset_state resets it.
Unicode width
enable_grapheme_mode t b sets the terminal's grapheme cluster mode (mode 2027) if b, and resets it otherwise. A caller must set it only where the terminal has it reset (Caps.t.grapheme_mode is Some false), since reset_state resets it.
Alternate screen
enter_alternate_screen t switches to the alternate screen (DECSET 1049).
leave_alternate_screen t switches back to the primary screen (DECRST 1049).
Scrolling region
set_scroll_region t ~top ~bottom sets the scrolling region (DECSTBM) to the rows top to bottom, from 1.
Raises Invalid_argument if top < 1 or bottom <= top, even when t writes nothing.
clear_scroll_region t makes the whole screen the scrolling region.
scroll_region t is the scrolling region t has set, Some (top, bottom), or None for the whole screen.
Cursor and appearance
The write_ functions append to a writer that the caller writes out later, as part of a frame. They append for a handle made with ~tty:false too, and change none of the cursor state the handle tracks.
move_cursor ~visible t ~row ~col moves the cursor to row and col, from 1, each raised to 1 if smaller, and records the position (cursor_position). It first shows or hides the cursor as visible says (default true), as set_cursor_visible does. It writes the move even when the cursor is there already.
set_cursor_visible t b shows the cursor if b and hides it otherwise (DECTCEM).
cursor_position t is the position of the last move_cursor, initially (1, 1), with the visibility last set.
set_cursor_style t style ~blinking records the cursor's style and blinking, writes them (DECSCUSR), and has reset_state put back the default shape. A terminal keeps the style while the cursor is hidden and shows it with the cursor. It writes every time.
cursor_style_state t is the cursor's style and blinking last recorded, initially (`Block, false).
set_cursor_color t ~r ~g ~b ~a records the cursor's color, with components from 0.0 to 1.0, writes it (OSC 12), each component clamped to that range and nan taken as 0.0, and has reset_state put back the default color. A terminal keeps the color while the cursor is hidden and shows it with the cursor. a is recorded and never written. It writes every time.
cursor_color t is the cursor's color last recorded, (r, g, b, a) as given, initially (1., 1., 1., 1.).
reset_cursor_color t gives the cursor the terminal's default color (OSC 12 with "default", then OSC 112), and records (1., 1., 1., 1.).
write_cursor_style t ~shape w appends to w the control function that gives the cursor shape (DECSCUSR), and has reset_state put back the default shape.
write_cursor_color t color w appends to w the control function that gives the cursor color (OSC 12), each component clamped to 0 to 255, and has reset_state put back the default color. With None, it appends the control functions of reset_cursor_color, and reset_state still puts back the default color, since the writer's bytes may never reach the terminal.
set_title t s sets the window title and the icon name to s (OSC 0). The first set_title of a handle, or the first after reset_state, first pushes the title and icon name the terminal has on its title stack (XTWINOPS CSI 22 ; 0 t), and has reset_state pop them back (CSI 23 ; 0 t). A terminal without the stack keeps the empty title that reset_state sets before it pops. s must hold no control character, since s is written as it is and one would end the control function early.
copy_to_clipboard t s asks the terminal to set the clipboard to s (OSC 52, with s in base64). Inside tmux (Caps.t.multiplexer) it wraps the request for tmux's passthrough. Inside GNU screen it cuts the request into DCS strings of at most 252 bytes each, which screen passes to the terminal outside.
notify t ~title ~body posts one desktop notification, in the form the terminal shows (Caps.t.notification). Inside tmux it wraps it for tmux's passthrough. title and body must hold no control character and title no ;, since they are written as they are.
query_color_scheme t asks the terminal for its color scheme (CSI ? 996 n). A terminal that knows the query answers CSI ? 997 ; 1 n (dark) or CSI ? 997 ; 2 n (light), which decodes as Matrix_input.Reply.t.Color_scheme.
query_pixel_resolution t asks the terminal for the size of its text area in pixels (CSI 14 t). The answer decodes as Matrix_input.Reply.t.Text_area_pixels.
Output and state
send t s writes s through output, and nothing for a handle made with ~tty:false. Whoever reads the terminal's input must expect the answer to a query sent so (Matrix_input.Decoder.expect), since a reply that is a control string, such as XTVERSION's, otherwise decodes as typed keys.
reset_state t puts back every mode t has set. It always shows the cursor and resets the SGR attributes. Of the rest, it puts back only what the handle changed. It gives the cursor its default color and shape, pops the handle's kitty keyboard flags, sets modifyOtherKeys to 0, and resets mouse tracking, bracketed paste, focus reporting, color scheme reports, resize reports, metaSendsEscape and grapheme cluster mode. It makes the whole screen the scrolling region and leaves the alternate screen. If the handle set the window title, it sets the title to "", then pops the one the handle replaced (set_title). The handle then tracks the state make gives, but for its capabilities, its pixel resolution and its cursor position.