357 lines
20 KiB
HTML
357 lines
20 KiB
HTML
<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>
|