kate-deft/docs/PLUMBING.md

Plumbing — configuring ~/lib/plumbing for Kate

Kate is a full plan9port plumb client: it sends plumb messages (plumb a token under the caret) and receives them on the edit port (open a file at a line, or a directory as a folder). The routing — what a plumbed string means — lives in the plumber's rules, not in Kate. This document covers the user-side rules in ~/lib/plumbing that make files and directories open in Kate.

The implementation (the native 9P client, the edit-port reader, and the in-process handler) lives in src/plumb/ — plumb_lib is the pure codec/9P client and plumbplugin.{h,cpp} is the Kate glue.

How plumbing reaches Kate

plumb <text>                         # or Kate's F2 on the caret token
   │
   ▼
plumber  ── applies ~/lib/plumbing rules ──►  routes to a PORT
   │
   ▼  (edit port)
Kate's reader thread  ──►  onPlumbEdit()  ──►  open file@line / open folder

• The plumber matches the message against rules top to bottom; first match wins.
• A rule routes to a port (plumb to edit, plumb to web, …). The edit port is where editors listen.
• plumb client <prog> / plumb start <prog> name what to run if no application currently holds that port. A ruleset may contain only one client/start action.
  • client — the started program is expected to open the port itself; the message is then delivered through the port. acme and Kate both work this way (Kate via its edit-port reader).
  • start — just runs the program with the given arguments.

Make Kate the editor

Set the editor variable near the top of ~/lib/plumbing:

editor = /usr/bin/kate

Every file rule ends with plumb to edit + plumb client $editor, so this alone makes files open in Kate:

• If Kate is already running, its reader holds the edit port and receives the message directly.
• If nothing holds edit, the plumber cold-starts /usr/bin/kate; once its reader attaches, the message is delivered.

The line/column travels in the message as an addr attribute (e.g. addr=42), not as a command-line argument. plumb client delivers it through the port, and Kate's handler jumps to it — so foo.c:42 opens foo.c at line 42.

The edit port is single-consumer. If acme and Kate run at the same time, whichever holds edit wins; you cannot have both receive plumbed files. With editor = /usr/bin/kate, Kate is the one cold-started and holding the port.

Open a directory as a folder

The stock basic rules only match regular files (arg isfile), so a bare directory path fails with "couldn't find destination for message." Add a directory rule. Place it before the generic file rules (those use isfile, which fails on a directory, so ordering is not strictly required, but keeping it with the other specific rules is clearest):

# any existing directory opens as a folder in Kate
type is text
data matches '[a-zA-Z¡-￿0-9_\-./@~]+'
arg isdir	$0
data set	$dir
plumb to edit
plumb start kate $dir

• arg isdir $0 succeeds only for an existing directory and sets $dir.
• data set $dir makes the directory path the message payload.
• plumb to edit delivers to Kate's reader when it is running (the in-process handler opens the folder; start does not fire).
• plumb start kate $dir cold-starts Kate on the directory when nothing holds edit. Kate registers inode/directory in its desktop entry and opens a directory as a folder.

Note the one-client/start-per-ruleset limit: this rule uses start (not both client and start), which covers running and cold-start cases together.

Apply changes to a running plumber

Rules reload without restarting the plumber:

cat ~/lib/plumbing | 9p write plumb/rules

A malformed ruleset is rejected whole (the write fails with an error such as ruleset has more than one client or start action); the previous rules stay in effect until a valid file is written.

Quick verification

# a file (should route to the edit port, carrying addr=3)
plumb /path/to/file:3

# a directory (should route to the edit port, data = the dir)
plumb /path/to/dir

To watch what a plumb actually delivers, read the edit port in another shell:

9p read plumb/edit        # prints the message: src/dst/wdir/type/attr/ndata/data

A successful file message looks like:

plumb
edit
<wdir>
text
addr=3
15
/path/to/file

and a directory message has an empty attr line and data = /path/to/dir.

Troubleshooting

Symptom	Cause	Fix
plumb: can't send message: couldn't find destination	no rule matched (e.g. a directory with only isfile rules)	add the directory rule above
files open in acme, not Kate	editor still points at acme	set editor = /usr/bin/kate and reload
9p write plumb/rules fails	malformed rule, or two client/start actions in one ruleset	keep a single client/start per rule; fix the reported line
directory plumb starts Kate but no folder	Kate build without inode/directory handling	verify kate /some/dir opens the folder from a shell