| <head> |
| <title>plumb(7) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>PLUMB(7)</b><td align=right><b>PLUMB(7)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| plumb – format of plumb messages and rules<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <plumb.h><br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <p><font size=+1><b>Message format </b></font><br> |
| The messages formed by the <a href="../man3/plumb.html"><i>plumb</i>(3)</a> library are formatted for |
| transmission between processes into textual form, using newlines |
| to separate the fields. Only the data field may contain embedded |
| newlines. The fields occur in a specified order, and each has |
| a name, corresponding to the elements of the <tt><font size=+1>Plumbmsg |
| </font></tt>structure, that is used in the plumbing rules. The fields, in |
| order, are:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>src</font></tt> application/service generating message<br> |
| <tt><font size=+1>dst</font></tt> destination ‘port’ for message<br> |
| <tt><font size=+1>wdir</font></tt> working directory (used if data is a file name)<br> |
| <tt><font size=+1>type</font></tt> form of the data, e.g. <tt><font size=+1>text<br> |
| attr</font></tt> attributes of the message, in <i>name</i><tt><font size=+1>=</font></tt><i>value</i> pairs separated by |
| white space (the value must follow the usual quoting convention |
| if it contains white space or quote characters or equal signs; |
| it cannot contain a newline)<br> |
| <tt><font size=+1>ndata</font></tt> number of bytes of data<br> |
| <tt><font size=+1>data</font></tt> the data itself<br> |
| |
| </table> |
| At the moment, only textual data (<tt><font size=+1>type=text</font></tt>) is supported. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| All fields are optional, but <tt><font size=+1>type</font></tt> should usually be set since |
| it describes the form of the data, and <tt><font size=+1>ndata</font></tt> must be an accurate |
| count (possibly zero) of the number of bytes of data. A missing |
| field is represented by an empty line.<br> |
| <p><font size=+1><b>Plumbing rules </b></font><br> |
| The <tt><font size=+1>plumber</font></tt> (see <a href="../man1/plumb.html"><i>plumb</i>(1)</a>) receives messages on its <tt><font size=+1>send</font></tt> port |
| (applications <i>send</i> messages there), interprets and reformats them, |
| and (typically) emits them from a destination port. Its behavior |
| is determined by a plumbing rules file, default <tt><font size=+1>/usr/$user/lib/plumbing</font></tt>, |
| which defines a set of pattern/action |
| rules with which to analyze, rewrite, and dispatch received messages. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The file is a sequence of rule sets, each of which is a set of |
| one-line rules called patterns and actions. There must be at least |
| one pattern and one action in each rule set. (The only exception |
| is that a rule set may contain nothing but <tt><font size=+1>plumb to</font></tt> rules; such |
| a rule set declares the named ports but has no other effect.) |
| A |
| blank line terminates a rule set. Lines beginning with a <tt><font size=+1>#</font></tt> character |
| are commentary and are regarded as blank lines. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A line of the form<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>include</font></tt> <i>file<br> |
| </i> |
| </table> |
| substitutes the contents of <i>file</i> for the line, much as in a C |
| <tt><font size=+1>#include</font></tt> statement. Unlike in C, the file name is not quoted. |
| If <i>file</i> is not an absolute path name, or one beginning <tt><font size=+1>./</font></tt> or <tt><font size=+1>../</font></tt>, |
| <i>file</i> is looked for first in the directory in which the plumber |
| is executing, and then in <tt><font size=+1>/sys/lib/plumb</font></tt>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| When a message is received by the <tt><font size=+1>plumber</font></tt>, the rule sets are examined |
| in order. For each rule set, if the message matches all the patterns |
| in the rule set, the actions associated with the rule set are |
| triggered to dispose of the message. If a rule set is triggered, |
| the rest are ignored for this message. If none is |
| triggered, the message is discarded (giving a write error to the |
| sender) unless it has a <tt><font size=+1>dst</font></tt> field that specifies an existing port, |
| in which case the message is emitted, unchanged, from there. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Patterns and actions all consist of three components: an <i>object</i>, |
| a <i>verb</i>, and arguments. These are separated by white space on the |
| line. The arguments may contain quoted strings and variable substitutions, |
| described below, and in some cases contain multiple words. The |
| object and verb are single words from a pre- |
| defined set. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The object in a pattern is the name of an element of the message, |
| such as <tt><font size=+1>src</font></tt> or <tt><font size=+1>data</font></tt>, or the special case <tt><font size=+1>arg</font></tt>, which refers to |
| the argument component of the current rule. The object in an action |
| is always the word <tt><font size=+1>plumb</font></tt>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The verbs in the pattern rules describe how the objects and arguments |
| are to be interpreted. Within a rule set, the patterns are evaluated |
| in sequence; if one fails, the rule set fails. Some verbs are |
| predicates that check properties of the message; others rewrite |
| components of the message and implicitly always succeed. |
| Such rewritings are permanent, so rules that specify them should |
| be placed after all pattern-matching rules in the rule set.<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>add</font></tt> The object must be <tt><font size=+1>attr</font></tt>. Append the argument, which must be |
| a sequence of <i>name</i><tt><font size=+1>=</font></tt><i>value</i> pairs, to the list of attributes of the |
| message.<br> |
| <tt><font size=+1>delete</font></tt> The object must be <tt><font size=+1>attr</font></tt>. If the message has an attribute |
| whose name is the argument, delete it from the list of attributes |
| of the message. (Even if the message does not, the rule matches |
| the message.)<br> |
| <tt><font size=+1>is</font></tt> If the text of the object is identical to the text of the argument, |
| the rule matches.<br> |
| <tt><font size=+1>isdir</font></tt> If the text of the object is the name of an existing directory, |
| the rule matches and sets the variable <tt><font size=+1>$dir</font></tt> to that directory |
| name.<br> |
| <tt><font size=+1>isfile</font></tt> If the text of the object is the name of an existing file |
| (not a directory), the rule matches and sets the variable <tt><font size=+1>$file</font></tt> |
| to that file name.<br> |
| <tt><font size=+1>matches</font></tt>If the entire text of the object matches the regular expression |
| specified in the argument, the rule matches. This verb is described |
| in more detail below.<br> |
| <tt><font size=+1>set</font></tt> The value of the object is set to the value of the argument.<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| </table> |
| The <tt><font size=+1>matches</font></tt> verb has special properties that enable the rules |
| to select which portion of the data is to be sent to the destination. |
| By default, a <tt><font size=+1>data matches</font></tt> rule requires that the entire text |
| matches the regular expression. If, however, the message has an |
| attribute named <tt><font size=+1>click</font></tt>, that reports that the message was |
| produced by a mouse click within the text and that the regular |
| expressions in the rule set should be used to identify what portion |
| of the data the user intended. Typically, a program such as an |
| editor will send a white-space delimited block of text containing |
| the mouse click, using the value of the <tt><font size=+1>click</font></tt> attribute (a |
| number starting from 0) to indicate where in the textual data |
| the user pointed. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| When the message has a <tt><font size=+1>click</font></tt> attribute, the <tt><font size=+1>data matches</font></tt> rules |
| extract the longest leftmost match to the regular expression that |
| contains or abuts the textual location identified by the <tt><font size=+1>click</font></tt>. |
| For a sequence of such rules within a given rule set, each regular |
| expression, evaluated by this specification, must |
| match the same subset of the data for the rule set to match the |
| message. For example, here is a pair of patterns that identify |
| a message whose data contains the name of an existing file with |
| a conventional ending for an encoded picture file:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>data matches '[a−zA−Z0−9_–./]+'<br> |
| data matches '([a−zA−Z0−9_–./]+).(jpe?g|gif|bit|ps|pdf)'<br> |
| </font></tt> |
| </table> |
| The first expression extracts the largest subset of the data around |
| the click that contains file name characters; the second sees |
| if it ends with, for example, <tt><font size=+1>.jpeg</font></tt>. If only the second pattern |
| were present, a piece of text <tt><font size=+1>horse.gift</font></tt> could be misinterpreted |
| as an image file named <tt><font size=+1>horse.gif</font></tt>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| If a <tt><font size=+1>click</font></tt> attribute is specified in a message, it will be deleted |
| by the <tt><font size=+1>plumber</font></tt> before sending the message if the <tt><font size=+1>data matches</font></tt> |
| rules expand the selection. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The action rules all have the object <tt><font size=+1>plumb</font></tt>. There are only three |
| verbs for action rules:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>to</font></tt> The argument is the name of the port to which the message will |
| be sent. If the message has a destination specified, it must match |
| the <tt><font size=+1>to</font></tt> port of the rule set or the entire rule set will be skipped. |
| (This is the only rule that is evaluated out of order.)<br> |
| <tt><font size=+1>client</font></tt> If no application has the port open, the arguments to a |
| <tt><font size=+1>plumb start</font></tt> rule specify a shell program to run in response to |
| the message. The message will be held, with the supposition that |
| the program will eventually open the port to retrieve it.<br> |
| <tt><font size=+1>start</font></tt> Like <tt><font size=+1>client</font></tt>, but the message is discarded. Only one <tt><font size=+1>start</font></tt> |
| or <tt><font size=+1>client</font></tt> rule should be specified in a rule set.<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| </table> |
| The arguments to all rules may contain quoted strings, exactly |
| as in <a href="../man1/rc.html"><i>rc</i>(1)</a>. They may also contain simple string variables, identified |
| by a leading dollar sign <tt><font size=+1>$</font></tt>. Variables may be set, between rule |
| sets, by assignment statements in the style of <tt><font size=+1>rc</font></tt>. Only one variable |
| assignment may appear on a line. The <tt><font size=+1>plumber</font></tt> also |
| maintains some built-in variables:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>$0</font></tt> The text that matched the entire regular expression in a previous |
| <tt><font size=+1>data matches</font></tt> rule. <tt><font size=+1>$1</font></tt>, <tt><font size=+1>$2</font></tt>, etc. refer to text matching the first, |
| second, etc. parenthesized subexpression.<br> |
| <tt><font size=+1>$attr</font></tt> The textual representation of the attributes of the message.<br> |
| <tt><font size=+1>$data</font></tt> The contents of the data field of the message.<br> |
| <tt><font size=+1>$dir</font></tt> The directory name resulting from a successful <tt><font size=+1>isdir</font></tt> rule. |
| If no such rule has been applied, it is the string constructed |
| syntactically by interpreting <tt><font size=+1>data</font></tt> as a file name in <tt><font size=+1>wdir</font></tt>.<br> |
| <tt><font size=+1>$dst</font></tt> The contents of the <tt><font size=+1>dst</font></tt> field of the message.<br> |
| <tt><font size=+1>$file</font></tt> The file name resulting from a successful <tt><font size=+1>isfile</font></tt> rule. If |
| no such rule has been applied, it is the string constructed syntactically |
| by interpreting <tt><font size=+1>data</font></tt> as a file name in <tt><font size=+1>wdir</font></tt>.<br> |
| <tt><font size=+1>$type</font></tt> The contents of the <tt><font size=+1>type</font></tt> field of the message.<br> |
| <tt><font size=+1>$src</font></tt> The contents of the <tt><font size=+1>src</font></tt> field of the message.<br> |
| <tt><font size=+1>$wdir</font></tt> The contents of the <tt><font size=+1>wdir</font></tt> field of the message.<br> |
| <tt><font size=+1>$plan9</font></tt>The root directory of the Plan 9 tree (see <a href="../man3/get9root.html"><i>get9root</i>(3)</a>).<br> |
| |
| </table> |
| |
| </table> |
| <p><font size=+1><b>EXAMPLE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| The following is a modest, representative file of plumbing rules.<br> |
| <tt><font size=+1># these are generally in order from most specific to least,<br> |
| # since first rule that fires wins.<br> |
| addr=':(#?[0−9]+)'<br> |
| protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)'<br> |
| domain='[a−zA−Z0−9_@]+([.:][a−zA−Z0−9_@]+)*/?[a−zA−Z0−9_?,%#~&/\−]+'<br> |
| file='([:.][a−zA−Z0−9_?,%#~&/\−]+)*'<br> |
| # image files go to page<br> |
| type is text<br> |
| data matches '[a−zA−Z0−9_\−./]+'<br> |
| data matches '([a−zA−Z0−9_\−./]+).(jpe?g|gif|bit)'<br> |
| arg isfile $0<br> |
| plumb to image<br> |
| plumb start page −w $file<br> |
| # URLs go to web browser<br> |
| type is text<br> |
| data matches $protocol://$domain$file<br> |
| plumb to web<br> |
| plumb start window webbrowser $0<br> |
| # existing files, possibly tagged by line number, go to edit/sam<br> |
| type is text<br> |
| data matches '([.a−zA−Z0−9_/–]+[a−zA−Z0−9_/\−])('$addr')?'<br> |
| arg isfile $1<br> |
| data set $file<br> |
| attr add addr=$3<br> |
| plumb to edit<br> |
| plumb start window sam $file<br> |
| # .h files are looked up in /sys/include and passed to edit/sam<br> |
| type is text<br> |
| data matches '([a−zA−Z0−9]+\.h)('$addr')?'<br> |
| arg isfile /sys/include/$1<br> |
| data set $file<br> |
| attr add addr=$3<br> |
| plumb to edit<br> |
| plumb start window sam $file<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| The following simple plumbing rules file is a good beginning set |
| of rules.<br> |
| <tt><font size=+1># to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules<br> |
| editor = acme<br> |
| # or editor = sam<br> |
| include basic<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>FILES </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>$HOME/lib/plumbing</font></tt> default rules file.<br> |
| <tt><font size=+1>plumb</font></tt> service name for <a href="../man4/plumber.html"><i>plumber</i>(4)</a>.<br> |
| <tt><font size=+1>/usr/local/plan9/plumb<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| directory for <tt><font size=+1>include</font></tt> files.<br> |
| |
| </table> |
| |
| </table> |
| <tt><font size=+1>/usr/local/plan9/plumb/fileaddr<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| public macro definitions.<br> |
| |
| </table> |
| |
| </table> |
| <tt><font size=+1>/usr/local/plan9/plumb/basic<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| basic rule set.<br> |
| |
| </table> |
| |
| </table> |
| |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man1/plumb.html"><i>plumb</i>(1)</a>, <a href="../man3/plumb.html"><i>plumb</i>(3)</a>, <a href="../man4/plumber.html"><i>plumber</i>(4)</a>, <a href="../man7/regexp.html"><i>regexp</i>(7)</a><br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
