Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PLUMB(7)	       Miscellaneous Information Manual		      PLUMB(7)

       plumb - format of plumb messages	and rules

       #include	<plumb.h>

   Message format
       The messages formed by the plumb(3) 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(1)) 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

       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.

		     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-

       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	could be misinterpreted	as an image file named

       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-

	      $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-

	      $attr  The  textual representation of the	attributes of the mes-

	      $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.

	      $plan9 The root directory	of the Plan 9 tree (see	get9root(3)).

       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.


       # 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
       # to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules

       editor =	acme
       # or editor = sam
       include basic

	      default rules file.

       plumb  service name for plumber(4).

	      directory	for include files.

	      public macro definitions.

	      basic rule set.

       plumb(1), plumb(3), plumber(4), regexp(7)



Want to link to this manual page? Use this URL:

home | help