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