package matrix

Build not yet checked
  1. Overview
  2. Docs
Fast, modern terminal toolkit for OCaml

Install

dune-project
 Dependency

Authors

Maintainers

Sources

mosaic-0.3.0.tbz
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3

doc/matrix.input/Matrix_input/Keystroke/index.html

Module Matrix_input.KeystrokeSource

Keystrokes, each with one value whatever the terminal's encoding.

Keystrokes, each with one value whatever the terminal's encoding.

A chord is a key pressed while Ctrl, Alt, Super, Hyper or Meta is held. A terminal reports a key in one of several encodings, and each carries its own set of facts:

  • legacy bytes send the text a key types, a C0 control for Ctrl with a letter, and an ESC before either for Alt;
  • xterm's control sequences encode keys that type nothing, such as CSI A or CSI 1 ; 5 A, whose second parameter is 1 plus a mask of modifiers, and SS3 forms such as ESC O P (xterm's Control Sequences, "PC-Style Function Keys");
  • xterm's modifyOtherKeys, CSI 27 ; m ; code ~, encodes the chords that legacy bytes cannot tell apart;
  • the kitty keyboard protocol sends CSI code:shifted:base ; m:event ; text u.

A keystroke here has the one value that every encoding carrying the same facts agrees on. When an encoding cannot carry a fact, the value leaves it out, and the sections below state each such loss where it occurs. A binding is a program's test of whether a keystroke is a given key or chord.

This binding matches Ctrl+s whatever the encoding and the state of the locks:

let is_save (k : Keystroke.t) =
  k.key = Keystroke.Char (Uchar.of_char 's')
  && k.mods.ctrl
  && not (k.mods.alt || k.mods.super || k.mods.hyper || k.mods.meta)

Characters

Char c is a key that types a character, and c is the character typed, with Shift and the keyboard layout applied. Shift+a is Char 'A', and Shift+4 on a US layout is Char '$'. Legacy bytes and modifyOtherKeys carry that character. The kitty protocol carries it in the shifted key it reports with its "report alternate keys" enhancement, and in the text it reports with a key that types one character when it sends every key as a sequence ("report associated text"). Shift is then consumed, in the sense that shift is set on a Char only when Shift did not change the character, as for Shift+Space. A binding for Ctrl+Shift+g therefore matches Char 'G' with ctrl.

The kitty protocol without that enhancement carries less. Its key code is "always the lower-case (or more technically, un-shifted) version of the key" (kitty keyboard protocol, "Key codes"), so Ctrl+Shift+1 arrives as Char '1' with ctrl and shift, where every other encoding gives Char '!' with ctrl. The value is then that key with shift, since the bytes do not carry the character typed.

Locks

Lock keys never change a chord's key. A character typed with Caps Lock on arrives as text with the lock already applied, so the Char is what was typed. Caps Lock with r is Char 'R', from the byte R or from the kitty protocol's CSI 114 ; 65 ; 82 u, whose text is R. In a chord the lock changes nothing. Ctrl+s is Char 's' with ctrl whatever Caps Lock's state, as xterm sends it (0x13) and as the kitty protocol does (CSI 115 ; 69 u), and caps_lock says the lock is on. The kitty protocol reports the lock bits on chords and legacy bytes never do, so a binding must ignore caps_lock and num_lock. Legacy bytes lose this fact under Alt. With Caps Lock on, Alt+a arrives as ESC A, Char 'A' with alt, and Alt+Shift+a as ESC a, because the terminal applies the lock to the character before it adds the ESC.

Controls

Legacy bytes send Ctrl with a key as a C0 control (kitty keyboard protocol, "Legacy ctrl mapping of ASCII keys"). 0x01..0x1A are Ctrl+a..z, 0x00 is Ctrl+Space, and 0x1C..0x1F are Ctrl+\\, Ctrl+], Ctrl+^ and Ctrl+_. Four controls are named keys, because legacy bytes cannot tell them from a chord. 0x09 is Tab (also Ctrl+i), 0x0D Enter (Ctrl+m), 0x1B Escape (Ctrl+[), and 0x08 and 0x7F are Backspace (0x08 is also Ctrl+h, and Ctrl+Backspace in some terminals). 0x0A is Ctrl+j. Enter sends 0x0D, but a terminal device that translates carriage returns on input (the termios flag ICRNL, set unless the terminal is in raw mode) delivers Enter as 0x0A, and Enter then arrives as Ctrl+j. Legacy bytes also lose Shift under Ctrl (Ctrl+Shift+a is Ctrl+a), and some chords alias a control (Ctrl+2 is Ctrl+Space). Under the kitty protocol's disambiguation all of these are distinct.

The keypad

keypad is set when the encoding says the key is on the numeric keypad, as the kitty protocol's keypad codes and xterm's application keypad (the SS3 forms of xterm's "PC-Style Function Keys") do. Legacy bytes send a keypad key as its main-keyboard equivalent ("All keypad keys are reported as their equivalent non-keypad keys", kitty keyboard protocol, "Legacy functional keys"), so the fact is absent there, and keypad 8 without Num Lock is Up without keypad. A binding ignores keypad unless it means the keypad. Begin, the keypad's 5 without Num Lock, exists only on the keypad and always has keypad.

Modifiers

Sourcetype mods = {
  1. shift : bool;
  2. alt : bool;
    (*

    Alt, or Option on a Mac. It is the kitty protocol's alt bit, xterm's Alt, and an ESC before a key.

    *)
  3. ctrl : bool;
  4. super : bool;
    (*

    The Windows or Command key. xterm's table names the bit worth 8 Meta; the kitty protocol, which reuses the same parameter, names it Super, and this is that bit.

    *)
  5. hyper : bool;
  6. meta : bool;
    (*

    A Meta key distinct from Alt, which only the kitty protocol reports (its bit worth 32).

    *)
  7. caps_lock : bool;
    (*

    Caps Lock is on, whether or not its key is held.

    *)
  8. num_lock : bool;
    (*

    Num Lock is on, whether or not its key is held.

    *)
}

The type for modifiers. The kitty protocol and xterm encode them as one parameter, 1 plus the sum of shift 1, alt 2, ctrl 4, super 8, hyper 16, meta 32, caps_lock 64 and num_lock 128 (kitty keyboard protocol, "Modifiers").

Sourceval no_mods : mods

no_mods is the modifiers with every field false.

Keys

Sourcetype media =
  1. | Play
  2. | Pause
  3. | Play_pause
  4. | Reverse
  5. | Stop
  6. | Fast_forward
  7. | Rewind
  8. | Track_next
  9. | Track_previous
  10. | Record
  11. | Volume_down
  12. | Volume_up
  13. | Mute

The type for media keys (kitty keyboard protocol, "Functional key definitions").

Sourcetype modifier =
  1. | Left_shift
  2. | Left_ctrl
  3. | Left_alt
  4. | Left_super
  5. | Left_hyper
  6. | Left_meta
  7. | Right_shift
  8. | Right_ctrl
  9. | Right_alt
  10. | Right_super
  11. | Right_hyper
  12. | Right_meta
  13. | Level3_shift
    (*

    ISO level 3 shift, AltGr on many layouts.

    *)
  14. | Level5_shift
    (*

    ISO level 5 shift.

    *)

The type for modifier keys pressed or released on their own, which the kitty protocol reports with its "report all keys as escape codes" enhancement.

Sourcetype key =
  1. | Char of Uchar.t
    (*

    A key that types a character (Characters).

    *)
  2. | Enter
  3. | Tab
  4. | Backspace
  5. | Escape
  6. | Up
  7. | Down
  8. | Left
  9. | Right
  10. | Home
  11. | End
  12. | Page_up
  13. | Page_down
  14. | Insert
  15. | Delete
  16. | Begin
    (*

    The keypad's 5 without Num Lock.

    *)
  17. | F of int
    (*

    A function key: F1..F20 from xterm's forms, F1..F35 from the kitty protocol.

    *)
  18. | Print_screen
  19. | Pause
  20. | Menu
  21. | Scroll_lock
  22. | Caps_lock
  23. | Num_lock
  24. | Media of media
  25. | Modifier of modifier
  26. | Unidentified of int
    (*

    A code in the kitty protocol's functional range, 57344..63743, that names none of the keys above.

    *)

The type for keys.

Keystrokes

Sourcetype release = {
  1. key : key;
  2. mods : mods;
    (*

    For a modifier key, the state after the release. Releasing Left Ctrl clears ctrl unless Right Ctrl is still held.

    *)
  3. base : Uchar.t option;
  4. keypad : bool;
}

The type for key releases. Only the kitty protocol reports them, with its "report event types" enhancement. A release types nothing, so it has no text.

Sourcetype t = {
  1. key : key;
  2. mods : mods;
  3. text : string;
    (*

    What the key types, as UTF-8. It is the kitty protocol's associated text when the key reports one, else the character of a Char. It is "" for a chord, which types nothing, for a control character, for a key other than a Char that reports no text, and when the encoding does not carry the character typed.

    *)
  4. base : Uchar.t option;
    (*

    The key at the same place on a US PC-101 layout, when the terminal reports it (the kitty protocol's base layout key). Ctrl+С on a Cyrillic layout has base = Some 'c', so a binding for Ctrl+c can match it.

    *)
  5. keypad : bool;
    (*

    The encoding says the key is on the keypad (The keypad).

    *)
  6. repeat : bool;
    (*

    The terminal reports an auto-repeat (the kitty protocol's event types). The other encodings send a repeat as a press, with repeat false.

    *)
}

The type for key presses.

Sourceval make : ?mods:mods -> ?text:string -> ?base:Uchar.t -> ?keypad:bool -> ?repeat:bool -> key -> t

make key is a press of key. mods defaults to no_mods, base to None, keypad and repeat to false, and text to what the key types as a decoder reports it: the character of a Char that is not a control, when no Ctrl, Alt, Super, Hyper or Meta is held, and "" otherwise.

Sourceval is_interrupt : t -> bool

is_interrupt k is true iff k is Ctrl+C, the key a terminal in cooked mode turns into SIGINT (its VINTR character): Ctrl with c, Shift allowed (the kitty protocol may report C), or with a key whose base is c, and no other modifier. In raw mode the terminal sends it as this key, and the application decides what it means.

Encoding

A terminal sends a keystroke in the encoding its program has asked for. Its keyboard state (encoding) is what decides the bytes. xterm's DECCKM and DECKPAM select the application forms of the cursor keys and of the keypad (SS3), LNM has Enter send CR LF, and then come xterm's modifyOtherKeys level and the kitty protocol's enhancement flags.

With a flag that disambiguates (1) or reports every key as a sequence (8), the kitty protocol decides, as its "Progressive enhancement" section says. Otherwise legacy bytes decide, with xterm's sequences for the keys that type nothing. modifyOtherKeys then sends CSI 27 ; m ; code ~ for the chords of a character, Enter, Tab, Backspace and Escape: at level 1 for a chord whose legacy bytes Decoder would read as another keystroke, and from level 2 for every one. A key the kitty protocol numbers is typed on a US PC-101 layout, so the code of Char '$' is 4's, with Shift held.

Decoder reads encode e k back as k, less the facts that e cannot carry, which the sections above list.

Sourcetype encoding = {
  1. cursor_keys : bool;
    (*

    DECCKM: unmodified cursor keys send SS3 forms.

    *)
  2. keypad : bool;
    (*

    DECKPAM: the keypad sends its application forms.

    *)
  3. new_line : bool;
    (*

    LNM: Enter sends CR LF.

    *)
  4. modify_other_keys : int;
    (*

    xterm's modifyOtherKeys level, 0 when off.

    *)
  5. kitty : int;
    (*

    The kitty protocol's enhancement flags, 0 when off.

    *)
}

The type for keyboard states.

Sourceval legacy : encoding

legacy is a terminal's keyboard state at power-up, with every field off.

Sourceval encode : encoding -> t -> string

encode e k is the bytes a terminal in the keyboard state e sends for k. A repeat is sent as a press unless e asks the kitty protocol for event types (flag 2).

Raises Invalid_argument if no terminal in e sends k: a Char that is a control character, a key above F20 or one with no xterm sequence (a lock key, Print_screen, Pause, Menu, a media, modifier or unidentified key) without the kitty protocol, a key above F35, a modifier key unless every key is a sequence (flag 8), or an unidentified key outside the kitty protocol's functional range.

Sourceval encode_release : encoding -> release -> string

encode_release e r is the bytes a terminal in e sends for r. It is "" unless e asks the kitty protocol for event types (flag 2), and for a key whose press goes as legacy bytes (a key that types text, and Enter, Tab and Backspace unmodified, unless every key is a sequence), whose release the protocol does not report.

Raises Invalid_argument as encode does.

Formatting

Sourceval pp_key : Format.formatter -> key -> unit

pp_key ppf k formats k for debugging, as in 'a', U+0001, Enter and F 5.

Sourceval pp : Format.formatter -> t -> unit

pp ppf k formats k for debugging as its modifiers and key, such as Ctrl+Shift+Up, followed by each other field that differs from its default.

Sourceval pp_release : Format.formatter -> release -> unit

pp_release ppf r formats r as pp formats a press.