1 058b0118 2005-01-03 devnull .TH PLUMB 7
3 058b0118 2005-01-03 devnull plumb \- format of plumb messages and rules
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .B #include <plumb.h>
6 058b0118 2005-01-03 devnull .SH DESCRIPTION
7 058b0118 2005-01-03 devnull .SS "Message format
8 058b0118 2005-01-03 devnull The messages formed by the
10 058b0118 2005-01-03 devnull library are formatted for transmission between
11 058b0118 2005-01-03 devnull processes into textual form, using newlines to separate
12 058b0118 2005-01-03 devnull the fields.
13 058b0118 2005-01-03 devnull Only the data field may contain embedded newlines.
14 058b0118 2005-01-03 devnull The fields occur in a specified order,
15 058b0118 2005-01-03 devnull and each has a name, corresponding to the elements
17 058b0118 2005-01-03 devnull .B Plumbmsg
18 058b0118 2005-01-03 devnull structure, that is used in the plumbing rules.
19 058b0118 2005-01-03 devnull The fields, in order, are:
21 058b0118 2005-01-03 devnull .TF ndata
24 058b0118 2005-01-03 devnull application/service generating message
27 058b0118 2005-01-03 devnull destination `port' for message
30 058b0118 2005-01-03 devnull working directory (used if data is a file name)
33 058b0118 2005-01-03 devnull form of the data, e.g.
37 058b0118 2005-01-03 devnull attributes of the message, in
38 058b0118 2005-01-03 devnull .IB name = value
39 058b0118 2005-01-03 devnull pairs separated by white space
40 058b0118 2005-01-03 devnull (the value must follow the usual quoting convention if it contains
41 058b0118 2005-01-03 devnull white space or quote characters or equal signs; it cannot contain a newline)
44 058b0118 2005-01-03 devnull number of bytes of data
47 058b0118 2005-01-03 devnull the data itself
49 058b0118 2005-01-03 devnull At the moment, only textual data
50 058b0118 2005-01-03 devnull .RB ( type=text )
51 058b0118 2005-01-03 devnull is supported.
54 058b0118 2005-01-03 devnull All fields are optional, but
56 058b0118 2005-01-03 devnull should usually be set since it describes the form of the data, and
58 058b0118 2005-01-03 devnull must be an accurate count (possibly zero) of the number of bytes of data.
59 058b0118 2005-01-03 devnull A missing field is represented by an empty line.
60 058b0118 2005-01-03 devnull .SS "Plumbing rules
62 058b0118 2005-01-03 devnull .B plumber
64 d32deab1 2020-08-16 rsc .MR plumb (1) )
65 058b0118 2005-01-03 devnull receives messages on its
67 058b0118 2005-01-03 devnull port (applications
69 058b0118 2005-01-03 devnull messages there), interprets and reformats them, and (typically) emits them from a destination port.
70 058b0118 2005-01-03 devnull Its behavior is determined by a plumbing rules file, default
71 058b0118 2005-01-03 devnull .BR /usr/$user/lib/plumbing ,
72 058b0118 2005-01-03 devnull which defines a set of pattern/action rules with which to analyze, rewrite, and dispatch
73 058b0118 2005-01-03 devnull received messages.
75 058b0118 2005-01-03 devnull The file is a sequence of rule sets, each of which is a set of one-line rules
76 058b0118 2005-01-03 devnull called patterns and actions.
77 058b0118 2005-01-03 devnull There must be at least one pattern and one action in each rule set.
78 058b0118 2005-01-03 devnull (The only exception is that a rule set may contain nothing but
81 058b0118 2005-01-03 devnull rules; such a rule set declares the named ports but has no other effect.)
82 058b0118 2005-01-03 devnull A blank line terminates a rule set.
83 058b0118 2005-01-03 devnull Lines beginning with a
85 058b0118 2005-01-03 devnull character are commentary and are regarded as blank lines.
87 058b0118 2005-01-03 devnull A line of the form
89 058b0118 2005-01-03 devnull include \f2file\fP
91 058b0118 2005-01-03 devnull substitutes the contents of
93 058b0118 2005-01-03 devnull for the line, much as in a C
94 058b0118 2005-01-03 devnull .B #include
95 058b0118 2005-01-03 devnull statement. Unlike in C, the file name is not quoted.
98 058b0118 2005-01-03 devnull is not an absolute path name, or one beginning
101 058b0118 2005-01-03 devnull .BR ../ ,
103 058b0118 2005-01-03 devnull is looked for first in the directory in which the plumber is executing,
104 058b0118 2005-01-03 devnull and then in
105 058b0118 2005-01-03 devnull .BR /sys/lib/plumb .
107 058b0118 2005-01-03 devnull When a message is received by the
108 058b0118 2005-01-03 devnull .BR plumber ,
109 058b0118 2005-01-03 devnull the rule sets are examined in order.
110 058b0118 2005-01-03 devnull For each rule set, if the message matches all the patterns in the rule set,
111 058b0118 2005-01-03 devnull the actions associated with the rule set are triggered to dispose of the message.
112 058b0118 2005-01-03 devnull If a rule set is triggered, the rest are ignored for this message.
113 058b0118 2005-01-03 devnull If none is triggered, the message is discarded (giving a write error to the sender)
114 058b0118 2005-01-03 devnull unless it has a
116 058b0118 2005-01-03 devnull field that specifies an existing port, in which case the message is emitted, unchanged, from there.
118 058b0118 2005-01-03 devnull Patterns and actions all consist of three components: an
119 058b0118 2005-01-03 devnull .IR object ,
121 058b0118 2005-01-03 devnull .IR verb ,
122 058b0118 2005-01-03 devnull and arguments.
123 058b0118 2005-01-03 devnull These are separated by white space on the line.
124 058b0118 2005-01-03 devnull The arguments may contain quoted strings and variable substitutions,
125 058b0118 2005-01-03 devnull described below, and in some cases contain multiple words.
126 058b0118 2005-01-03 devnull The object and verb are single words from a pre-defined set.
128 058b0118 2005-01-03 devnull The object in a pattern is the name of an element of the message, such as
131 058b0118 2005-01-03 devnull .BR data ,
132 058b0118 2005-01-03 devnull or the special case
133 058b0118 2005-01-03 devnull .BR arg ,
134 058b0118 2005-01-03 devnull which refers to the argument component of the current rule.
135 058b0118 2005-01-03 devnull The object in an action is always the word
136 058b0118 2005-01-03 devnull .BR plumb .
138 058b0118 2005-01-03 devnull The verbs in the pattern rules
139 058b0118 2005-01-03 devnull describe how the objects and arguments are to be interpreted.
140 058b0118 2005-01-03 devnull Within a rule set, the patterns are evaluated in sequence; if one fails,
141 058b0118 2005-01-03 devnull the rule set fails.
142 058b0118 2005-01-03 devnull Some verbs are predicates that check properties of the message; others rewrite
143 058b0118 2005-01-03 devnull components of the message and implicitly always succeed.
144 058b0118 2005-01-03 devnull Such rewritings are permanent, so rules that specify them should be placed after
145 058b0118 2005-01-03 devnull all pattern-matching rules in the rule set.
147 058b0118 2005-01-03 devnull .TF delete
150 058b0118 2005-01-03 devnull The object must be
151 058b0118 2005-01-03 devnull .BR attr .
152 058b0118 2005-01-03 devnull Append the argument, which must be a sequence of
153 058b0118 2005-01-03 devnull .IB name = value
154 058b0118 2005-01-03 devnull pairs, to the list of attributes of the message.
156 058b0118 2005-01-03 devnull .B delete
157 058b0118 2005-01-03 devnull The object must be
158 058b0118 2005-01-03 devnull .BR attr .
159 058b0118 2005-01-03 devnull If the message has an attribute whose name is the argument,
160 058b0118 2005-01-03 devnull delete it from the list of attributes of the message.
161 058b0118 2005-01-03 devnull (Even if the message does not, the rule matches the message.)
164 058b0118 2005-01-03 devnull If the text of the object is identical to the text of the argument,
165 058b0118 2005-01-03 devnull the rule matches.
167 058b0118 2005-01-03 devnull .B isdir
168 058b0118 2005-01-03 devnull If the text of the object
169 058b0118 2005-01-03 devnull is the name of an existing directory, the rule matches and
170 058b0118 2005-01-03 devnull sets the variable
172 058b0118 2005-01-03 devnull to that directory name.
174 058b0118 2005-01-03 devnull .B isfile
175 058b0118 2005-01-03 devnull If the text of the object is the name of an existing file (not a directory),
176 058b0118 2005-01-03 devnull the rule matches and sets the variable
177 058b0118 2005-01-03 devnull .B $file
178 058b0118 2005-01-03 devnull to that file name.
180 058b0118 2005-01-03 devnull .B matches
181 058b0118 2005-01-03 devnull If the entire text of the object matches the regular expression
182 058b0118 2005-01-03 devnull specified in the argument, the rule matches.
183 058b0118 2005-01-03 devnull This verb is described in more detail below.
186 058b0118 2005-01-03 devnull The value of the object is set to the value of the argument.
190 058b0118 2005-01-03 devnull .B matches
191 058b0118 2005-01-03 devnull verb has special properties that enable the rules to select which portion of the
192 058b0118 2005-01-03 devnull data is to be sent to the destination.
193 058b0118 2005-01-03 devnull By default, a
195 058b0118 2005-01-03 devnull .B matches
196 058b0118 2005-01-03 devnull rule requires that the entire text matches the regular expression.
197 058b0118 2005-01-03 devnull If, however, the message has an attribute named
198 058b0118 2005-01-03 devnull .BR click ,
199 058b0118 2005-01-03 devnull that reports that the message was produced by a mouse click within the
200 058b0118 2005-01-03 devnull text and that the regular expressions in the rule set should be used to
201 058b0118 2005-01-03 devnull identify what portion of the data the user intended.
202 058b0118 2005-01-03 devnull Typically, a program such as an editor will send a white-space delimited
203 058b0118 2005-01-03 devnull block of text containing the mouse click, using the value of the
204 058b0118 2005-01-03 devnull .B click
205 058b0118 2005-01-03 devnull attribute (a number starting from 0) to indicate where in the textual data the user pointed.
207 058b0118 2005-01-03 devnull When the message has a
208 058b0118 2005-01-03 devnull .B click
209 058b0118 2005-01-03 devnull attribute, the
211 058b0118 2005-01-03 devnull .B matches
212 058b0118 2005-01-03 devnull rules extract the longest leftmost match to the regular expression that contains or
213 058b0118 2005-01-03 devnull abuts the textual location identified by the
214 058b0118 2005-01-03 devnull .BR click .
215 058b0118 2005-01-03 devnull For a sequence of such rules within a given rule set, each regular expression, evaluated
216 058b0118 2005-01-03 devnull by this specification, must match the same subset of the data for the rule set to match
217 058b0118 2005-01-03 devnull the message.
218 058b0118 2005-01-03 devnull For example, here is a pair of patterns that identify a message whose data contains
219 058b0118 2005-01-03 devnull the name of an existing file with a conventional ending for an encoded picture file:
221 058b0118 2005-01-03 devnull data matches '[a-zA-Z0-9_\-./]+'
222 058b0118 2005-01-03 devnull data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)'
224 058b0118 2005-01-03 devnull The first expression extracts the largest subset of the data around the click that contains
225 058b0118 2005-01-03 devnull file name characters; the second sees if it ends with, for example,
226 058b0118 2005-01-03 devnull .BR \&.jpeg .
227 058b0118 2005-01-03 devnull If only the second pattern were present, a piece of text
228 058b0118 2005-01-03 devnull .B horse.gift
229 058b0118 2005-01-03 devnull could be misinterpreted as an image file named
230 058b0118 2005-01-03 devnull .BR horse.gif .
233 058b0118 2005-01-03 devnull .B click
234 058b0118 2005-01-03 devnull attribute is specified in a message, it will be deleted by the
235 058b0118 2005-01-03 devnull .B plumber
236 058b0118 2005-01-03 devnull before sending the message if the
238 058b0118 2005-01-03 devnull .B matches
239 058b0118 2005-01-03 devnull rules expand the selection.
241 058b0118 2005-01-03 devnull The action rules all have the object
242 058b0118 2005-01-03 devnull .BR plumb .
243 058b0118 2005-01-03 devnull There are only three verbs for action rules:
245 058b0118 2005-01-03 devnull .TF client
248 058b0118 2005-01-03 devnull The argument is the name of the port to which the message will be sent.
249 058b0118 2005-01-03 devnull If the message has a destination specified, it must match the
251 058b0118 2005-01-03 devnull port of the rule set or the entire rule set will be skipped.
252 058b0118 2005-01-03 devnull (This is the only rule that is evaluated out of order.)
254 058b0118 2005-01-03 devnull .B client
255 058b0118 2005-01-03 devnull If no application has the port open, the arguments to a
256 058b0118 2005-01-03 devnull .B plumb
257 e2a141ae 2023-01-23 crossd .B client
258 058b0118 2005-01-03 devnull rule specify a shell program to run in response to the message.
259 058b0118 2005-01-03 devnull The message will be held, with the supposition that the program
260 058b0118 2005-01-03 devnull will eventually open the port to retrieve it.
262 058b0118 2005-01-03 devnull .B start
264 058b0118 2005-01-03 devnull .BR client ,
265 058b0118 2005-01-03 devnull but the message is discarded.
266 058b0118 2005-01-03 devnull Only one
267 058b0118 2005-01-03 devnull .B start
269 058b0118 2005-01-03 devnull .B client
270 058b0118 2005-01-03 devnull rule should be specified in a rule set.
273 058b0118 2005-01-03 devnull The arguments to all rules may contain quoted strings, exactly as in
274 d32deab1 2020-08-16 rsc .MR rc (1) .
275 058b0118 2005-01-03 devnull They may also contain simple string variables, identified by a leading dollar sign
277 058b0118 2005-01-03 devnull Variables may be set, between rule sets, by assignment statements in the style of
278 058b0118 2005-01-03 devnull .BR rc .
279 058b0118 2005-01-03 devnull Only one variable assignment may appear on a line.
281 058b0118 2005-01-03 devnull .B plumber
282 058b0118 2005-01-03 devnull also maintains some built-in variables:
284 058b0118 2005-01-03 devnull .TF $wdir
287 058b0118 2005-01-03 devnull The text that matched the entire regular expression in a previous
289 058b0118 2005-01-03 devnull .B matches
291 058b0118 2005-01-03 devnull .BR $1 ,
292 058b0118 2005-01-03 devnull .BR $2 ,
293 058b0118 2005-01-03 devnull etc. refer to text matching the first, second, etc. parenthesized subexpression.
295 058b0118 2005-01-03 devnull .B $attr
296 058b0118 2005-01-03 devnull The textual representation of the attributes of the message.
298 058b0118 2005-01-03 devnull .B $data
299 058b0118 2005-01-03 devnull The contents of the data field of the message.
302 058b0118 2005-01-03 devnull The directory name resulting from a successful
303 058b0118 2005-01-03 devnull .B isdir
305 058b0118 2005-01-03 devnull If no such rule has been applied, it is the string constructed
306 058b0118 2005-01-03 devnull syntactically by interpreting
308 058b0118 2005-01-03 devnull as a file name in
309 058b0118 2005-01-03 devnull .BR wdir .
312 058b0118 2005-01-03 devnull The contents of the
314 058b0118 2005-01-03 devnull field of the message.
316 058b0118 2005-01-03 devnull .B $file
317 058b0118 2005-01-03 devnull The file name resulting from a successful
318 058b0118 2005-01-03 devnull .B isfile
320 058b0118 2005-01-03 devnull If no such rule has been applied, it is the string constructed
321 058b0118 2005-01-03 devnull syntactically by interpreting
323 058b0118 2005-01-03 devnull as a file name in
324 058b0118 2005-01-03 devnull .BR wdir .
326 058b0118 2005-01-03 devnull .B $type
327 058b0118 2005-01-03 devnull The contents of the
329 058b0118 2005-01-03 devnull field of the message.
332 058b0118 2005-01-03 devnull The contents of the
334 058b0118 2005-01-03 devnull field of the message.
336 058b0118 2005-01-03 devnull .B $wdir
337 058b0118 2005-01-03 devnull The contents of the
339 058b0118 2005-01-03 devnull field of the message.
341 4de03b54 2005-01-11 devnull .B $plan9
342 4de03b54 2005-01-11 devnull The root directory of the Plan 9 tree
344 d32deab1 2020-08-16 rsc .MR get9root (3) ).
346 058b0118 2005-01-03 devnull .SH EXAMPLE
347 058b0118 2005-01-03 devnull The following is a modest, representative file of plumbing rules.
349 058b0118 2005-01-03 devnull # these are generally in order from most specific to least,
350 058b0118 2005-01-03 devnull # since first rule that fires wins.
352 058b0118 2005-01-03 devnull addr=':(#?[0-9]+)'
353 058b0118 2005-01-03 devnull protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)'
354 058b0118 2005-01-03 devnull domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\e-]+'
355 058b0118 2005-01-03 devnull file='([:.][a-zA-Z0-9_?,%#~&/\e-]+)*'
357 058b0118 2005-01-03 devnull # image files go to page
358 058b0118 2005-01-03 devnull type is text
359 058b0118 2005-01-03 devnull data matches '[a-zA-Z0-9_\e-./]+'
360 058b0118 2005-01-03 devnull data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)'
361 058b0118 2005-01-03 devnull arg isfile $0
362 058b0118 2005-01-03 devnull plumb to image
363 058b0118 2005-01-03 devnull plumb start page -w $file
365 058b0118 2005-01-03 devnull # URLs go to web browser
366 058b0118 2005-01-03 devnull type is text
367 058b0118 2005-01-03 devnull data matches $protocol://$domain$file
368 058b0118 2005-01-03 devnull plumb to web
369 058b0118 2005-01-03 devnull plumb start window webbrowser $0
371 058b0118 2005-01-03 devnull # existing files, possibly tagged by line number, go to edit/sam
372 058b0118 2005-01-03 devnull type is text
373 058b0118 2005-01-03 devnull data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?'
374 058b0118 2005-01-03 devnull arg isfile $1
375 058b0118 2005-01-03 devnull data set $file
376 058b0118 2005-01-03 devnull attr add addr=$3
377 058b0118 2005-01-03 devnull plumb to edit
378 058b0118 2005-01-03 devnull plumb start window sam $file
380 058b0118 2005-01-03 devnull # .h files are looked up in /sys/include and passed to edit/sam
381 058b0118 2005-01-03 devnull type is text
382 058b0118 2005-01-03 devnull data matches '([a-zA-Z0-9]+\e.h)('$addr')?'
383 058b0118 2005-01-03 devnull arg isfile /sys/include/$1
384 058b0118 2005-01-03 devnull data set $file
385 058b0118 2005-01-03 devnull attr add addr=$3
386 058b0118 2005-01-03 devnull plumb to edit
387 058b0118 2005-01-03 devnull plumb start window sam $file
390 058b0118 2005-01-03 devnull The following simple plumbing rules file is a good beginning set of rules.
392 058b0118 2005-01-03 devnull # to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules
394 058b0118 2005-01-03 devnull editor = acme
395 058b0118 2005-01-03 devnull # or editor = sam
396 058b0118 2005-01-03 devnull include basic
398 058b0118 2005-01-03 devnull .SH FILES
399 c8b6342d 2005-01-13 devnull .TF $HOME/lib/plumbing
401 c8b6342d 2005-01-13 devnull .B $HOME/lib/plumbing
402 058b0118 2005-01-03 devnull default rules file.
404 c8b6342d 2005-01-13 devnull .B plumb
405 c8b6342d 2005-01-13 devnull service name for
406 d32deab1 2020-08-16 rsc .MR plumber (4) .
408 c8b6342d 2005-01-13 devnull .B \*9/plumb
409 058b0118 2005-01-03 devnull directory for
410 058b0118 2005-01-03 devnull .B include
413 c8b6342d 2005-01-13 devnull .B \*9/plumb/fileaddr
414 058b0118 2005-01-03 devnull public macro definitions.
416 c8b6342d 2005-01-13 devnull .B \*9/plumb/basic
417 058b0118 2005-01-03 devnull basic rule set.
418 058b0118 2005-01-03 devnull .SH "SEE ALSO"
419 d32deab1 2020-08-16 rsc .MR plumb (1) ,
420 d32deab1 2020-08-16 rsc .MR plumb (3) ,
421 d32deab1 2020-08-16 rsc .MR plumber (4) ,
422 d32deab1 2020-08-16 rsc .MR regexp (7)
