summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:07:09 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:25:35 -0300
commit6b3df3071d16153bd554462c4f54ebb88f3ed50e (patch)
tree5428c2d4d6679fe0c34c0496cd58f94fad1b7486 /docs
parenta953f560f648e91dda8dd3a8dafe60a7f75739d0 (diff)
downloadpardes-6b3df3071d16153bd554462c4f54ebb88f3ed50e.tar.gz
pardes-6b3df3071d16153bd554462c4f54ebb88f3ed50e.zip
lib: pardes's syntax is a library, as ghostty-vt is ghostty's: a package that depends on pardes is given build.zig's `library` and nothing of the editor, one module, `pardes-syntax` (src/lib_syntax.zig), naming what a program that draws source text itself takes, the editor's own code under its own names (highlightFileRange and analyzeSource for a Syn a byte and the sticky headers' declarations, parse and walkNodes over the tree-sitter bindings, theme, page, ink and synInk for a named theme's colours, the line arithmetic, pathFor for a language's name); every dependency but tree-sitter's runtime is lazy in the manifest, so such a package fetches the runtime and the grammars of its tree-sitter set alone, and pardes's own build asks for all it is missing in one round before its first b.dependency; build.zig's tree-sitter and theme-generator blocks become treeSitter and generatedThemes for both to call, a grammar not yet fetched asked for and left out of that round, and the scanners' -include of src/tree_sitter_heap.h is spelled from the root package's directory, where the compiler runs (pardes's own flags are as they were); File.synStyle's switch moves to colors.synInk, so the editor and the library colour a class from one place; test/lib is such a package, depending on pardes by path: it colours, outlines and walks a C and a Zig source in orchard's colours under the testing allocator, and `zig build lib-test`, which unit-test runs, is its own `zig build test` over this checkout's zig-pkg; ts_markdown is pinned by the commit its hash is of (a0a00f81): its split_parser branch moved to v0.5.4 and a fresh fetch no longer matched; building.typ and the changelog say so; syntax snapshots unchanged
Diffstat (limited to 'docs')
-rw-r--r--docs/typ/building.typ49
1 files changed, 47 insertions, 2 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index f78f83a9..31019116 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -1,5 +1,5 @@
-// Building pardes, for contributors: platforms, options, tests, the
-// release gates and sending patches, then how the pieces fit: the core
+// Building pardes, for contributors: platforms, options, the library, tests,
+// the release gates and sending patches, then how the pieces fit: the core
// and its shells, the threads, the daemon and its sessions, the 9P engine, the
// listeners and mounts.
#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
@@ -71,6 +71,49 @@ must share with its session; `pardes --help` lists every flag.
[`-Dhelix-harness`], [reference executable for live differential tests; `HX_HARNESS`, else `hx-harness` on `PATH`],
)
+== As a library <library>
+
+A Zig package that depends on pardes is given one module and nothing of
+the editor: `pardes-syntax` (`src/lib_syntax.zig`), for a program that
+draws source text itself and wants it parsed and coloured as pardes has
+it.
+
+```
+// build.zig.zon
+.pardes = .{ .path = "../pardes" },
+// build.zig
+const pardes = b.dependency("pardes", .{
+ .target = target,
+ .optimize = optimize,
+ .@"tree-sitter" = .minimal,
+});
+exe.root_module.addImport("pardes-syntax", pardes.module("pardes-syntax"));
+```
+
+It is the editor's own code under the names it has there. A language is
+told by a path's extension, as in the editor, and `pathFor` gives a path
+for a language's name.
+
+#pairs(
+ [`highlightFileRange`, `analyzeSource`], [a style class for each byte (`Syn`: keyword, string, number, comment or none) and the declarations the sticky headers show, each with its bytes and lines],
+ [`parse`, `walkNodes`, `ts`], [a text's syntax tree, helix's walks from a byte range to the node about it, its siblings and children, and the tree-sitter bindings the nodes are read through],
+ [`theme`, `themes`, `page`, `ink`, `synInk`], [a theme by name and what it draws a page, its text and each class in],
+ [`lineCount`, `lineStartOffset`, `lineSlice`], [a line's bytes from its number],
+ [`grammars`, `supportsPath`, `pathFor`], [every grammar, and whether this build has a path's],
+ [`start`, `stop`], [tree-sitter's allocator, and the end of the parsers kept per language],
+)
+
+The `tree-sitter` option is the build's own: `zig`, `minimal` (C, C++
+and Zig) or `full`, the default. Every dependency but tree-sitter's
+runtime is lazy in the manifest, so the package fetches the runtime and
+its set's grammars and compiles those alone; pardes's own build asks for
+what it is missing in one round. Zig still unpacks a lazy package whose
+archive its global cache already holds; `--pkg-dir` (or `ZIG_LOCAL_PKG_DIR`)
+at pardes's `zig-pkg` shares the one copy. What a pane measures stays
+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.
+
= Tests
```
@@ -85,6 +128,8 @@ zig build kitty-harness kitty graphics through a pane end to end (a fake kitt
kitten icat and chafa too when installed)
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);
+ 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
zig build process-test real sessions over their sockets: mounts, flags, shells (test/process/),