diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-editor.md | 221 | ||||
| -rw-r--r-- | docs/typ/building.typ | 36 |
2 files changed, 175 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; +} +``` diff --git a/docs/typ/building.typ b/docs/typ/building.typ index 543acfa5..f5afda19 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -116,6 +116,41 @@ out: a cell's width is vaxis's and uucode's, and a tab is `config.tab_width` cells wherever it stands. `test/lib` is such a package, and `zig build lib-test` builds and runs it. +=== The editor + +`pardes-editor` (`src/lib_editor.zig`) is the text pane as a library: +helix's keys on a text kept in memory, no files, commands, builtins, +prompts or views. A package asks for it, and is then given uucode, mvzr +and vaxis's grapheme width besides; one that does not fetches nothing more. +It has `pardes-syntax` in it as `.syntax`: a file belongs to one module, so +a package imports one of the two. + +``` +const pardes = b.dependency("pardes", .{ + .target = target, + .optimize = optimize, + .@"tree-sitter" = .minimal, + .editor = true, +}); +exe.root_module.addImport("pardes-editor", pardes.module("pardes-editor")); +``` + +The editor is a value of plain data, `Editor(capacity)`: no pointer, no +allocator, every capacity in its type, so a program keeps it where it +keeps its state and it outlives the code that made it. Each call is handed +an allocator it may drop afterwards (a frame's arena), runs the editor's +own normal.zig and edit.zig, and says what came of the key. + +#pairs( + [`key`, `run`], [a key as a pane in normal or insert mode takes it, or an action the caller built: `done`, `pending` (a count or a prefix awaits the next), `unbound`, `action` (bound but the caller's: a view, `:`, `/`, `s`, a language server, a macro), or `refused` (what it made does not fit; the value is as it was)], + [`selectRegex`, `setText`, `setRegister`], [what a caller does with `s` once it has a pattern, a whole new text as one step to undo, the clipboard into `+`], + [`read`, `bytes`, `ranges`, `mode`, `pending`, `register`], [the text, the ranges in document order and the primary, normal, insert or select], + [`Language`, `Syntax`], [a grammar handed in at run time (its `TSLanguage` and query sources, told by an extension), and a text's parse and colours made again when it changes; drop it at a reload], +) + +`zig build hxlib` runs helix's cases on it against the goldens, and +`-- --parity` against the file pane. + = Tests ``` @@ -135,6 +170,7 @@ zig build kitty-harness kitty graphics through a pane end to end (a fake kitt zig build syntax-test tree-sitter tests without building the editor zig build syntax deterministic per-byte highlighting snapshots zig build lib-test the library, from a package that depends on pardes (test/lib); +zig build hxlib helix's cases on the library's editor (-- --parity: against the file pane); unit-test runs it too zig build behaviour-test behaviour through the 9P tree, in process (test/behaviour/), and the T1 runner's short run of random 9P requests |
