Source code for vtterm.parser

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Read VT100 and ANSI escape codes from a byte stream onto a `Screen`.

`Parser.feed` takes bytes as they arrive, in pieces of any size: a sequence
split across two calls finishes on the second. Printable ASCII goes to the
screen in runs. UTF-8 is decoded: box-drawing characters become the screen's
line-drawing cells, and another character the fonts don't have is drawn as
its nearest ASCII or as ``?``. OSC, DCS and the other string sequences are
read and ignored.

What the parser understands:

* Controls: BS, HT, LF, VT, FF, CR, SO, SI, CAN, SUB, ESC.
* ``ESC``: ``7`` ``8`` save and restore, ``D`` index, ``M`` reverse index,
  ``E`` next line, ``c`` reset, ``# 8`` alignment fill, and ``( 0`` ``( B``
  ``) 0`` ``) B`` to make G0 or G1 the DEC line-drawing set or ASCII.
* CSI: cursor moves (``A`` to ``H``, ``f``, ``d``, ``e``, ``a``, `````),
  erases (``J``, ``K``, ``X``), inserts and deletes (``@``, ``P``, ``L``,
  ``M``), scrolls (``S``, ``T``), the scroll region (``r``), save and
  restore (``s``, ``u``), SGR colors and styles (``m``), modes (``h``,
  ``l``) and reports (``n``, ``c``).
* SGR: bold, underline, reverse, the 8 and bright 8 colors, 256 colors,
  and 24-bit color fitted to the nearest of the 256.
* Modes: insert (4), newline (20), and DEC private cursor keys (1),
  origin (6), autowrap (7), cursor visible (25), the alternate screen (47,
  1047, 1049) and mouse reports (9, 1000, 1002, 1003, with 1006 for the SGR
  form).
"""

from .screen import BOLD, REVERSE, UNDERLINE

_GROUND = 0
_ESC = 1
_CSI = 2
_STRING = 3
_CHARSET = 4
_HASH = 5

_QUESTION = 0x3F
_MAX_PARAMS = 16

# Characters the 8-pixel-wide fonts don't have, as the ASCII that looks most like them.
_LOOKALIKE = {
    0x00A0: 32,
    0x00B7: 46,
    0x2018: 39,
    0x2019: 39,
    0x201C: 34,
    0x201D: 34,
    0x2022: 42,
    0x2026: 46,
    0x2013: 45,
    0x2014: 45,
    0x2190: 60,
    0x2192: 62,
    0x2191: 94,
    0x2193: 118,
    0x2588: 35,
    0x2591: 35,
    0x2592: 35,
    0x2593: 35,
}

# The DEC line-drawing set, for the bytes 0x5F to 0x7E: a line-drawing cell
# code, or the nearest ASCII for the symbols the renderer doesn't draw.
_DEC = b" \x01\x02    '#  \x0b\x0c\x0d\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19<>*!f\x1f"

# Box-drawing characters by shape, light, heavy, double and rounded, and the
# line-drawing cell code for each column.
_BOXES = (
    "\u2518\u2510\u250c\u2514\u253c\u2500\u251c\u2524\u2534\u252c\u2502",
    "\u251b\u2513\u250f\u2517\u254b\u2501\u2523\u252b\u253b\u2533\u2503",
    "\u255d\u2557\u2554\u255a\u256c\u2550\u2560\u2563\u2569\u2566\u2551",
    "\u256f\u256e\u256d\u2570",
)
_BOX_CODES = b"\x0b\x0c\x0d\x0e\x0f\x12\x15\x16\x17\x18\x19"

_PALETTE = None  # the 256 colors, made at the first 24-bit color


def _lookalike(cp):
    c = _LOOKALIKE.get(cp)
    if c is not None:
        return c
    if 0x2500 <= cp <= 0x257F:
        # Box drawing: a line-drawing cell of the same shape. Dashed lines
        # are drawn solid, and a mixed-weight joint is a plus.
        ch = chr(cp)
        for row in _BOXES:
            k = row.find(ch)
            if k >= 0:
                return _BOX_CODES[k]
        if cp in (0x2504, 0x2505, 0x2508, 0x2509, 0x254C, 0x254D):
            return 0x12
        if cp in (0x2506, 0x2507, 0x250A, 0x250B, 0x254E, 0x254F):
            return 0x19
        return 43
    if cp == 0x25C6:
        return 1
    return 63


[docs] class Parser: """Turns bytes from a program or a remote board into changes on a `Screen`. Args: screen (Screen): The grid to draw on. answer (callable): Called with the bytes a terminal sends back, such as the cursor position report for ``ESC [ 6 n``. ``None`` drops them. Attributes: onlcr (bool): Start each new line at column 0, as a tty does for a program that ends lines with a bare ``\\n``. Off by default, as on a VT100; `Console <vtterm.console.Console>` turns it on. """ def __init__(self, screen, answer=None): self.screen = screen self.answer = answer self.onlcr = False self._state = _GROUND self._params = [] self._cur = -1 self._private = 0 self._inter = 0 self._utf_need = 0 self._utf_cp = 0 self._one = bytearray(1)
[docs] def feed(self, data): """Act on ``data``, any number of bytes, continuing an unfinished sequence. Args: data (bytes): Bytes from the program or the remote end. """ screen = self.screen n = len(data) i = 0 if n and screen.view: screen.snap() while i < n: state = self._state if state == _GROUND and not self._utf_need: j = i while j < n and 32 <= data[j] < 127: j += 1 if j > i: if screen.g1 if screen.shift else screen.g0: self._put_graphics(data, i, j) else: screen.put(data, i, j) i = j continue b = data[i] i += 1 if state == _GROUND: if b >= 0x80 or self._utf_need: self._utf8(b) elif b == 0x1B: self._state = _ESC else: self._control(b) elif state == _CSI: self._csi_byte(b) elif state == _ESC: self._esc(b) elif state == _STRING: # Strings end with BEL or with ESC \ (the ESC state ignores the \). if b == 7: self._state = _GROUND elif b == 0x1B: self._state = _ESC elif b in (0x18, 0x1A): self._state = _GROUND elif state == _CHARSET: self._state = _GROUND # 0 is the line-drawing set; B and the national sets are ASCII here. if self._inter == 0x28: screen.g0 = b == 0x30 elif self._inter == 0x29: screen.g1 = b == 0x30 elif state == _HASH: self._state = _GROUND if b == 0x38: screen.fill_e()
def _put_graphics(self, data, start, end): # Printable bytes while the line-drawing set is in use. out = bytearray(data[start:end]) for k in range(len(out)): c = out[k] if c >= 0x5F: out[k] = _DEC[c - 0x5F] self.screen.put(out, 0, len(out)) def _put_code(self, c): self._one[0] = c self.screen.put(self._one, 0, 1) def _utf8(self, b): if self._utf_need: if 0x80 <= b <= 0xBF: self._utf_cp = (self._utf_cp << 6) | (b & 0x3F) self._utf_need -= 1 if not self._utf_need: self._put_code(_lookalike(self._utf_cp)) return # A broken sequence: show it, then treat this byte afresh. self._utf_need = 0 self._put_code(63) if b < 0x80: if b == 0x1B: self._state = _ESC elif 32 <= b < 127: self._put_code(b) else: self._control(b) return if 0xC2 <= b <= 0xDF: self._utf_need, self._utf_cp = 1, b & 0x1F elif 0xE0 <= b <= 0xEF: self._utf_need, self._utf_cp = 2, b & 0x0F elif 0xF0 <= b <= 0xF4: self._utf_need, self._utf_cp = 3, b & 0x07 else: self._put_code(63) def _control(self, b): s = self.screen if b == 10 or b == 11 or b == 12: s.wrap_pending = False if self.onlcr: s.carriage_return() s.linefeed() elif b == 13: s.carriage_return() elif b == 8: s.backspace() elif b == 9: s.tab() elif b == 0x0E: s.shift = 1 elif b == 0x0F: s.shift = 0 elif b == 0x18 or b == 0x1A: self._state = _GROUND def _esc(self, b): s = self.screen self._state = _GROUND if b == 0x5B: # [ self._state = _CSI self._params = [] self._cur = -1 self._private = 0 self._inter = 0 elif b in (0x5D, 0x50, 0x58, 0x5E, 0x5F): # ] P X ^ _ self._state = _STRING elif b in (0x28, 0x29, 0x2A, 0x2B): # ( ) * + self._state = _CHARSET self._inter = b elif b == 0x23: # # self._state = _HASH elif b == 0x37: # 7 s.save_cursor() elif b == 0x38: # 8 s.restore_cursor() elif b == 0x44: # D s.wrap_pending = False s.linefeed() elif b == 0x4D: # M s.reverse_index() elif b == 0x45: # E s.carriage_return() s.linefeed() elif b == 0x63: # c s.reset() elif b == 0x1B: self._state = _ESC def _csi_byte(self, b): if 0x30 <= b <= 0x39: cur = self._cur cur = max(cur, 0) if cur < 10000: cur = cur * 10 + b - 0x30 self._cur = cur elif b == 0x3B or b == 0x3A: if len(self._params) < _MAX_PARAMS: self._params.append(self._cur) self._cur = -1 elif 0x40 <= b <= 0x7E: self._state = _GROUND if len(self._params) < _MAX_PARAMS: self._params.append(self._cur) if not self._inter: self._csi(b, self._params) elif 0x3C <= b <= 0x3F: self._private = b elif 0x20 <= b <= 0x2F: self._inter = b elif b == 0x1B: self._state = _ESC elif b == 0x18 or b == 0x1A: self._state = _GROUND elif b < 0x20: self._control(b) def _csi(self, final, params): s = self.screen def count(i=0): v = params[i] if i < len(params) else -1 return v if v > 0 else 1 def value(i=0): v = params[i] if i < len(params) else -1 return max(0, v) if self._private: if final in (0x68, 0x6C) and self._private == _QUESTION: self._dec_modes(params, final == 0x68) return if final == 0x6D: # m self._sgr(params) elif final == 0x48 or final == 0x66: # H f s.move_to(count(0) - 1, count(1) - 1) elif final == 0x41: # A s.up(count()) elif final == 0x42 or final == 0x65: # B e s.down(count()) elif final == 0x43 or final == 0x61: # C a s.right(count()) elif final == 0x44: # D s.left(count()) elif final == 0x45: # E s.down(count()) s.carriage_return() elif final == 0x46: # F s.up(count()) s.carriage_return() elif final == 0x47 or final == 0x60: # G ` s.move_column(count() - 1) elif final == 0x64: # d s.move_row(count() - 1) elif final == 0x4A: # J s.erase_display(value()) elif final == 0x4B: # K s.erase_line(value()) elif final == 0x40: # @ s.insert_chars(count()) elif final == 0x50: # P s.delete_chars(count()) elif final == 0x58: # X s.erase_chars(count()) elif final == 0x4C: # L s.insert_lines(count()) elif final == 0x4D: # M s.delete_lines(count()) elif final == 0x53: # S s.scroll_up(count()) elif final == 0x54: # T s.scroll_down(count()) elif final == 0x72: # r s.set_region(count(0) - 1, (params[1] if len(params) > 1 and params[1] > 0 else s.rows) - 1) elif final == 0x73: # s s.save_cursor() elif final == 0x75: # u s.restore_cursor() elif final == 0x68 or final == 0x6C: # h l on = final == 0x68 for p in params: if p == 4: s.insert = on elif p == 20: s.newline = on elif final == 0x6E: # n v = value() if v == 5: self._send(b"\x1b[0n") elif v == 6: y = s.y - (s.top if s.origin else 0) self._send(("\x1b[%d;%dR" % (y + 1, s.x + 1)).encode()) elif final == 0x63: # c if value() == 0: self._send(b"\x1b[?1;2c") def _dec_modes(self, params, on): s = self.screen for p in params: if p == 1: s.app_cursor = on elif p == 6: s.origin = on s.move_to(0, 0) elif p == 7: s.autowrap = on if not on: s.wrap_pending = False elif p == 47 or p == 1047: if on: s.enter_alt() else: s.leave_alt() elif p == 1049: if on: s.save_cursor() s.enter_alt() elif s.alt: s.leave_alt() s.restore_cursor() elif p == 25: s.cursor_visible = on s.dirty[s.y] = 1 elif p == 9 or p == 1000 or p == 1002 or p == 1003: if on: s.mouse = p elif s.mouse == p: s.mouse = 0 elif p == 1006: s.mouse_sgr = on def _sgr(self, params): s = self.screen fg, bg, flags = s.fg, s.bg, s.flags i = 0 n = len(params) while i < n: p = params[i] i += 1 if p <= 0: fg, bg, flags = s.default_fg, s.default_bg, 0 elif p == 1: flags |= BOLD elif p == 4: flags |= UNDERLINE elif p == 7: flags |= REVERSE elif p == 22: flags &= ~BOLD elif p == 24: flags &= ~UNDERLINE elif p == 27: flags &= ~REVERSE elif 30 <= p <= 37: fg = p - 30 elif p == 39: fg = s.default_fg elif 40 <= p <= 47: bg = p - 40 elif p == 49: bg = s.default_bg elif 90 <= p <= 97: fg = p - 82 elif 100 <= p <= 107: bg = p - 92 elif p == 38 or p == 48: color, i = self._extended(params, i) if color is not None: if p == 38: fg = color else: bg = color s.set_pen(fg, bg, flags) def _extended(self, params, i): # 38;5;n or 38;2;r;g;b (and the same after 48). Returns (index, next i). n = len(params) if i >= n: return None, i kind = params[i] if kind == 5 and i + 1 < n: return max(0, min(255, params[i + 1])), i + 2 if kind == 2 and i + 3 < n: r, g, b = (max(0, min(255, v)) for v in params[i + 1 : i + 4]) return _nearest(r, g, b), i + 4 return None, n def _send(self, data): if self.answer is not None: self.answer(data)
def _nearest(r, g, b): global _PALETTE if _PALETTE is None: from palettes.ansi import AnsiPalette _PALETTE = AnsiPalette(length=256, color_depth=24) return _PALETTE.nearest(r, g, b)