MeshTerm/meshterm/emulator/run.py

# SPDX-License-Identifier: Apache-2.0
"""Run MeshTerm in the emulator: the TUI does not change, and the emulator supplies its terminal.

:func:`run` builds the three parts that all the front ends share:

* the :class:`~.vt.Terminal` that the bytes of the TUI go to,
* the prompt_toolkit output that writes to that terminal (:func:`panel_output`), and
* a pipe input that the key presses go into.

Then :func:`run` sets them as the app session of prompt_toolkit. It calls the ordinary CLI
with ``--platform`` set to the emulated handheld, exactly as a shell does. A *front end* is
the part that is different: where the pixels go, and where the key presses come from. The
front end gets the terminal, the lock that guards it, and a function to type with. It
starts the threads that it uses, and it gets a call each time a frame is complete.
"""

from __future__ import annotations

import threading
from collections.abc import Callable, Sequence
from typing import Protocol

from prompt_toolkit.application.current import create_app_session
from prompt_toolkit.data_structures import Size
from prompt_toolkit.input import create_pipe_input
from prompt_toolkit.output.color_depth import ColorDepth
from prompt_toolkit.output.vt100 import Vt100_Output

from .. import platforms
from .devices import CARDPUTER_ZERO_DEVICE, EmulatedDevice
from .vt import RGB, Terminal


def _hex(colour: str) -> RGB:
    raw = colour.removeprefix("#")
    return (int(raw[0:2], 16), int(raw[2:4], 16), int(raw[4:6], 16))


def _palette() -> tuple[RGB, ...]:
    """The 16 named colours: the same RGB values that the PicoCalc's console is set to."""
    from ..ui.theme import _VT_SLOTS

    return tuple(_hex(rgb) for _, _, rgb in _VT_SLOTS)


#: The ink of a cell whose style names no ink: the default foreground of a desktop
#: terminal. The truecolour theme that this platform runs was designed against it.
DEFAULT_FG: RGB = (204, 204, 204)
#: The paper of a cell whose style names no paper.
DEFAULT_BG: RGB = (0, 0, 0)


def default_colours(device: EmulatedDevice) -> tuple[RGB, RGB]:
    """The ink and the paper of a cell whose style names none, on ``device``.

    A Linux console uses slot 7 on slot 0 of its own palette. When MeshTerm draws a
    display itself, it uses the colours of a desktop terminal, because its truecolour
    theme was designed against them.
    """
    if device.console:
        palette = _palette()
        return palette[7], palette[0]
    return DEFAULT_FG, DEFAULT_BG


class _Sink:
    """The text stream that a :class:`Vt100_Output` writes to: bytes into the terminal."""

    encoding = "utf-8"

    def __init__(self, terminal: Terminal, lock: threading.Lock, on_frame: Callable[[], None]):
        self._terminal = terminal
        self._lock = lock
        self._on_frame = on_frame
        self._pending: list[str] = []

    def write(self, data: str) -> int:
        self._pending.append(data)
        return len(data)

    def flush(self) -> None:
        if not self._pending:
            return
        data = "".join(self._pending)
        self._pending.clear()
        with self._lock:
            self._terminal.feed(data)
        self._on_frame()

    def isatty(self) -> bool:
        return True

    def fileno(self) -> int:
        raise OSError("the emulator's output has no file descriptor")


def panel_output(
    terminal: Terminal,
    lock: threading.Lock,
    on_frame: Callable[[], None],
    depth: ColorDepth = ColorDepth.TRUE_COLOR,
) -> Vt100_Output:
    """A prompt_toolkit output that draws into ``terminal``: a fixed size, ``depth`` colours."""
    size = Size(rows=terminal.rows, columns=terminal.cols)
    return Vt100_Output(
        _Sink(terminal, lock, on_frame),  # type: ignore[arg-type]
        lambda: size,
        term="xterm-256color",
        default_color_depth=depth,
        enable_cpr=False,
    )


class FrontEnd(Protocol):
    """Where the pixels go, and where the key presses come from."""

    def frame_ready(self) -> None:
        """A complete frame is in the terminal. Draw it when it is convenient."""

    def close(self) -> None:
        """The TUI has ended. Stop."""


#: Builds a front end from the terminal, its lock, and a function that types into the TUI.
FrontEndFactory = Callable[[Terminal, threading.Lock, Callable[[str], None]], FrontEnd]


def run(
    argv: Sequence[str],
    front_end: FrontEndFactory,
    device: EmulatedDevice = CARDPUTER_ZERO_DEVICE,
) -> int:
    """Run the MeshTerm CLI with ``argv`` as it runs on ``device``, drawn by ``front_end``.

    The CLI resolves the platform of ``device`` as a platform that MeshTerm draws itself
    (:func:`~meshterm.platforms.drawn_by_meshterm`). Thus here the emulator draws the
    console of a PicoCalc, not the terminal from which the emulator was started.

    Returns:
        The exit status of the CLI.
    """
    from .. import cli

    lock = threading.Lock()
    with create_pipe_input() as pipe:
        terminal = Terminal(
            device.platform.readable_cols,
            device.platform.readable_rows,
            palette=_palette(),
            reply=pipe.send_text,
        )
        end = front_end(terminal, lock, pipe.send_text)
        output = panel_output(terminal, lock, end.frame_ready, device.color_depth)
        try:
            with create_app_session(input=pipe, output=output), platforms.drawn_by_meshterm():
                # Standalone, as a shell runs it: the CLI reports its own errors. At the
                # end, it raises SystemExit with the status.
                cli.app(args=["--platform", device.id, *argv], windows_expand_args=False)
            return 0
        except SystemExit as done:
            return done.code if isinstance(done.code, int) else (0 if done.code is None else 1)
        finally:
            end.close()