Decoding the Keyboard

The output direction (previous lesson) had a tidy standard. The input direction is messier, because what your program reads in raw mode is whatever bytes the terminal emulator decided to send for each key — a dialect frozen by history, with real variation between terminals. Time to learn it cold, because your editor's first job every loop iteration is turning these bytes back into intent.

One byte: printable keys and the Ctrl story

Letters, digits, punctuation, space: one byte each, exactly the ASCII you expect (multi-byte UTF-8 for non-ASCII — next lesson).

Ctrl+letter is where the teletype heritage shows. Terminals send Ctrl+A through Ctrl+Z as bytes 0x01–0x1A: the letter's ASCII value with bits 6 and 5 stripped — 'A' & 0x1F == 0x01. The Ctrl key was literally a "zero the high bits" key on teletypes. This mapping has consequences you must design around:

• Ctrl+M is 0x0D — the same byte as Enter. You cannot tell them apart. ('M' & 0x1F == 13 == '\r'.)
• Ctrl+I is 0x09 — Tab. Same collision.
• Ctrl+[ is 0x1B — Escape itself. That's why vim users remap Caps Lock: Ctrl+[ is ESC at the byte level.
• In raw mode (ICRNL off), Enter arrives as \r (0x0D), not \n. Programs that forget this wait forever for a newline that never comes.

And the strangest resident of the one-byte world: Backspace sends 0x7F (DEL), not 0x08 (BS), on essentially every modern terminal. Byte 0x08 is what Ctrl+H sends. The reasons are pure archaeology (DEL was the "rub out a punch-tape mistake" character; the VT100 shipped its Backspace key sending DEL), and the upshot is a rule: treat both 0x7F and 0x08 as Backspace and nobody gets hurt.

Many bytes: the escape sequences

Keys that had no ASCII seat at the table send short escape sequences — the same CSI grammar you've been writing, now arriving as input:

Up      ESC [ A          Home    ESC [ H   or  ESC [ 1 ~   or  ESC O H
Down    ESC [ B          End     ESC [ F   or  ESC [ 4 ~   or  ESC O F
Right   ESC [ C          Delete  ESC [ 3 ~
Left    ESC [ D          PgUp    ESC [ 5 ~
                         PgDn    ESC [ 6 ~

Notice Home and End each have three spellings — CSI-letter, CSI-number-tilde, and ESC O letter (the VT100's "application mode", called SS3). Which one you receive depends on the terminal and its mode. A robust decoder simply accepts all of them; that's not sloppiness, that's the actual job.

Modifier keys extend the grammar with a parameter: the encoding is 1 + bitmask where Shift=1, Alt=2, Ctrl=4. So Ctrl+Right arrives as ESC [ 1 ; 5 C (5 = 1 + Ctrl's 4) and Shift+Alt+Up as ESC [ 1 ; 4 A (4 = 1 + 1 + 2). Same shape for tilde keys: Ctrl+Delete is ESC [ 3 ; 5 ~.

The ESC ambiguity — the one genuinely hard part

The user presses the Escape key: you read byte 0x1B, alone. The user presses Up: you read 0x1B, then [, then A — but possibly split across read() calls, with 0x1B arriving alone in the first one!

At the moment 0x1B lands in your buffer, "Escape was pressed" and "an arrow key's first byte arrived" are indistinguishable. No amount of cleverness fixes this; the information simply isn't there yet. Every terminal program resolves it the same way: wait a few milliseconds. If more bytes follow immediately, it was a sequence (machines are fast); if silence follows, it was the Escape key (humans are slow). That's what vim's ttimeoutlen option tunes, and it's why Escape feels ever-so-slightly laggy in some tools.

Related: terminals encode Alt+x by prefixing the key with ESC — Alt+f sends ESC f. Your decoder gets that for free once it treats "ESC followed by a non-sequence byte" as Alt+byte.

This shapes the decoder's interface. Rather than reading the fd itself (unmockable, untestable), the decoder is a pure function over a byte buffer:

size_t key_decode(const unsigned char *buf, size_t len,
                  struct key_event *out);

Return how many bytes you consumed; return 0 to mean "I can't decide yet — bring more bytes (or a timeout)". The event loop owns the fd, the timing, and the buffer; the decoder owns the grammar. The tests can then feed any byte pattern, including pathological splits, without a terminal in sight. (Two modern extensions worth knowing exist — the kitty keyboard protocol, which fixes the ambiguity properly, and bracketed paste, which brackets pasted text in ESC[200~/ESC[201~ so a pasted :wq! can't execute — both are opt-in CSI modes and out of our scope.)