py-sparcli 0.3.0__py3-none-any.whl

sparcli/core/markup.py

@@ -0,0 +1,215 @@
+"""
+sparcli.core.markup
+==================
+
+Parses lightweight inline markup such as ``[bold red]text[/]`` into rich text.
+
+Space-separated specs inside brackets combine attributes and colors; ``on
+<color>`` sets a background; ``[/]`` closes the most recent tag; a backtick
+span like ```code``` gets a cyan code style; and a backslash escapes the next
+character. The parser never fails: a bracket that names no known style or
+attribute (such as ``array[0]``) and any malformed bracket are emitted
+literally.
+"""
+
+from __future__ import annotations
+
+from sparcli.core.color import Color
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Attribute, Style
+from sparcli.core.text import Line, Span, Text
+
+_BACKGROUND_KEYWORD = "on"
+
+_ATTRIBUTE_TOKENS: dict[str, Attribute] = {
+    "bold": Attribute.BOLD,
+    "b": Attribute.BOLD,
+    "dim": Attribute.DIM,
+    "d": Attribute.DIM,
+    "italic": Attribute.ITALIC,
+    "i": Attribute.ITALIC,
+    "underline": Attribute.UNDERLINED,
+    "underlined": Attribute.UNDERLINED,
+    "u": Attribute.UNDERLINED,
+    "strike": Attribute.STRIKETHROUGH,
+    "strikethrough": Attribute.STRIKETHROUGH,
+    "s": Attribute.STRIKETHROUGH,
+}
+
+
+def parse(markup: str) -> Text:
+    """
+    Parses markup into a :class:`~sparcli.core.text.Text`.
+
+    Parameters
+    ----------
+    markup : str
+        The markup string.
+
+    Returns
+    -------
+    Text
+        The parsed rich text.
+
+    Examples
+    --------
+    >>> text = parse("[bold]hi[/]")
+    >>> text.lines[0].plain()
+    'hi'
+    """
+    return _Parser(markup).run()
+
+
+def markup_print(markup: str) -> None:
+    """Parses ``markup`` and prints it to stdout."""
+    _AsRenderable(parse(markup)).print()
+
+
+def markup_println(markup: str) -> None:
+    """Parses ``markup``, appends a blank line and prints it to stdout."""
+    text = parse(markup)
+    text.push_line(Line())
+    _AsRenderable(text).print()
+
+
+class _AsRenderable(Renderable):
+    """Adapts a parsed :class:`Text` to the :class:`Renderable` interface."""
+
+    __slots__ = ("_text",)
+
+    def __init__(self, text: Text) -> None:
+        self._text = text
+
+    def render(self, max_width: int) -> Rendered:
+        """Returns the text's lines as a rendered block."""
+        return Rendered.from_text(self._text)
+
+
+class _Parser:
+    """A small state machine turning markup into styled lines."""
+
+    __slots__ = ("_chars", "_stack", "_lines", "_spans", "_buffer", "_in_code")
+
+    def __init__(self, markup: str) -> None:
+        self._chars = markup
+        self._stack: list[Style] = [Style.new()]
+        self._lines: list[Line] = []
+        self._spans: list[Span] = []
+        self._buffer: list[str] = []
+        self._in_code = False
+
+    def run(self) -> Text:
+        """Parses the input and returns the resulting text."""
+        index = 0
+        length = len(self._chars)
+        while index < length:
+            char = self._chars[index]
+            if char == "\\":
+                index = self._consume_escape(index)
+            elif char == "[":
+                index = self._consume_tag(index)
+            elif char == "`":
+                self._toggle_code()
+                index += 1
+            elif char == "\n":
+                self._break_line()
+                index += 1
+            else:
+                self._buffer.append(char)
+                index += 1
+        self._break_line()
+        return Text(self._lines)
+
+    def _consume_escape(self, index: int) -> int:
+        """Appends the escaped character literally and returns the next index."""
+        if index + 1 < len(self._chars):
+            self._buffer.append(self._chars[index + 1])
+            return index + 2
+        self._buffer.append("\\")
+        return index + 1
+
+    def _consume_tag(self, index: int) -> int:
+        """Handles a ``[...]`` tag or emits an unrecognized bracket literally."""
+        end = self._chars.find("]", index)
+        if end == -1:
+            self._buffer.append("[")
+            return index + 1
+        tag = self._chars[index + 1 : end]
+        if tag.strip() == "/":
+            self._flush_buffer()
+            if len(self._stack) > 1:
+                self._stack.pop()
+            return end + 1
+        specs = _parse_specs(tag)
+        if specs == Style.new():
+            # A closed bracket that names no known style or attribute (e.g.
+            # "array[0]") is content, not markup, so emit it literally.
+            self._buffer.append(self._chars[index : end + 1])
+            return end + 1
+        self._flush_buffer()
+        self._stack.append(self._current().patch(specs))
+        return end + 1
+
+    def _toggle_code(self) -> None:
+        """Toggles a cyan code style on or off at the current nesting."""
+        self._flush_buffer()
+        if self._in_code:
+            if len(self._stack) > 1:
+                self._stack.pop()
+        else:
+            code = self._current().patch(Style.new().with_fg(Color.CYAN))
+            self._stack.append(code)
+        self._in_code = not self._in_code
+
+    def _break_line(self) -> None:
+        """Flushes the buffer and starts a new line."""
+        self._flush_buffer()
+        self._lines.append(Line(self._spans))
+        self._spans = []
+
+    def _flush_buffer(self) -> None:
+        """Emits the buffered text as a span with the current style."""
+        if not self._buffer:
+            return
+        content = "".join(self._buffer)
+        self._spans.append(Span(content=content, style=self._current()))
+        self._buffer = []
+
+    def _current(self) -> Style:
+        """Returns the style on top of the stack."""
+        return self._stack[-1]
+
+
+def _parse_specs(tag: str) -> Style:
+    """Parses a tag's space-separated specs into a style."""
+    style = Style.new()
+    expect_background = False
+    for token in tag.split():
+        lowered = token.lower()
+        if lowered == _BACKGROUND_KEYWORD:
+            expect_background = True
+            continue
+        if expect_background:
+            color = _parse_color(token)
+            if color is not None:
+                style = style.with_bg(color)
+            expect_background = False
+            continue
+        style = _apply_token(style, lowered, token)
+    return style
+
+
+def _apply_token(style: Style, lowered: str, token: str) -> Style:
+    """Applies a single foreground or attribute token to ``style``."""
+    attribute = _ATTRIBUTE_TOKENS.get(lowered)
+    if attribute is not None:
+        return style.add_modifier(attribute)
+    color = _parse_color(token)
+    return style.with_fg(color) if color is not None else style
+
+
+def _parse_color(token: str) -> Color | None:
+    """Parses a hex or named color token, returning ``None`` if unknown."""
+    if token.startswith("#"):
+        return Color.from_hex(token)
+    return Color.from_name(token)

sparcli/core/render.py

@@ -0,0 +1,245 @@
+"""
+sparcli.core.render
+===================
+
+Defines the render model: :class:`Rendered`, :class:`Renderable` and the ANSI
+writer.
+
+Every widget lays itself out into a :class:`Rendered` (a list of styled lines
+of known width) before anything reaches the terminal. Colors and attributes are
+turned into escape codes only here, in :func:`write_rendered`, downgraded to the
+detected :class:`~sparcli.core.terminal.ColorSupport`. Plain, unstyled text is
+written without a single escape, which keeps piped and ``NO_COLOR`` output
+clean.
+"""
+
+from __future__ import annotations
+
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from sparcli.core.color import ResolvedColor
+from sparcli.core.style import Attribute, Style
+from sparcli.core.terminal import ColorSupport, color_support, term_width
+from sparcli.core.text import IntoLine, Line, Span, Text, into_line
+
+_ESC = "\x1b"
+_RESET = f"{_ESC}[0m"
+_OSC8_START = f"{_ESC}]8;;"
+_OSC8_END = f"{_ESC}\\"
+
+# Control characters (C0, DEL and C1) minus tab. Emitting these verbatim lets
+# untrusted content inject escape sequences or corrupt the layout, so they are
+# stripped just before text reaches the terminal.
+_CONTROL_TABLE: dict[int, None] = {
+    code: None
+    for code in (*range(0x00, 0x20), 0x7F, *range(0x80, 0xA0))
+    if code != 0x09
+}
+
+# SGR parameter for each attribute flag.
+_ATTRIBUTE_SGR: list[tuple[Attribute, str]] = [
+    (Attribute.BOLD, "1"),
+    (Attribute.DIM, "2"),
+    (Attribute.ITALIC, "3"),
+    (Attribute.UNDERLINED, "4"),
+    (Attribute.STRIKETHROUGH, "9"),
+]
+
+
+@runtime_checkable
+class SupportsWrite(Protocol):
+    """A minimal text sink: anything with a ``write(str)`` method."""
+
+    def write(self, data: str, /) -> int | None:
+        """Writes ``data`` to the sink."""
+        ...
+
+
+class Renderable(ABC):
+    """
+    The interface every printable widget implements.
+
+    Subclasses provide :meth:`render`; :meth:`print` and :meth:`print_to` are
+    derived from it.
+    """
+
+    __slots__ = ()
+
+    @abstractmethod
+    def render(self, max_width: int) -> Rendered:
+        """
+        Lays the widget out into at most ``max_width`` columns.
+
+        Parameters
+        ----------
+        max_width : int
+            The maximum width available, in columns.
+
+        Returns
+        -------
+        Rendered
+            The laid-out block of styled lines.
+        """
+        raise NotImplementedError
+
+    def print(self) -> None:
+        """Renders at the terminal width and writes the result to stdout."""
+        rendered = self.render(term_width())
+        write_rendered(sys.stdout, rendered, color_support())
+        sys.stdout.flush()
+
+    def print_to(self, writer: SupportsWrite) -> None:
+        """
+        Renders at the terminal width and writes to ``writer``.
+
+        Parameters
+        ----------
+        writer : SupportsWrite
+            Any object with a ``write(str)`` method (a file, ``io.StringIO``).
+        """
+        rendered = self.render(term_width())
+        write_rendered(writer, rendered, color_support())
+
+
+@dataclass(slots=True)
+class Rendered(Renderable):
+    """
+    A laid-out block of styled lines of known width.
+
+    :class:`Rendered` is both the output of :meth:`Renderable.render` and the
+    composable unit used to stack and place widgets next to each other. It is
+    itself a :class:`Renderable`, so a pre-built block can be printed directly.
+    """
+
+    lines: list[Line] = field(default_factory=list)
+
+    @classmethod
+    def empty(cls) -> Rendered:
+        """Returns an empty rendered block."""
+        return cls([])
+
+    @classmethod
+    def from_text(cls, text: Text) -> Rendered:
+        """Returns a rendered block from a :class:`Text`'s lines."""
+        return cls(list(text.lines))
+
+    def render(self, max_width: int) -> Rendered:
+        """Returns a copy of this block, ignoring ``max_width``."""
+        return Rendered(list(self.lines))
+
+    def push(self, line: IntoLine) -> None:
+        """Appends a line to the block."""
+        self.lines.append(into_line(line))
+
+    def width(self) -> int:
+        """Returns the width of the widest line in columns."""
+        return max((line.width() for line in self.lines), default=0)
+
+    def height(self) -> int:
+        """Returns the number of lines."""
+        return len(self.lines)
+
+    def plain(self) -> str:
+        """Returns the block's text without styling, lines joined by ``\\n``."""
+        return "\n".join(line.plain() for line in self.lines)
+
+
+def write_rendered(
+    writer: SupportsWrite, rendered: Rendered, support: ColorSupport
+) -> None:
+    """
+    Writes a :class:`Rendered` to ``writer`` as ANSI, one line per row.
+
+    Parameters
+    ----------
+    writer : SupportsWrite
+        The text sink to write to.
+    rendered : Rendered
+        The block to write.
+    support : ColorSupport
+        The color depth to emit.
+    """
+    for line in rendered.lines:
+        write_line(writer, line, support)
+        writer.write("\n")
+
+
+def write_line(
+    writer: SupportsWrite, line: Line, support: ColorSupport
+) -> None:
+    """Writes a single styled line to ``writer`` without a trailing newline."""
+    for span in line.spans:
+        writer.write(_render_span(span, support))
+
+
+def _render_span(span: Span, support: ColorSupport) -> str:
+    """Returns the escaped string for a single span at a support level."""
+    content = _sanitize(span.content)
+    if support is ColorSupport.NONE:
+        return content
+    codes = _sgr_codes(span.style, support)
+    content = _wrap_link(content, span.link)
+    if not codes:
+        return content
+    prefix = f"{_ESC}[{';'.join(codes)}m"
+    return f"{prefix}{content}{_RESET}"
+
+
+def _sanitize(text: str) -> str:
+    """Strips control characters (except tab) that would corrupt output."""
+    return text.translate(_CONTROL_TABLE)
+
+
+def _sgr_codes(style: Style, support: ColorSupport) -> list[str]:
+    """Returns the SGR parameters for a style, empty when nothing is styled."""
+    codes: list[str] = []
+    if style.fg is not None:
+        resolved = style.fg.resolve(support)
+        if resolved is not None:
+            codes.append(_color_sgr(resolved, background=False))
+    if style.bg is not None:
+        resolved = style.bg.resolve(support)
+        if resolved is not None:
+            codes.append(_color_sgr(resolved, background=True))
+    for attribute, code in _ATTRIBUTE_SGR:
+        if style.attrs.contains(attribute):
+            codes.append(code)
+    return codes
+
+
+def _color_sgr(resolved: ResolvedColor, *, background: bool) -> str:
+    """Builds the SGR fragment for a resolved color."""
+    lead = "48" if background else "38"
+    match resolved:
+        case ("reset",):
+            return "49" if background else "39"
+        case ("ansi16", index):
+            return _ansi16_sgr(index, background=background)
+        case ("rgb", red, green, blue):
+            return f"{lead};2;{red};{green};{blue}"
+        case ("indexed", palette_index):
+            return f"{lead};5;{palette_index}"
+
+
+def _ansi16_sgr(index: int, *, background: bool) -> str:
+    """Builds the SGR fragment for a 16-color palette index."""
+    if index < 8:
+        base = 40 if background else 30
+        return str(base + index)
+    base = 100 if background else 90
+    return str(base + index - 8)
+
+
+def _wrap_link(content: str, link: str | None) -> str:
+    """Wraps ``content`` in an OSC-8 hyperlink when a link is present.
+
+    The URL is scrubbed of control characters so a crafted link cannot
+    terminate the OSC-8 sequence early and inject its own escapes.
+    """
+    if link is None:
+        return content
+    safe = _sanitize(link)
+    return f"{_OSC8_START}{safe}{_OSC8_END}{content}{_OSC8_START}{_OSC8_END}"

sparcli/core/style.py

@@ -0,0 +1,128 @@
+"""
+sparcli.core.style
+==================
+
+Defines text styling: attributes and the :class:`Style` value type.
+
+A :class:`Style` bundles an optional foreground and background color with a set
+of :class:`Attribute` flags (bold, dim, italic, ...). Styles are immutable;
+builder methods return a new style, and :meth:`Style.patch` layers one style on
+top of another.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, replace
+
+from sparcli.core.color import Color
+
+
+class Attribute(enum.IntFlag):
+    """Bitflags for text attributes; combine with ``|``."""
+
+    NONE = 0
+    BOLD = enum.auto()
+    DIM = enum.auto()
+    ITALIC = enum.auto()
+    UNDERLINED = enum.auto()
+    STRIKETHROUGH = enum.auto()
+
+    def contains(self, other: Attribute) -> bool:
+        """Returns whether every flag in ``other`` is set in ``self``."""
+        return (self & other) == other
+
+    def is_empty(self) -> bool:
+        """Returns whether no attribute flag is set."""
+        return self == Attribute.NONE
+
+
+# ratatui-familiar alias for the attribute flags.
+Modifier = Attribute
+
+
+@dataclass(frozen=True, slots=True)
+class Style:
+    """
+    An immutable text style: foreground, background and attribute flags.
+
+    Attributes
+    ----------
+    fg : Color | None
+        Foreground color, or ``None`` to inherit.
+    bg : Color | None
+        Background color, or ``None`` to inherit.
+    attrs : Attribute
+        The set of active attribute flags.
+    """
+
+    fg: Color | None = None
+    bg: Color | None = None
+    attrs: Attribute = Attribute.NONE
+
+    @classmethod
+    def new(cls) -> Style:
+        """Returns an empty style with no color and no attributes."""
+        return cls()
+
+    def with_fg(self, color: Color) -> Style:
+        """Returns a copy with the foreground color set."""
+        return replace(self, fg=color)
+
+    def with_bg(self, color: Color) -> Style:
+        """Returns a copy with the background color set."""
+        return replace(self, bg=color)
+
+    def add_modifier(self, attr: Attribute) -> Style:
+        """Returns a copy with ``attr`` added to the attribute flags."""
+        return replace(self, attrs=self.attrs | attr)
+
+    def remove_modifier(self, attr: Attribute) -> Style:
+        """Returns a copy with ``attr`` cleared from the attribute flags."""
+        return replace(self, attrs=self.attrs & ~attr)
+
+    def bold(self) -> Style:
+        """Returns a copy with the bold attribute set."""
+        return self.add_modifier(Attribute.BOLD)
+
+    def dim(self) -> Style:
+        """Returns a copy with the dim attribute set."""
+        return self.add_modifier(Attribute.DIM)
+
+    def italic(self) -> Style:
+        """Returns a copy with the italic attribute set."""
+        return self.add_modifier(Attribute.ITALIC)
+
+    def underlined(self) -> Style:
+        """Returns a copy with the underlined attribute set."""
+        return self.add_modifier(Attribute.UNDERLINED)
+
+    def strikethrough(self) -> Style:
+        """Returns a copy with the strikethrough attribute set."""
+        return self.add_modifier(Attribute.STRIKETHROUGH)
+
+    def patch(self, other: Style) -> Style:
+        """
+        Layers ``other`` on top of this style.
+
+        Parameters
+        ----------
+        other : Style
+            The overriding style. Its set colors win; attribute flags from both
+            styles are combined.
+
+        Returns
+        -------
+        Style
+            The merged style.
+        """
+        return Style(
+            fg=other.fg if other.fg is not None else self.fg,
+            bg=other.bg if other.bg is not None else self.bg,
+            attrs=self.attrs | other.attrs,
+        )
+
+    @classmethod
+    def from_color(cls, color: Color) -> Style:
+        """Returns a style whose foreground is ``color``."""
+        return cls(fg=color)