turbovi 0.3.0__tar.gz

turbovi-0.3.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: turbovi
+Version: 0.3.0
+Summary: A vi clone for the terminal: enough vim to edit with, in three thousand lines
+Keywords: terminal,tui,vi,vim,editor,modal
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Dist: turbodesk[syntax]>=0.2
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# TurboVI
+
+A vi clone for the terminal: modes, counts, operators, registers, marks, macros, split windows and `:s`, in about three thousand lines of Python.
+
+```sh
+uv sync
+uv run turbovi somefile.py
+uv run turbovi one.py two.py   # two buffers, :bn between them
+uv run turbovi                 # a scratch buffer
+```
+
+`:q` to leave, `:help` for what is here.
+
+## What a vim user gets
+
+**The grammar**, `["x] [count] operator [count] motion`, over `hjkl w b e W B E 0 ^ $ gg G { } f F t T %`. Operators `d c y > <` with doubling (`dd`, `yy`, `cc`), text objects (`iw aw i( a" i{`), and `x X D C s S r ~ J p P o O`.
+
+**Modes**: normal, insert, visual, visual-line and command.
+
+**Paging** with `<C-f>` `<C-b>` `<C-d>` `<C-u>`, by the window rather than by a fixed number, and `<C-e>` / `<C-y>` to move the view without moving the cursor.
+
+**Search** with `/ ? n N` and match highlighting. **Undo and redo** with `u` and `<C-r>`. **`.`** repeats the last change, recorded as keystrokes the way vi does it, so a change that ends in insert mode replays whole.
+
+**`:s`** with ranges (`%`, `.`, `$`, `1,5`, `.+1`), the `g`, `i` and `n` flags, any non-alphanumeric delimiter, and `&` in the replacement. One `u` undoes the whole substitution.
+
+**Marks**: `ma` puts one down, `` `a `` comes back to the character and `'a` to the first non-blank of that line. Every jump leaves a mark, so `` `` `` returns from a `G` or a search. `:marks` lists them. They are not shifted when the text moves, which is the one place this is smaller than vi.
+
+**Macros**: `qa` records into register `a`, `q` stops, `@a` plays, `3@a` plays three times, `@@` repeats the last. They share storage with the yank registers the way vi's do, so `"ap` pastes a macro as text and `@a` runs a yanked line. A macro that calls itself stops with a message rather than a stack that runs out.
+
+**Several files at once** with `:e :ls :bn :bp :b`, split windows with `:sp` and `:vsp`, and `<C-w>` then `w s v c o` or `h j k l` to move between them. `<C-p>` and `:find` are a fuzzy picker over the project: type a few letters of the path and it opens in the current window.
+
+**The system clipboard** on `"+y` and `"+p`, over OSC 52 and a local helper, so it crosses ssh.
+
+**Syntax colouring** from the file's name. `:set syntax=rust` colours a file with no suffix, `:set nosyntax` stops. A search hit and a selection paint over the colouring, because finding something inside a comment has to be visible.
+
+**A file opens and saves as itself.** The encoding, the line endings and whether the last line had a newline are read once and written back unchanged. A latin-1 file stays latin-1, a CRLF file stays CRLF, and a file with no trailing newline does not gain one.
+
+## Settings and recovery
+
+Settings live in `$XDG_CONFIG_HOME/turbovi/config`, a file of ex commands the way a `vimrc` is:
+
+```
+set nu
+set rnu
+sp
+```
+
+A modified buffer is copied to `$XDG_DATA_HOME/turbovi/recover/` every few seconds, keyed by a hash of its absolute path, and `:recover` puts it back after a crash without writing anything to disk. The recovery copy is dropped when the buffer is saved.
+
+## What it is not
+
+Not a vim: no plugins, no scripting language, no `:g`, no folds, no tabs, no persistent undo across sessions yet.
+
+## Built on turbodesk
+
+[turbodesk](https://turbodesk.lab.abilian.com) is the immediate-mode terminal UI library underneath. This editor is the application on it that uses **no widgets at all** — views, events and hooks, nothing else — which is what proved the core carries a real application on its own. It lived in that repository as `examples/vi/` until 2026-08-26; a smaller showcase version stays there.

turbovi-0.3.0/README.md

@@ -0,0 +1,56 @@
+# TurboVI
+
+A vi clone for the terminal: modes, counts, operators, registers, marks, macros, split windows and `:s`, in about three thousand lines of Python.
+
+```sh
+uv sync
+uv run turbovi somefile.py
+uv run turbovi one.py two.py   # two buffers, :bn between them
+uv run turbovi                 # a scratch buffer
+```
+
+`:q` to leave, `:help` for what is here.
+
+## What a vim user gets
+
+**The grammar**, `["x] [count] operator [count] motion`, over `hjkl w b e W B E 0 ^ $ gg G { } f F t T %`. Operators `d c y > <` with doubling (`dd`, `yy`, `cc`), text objects (`iw aw i( a" i{`), and `x X D C s S r ~ J p P o O`.
+
+**Modes**: normal, insert, visual, visual-line and command.
+
+**Paging** with `<C-f>` `<C-b>` `<C-d>` `<C-u>`, by the window rather than by a fixed number, and `<C-e>` / `<C-y>` to move the view without moving the cursor.
+
+**Search** with `/ ? n N` and match highlighting. **Undo and redo** with `u` and `<C-r>`. **`.`** repeats the last change, recorded as keystrokes the way vi does it, so a change that ends in insert mode replays whole.
+
+**`:s`** with ranges (`%`, `.`, `$`, `1,5`, `.+1`), the `g`, `i` and `n` flags, any non-alphanumeric delimiter, and `&` in the replacement. One `u` undoes the whole substitution.
+
+**Marks**: `ma` puts one down, `` `a `` comes back to the character and `'a` to the first non-blank of that line. Every jump leaves a mark, so `` `` `` returns from a `G` or a search. `:marks` lists them. They are not shifted when the text moves, which is the one place this is smaller than vi.
+
+**Macros**: `qa` records into register `a`, `q` stops, `@a` plays, `3@a` plays three times, `@@` repeats the last. They share storage with the yank registers the way vi's do, so `"ap` pastes a macro as text and `@a` runs a yanked line. A macro that calls itself stops with a message rather than a stack that runs out.
+
+**Several files at once** with `:e :ls :bn :bp :b`, split windows with `:sp` and `:vsp`, and `<C-w>` then `w s v c o` or `h j k l` to move between them. `<C-p>` and `:find` are a fuzzy picker over the project: type a few letters of the path and it opens in the current window.
+
+**The system clipboard** on `"+y` and `"+p`, over OSC 52 and a local helper, so it crosses ssh.
+
+**Syntax colouring** from the file's name. `:set syntax=rust` colours a file with no suffix, `:set nosyntax` stops. A search hit and a selection paint over the colouring, because finding something inside a comment has to be visible.
+
+**A file opens and saves as itself.** The encoding, the line endings and whether the last line had a newline are read once and written back unchanged. A latin-1 file stays latin-1, a CRLF file stays CRLF, and a file with no trailing newline does not gain one.
+
+## Settings and recovery
+
+Settings live in `$XDG_CONFIG_HOME/turbovi/config`, a file of ex commands the way a `vimrc` is:
+
+```
+set nu
+set rnu
+sp
+```
+
+A modified buffer is copied to `$XDG_DATA_HOME/turbovi/recover/` every few seconds, keyed by a hash of its absolute path, and `:recover` puts it back after a crash without writing anything to disk. The recovery copy is dropped when the buffer is saved.
+
+## What it is not
+
+Not a vim: no plugins, no scripting language, no `:g`, no folds, no tabs, no persistent undo across sessions yet.
+
+## Built on turbodesk
+
+[turbodesk](https://turbodesk.lab.abilian.com) is the immediate-mode terminal UI library underneath. This editor is the application on it that uses **no widgets at all** — views, events and hooks, nothing else — which is what proved the core carries a real application on its own. It lived in that repository as `examples/vi/` until 2026-08-26; a smaller showcase version stays there.

turbovi-0.3.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "turbovi"
+version = "0.3.0"
+description = "A vi clone for the terminal: enough vim to edit with, in three thousand lines"
+requires-python = ">=3.12"
+readme = "README.md"
+license = "Apache-2.0"
+keywords = ["terminal", "tui", "vi", "vim", "editor", "modal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Editors",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+# No `License ::` classifier: `license` above is an SPDX expression (PEP 639), and
+# PyPI rejects a distribution that carries both.
+
+# The syntax extra rather than plain turbodesk: `:set syntax` colours the buffer, and
+# `turbodesk.syntax` is where Pygments lives.
+dependencies = ["turbodesk[syntax]>=0.2"]
+
+[project.scripts]
+turbovi = "turbovi.__main__:main"
+
+# [project.urls] once the repository is public. A project URL that 404s is worse than
+# an absent one.
+
+[build-system]
+requires = ["uv_build>=0.11.33,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+# turbodesk from the checkout beside this one, so a library edit is picked up live.
+# Drop this and the version floor above takes over the day both are on PyPI.
+turbodesk = { path = "../turbodesk", editable = true }
+
+# Linting lives in ruff.toml.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--strict-markers --import-mode=importlib"
+markers = [
+    "unit: isolated and fast — no I/O, no event loop",
+    "integration: components wired together, may touch the filesystem",
+    "slow: needs an external program or wall-clock time",
+]
+
+[tool.mypy]
+# Read by zuban too. Same search path as pytest and the other checkers.
+mypy_path = "src"
+
+[tool.ty.environment]
+extra-paths = ["src"]
+
+[tool.pyrefly]
+project-includes = ["**/*.py*"]
+project-excludes = ["**/.venv/**"]
+search-path = ["src", "tests"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.0",
+    "pre-commit>=4.6.1",
+    "pyrefly>=1.2.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.1",
+    "ty>=0.0.66",
+    "types-pygments>=2.20.0.20260728",
+    "zuban>=0.9.1",
+]

turbovi-0.3.0/src/turbovi/__init__.py

@@ -0,0 +1,16 @@
+"""TurboVI: a vi clone for the terminal, in about three thousand lines.
+
+Modes, motions, operators, counts, registers, marks, macros, `.` repeat, `:s` with
+ranges and flags, multiple buffers, split windows, syntax colouring, crash recovery,
+and a config file that is a list of ex commands the way a `vimrc` is.
+
+`state.py` is the value every keystroke transforms; `keymap.py` is the grammar over it,
+pure functions with no `UI` import. `session.py` owns the buffers and windows, and
+`screen.py` draws. Built on [turbodesk](https://turbodesk.lab.abilian.com), and the one
+application on it that uses no widgets at all: the buffer is drawn from the view
+combinators directly, which is what proved the core carries an application on its own.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"

turbovi-0.3.0/src/turbovi/__main__.py

@@ -0,0 +1,198 @@
+"""turbovi — a vi clone, enough vim to edit with, in under two thousand lines.
+
+    turbovi                 # scratch buffer
+    turbovi somefile.py
+    turbovi one.py two.py   # two buffers, :bn between them
+
+Modes, counts, operators, motions, text objects, registers, undo, search, `.` to repeat
+the last change, `:s` to substitute, and a handful of other ex commands. Several files
+at once with `:e` and `:bn`, split windows with `:sp` and `:vsp`, `<C-w>` to move
+between them. Source is coloured by the file's name, and `:set syntax=rust` says so by
+hand. `:q` to leave, `:help` for what is here.
+
+Settings live in `$XDG_CONFIG_HOME/turbovi/config`, a file of ex commands the way a
+`vimrc` is. A modified buffer is copied to `$XDG_DATA_HOME/turbovi/recover/` every few
+seconds, and `:recover` puts it back after a crash.
+
+Not a bonsai_term example. This one exists to find out whether the turbodesk core is
+enough to build a real application on — no widgets, just views, events and hooks.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from dataclasses import replace
+
+from turbodesk import UI, View, run
+from turbodesk.events import Event, Key, KeyPress, Mod, Paste
+from turbovi import persist, screen, session
+from turbovi.session import Session
+from turbovi.state import INSERT
+
+HELP = (
+    "motions hjkl w b e W B E 0 ^ $ gg G { } f F t T % · "
+    "pages <C-f> <C-b> <C-d> <C-u> · scroll <C-e> <C-y> · counts 3j d2w · "
+    'operators d c y > < with dd yy cc · text objects iw aw i( a" · '
+    "x X D C s S r ~ J p P o O · v V visual · u <C-r> undo · "
+    "/ ? n N search · . repeat · qa..q @a @@ macros · ma `a 'a marks · "
+    '"+y "+p system clipboard · '
+    ":w :q :wq :s :set nu/syntax :noh :recover · ZZ · "
+    ":e :ls :bn :bp buffers · :sp :vsp :only splits · <C-w>wsvcjkhl windows"
+)
+
+#: How often a modified buffer is copied somewhere it can be recovered from. Long
+#: enough to cost nothing, short enough that a crash loses a sentence rather than a
+#: paragraph.
+RECOVERY_SECONDS = 5.0
+
+SPECIAL_KEYS = {
+    Key.ESCAPE: "<Esc>",
+    Key.ENTER: "<CR>",
+    Key.BACKSPACE: "<BS>",
+    Key.TAB: "<Tab>",
+    Key.UP: "<Up>",
+    Key.DOWN: "<Down>",
+    Key.LEFT: "<Left>",
+    Key.RIGHT: "<Right>",
+    Key.DELETE: "<Del>",
+    Key.HOME: "<Home>",
+    Key.END: "<End>",
+    Key.PAGE_UP: "<C-b>",
+    Key.PAGE_DOWN: "<C-f>",
+}
+
+
+def encode(event: Event) -> str | None:
+    """Input event to vim key notation, which is what the keymap parses."""
+    if isinstance(event, Paste):
+        return None
+    if not isinstance(event, KeyPress):
+        return None
+    if isinstance(event.key, str):
+        if Mod.CTRL in event.mods:
+            return f"<C-{event.key}>"
+        return event.key if Mod.META not in event.mods else None
+    return SPECIAL_KEYS.get(event.key)
+
+
+def configured(live: Session) -> Session:
+    """Apply the config file, which is a list of ex commands.
+
+    The loaded file's own message survives unless a config line complained, because the
+    thing worth reading on the first frame is usually "there is a recovery file" and a
+    config that ran cleanly has nothing to say.
+    """
+    loaded = session.current(live).message
+    for line in persist.read_config():
+        live = session.command(
+            session.settled(live, session.current(live).noted("")), line
+        )
+    said = session.current(live).message
+    return live if said else session.settled(live, session.current(live).noted(loaded))
+
+
+#: Requests the app carries out rather than the session: both have to leave the render
+#: loop, one for a subprocess and one for a modal.
+SPAWNED = ("clip", "find")
+
+
+def app(ui: UI, initial: Session) -> View:
+    stored, set_live = ui.state(initial)
+
+    # **Cleared before anything else reads it.** A spawned task does not run until this
+    # render returns, and a picker then waits on somebody typing at a modal, so a
+    # request left in place is re-read by every frame in between and spawned again each
+    # time. The first attempt cleared it *and then* let the scroll below write the old
+    # session back over the top — seventy-nine stacked modals, each revealed by closing
+    # the one on top of it. Everything downstream reads `live`, the cleared one.
+    pending = session.current(stored).request
+    spawning = bool(pending) and pending[0] in SPAWNED
+    live = (
+        session.settled(stored, replace(session.current(stored), request=()))
+        if spawning
+        else stored
+    )
+    editor = session.current(live)
+    if spawning:
+        if pending[0] == "clip":
+            ui.spawn(_clipboard(live, pending, set_live))
+        else:
+            ui.spawn(_find_file(live, ui, set_live))
+
+    # `live` here is one frame behind the scroll and the size settled below, and that
+    # is not a problem: setting an unequal value marks the frame dirty, so a session
+    # that has just measured a new terminal is re-rendered before any key is delivered
+    # and the handler that sees the key closes over the settled value.
+    @ui.on_event
+    def on_key(event: Event) -> bool:
+        key = encode(event)
+        if key is None:
+            return False
+        if key == "<C-c>":  # vi answers Ctrl-C with a nudge, it does not quit
+            set_live(session.settled(live, editor.noted("type :q to exit")))
+            return True
+        set_live(session.apply(live, key))
+        return True
+
+    # Keep a copy of every buffer that differs from its file, and drop it the moment it
+    # does not. `:w` clears `modified`, so writing takes the copy away by itself.
+    ui.every(RECOVERY_SECONDS, lambda: _keep(live))
+
+    if editor.quit:
+        for buffer in live.buffers:
+            if buffer.path:
+                persist.drop_recovery(buffer.path)
+        ui.exit()
+
+    # Setting an equal value does not schedule a frame, so storing the scroll this frame
+    # settled on is free on every frame that did not scroll.
+    scrolled = session.followed(live, ui.size)
+    set_live(scrolled)
+
+    ui.set_cursor(
+        screen.CURSOR, kind="bar-blinking" if editor.mode == INSERT else "block"
+    )
+    return session.render(scrolled, ui.size, ui.theme)
+
+
+async def _find_file(
+    live: Session, ui: UI, set_live: Callable[[Session], None]
+) -> None:
+    set_live(await session.found(live, ui))
+
+
+async def _clipboard(
+    live: Session, request: tuple[str, ...], set_live: Callable[[Session], None]
+) -> None:
+    set_live(await session.clipped(live, request))
+
+
+def _keep(live: Session) -> None:
+    """The recovery copy covers every open buffer, not only the one on screen."""
+    for buffer in live.buffers:
+        if not buffer.path:
+            continue
+        if buffer.modified:
+            persist.save_recovery(buffer.path, buffer.lines)
+        else:
+            persist.drop_recovery(buffer.path)
+
+
+def opened(paths: list[str]) -> Session:
+    """The session the command line asks for: a buffer per file, the first on screen."""
+    buffers = tuple(session.load(path) for path in paths) or (session.load(None),)
+    return configured(Session(buffers=buffers))
+
+
+def main() -> None:
+    arguments = [a for a in sys.argv[1:] if not a.startswith("-")]
+    if "--help" in sys.argv:
+        print(f"usage: turbovi [FILE...]\n\n{HELP}")
+        return
+    initial = opened(arguments)
+    run(lambda ui: app(ui, initial), title="turbovi")
+
+
+if __name__ == "__main__":
+    main()