py-sparcli 0.3.0__py3-none-any.whl

sparcli/input/line_edit.py

@@ -0,0 +1,229 @@
+"""
+sparcli.input.line_edit
+======================
+
+Defines :class:`LineEditor`, the shared text-editing core for input widgets.
+
+This is the single source of truth for caret movement, selection and edit
+operations behind both single- and multi-line prompts. Widgets own the control
+keys (Enter, Esc, ...); the editor only edits. The clipboard is in-process (no
+system dependency); the terminal's bracketed paste still delivers external text
+through :meth:`LineEditor.insert_str`.
+"""
+
+from __future__ import annotations
+
+
+class LineEditor:
+    """A caret-and-selection text editor over a character buffer."""
+
+    __slots__ = ("_chars", "_cursor", "_anchor", "_clipboard", "_multiline")
+
+    def __init__(self, initial: str = "", *, multiline: bool = False) -> None:
+        self._chars: list[str] = list(initial)
+        self._cursor: int = len(self._chars)
+        self._anchor: int | None = None
+        self._clipboard: str = ""
+        self._multiline: bool = multiline
+
+    def value(self) -> str:
+        """Returns the current text."""
+        return "".join(self._chars)
+
+    def set_value(self, value: str) -> None:
+        """Replaces the entire buffer and moves the caret to the end."""
+        self._chars = list(value)
+        self._cursor = len(self._chars)
+        self._anchor = None
+
+    def __len__(self) -> int:
+        """Returns the number of characters."""
+        return len(self._chars)
+
+    @property
+    def cursor(self) -> int:
+        """Returns the caret position as a character index."""
+        return self._cursor
+
+    def lines(self) -> list[str]:
+        """Returns the display lines (split on newlines)."""
+        return self.value().split("\n")
+
+    def cursor_line_col(self) -> tuple[int, int]:
+        """Returns the caret's ``(line, column)`` in characters."""
+        line = 0
+        col = 0
+        for ch in self._chars[: self._cursor]:
+            if ch == "\n":
+                line += 1
+                col = 0
+            else:
+                col += 1
+        return (line, col)
+
+    def selection_range(self) -> tuple[int, int] | None:
+        """Returns the selection range as ``(start, end)`` if any."""
+        anchor = self._anchor
+        if anchor is None or anchor == self._cursor:
+            return None
+        return (min(anchor, self._cursor), max(anchor, self._cursor))
+
+    def insert_char(self, ch: str) -> None:
+        """Inserts a character, replacing any selection."""
+        self._delete_selection()
+        self._chars.insert(self._cursor, ch)
+        self._cursor += 1
+
+    def insert_str(self, text: str) -> None:
+        """
+        Inserts a string (e.g. a paste), replacing any selection.
+
+        In single-line mode newlines are converted to spaces.
+        """
+        self._delete_selection()
+        for ch in text:
+            char = " " if not self._multiline and ch == "\n" else ch
+            self._chars.insert(self._cursor, char)
+            self._cursor += 1
+
+    def insert_newline(self) -> None:
+        """Inserts a newline (multi-line only; ignored otherwise)."""
+        if self._multiline:
+            self.insert_char("\n")
+
+    def backspace(self) -> None:
+        """Deletes the character before the caret, or the selection."""
+        if self._delete_selection():
+            return
+        if self._cursor > 0:
+            self._cursor -= 1
+            del self._chars[self._cursor]
+
+    def delete(self) -> None:
+        """Deletes the character at the caret, or the selection."""
+        if self._delete_selection():
+            return
+        if self._cursor < len(self._chars):
+            del self._chars[self._cursor]
+
+    def move_left(self, *, select: bool) -> None:
+        """Moves the caret left by one character."""
+        self._update_anchor(select=select)
+        if self._cursor > 0:
+            self._cursor -= 1
+
+    def move_right(self, *, select: bool) -> None:
+        """Moves the caret right by one character."""
+        self._update_anchor(select=select)
+        if self._cursor < len(self._chars):
+            self._cursor += 1
+
+    def move_home(self, *, select: bool) -> None:
+        """Moves the caret to the start of the current line."""
+        self._update_anchor(select=select)
+        self._cursor = self._line_start(self._cursor)
+
+    def move_end(self, *, select: bool) -> None:
+        """Moves the caret to the end of the current line."""
+        self._update_anchor(select=select)
+        self._cursor = self._line_end(self._cursor)
+
+    def move_up(self, *, select: bool) -> None:
+        """Moves the caret up one line, preserving the column."""
+        self._update_anchor(select=select)
+        start = self._line_start(self._cursor)
+        if start == 0:
+            return
+        col = self._cursor - start
+        prev_start = self._line_start(start - 1)
+        prev_end = start - 1
+        self._cursor = min(prev_start + col, prev_end)
+
+    def move_down(self, *, select: bool) -> None:
+        """Moves the caret down one line, preserving the column."""
+        self._update_anchor(select=select)
+        end = self._line_end(self._cursor)
+        if end >= len(self._chars):
+            return
+        col = self._cursor - self._line_start(self._cursor)
+        next_start = end + 1
+        next_end = self._line_end(next_start)
+        self._cursor = min(next_start + col, next_end)
+
+    def select_all(self) -> None:
+        """Selects the entire buffer."""
+        self._anchor = 0
+        self._cursor = len(self._chars)
+
+    def delete_word_back(self) -> None:
+        """Deletes the previous whitespace-delimited word."""
+        if self._delete_selection():
+            return
+        index = self._cursor
+        while index > 0 and self._chars[index - 1].isspace():
+            index -= 1
+        while index > 0 and not self._chars[index - 1].isspace():
+            index -= 1
+        del self._chars[index : self._cursor]
+        self._cursor = index
+
+    def kill_to_line_start(self) -> None:
+        """Deletes from the caret to the start of the current line."""
+        start = self._line_start(self._cursor)
+        del self._chars[start : self._cursor]
+        self._cursor = start
+
+    def kill_to_line_end(self) -> None:
+        """Deletes from the caret to the end of the current line."""
+        end = self._line_end(self._cursor)
+        del self._chars[self._cursor : end]
+
+    def copy(self) -> None:
+        """Copies the selection to the in-process clipboard."""
+        span = self.selection_range()
+        if span is not None:
+            start, end = span
+            self._clipboard = "".join(self._chars[start:end])
+
+    def cut(self) -> None:
+        """Cuts the selection to the in-process clipboard."""
+        self.copy()
+        self._delete_selection()
+
+    def paste(self) -> None:
+        """Pastes the in-process clipboard at the caret."""
+        self.insert_str(self._clipboard)
+
+    def _update_anchor(self, *, select: bool) -> None:
+        """Sets or clears the selection anchor before a movement."""
+        if select:
+            if self._anchor is None:
+                self._anchor = self._cursor
+        else:
+            self._anchor = None
+
+    def _delete_selection(self) -> bool:
+        """Deletes the current selection; returns whether anything was removed."""
+        span = self.selection_range()
+        if span is None:
+            self._anchor = None
+            return False
+        start, end = span
+        del self._chars[start:end]
+        self._cursor = start
+        self._anchor = None
+        return True
+
+    def _line_start(self, index: int) -> int:
+        """Returns the index of the start of the line containing ``index``."""
+        for pos in range(index - 1, -1, -1):
+            if self._chars[pos] == "\n":
+                return pos + 1
+        return 0
+
+    def _line_end(self, index: int) -> int:
+        """Returns the index of the end of the line containing ``index``."""
+        for pos in range(index, len(self._chars)):
+            if self._chars[pos] == "\n":
+                return pos
+        return len(self._chars)

sparcli/input/number.py

@@ -0,0 +1,232 @@
+"""
+sparcli.input.number
+====================
+
+Defines :class:`NumberInput`, a numeric prompt with an optional calculator.
+
+The prompt edits a single line through :class:`~sparcli.input.line_edit.\
+LineEditor`, accepts only characters that can form a number (or, in calculator
+mode, a full arithmetic expression), and adjusts the value with the Up and Down
+arrows. On submit it parses the field, clamps it to the configured range and
+returns the value in an :class:`~sparcli.input.outcome.Outcome`.
+"""
+
+from __future__ import annotations
+
+from sparcli.core.render import Rendered
+from sparcli.core.style import Style
+from sparcli.core.terminal import is_input_tty
+from sparcli.core.theme import theme
+from sparcli.errors import NoTerminalError
+from sparcli.input.calc import CalcError, evaluate, parse_number
+from sparcli.input.event import (
+    EventKind,
+    EventSource,
+    InputEvent,
+    KeyCode,
+    KeyKind,
+    KeyPress,
+    TerminalSource,
+)
+from sparcli.input.field import error_line, field_line, value_line
+from sparcli.input.guard import TerminalGuard
+from sparcli.input.line_edit import LineEditor
+from sparcli.input.outcome import Outcome
+from sparcli.input.prompt import Flow, run_prompt
+
+# Characters that may form a plain number.
+_NUMERIC_CHARS = "0123456789.,-"
+# Extra characters accepted only in calculator mode.
+_CALC_CHARS = "+*/() "
+
+
+class _State:
+    """The mutable state of a running number prompt."""
+
+    __slots__ = ("editor", "error")
+
+    def __init__(self, editor: LineEditor) -> None:
+        self.editor = editor
+        self.error: str | None = None
+
+
+class NumberInput:
+    """A numeric input prompt with bounds, step and optional calculator mode."""
+
+    __slots__ = (
+        "_prompt",
+        "_initial",
+        "_minimum",
+        "_maximum",
+        "_step",
+        "_decimals",
+        "_calculator",
+    )
+
+    def __init__(
+        self,
+        prompt: str = "",
+        *,
+        initial: float = 0.0,
+        minimum: float = float("-inf"),
+        maximum: float = float("inf"),
+        step: float = 1.0,
+        decimals: int = 0,
+        calculator: bool = False,
+    ) -> None:
+        self._prompt = prompt
+        self._initial = initial
+        self._minimum = minimum
+        self._maximum = maximum
+        self._step = step
+        self._decimals = max(decimals, 0)
+        self._calculator = calculator
+
+    def initial(self, value: float) -> NumberInput:
+        """Sets the initial value and returns ``self``."""
+        self._initial = value
+        return self
+
+    def range(self, minimum: float, maximum: float) -> NumberInput:
+        """Sets the inclusive ``[minimum, maximum]`` bounds and returns self."""
+        self._minimum = minimum
+        self._maximum = maximum
+        return self
+
+    def step(self, step: float) -> NumberInput:
+        """Sets the step used by Up and Down and returns ``self``."""
+        self._step = step
+        return self
+
+    def decimals(self, decimals: int) -> NumberInput:
+        """Sets the number of decimal places shown and returns ``self``."""
+        self._decimals = max(decimals, 0)
+        return self
+
+    def calculator(self) -> NumberInput:
+        """Enables calculator expressions (``+ - * / ( )``); returns self."""
+        self._calculator = True
+        return self
+
+    def run(self) -> Outcome[float]:
+        """
+        Runs the prompt on the real terminal.
+
+        Returns
+        -------
+        Outcome[float]
+            The clamped submitted value or a cancellation.
+
+        Raises
+        ------
+        NoTerminalError
+            If there is no interactive terminal.
+        """
+        if not is_input_tty():
+            raise NoTerminalError()
+        with TerminalGuard():
+            return self.run_with(TerminalSource())
+
+    def run_with(self, source: EventSource) -> Outcome[float]:
+        """Runs the prompt against any event source (used for tests)."""
+        state = _State(LineEditor(self._format(self._initial)))
+        return run_prompt(source, state, self._render, self._handle)
+
+    def frame(self) -> Rendered:
+        """Renders the prompt's static frame without running it."""
+        state = _State(LineEditor(self._format(self._initial)))
+        return self._render(state, False)
+
+    def _render(self, state: _State, final: bool) -> Rendered:
+        """Builds the prompt frame; ``final`` drops the cursor after submit."""
+        active = theme()
+        value = state.editor.value()
+        if final:
+            line = value_line(self._prompt, value, Style.new(), active)
+            return Rendered([line])
+        lines = [
+            field_line(
+                self._prompt, value, state.editor.cursor, Style.new(), active
+            )
+        ]
+        if state.error is not None:
+            lines.append(error_line(state.error, active))
+        return Rendered(lines)
+
+    def _handle(self, state: _State, event: InputEvent) -> Flow[float]:
+        """Handles one input event."""
+        if event.kind is not EventKind.KEY or event.key is None:
+            return Flow[float].cont()
+        return self._handle_key(state, event.key)
+
+    def _handle_key(self, state: _State, key: KeyPress) -> Flow[float]:
+        """Handles a single key press."""
+        if key.is_ctrl("u"):
+            state.editor.kill_to_line_start()
+            return Flow[float].cont()
+        code = key.code
+        if code == KeyCode.ESC:
+            return Flow[float].cancel()
+        if code == KeyCode.ENTER:
+            return self._submit(state)
+        self._edit(state, code)
+        return Flow[float].cont()
+
+    def _edit(self, state: _State, code: KeyCode) -> None:
+        """Applies a non-terminal editing or navigation key."""
+        editor = state.editor
+        if code == KeyCode.UP:
+            self._adjust(state, self._step)
+        elif code == KeyCode.DOWN:
+            self._adjust(state, -self._step)
+        elif code == KeyCode.LEFT:
+            editor.move_left(select=False)
+        elif code == KeyCode.RIGHT:
+            editor.move_right(select=False)
+        elif code == KeyCode.BACKSPACE:
+            editor.backspace()
+        elif code == KeyCode.DELETE:
+            editor.delete()
+        elif code.kind is KeyKind.CHAR and code.ch is not None:
+            self._insert(state, code.ch)
+
+    def _insert(self, state: _State, ch: str) -> None:
+        """Inserts ``ch`` if it is a valid input character."""
+        if not self._accepts(ch):
+            return
+        state.editor.insert_char(ch)
+        state.error = None
+
+    def _accepts(self, ch: str) -> bool:
+        """Returns whether ``ch`` may be typed into the field."""
+        numeric = ch in _NUMERIC_CHARS
+        calc = ch in _CALC_CHARS
+        return numeric or (self._calculator and calc)
+
+    def _adjust(self, state: _State, delta: float) -> None:
+        """Adjusts the current value by ``delta`` and reformats the field."""
+        try:
+            current = parse_number(state.editor.value())
+        except CalcError:
+            current = 0.0
+        value = self._clamp(current + delta)
+        state.editor.set_value(self._format(value))
+        state.error = None
+
+    def _submit(self, state: _State) -> Flow[float]:
+        """Evaluates the field and submits the clamped value, or shows error."""
+        text = state.editor.value()
+        try:
+            value = evaluate(text) if self._calculator else parse_number(text)
+        except CalcError as error:
+            state.error = str(error)
+            return Flow[float].cont()
+        return Flow[float].submit(self._clamp(value))
+
+    def _clamp(self, value: float) -> float:
+        """Clamps ``value`` to the configured range."""
+        return max(self._minimum, min(value, self._maximum))
+
+    def _format(self, value: float) -> str:
+        """Formats ``value`` with the configured number of decimals."""
+        return f"{value:.{self._decimals}f}"

sparcli/input/outcome.py

@@ -0,0 +1,107 @@
+"""
+sparcli.input.outcome
+=====================
+
+Defines :class:`Outcome`, the result type returned by every interactive prompt.
+
+A prompt never signals its result with an exception or ``None``: it returns an
+:class:`Outcome` that is either a submitted value, a cancellation, or a fired
+shortcut. The kind is carried by :class:`OutcomeKind`; the submitted value is
+reached through :attr:`Outcome.value` (guarded) and the fired shortcut through
+:attr:`Outcome.shortcut_id`. ``__match_args__`` exposes the kind for structural
+pattern matching.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import cast
+
+from sparcli.errors import SparcliError
+
+
+class OutcomeKind(enum.Enum):
+    """The three ways an interactive prompt can end."""
+
+    SUBMITTED = enum.auto()
+    CANCELLED = enum.auto()
+    SHORTCUT = enum.auto()
+
+
+@dataclass(frozen=True, slots=True, match_args=False)
+class Outcome[T]:
+    """
+    The result of running an interactive prompt.
+
+    Attributes
+    ----------
+    kind : OutcomeKind
+        Which of the three terminal states the prompt reached.
+    """
+
+    kind: OutcomeKind
+    _value: object = None
+    _shortcut_id: int | None = None
+
+    __match_args__ = ("kind",)
+
+    @classmethod
+    def submitted[U](cls, value: U) -> Outcome[U]:
+        """Returns a submitted outcome carrying ``value``."""
+        return Outcome[U](OutcomeKind.SUBMITTED, value)
+
+    @classmethod
+    def cancelled[U](cls) -> Outcome[U]:
+        """Returns a cancelled outcome."""
+        return Outcome[U](OutcomeKind.CANCELLED)
+
+    @classmethod
+    def shortcut[U](cls, shortcut_id: int) -> Outcome[U]:
+        """Returns a shortcut outcome carrying the fired action id."""
+        return Outcome[U](OutcomeKind.SHORTCUT, None, shortcut_id)
+
+    @property
+    def is_submitted(self) -> bool:
+        """Returns whether the prompt ended with a submitted value."""
+        return self.kind is OutcomeKind.SUBMITTED
+
+    @property
+    def is_cancelled(self) -> bool:
+        """Returns whether the prompt was cancelled."""
+        return self.kind is OutcomeKind.CANCELLED
+
+    @property
+    def is_shortcut(self) -> bool:
+        """Returns whether the prompt ended on a registered shortcut."""
+        return self.kind is OutcomeKind.SHORTCUT
+
+    @property
+    def value(self) -> T:
+        """
+        Returns the submitted value.
+
+        Returns
+        -------
+        T
+            The value the user submitted.
+
+        Raises
+        ------
+        SparcliError
+            If the outcome is not a submission.
+        """
+        if self.kind is not OutcomeKind.SUBMITTED:
+            raise SparcliError("outcome carries no submitted value")
+        return cast("T", self._value)
+
+    @property
+    def shortcut_id(self) -> int | None:
+        """Returns the fired shortcut id, or ``None`` for other outcomes."""
+        return self._shortcut_id
+
+    def submitted_or(self, default: T) -> T:
+        """Returns the submitted value, or ``default`` for other outcomes."""
+        if self.kind is OutcomeKind.SUBMITTED:
+            return cast("T", self._value)
+        return default