diff options
Diffstat (limited to 'man/man7/plumb.html')
| -rw-r--r-- | man/man7/plumb.html | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/man/man7/plumb.html b/man/man7/plumb.html new file mode 100644 index 00000000..eca67a76 --- /dev/null +++ b/man/man7/plumb.html @@ -0,0 +1,357 @@ +<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> |