term% cat index.txt PLUMB(6) Games Manual PLUMB(6)
NAME
plumb - format of plumb messages and rules
SYNOPSIS
#include <plumb.h>
DESCRIPTION
Message format
The messages formed by the plumb(2) library are formatted for transmis‐
sion 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 Plumbmsg structure, that is used in the plumbing
rules. The fields, in order, are:
src application/service generating message
dst destination `port' for message
wdir working directory (used if data is a file name)
type form of the data, e.g. text
attr attributes of the message, in name=value 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)
ndata number of bytes of data
data the data itself
At the moment, only textual data (type=text) is supported.
All fields are optional, but type should usually be set since it de‐
scribes the form of the data, and ndata must be an accurate count (pos‐
sibly zero) of the number of bytes of data. A missing field is repre‐
sented by an empty line.
Plumbing rules
The plumber (see plumb(2)) receives messages on its send port (applica‐
tions send messages there), interprets and reformats them, and (typi‐
cally) emits them from a destination port. Its behavior is determined
by a plumbing rules file, default /usr/$user/lib/plumbing, which de‐
fines a set of pattern/action rules with which to analyze, rewrite, and
dispatch received messages.
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 plumb to 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 # character are commentary and are
regarded as blank lines.
A line of the form
include file
substitutes the contents of file for the line, much as in a C #include
statement. Unlike in C, the file name is not quoted. If file is not
an absolute path name, or one beginning ./ or ../, file is looked for
first in the directory in which the plumber is executing, and then in
/sys/lib/plumb.
When a message is received by the plumber, 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 dis‐
carded (giving a write error to the sender) unless it has a dst field
that specifies an existing port, in which case the message is emitted,
unchanged, from there.
Patterns and actions all consist of three components: an object, a
verb, 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.
The object in a pattern is the name of an element of the message, such
as src or data, or the special case arg, which refers to the argument
component of the current rule. The object in an action is always the
word plumb.
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 predi‐
cates that check properties of the message; others rewrite components
of the message and implicitly always succeed. Such rewritings are per‐
manent, so rules that specify them should be placed after all pattern-
matching rules in the rule set.
add The object must be attr. Append the argument, which must
be a sequence of name=value pairs, to the list of at‐
tributes of the message.
delete The object must be attr. 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.)
is If the text of the object is identical to the text of the
argument, the rule matches.
isdir If the text of the object is the name of an existing di‐
rectory, the rule matches and sets the variable $dir to
that directory name.
isfile If the text of the object is the name of an existing file
(not a directory), the rule matches and sets the variable
$file to that file name.
matches
If the entire text of the object matches the regular ex‐
pression specified in the argument, the rule matches.
This verb is described in more detail below.
set The value of the object is set to the value of the argu‐
ment.
The matches verb has special properties that enable the rules to select
which portion of the data is to be sent to the destination. By de‐
fault, a data matches rule requires that the entire text matches the
regular expression. If, however, the message has an attribute named
click, 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. Typi‐
cally, a program such as an editor will send a white-space delimited
block of text containing the mouse click, using the value of the click
attribute (a number starting from 0) to indicate where in the textual
data the user pointed.
When the message has a click attribute, the data matches rules extract
the longest leftmost match to the regular expression that contains or
abuts the textual location identified by the click. 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:
data matches '[a-zA-Z0-9_-./]+'
data matches '([a-zA-Z0-9_-./]+).(jpe?g|gif|bit|ps|pdf)'
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, .jpeg. If only the second pattern were present, a
piece of text horse.gift could be misinterpreted as an image file named
horse.gif.
If a click attribute is specified in a message, it will be deleted by
the plumber before sending the message if the data matches rules expand
the selection.
The action rules all have the object plumb. There are only three verbs
for action rules:
to The argument is the name of the port to which the message
will be sent. If the message has a destination speci‐
fied, it must match the to port of the rule set or the
entire rule set will be skipped. (This is the only rule
that is evaluated out of order.)
client If no application has the port open, the arguments to a
plumb start rule specify a shell program to run in re‐
sponse to the message. The message will be held, with
the supposition that the program will eventually open the
port to retrieve it.
start Like client, but the message is discarded. Only one
start or client rule should be specified in a rule set.
The arguments to all rules may contain quoted strings, exactly as in
rc(1). They may also contain simple string variables, identified by a
leading dollar sign $. Variables may be set, between rule sets, by as‐
signment statements in the style of rc. Only one variable assignment
may appear on a line. The plumber also maintains some built-in vari‐
ables:
$0 The text that matched the entire regular expression in a
previous data matches rule. $1, $2, etc. refer to text
matching the first, second, etc. parenthesized subexpres‐
sion.
$attr The textual representation of the attributes of the mes‐
sage.
$data The contents of the data field of the message.
$dir The directory name resulting from a successful isdir
rule. If no such rule has been applied, it is the string
constructed syntactically by interpreting data as a file
name in wdir.
$dst The contents of the dst field of the message.
$file The file name resulting from a successful isfile rule.
If no such rule has been applied, it is the string con‐
structed syntactically by interpreting data as a file
name in wdir.
$type The contents of the type field of the message.
$src The contents of the src field of the message.
$wdir The contents of the wdir field of the message.
EXAMPLE
The following is a modest, representative file of plumbing rules.
# these are generally in order from most specific to least,
# since first rule that fires wins.
addr=':(#?[0-9]+)'
protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)'
domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\-]+'
file='([:.][a-zA-Z0-9_?,%#~&/\-]+)*'
# image files go to page
type is text
data matches '[a-zA-Z0-9_\-./]+'
data matches '([a-zA-Z0-9_\-./]+).(jpe?g|gif|bit)'
arg isfile $0
plumb to image
plumb start page -w $file
# URLs go to web browser
type is text
data matches $protocol://$domain$file
plumb to web
plumb start window webbrowser $0
# existing files, possibly tagged by line number, go to edit/sam
type is text
data matches '([.a-zA-Z0-9_/-]+[a-zA-Z0-9_/\-])('$addr')?'
arg isfile $1
data set $file
attr add addr=$3
plumb to edit
plumb start window sam $file
# .h files are looked up in /sys/include and passed to edit/sam
type is text
data matches '([a-zA-Z0-9]+\.h)('$addr')?'
arg isfile /sys/include/$1
data set $file
attr add addr=$3
plumb to edit
plumb start window sam $file
The following simple plumbing rules file is a good beginning set of
rules.
# to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules
editor = acme
# or editor = sam
include basic
FILES
/usr/$user/lib/plumbing
default rules file.
/mnt/plumb
mount point for plumber(4).
/sys/lib/plumb
directory for include files.
/sys/lib/plumb/fileaddr
public macro definitions.
/sys/lib/plumb/basic
basic rule set.
SEE ALSO
plumb(1), plumb(2), plumber(4), regexp(6)
PLUMB(6)