PLUMBING(6)                                           PLUMBING(6)

     NAME
          plumbing - plumbing rules

     DESCRIPTION
          Plumbing rules tell plumber(8) how to route plumbing mes-
          sages generated by applications using plumbmsg(2).

          The file is a set of rules separated by blank lines.  Each
          rule is a set of patterns followed by a set of actions.  The
          rules are interpreted in order.  The first rule whose pat-
          terns all match is applied, and no further rules are exam-
          ined.  Comments start with # and continue to end of line.
          Single quotes protect special characters (use '' to get a
          single quote).

          A pattern has the general form:

               field verb arg

          Each field corresponds to a field in the incoming plumbing
          message:

               src  Source application

               dst  Destination port

               dir  Working directory

               kind Format of the data (eg, text or image)

               attr A line of name=value pairs

               data The message data (an array of bytes)

          The verbs are:

               is       Exact string comparison with arg

               matches  Regular expression comparison with arg

               isdir    Arg must name an existing directory

               isfile   Arg must name an existing file

               set      Set the value of the field to arg. This verb
                        operates in place, so put it after all other
                        patterns in the rule.

          The arg can refer to one of the following variables:

     Page 1                       Plan 9             (printed 5/22/22)

     PLUMBING(6)                                           PLUMBING(6)

               $0 to $9   Substrings resulting from the most recent
                          regular expression match: $0 is the entire
                          substring; $1 the first parenthesised sub-
                          string, etc.

               $file      The file name examined by the last isfile
                          verb.

               $dir       The directory name examined by the last
                          isdir verb.

          The following actions are provided:

               plumb to port
                    Route the message to the given plumbing port.

               plumb start command arg ...
                    If no program is currently listening on the cur-
                    rent rule's port, start the command with the given
                    arguments.  The `$' variables listed above can be
                    used, to include part of the message in the com-
                    mand line arguments to the program.  They are
                    replaced in the command string by their actual
                    values.

          For example, the following rule sends the names of module
          files- file names ending with suffix `.m'- to wm-brutus(1),
          starting it if it is not already running:

               kind is text
               data matches '([a-zA-Z0-9]+.m)(:[0-9]+)?'
               data isfile     /module/$1
               data set        /module/$0
               plumb to edit
               plumb start /dis/wm/brutus.dis $file$2

          Note the use of $2 in the start action to pass brutus the
          line number selected by the second parenthesised expression
          in the pattern.

     FILES
          /usr/user/lib/plumbing

     SEE ALSO
          plumb(1), plumbmsg(2), plumber(8)

     Page 2                       Plan 9             (printed 5/22/22)