zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/input/bridge.py

@@ -0,0 +1,46 @@
+"""Translate decoded terminal input into the widget-facing event model.
+
+The legacy ``InputEvent`` structure predates the widget contract. This bridge
+is the only place that knows both shapes, so removing it later is a local
+change rather than a hunt through every widget.
+"""
+
+from __future__ import annotations
+
+from ..core.events import (
+    AnyEvent,
+    FocusEvent,
+    KeyEvent,
+    MouseEvent,
+    PasteEvent,
+    ResizeEvent,
+    TextEvent,
+)
+from .events import EventType, InputEvent
+
+
+def translate(event: InputEvent) -> AnyEvent | None:
+    """Return the widget-facing event, or None for internal signals."""
+    match event.type:
+        case EventType.KEY:
+            return KeyEvent(key=event.key, shift=event.shift, alt=event.alt, control=event.control)
+        case EventType.TEXT:
+            return TextEvent(text=event.text, alt=event.alt, control=event.control)
+        case EventType.PASTE:
+            return PasteEvent(text=event.text)
+        case EventType.MOUSE if event.action is not None:
+            return MouseEvent(
+                x=event.x,
+                y=event.y,
+                button=event.button,
+                action=event.action,
+                shift=event.shift,
+                alt=event.alt,
+                control=event.control,
+            )
+        case EventType.RESIZE:
+            return ResizeEvent()
+        case EventType.FOCUS:
+            return FocusEvent(focused=event.focused)
+        case _:
+            return None

zettcode/tui/input/decoder.py

@@ -0,0 +1,234 @@
+"""Incremental terminal byte-stream decoder."""
+
+from __future__ import annotations
+
+import re
+
+from ..core.events import MouseAction
+from .events import EventType, InputEvent
+from .keys import CONTROL_KEYS, KEY_SEQUENCES, csi_event, meta_csi, split_csi
+
+# SGR mouse report: CSI < Cb ; Cx ; Cy M (press or motion) or m (release).
+# Coordinates arrive 1-based, so the decoder subtracts one from each.
+_MOUSE = re.compile(rb"^\x1b\[<(\d+);(\d+);(\d+)([Mm])")
+
+#: An operating-system command, which is how a terminal answers a query.
+_OSC = b"\x1b]"
+
+#: Focus reporting, asked for with DECSET 1004: ``CSI I`` means the window gained focus, ``CSI O`` that it lost it.
+_FOCUS_IN = b"\x1b[I"
+_FOCUS_OUT = b"\x1b[O"
+
+#: Control characters a paste may keep: tab indents code and newline separates
+#: it. Everything else — the carriage return a clipboard adds per line, a stray
+#: escape, a bell — would be drawn as a broken line or walked over silently.
+_PASTE_KEEP = {"\t", "\n"}
+
+
+def _paste_text(payload: bytes) -> str:
+    """Decode one bracketed-paste payload into text an editor can hold.
+
+    Clipboard line endings are normalised to ``\\n`` and control characters
+    other than tab and newline are dropped, so pasted code cannot depend on the
+    terminal it came from.
+    """
+    text = payload.decode("utf-8", "replace").replace("\r\n", "\n").replace("\r", "\n")
+    return "".join(character for character in text if character in _PASTE_KEEP or character.isprintable())
+
+
+class InputDecoder:
+    """Decode fragmented UTF-8, keyboard, paste, and SGR mouse input."""
+
+    def __init__(self) -> None:
+        """Start with an empty buffer."""
+        self.buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[InputEvent]:
+        """Decode everything buffered, holding back a sequence that is still incomplete.
+
+        Args:
+            data: One raw read from the terminal; it may split a key sequence or
+                a UTF-8 character anywhere, so the leftover stays in ``buffer``
+                until the next call or ``flush_escape``.
+        """
+        self.buffer.extend(data)
+        events: list[InputEvent] = []
+        while self.buffer:
+            event, consumed, incomplete = self._next()
+            if incomplete:
+                break
+            if consumed == 0:
+                consumed = 1
+            del self.buffer[:consumed]
+            if event is not None:
+                events.append(event)
+        return events
+
+    def flush_escape(self) -> InputEvent | None:
+        """Resolve a pending escape once the terminal's sequence timeout lapsed.
+
+        One event at a time: a buffer holding several escapes gives one now, and the caller
+        asks again until nothing is left.
+        """
+        if not self.buffer:
+            return None
+        data = bytes(self.buffer)
+        if data.startswith(b"\x1b\x1b"):
+            # Escape pressed more than once: the first is reported and the rest stays, so
+            # each press is its own event. The caller asks again while anything is left.
+            del self.buffer[:1]
+            return InputEvent(EventType.KEY, key="escape")
+        self.buffer.clear()
+        # A reply cut off mid-sequence is a terminal that stopped talking, not
+        # the Escape key followed by Alt-]: dropping it is the only reading that
+        # cannot type the answer into the reader's draft.
+        if data.startswith(_OSC):
+            return None
+        # "ESC <printable>" is how a terminal spells Alt-<key>; anything else
+        # left over is the Escape key on its own.
+        if len(data) >= 2 and 0x20 <= data[1] < 0x7F:
+            return InputEvent(EventType.KEY, key=chr(data[1]), alt=True)
+        return InputEvent(EventType.KEY, key="escape")
+
+    def _next(self) -> tuple[InputEvent | None, int, bool]:
+        """Decode one event, reporting bytes consumed and whether more are needed."""
+        data = bytes(self.buffer)
+        # Bracketed paste: 200~ opens the payload, 201~ closes it. Until the
+        # closing guard arrives the payload is held back, so a paste containing
+        # newlines or escape bytes is delivered whole rather than replayed.
+        if data.startswith(b"\x1b[200~"):
+            end = data.find(b"\x1b[201~", 6)
+            if end < 0:
+                return None, 0, True
+            return (
+                InputEvent(EventType.PASTE, text=_paste_text(data[6:end])),
+                end + 6,
+                False,
+            )
+
+        # Operating-system reply: ``ESC ]`` body, ended by BEL or by ST (ESC \).
+        # The body belongs to whoever asked the question — it is stripped of its
+        # framing and delivered as a REPLY, never decoded as keystrokes.
+        if data.startswith(_OSC):
+            bell = data.find(b"\x07", 2)
+            terminator = data.find(b"\x1b\\", 2)
+            if bell < 0 and terminator < 0:
+                return None, 0, True
+            if 0 <= bell and (terminator < 0 or bell < terminator):
+                end, length = bell, 1
+            else:
+                end, length = terminator, 2
+            return InputEvent(EventType.REPLY, text=data[2:end].decode("utf-8", "replace")), end + length, False
+
+        # Focus reporting arrives as bare ``CSI I`` / ``CSI O``, which the general control-sequence table has no name
+        # for; read before it, so the window losing focus is an event and not silence.
+        if data.startswith(_FOCUS_IN):
+            return InputEvent(EventType.FOCUS, focused=True), len(_FOCUS_IN), False
+        if data.startswith(_FOCUS_OUT):
+            return InputEvent(EventType.FOCUS, focused=False), len(_FOCUS_OUT), False
+
+        mouse = _MOUSE.match(data)
+        if mouse:
+            code, x, y = (int(mouse.group(index)) for index in (1, 2, 3))
+            suffix = mouse.group(4)
+            action = _mouse_action(code, suffix)
+            return (
+                InputEvent(
+                    EventType.MOUSE,
+                    x=max(0, x - 1),
+                    y=max(0, y - 1),
+                    button=code & 3,  # low two bits: which button
+                    action=action,
+                    shift=bool(code & 4),  # bit 2
+                    alt=bool(code & 8),  # bit 3, reported as "meta" by some terminals
+                    control=bool(code & 16),  # bit 4
+                ),
+                mouse.end(),
+                False,
+            )
+
+        for sequence, key in sorted(KEY_SEQUENCES.items(), key=lambda item: len(item[0]), reverse=True):
+            if data.startswith(sequence):
+                return InputEvent(EventType.KEY, key=key), len(sequence), False
+            if sequence.startswith(data):
+                return None, 0, True
+
+        # Two escapes may be Alt on a cursor key, which is spelled with a second ESC in front,
+        # so wait for the byte that says. Reading the first as Escape straight away would make
+        # the result depend on where the stream happened to be cut — and Escape stops a request.
+        if data == b"\x1b\x1b":
+            return None, 0, True
+
+        # Alt on a cursor key, before the general case below, which would read it as Escape
+        # followed by the bare key.
+        meta = meta_csi(data)
+        if meta is not None:
+            named, length = meta
+            if named is None:
+                return None, 0, True
+            return InputEvent(EventType.KEY, key=named), length, False
+
+        # The modified encoding: the key a terminal can only report after being asked,
+        # like Shift-Enter, and the keys whose names the fixed table does not spell.
+        # A complete sequence this program has no name for is consumed rather than
+        # typed into the draft one byte at a time.
+        csi = split_csi(data)
+        if csi is not None:
+            parameters, final, consumed = csi
+            named, text = csi_event(parameters, final)
+            if text is not None:
+                return InputEvent(EventType.TEXT, text=text), consumed, False
+            return (InputEvent(EventType.KEY, key=named) if named is not None else None), consumed, False
+
+        first = data[0]
+        if first in CONTROL_KEYS:
+            return InputEvent(EventType.KEY, key=CONTROL_KEYS[first]), 1, False
+        if first == 0x1B:
+            if len(data) == 1:
+                return None, 0, True
+            if data[1] in (0x0A, 0x0D):
+                return InputEvent(EventType.KEY, key="alt_enter"), 2, False
+            if data[1] in (0x08, 0x7F):
+                return InputEvent(EventType.KEY, key="alt_backspace"), 2, False
+            if data[1] in (ord("["), ord("O")):
+                # ``ESC [`` and ``ESC O`` may still grow into a control sequence
+                # the tables do not list, so wait for the timeout rather than
+                # guessing that the user pressed Alt with a bracket.
+                return None, 0, True
+            if 0x20 <= data[1] < 0x7F:
+                return InputEvent(EventType.KEY, key=chr(data[1]), alt=True), 2, False
+            return InputEvent(EventType.KEY, key="escape"), 1, False
+        if first < 0x20:
+            return None, 1, False
+
+        length = _utf8_length(first)
+        if len(data) < length:
+            return None, 0, True
+        try:
+            text = data[:length].decode("utf-8")
+        except UnicodeDecodeError:
+            text = "�"
+            length = 1
+        return InputEvent(EventType.TEXT, text=text), length, False
+
+
+def _utf8_length(first: int) -> int:
+    """Return the byte length of a UTF-8 sequence from its lead byte."""
+    if first < 0x80:
+        return 1
+    if first & 0xE0 == 0xC0:
+        return 2
+    if first & 0xF0 == 0xE0:
+        return 3
+    if first & 0xF8 == 0xF0:
+        return 4
+    return 1
+
+
+def _mouse_action(code: int, suffix: bytes) -> MouseAction:
+    """Map an SGR mouse code and its suffix onto one action."""
+    if code & 64:  # bit 6: wheel; bit 0 then picks up versus down
+        return MouseAction.SCROLL_DOWN if code & 1 else MouseAction.SCROLL_UP
+    if code & 32:  # bit 5: motion with a button held
+        return MouseAction.MOVE
+    return MouseAction.UP if suffix == b"m" else MouseAction.DOWN  # M presses, m releases

zettcode/tui/input/events.py

@@ -0,0 +1,64 @@
+"""Decoded terminal input shared by the decoder and the legacy component API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .._compat import StrEnum
+from ..core.events import MouseAction
+
+
+class EventType(StrEnum):
+    """The kinds of input the decoder can produce."""
+
+    KEY = "key"
+    TEXT = "text"
+    PASTE = "paste"
+    MOUSE = "mouse"
+    RESIZE = "resize"
+    RENDER = "render"
+    #: The terminal window gained or lost focus (DECSET 1004 reports it as
+    #: ``CSI I`` and ``CSI O``).
+    FOCUS = "focus"
+    #: An answer to a query the application sent, such as the terminal's own
+    #: background colour. It is input, but no widget ever sees it.
+    REPLY = "reply"
+
+
+@dataclass(frozen=True, slots=True)
+class InputEvent:
+    """One decoded terminal input, before it becomes a framework event.
+
+    Which fields matter depends on ``type``: keys fill ``key``, text and paste
+    payloads fill ``text``, mouse events fill ``x``/``y``/``button``/``action``,
+    and a resize carries no payload at all.
+
+    Attributes:
+        type: Which decoder branch produced this event.
+        key: Canonical key name for ``KEY`` events.
+        text: Payload for ``TEXT``, ``PASTE``, and ``REPLY`` events; a reply
+            carries the sequence's body, without its introducer or terminator.
+        x: Column for ``MOUSE`` events, zero-based.
+        y: Row for ``MOUSE`` events, zero-based.
+        button: Button index reported by the terminal.
+        action: Gesture for ``MOUSE`` events.
+        shift: Shift modifier, where the terminal reports it.
+        alt: Alt modifier, where the terminal reports it.
+        control: Ctrl modifier, where the terminal reports it.
+        focused: Whether the terminal gained focus, for ``FOCUS`` events.
+    """
+
+    type: EventType
+    key: str = ""
+    text: str = ""
+    x: int = 0
+    y: int = 0
+    button: int = 0
+    action: MouseAction | None = None
+    shift: bool = False
+    alt: bool = False
+    control: bool = False
+    focused: bool = True
+
+
+__all__ = ["EventType", "InputEvent", "MouseAction"]

zettcode/tui/input/keys.py

@@ -0,0 +1,289 @@
+"""Byte sequences terminals use to report keys and modifiers.
+
+Two families are decoded here. The fixed table below covers what a terminal sends
+without being asked. The rest is the *modified* encoding, which a terminal has to be
+asked for: ``CSI <code> ; <modifiers> u`` (the kitty protocol, requested in
+``Terminal._enter_sequences``) and ``CSI 27 ; <modifiers> ; <code> ~`` (xterm's
+``modifyOtherKeys``, which some terminals are configured for). Without one of those,
+a terminal cannot report Shift-Enter at all: it sends the same carriage return as
+Enter, and no decoder can tell them apart.
+"""
+
+from __future__ import annotations
+
+# Terminals do not send "up"; they send a Control Sequence Introducer (CSI,
+# ``ESC [``) followed by parameters. These are the two families worth knowing:
+# letter-final sequences (``CSI A`` is up) and tilde-final ones (``CSI 3 ~`` is
+# delete), plus the modifier form ``CSI 1 ; <modifier> <letter>``.
+KEY_SEQUENCES: dict[bytes, str] = {
+    # CSI A-D: the four arrows in normal cursor-key mode.
+    b"\x1b[A": "up",
+    b"\x1b[B": "down",
+    b"\x1b[C": "right",
+    b"\x1b[D": "left",
+    # CSI H / F: Home and End, with the tilde spellings some terminals prefer.
+    b"\x1b[H": "home",
+    b"\x1b[F": "end",
+    b"\x1b[1~": "home",
+    b"\x1b[4~": "end",
+    # CSI n ~: the keys that have no letter of their own.
+    b"\x1b[5~": "page_up",
+    b"\x1b[6~": "page_down",
+    b"\x1b[3~": "delete",
+    b"\x1b[2~": "insert",
+    b"\x1b[Z": "backtab",  # CSI Z: Shift-Tab
+    # CSI 1 ; m <letter>, where m encodes the modifiers: 3 = Alt, 5 = Ctrl.
+    b"\x1b[1;5D": "ctrl_left",
+    b"\x1b[1;5C": "ctrl_right",
+    b"\x1b[1;3D": "alt_left",
+    b"\x1b[1;3C": "alt_right",
+    b"\x1b[1;5H": "ctrl_home",
+    b"\x1b[1;5F": "ctrl_end",
+}
+
+CONTROL_KEYS: dict[int, str] = {
+    0x01: "ctrl_a",
+    0x02: "ctrl_b",
+    0x03: "ctrl_c",
+    0x04: "ctrl_d",
+    0x05: "ctrl_e",
+    0x06: "ctrl_f",
+    0x07: "ctrl_g",
+    0x09: "tab",
+    0x0A: "enter",
+    0x0B: "ctrl_k",
+    0x0C: "ctrl_l",
+    0x0D: "enter",
+    0x0E: "ctrl_n",
+    0x10: "ctrl_p",
+    0x12: "ctrl_r",
+    0x14: "ctrl_t",
+    0x15: "ctrl_u",
+    0x16: "ctrl_v",
+    0x17: "ctrl_w",
+    0x19: "ctrl_y",
+    0x1A: "ctrl_z",
+    0x1F: "ctrl_underscore",
+    0x7F: "backspace",
+    0x08: "backspace",
+}
+
+
+#: Modifier bits of a modified key, most significant first: the parameter a terminal
+#: reports is one plus a mask, and the lock bits above these are dropped — whether a
+#: program sees Ctrl depends on Caps Lock, which is not a modifier anyone binds.
+MODIFIER_BITS = ((8, "super"), (4, "ctrl"), (2, "alt"), (1, "shift"))
+
+#: Keys the modified encoding names by code point instead of by character.
+NAMED_CODES: dict[int, str] = {
+    8: "backspace",
+    9: "tab",
+    10: "enter",
+    13: "enter",
+    27: "escape",
+    32: "space",
+    127: "backspace",
+}
+
+#: Tilde-final keys, by the number in front of the tilde.
+TILDE_KEYS: dict[int, str] = {
+    1: "home",
+    2: "insert",
+    3: "delete",
+    4: "end",
+    5: "page_up",
+    6: "page_down",
+}
+
+#: Letter-final keys: the arrows and the Home/End family.
+LETTER_KEYS: dict[bytes, str] = {
+    b"A": "up",
+    b"B": "down",
+    b"C": "right",
+    b"D": "left",
+    b"F": "end",
+    b"H": "home",
+    b"P": "f1",
+    b"Q": "f2",
+    b"R": "f3",
+    b"S": "f4",
+    b"Z": "backtab",
+}
+
+#: Longest modifier parameter this decoder reads. A terminal may report more bits
+#: than there are names for; the extra ones are ignored rather than fatal.
+_MODIFIER_LIMIT = 256
+
+
+def split_csi(data: bytes) -> tuple[bytes, bytes, int] | None:
+    """Return ``(parameters, final, length)`` of one complete control sequence.
+
+    A control sequence is ``ESC [``, then parameter and intermediate bytes — all of
+    them below ``@`` — and a final byte at or above it (ECMA-48). A sequence whose
+    final byte has not arrived is not returned: the caller keeps waiting for it,
+    which is what a sequence split across two reads looks like.
+
+    Returns:
+        The parts and the number of bytes they take, or ``None`` when ``data`` does
+        not hold a complete control sequence.
+    """
+    if not data.startswith(b"\x1b["):
+        return None
+    index = 2
+    while index < len(data) and data[index] < 0x40:
+        index += 1
+    if index >= len(data):
+        return None
+    return data[2:index], data[index : index + 1], index + 1
+
+
+def modifiers_of(parameter: bytes) -> tuple[bool, bool, bool, bool]:
+    """Return the (shift, alt, ctrl, super) flags one modifier parameter carries.
+
+    An empty parameter means one, which is "no modifiers": every terminal omits it
+    rather than writing a one.
+    """
+    # A terminal that reports event types writes "3:1" — the modifiers, then what the
+    # key did — and only the part before the colon says which modifiers are held.
+    parameter = parameter.split(b":")[0]
+    try:
+        value = int(parameter) if parameter else 1
+    except ValueError:
+        return (False, False, False, False)
+    mask = max(0, min(value, _MODIFIER_LIMIT) - 1)
+    flags = {name: bool(mask & bit) for bit, name in MODIFIER_BITS}
+    return (flags["shift"], flags["alt"], flags["ctrl"], flags["super"])
+
+
+def modified(base: str, *, shift: bool = False, alt: bool = False, ctrl: bool = False, super_: bool = False) -> str:
+    """Return the key name a modified key is spelled with, as its bindings expect.
+
+    The prefixes are the ones this framework already uses — ``shift_enter``,
+    ``alt_backspace``, ``ctrl_left`` — so a key reached through the modified
+    encoding lands on the same binding as one reached through the fixed table.
+    Shift-Tab keeps its own name, which is what the table calls it.
+    """
+    if base == "tab" and shift and not (alt or ctrl or super_):
+        return "backtab"
+    prefix = "".join(name for name, on in (("ctrl", ctrl), ("alt", alt), ("shift", shift), ("super", super_)) if on)
+    return f"{prefix}_{base}" if prefix else base
+
+
+def control_name(character: str) -> str:
+    """Return the name a Ctrl-<character> would have arrived as without the encoding.
+
+    A terminal that cannot say "Ctrl-C" sends byte 3, and this framework already has
+    a name for every one of those: the same name is what a modified encoding has to
+    produce, or the key would reach a binding that no longer exists. Where the
+    legacy byte has no name — Ctrl-Space, Ctrl-/, which a terminal may or may not
+    send at all — the name is spelled out, and being unbound it does nothing.
+    """
+    code = ord(character)
+    if character == "@" or code == 0x20:
+        legacy = 0x00
+    elif character == "?":
+        legacy = 0x7F
+    elif 0x40 <= code <= 0x5F:
+        legacy = code - 0x40
+    elif 0x61 <= code <= 0x7A:
+        legacy = code - 0x60
+    else:
+        return f"ctrl_{character}"
+    return CONTROL_KEYS.get(legacy, f"ctrl_{character}")
+
+
+#: Keys a terminal that sends Alt as a leading ESC can put Alt on: the cursor keys.
+META_KEYS = frozenset({"up", "down", "left", "right", "home", "end", "page_up", "page_down", "delete"})
+
+
+def meta_csi(data: bytes) -> tuple[str | None, int] | None:
+    """Read ``ESC ESC [ …``: how a terminal in "Option sends Esc+" mode spells Alt on a cursor key.
+
+    The same key without Alt is ``ESC [ A``, and with Alt the terminal puts one more ``ESC``
+    in front of it. Read as two keys that is *Escape, then Up* — and Escape stops a running
+    request, so an Alt-Up that was read that way would cancel the work it was pressed over.
+
+    Returns:
+        ``None`` when ``data`` is not this shape, ``(None, 0)`` while the sequence is still
+        arriving, and ``(key, length)`` once it is complete.
+    """
+    if not data.startswith(b"\x1b\x1b["):
+        return None
+    csi = split_csi(data[1:])
+    if csi is None:
+        return (None, 0)
+    parameters, final, length = csi
+    named, _ = csi_event(parameters, final)
+    if named not in META_KEYS:
+        return None
+    return (f"alt_{named}", length + 1)
+
+
+def csi_event(parameters: bytes, final: bytes) -> tuple[str | None, str | None]:
+    """Return ``(key, text)`` for one control sequence: a name, or text it spells.
+
+    Args:
+        parameters: Everything between ``ESC [`` and the final byte.
+        final: The final byte.
+
+    Returns:
+        A key name, or the text a printable key spells, or ``(None, None)`` for a
+        sequence this program has no name for.
+    """
+    fields = parameters.split(b";")
+    if final == b"u":
+        return _code_event(_number(fields[0]), modifiers_of(fields[1] if len(fields) > 1 else b""))
+    if final == b"~":
+        if len(fields) == 3 and _number(fields[0], default=-1) == 27:
+            # xterm's modifyOtherKeys form: 27 ; modifiers ; code ~
+            return _code_event(_number(fields[2]), modifiers_of(fields[1]))
+        base = TILDE_KEYS.get(_number(fields[0], default=-1))
+        if base is None:
+            return (None, None)
+        shift, alt, ctrl, super_ = modifiers_of(fields[1] if len(fields) > 1 else b"")
+        return (modified(base, shift=shift, alt=alt, ctrl=ctrl, super_=super_), None)
+    base = LETTER_KEYS.get(final)
+    if base is None:
+        return (None, None)
+    shift, alt, ctrl, super_ = modifiers_of(fields[1] if len(fields) > 1 else b"")
+    return (modified(base, shift=shift, alt=alt, ctrl=ctrl, super_=super_), None)
+
+
+def _code_event(code: int, mods: tuple[bool, bool, bool, bool]) -> tuple[str | None, str | None]:
+    """Return (key, text) for a code point and its modifiers, or (None, None) if unusable."""
+    shift, alt, ctrl, super_ = mods
+    if code < 0 or code > 0x10FFFF:
+        return (None, None)
+    character = chr(code)
+    if ctrl or super_:
+        if code in NAMED_CODES:
+            return (modified(NAMED_CODES[code], shift=shift, alt=alt, ctrl=ctrl, super_=super_), None)
+        # A control key means a letter or a punctuation mark: Ctrl with a character
+        # outside ASCII is not something a terminal reports, and naming one after a
+        # letter it is not would be worse than ignoring it.
+        if character.isascii() and character.isprintable():
+            return (control_name(character), None)
+        return (None, None)
+    if code in NAMED_CODES:
+        base = NAMED_CODES[code]
+        if base == "space":
+            return (None, " ") if not alt else (modified(base, alt=alt, shift=shift), None)
+        return (modified(base, shift=shift, alt=alt, super_=super_), None)
+    if not character.isprintable():
+        return (None, None)
+    if alt:
+        # Alt with a printable key is not text: without the encoding a terminal spells
+        # it "ESC <key>", which this decoder reads as the key with Alt held, and a
+        # binding is what acts on it.
+        return (modified(character.lower(), alt=True, shift=shift, super_=super_), None)
+    return (None, character.upper() if shift and character.isalpha() else character)
+
+
+def _number(field: bytes, *, default: int = 0) -> int:
+    """Return the number a control-sequence parameter holds, or ``default``."""
+    if not field:
+        return default
+    try:
+        return int(field)
+    except ValueError:
+        return default