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