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 --- src/CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'src/CHANGELOG.md') 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 'src/CHANGELOG.md') 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