plumb(7) - Plan 9 from User Space

From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man7/plumb.html | 357 ---------------------------------------------------- 1 file changed, 357 deletions(-) delete mode 100644 man/man7/plumb.html (limited to 'man/man7/plumb.html') 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 @@ - -plumb(7) - Plan 9 from User Space - - - - -

PLUMB(7) PLUMB(7) -

-
-

NAME
- -
- - plumb – format of plumb messages and rules
- -
-

SYNOPSIS
- -
- - #include <plumb.h> - -
-

DESCRIPTION
- -
- -
Message format
- The messages formed by the plumb(3) 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 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 describes the form of the data, and ndata must be an accurate - count (possibly zero) of the number of bytes of data. A missing - field is represented by an empty line.
-
Plumbing rules
- The plumber (see plumb(1)) receives messages on its send port - (applications send messages there), interprets and reformats them, - and (typically) emits them from a destination port. Its behavior - is determined by a plumbing rules file, default /usr/$user/lib/plumbing, - which defines 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 discarded (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 - 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.
- -
- - add      The object must be attr. Append the argument, which must be - a sequence of name=value pairs, to the list of attributes 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 directory, - 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.
- matchesIf 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.
- set      The value of the object is set to the value of the argument.
- -
- - -
- 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 default, 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. 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 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 specified, 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 response 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 assignment statements in the style of rc. Only one variable - assignment may appear on a line. The plumber also - maintains some built-in variables:
- -
- - $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 subexpression.
- $attr   The textual representation of the attributes of the message.
- $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 constructed 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.
- $plan9The root directory of the Plan 9 tree (see get9root(3)).
- -
- -
-

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
- -
- - $HOME/lib/plumbing default rules file.
- plumb service name for plumber(4).
- /usr/local/plan9/plumb - -
- - -
- - directory for include files.
- -
- -
- /usr/local/plan9/plumb/fileaddr - -
- - -
- - public macro definitions.
- -
- -
- /usr/local/plan9/plumb/basic - -
- - -
- - basic rule set.
- -
- -
- -
-

SEE ALSO
- -
- - plumb(1), plumb(3), plumber(4), regexp(7)
- -
- -

- - -

		-
	- - - -

- - -- cgit v1.2.3