summaryrefslogtreecommitdiff
path: root/docs/typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ')
-rw-r--r--docs/typ/building.typ36
1 files changed, 36 insertions, 0 deletions
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