From 55dbff5aced5c62f47be39fbc01276b6e36d7dd5 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 05:37:59 -0300 Subject: docs/next-editor.md: the text pane as a library, the record before the code (.scratch/sketch/reports/editor-lib.md, the coordinator's leans): the calls as they will ship (key, run, selectRegex, text, ranges, mode, pending, setText; Outcome done, pending, unbound, action, refused), the flat stored form and its capacities (a gap buffer for the text, Text's fields by name, two rings of snapshots, registers as records), thaw and freeze O(document) a key, a key refused whole at capacity, syntax derived from a language handed in at run time, the seam (a context of pointers gathered per call, not an embedded field: the dump matches fields by name), what is left out and why, and that a dump from before loads as it did --- docs/next-editor.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/next-editor.md (limited to 'docs') diff --git a/docs/next-editor.md b/docs/next-editor.md new file mode 100644 index 00000000..c08a63e7 --- /dev/null +++ b/docs/next-editor.md @@ -0,0 +1,105 @@ +# The text pane as a library: `pardes-editor` + +> the basic text pane of pardes as a library … embeddable but taken from +> pardes … the end goal is to make the sketch a live environment for +> 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. + +## The calls + +`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). + +```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 +``` + +`scratch` is any allocator the call may use and drop (a frame's arena); +nothing outlives the call in it. + +## The stored form, flat + +`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. + +- **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`. + +**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). + +**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. + +**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. + +## The seam in pardes + +- **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. + +## Not in the library + +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`. + +## What a dump from before loads as + +The same: no field of `Pardes`, `View` or `Text` changes name or type. -- cgit v1.3 From 946e96c0ec793d6b546da8ebef19555d639ccda6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 06:16:40 -0300 Subject: 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 --- docs/next-editor.md | 243 +++++++++++++++++++++++++++++++------------------- docs/typ/building.typ | 36 ++++++++ src/CHANGELOG.md | 12 +++ 3 files changed, 198 insertions(+), 93 deletions(-) (limited to 'docs') 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. - -## The calls - -`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). +`.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, as built + +`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`. + +- `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 | + +**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). + +**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. + +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. + +## The seam, as built + +- `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. + +**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 `/`. + +## Left out, and why + +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). + +## An editor in a sketch (not compiled against sketchbook) ```zig +const sk = @import("sketch"); 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 +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"); + +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) }; + +/// 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, + }; } -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 -``` -`scratch` is any allocator the call may use and drop (a frame's arena); -nothing outlives the call in it. - -## The stored form, flat - -`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. - -- **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`. - -**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). - -**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. - -**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. - -## The seam in pardes - -- **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. - -## Not in the library - -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`. - -## What a dump from before loads as - -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 diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 44d55707..294b7445 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -2,6 +2,18 @@ ## Unreleased +- The text pane is a library too, `pardes-editor` (`src/lib_editor.zig`, + docs/next-editor.md): helix's keys on a text kept in memory, for a + program that draws it itself (a sketch with a language of its own). It + is a value of plain data, every capacity in its type, copied anywhere + and outliving the code that made it; each call runs pardes's own + normal.zig and edit.zig on it, built with no pane and no core, and hands + back what is not the text's (a view, `:`, `/`, `s`, a language server, a + macro) to its caller. A grammar can be handed in at run time beside the + compiled-in ones. A package asks for it with `.editor = true`; one that + asks for `pardes-syntax` alone fetches what it did. `zig build hxlib` + runs helix's cases on it, against the goldens and against the file pane. + Nothing a session does changes, and a session dumped before loads after. - The terminal is a module of its own (`src/term/`: the emulator, its screen state for replicas, kitty images, the pager's parse), which never imports the core and is reached through one table of plain-data -- cgit v1.3 From dee94c740bdaea61ff35b4e0a7f1d2815c9ee441 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 07:33:32 -0300 Subject: +85 -24 docs: the library's tree handed in and its replace, as built (docs/next-editor.md): `key(a, syn, k)`, `run(a, syn, act)` and `replace(a, from, to, with, join)` among the calls; the tree handed in, its shape and why (an argument the call's context carries, `normal.nodeTree` the one seam), which walks run in the library and what comes back without one; the hxlib counts, 538 of 658 and 618 of 738, the walks' one case compared; Left out keeps tree indents and says where Alt-o's history lives; the recipe gains "hear this subexpression" (Alt-o and Alt-i on a module's `Syntax`, the primary range read back) and "drag a number" (the number node under the pointer rewritten every frame, the drag one step to undo); building.typ's table and the changelog say so; hxlib 538 / --parity 618, core-test 811 of 950, shell-test 990 of 993, hxdiff 658 / parity 738 / hxgolf 124 with 0 mismatches, replicas pass, lib-test pass, the book compiles Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- docs/next-editor.md | 99 +++++++++++++++++++++++++++++++++++++++------------ docs/typ/building.typ | 4 +-- src/CHANGELOG.md | 6 ++++ 3 files changed, 85 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/next-editor.md b/docs/next-editor.md index 58d03c46..af0ee537 100644 --- a/docs/next-editor.md +++ b/docs/next-editor.md @@ -16,17 +16,39 @@ 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`. -- `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)`, +- `Editor(cap)`: `key(a, syn, k)`, `run(a, syn, action)`, + `selectRegex(a, pattern, how)`, `setText(a, bytes)`, `replace(a, from, + to, with, join)`, `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. +- `a` is any allocator the call may drop after it; `syn` a `?*Syntax`. +- `replace` rewrites the bytes `from..to` as one step to undo, the ranges + following as an edit moves them (one inside the bytes goes to their + start: edit.replaceBytes, one sam op the ranges are mapped through as + `&`'s are); `join` makes it part of the step before instead: a drag + passes false on its first frame and true on the rest, and one undo + takes it all back. + +**The tree handed in** (`syn`): the walks read a `Syntax`, which keeps +its `lang` (the last `parse`'s, or set), the tree, parsed on the first +walk after `revision` moves, and helix's object_selections, Alt-o's +history for Alt-i to go back by (the page allocator: it holds nothing of +the code that made it). With it, Alt-o, Alt-i, Alt-n, Alt-p, Alt-a, +Alt-I, Alt-e, Alt-b and `]f` and kin are the text's and run in the +library on pardes's own nodeSelect and objectJump, and `mif` and kin find +the `Language`'s `textobjects`; with no `lang` they do nothing, as in a +text without a grammar. Without `syn` they come back as actions (`mif` +does nothing). An argument, not a field of the value: the tree holds +pointers into the grammar's code, and an argument is the least code +(the context of the call carries it, `Editor.syntax`; no interface). +`normal.nodeTree` is the one seam: a file's `fileTree` in pardes, the +`Syntax` in the library, `Editor.Tree` what both give. ## The flat form, as built @@ -79,7 +101,8 @@ share 0.5666 before, 0.5658 after. The Debug core-test binary grew from 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 +- `if (comptime Editor.lib)` in: `nodeTree` (the parse handed 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 @@ -88,10 +111,11 @@ share 0.5666 before, 0.5658 after. The Debug core-test binary grew from check of the builtins' leader paths. **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 +library: 538 of 658 against helix's goldens and 618 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 +and N 64, macros and `.` 14, views 34, gw 7, an insert-mode page key); +it hands each case a `Syntax` with no grammar, as a case's text has +none, so the walks' one case (expand_node) is compared. What it found was fixed: paneCursorLines gave the library no lines; `s` keeps its pattern in `/`. ## Left out, and why @@ -101,9 +125,11 @@ 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). +Tree indents: they read the file's tree through `fileTree`, not +`nodeTree`; a new line's indent in the library is the plain one. +Alt-o's history across calls lives in the `Syntax`, so a caller that +makes one per call (a sketch's `update` sees only State) has Alt-i go to +the first child instead, as helix does with no history. ## An editor in a sketch (not compiled against sketchbook) @@ -114,8 +140,14 @@ 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"); -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) }; +pub const State = struct { ed: Ed = .{}, run: sk.Request(u32) = .{}, hear: sk.Request([2]usize) = .{}, drag: ?Drag = null }; +const Drag = struct { at: u32, from: f32, value: f64, moved: bool = false }; +/// The parse: derived, so not in State; a module's var, as `update` sees only +/// State (a reload starts it again with the code; the old tree is leaked). +var syn: pe.Syntax = .{}; +fn dsl() pe.Language { + return .{ .name = "mydsl", .ext = ".mydsl", .ts = tree_sitter_mydsl(), .highlights = dsl_highlights }; +} /// printables from `text` events only (a key_down comes with them too) fn toKey(e: sk.Event) ?pe.Key { @@ -135,24 +167,47 @@ fn toKey(e: sk.Event) ?pe.Key { 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(); + const a = arena.allocator(); + syn.lang = dsl(); 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(...) + switch (s.ed.key(a, &syn, k)) { // Alt-o, Alt-i... run here, on `syn` + .action => |act| if (act.role == .select_regex) {}, // open my prompt; then s.ed.selectRegex(...) .refused => {}, // the DSL is full: say so else => {}, } + // "hear this subexpression": after Alt-o or Alt-i, the primary range + if (k.alt and (k.cp == 'o' or k.cp == 'i')) { + var out: [pe.max_selections]pe.Selection = undefined; + const got = s.ed.ranges(a, &out) catch continue; + const r = out[got.primary]; + s.hear.send(.{ @min(r.anchor, r.head), @max(r.anchor, r.head) }); + } } + // "drag a number": the number token under the pointer, rewritten each + // frame of the drag, the whole drag one step to undo + if (in.mouse.pressed) s.drag = .{ .at = byteUnder(s, in.mouse), .from = in.mouse.x, .value = 0 }; // byteUnder: my layout's + if (s.drag) |*d| if (in.mouse.down) { + const tree = syn.parse(a, &s.ed, dsl()) orelse return; + const n = tree.rootNode().descendantForByteRange(d.at, d.at) orelse return; + if (!std.mem.eql(u8, n.kind(), "number")) return; + const text = s.ed.bytes(a) catch return; + if (!d.moved) d.value = std.fmt.parseFloat(f64, text[n.startByte()..n.endByte()]) catch return; + var buf: [32]u8 = undefined; + const num = std.fmt.bufPrint(&buf, "{d}", .{d.value + (in.mouse.x - d.from) * 0.01}) catch return; + _ = s.ed.replace(a, n.startByte(), n.endByte(), num, d.moved); // the first frame a step, the rest joined + d.moved = true; + } else { + s.drag = null; + }; } -pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { +pub fn draw(s: *const State, 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... + const colors = pe.Syntax.colors(a, &s.ed, dsl(), 0, text.len) catch &.{}; + _ = syn.parse(a, &s.ed, dsl()); // 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; diff --git a/docs/typ/building.typ b/docs/typ/building.typ index f5afda19..17b18f35 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -143,9 +143,9 @@ 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 `+`], + [`selectRegex`, `setText`, `replace`, `setRegister`], [what a caller does with `s` once it has a pattern, a whole new text as one step to undo, a byte range rewritten as one (or `join`ed to the step before: a drag's frames one 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], + [`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. Handed to `key` and `run`, the tree-sitter walks (Alt-o and kin, `]f`, `mif`) run on it; without one they are the caller's], ) `zig build hxlib` runs helix's cases on it against the goldens, and diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 294b7445..6d51311b 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -14,6 +14,12 @@ asks for `pardes-syntax` alone fetches what it did. `zig build hxlib` runs helix's cases on it, against the goldens and against the file pane. Nothing a session does changes, and a session dumped before loads after. + The caller can hand it the parse it keeps (`Syntax`), and helix's + tree-sitter walks (Alt-o, Alt-i, Alt-n, Alt-p and kin, `]f`, `mif`) run + in the library on pardes's own functions, Alt-i going back the way + Alt-o came; `replace` rewrites a byte range as one step to undo, the + ranges following, and a drag that rewrites a number every frame can + join its frames into one. - The terminal is a module of its own (`src/term/`: the emulator, its screen state for replicas, kitty images, the pager's parse), which never imports the core and is reached through one table of plain-data -- cgit v1.3