summaryrefslogtreecommitdiff
path: root/docs/next-editor.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 06:16:40 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit946e96c0ec793d6b546da8ebef19555d639ccda6 (patch)
tree8da8bdaebeede93e92dcbecea8e138b2f6e9c24e /docs/next-editor.md
parentf923d0342f7fbbc965867c19e03cb6c94fcb7fd3 (diff)
downloadpardes-946e96c0ec793d6b546da8ebef19555d639ccda6.tar.gz
pardes-946e96c0ec793d6b546da8ebef19555d639ccda6.zip
docs: the text pane as a library, as built (docs/next-editor.md): the calls, the flat form's fields and capacities, what is refused at capacity and what a ring drops, the numbers (a key at 1, 16 and 64 KiB in Debug and ReleaseFast, the pages a typed character changes, a full parse, what a package taking the editor pays to compile, pardes's recompile, perf cells and codeloc before and after), the seam's compile-time branches, the hxlib counts, what is left out and why, and the recipe for an editor in a sketch; building.typ's library section gains the editor, how a package asks for it, its calls and `zig build hxlib`; the changelog says so
Diffstat (limited to 'docs/next-editor.md')
-rw-r--r--docs/next-editor.md221
1 files changed, 139 insertions, 82 deletions
diff --git a/docs/next-editor.md b/docs/next-editor.md
index c08a63e7..58d03c46 100644
--- a/docs/next-editor.md
+++ b/docs/next-editor.md
@@ -5,101 +5,158 @@
> iterating and experimenting
Decided 2026-11-17 on the coordinator's leans (survey:
-`.scratch/sketch/reports/editor-lib.md`). One source of truth: the library
-runs the functions pardes runs, compiled from the same files; nothing is
-copied or rewritten for it.
+`.scratch/sketch/reports/editor-lib.md`); built the same day. One source
+of truth: the library runs the functions pardes runs, compiled from the
+same files with `pardes_config.lib` set; nothing is copied for it.
-## The calls
+## The calls, as built
-`library()` in build.zig exports `pardes-editor` (src/lib_editor.zig) beside
-`pardes-syntax`, only when the depending package asks for it
-(`.editor = true`): a `pardes-syntax` consumer fetches and compiles what it
-did. `pardes-editor` re-exports `pardes-syntax` as `.syntax` (a file belongs
-to one module, so a package imports one of the two).
+`library()` exports `pardes-editor` (src/lib_editor.zig) to a package that
+passes `.editor = true` (it then fetches uucode, mvzr and vaxis, of which
+it compiles the grapheme width); a `pardes-syntax` package fetches what it
+did. The module has `pardes-syntax` in it as `.syntax`.
-```zig
-const pe = @import("pardes-editor");
-const Ed = pe.Editor(.{}); // capacities in the type
-s.ed = .{}; // or Ed.init(text) once
-switch (s.ed.key(scratch, k)) { // parse + run, as a pane does
- .done, .pending => {},
- .unbound => |k| ..., // helix binds nothing to it
- .action => |a| ..., // bound, but the app's: view, `:`, LSP, `/`, `s`...
- .refused => |why| ..., // .text_full, .registers_full, .selections_full
-}
-s.ed.run(scratch, action) // a role the app built, or one it took back
-s.ed.selectRegex(scratch, pattern, .select)
-s.ed.text(scratch) s.ed.ranges(&out) s.ed.mode() s.ed.pending()
-s.ed.setText(scratch, bytes) // one undo step
-```
+- `Editor(cap)`: `key(a, k)`, `run(a, action)`, `selectRegex(a, pattern,
+ how)`, `setText(a, bytes)`, `setRegister(a, name, value)` give an
+ `Outcome`: `done`, `pending`, `unbound: Key`, `action: Action` (the
+ caller's), `refused: Refusal` (`text_full`, `registers_full`,
+ `selections_full`, `out_of_memory`). Read back: `read(buf)`,
+ `bytes(a)`, `len()`, `ranges(a, &out)`, `mode()`, `pending()`,
+ `register(a, name)`, `revision`. `load(bytes)` starts a text over.
+- `Language` (syntax.zig's run-time grammar: `ts`, `ext`, query sources)
+ and `Syntax` (`parse`, `colors`, `forget`): derived, rebuilt when
+ `revision` moves; `forget` at a reload drops the handed-in grammars.
+- `a` is any allocator the call may drop after it.
+
+## The flat form, as built
+
+Fields of `Editor(cap)` (defaults: text 64 KiB, undo and redo 256 KiB
+each, registers 16 KiB, 256 selections; about 1.2 MiB at
+`.{ .text = 128 KiB, .undo = 512 KiB }`):
+
+| field | what |
+|---|---|
+| `text`, `front`, `back` | a gap buffer; the gap is put where the key's edit ended, so typing changes the page it lands in |
+| `revision` | one more a key that changed the text |
+| `cursor` | Text's own fields by name (cells, anchor, mode, select, pending parse state, find, sticky column, `last_edit`) |
+| `sels` | the other ranges, `[cap.selections - 1]SelRange` |
+| `undo`, `redo` | byte rings of `[len][snapshot][len]`, the oldest dropped to make room; a key thaws the undo top and the two newest redos (two tell a redo from an edit forgetting them all) |
+| `registers`, `registers_len`, `last_search` | every register's values as records |
-`scratch` is any allocator the call may use and drop (a frame's arena);
-nothing outlives the call in it.
+**At capacity** a key is refused whole: `keep` checks text, selections and
+registers before it writes anything. A ring never refuses: it drops its
+oldest snapshots, never part of one (an undo ring holds at least one whole
+text, checked at compile time).
-## The stored form, flat
+**Measured** (test/lib `zig build bench`, a text in C's shape, a key typed
+into its middle, 200 keys, this machine): a key at 1, 16, 64 KiB is 13,
+173 and 692 µs in Debug (270k, 3.1M, 12.2M instructions) and 0.7, 7.7 and
+30 µs in ReleaseFast: the 64 KiB key is 4% of a 16 ms frame in Debug. A
+typed character changes 2 of the value's 4 KiB pages on average (the
+text's and the cursor's); the first after a jump moves the gap, 3, 5 and
+10 at most. A full parse is 0.2, 3.1 and 11.3 ms (tree-sitter is built
+optimised in every mode): once a changed key, not a frame, so no
+incremental re-parse.
-`Editor(cap)` is plain data, every capacity in its type: valid after a
-memcpy, after the code that made it is unloaded, with no pointer and no
-allocator. Defaults: text 64 KiB, undo and redo 256 KiB each, registers 16
-KiB, selections 256.
+A package taking the editor (test/lib) compiles cold in 6.4 s (126e9
+instructions), an edit of its own file in 0.95 s plainly and 0.09-0.11 s
+under `--watch -fincremental`. pardes itself: core-test's full recompile
+238.8e9 instructions before and after; the typing cells of `zig build
+perf` (50k lines, whole runs) 0.13-0.29% fewer instructions; codeloc's far
+share 0.5666 before, 0.5658 after. The Debug core-test binary grew from
+353 to 381 MB (shell-test's 448 to 454 MB): not looked into.
-- **text**: a gap buffer, `front` bytes at the start and `back` at the end
- of `[cap.text]u8`. The gap is put where the last edit was, so a typed
- character changes the page it lands in and the stored ints, not the
- pages after it (a shift would rewrite every page from the cursor on).
-- **selections and mode**: Text's own fields, copied by name: the primary's
- cells, its anchor, the other ranges (`[cap.selections - 1]SelRange`), the
- modal state (`normal`, `select`, `mode`, find, sticky column, `last_edit`).
-- **undo, redo**: two byte rings of whole-text snapshots with their cursor,
- as Text keeps an own text's (`remember`, `step`), the oldest dropped when
- full. A key thaws only each ring's top: `remember` compares with it,
- `step` pops it.
-- **registers**: `[cap.registers]u8` of records (name, values per range),
- `last_search`.
+## The seam, as built
-**Thaw and freeze.** Each call copies the value into the structures pardes
-edits (a `Text` of what `.body` with its characters its own, `Registers`) in
-`scratch`, runs pardes's code on them, and writes them back. That is
-O(document) a key, right for a DSL of a few KiB; the ceiling is marked
-`// ponytail:` with the way up (a shared Buffer under File and the
-library, the survey's R3).
+- `Editor` (src/Editor.zig) is gathered per call: `p.editor()` in pardes,
+ `Live.context` in the library. No field of `Pardes`, `View` or `Text`
+ moved, so the dump is as it was (an embedded field would have renamed
+ `registers` in it).
+- normal.zig and edit.zig: 57 functions take `e: Editor` (10 and 47); the
+ 22 left on `*Pardes` are the core's (the pointer's selections, the
+ clipboard, a terminal's rows, prompts, jump labels, the file's tree);
+ 119 calls outside hand `p.editor()`. `textAction` has the text's 58 roles, `executeNormalAction`
+ the core's 34, `textRole` says which. `textKey` is the mode dispatch
+ keys.zig and the library share; `runAction` and `selectByRegex` are the
+ parts of handleNormal and applySelRegex the library calls.
+- `if (comptime Editor.lib)` in: `Text.pane` (null, inline, so what a pane
+ does is not compiled), flatSurface, editText, setEditTextSpan,
+ paneCursorLines, pushUndo, undoStep (the body's characters and undo are
+ its own), bodyFile and filePane (none), replaySels, Esc and `*` (the
+ text's part), setYank (`+` is a plain register), handleNormal (the
+ core's roles come back), Editor.reportError (`failed`), and config.zig's
+ check of the builtins' leader paths.
-**At capacity** the key is refused: freeze checks every part fits before it
-writes any, the value is left as it was before the key, and the outcome is
-`.refused`. Nothing is truncated. A ring drops its oldest snapshots, never
-part of one; an undo ring is at least the text's capacity, so a text that
-fits is a snapshot that fits.
+**Held to parity**: `zig build hxlib` runs every hxdiff case on the
+library: 537 of 658 against helix's goldens and 617 of 738 against the
+file pane, 0 mismatches, the rest reaching an action the caller does (n
+and N 64, macros and `.` 14, views 34, gw 7, an insert-mode page key,
+expand_node 1). What it found was fixed: paneCursorLines gave the library
+no lines; `s` keeps its pattern in `/`.
-**Syntax is derived**, never stored: `pe.Syntax` is rebuilt from the bytes
-and a `pe.Language` handed in at run time (its `TSLanguage` and query
-sources, syntax.zig's run-time `Spec`), dropped at a reload.
+## Left out, and why
-## The seam in pardes
+Files, commands, builtins, LSP, look/exec, prompts, views, sam's Edit,
+terminals, replicas, dumps. Macros and `.`: their log is keys.zig's (the
+core's dispatcher) and recording replays through it; keeping them meant
+moving it, more code than leaving them out. `n`/`N`: pardes decides
+between the look ring, a query's places and the register, the core's.
+Tree-sitter walks (Alt-o and kin, `]f`) and tree indents: they read the
+file's kept tree; the library parses in `Syntax`, so they come back as
+actions (a later step: hand the tree in the context).
-- **R1.** `Editor` (src/Editor.zig): the context an edit runs with, gathered
- per call (`p.editor()`): the allocators, pointers to the registers, the
- named register and the replay's state (`multi_*`), the retired text, and
- `p: *Pardes` (void in the library). The fields stay where they are on
- `Pardes` and its view: no dump changes, registers kept across an Upgrade.
- The embedded `ed: Editor` field with `@fieldParentPtr` would have moved
- `registers` in the dump (fields are matched by name) and lost them at an
- Upgrade from an older build.
-- **R2.** The text functions of normal.zig and edit.zig take `e: Editor`;
- `executeNormalAction` splits into `run` (the text's roles, returning the
- rest) and the core's switch.
-- **Library build.** `pardes_config.lib` is true only in `library()`. The
- routing functions branch on it at compile time: `Text.pane()` is null, a
- body's characters are its own, its undo is Text's own. Zig analyses only
- the branch taken, so the library never compiles panes, tags or LSP.
+## An editor in a sketch (not compiled against sketchbook)
-## Not in the library
+```zig
+const sk = @import("sketch");
+const pe = @import("pardes-editor");
+const Ed = pe.Editor(.{ .text = 32 * 1024, .undo = 128 * 1024 });
+extern fn tree_sitter_mydsl() *const pe.syntax.ts.Language; // the DSL's parser.c, in build.zig
+const dsl_highlights = @embedFile("highlights.scm");
-Files, commands, builtins, LSP, look/exec, prompts and their UI, view and
-scroll keys (`zz`, C-f, `gt`), the clipboard (`+` is a plain register the
-app fills), sam's Edit, terminals, replicas, dumps; macros and `.` (their
-recording lives in keys.zig, the core's dispatcher: keeping them would mean
-moving it, more code than leaving them out). These come back as `.action`.
+pub const State = struct { ed: Ed = .{}, run: sk.Request(u32) = .{} };
+pub const Session = struct { syn: pe.Syntax = .{}, arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator) };
-## What a dump from before loads as
+/// printables from `text` events only (a key_down comes with them too)
+fn toKey(e: sk.Event) ?pe.Key {
+ return switch (e.kind) {
+ .text => .{ .cp = @intCast(e.value), .text = utf8(e.value) }, // the codepoint's bytes, kept in State or a static
+ .key_down => switch (e.key()) {
+ .escape => .{ .cp = pe.Key.escape },
+ .enter => .{ .cp = pe.Key.enter },
+ .backspace => .{ .cp = pe.Key.backspace },
+ .left => .{ .cp = pe.Key.left }, // and the rest of the specials
+ else => null, // ctrl and alt chords: `.{ .cp = letter, .ctrl = mods & ctrl != 0 }`
+ },
+ else => null,
+ };
+}
-The same: no field of `Pardes`, `View` or `Text` changes name or type.
+pub fn update(s: *State, in: *const sk.Input) void {
+ var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator); // no allocator reaches State
+ defer arena.deinit();
+ for (in.events) |e| {
+ const k = toKey(e) orelse continue;
+ if (k.cp == pe.Key.enter and k.ctrl) { s.run.send(s.ed.revision); continue; } // mine, before helix
+ switch (s.ed.key(arena.allocator(), k)) {
+ .action => |a| if (a.role == .select_regex) {}, // open my prompt; then s.ed.selectRegex(...)
+ .refused => {}, // the DSL is full: say so
+ else => {},
+ }
+ }
+}
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ const a = f.scratch;
+ if (f.in.jumped) ss.syn.forget(); // new code: the grammar's pointers are stale
+ const lang: pe.Language = .{ .name = "mydsl", .ext = ".mydsl", .ts = tree_sitter_mydsl(), .highlights = dsl_highlights };
+ const text = s.ed.bytes(a) catch return;
+ const colors = pe.Syntax.colors(a, &s.ed, lang, 0, text.len) catch &.{};
+ _ = ss.syn.parse(a, &s.ed, lang); // the tree, for sizes by node, an inline Typst block...
+ // lines, coloured by `colors[i]`; then the ranges and a caret
+ var out: [pe.max_selections]pe.Selection = undefined;
+ const got = s.ed.ranges(a, &out) catch return;
+ for (out[0..got.n], 0..) |r, i| drawRange(f, text, r, i == got.primary); // f.fill under the bytes, f.text over
+ _ = colors;
+}
+```