Plumb

Plumb is a program that starts a number of processes, and configures any number of pipes between their (and Plumb's own) STDIN, STDOUT, STDERR, in any combination.

All multiplexing is handled using line buffering, so the contents of lines won't get mixed when two sources write on the same output.

For convenience, pipes can filter and optionally remove line prefixes (so a single program can give selective output to multiple programs from the same STDOUT). Outputs can add their own line prefix, so outputs from multiple sources may be distinguished.

Plumb might be useful together with software like Animator.

Download

Source code is available from Subversion:

$ svn co svn://repo.hu/plumb/trunk plumb

i386 Debian packages are available from the repo.hu Debian repository.

Command Line

All of Plumb's behavior is configured on the command line, all at once. Starting Plumb without arguments will give a short help on the syntax.

The command line is made of two parts: the description of processes, then the pipes between them.

$ plumb [-a] processes... pipes...

The -a flag turns on keepalive mode (see below).

You can specify zero or more processes, and zero or more pipes (but having zero of either isn't terribly useful).

Each process specification starts with a + (plus), and finishes with a single ; (semicolon, which you'll have to escape in the shell).

+ program arg1 arg2... \;

Alternatively, you can specify a shell command - this is equivalent to: + /bin/sh -c shell-command \;

: shell-command

Pipe specifications look like this:

input [-p|-P|-k|-K filterprefix] output [+p prependprefix]

Input says where to read from:

0 - from Plumb's STDIN
1..N - from the STDOUT of the Nth process
e1..N - from the STDERR of the Nth process

Output says where to write to:

0 - to Plumb's STDOUT
e - to Plumb's STDERR
1..N - to the STDIN of the Nth process

A filterprefix may be specified, using one of the listed flags:

-p prefix - write only if line starts with prefix
-P prefix - like -p, but before writing, the prefix is cut off
-k prefix - like -p, but if the filter matches, pipes for this input defined later in the chain aren't processed for this line
-K prefix - like -k, but before writing, the prefix is cut off

Using the +p flag after the output, a prefix may be defined that will be written before each line the pipe outputs.

Examples

To emulate 69 (a tool that starts two programs with pipes first to second and second to first):

$ plumb + program1... \; + program2... \; 1 2 2 1

Same scenario as before, but grep every line that contains the string "red" from the output of the first program, and output to Plumb's STDOUT, every line prefixed with "First program says ":

$ plumb + program1... \; + program2... \; + grep --line-buffered red \; 1 2 2 1 1 3 3 0 +p "First program says "

Copy every input line, except those that start with "X"; in these, remove the "X", then replace all "a" characters to "b":

$ plumb + sed -u 's/a/b/g' \; 0 -K X 1 0 0 1 0

Keepalive mode

Normally (without the -a flag) Plumb will shut down everything as soon as the first process stops or the first input is closed. This is useful for interactive applications, but will cause problems with filter chains on static inputs.

When keepalive is enabled, Plumb will shut down when:

Any process exits abnormally or with an error exit status
There is a write error on any pipe
All processes have exited normally and there are no open inputs left

In keepalive mode, Plumb keeps track of pipes: when all inputs to a specific output are closed, then the output is closed as well (this way filters can get an EOF at end of input). Be ware of multiplexing: if one output has multiple inputs pointed at it, it's not enough to close one input to close the output; all inputs have to be closed.

Author

Plumb is licensed under the GNU General Public License Version 3 (available in the file COPYING) or any later version.

Home page: http://repo.hu/projects/plumb