QCodeSitter 0.1.0__py3-none-any.whl

QCodeSitter/queries/predicates.py

@@ -0,0 +1,172 @@
+"""Text predicates for tree-sitter queries
+
+Tree-sitter's built-in text predicates (#eq?, #match?, #any-of?, etc) compare the
+node's source text against the strings in the query. Our trees are parsed as UTF-16,
+so tree-sitter compares UTF-16 bytes against UTF-8 strings, and they never match.
+
+To get around this, `prepare_query_source` renames the text predicates so tree-sitter
+treats them as custom predicates, and `QueryPredicates` evaluates them against the
+node text it is given, which TrackedDocument.node_text reads from the document.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+    from . import Captures, PredicateArgs
+
+
+PREFIX = "qcs-"
+_TEXT_PREDICATE_RE = re.compile(r"#((?:not-)?(?:eq|match|lua-match|any-of))\?")
+
+# Lua pattern character classes (nvim queries use these) as regex set contents
+_LUA_CLASSES = {
+    "a": r"A-Za-z",
+    "c": r"\x00-\x1f\x7f",
+    "d": r"0-9",
+    "l": r"a-z",
+    "p": r"!-/:-@\[-`{-~",
+    "s": r"\s",
+    "u": r"A-Z",
+    "w": r"A-Za-z0-9",
+    "x": r"A-Fa-f0-9",
+}
+
+
+def prepare_query_source(source: str) -> str:
+    """Rename the text predicates in a query so we can evaluate them ourselves"""
+    return _TEXT_PREDICATE_RE.sub(lambda m: f"#{PREFIX}{m.group(1)}?", source)
+
+
+def _lua_class(nxt: str, in_set: bool) -> str:
+    """Convert the character after a % into regex"""
+    cls = _LUA_CLASSES.get(nxt.lower())
+    if cls is None:
+        # %% or %. etc are escaped literals
+        return re.escape(nxt)
+    if not nxt.isupper():
+        return cls if in_set else f"[{cls}]"
+    # Uppercase classes are the complement
+    if in_set:
+        raise re.error(f"%{nxt} is not supported inside a set")
+    return f"[^{cls}]"
+
+
+def lua_to_regex(pattern: str) -> str:
+    """Convert the lua pattern character classes (ie %u, %l) into a python regex
+
+    Only handles the character classes, which is what the nvim queries use.
+    Normal regex syntax passes through unchanged. The complement classes (ie %U)
+    aren't supported inside of a [set]
+    """
+    out = []
+    in_set = False
+    i = 0
+    while i < len(pattern):
+        ch = pattern[i]
+        if ch in "%\\" and i + 1 < len(pattern):
+            pair = pattern[i : i + 2]
+            out.append(_lua_class(pair[1], in_set) if ch == "%" else pair)
+            i += 2
+            continue
+        if ch == "[" and not in_set:
+            in_set = True
+        elif ch == "]" and in_set:
+            in_set = False
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+@functools.lru_cache(maxsize=256)
+def _compile_pattern(pattern: str) -> re.Pattern | None:
+    """Compile a #match? pattern once, or warn once and give None if it's invalid"""
+    try:
+        return re.compile(lua_to_regex(pattern))
+    except re.error as err:
+        warnings.warn(
+            f"Invalid #match? pattern {pattern!r} in a tree-sitter query: {err}",
+            stacklevel=2,
+        )
+        return None
+
+
+class QueryPredicates:
+    """A predicate callback for QueryCursor.captures that evaluates the renamed
+    text predicates using the text from a document
+
+    Args:
+        get_text: A function that returns the source text of a node
+    """
+
+    def __init__(self, get_text: Callable[[Node], str]) -> None:
+        self.get_text = get_text
+
+    def _eq_check(
+        self, rest: PredicateArgs, captures: Captures
+    ) -> Callable[[str], bool] | None:
+        value, kind = rest[0]
+        if kind != "capture":
+            return lambda text: text == value
+        others = captures.get(value, [])
+        if not others:
+            return None
+        other = self.get_text(others[0])
+        return lambda text: text == other
+
+    def _match_check(self, rest: PredicateArgs) -> Callable[[str], bool]:
+        regex = _compile_pattern(rest[0][0])
+        if regex is None:
+            # An invalid pattern can't match anything
+            return lambda _text: False
+        return lambda text: regex.search(text) is not None
+
+    def _make_check(
+        self, name: str, rest: PredicateArgs, captures: Captures
+    ) -> Callable[[str], bool] | None:
+        """Build the text test for a predicate, or None if it can't filter"""
+        if name == "any-of":
+            values = {value for value, _kind in rest}
+            return lambda text: text in values
+        if not rest:
+            return None
+        if name == "eq":
+            return self._eq_check(rest, captures)
+        # The nvim queries use lua classes in #match? too, so treat them the same
+        if name in ("match", "lua-match"):
+            return self._match_check(rest)
+        return None
+
+    def __call__(
+        self,
+        predicate: str,
+        args: PredicateArgs,
+        pattern_index: int,
+        captures: Captures,
+    ) -> bool:
+        # The names match tree-sitter's QueryPredicate protocol
+        name = predicate
+        if not name.startswith(PREFIX):
+            # Not one of ours. Don't filter anything out
+            return True
+        name = name[len(PREFIX) : -1]
+        negate = name.startswith("not-")
+        if negate:
+            name = name[4:]
+
+        if not args or args[0][1] != "capture":
+            return True
+        check = self._make_check(name, args[1:], captures)
+        if check is None:
+            return True
+        return all(
+            check(self.get_text(node)) != negate
+            for node in captures.get(args[0][0], [])
+        )

QCodeSitter/syntax_specs.py

@@ -0,0 +1,65 @@
+"""The "syntax" option: text formats keyed by tree-sitter capture name, and how
+dotted capture names fall back to their parents
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TypedDict, TypeVar
+
+
+class SyntaxSpec(TypedDict, total=False):
+    color: str
+    italic: bool
+    bold: bool
+
+
+# Tree-sitter capture name -> format
+SyntaxSpecs = dict[str, SyntaxSpec]
+
+T = TypeVar("T")
+
+
+def resolve_capture(name: str, specs: Mapping[str, T]) -> T | None:
+    """Look up a treesitter capture name, falling back to its parent groups
+
+    For example "function.method.call" will check "function.method.call", then
+    "function.method", then "function". This mirrors how nvim resolves highlight groups
+
+    Args:
+        name: The dotted treesitter capture name
+        specs: A dictionary keyed by capture names
+
+    Returns:
+        The value of the most specific matching key, or None if nothing matches
+    """
+    parts = name.split(".")
+    while parts:
+        val = specs.get(".".join(parts))
+        if val is not None:
+            return val
+        parts.pop()
+    return None
+
+
+def overlay_syntax(base: SyntaxSpecs, overrides: SyntaxSpecs) -> SyntaxSpecs:
+    """Overlay syntax specs onto a base set of syntax specs
+
+    Overrides are resolved hierarchically, so an override for "keyword" will replace
+    the base "keyword.return" unless there is also an override for "keyword.return".
+
+    Args:
+        base: A syntax spec dictionary as returned by read_theme
+        overrides: A partial syntax spec dictionary
+
+    Returns:
+        A new syntax spec dictionary
+    """
+    names = set(base) | set(overrides)
+    out: SyntaxSpecs = {}
+    for name in names:
+        spec = resolve_capture(name, overrides)
+        if spec is None:
+            spec = base[name]
+        out[name] = spec.copy()
+    return out

QCodeSitter/themes.py

@@ -0,0 +1,271 @@
+"""Built-in color themes, and helpers to turn a theme into editor options
+
+A theme has an optional "palette" of named colors, "gui" colors for the editor
+and its behaviors (see gui_colors.py), and "syntax" specs keyed by tree-sitter
+capture name (see syntax_specs.py for their format). Gui and syntax colors can
+be hex colors or palette names.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping
+from typing import TypedDict
+
+from Qt import QtGui
+
+from .gui_colors import GuiColors
+from .syntax_specs import SyntaxSpecs
+
+
+class _RequiredThemeSections(TypedDict):
+    gui: dict[str, str]
+    syntax: SyntaxSpecs
+
+
+class Theme(_RequiredThemeSections, total=False):
+    palette: dict[str, str]
+
+
+# fmt: off
+
+# This colorscheme is pulled from the nvim Dracula theme
+# https://github.com/Mofiqul/dracula.nvim
+DARK_THEME: Theme = {
+    "palette": {
+        "red":             "#FF5555",
+        "orange":          "#FFB86C",
+        "yellow":          "#F1FA8C",
+        "green":           "#50fa7b",
+        "purple":          "#BD93F9",
+        "cyan":            "#8BE9FD",
+        "pink":            "#FF79C6",
+        "bright_red":      "#FF6E6E",
+        "bright_green":    "#69FF94",
+        "bright_yellow":   "#FFFFA5",
+        "bright_blue":     "#D6ACFF",
+        "bright_magenta":  "#FF92DF",
+        "bright_cyan":     "#A4FFFF",
+        "bright_white":    "#FFFFFF",
+        "white":           "#ABB2BF",
+        "half_mid_gray":   "#B4B4B4",
+        "mid_gray":        "#C8C8C8",
+        "gray":            "#787878",
+        "dark_gray":       "#101010",
+        "black":           "#191A21",
+        "cream":           "#F8F8F2",
+        "xlight_slate":    "#8E9CBC",
+        "light_slate":     "#6272A4",
+        "mid_light_slate": "#4C4C5C",
+        "slate":           "#3E4452",
+        "slate2":          "#3C3C4C",
+        "mid_dark_slate":  "#282A36",
+        "dark_slate":      "#21222C",
+    },
+
+    "gui" : {
+        "bg":                  "mid_dark_slate",
+        "bg_dim":              "slate2",
+        "fg":                  "cream",
+        "fg_dim":              "mid_gray",
+        "gutter":              "dark_gray",
+        "gutter_fg":           "xlight_slate",
+        "hl_dim":              "mid_light_slate",
+        "manual_fold":         "orange",
+        "match_hl":            "bright_yellow",
+        "menu":                "dark_slate",
+        "outside_bg":          "dark_slate",
+        "pair_hl":             "mid_gray",
+        "primary_cursor":      "bright_white",
+        "secondary_cursor":    "half_mid_gray",
+        "selection":           "mid_light_slate",
+        "secondary_selection": "half_mid_gray",
+    },
+
+    "syntax" : {
+        "attribute":             {"color": "cyan"},
+        "attribute.builtin":     {"color": "cyan"},
+        "boolean":               {"color": "purple"},
+        "character.special":     {"color": "green"},
+        "comment":               {"color": "light_slate"},
+        "constructor":           {"color": "cyan"},
+        "function":              {"color": "green"},
+        "function.builtin":      {"color": "cyan"},
+        "function.call":         {"color": "green"},
+        "function.macro":        {"color": "green"},
+        "function.method":       {"color": "green"},
+        "function.method.call":  {"color": "green"},
+        "keyword":               {"color": "pink"},
+        "keyword.conditional":   {"color": "pink"},
+        "keyword.coroutine":     {"color": "pink"},
+        "keyword.directive":     {"color": "pink"},
+        "keyword.exception":     {"color": "purple"},
+        "keyword.function":      {"color": "cyan"},
+        "keyword.import":        {"color": "pink"},
+        "keyword.operator":      {"color": "pink"},
+        "keyword.repeat":        {"color": "pink"},
+        "keyword.return":        {"color": "pink"},
+        "keyword.type":          {"color": "pink"},
+        "module":                {"color": "orange"},
+        "module.builtin":        {"color": "orange"},
+        "none":                  {"color": "purple"},
+        "number":                {"color": "purple"},
+        "number.float":          {"color": "green"},
+        "operator":              {"color": "pink"},
+        "punctuation.bracket":   {"color": "cream"},
+        "punctuation.delimiter": {"color": "cream"},
+        "string":                {"color": "yellow"},
+        "string.documentation":  {"color": "cyan"},
+        "string.escape":         {"color": "cyan"},
+        "string.regexp":         {"color": "red"},
+        "type":                  {"color": "bright_cyan"},
+        "type.builtin":          {"color": "cyan", "italic": True},
+        "type.definition":       {"color": "bright_cyan"},
+        "variable":              {"color": "cream"},
+        "variable.builtin":      {"color": "purple"},
+        "variable.member":       {"color": "orange"},
+        "variable.parameter":    {"color": "orange"},
+        "constant":              {"color": "purple"},
+        "constant.builtin":      {"color": "purple"},
+    },
+}
+
+# This colorscheme is pulled from the nvim Edge theme
+# https://github.com/sainnhe/edge
+LIGHT_THEME: Theme = {
+    "palette" : {
+        'true_black':    '#000000',
+        'true_white':    '#FFFFFF',
+        'black':         '#DDE2E7',
+        'bg_dim':        '#E8EBF0',
+        'bg0':           '#FAFAFA',
+        'bg1':           '#EEF1F4',
+        'bg2':           '#E8EBF0',
+        'bg3':           '#E8EBF0',
+        'bg4':           '#DDE2E7',
+        'bg_grey':       '#BCC5CF',
+        'bg_red':        '#F6E4E4',
+        'bg_yellow':     '#F0ECE2',
+        'bg_green':      '#E5EEE4',
+        'bg_blue':       '#E3EAF6',
+        'bg_purple':     '#F4E9F8',
+        'filled_red':    '#E17373',
+        'filled_green':  '#76AF6F',
+        'filled_blue':   '#6996E0',
+        'filled_purple': '#BF75D6',
+        'fg':            '#4B505B',
+        'red':           '#D05858',
+        'yellow':        '#BE7E05',
+        'green':         '#608E32',
+        'cyan':          '#3A8B84',
+        'blue':          '#5079BE',
+        'purple':        '#B05CCC',
+        'grey':          '#8790A0',
+        'grey_dim':      '#BAC3CB',
+    },
+
+    "gui" : {
+        "bg":                  "true_white",
+        "bg_dim":              "bg_dim",
+        "fg":                  "fg",
+        "fg_dim":              "grey",
+        "gutter":              "bg2",
+        "gutter_fg":           "fg",
+        "hl_dim":              "filled_blue",
+        "manual_fold":         "yellow",
+        "match_hl":            "filled_green",
+        "menu":                "bg4",
+        "outside_bg":          "bg_grey",
+        "pair_hl":             "bg_yellow",
+        "primary_cursor":      "true_black",
+        "secondary_cursor":    "true_black",
+        "selection":           "filled_blue",
+        "secondary_selection": "blue",
+    },
+
+    "syntax" : {
+        "attribute":             {"color": "yellow"},
+        "attribute.builtin":     {"color": "blue"},
+        "boolean":               {"color": "green"},
+        "character.special":     {"color": "yellow"},
+        "comment":               {"color": "grey"},
+        "constructor":           {"color": "blue"},
+        "function":              {"color": "blue"},
+        "function.builtin":      {"color": "blue"},
+        "function.call":         {"color": "blue"},
+        "function.macro":        {"color": "blue"},
+        "function.method":       {"color": "blue"},
+        "function.method.call":  {"color": "blue"},
+        "keyword":               {"color": "purple"},
+        "keyword.conditional":   {"color": "purple"},
+        "keyword.coroutine":     {"color": "purple"},
+        "keyword.directive":     {"color": "purple"},
+        "keyword.exception":     {"color": "purple"},
+        "keyword.function":      {"color": "purple"},
+        "keyword.import":        {"color": "purple"},
+        "keyword.operator":      {"color": "purple"},
+        "keyword.repeat":        {"color": "purple"},
+        "keyword.return":        {"color": "purple"},
+        "keyword.type":          {"color": "yellow"},
+        "module":                {"color": "yellow"},
+        "module.builtin":        {"color": "yellow"},
+        "none":                  {"color": "fg"},
+        "number":                {"color": "green"},
+        "number.float":          {"color": "green"},
+        "operator":              {"color": "purple"},
+        "punctuation.bracket":   {"color": "grey"},
+        "punctuation.delimiter": {"color": "grey"},
+        "string":                {"color": "green"},
+        "string.documentation":  {"color": "green"},
+        "string.escape":         {"color": "yellow"},
+        "string.regexp":         {"color": "yellow"},
+        "type":                  {"color": "yellow"},
+        "type.builtin":          {"color": "yellow"},
+        "type.definition":       {"color": "yellow"},
+        "variable":              {"color": "red", "italic": True},
+        "variable.builtin":      {"color": "cyan", "italic": True},
+        "variable.member":       {"color": "cyan"},
+        "variable.parameter":    {"color": "red", "italic": True},
+        "constant":              {"color": "red", "italic": True},
+        "constant.builtin":      {"color": "red", "italic": True},
+    },
+}
+# fmt: on
+
+
+def read_theme(theme: Theme) -> tuple[GuiColors, SyntaxSpecs]:
+    """Resolve a theme's palette names into gui colors and syntax specs
+
+    See the module docstring for the theme format.
+
+    Returns:
+        The gui colors, which also include the palette's names unless a gui
+        color has the same name, and the syntax specs
+    """
+    pal = theme.get("palette", {})
+
+    gui = {
+        **pal,
+        **{k: _resolve_color(f"gui {k!r}", v, pal) for k, v in theme["gui"].items()},
+    }
+
+    newsyn: SyntaxSpecs = {}
+    for k, vdata_orig in theme["syntax"].items():
+        vdata = vdata_orig.copy()
+        if "color" in vdata:
+            vdata["color"] = _resolve_color(f"syntax {k!r}", vdata["color"], gui)
+        newsyn[k] = vdata
+
+    return gui, newsyn
+
+
+def _resolve_color(where: str, value: str, names: Mapping[str, str]) -> str:
+    """Look up a color name, warning if it's neither a known name nor a color"""
+    if value in names:
+        return names[value]
+    if not QtGui.QColor(value).isValid():
+        warnings.warn(
+            f"Theme {where} color {value!r} is not a palette name or a color",
+            stacklevel=3,
+        )
+    return value

QCodeSitter/tracked_document.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from Qt import QtCore, QtGui, QtWidgets
+from tree_sitter import Point
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+# Qt positions count UTF-16 code units, and tree-sitter parses the document as
+# UTF-16LE bytes. Python strings count code points, so they differ for
+# characters outside the BMP, which take two code units
+ENC = "utf-16-le"
+
+
+def len16(val: str) -> int:
+    """Get the number of UTF-16 code units, where surrogate pairs count as 2"""
+    return len(val.encode(ENC)) // 2
+
+
+def utf16_to_index(text: str, col: int) -> int:
+    """Convert a UTF-16 column in text (ie: positionInBlock) to a str index
+
+    A column inside a surrogate pair rounds down to the start of the pair
+    """
+    return len(text.encode(ENC)[: col * 2].decode(ENC, errors="ignore"))
+
+
+class TrackedDocument(QtGui.QTextDocument):
+    """A QTextDocument that reports its edits in the form tree-sitter expects
+
+    Qt positions are UTF-16 code units. Tree-sitter parses the document as
+    UTF-16LE, so its offsets and Point columns are in bytes, which is always
+    2 bytes per code unit. Every edit made through a TrackedCursor emits
+    `byteContentsChange` with those byte offsets.
+    """
+
+    byteContentsChange: QtCore.Signal[tuple[int, int, int, Point, Point, Point]] = (
+        QtCore.Signal(int, int, int, Point, Point, Point)
+    )
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.setDocumentLayout(QtWidgets.QPlainTextDocumentLayout(self))
+
+    @staticmethod
+    def byte_to_char(byte_offset: int) -> int:
+        """Convert a UTF-16LE byte offset from tree-sitter to a Qt position"""
+        return byte_offset // 2
+
+    @staticmethod
+    def char_to_byte(position: int) -> int:
+        """Convert a Qt position to a UTF-16LE byte offset for tree-sitter"""
+        return position * 2
+
+    def row_col_to_char(self, row: int, col: int) -> int:
+        """Get the Qt position of a block row and a column in UTF-16 code units"""
+        return self.findBlockByNumber(row).position() + col
+
+    def node_text(self, node: Node) -> str:
+        """Get the current text of a tree-sitter node of this document"""
+        start, end = node.start_point, node.end_point
+        lines = []
+        block = self.findBlockByNumber(start.row)
+        for row in range(start.row, end.row + 1):
+            if not block.isValid():
+                break
+            data = block.text().encode(ENC)
+            first = start.column if row == start.row else 0
+            last = end.column if row == end.row else len(data)
+            lines.append(data[first:last].decode(ENC, errors="replace"))
+            block = block.next()
+        return "\n".join(lines)
+
+    def report_edit(self, position: int, removed: str, added: str) -> None:
+        """Emit `byteContentsChange` for an edit at a Qt position
+
+        The signal carries the start, old end and new end as UTF-16LE byte
+        offsets, then the same three as Points with byte columns.
+        """
+        start_block = self.findBlock(position)
+        start_line = start_block.blockNumber()
+        start_col = self.char_to_byte(position - start_block.position())
+        start_byte = self.char_to_byte(position)
+
+        def end_point(text: str) -> tuple[int, Point]:
+            """Get the end byte and end point of text inserted at position"""
+            # QTextCursor.selectedText uses the paragraph separator for newlines
+            text = text.replace("
", "\n")
+            lines = text.count("\n")
+            if lines == 0:
+                col = start_col + len(text.encode(ENC))
+            else:
+                col = len(text[text.rfind("\n") + 1 :].encode(ENC))
+            return start_byte + len(text.encode(ENC)), Point(start_line + lines, col)
+
+        old_end_byte, old_end_point = end_point(removed)
+        new_end_byte, new_end_point = end_point(added)
+        self.byteContentsChange.emit(
+            start_byte,
+            old_end_byte,
+            new_end_byte,
+            Point(start_line, start_col),
+            old_end_point,
+            new_end_point,
+        )