plumb.7 (10973B)
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 client 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)