iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/terminal/emulator/input.py

@@ -0,0 +1,342 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""What a terminal sends to the program: keys, pointer reports, pastes and focus changes.
+
+Keys follow xterm until the program asks for more. A function key is a fixed sequence with the
+held modifiers in its second parameter, one more than their bits. A text key sends its text, Ctrl
+folds it into a C0 control and Alt prefixes ESC, which is where the classic encoding runs out:
+Shift+Enter is Enter, Ctrl+Shift+A is Ctrl+A. A program that wants those told apart asks for one of
+the extended encodings (`KeyProtocol`), and only then are they sent, because a shell that never
+asked would print the unfamiliar sequence as text.
+
+The extended encodings are two families, and each is followed by its own definition. xterm's
+modifyOtherKeys respells text keys only, and how many of them is a matter of the level asked for.
+The kitty keyboard protocol has its own modifier bits, and respells the function keys as well:
+none of them is an SS3 sequence any more, whatever the cursor key mode, and F3 stops looking like
+a cursor position report.
+
+Key names are Textual's: modifiers first, ``+`` between (``ctrl+shift+left``).
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from enum import Enum
+from typing import Final
+
+from chrys.app.tui.terminal.emulator.core import KeyProtocol, MouseEncoding, MouseTracking
+
+FOCUS_IN: Final = "\x1b[I"
+FOCUS_OUT: Final = "\x1b[O"
+
+_PASTE_START: Final = "\x1b[200~"
+_PASTE_END: Final = "\x1b[201~"
+
+_SHIFT, _ALT, _CTRL = 1, 2, 4
+# xterm has a bit for Meta and none for Super or Hyper, which it cannot say at all. kitty has all
+# three, and its Meta is not where xterm's is.
+_XTERM_MODIFIER_BITS: Final = {"shift": _SHIFT, "alt": _ALT, "ctrl": _CTRL, "meta": 8, "super": 0, "hyper": 0}
+_KITTY_MODIFIER_BITS: Final = {"shift": _SHIFT, "alt": _ALT, "ctrl": _CTRL, "super": 8, "hyper": 16, "meta": 32}
+
+# Keys spelled ``CSI 1 ; modifiers <final>``. Bare, xterm has the cursor keys honor application mode
+# (DECCKM) and F1-F4 always SS3; the kitty protocol keeps both where they are.
+_CURSOR_KEYS: Final = {"up": "A", "down": "B", "right": "C", "left": "D", "home": "H", "end": "F"}
+_FUNCTION_KEYS_SS3: Final = {"f1": "P", "f2": "Q", "f3": "R", "f4": "S"}
+# Keys spelled ``CSI <number> ; modifiers ~``. The gaps in the numbering are DEC's.
+_TILDE_KEYS: Final = {
+    "insert": 2,
+    "delete": 3,
+    "pageup": 5,
+    "pagedown": 6,
+    "f5": 15,
+    "f6": 17,
+    "f7": 18,
+    "f8": 19,
+    "f9": 20,
+    "f10": 21,
+    "f11": 23,
+    "f12": 24,
+    "f13": 25,
+    "f14": 26,
+    "f15": 28,
+    "f16": 29,
+    "f17": 31,
+    "f18": 32,
+    "f19": 33,
+    "f20": 34,
+}
+# Where kitty parts with xterm: F3 by number, since ``CSI 1 ; modifiers R`` is also how a terminal
+# reports the cursor position, and the keys past F12 by numbers of kitty's own, up to F35.
+_FIRST_KITTY_NUMBERED_FUNCTION_KEY: Final = 13
+_KITTY_FUNCTION_KEYS: Final = {
+    "f3": (13, "~"),
+    **{f"f{number}": (57376 + number - _FIRST_KITTY_NUMBERED_FUNCTION_KEY, "u") for number in range(13, 36)},
+}
+
+# Keys that are a character but not a printable one, and the names Textual gives punctuation where
+# the Unicode name would not lead back to the character.
+_EDITING_KEYS: Final = {"enter": "\r", "tab": "\t", "escape": "\x1b", "backspace": "\x7f", "space": " "}
+_PUNCTUATION_NAMES: Final = {
+    "slash": "/",
+    "backslash": "\\",
+    "at": "@",
+    "minus": "-",
+    "plus": "+",
+    "underscore": "_",
+    "less_than_sign": "<",
+    "greater_than_sign": ">",
+}
+# What a key types with Shift held, where that is not the capital of what it types without. Textual
+# names such a key by the latter and nothing records the layout that turns one into the other, so
+# it is the US one: what xterm's own table of these encodings is written for.
+_US_SHIFTED: Final = dict(zip("`1234567890-=[]\\;',./", '~!@#$%^&*()_+{}|:"<>?', strict=True))
+# What Ctrl makes of a character besides the letters: the C0 control sharing its low five bits,
+# plus the digit row and the few aliases every terminal has inherited from the VT100 keyboard.
+_CONTROL_CHARACTERS: Final = {
+    "@": "\x00",
+    " ": "\x00",
+    "`": "\x00",
+    "2": "\x00",
+    "[": "\x1b",
+    "{": "\x1b",
+    "3": "\x1b",
+    "\\": "\x1c",
+    "|": "\x1c",
+    "4": "\x1c",
+    "]": "\x1d",
+    "}": "\x1d",
+    "5": "\x1d",
+    "^": "\x1e",
+    "~": "\x1e",
+    "6": "\x1e",
+    "_": "\x1f",
+    "-": "\x1f",
+    "/": "\x1f",
+    "7": "\x1f",
+    "8": "\x7f",
+    "?": "\x7f",
+    "\x7f": "\x08",
+}
+# The two of those xterm does not count as well known: it sends "-" as itself, and makes DEL of "?"
+# only once it has decided how the key is spelled.
+_LESSER_CONTROL_ALIASES: Final = frozenset("-?")
+
+
+def encode_key(
+    key: str,
+    character: str | None,
+    *,
+    application_cursor_keys: bool = False,
+    protocol: KeyProtocol = KeyProtocol.LEGACY,
+) -> str | None:
+    """The bytes for a key press, or ``None`` if the key sends nothing.
+
+    Args:
+        key: Textual's key name.
+        character: The text the key produced, if any. It may be several code points: an input
+            method commits a whole word as one key.
+        application_cursor_keys: Whether the program switched the cursor keys to application mode.
+        protocol: The encoding the program asked for.
+    """
+    kitty = protocol is KeyProtocol.KITTY
+    bits = _KITTY_MODIFIER_BITS if kitty else _XTERM_MODIFIER_BITS
+    *modifiers, base = key.split("+")
+    if any(modifier not in bits for modifier in modifiers):
+        # Not a modified key after all, just text that happens to contain a plus sign.
+        return character
+    held = sum(bits[modifier] for modifier in modifiers)
+
+    if (final := _CURSOR_KEYS.get(base)) is not None:
+        application = application_cursor_keys and not held and not kitty
+        return f"\x1bO{final}" if application else _control_sequence(1, held, final)
+    if kitty and (spelling := _KITTY_FUNCTION_KEYS.get(base)) is not None:
+        return _control_sequence(spelling[0], held, spelling[1])
+    if (final := _FUNCTION_KEYS_SS3.get(base)) is not None:
+        return _control_sequence(1, held, final) if held or kitty else f"\x1bO{final}"
+    if (number := _TILDE_KEYS.get(base)) is not None:
+        return _control_sequence(number, held, "~")
+
+    typed = _key_character(base)
+    if typed is None:
+        return character
+    if kitty:
+        if typed != typed.lower() and len(typed.lower()) == 1:
+            # The key is named by what it types unshifted, and Shift is a modifier like any other.
+            typed, held = typed.lower(), held | _SHIFT
+        if typed == "\x1b" or held & ~_SHIFT or (held and base in _EDITING_KEYS):
+            return _control_sequence(ord(typed), held, "u")
+    if held & _SHIFT:
+        # xterm goes the other way: by what was typed, Shift's part in it included. That is what Ctrl
+        # folds, what is asked whether it has a classic spelling, and the code that is reported.
+        typed = _shifted(typed)
+    if _modify_other_keys_applies(protocol, base, typed, held):
+        return f"\x1b[27;{held + 1};{ord(typed)}~"
+    return _classic_encoding(base, typed, held, character)
+
+
+def _control_sequence(number: int, held: int, final: str) -> str:
+    """``CSI number ; modifiers final``, less the parameters that would only state a default."""
+    if held:
+        return f"\x1b[{number};{held + 1}{final}"
+    return f"\x1b[{final}" if number == 1 else f"\x1b[{number}{final}"
+
+
+def _key_character(base: str) -> str | None:
+    """The character a key name stands for, or ``None`` for a key that is not a character."""
+    if len(base) == 1:
+        return base
+    if (known := _EDITING_KEYS.get(base) or _PUNCTUATION_NAMES.get(base)) is not None:
+        return known
+    try:
+        return unicodedata.lookup(base.replace("_", " "))
+    except KeyError:
+        return None
+
+
+def _shifted(typed: str) -> str:
+    """What the key that types this types with Shift held, as far as that can be told."""
+    capital = typed.upper()
+    if capital != typed:
+        return capital if len(capital) == 1 else typed
+    return _US_SHIFTED.get(typed, typed)
+
+
+def _classic_encoding(base: str, typed: str, held: int, character: str | None) -> str | None:
+    if base == "tab" and held & _SHIFT:
+        typed = "\x1b[Z"
+    elif held & _CTRL:
+        is_letter = typed.isascii() and typed.isalpha()
+        typed = chr(ord(typed) & 0x1F) if is_letter else _CONTROL_CHARACTERS.get(typed, typed)
+    elif base not in _EDITING_KEYS:
+        # Whatever the key name says, the text the key produced is what was typed.
+        typed = character if character is not None else typed
+    return f"\x1b{typed}" if held & _ALT else typed
+
+
+def _modify_other_keys_applies(protocol: KeyProtocol, base: str, typed: str, held: int) -> bool:
+    """Whether xterm spells a text key ``CSI 27 ; modifiers ; code ~`` at the level the program asked for.
+
+    xterm as it is when Alt sends ESC, the only Alt the classic encoding here knows, going as it
+    does by ``typed`` with Shift's part already in it. One departure: at level 2 xterm also
+    respells Shift with a letter, and not Shift with a digit. Shift with something printable is
+    sent as what it types, everywhere.
+    """
+    if not held or protocol not in (KeyProtocol.MODIFY_OTHER_KEYS_1, KeyProtocol.MODIFY_OTHER_KEYS_2):
+        return False
+    if base == "backspace" and held == _CTRL:
+        # Not a chord to xterm but the other backspace: Ctrl swaps which of BS and DEL the key sends.
+        return False
+    if held & ~(_SHIFT | _ALT | _CTRL):
+        # Meta. There is no classic spelling to keep.
+        return True
+    if protocol is KeyProtocol.MODIFY_OTHER_KEYS_2:
+        return held != _SHIFT or base in _EDITING_KEYS
+    # Level 1 leaves alone whatever has a well-known spelling, even one that drops a modifier.
+    if base in ("tab", "enter"):
+        # Back-tab is the one such spelling these two have; Alt has none, as ESC is not put before them.
+        return (base, held) != ("tab", _SHIFT)
+    if base == "escape":
+        return bool(held & _ALT)
+    if base in _EDITING_KEYS:
+        return False
+    is_letter = typed.isascii() and typed.isalpha()
+    has_control = is_letter or (typed in _CONTROL_CHARACTERS and typed not in _LESSER_CONTROL_ALIASES)
+    return bool(held & _CTRL) and not has_control
+
+
+def encode_paste(text: str, *, bracketed: bool) -> str:
+    """The bytes for pasted text.
+
+    Bracketed, the program is told where the paste starts and ends, so the paste itself must not be
+    able to say so first. Unbracketed, the text arrives as if typed, where Return ends a line.
+    """
+    if bracketed:
+        return f"{_PASTE_START}{text.replace(_PASTE_END, '')}{_PASTE_END}"
+    return text.replace("\r\n", "\r").replace("\n", "\r")
+
+
+class PointerAction(Enum):
+    PRESS = "press"
+    RELEASE = "release"
+    MOVE = "move"
+    WHEEL_UP = "wheel_up"
+    WHEEL_DOWN = "wheel_down"
+    WHEEL_LEFT = "wheel_left"
+    WHEEL_RIGHT = "wheel_right"
+
+
+_NO_BUTTON: Final = 3
+_MOTION: Final = 32
+_WHEEL: Final = {
+    PointerAction.WHEEL_UP: 64,
+    PointerAction.WHEEL_DOWN: 65,
+    PointerAction.WHEEL_LEFT: 66,
+    PointerAction.WHEEL_RIGHT: 67,
+}
+_MAX_DEFAULT_COORDINATE: Final = 223
+_MAX_UTF8_COORDINATE: Final = 2015
+_FIRST_BYTE_THAT_IS_NOT_TEXT: Final = 0x80
+_SURROGATE_ESCAPE: Final = 0xDC00
+
+
+def encode_pointer(
+    tracking: MouseTracking,
+    encoding: MouseEncoding,
+    action: PointerAction,
+    *,
+    x: int,
+    y: int,
+    button: int | None = None,
+    shift: bool = False,
+    alt: bool = False,
+    ctrl: bool = False,
+) -> str | None:
+    """The report for a pointer event, or ``None`` when the program did not ask to hear of it.
+
+    xterm's original format spends one byte on each coordinate, and from column 96 on that byte is
+    not text. It is returned as the lone surrogate the ``surrogateescape`` error handler turns back
+    into the byte, which is how whoever encodes the report for the program has to encode it. Only
+    the UTF-8 format (mode 1005) sends such a value as a character.
+
+    Args:
+        tracking: The tracking mode the program selected.
+        encoding: The report format the program selected.
+        action: What the pointer did.
+        x: Zero-based column.
+        y: Zero-based row.
+        button: 0 left, 1 middle, 2 right; ``None`` when no button is involved or held.
+        shift: Shift is held.
+        alt: Alt (Meta) is held.
+        ctrl: Control is held.
+    """
+    if tracking is MouseTracking.OFF:
+        return None
+    if tracking is MouseTracking.PRESS and action is not PointerAction.PRESS:
+        return None
+    if action is PointerAction.MOVE and (
+        tracking is MouseTracking.PRESS_RELEASE or (tracking is MouseTracking.DRAG and button is None)
+    ):
+        return None
+
+    released = action is PointerAction.RELEASE
+    if (code := _WHEEL.get(action)) is None:
+        # Only the SGR format can say which button was released; the others report "no button".
+        code = _NO_BUTTON if button is None or (released and encoding is not MouseEncoding.SGR) else button
+        if action is PointerAction.MOVE:
+            code += _MOTION
+    if tracking is not MouseTracking.PRESS:
+        code += 4 * shift + 8 * alt + 16 * ctrl
+
+    column, row = x + 1, y + 1
+    if encoding is MouseEncoding.SGR:
+        return f"\x1b[<{code};{column};{row}{'m' if released else 'M'}"
+    if encoding is MouseEncoding.URXVT:
+        return f"\x1b[{code + 32};{column};{row}M"
+    limit = _MAX_UTF8_COORDINATE if encoding is MouseEncoding.UTF8 else _MAX_DEFAULT_COORDINATE
+    if column > limit or row > limit:
+        # These formats spend one character, or one byte, per coordinate and cannot count any higher.
+        return None
+    values = (code + 32, column + 32, row + 32)
+    if encoding is not MouseEncoding.UTF8:
+        values = (value + _SURROGATE_ESCAPE * (value >= _FIRST_BYTE_THAT_IS_NOT_TEXT) for value in values)
+    return "\x1b[M" + "".join(map(chr, values))

chrys/app/tui/terminal/emulator/parser.py

@@ -0,0 +1,227 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Control-sequence parser: splits a terminal's output stream into printable runs and controls.
+
+The grammar is ECMA-48's, driven as a resumable state machine so a sequence may be cut anywhere by
+a read boundary, and the recovery rules are the ones DEC terminals established: a control
+character inside a sequence acts immediately without ending it, ESC abandons the sequence in
+progress and starts another, CAN and SUB cancel it. Whole runs of text and whole control sequences
+are matched in one step when they arrive intact, which is nearly always; the character-at-a-time
+states only finish what a boundary or an embedded control interrupted.
+
+The parser holds no terminal state. It reports what it recognized to a `SequenceHandler`. A handler
+that fails costs the rest of that `feed` and the sequence in progress, never the parse of what is
+fed next.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final, Protocol
+
+ESC: Final = "\x1b"
+BEL: Final = "\x07"
+_CAN: Final = "\x18"
+_SUB: Final = "\x1a"
+_DEL: Final = "\x7f"
+_ST: Final = "\x9c"
+
+# C0, DEL and C1 never print. Decoded C1 code points are dropped rather than obeyed: in a UTF-8
+# stream they are far likelier to be damage than an 8-bit control.
+_PRINTABLE_RUN = re.compile(r"[^\x00-\x1f\x7f-\x9f]+")
+_CONTROL_SEQUENCE = re.compile(r"([<=>?]?)([0-9:;]*)([ -/]*)([@-~])")
+_STRING_RUN = re.compile(r"[^\x00-\x1f\x9c]+")
+
+_MAX_PARAMETER_LENGTH: Final = 256
+_MAX_STRING_LENGTH: Final = 1 << 18
+
+_GROUND: Final = 0
+_ESCAPE: Final = 1
+_CSI_PARAMETERS: Final = 2
+_CSI_INTERMEDIATES: Final = 3
+_CSI_IGNORE: Final = 4
+_OSC_STRING: Final = 5
+_DCS_STRING: Final = 6
+_IGNORED_STRING: Final = 7
+
+# OSC and DCS carry data we act on; SOS, PM and APC are consumed so their text never prints.
+_STRING_INTRODUCERS: Final = {
+    "]": _OSC_STRING,
+    "P": _DCS_STRING,
+    "X": _IGNORED_STRING,
+    "^": _IGNORED_STRING,
+    "_": _IGNORED_STRING,
+}
+
+
+class SequenceHandler(Protocol):
+    """What a parser reports to."""
+
+    def print(self, text: str) -> None:
+        """A run of printable characters."""
+
+    def execute(self, control: str) -> None:
+        """A C0 control character."""
+
+    def escape(self, intermediates: str, final: str) -> None:
+        """An escape sequence: ``ESC intermediates final``."""
+
+    def control_sequence(self, marker: str, parameters: str, intermediates: str, final: str) -> None:
+        """A control sequence: ``CSI marker parameters intermediates final``.
+
+        ``marker`` is the private-use prefix (one of ``<=>?``) or empty; ``parameters`` is the raw
+        parameter text, digits with ``;`` between parameters and ``:`` between sub-parameters.
+        """
+
+    def operating_system_command(self, payload: str) -> None:
+        """The text of an OSC string."""
+
+    def device_control(self, payload: str) -> None:
+        """The text of a DCS string, introducer parameters included."""
+
+
+class SequenceParser:
+    """Feeds a `SequenceHandler` from a stream of decoded terminal output."""
+
+    __slots__ = ("_collected", "_collected_length", "_handler", "_intermediates", "_marker", "_state")
+
+    def __init__(self, handler: SequenceHandler) -> None:
+        self._handler = handler
+        self._state = _GROUND
+        self._marker = ""
+        self._collected: list[str] = []
+        self._collected_length = 0
+        self._intermediates = ""
+
+    def reset(self) -> None:
+        """Forget any sequence in progress."""
+        self._state = _GROUND
+        self._begin_collecting()
+
+    def feed(self, data: str) -> None:
+        """Parse the next piece of the stream."""
+        try:
+            self._feed(data)
+        except BaseException:
+            # Reports are made from inside a sequence as well: a string is still open while its
+            # text is handed over, a control character acts in the middle of whatever it interrupts.
+            # Left there, the parser would read what comes next as more of the same.
+            self.reset()
+            raise
+
+    def _feed(self, data: str) -> None:
+        handler = self._handler
+        position = 0
+        end = len(data)
+        while position < end:
+            state = self._state
+            if state == _GROUND:
+                if (run := _PRINTABLE_RUN.match(data, position)) is not None:
+                    handler.print(run.group())
+                    position = run.end()
+                    continue
+                char = data[position]
+                position += 1
+                if char == ESC:
+                    self._state = _ESCAPE
+                    self._begin_collecting()
+                elif char < " ":
+                    handler.execute(char)
+                continue
+
+            if state >= _OSC_STRING:
+                position = self._feed_string(data, position)
+                continue
+
+            char = data[position]
+            position += 1
+            if char == ESC:
+                self._state = _ESCAPE
+                self._begin_collecting()
+            elif char in (_CAN, _SUB):
+                self._state = _GROUND
+            elif char < " ":
+                handler.execute(char)
+            elif char >= _DEL:
+                if char != _DEL:
+                    # Not part of any sequence: the sequence is damaged, the character still prints.
+                    self._state = _GROUND
+                    position -= 1
+            elif state == _ESCAPE:
+                position = self._feed_escape(char, data, position)
+            else:
+                self._feed_control_sequence(char)
+
+    def _begin_collecting(self) -> None:
+        self._marker = ""
+        self._collected = []
+        self._collected_length = 0
+        self._intermediates = ""
+
+    def _feed_escape(self, char: str, data: str, position: int) -> int:
+        if char < "0":
+            self._intermediates += char
+            return position
+        self._state = _GROUND
+        if self._intermediates:
+            self._handler.escape(self._intermediates, char)
+        elif char == "[":
+            if (sequence := _CONTROL_SEQUENCE.match(data, position)) is not None:
+                if len(sequence[2]) <= _MAX_PARAMETER_LENGTH:
+                    self._handler.control_sequence(*sequence.groups())
+                return sequence.end()
+            self._state = _CSI_PARAMETERS
+        elif (string_state := _STRING_INTRODUCERS.get(char)) is not None:
+            self._state = string_state
+        else:
+            self._handler.escape("", char)
+        return position
+
+    def _feed_control_sequence(self, char: str) -> None:
+        if char >= "@":
+            if self._state != _CSI_IGNORE:
+                self._handler.control_sequence(self._marker, "".join(self._collected), self._intermediates, char)
+            self._state = _GROUND
+        elif self._state == _CSI_IGNORE:
+            pass
+        elif char < "0":
+            self._intermediates += char
+            self._state = _CSI_INTERMEDIATES
+        elif self._state == _CSI_INTERMEDIATES:
+            # A parameter byte after an intermediate is malformed; swallow through the final byte.
+            self._state = _CSI_IGNORE
+        elif char < "<":
+            self._collected.append(char)
+            if len(self._collected) > _MAX_PARAMETER_LENGTH:
+                self._state = _CSI_IGNORE
+        elif self._collected or self._marker:
+            self._state = _CSI_IGNORE
+        else:
+            self._marker = char
+
+    def _feed_string(self, data: str, position: int) -> int:
+        if (run := _STRING_RUN.match(data, position)) is not None:
+            if self._state != _IGNORED_STRING and self._collected_length <= _MAX_STRING_LENGTH:
+                self._collected.append(run.group())
+                self._collected_length += run.end() - position
+            return run.end()
+        char = data[position]
+        if char == ESC:
+            # Normally the first half of ST (ESC \); whatever follows, the string is over.
+            self._end_string()
+            self._state = _ESCAPE
+            self._begin_collecting()
+        elif char == _ST or (char == BEL and self._state == _OSC_STRING):
+            self._end_string()
+            self._state = _GROUND
+        elif char in (_CAN, _SUB):
+            self._state = _GROUND
+        return position + 1
+
+    def _end_string(self) -> None:
+        if self._collected_length > _MAX_STRING_LENGTH:
+            return
+        if self._state == _OSC_STRING:
+            self._handler.operating_system_command("".join(self._collected))
+        elif self._state == _DCS_STRING:
+            self._handler.device_control("".join(self._collected))