3 plumb \- format of plumb messages and rules
8 The messages formed by the
10 library are formatted for transmission between
11 processes into textual form, using newlines to separate
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
18 structure, that is used in the plumbing rules.
19 The fields, in order, are:
24 application/service generating message
27 destination `port' for message
30 working directory (used if data is a file name)
33 form of the data, e.g.
37 attributes of the message, in
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)
44 number of bytes of data
49 At the moment, only textual data
54 All fields are optional, but
56 should usually be set since it describes the form of the data, and
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.
65 receives messages on its
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
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
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
85 character are commentary and are regarded as blank lines.
91 substitutes the contents of
93 for the line, much as in a C
95 statement. Unlike in C, the file name is not quoted.
98 is not an absolute path name, or one beginning
103 is looked for first in the directory in which the plumber is executing,
107 When a message is received by the
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)
116 field that specifies an existing port, in which case the message is emitted, unchanged, from there.
118 Patterns and actions all consist of three components: an
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.
128 The object in a pattern is the name of an element of the message, such as
134 which refers to the argument component of the current rule.
135 The object in an action is always the word
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,
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.
152 Append the argument, which must be a sequence of
154 pairs, to the list of attributes of the message.
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.)
164 If the text of the object is identical to the text of the argument,
168 If the text of the object
169 is the name of an existing directory, the rule matches and
172 to that directory name.
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
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.
186 The value of the object is set to the value of the argument.
191 verb has special properties that enable the rules to select which portion of the
192 data is to be sent to the destination.
196 rule requires that the entire text matches the regular expression.
197 If, however, the message has an attribute named
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
205 attribute (a number starting from 0) to indicate where in the textual data the user pointed.
207 When the message has a
212 rules extract the longest leftmost match to the regular expression that contains or
213 abuts the textual location identified by the
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
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:
221 data matches '[a-zA-Z0-9_\-./]+'
222 data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)'
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,
227 If only the second pattern were present, a piece of text
229 could be misinterpreted as an image file named
234 attribute is specified in a message, it will be deleted by the
236 before sending the message if the
239 rules expand the selection.
241 The action rules all have the object
243 There are only three verbs for action rules:
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
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.)
255 If no application has the port open, the arguments to a
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.
265 but the message is discarded.
270 rule should be specified in a rule set.
273 The arguments to all rules may contain quoted strings, exactly as in
275 They may also contain simple string variables, identified by a leading dollar sign
277 Variables may be set, between rule sets, by assignment statements in the style of
279 Only one variable assignment may appear on a line.
282 also maintains some built-in variables:
287 The text that matched the entire regular expression in a previous
293 etc. refer to text matching the first, second, etc. parenthesized subexpression.
296 The textual representation of the attributes of the message.
299 The contents of the data field of the message.
302 The directory name resulting from a successful
305 If no such rule has been applied, it is the string constructed
306 syntactically by interpreting
314 field of the message.
317 The file name resulting from a successful
320 If no such rule has been applied, it is the string constructed
321 syntactically by interpreting
329 field of the message.
334 field of the message.
339 field of the message.
342 The root directory of the Plan 9 tree
347 The following is a modest, representative file of plumbing rules.
349 # these are generally in order from most specific to least,
350 # since first rule that fires wins.
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-]+)*'
357 # image files go to page
359 data matches '[a-zA-Z0-9_\e-./]+'
360 data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)'
363 plumb start page -w $file
365 # URLs go to web browser
367 data matches $protocol://$domain$file
369 plumb start window webbrowser $0
371 # existing files, possibly tagged by line number, go to edit/sam
373 data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?'
378 plumb start window sam $file
380 # .h files are looked up in /sys/include and passed to edit/sam
382 data matches '([a-zA-Z0-9]+\e.h)('$addr')?'
383 arg isfile /sys/include/$1
387 plumb start window sam $file
390 The following simple plumbing rules file is a good beginning set of rules.
392 # to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules
399 .TF $HOME/lib/plumbing
401 .B $HOME/lib/plumbing
413 .B \*9/plumb/fileaddr
414 public macro definitions.
