class

Termisu::Input::Parser

Inherits Reference / Object

Input parser for terminal escape sequences.

Parses raw terminal input into structured Event objects. Supports CSI sequences (arrows, function keys, nav), SS3 sequences, Alt+key combinations, Ctrl+key combinations, and mouse events.

Example:

parser = Termisu::Input::Parser.new(reader)
if event = parser.poll_event(1000)
  puts "Got event: #{event}"
end

Constants

CSI_KEYS = {'A' => Key::Up, 'B' => Key::Down, 'C' => Key::Right, 'D' => Key::Left, 'H' => Key::Home, 'F' => Key::End, 'Z' => Key::BackTab, 'P' => Key::F1, 'Q' => Key::F2, 'R' => Key::F3, 'S' => Key::F4}

CSI final character to Key mapping.

ESCAPE_TIMEOUT_MS = 50

Timeout in milliseconds to distinguish ESC key from escape sequences. 50ms matches termbox/tcell behavior.

KITTY_CODEPOINTS = {27 => Key::Escape, 13 => Key::Enter, 9 => Key::Tab, 127 => Key::Backspace, 8 => Key::Backspace, 57358 => Key::CapsLock, 57359 => Key::ScrollLock, 57360 => Key::NumLock, 57361 => Key::PrintScreen, 57362 => Key::Pause, 57376 => Key::F13, 57377 => Key::F14, 57378 => Key::F15, 57379 => Key::F16, 57380 => Key::F17, 57381 => Key::F18, 57382 => Key::F19, 57383 => Key::F20, 57384 => Key::F21, 57385 => Key::F22, 57386 => Key::F23, 57387 => Key::F24}

Kitty protocol codepoint to Key mapping for special keys. These codepoints are specific to the Kitty keyboard protocol.

LINUX_CONSOLE_KEYS = {"[[A" => Key::F1, "[[B" => Key::F2, "[[C" => Key::F3, "[[D" => Key::F4, "[[E" => Key::F5}

Linux console function keys use \e[[A through \e[[E.

Log = Termisu::Logs::Input
MAX_SEQUENCE_LENGTH = 32

Maximum escape sequence length before giving up.

MOUSE_MOTION_BIT = 32

Mouse protocol bit mask for motion events (bit 5). When set, indicates mouse moved while button was held.

PASTE_END_TAIL = "[201~".bytes

The bytes that follow ESC in the end marker, matched literally.

Inside a paste the terminator is found by comparing raw bytes, never by parsing an escape sequence. Two ways the parsing route loses it: the fd can run dry at the marker's ESC and the rest arrive after ESCAPE_TIMEOUT_MS (the ESC then resolves as a bare Escape and [201~ lands as text), and paste CONTENT ending in a truncated escape can swallow the marker's ESC into its own Alt-key or CSI-parameter branch. Both wedge a consumer that tracks PasteStart/PasteEnd as a boolean, since the mode never closes.

PASTE_END_TIMEOUT_MS = 1000

How long to wait for the rest of the end marker once its ESC has arrived.

Deliberately not ESCAPE_TIMEOUT_MS: that value exists to tell a lone Escape KEYPRESS from a sequence, a distinction a paste has already settled — the terminal opened the bracket and owes us the close. It only has to outlast scheduling jitter on the tail of a transfer (ssh/mosh, a loaded machine), which 50ms does not. Bounded rather than infinite so a terminal that dies mid-paste degrades to delivering the bytes as content instead of hanging.

PASTE_KEYS = {200 => Key::PasteStart, 201 => Key::PasteEnd}

Bracketed paste boundary codes, also delivered as \e[N~ sequences.

Kept out of TILDE_KEYS because they are not keystrokes: they only mark where a paste begins and ends. A terminal sends them exclusively while DEC private mode 2004 is on (see Terminal#enable_bracketed_paste), which is why an application that never enables the mode cannot observe them.

SS3_KEYS = {'P' => Key::F1, 'Q' => Key::F2, 'R' => Key::F3, 'S' => Key::F4, 'A' => Key::Up, 'B' => Key::Down, 'C' => Key::Right, 'D' => Key::Left, 'H' => Key::Home, 'F' => Key::End}

SS3 final character to Key mapping (\eO...).

TILDE_KEYS = {1 => Key::Home, 2 => Key::Insert, 3 => Key::Delete, 4 => Key::End, 5 => Key::PageUp, 6 => Key::PageDown, 7 => Key::Home, 8 => Key::End, 11 => Key::F1, 12 => Key::F2, 13 => Key::F3, 14 => Key::F4, 15 => Key::F5, 17 => Key::F6, 18 => Key::F7, 19 => Key::F8, 20 => Key::F9, 21 => Key::F10, 23 => Key::F11, 24 => Key::F12, 25 => Key::F13, 26 => Key::F14, 28 => Key::F15, 29 => Key::F16, 31 => Key::F17, 32 => Key::F18, 33 => Key::F19, 34 => Key::F20}

Tilde sequence code to Key mapping (\e[N~ format).

Maps numeric codes from CSI tilde sequences to keys. Codes 1-8 are navigation keys, 11-24 are function keys F1-F12. Codes 25-34 are extended function keys F13-F20 (rarely used).

Note: Some codes are skipped (9-10, 16, 22, 27, 30) for historical terminal compatibility reasons. Codes 1/7 and 4/8 are duplicates (Home/End) because different terminals use different codes.

Reference: XTerm ctlseqs, VT220 sequences.

Constructors

new(reader : Reader)
Source

Instance methods

poll_event(timeout_ms : Int32 = -1) : Event::Any | Nil

Polls for an input event with optional timeout.

  • timeout_ms - Timeout in milliseconds (-1 for blocking)

Returns an Event or nil if timeout/no data.

Source