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
|
---
name: pardes
description: What the pardes editor is and how to use it, with a small cheatsheet (mouse, modes, keys, Look addresses, tags, sessions, config) and a map of its book. Use whenever the user mentions pardes, asks how to do something in it, wants a file opened or text paged in the editor, and to check whether you are running inside a pardes session ($PARDES_PID, $PARDES_9P, $PARDES_PANE, $PARDES_MOUNT) before acting on the user's editor. For scripting or driving a session through its 9P files, use pardes-9p.
---
# pardes
pardes is acme's idea (text is the interface: any word can be looked at or
run) with helix's modal keys, VT terminals and PDFs in panes. Two builtins
carry it: Look (right-click, B3, or Enter in normal mode) opens what the
text names (a file, `file:line`, a directory, a URL), else finds the word's
next place; Exec (middle-click, B2, or Tab) runs the builtin a word names,
else runs it as a shell line. Every session is also a virtual filesystem
served over 9P, so any program that opens files can script it (pardes-9p).
Paths below are relative to the pardes source tree, the repository this
skill lives in (`readlink -f` this skill's directory if it is reached
through a symlink).
## Am I in a pardes session?
Check this first: it decides whether "open it", "show me" or "run it"
can mean the user's editor. Every shell and command pane pardes starts
gets these, and every program started from it (an agent too) inherits them:
| Variable | |
|---|---|
| `PARDES_PID` | the session's pid (what `status` says) |
| `PARDES_9P` | the session's 9P socket |
| `PARDES_PANE` | the serial of the pane this shell runs in |
| `PARDES_MOUNT` | the session as a directory, only under `9ns --mntgen` or in a `Tty9p` shell |
| `winid` | the pane a command was clicked in (command panes only) |
A variable can outlive its session (a `--detach` session quit, a shell
moved under tmux), so check that it is live, not just set:
```sh
if [ -n "${PARDES_9P:-}" ] && [ -S "$PARDES_9P" ] && kill -0 "${PARDES_PID:-}" 2>/dev/null; then
echo "in pardes: session $PARDES_PID, pane $PARDES_PANE, mount ${PARDES_MOUNT:-none}"
else
echo "not in pardes"
fi
```
With a mount, `sed -n 1p "$PARDES_MOUNT/status"` answers `pid
$PARDES_PID`. Sessions listed under `$NINE_MOUNT/pardes/` are not proof:
that lists every running session, the user's included, whether or not you
run inside one. Not in a session: say so, and touch no session you merely
found there.
## Words
- **tag**: the editable line of words above the workspace, each column and
each pane. A pane's starts with its path. Any word runs from any tag.
- **serial**: a pane's number, never reused (`@p3:12`, `pane/3/`).
- **command pane**: a terminal running one command line; its tag ends in
`running`, then `exit N`.
- **`+` names**: panes pardes makes: `+New` (scratch), `+Search`, `+Pager`,
`+Errors`, `+Unsaved`, `+Diff`.
- **active column**: where the next new pane goes.
## Cheatsheet
| Mouse | |
|---|---|
| B1 | select; give the pane the keyboard |
| B2 | Exec the word or sweep |
| B3 | Look at the word or sweep |
| B1+B2 / B1+B3 / B1+B2+B3 | cut / paste / copy (chords) |
| B2+B1 | Exec with the B1 selection as argument |
| Alt-click / Super-click | B2 / B3 for one button |
| Modes (the box left of a tag) | |
|---|---|
| ` ` normal | helix keys: motions select, edits act on the selection |
| `^` insert | `i a o`…; Esc back to normal |
| `$` raw, terminals | keys go to the program; Ctrl-b toggles raw/normal |
| Esc in normal | back to the previous pane (unlike helix) |
| Keys pardes adds or changes | |
|---|---|
| `SPC ?` | Help: every builtin, its leader path and keys |
| `:` | to the pane's tag and back |
| `Ctrl-w h/j/k/l` | focus a neighbour |
| `Ctrl-o` / `Ctrl-i` | jump list back / forward |
| `Alt-n` / `Alt-c` | new terminal below / pane to a new column |
| `SPC f s`, `SPC d`, `SPC q` | Save, Del, Exit |
| `SPC f f`, `SPC f g`, `SPC f r` | Find, Grep, Recent |
| `12G`, `n` in a command pane | line 12; next `file:line` error |
| Look addresses (B3 or Enter) | |
|---|---|
| `file:12`, `file:12:5` | line, byte column |
| `file:/re/`, `file:0/re/` | next match, first match |
| `:40` | line 40 of the pane looked from |
| `@p3:12` | pane 3 by serial |
| `src/` | a directory pane |
Addresses are sam's (`#n /re/ ?re? $ a,b`).
| Common words | |
|---|---|
| `Save` `Del` `Get` `Undo` `Edit` | pane; Del/Exit/Restore refuse once over unsaved text, again discards |
| `New` `Term` `Term+bash` `Newcol` `Delcol` | panes and columns |
| `Find name` `Grep text` `Recent` | listings in a `+Search` |
| `Kill make` `Repl python` `Filter` `Mode` | terminals and commands |
| `Dump` `Restore` `Config` `DumpConfig` `Theme x` | workspace and settings |
## From a shell inside pardes
```sh
pardes notes.txt # open it in this session, return at once
pardes --wait notes.txt # return when its pane closes (EDITOR='pardes --wait')
git log | pardes - # page text into a +Pager
pardes --detach=work & # a session with no screen; --attach=work shows it
```
These act on the user's session: do them when asked. Anything more (read
panes, run commands, react to clicks) is the pardes-9p skill. Config is
`~/.config/pardes/init`, a builtin a line; keys are compiled in
(`src/config.zig`). `$NINE_MOUNT/agents`, where present, is cloud9's
read-only view of running coding agents.
## The book
`docs/typ/` holds it, one file a chapter, in reading order: `guide.typ`
(day to day), `setup.typ` (9ns, EDITOR, pager, language servers),
`cheatsheet.typ`, `scripting.typ`, `reference.typ` (every 9P file),
`themes.typ`, `building.typ`. `docs/typ/README` says how they build into
the A4 cheatsheet, the book and the website. In the editor: `Help`
(`SPC ?`) and `Tutor` (`SPC h t`).
|