|  | 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:
 
 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.|  |  |  | 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
 
 | 
 
 Plumbing rules     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 formThe 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.
 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.
 
 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:|  |  |  | 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 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:|  |  |  | data matches '[a−zA−Z0−9_–./]+' data matches '([a−zA−Z0−9_–./]+).(jpe?g|gif|bit|ps|pdf)'
 
 | 
 
 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:|  |  |  | 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.
 
 | 
 |  |  |  | $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)).
 
 | 
 |