1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
pardes: an editor, a terminal multiplexer, and the file tree that scripts both.
Usage:
pardes [flags] [FILE[:LINE] | DIR | -] open, start a session, or page stdin
pardes COMMAND [ARGS] [-s NAME] a file named like a command: pardes ./ps
Open:
FILE[:LINE] open it; in a pane, in that pane's session
-w, --wait FILE open it, return when its pane closes (EDITOR='pardes -w')
- stdin into a +Pager, its colours kept
DIR start in it
Sessions:
ps the daemon's sessions, their clients and shells
attach [NAME] show a detached session here (HOST:NAME: over ssh)
kill NAME end a session and its shells (--all: every one)
new [flags] [FILE] start one: --detach=NAME --9p=NAME -n 3 (help new)
Words:
do WORD [ARG] run a builtin at this pane, or the session's: do Newcol
words [GROUP] the builtins by group, or one group's: words column
Files:
fs VERB [PATH] ls read write ask follow stat help complete, on the session's tree
Self:
help [CMD|WORD|PATH] this, a command, a builtin, or a file of the tree
completion SHELL bash, fish or zsh
skill the guide an agent reads
version this build, its session wire and its 9P
Flags:
-s, --session NAME the session to act on ($PARDES_9P, else the only one)
-p N the pane, for do ($PARDES_PANE)
The old spellings --ps, --attach[=NAME], --kill=NAME, --kill-all, -h and
--version still work, for a release.
== pardes help ps
What the per-user daemon keeps: each session with its name, pid, kind
(tty or gui) and whether one is attached; under it its clients and its
shells; then the shells no session holds, which Adopt takes. /sessions
is the same list, read from inside a session.
Usage:
pardes ps
Examples:
pardes ps every session, client and shell
See also: attach, kill, /sessions
== pardes help attach
Show a detached session here: in this terminal for pardes, a window
for pardes-gui. Bare, the one detached session (with none, the one
session). One attached already, or of the other kind, is joined as a
client. HOST:NAME is a client of session NAME on another machine,
over `ssh -L` to its pardes-replica.sock ($PARDES_SSH: the ssh
command, default ssh; $PARDES_REMOTE_RUNTIME: its runtime directory,
if not this one's path); SOCK:NAME goes through a socket forwarded
already (a path, with a '/'). Returns when the session detaches or
ends.
Usage:
pardes attach [NAME]
Examples:
pardes attach the one detached session
pardes attach notes the one started with --detach=notes
pardes attach box:notes on host box, over ssh -L
pardes attach /run/x.sock:notes through a socket forwarded already
See also: ps, kill, new --detach, the Detach word
== pardes help kill
End session NAME (its --9p or --detach name, else its pid) and its
shells: TERM, then KILL 2 s later. Unsaved changes are lost. --all
ends every session and every shell the daemon keeps.
Usage:
pardes kill NAME
Examples:
pardes kill notes the session started with --detach=notes
pardes kill --all every session and shell
See also: ps, attach
== pardes help new
Start a session here, even in a pane of another: in this terminal for
pardes, a window for pardes-gui, or with --detach none until one
attaches. Bare `pardes` takes the same flags, and starts one unless
it is in a pane (where it hands its FILE to that session).
Usage:
pardes new [flags] [FILE]
Flags:
--tty start as one shell pane already in tty mode
-n COUNT shell panes to start with: 1 (default) or 3 (classic); a FILE boots just that file
--tty-toggle KEY Ctrl-KEY toggles tty and editor mode
-l DUMP load a dump of another instance (see Dump)
--nested a session of its own in a pane of another, serving none of its children
--9p=NAME name the 9P socket (else the --detach name, else the pid); under $XDG_RUNTIME_DIR, else ~/.local/state/pardes: a directory of yours alone
--9p-tcp=tcp!IP!PORT also serve 9P there, a numeric address
--mount=NAME=DIAL a 9P session or Unix/TCP endpoint under /n/NAME; repeat for more; os and self are reserved
--geometry=WxH[+X+Y] the window's size in points, and where it goes where the display lets a window say (X11)
--detach[=NAME] no terminal (no window) until one attaches; panes, shells and files stay; NAME (one path component) rather than the pid. One pardes --daemon per user keeps sessions (PARDES_DAEMON=off: none)
-w, --wait in a pane, hand FILE to its session and return once its pane is deleted: 0, or 1 if the session goes (EDITOR='pardes --wait')
-- the end of the flags: pardes -- -name opens -name
Examples:
pardes new a session here, its shell pane in tty mode
pardes new --detach=notes one with no terminal, named notes
pardes new -n 3 src/ three shell panes in src/
pardes new --mount=peer=notes with session notes under /n/peer
See also: attach, kill, --nested
== pardes help do
Write WORD and its ARG to the ctl that takes it, as the session's
/commands says: the root's /ctl for a session's word, a pane's
pane/N/ctl for a pane's, that pane being this shell's ($PARDES_PANE)
or -p N. A refusal prints the session's own words, and the exit is 1.
The session is -s NAME, else $PARDES_9P, else the only one running.
Usage:
pardes do WORD [ARG]
Examples:
pardes do Newcol an empty column
pardes do Save -p 3 save pane 3
pardes do Edit ',x/foo/c/bar/' -p 3 sam's Edit on pane 3
pardes do Wrap -s notes at session notes
See also: words, help WORD, /commands
== pardes help words
The session's builtins, as its /commands lists them, grouped by the
first key after the leader (SPC f is file, SPC c column): with no key,
a setting, a session's word (its root ctl's) or a text word (a
pane's). An addon's words are the addon group. With no session, the
ones this build has.
Usage:
pardes words [GROUP]
Examples:
pardes words every builtin, by group
pardes words column the column words
See also: do, help WORD, /commands
== pardes help fs
The session's file tree, through a 9P client in this binary: the
files a mount or 9p(1) reaches, with a refusal in the session's own
words (a mount says only EINVAL). With no session, ls, stat, help and
complete, and a read of README, commands or ctl, ask a core made in
this process; the rest are a running session's, and say so.
Usage:
pardes fs VERB [PATH]
usage: fs ls [PATH] the names in a directory, a / after each directory
fs read PATH the file, to its end (a held read streams)
fs write PATH [WORDS...] the words and a newline, else stdin, as > would
fs ask PATH WORDS... write the words and read the answer on the same open
fs follow PATH [WORDS...] ask, or read: what comes, as it comes, for as long
fs stat PATH mode length uid gid mtime name
fs help [PATH] what the tree's README says of PATH
fs complete [PREFIX] the paths that go on from PREFIX, for a shell
Examples:
pardes fs ls pane/1 what a pane serves
pardes fs read index a line per pane
pardes fs write pane/3/ctl 'Edit ,x/foo/c/bar/' a write, refused in words
pardes fs ask pane/3/pty/run make exit N, then the output
pardes fs follow log follow events as they come
See also: help PATH, /README
== pardes help help
Bare, this map. A command: what it does, with examples. A builtin:
its /commands line, its key, and how to run it. A path of the tree:
what the tree's README says of it and of what is under it. --all:
every command's help and the README whole, as this build has them
(never a session's), which the reference prints.
Usage:
pardes help [CMD|WORD|PATH]
Examples:
pardes help attach a command
pardes help Newcol a builtin
pardes help pane/3/addr a file of the tree
See also: words, fs help
== pardes help completion
A completion script for SHELL, printed, never installed. It asks this
binary back for each word (`pardes completion -- WORDS`): commands,
the builtins after do, sessions after attach and kill, the tree's
paths after fs.
Usage:
pardes completion SHELL
Examples:
pardes completion fish | source in fish, for this shell
source <(pardes completion bash) in bash
source <(pardes completion zsh) in zsh
== pardes help skill
The guide for an agent that drives pardes, from this binary, so it
matches what it runs: recipes and traps. What is there it leaves to
`pardes help`.
Usage:
pardes skill
Examples:
pardes skill
== pardes help version
This build's version; the semantics a replica must share with its
session; the 9P its tree speaks.
Usage:
pardes version
Examples:
pardes version
== the old spellings
--attach[=NAME] pardes attach NAME
--ps pardes ps
--kill=NAME pardes kill NAME
--kill-all pardes kill --all
-h, --help pardes help
--version pardes version
== pardes help /: the tree's README
Pardes virtual filesystem
=========================
README this summary; the pardes book's Scripting and Reference chapters have the rest
index a line per pane: serial kind(text|term|cmd|pdf|image|an addon's) dirty name column; names hold blanks: rsplit(maxsplit=1)
status pid, version and pane count
look write a line: a right click on it at the pane with the keyboard; read: the serials it touched (this open's)
exec write a line: a middle click, a builtin or a shell line; read the same (every exec file)
pager write a directory: its one +Pager, made or emptied; read the same open: its serial (pardes -)
log events: new del rename save newcol delcol run exit send ask answer changed dump restore restored restoredcol msg err
screen the rendered screen as JSON, frozen from open to close
listeners the session's dial addresses
sessions the pardes daemon's, as pardes --ps: daemon <pid>; session <pid> tty|gui attached|detached <name>; shell <pid>; orphan <pid>
focus the serial of the pane with the keyboard (empty on a column tag); write one to give it the keyboard
kbdin write runes: keys typed at the pane with the keyboard, done before the write answers (\x1b Esc, \n Enter)
mousein write `m col row buttons` (1 left, 2 middle, 4 right): the mouse as it now is; m 10 5 4, m 10 5 0 is a right click
ctl settings a line; or Newcol, Dump [export f], Restore [label|f], Exit (refuses once over unsaved panes), Kill [w], size C R
commands every builtin: word, arg, root|pane|both (the ctl that takes it), -- what it does; addons: the kinds of pane here
recent files opened lately, closed ones too: open|closed <path>
dumps the dumps the state file keeps, the newest first: <label> <date> <size> <panes>
layout a line per column: serial index x width current|notcurrent empty|full pane-serials; then active <serial>
tag the workspace tag, tagexec a word as a click in it; col/<serial>/ a column's tag, ctl, exec; rmdir: empty only
plumb/ rules: the plumber's rules, plumb(6)'s (a write adds rule sets, > replaces); send: write a message, six lines then data; <port>: read the messages sent to it
pane/new open it to make a pane (<session dir>/+New) in the active column; the read answers its serial
pane/<n>/ name body tag ctl addr dot limit data xdata sel dirty mark scroll errors event look exec tagexec rows; rmdir closes
rows: a line a row, kind (m c p; d decl, u unmarked) line col end_line end_col source_column location_end code_start styles path; styles - or N:start+len=role,... (keyword string number comment, add del emph line, joined by .); a write at 0 replaces
on terminals pty/data (keys in, output out), pty/status, pty/ctl (winsize, sig, exec), pty/run (a line, its exit and output)
os/ the host filesystem
$m below: $PARDES_MOUNT (set under 9ns --mntgen); without it, 9p -a "unix!$PARDES_9P".
cat $m/index which panes exist
n=$(cat $m/pane/new) make a pane of your own (each open makes one), take its serial
exec 3<>$m/pane/$n/look; echo /etc/hosts:3 >&3; cat <&3 open a file through it, see the pane it went to
printf 'text\n' >> $m/pane/$n/body append to it (> replaces it all)
echo 'Msg hello' > $m/pane/$n/exec show text in the editor
echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl sam's Edit, one undo step; an x that matches nothing succeeds
echo /re/ > $m/pane/$n/addr; printf new > $m/pane/$n/data replace the next match
exec 3<>$m/log; echo follow >&3; cat <&3 what happened lately, then wait for more
exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3 exit N, then the output
Traps:
A refused write says only EINVAL or EIO; grep '^err' log | tail -1 says why (not the last line, maybe +Unsaved's new).
Root look and exec act at the pane with the keyboard, which another client may own: use a pane's own look and exec.
addr is the pane's and moves on: each /re/ searches from the last, a data write leaves it past the text.
Through a mount, printf 'a\nb\n' arrives a line a write: send a block with one write, ending in a newline.
Pane words (Save Undo Del) go to pane/<n>/ctl, settings and session words to /ctl.
Exit, Restore, Del and get refuse once over unsaved text; the same word again discards.
|