diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 03:51:15 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 79a1e816ceb13ef81b712007716c8add2de75434 (patch) | |
| tree | 1714b1bf19da3a58be2623ffe29e3f8be1b21fe3 /docs | |
| parent | a22b579ad2df8d1811f0e194fa1bbc06e2282cf8 (diff) | |
| parent | f1af015f01e4e8d42f6224c4d4063f3aea218f5a (diff) | |
| download | pardes-79a1e816ceb13ef81b712007716c8add2de75434.tar.gz pardes-79a1e816ceb13ef81b712007716c8add2de75434.zip | |
integration: the terminal a module of its own, with the plumber whole and the walker's cheaper compile
A merge of term-phase1a and pardes-next, no conflicts. core-test (the core with no terminal) 411 passed, 535 skipped of 946; shell-test (the same tests, the terminal compiled in) 989/989, on tui.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-plumber.md | 29 | ||||
| -rw-r--r-- | docs/typ/builtins-gui.json | 4 | ||||
| -rw-r--r-- | docs/typ/builtins-tui.json | 4 | ||||
| -rw-r--r-- | docs/typ/guide.typ | 2 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 72 |
5 files changed, 91 insertions, 20 deletions
diff --git a/docs/next-plumber.md b/docs/next-plumber.md index 76a86bea..178814b3 100644 --- a/docs/next-plumber.md +++ b/docs/next-plumber.md @@ -867,6 +867,35 @@ The options as round 1 put them: $0`, `9 page $file`), at the cost of a host effect generalising `open_link`. +## What phases 2-4 did otherwise (2026-11-17) + +- **Q4 is (b) now**, the coordinator's lean while the user was away: a + program a rule starts runs detached, as Plan 9's plumber starts one + (Effect.start, every host's host_io.startDetached: setsid, stdin, stdout + and stderr `/dev/null`, every other fd closed, argv exec'd in wdir with no + shell). Its output is not the session's log, as the lean said: that needs + an inbox message and an Event through the tui, window, macOS and daemon + hosts, which other agents are changing. A failure to start (the program + not found, its directory gone) is said and logged, the child's errno + carried back by a close-on-exec pipe. Its directory and words fit 256 + bytes, an effect's inline payload. +- **Only a diff paged is sent** (§5.4 had every page sent). Text paged is + `type text`, which the look rules do see, contrary to §5.4: their + `matches` would run over the whole output (up to a MiB, and the regular + expressions' 300 ms budget) at each page. A diff is `text/x-diff`, which + every look rule refuses at its first pattern. +- **A port pardes reads itself (edit, web, a kind) asks nobody** whether a + program reads it: its readers' copies are the authority's own to hand + out, and pardes reads it anyway, so a URL's look still speculates whole. + Only another port's dispose asks `tape.authority`. +- **The rules in force are read once** and kept until their text changes + (by its hash, derived state): per send the parse was 29k instructions + in a fast build, about half of a URL's send and 40% of a word's look. +- **`showdata` from another sender** makes a clean pane of its `filename` + (acme's plumbshow); the pager's own message is shown already. +- **plumb/rules' rest read at the close**, refused there, is an `err` in + the log (Plan 9 loses it); the T1 monkey models it as a line file's. + ## Not verified - **Nothing was built or run.** All sizes are estimates, and the test counts are diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json index c7ff594f..8ed70b10 100644 --- a/docs/typ/builtins-gui.json +++ b/docs/typ/builtins-gui.json @@ -26,7 +26,7 @@ {"name": "Delcol", "leader": "SPC c d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close this column and its panes, refusing once over unsaved text."}, {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal or window, leaving the session running: `pardes --attach` (or `pardes-gui --attach`) takes it back."}, {"name": "Diagnostics", "leader": "SPC l d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the file's diagnostics from the language server."}, - {"name": "Diff", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."}, + {"name": "Diff", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."}, {"name": "Down", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane below, off a tag onto the pane under it."}, {"name": "Dump", "leader": "SPC s d", "also": ["topbar"], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Write the session's panes and layout to the state file, for Restore; `Dump export <path>` writes them to a file of their own instead."}, {"name": "DumpConfig", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the settings in effect, each a word to click, and the startup file's path."}, @@ -76,7 +76,7 @@ {"name": "Panes", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Pick an open pane by its name in a query pane under this one (SPC b b)."}, {"name": "Pet", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "off, cat, frog", "doc": "The window's companion in the workspace tag's blank space: off, cat or frog."}, {"name": "Petscii", "leader": "SPC t p", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "glyph art over the host's pixels: an image pane's picture, or the kitty graphics a terminal's program placed (yazi's previews)"}, - {"name": "Plumb", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "The plumber's rules, for the session, one a line as plumb(6) orders a rule: `Plumb suffix .svg to image` makes a look at an existing `.svg` file an image pane."}, + {"name": "Plumb", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Open the plumbing file, the plumber's rules (plumb(6)'s rule sets) in the configuration directory beside `init`: saved, they are the rules in force."}, {"name": "Putall", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "acme's Putall: every pane holding unsaved edits to a file is saved, each as its own Save; one that is refused (changed on disk since, a write that fails) says so and the rest are saved all the same."}, {"name": "Recent", "leader": "SPC f r", "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "List the files opened lately, closed ones too, each a place to open again."}, {"name": "Redo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Redo the last undone edit."}, diff --git a/docs/typ/builtins-tui.json b/docs/typ/builtins-tui.json index feb1140f..aa95d9a6 100644 --- a/docs/typ/builtins-tui.json +++ b/docs/typ/builtins-tui.json @@ -25,7 +25,7 @@ {"name": "Delcol", "leader": "SPC c d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close this column and its panes, refusing once over unsaved text."}, {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal or window, leaving the session running: `pardes --attach` (or `pardes-gui --attach`) takes it back."}, {"name": "Diagnostics", "leader": "SPC l d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the file's diagnostics from the language server."}, - {"name": "Diff", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."}, + {"name": "Diff", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."}, {"name": "Down", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane below, off a tag onto the pane under it."}, {"name": "Dump", "leader": "SPC s d", "also": ["topbar"], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Write the session's panes and layout to the state file, for Restore; `Dump export <path>` writes them to a file of their own instead."}, {"name": "DumpConfig", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the settings in effect, each a word to click, and the startup file's path."}, @@ -71,7 +71,7 @@ {"name": "Palette", "leader": "SPC t l", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "the C64 palette or the terminal's own 16"}, {"name": "Panes", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Pick an open pane by its name in a query pane under this one (SPC b b)."}, {"name": "Petscii", "leader": "SPC t p", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "glyph art over the host's pixels: an image pane's picture, or the kitty graphics a terminal's program placed (yazi's previews)"}, - {"name": "Plumb", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "The plumber's rules, for the session, one a line as plumb(6) orders a rule: `Plumb suffix .svg to image` makes a look at an existing `.svg` file an image pane."}, + {"name": "Plumb", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Open the plumbing file, the plumber's rules (plumb(6)'s rule sets) in the configuration directory beside `init`: saved, they are the rules in force."}, {"name": "Putall", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "acme's Putall: every pane holding unsaved edits to a file is saved, each as its own Save; one that is refused (changed on disk since, a write that fails) says so and the rest are saved all the same."}, {"name": "Recent", "leader": "SPC f r", "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "List the files opened lately, closed ones too, each a place to open again."}, {"name": "Redo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Redo the last undone edit."}, diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index c602927d..6a50eef1 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -174,7 +174,7 @@ pardes. addr("notes.txt:12"), [line 12], addr("notes.txt:/TODO/"), [the next match of `TODO`], addr("src/"), [a pane listing it, as acme's directory window: a #word("Look") at an entry opens it, `..` goes up, `Get` reads it again], - addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS); #word("Plumb") adds rules of your own], + addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS): a plumbing rule's; #word("Plumb") opens your rules], ) #key("Enter") does the same from the keyboard; the other address forms are diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 0d287381..987f9f9b 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -41,6 +41,7 @@ tagexec a word clicked in the workspace tag @co 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 + <port> a port the rules name: read, the messages sent to it @plumber col/ the columns @columns-and-tags <n>/ column <n>; rmdir closes it when empty @columns-and-tags tag its tag @@ -1022,16 +1023,24 @@ 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 - read as its blank line comes, the rest at the close; `>` replaces them + 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 (refused there, it + is an `err` in the log alone; Plan 9's loses it); `>` 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`, @@ -1055,14 +1064,47 @@ yet (the #word("Plumb") rules do, #doc("reference", section: "from-acme")). `$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. +- Each port a rule has named this session has a file, + #file("/plumb/<port>") (0444), listed after `rules` and `send` in the + order the rules named them, never dropped. An open of it reads the + messages sent to that port from then on, one a read in the six lines' + form, a read that finds none held until one comes; every open gets its + own copy (`cat /plumb/edit` beside the editor sees every look it opens), + a message over its 64 KiB queue is not sent to it (an `err` in the log + says so). Messages sent before the open are not its. +- The ports pardes reads itself, whatever else reads them: `edit` (the + data opened as a #word("Look") opens it, at `addr=` when given; with + `action=showdata` the data itself shown, as acme's `plumb -i`, in the + pane `filename=` names, else a new clean one of that name, and with + `action=showdiff` then stacked in a +Diff in its place), `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 goes to its + readers; with none, its rule set's `start` runs (the message dropped), + or its `client`, the message held for the port's first reader (the + program it started, as a rule's `plumb client` means). To a port no + rule ever named it goes nowhere. +- `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); a diff paged into a +Pager, which the pager +sends to `edit` (`src` `pager`, `type` `text/x-diff`, `action=showdata` +and the +Pager's `filename`), made `showdiff`: stacked in a +Diff in the ++Pager's place. Text paged that is no diff is not sent: + +#raw(read("../../src/plumbing"), block: true) = Addons <addons> @@ -1401,7 +1443,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)], [#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))], ) |
