summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:07:32 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit83b9d45b8665a80bdb70934aa23bbde5cc03d202 (patch)
treec902b557ef624b07cd139659d0a891cd4809e03e /docs/typ/reference.typ
parentb3d32656413734952bc918c2d4cfd12fede6c214 (diff)
downloadpardes-83b9d45b8665a80bdb70934aa23bbde5cc03d202.tar.gz
pardes-83b9d45b8665a80bdb70934aa23bbde5cc03d202.zip
plumber: a look sends what it looks at (docs/next-plumber.md, phase 2): after the pane's own readings and once a name already open in a pane is focused (never sent), lookAt sends the trimmed name, type text, src pardes (term from a raw terminal, a kind's name from its pane), wdir the pane's directory, with what resolveLookTarget found of it (Plumb.Seen: isfile and isdir take it, so no second stat and Look's own readings of a URL or `//` stay no file); a message the rules give back to `edit` as sent is Look's own (Sent.look) and runs lookAt's switch on that target, one nothing takes or a started word declines is Look's own too, whose `.url` arm is now the word's search; the edit port's open of another message runs with look_text, which now means "unplumbed", so the edit port's lookAt never sends again (the recursion trap); the three diff hooks become the default rules of the record's §5.2 (a bare .diff/.patch to `Diff $file`, a commit hash in the editor to `Diff $0`, after the two edit sets), and `Diff` takes a file or a revision, a rule's Diff declining in silence (Pardes.plumb_declined) where it cannot (no hunk, not readable, no .git above): hunks.lookedAt and lookedAtCommit go, their bodies in hunks.word, the `needs` check of the bare form in the word, PaneKind.diff gone; the old one-line `Plumb` word, Core.plumb, look.Port, plumbRuleError, plumbTarget and resolve's rules block go: bare, `Plumb` opens <config>/plumbing as Config opens init (both through builtins.openConfigFile; `include basic` in a new one), an argument is refused in words, Save applies it (host_io.writeFile beside reapplyInitFile, Plumb.saved), and boot reads it (Plumb.boot in applyStartupConfig); a started program now runs detached as Plan 9's plumber's (the coordinator's decision for the user's question 4): Effect.start, every host's host_io.startDetached (double fork, setsid, /dev/null for 0-2, every other fd closed, argv exec'd in wdir with no shell, the child's errno back through a close-on-exec pipe, said as `plumb start: <prog>: <why>`), so exec_dir goes; resolveLookTarget's and Plumb.Send.search's directory walk is one look.Dirs; test: look.zig's Plumb test rewritten onto the rules (a rule's word, an open pane unsent, the hover's resolve, a URL with no web rule searched for) and a hash inside and outside a git work tree; addons.zig's Plumb test onto plumb/rules (a port no kind reads, its kind gone: Look's own); Plumb.zig: the word, the save and boot; replicas.zig gains a URL (speculated whole, confirmed, no rollback) and a hash, each the authority's and a replica's own; every look golden unchanged; the reference quotes src/plumbing whole and says the order, the changelog says so
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ41
1 files changed, 32 insertions, 9 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 0d287381..f1b4df76 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -1022,15 +1022,22 @@ at 200, ending in `…`. Control characters become spaces.
= 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")).
+match a message and say where it goes. A #word("Look") asks it first, as
+acme's does: after the pane's own readings (a +History or +Recent row, a
+diff line, a command word, `file:/re/`) and once a name already open in a
+pane is focused (never sent), what is looked at is sent, `type` `text`,
+`src` `pardes` (`term` from a terminal's raw mode, a kind's name from its
+pane), `wdir` the pane's directory, the data the name as Look reads it.
+One that no rule set takes, or that a started word declines, is Look's
+own: a file or directory opened, else the word searched for.
- #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
+ place. A session starts with the plumbing file's rules, #word("Plumb")
+ (`plumbing` in the configuration directory, beside `init`; saved, its
+ rules are in force), or without one `include basic`, pardes's own
+ (`src/plumbing`, below). 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,
@@ -1060,9 +1067,25 @@ yet (the #word("Plumb") rules do, #doc("reference", section: "from-acme")).
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.
+- `plumb start` of a builtin or a kind's word runs it in place, at the
+ looking pane (the pane with the keyboard for a #file("/plumb/send")
+ message); one that cannot do what it is asked declines, saying
+ nothing, and the send is refused (`no matching plumb rule`), so a
+ #word("Look") looks itself. Any other word is a program, started as
+ Plan 9's plumber starts one: detached, no pane, stdin, stdout and
+ stderr `/dev/null`, its words exec'd in `wdir` with no shell (a rule
+ that wants one says `sh -c '...'`); a failure to start it is said, and
+ logged as an `err`. Its directory and words fit in 256 bytes.
+
+The default rules, `src/plumbing`, keep #word("Look")'s ways: a URL to
+the browser; a bare `.diff` or `.patch` stacked in a +Diff (#word("Diff")
+with the file, which declines one with no hunk, opened as text then); an
+existing directory or file to `edit`, Look's own open (a kind's file in
+its kind); a commit hash looked at in the editor, in a git work tree, to
+#word("Diff") with it, `git show` paged (outside one, Diff declines and
+the word is searched for):
+
+#raw(read("../../src/plumbing"), block: true)
= Addons <addons>
@@ -1401,7 +1424,7 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
[Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#doc("fs", section: "edit"))],
[`win`], [#word("Term") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
[a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it],
- [the plumber], [no process: #word("Plumb") rules, one a line in plumb(6)'s order (`Plumb suffix .svg to image`), for the session and kept in a dump, are tried before the built-in ones and the first that matches takes the #word("Look"); the tests are `prefix`, `suffix` (an existing file's name, any case), `isdir` and `isfile`, the ports `url` (`xdg-open`, `open` on macOS), `dir`, `file` and any loaded kind by its name (`image`, `pdf`): a rule naming a kind not loaded is refused, and one whose kind has gone since is passed over; no `matches`, attributes, variables or `include`; bare, #word("Plumb") lists the rules, `Plumb -` empties them; the user's own go in `init`, a `Plumb` line each; the built-in rules: an `http://` or `https://` URL to `url`, a directory, a kind's extensions, then any file],
+ [the plumber], [no process: the plumber is the editor's own (#doc("reference", section: "plumber")): plumb(6)'s rules in #file("/plumb/rules") and the plumbing file #word("Plumb") opens, messages to #file("/plumb/send"); no submatches (`$1`-`$9`), no `click` from a #word("Look") (its own expansion stands), and no external port files yet],
[#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
)