diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
| commit | 6d8da8721141284cf33bb901168b26135893eb86 (patch) | |
| tree | 791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/typ/scripting.typ | |
| parent | efd43a3a2cf03bb741366331158b368abf9ac583 (diff) | |
| parent | bf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff) | |
| download | pardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz pardes-6d8da8721141284cf33bb901168b26135893eb86.zip | |
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/typ/scripting.typ')
| -rw-r--r-- | docs/typ/scripting.typ | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ new file mode 100644 index 00000000..590d71ac --- /dev/null +++ b/docs/typ/scripting.typ @@ -0,0 +1,162 @@ +// Scripting pardes over 9P: finding the session, a first tag word, the +// recipes, and the traps. Every file's full semantics are in the +// reference. +#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs + +Every session is a virtual filesystem, served over 9P and modelled on +acme's (#doc("reference", section: "from-acme")), so a program that opens +files is an extension: + +``` +$ ls $m +README col commands ctl exec focus index layout listeners log +look os pager pane recent screen status tag tagexec +$ cat $m/index +1 term 0 /home/me/src 1 +2 text 0 /home/me/src/+New 1 +``` + +The reference (#doc("fs")) has every file. + += Finding the session <find-the-session> + +#pairs( + [`PARDES_9P`], [the session's socket, in every shell and command pane], + [`PARDES_PANE`], [the serial of the pane the shell runs in], + [`$winid`], [the serial of the pane a command was clicked in, as in acme (unset from a column's or the workspace's tag)], + [`PARDES_MOUNT`], [the session as a directory, under `9ns --mntgen` (#doc("setup", section: "ninens"))], +) + +Every recipe here starts from this line: +#cmd("m=${PARDES_MOUNT:-}\ncat \"$m/index\"") +When it is empty (no mount), plan9port's `9p` talks to the socket instead: +`cat $m/x` is `9p -a "unix!$PARDES_9P" read x`, and `echo y > $m/x` is +`echo y | 9p -a "unix!$PARDES_9P" write x`. + += Your first tag word <first-tag-word> + +A script on `PATH` is a word you can click. This `Fmt` finds its pane +through `$winid` (`PARDES_PANE` is the command pane it runs in): + +```sh +#!/bin/sh +# Fmt: gofmt the Go file whose tag it was clicked in, then reload it +n=${winid:?Fmt: click me in a pane tag} +m=${PARDES_MOUNT:-} +if [ -n "$m" ]; then + rd() { cat "$m/$1"; }; wr() { cat > "$m/$1"; } +else + rd() { 9p -a "unix!$PARDES_9P" read "$1"; } + wr() { 9p -a "unix!$PARDES_9P" write "$1"; } +fi +f=$(rd pane/$n/name) # the file it shows +case $f in *.go) ;; *) echo "Fmt: $f is not Go" >&2; exit 1 ;; esac +echo Save | wr pane/$n/ctl && gofmt -w "$f" && echo get | wr pane/$n/ctl # get: reload +``` + +Type `Fmt` into a Go pane's tag and #word("Exec") it (middle-click: run +the builtin a word names, or else run it as a shell line); its output +shows in a command pane. To have `Fmt` in every Go file's tag, follow the +log and add it to each new `.go` pane (with a mount): + +```sh +#!/bin/sh +# fmt-tags: put Fmt in the tag of every Go file opened from now on +m=${PARDES_MOUNT:?fmt-tags: needs 9ns --mntgen} +exec 3<>$m/log; echo 'follow new' >&3 +while read -r what serial name <&3; do + case $what:$name in new:*.go) printf ' Fmt' >> $m/pane/$serial/tag ;; esac +done +``` + += Recipes + +Each recipe starts after the session line above and this one, which makes +a pane of your own: reading #file("pane/new") makes a pane and answers its +serial, and `rmdir $p` closes it. Work through that pane's #file("look") +and #file("exec"), not the root's: +#cmd("n=$(cat $m/pane/new); p=$m/pane/$n") + +#pairs( + [look around], [#cmd("cat $m/index\ncat $m/layout\ncat $m/focus\ncat $m/commands")], + [open a file at a place], [#cmd("exec 3<>$p/look; echo \"$PWD/main.zig:120\" >&3; f=$(cat <&3); exec 3<&- # its pane\necho \"$PWD/main.zig:0/fn main/\" > $p/look # the first match")], + [fill, name, save, close], [#cmd("printf 'hello\\n' > $p/body # > replaces, >> appends\necho \"$PWD/notes.txt\" > $p/name\necho Save > $p/ctl\nrmdir $p")], + [say something], [#cmd("echo 'Msg hello' > $p/exec")], + [replace everywhere], [#cmd("echo 'Edit ,x/foo/c/bar/' > $p/ctl\ngrep -c foo $p/body # 0: none left")], + [insert after a match], [#cmd("echo 'Edit /old/a/ text/' > $p/ctl # from dot; one undo step")], + [replace one match], [#cmd("echo /old/ > $p/addr && printf new > $p/data")], + [delete line 3], [#cmd("echo 3 > $p/addr; : > $p/data")], + [select line 3, read it], [#cmd("echo 3 > $p/addr; cp $p/addr $p/dot; cat $p/sel")], + [run a command], [#cmd("exec 3<>$p/exec; echo \"cd '$PWD' && make test\" >&3; c=$(cat <&3) # its pane\nuntil grep -q ') exit ' $m/pane/$c/tag; do sleep 0.2; done\ncat $m/pane/$c/body; exec 3<&- # read it before letting go")], + [run at a prompt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nexec 3<>$m/pane/$t/pty/run; echo ls >&3; cat <&3; exec 3<&-")], + [type, interrupt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nprintf 'q' > $m/pane/$t/pty/data # \\r Enter, \\x03 Ctrl-C\necho 'sig INT' > $m/pane/$t/pty/ctl")], + [ask the language server], [#cmd("exec 3<>$p/look; echo \"$PWD/main.zig\" >&3; q=$m/pane/$(cat <&3); exec 3<&-\necho /myFunc/ > $q/addr; echo dot=addr > $q/ctl\necho Hover > $q/exec # also Rename new, Symbols")], + [follow what happens], [#cmd("exec 3<>$m/log; echo 'follow new' >&3\ntimeout 30 cat <&3; exec 3<&-")], +) + +A command pane your #file("exec") open was answered is yours while that +open stays open: read its #file("body") before you close it. In +#file("index") a `term` is a shell, a `cmd` a command's pane. + +== Event helpers + +Holding a pane's #file("event") open takes its #word("Exec") and #word("Look") clicks (right-click: open what +the text names, or else find it): they arrive as acme's records instead of acting, and writing a +record back has pardes do it. A record is a line, `MX31 36 1 5 Upper`: who +(`M` mouse, `K` keyboard, `E` or `F` a write to a file), what (`X` #word("Exec") or `L` #word("Look") +in the body, `x` `l` in the tag), the range, a flag, the text's length and +the text (#doc("fs", section: "event")). This helper owns the tag words +`Upper` and `Done` in pane `$1` and writes every other click back: + +```bash +#!/bin/bash +# upper PANE: own the tag words Upper and Done in pane PANE +m=${PARDES_MOUNT:?upper: needs 9ns --mntgen}; p=$m/pane/$1 +grep -q ' Upper Done' $p/tag || printf ' Upper Done' >> $p/tag +exec 3<>$p/event # hold event on fd 3, this shell's own +while IFS= read -r rec <&3; do + read -r head q1 flag n text <<< "$rec" # e.g. Mx31 36 1 5 Upper + case $head$text in + [EFKM][Xx]*Upper) sel=$(cat $p/sel; echo x); sel=${sel%x}; printf %s "${sel^^}" > $p/sel ;; + [EFKM][Xx]*Done) break ;; + [EFKM][XxLl]*) printf '%s\n' "$rec" >&3 ;; # not ours: do what it would + esac # I D i d report edits: nothing to do +done +exec 3<&- # let event go: clicks act again +``` + += Traps <traps> + +- A refused write says only `Invalid argument` or `Input/output error`; + its reason is `grep '^err' $m/log | tail -1`, not the log's last line, + which after a refused #word("Del") may be `+Unsaved`'s `new`. A write that + succeeds adds no record, so check its status first. +- The root #file("look") and #file("exec") act at the pane with the + keyboard, which another client, an idle shell or an event helper may + own. Use a pane's own. +- Read #file("look"), #file("exec") or #file("pager") on the open you + wrote (`exec 3<>…`): a fresh open reads the session's last answer, from + whichever client wrote it. +- #file("addr") is the pane's and moves on: each `/re/` searches from the + last address, and a #file("data") write leaves it past the text. Write + #file("addr") before each replacement; a failed one leaves none. +- An #word("Edit") `x` that matches nothing succeeds: check the text. +- Through a mount, `printf 'a\nb\n' > ctl` arrives one write per line: + send a block as one write, ending in a newline. +- Read #file("event") on a descriptor your shell owns, never + `cat $p/event | while read`: the `cat` outlives the loop, holds + #file("event") and swallows the next click. +- `head` through 9ns says `Illegal seek` on #file("index"), + #file("layout"), #file("log") and #file("recent"): use `sed -n 1p`. + += An isolated session + +Never experiment on a session someone is using. Under `9ns --mntgen`, +start one with an empty environment and home, and quit it when done: + +``` +env -i PATH="$PATH" HOME="$(mktemp -d)" XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" pardes --detach=try & +m=$NINE_MOUNT/pardes/try +cat $m/index +echo Exit > $m/exec +``` |
