summaryrefslogtreecommitdiff
path: root/docs/next-editor.md
blob: c08a63e72f2e3042c15fb293b7399c7298eaf819 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
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.