side-vim 0.1.0__py3-none-any.whl

side_vim/scroll.py

@@ -0,0 +1,98 @@
+"""Ctrl+E, Ctrl+Y, Ctrl+D, Ctrl+U, Ctrl+F and Ctrl+B, worked out on line numbers, like
+vim 9.1 with its defaults ('scrolloff' 0, 'startofline' on). No Qt here.
+
+The screen is the lines from `top`, `height` of them. vim can scroll until only the
+last line is left on the screen. An editor can stop earlier, with the last line at its
+bottom: `max_top` is the highest top it allows. The cursor still goes to vim's line.
+"""
+
+from dataclasses import dataclass
+
+SCROLL_KEYS = frozenset({"<C-e>", "<C-y>", "<C-d>", "<C-u>", "<C-f>", "<C-b>"})
+
+
+@dataclass(frozen=True)
+class Scrolled:
+    top: int  # the new first line on the screen
+    line: int  # the cursor's new line
+    keep_column: bool  # True: the column j and k aim for; False: the first non-blank
+    amount: int | None  # what Ctrl+D and Ctrl+U scroll from now on (vim's 'scroll')
+
+
+def scroll(
+    key: str,
+    count: int | None,
+    *,
+    top: int,
+    line: int,
+    height: int,
+    lines: int,
+    max_top: int,
+    amount: int | None = None,
+) -> Scrolled | None:
+    """One scrolling command. None where vim beeps and does nothing.
+
+    top, line: the first line on the screen and the cursor's line. height: how many
+    lines fit on the screen. lines: how many lines the text has. amount: what Ctrl+D and
+    Ctrl+U scroll, if a count set it before; half the screen otherwise.
+    """
+    last = lines - 1
+    height = max(height, 1)
+    n = count or 1
+    if key in ("<C-d>", "<C-u>"):
+        if count:
+            amount = min(count, height)
+        step = amount or max(height // 2, 1)
+        if key == "<C-d>":
+            if line >= last:
+                return None
+            # unlike Ctrl+E and Ctrl+F, it stops with the last line at the bottom
+            new_top = max(min(top + step, max_top, lines - height), top)
+            return Scrolled(new_top, min(line + step, last), False, amount)
+        if line <= 0:
+            return None
+        return Scrolled(max(top - step, 0), max(line - step, 0), False, amount)
+
+    if key == "<C-e>":
+        if top >= max_top:
+            return None
+        new_top = min(top + n, max_top)
+        return Scrolled(new_top, max(line, new_top), True, amount)
+    if key == "<C-y>":
+        if top <= 0:
+            return None
+        new_top = max(top - n, 0)
+        return Scrolled(new_top, min(line, new_top + height - 1), True, amount)
+
+    # When a count asks for more pages than there are, vim beeps on the last one and
+    # leaves the column alone.
+    page = max(height - 2, 1)  # two lines stay on the screen
+    beeped = False
+    if key == "<C-f>":
+        new_top = top
+        for _ in range(n):
+            if new_top + height - 1 >= last:  # the end is on the screen
+                if new_top >= last:
+                    beeped = True
+                    break
+                new_top = last
+            else:
+                new_top += page
+        if new_top == top and top >= last:
+            return None
+        return Scrolled(min(new_top, max_top), min(new_top, last), beeped, amount)
+    if key == "<C-b>":
+        if top <= 0:
+            return None
+        new_top = before = top
+        for _ in range(n):
+            if new_top <= 0:
+                beeped = True
+                break
+            before = new_top
+            new_top -= page
+            if new_top < 2:  # vim goes all the way up from one line short of the start
+                new_top = 0
+        line = min(before + 1, new_top + height - 1, last)
+        return Scrolled(new_top, line, beeped, amount)
+    raise ValueError(f"not a scrolling key: {key!r}")

side_vim/search.py

@@ -0,0 +1,118 @@
+"""n and N: find the next match of a plain text, like vim. No Qt here.
+
+The text and the pattern are lines of characters (grapheme clusters), as in motions.py,
+so "e" doesn't match the "e" in "e" plus an accent, just as in vim. A newline in the
+pattern matches a line break. vim treats every line as ending in one, the last line
+too, and so does this.
+
+vim's defaults decide which match comes next: 'wrapscan', so the search goes on from
+the other end, and 'cpoptions' with "c", so the matches in a line are found one after
+the other from its start, each one after the end of the one before. In "aaaa", `n` for
+"aa" goes from column 0 to column 2, not 1.
+"""
+
+from bisect import bisect_right
+from collections.abc import Iterator, Sequence
+
+from side_vim.motions import Line, Pos
+
+NEWLINE = "\n"
+
+
+class _Text:
+    """The lines as one list of characters, with a NEWLINE after each line."""
+
+    def __init__(self, lines: Sequence[Line]) -> None:
+        self.lines: Sequence[Line] = lines
+        self.chars: list[str] = []
+        self.starts: list[int] = []
+        for line in lines:
+            self.starts.append(len(self.chars))
+            self.chars.extend(line)
+            self.chars.append(NEWLINE)
+
+    def index(self, pos: Pos) -> int:
+        return self.starts[pos.line] + pos.col
+
+    def line_of(self, index: int) -> int:
+        return bisect_right(self.starts, index) - 1
+
+    def matches(self, line: int, pattern: list[str]) -> Iterator[tuple[int, bool]]:
+        """The matches that start in a line, one after the other from its start: the
+        index of each, and whether it goes on past the line's end."""
+        end = self.starts[line] + len(self.lines[line])  # the line's NEWLINE
+        i = self.starts[line]
+        size = len(pattern)
+        while i <= end:
+            if self.chars[i : i + size] == pattern:
+                more = i + size > end
+                yield i, more
+                if more:
+                    return
+                i += size
+            else:
+                i += 1
+
+
+def search(
+    lines: Sequence[Line],
+    pos: Pos,
+    pattern: Sequence[Line],
+    forward: bool = True,
+    count: int | None = None,
+) -> Pos | None:
+    """Where `n` (forward) or `N` goes from pos for a pattern given as lines of
+    characters. None if the pattern is empty or not in the text."""
+    chars = [ch for i, part in enumerate(pattern) for ch in ([NEWLINE] if i else []) + list(part)]
+    if not chars:
+        return None
+    text = _Text(lines)
+    at = text.index(pos)
+    for _ in range(count or 1):
+        found = _forward(text, at, chars) if forward else _backward(text, at, chars)
+        if found is None:
+            return None
+        at = found
+    line = text.line_of(at)
+    col = at - text.starts[line]
+    # a match that starts on the line break puts the cursor on the last character
+    if col == len(lines[line]) and col > 0:
+        col -= 1
+    return Pos(line, col)
+
+
+def _forward(text: _Text, at: int, pattern: list[str]) -> int | None:
+    line = text.line_of(at)
+    end = text.starts[line] + len(text.lines[line])
+    for i, more in text.matches(line, pattern):
+        # on the line break, a match counts as on the character before it
+        if i - (i == end) > at:
+            return i
+        if more:
+            break
+    count = len(text.lines)
+    for step in range(1, count + 1):
+        first = next(text.matches((line + step) % count, pattern), None)
+        if first is not None:
+            return first[0]
+    return None
+
+
+def _backward(text: _Text, at: int, pattern: list[str]) -> int | None:
+    line = text.line_of(at)
+    found = None
+    if at > text.starts[line]:
+        for i, _ in text.matches(line, pattern):
+            if i >= at:
+                break
+            found = i
+    if found is not None:
+        return found
+    count = len(text.lines)
+    for step in range(1, count + 1):
+        last = None
+        for i, _ in text.matches((line - step) % count, pattern):
+            last = i
+        if last is not None:
+            return last
+    return None

side_vim/text.py

@@ -0,0 +1,146 @@
+"""The editor's text as vim lines, and positions in Qt's terms.
+
+Uses QtCore only, never the editor. Two things make this more than str.split("\\n"):
+
+- Qt counts positions in UTF-16 code units, so an emoji is 2 positions and a family
+  emoji is 8, while Python counts code points. Every position goes through here.
+- One character on screen (a grapheme cluster: a family emoji, a flag, a letter plus
+  an accent) is one character for vim, so commands never cut one in half. Qt decides
+  where clusters end, the same way its own cursor does.
+
+Read the editor's text with document().toRawText(), not toPlainText(): toPlainText()
+turns a line separator (U+2028, a soft line break inside a block) into "\\n", so its
+lines no longer match Qt's blocks.
+"""
+
+from collections.abc import Iterator, Sequence
+from typing import overload
+
+from PySide6.QtCore import QTextBoundaryFinder
+
+from side_vim.motions import Pos
+
+# What separates blocks (vim's lines) in QTextDocument.toRawText().
+PARAGRAPH_SEPARATOR = "
"
+
+
+def utf16_len(s: str) -> int:
+    """Length in UTF-16 code units, the way Qt counts."""
+    return len(s.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def split_clusters(line: str) -> tuple[str, ...]:
+    """Split a line into the characters the user sees, as Qt finds them."""
+    if not line:
+        return ()
+    finder = QTextBoundaryFinder(QTextBoundaryFinder.BoundaryType.Grapheme, line)
+    # the finder speaks UTF-16; map its boundaries back to code point indexes
+    ends: set[int] = set()
+    while (boundary := finder.toNextBoundary()) != -1:
+        ends.add(boundary)
+    clusters: list[str] = []
+    start = offset = 0
+    for i, ch in enumerate(line):
+        offset += 2 if ord(ch) > 0xFFFF else 1
+        if offset in ends:
+            clusters.append(line[start : i + 1])
+            start = i + 1
+    if start < len(line):
+        clusters.append(line[start:])
+    return tuple(_pair_flags(clusters))
+
+
+def _is_flag_half(cluster: str) -> bool:
+    return all(0x1F1E6 <= ord(ch) <= 0x1F1FF for ch in cluster)
+
+
+def _pair_flags(clusters: list[str]) -> list[str]:
+    """Pair regional indicators (the two halves of a flag) from the start of each run.
+
+    Qt 6.12 gets this wrong after an emoji: it splits "😀🇺🇦" into 😀, 🇺, 🇦, and its
+    own cursor does the same, so a plain QPlainTextEdit can break a flag. Unicode
+    pairs them from the start of the run, so vim commands always take a flag whole.
+    """
+    out: list[str] = []
+    run: list[str] = []
+    for cluster in [*clusters, ""]:
+        if cluster and _is_flag_half(cluster):
+            run.extend(cluster)
+            continue
+        out.extend("".join(run[i : i + 2]) for i in range(0, len(run), 2))
+        run = []
+        if cluster:
+            out.append(cluster)
+    return out
+
+
+class Lines(Sequence[tuple[str, ...]]):
+    """The document's lines, each split into clusters when first used.
+
+    raw: QTextDocument.toRawText(), with blocks separated by U+2029. Or the lines'
+    texts as a sequence that reads them when asked, so that a long document isn't
+    copied for every key. Such a sequence must not change while this is in use.
+    """
+
+    def __init__(self, raw: str | Sequence[str]) -> None:
+        self._raw: Sequence[str] = raw.split(PARAGRAPH_SEPARATOR) if isinstance(raw, str) else raw
+        self._split: dict[int, tuple[str, ...]] = {}
+
+    def __len__(self) -> int:
+        return len(self._raw)
+
+    @overload
+    def __getitem__(self, index: int) -> tuple[str, ...]: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[tuple[str, ...]]: ...
+    def __getitem__(self, index: int | slice) -> tuple[str, ...] | list[tuple[str, ...]]:
+        if isinstance(index, slice):
+            return [self[i] for i in range(*index.indices(len(self)))]
+        if index < 0:
+            index += len(self)
+        if not 0 <= index < len(self._raw):
+            raise IndexError(index)
+        line = self._split.get(index)
+        if line is None:
+            line = self._split[index] = split_clusters(self._raw[index])
+        return line
+
+    def __iter__(self) -> Iterator[tuple[str, ...]]:
+        return (self[i] for i in range(len(self)))
+
+    def raw(self, index: int) -> str:
+        """A line as plain text."""
+        return self._raw[index]
+
+    def offset(self, pos: Pos) -> int:
+        """A column as a UTF-16 offset in its line. Past the line end means the end."""
+        return utf16_len("".join(self[pos.line][: pos.col]))
+
+    def col_at(self, line: int, offset: int) -> int:
+        """The column at a UTF-16 offset in a line. Inside a cluster (which Qt's own
+        cursor never does, but an app could) means the start of that cluster."""
+        end = col = 0
+        for cluster in self[line]:
+            end += utf16_len(cluster)
+            if end > offset:
+                break
+            col += 1
+        return col
+
+    def to_qt(self, pos: Pos) -> int:
+        """A position as a Qt document position. A column past the line end means the
+        line end. The editor asks the document where lines start instead, which is
+        faster in long texts."""
+        start = sum(utf16_len(line) + 1 for line in self._raw[: pos.line])
+        return start + self.offset(pos)
+
+    def from_qt(self, position: int) -> Pos:
+        """A Qt document position as a position. Past the end of the document means its
+        end."""
+        for index, raw in enumerate(self._raw):
+            length = utf16_len(raw)
+            if position <= length:
+                return Pos(index, self.col_at(index, position))
+            position -= length + 1
+        last = len(self._raw) - 1
+        return Pos(last, len(self[last]))

side_vim/unicode.py

@@ -0,0 +1,31 @@
+"""Character classes and cell widths, as vim sees them. No Qt here.
+
+A "character" here is one character as the user sees it: a grapheme cluster, which may
+be several code points (a family emoji, a flag, a letter plus an accent). Its first
+code point decides its class and width, as in vim, where accents belong to the
+letter before them.
+"""
+
+from bisect import bisect_right
+
+from side_vim._unicode_data import CLASS_STARTS, CLASS_VALUES, WIDTH_STARTS, WIDTH_VALUES
+
+
+def char_class(ch: str, bigword: bool = False) -> int:
+    """Vim's character class: 0 blank, 1 punctuation, 2 word character, 3 emoji, and
+    more for some scripts (Hiragana, CJK ideographs, ...). "" stands for the end of a
+    line, which vim counts as blank. With bigword (W, B, E) every non-blank is 1."""
+    if not ch:
+        return 0
+    cls = CLASS_VALUES[bisect_right(CLASS_STARTS, ord(ch[0])) - 1]
+    if bigword and cls:
+        return 1
+    return cls
+
+
+def cell_width(ch: str) -> int:
+    """How many screen cells vim gives a character: 2 for CJK and emoji, 1 for most.
+    A tab's width depends on where it sits, so the caller handles tabs."""
+    if not ch:
+        return 0
+    return WIDTH_VALUES[bisect_right(WIDTH_STARTS, ord(ch[0])) - 1]