summaryrefslogtreecommitdiff
path: root/docs/typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 01:42:25 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitb3d32656413734952bc918c2d4cfd12fede6c214 (patch)
tree04386fab10b9ed803ec31251cb733cc32852390a /docs/typ
parent4a33b8d2bd409d4a06205f28e0eb1b4cdaf49889 (diff)
parente6e81a6bc544c5ab5a47c21d85e6868020031abb (diff)
downloadpardes-b3d32656413734952bc918c2d4cfd12fede6c214.tar.gz
pardes-b3d32656413734952bc918c2d4cfd12fede6c214.zip
integration: the diff viewer on general mechanisms, and the plumber's first phase, together
A merge of diff-lib and plumber-1; the changelog keeps both sides' entries; core-test 984/984 on tui, the process suite's tree cases pass (fs-help.txt holds both the rows and the plumb lines in its 45). Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'docs/typ')
-rw-r--r--docs/typ/reference.typ48
1 files changed, 48 insertions, 0 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 637d9c72..0d287381 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -38,6 +38,9 @@ addons the kinds of pane here, compiled in or an addon's @add
layout a line per column, then active <serial> @columns-and-tags
tag the workspace tag @columns-and-tags
tagexec a word clicked in the workspace tag @columns-and-tags
+plumb/ the plumber's: plumb(6) rules, and messages sent by them @plumber
+ rules the rules in force; a write adds rule sets, > replaces them @plumber
+ send write a message: six header lines, then its data @plumber
col/ the columns @columns-and-tags
<n>/ column <n>; rmdir closes it when empty @columns-and-tags
tag its tag
@@ -1016,6 +1019,51 @@ at 200, ending in `…`. Control characters become spaces.
synthetic. Linux v9fs's truncation `mtime` hint is accepted and dropped.
- #file("/src/") with `-Dembed-sources=true`.
+= The plumber <plumber>
+
+Plan 9's plumber(4), its language plumb(6)'s, in the session: rules
+match a message and say where it goes. A #word("Look") does not ask it
+yet (the #word("Plumb") rules do, #doc("reference", section: "from-acme")).
+
+- #file("/plumb/rules") reads the rules in force: rule sets of
+ `object<tab>verb<tab>arg` lines, each set ended by a blank line, a
+ variable's `name=value` where it was set, an `include`'s rules in its
+ place. A session starts with `include basic`, pardes's own
+ (`src/plumbing`): a URL to the `web` port, an existing directory or file
+ (at the place written after it) to `edit`. A write adds rule sets, each
+ read as its blank line comes, the rest at the close; `>` replaces them
+ all. One open writes at a time (`file in use`). Kept in a dump.
+- A rule set that does not read is refused at the write it is whole in,
+ `plumb/rules:<line>: <why>` in rules.c's words (`unknown verb isnt`,
+ `ruleset must have patterns and actions`), and the rules stay as they
+ were. `$1`-`$9` are refused: pardes's regular expressions
+ (#doc("reference", section: "regexp")) have no submatches; write `$0`
+ and several `matches`, as Pike's two patterns do. `include basic` is
+ `src/plumbing`; another name is the configuration directory's file, an
+ absolute one where it says.
+- #file("/plumb/send") takes a message, plumb(6)'s six lines (`src`,
+ `dst`, `wdir`, `type`, `attr`, the data's length) and then the data,
+ in one write or several. The write is answered once it has gone where
+ the first rule set whose patterns hold says, or refused in Plan 9's
+ words: `bad plumb message format`, `couldn't find destination for
+ message` (no rule set takes it and it names no port), `no start action
+ for plumb message`, `no port for "client" rule`.
+- The verbs are plumb(6)'s: `is`, `matches` (the whole text; with
+ `click=N` in `attr`, the run around rune N, and the data cut to it),
+ `isfile` and `isdir` (a name found as #word("Look") finds one: past the
+ place written after it, in `wdir`, then #word("Incl")'s directories;
+ `$file` and `$dir` are where), `set`, `add` and `delete` (`delete` of
+ an attribute not there fails, as plumber's code does), and the actions
+ `plumb to <port>`, `plumb start <words>` and `plumb client <words>`.
+- The ports pardes reads itself: `edit` (the data opened as a
+ #word("Look") opens it, at `addr=` when given), `web` (the host's
+ browser, a URL of at most 256 bytes) and each loaded kind by its name
+ (`image`, `pdf`). A message to another port runs its rule set's
+ `start` or `client`; to a port no rule names it goes nowhere.
+- `plumb start` runs its words as #word("Exec") runs a line: a builtin in
+ place at the pane with the keyboard, anything else a command pane in
+ the message's `wdir`, each word one argument to the shell.
+
= Addons <addons>
An addon is a shared library that brings one kind of pane: a picture, a