Source code for click_extra.capture.terminal

# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
"""Rebuild the screen a terminal shows from the stream a command writes at it.

A command prints text and control sequences, never a picture. The terminal makes
the picture: a carriage return sends the cursor back over its row, a cursor
position sends it anywhere on the screen, an erase blanks cells in the
background color in force, and a full-screen program draws on a second screen
that hides the first. {class}`TerminalScreen` is that terminal, held in memory,
so a recording can read every screen off it.

```{note}
The vocabulary is xterm's, as `ncurses` drives it for `TERM=xterm-256color`: the
terminal {data}`~click_extra.capture.recording.RECORDING_TERM` names to every
recorded command. A spinner or a progress bar uses a handful of it: a return, an
erase, a newline. A full-screen program uses much more: cursor addressing,
scroll regions, insertion and deletion of cells and rows, the line-drawing
character set and the alternate screen. Sequences that change nothing on screen
(keypad and mouse modes, window titles, hyperlinks, the queries a program sends
its terminal) are read whole and dropped, so their bytes never reach a cell.
```

```{todo}
Answer the cursor position report (`CSI 6 n`) and the device attributes query
(`CSI c`) once a recorded program blocks on either. No reply reaches the program
today, so one waiting for it waits until it gives up.
```
"""

from __future__ import annotations

import re
from typing import Any, Final

import click

from ..ansi import apply_sgr_codes
from ..layout import cell_width

TYPE_CHECKING = False
if TYPE_CHECKING:
    from typing import TypeAlias

    _Style: TypeAlias = tuple[tuple[str, Any], ...]
    _Cell: TypeAlias = tuple[str | None, _Style]

DEC_SPECIAL_GRAPHICS: Final[dict[str, str]] = {
    "_": " ",
    "`": "◆",
    "a": "▒",
    "b": "␉",
    "c": "␌",
    "d": "␍",
    "e": "␊",
    "f": "°",
    "g": "±",
    "h": "␤",
    "i": "␋",
    "j": "┘",
    "k": "┐",
    "l": "┌",
    "m": "└",
    "n": "┼",
    "o": "⎺",
    "p": "⎻",
    "q": "─",
    "r": "⎼",
    "s": "⎽",
    "t": "├",
    "u": "┤",
    "v": "┴",
    "w": "┬",
    "x": "│",
    "y": "≤",
    "z": "≥",
    "{": "π",
    "|": "≠",
    "}": "£",
    "~": "·",
}
"""Glyphs the DEC Special Graphics character set draws in place of ASCII.

A program selects the set with `ESC ( 0` and then writes `q` for a horizontal
rule, `x` for a vertical one and `l` for a corner. `ncurses` does so for its
line-drawing routines, like `box()` and the `ACS_*` characters. The screen keeps
the Unicode glyph, which the renderers draw as the shape it names.
"""

PENDING_LIMIT: Final = 4096
"""Characters an unfinished escape sequence may hold while its tail is awaited.

A sequence split across two reads waits for its tail, and each read re-reads
what waits. A string longer than this is skipped as it arrives instead, up to
the terminator closing it.
"""

TAB_WIDTH: Final = 8
"""Columns between two tab stops, until a program sets its own."""

_BLANK: Final[_Cell] = (None, ())
"""A cell nothing was written to, or that an erase cleared on no background."""

_STRING_END_RE: Final = re.compile(r"\x07|\x1b\\")
"""What closes a string: BEL, or the string terminator `ESC \\`."""

_PARTIAL_RE: Final = re.compile(
    r"\x1b(?:\[[0-?]*[ -/]*|\][^\x07\x1b]*\x1b?|[PX^_][^\x1b]*\x1b?|[ -/]*)\Z"
)
"""The opening of an escape sequence whose tail has not arrived yet.

A recorder reads whatever the terminal hands it, on boundaries that answer to
the pipe rather than to the stream, so a sequence routinely straddles two reads.
"""

_TOKEN_RE: Final = re.compile(
    # Printable text: everything but the C0 and C1 controls and DEL.
    r"(?P<text>[^\x00-\x1f\x7f-\x9f]+)"
    # A control sequence: parameters, intermediates, then the final byte.
    r"|\x1b\[(?P<parameters>[0-?]*)(?P<intermediates>[ -/]*)(?P<final>[@-~])"
    # An operating system command, closed by BEL or by the string terminator.
    r"|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)"
    # A device control string, and the three other strings no terminal draws.
    r"|\x1b[PX^_][^\x1b]*\x1b\\"
    # Any other escape: intermediates, then a final byte that opens no string.
    r"|\x1b(?P<escape>[ -/]*[0-OQ-WYZ\\`-~])"
    # One control character.
    r"|(?P<control>[\x00-\x1a\x1c-\x1f\x7f-\x9f])"
)
"""One unit of a terminal stream: a run of text, a control sequence, a string,
an escape or a control character."""


def _numbers(parameters: str) -> list[int]:
    """Read the numeric parameters of a control sequence.

    An omitted parameter reads as `0`, which each sequence then takes as its own
    default. A sub-parameter, after a colon, is ignored.

    :param parameters: the parameter bytes, private marker removed.
    :return: one number per parameter.
    """
    numbers = []
    for field in parameters.split(";"):
        head = field.split(":", 1)[0]
        numbers.append(int(head) if head.isdigit() else 0)
    return numbers


def _sgr_codes(parameters: str) -> list[int]:
    """Read the parameters of an SGR sequence, colon sub-parameters included.

    xterm reads a color in two spellings: `38;2;R;G;B`, and the one of ITU T.416,
    `38:2::R:G:B`, whose sub-parameters {func}`~click_extra.ansi.apply_sgr_codes`
    does not take. The second is rewritten into the first. So is a styled
    underline, `4:3` for a curly one, which a capture draws as a plain one.

    :param parameters: the parameter bytes of the sequence.
    :return: the codes, in the form {func}`~click_extra.ansi.apply_sgr_codes`
        reads.
    """
    codes: list[int] = []
    for field in parameters.split(";"):
        if ":" not in field:
            codes.append(int(field) if field.isdigit() else 0)
            continue
        parts = [int(part) if part.isdigit() else 0 for part in field.split(":")]
        head = parts[0]
        if head in (38, 48) and len(parts) > 4 and parts[1] == 2:
            codes.extend((head, 2, *parts[-3:]))
        elif head in (38, 48) and len(parts) > 2 and parts[1] == 5:
            codes.extend((head, 5, parts[2]))
        elif head == 4:
            codes.append(24 if parts[1] == 0 else 4)
        elif head not in (38, 48, 58):
            codes.append(head)
    return codes


[docs] class TerminalScreen: """The screen a terminal shows, rebuilt from what was written at it. The screen is a grid of cells, each holding one grapheme and the style it was written in. A write lands on the cells under the cursor and leaves the others alone, so a redraw shorter than the row it covers keeps the row's tail, the way a terminal does. An erase blanks cells in the background color in force, which is how a full-screen program paints a bar across the screen. Rows the cursor leaves through the top of a full screen stay above it, as a terminal's history does, and stay in the picture: {attr}`display` holds every row a command printed, not only the last screenful. A full-screen program draws on the alternate screen instead, which keeps no history and holds exactly the screen's height. Leaving it brings the first screen back as it was. ```{note} A screen of unknown size is boundless: a row never wraps, and a newline on the last row adds a row below it. That is the screen an in-process recording has, which nothing tells how big its terminal is. The renderers fold a long row at the capture's own width later. ``` """ def __init__( self, columns: int | None = None, rows: int | None = None, *, onlcr: bool = True, ) -> None: """Start on an empty screen, with the cursor in its top-left corner. :param columns: width of the terminal, in cells. `None` never wraps. :param rows: height of the terminal, in cells. `None` never scrolls. :param onlcr: return the cursor to the start of its row on every newline, as the `ONLCR` flag of a terminal driver does on the way to the screen. A pseudo-terminal applies the flag itself, so a stream read from one already carries a return before each newline that wants one, and a full-screen program clears the flag to move straight down. A stream written in-process went through no driver at all. :raises ValueError: when a stated size is not positive. """ if (columns is not None and columns < 1) or (rows is not None and rows < 1): raise ValueError(f"A terminal of {columns}x{rows} cells holds nothing.") self.width = columns """Width of the terminal, in cells, or `None` when unbounded.""" self.height = rows """Height of the terminal, in cells, or `None` when unbounded.""" self._onlcr = onlcr self._spans: dict[_Style, tuple[str, str]] = {} self._reset() def _reset(self) -> None: """Put every state back to the one a terminal starts in.""" self._main: list[list[_Cell]] = [] self._alternate: list[list[_Cell]] | None = None self._lines = self._main self._main_top = 0 self._row = 0 self._column = 0 self._wrap_pending = False self._state: dict[str, Any] = {} self._style: _Style = () self._charsets = ["B", "B"] self._shift = 0 self._autowrap = True self._insert = False self._origin = False self._newline_returns = self._onlcr self._margin_top = 0 self._margin_bottom = None if self.height is None else self.height - 1 self._tab_stops: set[int] | None = None self._saved: dict[bool, tuple[Any, ...]] = {} self._last = "" self._pending = "" self._skipping = False self._cursor_visible = True self._synchronized = False @property def alternate(self) -> bool: """Whether a full-screen program switched to the alternate screen.""" return self._lines is self._alternate @property def cursor(self) -> tuple[int, int]: """Row and column the cursor stands on, both counted from zero. The row counts from the top of {attr}`rows`, history included. """ return self._base() + self._row, self._column @property def cursor_visible(self) -> bool: """Whether the program shows its cursor, which a full-screen one hides.""" return self._cursor_visible @property def display(self) -> str: """The screen as it stands, rows joined by newlines.""" return "\n".join(self.rows) @property def rows(self) -> list[str]: """Every row of the picture, each as styled text. On the first screen, the history and every row down to the last one holding anything, or the cursor's when it stands lower: output closing on a newline leaves an empty last row, where the cursor waits. On the alternate screen, exactly its height. """ return [self._render(cells) for cells in self._picture()] @property def synchronized(self) -> bool: """Whether the program is in the middle of a synchronized update. A program opens one with `CSI ? 2026 h` and closes it with `CSI ? 2026 l`, asking its terminal to show nothing it drew in between until the close. """ return self._synchronized
[docs] def feed(self, text: str) -> None: """Replay what a command wrote, moving the screen to what it now shows. Safe to call with the stream cut anywhere: an escape sequence straddling two calls is held until the rest of it arrives. A sequence still unfinished when the stream ends never reaches the screen, having named nothing to draw. :param text: the stream, control sequences and all. """ text = self._pending + text self._pending = "" position, end = 0, len(text) if self._skipping: closing = _STRING_END_RE.search(text) if closing is None: # An escape ending the read may open the terminator. self._pending = "\x1b" if text.endswith("\x1b") else "" return position = closing.end() self._skipping = False while position < end: match = _TOKEN_RE.match(text, position) if match is None: # Only an escape sequence fails to match, either because its # tail is still on its way or because it is malformed. A # terminal drops the escape of a malformed one and reads on. if _PARTIAL_RE.match(text, position) is None: position += 1 elif end - position <= PENDING_LIMIT: self._pending = text[position:] return elif text[position + 1] in "]PX^_": # A string this long is skipped up to its terminator, whose # escape may end the read. self._skipping = True self._pending = "\x1b" if text.endswith("\x1b") else "" return else: position += 1 continue position = match.end() kind = match.lastgroup if kind == "text": self._print(match["text"]) elif kind == "final": self._sequence( match["parameters"], match["intermediates"], match["final"] ) elif kind == "escape": self._escape(match["escape"]) elif kind == "control": self._control(match["control"])
# What is left is a string, which draws nothing. def _base(self) -> int: """Index of the screen's top row in the lines of the buffer in use.""" return 0 if self.alternate else self._main_top def _cells(self, row: int) -> list[_Cell]: """The cells of a row of the screen, created when nothing reached it yet. :param row: the row, counted from the top of the screen. :return: the row's cells, which the caller may change in place. """ index = self._base() + row lines = self._lines while len(lines) <= index: lines.append([]) return lines[index] def _erased(self) -> _Cell: """The cell an erase leaves: a blank in the background color in force.""" background = self._state.get("bg") return _BLANK if background is None else (None, (("bg", background),)) def _erased_row(self) -> list[_Cell]: """A row an erase or a scroll leaves, painted like {meth}`_erased`.""" erased = self._erased() if erased == _BLANK or self.width is None: return [] return [erased] * self.width def _pad_screen(self) -> None: """Create every row of a bounded screen, so rows can move as a block.""" if self.height is not None: self._cells(self.height - 1) def _clamp_column(self, column: int) -> int: """Keep a column on the screen.""" if self.width is not None: column = min(column, self.width - 1) return max(column, 0) def _clamp_row(self, row: int) -> int: """Keep a row on the screen.""" if self.height is not None: row = min(row, self.height - 1) return max(row, 0) def _move(self, row: int, column: int) -> None: """Send the cursor to a cell, kept on the screen.""" self._row = self._clamp_row(row) self._column = self._clamp_column(column) self._wrap_pending = False def _home(self) -> None: """Send the cursor to the top-left corner of the screen or its region.""" self._move(self._margin_top if self._origin else 0, 0) def _print(self, text: str) -> None: """Lay printable text on the screen, one grapheme per cell or two. :param text: printable characters, with no control among them. """ # Deferred import: keeps wcwidth off the startup path of every CLI. from wcwidth import iter_graphemes graphics = self._charsets[self._shift] == "0" for grapheme in iter_graphemes(text): if graphics: grapheme = DEC_SPECIAL_GRAPHICS.get(grapheme, grapheme) width = cell_width(grapheme) if width: self._put(grapheme, min(width, 2)) self._last = grapheme else: self._combine(grapheme) def _put(self, grapheme: str, width: int) -> None: """Write one grapheme under the cursor and move the cursor past it. Writing the last column of a row leaves the cursor on it, with a wrap pending: the next grapheme starts the row below, while a return, a backspace or a cursor movement cancels the wrap. `ncurses` counts on this, which xterm calls the `xenl` glitch. :param grapheme: what to write. :param width: cells it covers, `1` or `2`. """ if self._wrap_pending: self._wrap_pending = False if self._autowrap: self._column = 0 self._index() if self.width is not None and self._column + width > self.width: if width > self.width: return if self._autowrap: # A wide glyph not fitting on the row moves down whole. self._column = 0 self._index() else: self._column = self.width - width cells = self._cells(self._row) column = self._column if self._insert: self._open(cells, column, width) self._split_wide(cells, column, column + width) if len(cells) < column + width: cells.extend([_BLANK] * (column + width - len(cells))) cells[column] = (grapheme, self._style) if width == 2: cells[column + 1] = ("", self._style) self._column += width if self.width is not None and self._column >= self.width: self._column = self.width - 1 self._wrap_pending = self._autowrap def _combine(self, mark: str) -> None: """Join a zero-width character to the grapheme before the cursor. A combining accent or a variation selector arriving in a later read than its base still lands on it. """ column = self._column if self._wrap_pending else self._column - 1 cells = self._cells(self._row) if column >= len(cells): return if column > 0 and cells[column][0] == "": column -= 1 if column < 0: return glyph, style = cells[column] cells[column] = ((glyph or " ") + mark, style) @staticmethod def _split_wide(cells: list[_Cell], start: int, stop: int) -> None: """Blank the half a change between `start` and `stop` leaves of a wide glyph. A wide glyph spans two cells. Overwriting or erasing one of them leaves the other on its own, which a terminal shows as a blank. """ if 0 < start < len(cells) and cells[start][0] == "": cells[start - 1] = (None, cells[start - 1][1]) if stop < len(cells) and cells[stop][0] == "": cells[stop] = (None, cells[stop][1]) def _open(self, cells: list[_Cell], column: int, count: int) -> None: """Insert blank cells at `column`, pushing the rest of the row right.""" if len(cells) <= column: return self._split_wide(cells, column, column) cells[column:column] = [self._erased()] * count if self.width is not None and len(cells) > self.width: del cells[self.width :] # A wide glyph pushed half off the row loses its other half too. if cells and cells[-1][0] and cell_width(cells[-1][0]) == 2: cells[-1] = (None, cells[-1][1]) def _control(self, char: str) -> None: """Act on one control character.""" if char in "\n\x0b\x0c": if self._newline_returns: self._column = 0 self._index() elif char == "\r": self._column = 0 self._wrap_pending = False elif char == "\b": self._column = max(self._column - 1, 0) self._wrap_pending = False elif char == "\t": self._tab(1) elif char == "\x0e": self._shift = 1 elif char == "\x0f": self._shift = 0 # A bell and the remaining controls change nothing on screen. def _escape(self, sequence: str) -> None: """Act on an escape sequence that is not a control sequence. :param sequence: what follows the escape: intermediates and final byte. """ if sequence == "7": self._save_cursor() elif sequence == "8": self._restore_cursor() elif sequence == "D": self._index() elif sequence == "E": self._column = 0 self._index() elif sequence == "M": self._reverse_index() elif sequence == "H": self._set_tab_stop() elif sequence == "c": self._reset() elif len(sequence) == 2 and sequence[0] in "()": # Designates the character set G0, with `(`, or G1, with `)`. Only # line drawing reads differently from ASCII. self._charsets["()".index(sequence[0])] = sequence[1] # Keypad modes and the other character sets change nothing on screen. def _sequence(self, parameters: str, intermediates: str, final: str) -> None: """Act on one control sequence. :param parameters: the parameter bytes, private marker included. :param intermediates: the intermediate bytes, which most sequences lack. :param final: the final byte, naming the function. """ private = parameters[0] if parameters and parameters[0] in "<=>?" else "" parameters = parameters[len(private) :] if intermediates: if intermediates == "!" and final == "p" and not private: self._soft_reset() # The cursor's shape and the rest change nothing the screen holds. return if private: if private == "?" and final in "hl": self._private_modes(_numbers(parameters), final == "h") return if final == "m": apply_sgr_codes(_sgr_codes(parameters), self._state) self._style = tuple(sorted(self._state.items())) return numbers = _numbers(parameters) count = numbers[0] or 1 if final == "A": top = self._margin_top if self._row >= self._margin_top else 0 self._move(max(self._row - count, top), self._column) elif final in "Be": bottom = self._margin_bottom if bottom is not None and self._row > bottom: bottom = None row = self._row + count self._move(row if bottom is None else min(row, bottom), self._column) elif final in "Ca": self._move(self._row, self._column + count) elif final == "D": self._move(self._row, self._column - count) elif final == "E": self._sequence(parameters, "", "B") self._column = 0 elif final == "F": self._sequence(parameters, "", "A") self._column = 0 elif final in "G`": self._move(self._row, count - 1) elif final in "Hf": row = (numbers[0] or 1) - 1 column = (numbers[1] if len(numbers) > 1 else 0) or 1 if self._origin: bottom = self._margin_bottom row = self._margin_top + row if bottom is not None: row = min(row, bottom) self._move(row, column - 1) elif final == "I": self._tab(count) elif final == "Z": self._tab(-count) elif final == "J": self._erase_display(numbers[0]) elif final == "K": self._erase_line(numbers[0]) elif final == "L": self._insert_rows(count) elif final == "M": self._delete_rows(count) elif final == "P": self._delete_cells(count) elif final == "S": self._scroll_up(count) elif final == "T" and len(numbers) == 1: # With more parameters, this is xterm's mouse highlight tracking. self._scroll_down(count) elif final == "X": self._erase_cells(count) elif final == "@": self._open(self._cells(self._row), self._column, count) elif final == "b": if self._last: width = min(cell_width(self._last), 2) for _ in range(count): self._put(self._last, width) elif final == "d": self._move(count - 1, self._column) elif final == "g": self._clear_tab_stops(numbers[0]) elif final in "hl": for mode in numbers: if mode == 4: self._insert = final == "h" elif mode == 20: self._newline_returns = final == "h" elif final == "r": self._set_margins(numbers) elif final == "s" and not parameters: self._save_cursor() elif final == "u" and not parameters: self._restore_cursor() # Queries, window operations and the rest change nothing on screen. def _private_modes(self, modes: list[int], enable: bool) -> None: """Set or reset DEC private modes, the `CSI ? … h` and `CSI ? … l` family.""" for mode in modes: if mode == 6: self._origin = enable self._home() elif mode == 7: self._autowrap = enable if not enable: self._wrap_pending = False elif mode == 25: self._cursor_visible = enable elif mode in (47, 1047): self._switch_screen(enable) if not enable and mode == 1047: # Left cleared, so coming back finds it blank. self._alternate = None elif mode == 1048: if enable: self._save_cursor() else: self._restore_cursor() elif mode == 1049: if enable: self._save_cursor() self._alternate = None self._switch_screen(True) else: self._switch_screen(False) self._restore_cursor() elif mode == 2026: self._synchronized = enable def _switch_screen(self, alternate: bool) -> None: """Draw on the alternate screen, or back on the first one.""" if alternate == self.alternate: return if alternate: if self._alternate is None: self._alternate = [[] for _ in range(self.height or 0)] self._lines = self._alternate else: self._lines = self._main def _save_cursor(self) -> None: """Remember the cursor and its rendition, one memory per screen.""" self._saved[self.alternate] = ( self._row, self._column, self._wrap_pending, dict(self._state), list(self._charsets), self._shift, self._origin, ) def _restore_cursor(self) -> None: """Bring back what {meth}`_save_cursor` remembered for this screen. With nothing remembered, the cursor goes home in the default rendition. """ saved = self._saved.get(self.alternate) if saved is None: saved = (0, 0, False, {}, ["B", "B"], 0, False) row, column, wrap, state, charsets, shift, origin = saved self._move(row, column) self._wrap_pending = wrap self._state = dict(state) self._style = tuple(sorted(self._state.items())) self._charsets = list(charsets) self._shift = shift self._origin = origin def _soft_reset(self) -> None: """Reset the modes and the rendition, leaving the screen's cells alone.""" self._state = {} self._style = () self._charsets = ["B", "B"] self._shift = 0 self._autowrap = True self._insert = False self._origin = False self._cursor_visible = True self._margin_top = 0 self._margin_bottom = None if self.height is None else self.height - 1 self._saved.pop(self.alternate, None) def _set_margins(self, numbers: list[int]) -> None: """Bound the rows a newline or a deletion scrolls, then go home.""" if self.height is None: return top = (numbers[0] or 1) - 1 bottom = min( ((numbers[1] if len(numbers) > 1 else 0) or self.height) - 1, self.height - 1, ) if top < bottom: self._margin_top, self._margin_bottom = top, bottom self._home() def _index(self) -> None: """Move the cursor down a row, scrolling the region from its last row.""" self._wrap_pending = False if self.height is None: self._row += 1 elif self._row == self._margin_bottom: self._scroll_up(1) elif self._row < self.height - 1: self._row += 1 def _reverse_index(self) -> None: """Move the cursor up a row, scrolling the region from its first row.""" self._wrap_pending = False if self.height is not None and self._row == self._margin_top: self._scroll_down(1) elif self._row > 0: self._row -= 1 def _scroll_up(self, count: int) -> None: """Move the rows of the scroll region up, blank rows entering below. Scrolling the whole first screen keeps the rows leaving its top as the history above it. A region or the alternate screen drops them. """ if self.height is None or self._margin_bottom is None: return top, bottom = self._margin_top, self._margin_bottom count = min(count, bottom - top + 1) self._pad_screen() lines, base = self._lines, self._base() if not self.alternate and top == 0 and bottom == self.height - 1: lines.extend(self._erased_row() for _ in range(count)) self._main_top += count return del lines[base + top : base + top + count] for _ in range(count): lines.insert(base + bottom - count + 1, self._erased_row()) def _scroll_down(self, count: int) -> None: """Move the rows of the scroll region down, blank rows entering above.""" if self.height is None or self._margin_bottom is None: return top, bottom = self._margin_top, self._margin_bottom count = min(count, bottom - top + 1) self._pad_screen() lines, base = self._lines, self._base() del lines[base + bottom - count + 1 : base + bottom + 1] for _ in range(count): lines.insert(base + top, self._erased_row()) def _insert_rows(self, count: int) -> None: """Insert blank rows at the cursor, pushing the region below it down.""" bottom = self._margin_bottom if self._row < self._margin_top or (bottom is not None and self._row > bottom): return lines, index = self._lines, self._base() + self._row if bottom is None: self._cells(self._row) lines[index:index] = [self._erased_row() for _ in range(count)] else: count = min(count, bottom - self._row + 1) self._pad_screen() del lines[self._base() + bottom - count + 1 : self._base() + bottom + 1] lines[index:index] = [self._erased_row() for _ in range(count)] self._column = 0 self._wrap_pending = False def _delete_rows(self, count: int) -> None: """Delete rows at the cursor, pulling the region below it up.""" bottom = self._margin_bottom if self._row < self._margin_top or (bottom is not None and self._row > bottom): return lines, index = self._lines, self._base() + self._row if bottom is None: del lines[index : index + count] else: count = min(count, bottom - self._row + 1) self._pad_screen() del lines[index : index + count] for _ in range(count): lines.insert(self._base() + bottom - count + 1, self._erased_row()) self._column = 0 self._wrap_pending = False def _delete_cells(self, count: int) -> None: """Delete cells at the cursor, pulling the rest of the row left.""" cells = self._cells(self._row) column = self._column erased = self._erased() self._wrap_pending = False if self.width is None or erased == _BLANK: # The cells entering at the right edge are blank, which a row # ending early already shows. self._split_wide(cells, column, column + count) del cells[column : column + count] return count = min(count, self.width - column) cells.extend([_BLANK] * (self.width - len(cells))) self._split_wide(cells, column, column + count) del cells[column : column + count] cells.extend([erased] * count) def _erase_cells(self, count: int) -> None: """Blank cells from the cursor on, without moving the rest of the row.""" cells = self._cells(self._row) start = self._column stop = start + count if self.width is not None: stop = min(stop, self.width) self._split_wide(cells, start, stop) if len(cells) < stop: cells.extend([_BLANK] * (stop - len(cells))) cells[start:stop] = [self._erased()] * (stop - start) self._wrap_pending = False def _erase_line(self, mode: int) -> None: """Blank part of the cursor's row: after it, before it, or all of it.""" cells = self._cells(self._row) column = self._column erased = self._erased() if mode == 0: self._split_wide(cells, column, column) if erased == _BLANK or self.width is None: del cells[column:] else: if len(cells) < column: cells.extend([_BLANK] * (column - len(cells))) cells[column:] = [erased] * (self.width - column) elif mode == 1: stop = column + 1 self._split_wide(cells, stop, stop) if len(cells) < stop: cells.extend([_BLANK] * (stop - len(cells))) cells[:stop] = [erased] * stop elif mode == 2: self._lines[self._base() + self._row] = self._erased_row() self._wrap_pending = False def _erase_display(self, mode: int) -> None: """Blank part of the screen: after the cursor, before it, or all of it. Mode `3` drops the history above the first screen instead. """ if self._erased() != _BLANK: # A painted erase reaches rows nothing was written to yet. self._pad_screen() lines, base = self._lines, self._base() end = base + self.height if self.height is not None else len(lines) cursor = base + self._row if mode == 0: self._erase_line(0) for index in range(cursor + 1, min(end, len(lines))): lines[index] = self._erased_row() elif mode == 1: for index in range(base, cursor): lines[index] = self._erased_row() self._erase_line(1) elif mode == 2: for index in range(base, min(end, len(lines))): lines[index] = self._erased_row() elif mode == 3 and not self.alternate: del lines[: self._main_top] self._main_top = 0 self._wrap_pending = False def _tab(self, count: int) -> None: """Move the cursor to the next tab stop, or back to the previous one.""" for _ in range(abs(count)): column = self._column if count > 0: if self._tab_stops is None: column = (column // TAB_WIDTH + 1) * TAB_WIDTH else: later = [stop for stop in self._tab_stops if stop > column] if later: column = min(later) elif self.width is not None: column = self.width - 1 elif self._tab_stops is None: column = max((column - 1) // TAB_WIDTH * TAB_WIDTH, 0) else: earlier = [stop for stop in self._tab_stops if stop < column] column = max(earlier) if earlier else 0 self._move(self._row, column) def _default_tab_stops(self) -> set[int]: """The stops a terminal starts with, every {data}`TAB_WIDTH` columns.""" return set(range(0, self.width or 1024, TAB_WIDTH)) def _set_tab_stop(self) -> None: """Add a tab stop at the cursor's column.""" if self._tab_stops is None: self._tab_stops = self._default_tab_stops() self._tab_stops.add(self._column) def _clear_tab_stops(self, mode: int) -> None: """Remove the tab stop at the cursor's column, or every one of them.""" if mode == 3: self._tab_stops = set() elif mode == 0: if self._tab_stops is None: self._tab_stops = self._default_tab_stops() self._tab_stops.discard(self._column) def _picture(self) -> list[list[_Cell]]: """The rows {attr}`rows` renders, each a list of cells.""" lines = self._lines if self.alternate and self.height is not None: return lines last = self._base() + self._row for index in range(len(lines) - 1, last, -1): if any(cell != _BLANK for cell in lines[index]): last = index break return [lines[index] if index < len(lines) else [] for index in range(last + 1)] def _render(self, cells: list[_Cell]) -> str: """Write one row back as styled text, its trailing blanks left out. A blank painted with a background is kept: it is part of a bar. """ end = len(cells) while end and cells[end - 1] == _BLANK: end -= 1 parts: list[str] = [] run: list[str] = [] style: _Style = () for glyph, cell_style in cells[:end]: if glyph == "": continue if cell_style != style: parts.append(self._wrap("".join(run), style)) run, style = [], cell_style run.append(" " if glyph is None else glyph) parts.append(self._wrap("".join(run), style)) return "".join(parts) def _wrap(self, text: str, style: _Style) -> str: """Wrap a run of text in the escapes of its style. Written by {func}`click.style`, the way a Click Extra CLI writes a styled run in the first place, so a recorded frame reads back exactly as the CLI printed it. """ if not text or not style: return text span = self._spans.get(style) if span is None: opening, _, closing = click.style("\0", **dict(style)).partition("\0") span = self._spans[style] = (opening, closing) return f"{span[0]}{text}{span[1]}"