PROG(1) General Commands Manual PROG(1)
NAME
plumb - run best command for given arguments
SYNOPSIS
plumb [-action ...] [--] arg ...
DESCRIPTION
plumb passes the given arguments, as is or modified, to the best command
associated to the rules the arguments match with.
plumb can be used, for example, to open files or URLs. By giving
filenames as arguments, plumb tries to find the best command to open them
after matching the filenames with sets of rules in sequence. See the
section EXAMPLES for illustration.
Each set of rule (or ruleset) is associated with a command for a given
type of action (such as "open" or "edit"). The command for the given
action associated with the first ruleset matching the arguments is the
one chosen to be run.
The first arguments beginning with hyphen (-), are interpreted as a
actions to be try. If the matching ruleset contains one of those
actions, the first action is performed. For example, -edit -open will
try to perform either the edit or the open action on the following
arguments.
The actions -o and -e are equivalent to -open and -edit, respectively.
A -- separates actions from actual arguments.
If no action is provided, plumb acts as if the action -open were given.
USAGE
plumb reads rules from the file $HOME/lib/plumb. Lines with blank and
lines beginning with "# are ignored."
Each non ignored line can be either a static variable assignment or can
be one of the four following types, named after the second word in the
line:
"for" A line beginning a ruleset.
"matches"
A line describing a condition a variable has to match case-
sensitively, and, optionally, setting new variables when the
matching occurs.
"imatches"
A line describing a condition a variable has to match case-
insensitively, and, optionally, setting new variables when the
matching occurs.
"types"
A line testing the existence and type of a file, and assigning
this information to a new variable.
"with" A line describing the command to be open if the conditions in the
same ruleset matches.
There are two kinds of variables that can be assigned and used in the
configuration file:
Static variables
Static variables are assigned with a "NAME=VALUE" line. Such
variables are expanded into a single word when prefixed with a
dollar sign ($) and occurring in any line after the place it was
defined. Environment variables are of this kind, but do not need
to be defined. See the section Static variables for more
information on static variables.
Argument variables
Argument variables are assigned with a "matches", "imatches", or
a "types" line. Such variables can be expanded into various
words (one for each argument passed to plumb) when prefixed with
a percent sign (%) and occurring as the last argument of a "with"
line in the same ruleset it was defined. See the section WITH-
lines for more information on argument variables.
Each line is a sequence of words (which are either space-delimited words
or strings quoted in rc(1) single-quote style). The first word of a line
is the "subject". The second word (which identifies the type of the
line) is the "verb". The remaining words are the arguments.
The configuration is processed once for each argument. For each
processing pass, the argument variable data is set to the argument itself
and the remaining argument variables are re-assigned. Static variables
are assigned only once, at plumb initialization.
Static variables
Lines of the form "NAME=VALUE" assign a value to a static variable.
Static variable are recognized anywhere in the file after the place they
are defined.
Environment variables are also static variables, but they are not defined
in the config file (they are already defined in the environment).
References to static variables can occur on the configuration file
outside quotations, and are replaced with their values. Such references
are prefixed with the dollar sign "$" or prefixed with the dollar sign
and surrounded by curly braces. The dollar sign can be escaped by
doubling it.
FOR-lines
Lines whose second word is "for" must have "rules" as subject. They
begin a new ruleset. A ruleset is everything between a "FOR-line" and
the next one.
For example, the following line begins the ruleset for handling video
files:
rules for video files
The arguments of a "FOR-line" are the name of the ruleset.
Conditions in a ruleset are only checked within the ruleset. Variables
set in a ruleset are only valid within the ruleset.
The lines before the first "FOR-line" make the global, unamed ruleset.
Conditions in the global ruleset are ignored. Variables set in the
global ruleset are valid for the entire file.
MATCHES-lines
Lines whose second word is "matches" or "imatches" must have the name of
a variable as subject (first word in the line). They must also have a
regular expression as first argument. The subject names a value that
must match the regular expression.
If the second word is "matches", the regular expression matching is case-
sensitive. If the second word is "imatches", the regular expression
matching is case-insensitive.
For example, the following line is a three-word condition that says that
one of the conditions for the current ruleset to be matched is for the
content of the variable mime to match the regular expression
image/(jpeg|png).
mime matches 'image/(jpeg|png)'
The regular expression is a extended POSIX regular expression and must
match the entire value of the argument variable for the condition to be
valid.
If the rule has more than one argument, the second argument must be into
and the following ones must be names of argument variables to be set.
Each argument variable is set to the substring matching the parenthesized
subexpression of the regular expression if, and only if, the full regular
expression matches the value of the subject.
For example, the following line assigns to the argument variable base the
basename(1) of the value on the argument variable data (supposing it
contains a filename); and assigns to the argument variable extension the
extension of the filename. If either subexpression does not match, the
corresponding argument variable is set to the empty string. The dummy
argument variable name _ (underscore) is used for uneeded values.
data matches '(([^/]*/)*)([^/]*(\.([A-Za-z0-9]+)?))' _ _ base extension
TYPES-lines
Lines whose second word is "types" must have the name of a argument
variable as subject, and the name of another argument variable as single
argument. The subject names a value for a existing file whose mimetype
is assigned to the argument variable passed as argument.
For example, the following line is a three-word assignment that says that
the mimetype of the file named in the argument variable data must be
assigned to the argument variable mime.
data types mime
WITH-lines
Lines whose second word is "with" must have the name of an action type
(like open or edit) as subject and a command invocation as arguments.
The arguments name a program to be run for the action named as subject
when the ruleset the line is in is valid for all the arguments passed.
for example, the following line is a three-word description to open the
browser firefox(1) on the open action.
open with firefox
If the last argument has a percent symbol ("%") before a name, then this
name is considered as a variable name. This argument is replaced by one
argument for each argument passed and the variable name with the percent
sign is replaced with the value of the variable.
For example, the following line opens firefox(1) replacing the argument
file://%data for the variable data for each argument. (so if plumb is
invoked for ./index.html and /path/to/file.html, then that single
argument is replaced with file://./index.html and
file:///path/to/file.html).
open with firefox -- file://%data
Just like environment variables, the percent sign can be escaped by
doubling it. The name of the variable can also occur between curly
braces.
ENVIRONMENT
The following environment variables affect the execution of plumb.
HOME Path to the directory to search for the file lib/plumb.
FILES
$HOME/lib/plumb
plumb's default configuration file.
EXIT STATUS
The plumb utility exits 0 on success, and >0 if an error occurs.
It is an error if no ruleset matches for an argument.
EXAMPLES
The following is the example of a simple configuration file.
DATAREGEX = '(([A-Za-z]+):(//)?)?(.*(\.([A-Za-z0-9]+))?)'
data matches $DATAREGEX into _ protocol _ file _ extension
file types mime
rules for youtube video
protocol matches '(ytdl|https?)?'
file matches '(.*/)?[A-Za-z0-9_-]{11}'
open with mpv --force-window=immediate -- %data
rules for image file
protocol matches '(file)?'
mime imatches 'image/(png|jpe?g|tiff)'
open with display -- %file
edit with gimp -- %file
rules for web page
protocol matches '(https?|file)?'
extension imatches 'html'
open with seamonkey -- %data
This configuration file is interpreted as follows:
o The static variable DATAREGEX is set to a regular expression used
later in the config file.
o For each passed argument, the second paragraph sets the argument
variables "protocol" to an URI protocol; "file" to the argument
without the protocol; "extension" to a file extension; and "mime" to
the mimetype of the value of "file". The argument variable "data" is
automatically set to the argument itself on each pass.
o The third paragraph sets rules for opening youtube videos on mpv(1)
using the ytdl protocol.
o The fourth paragraph sets rules for opening and editing image files.
o The fifth paragraph sets rules for opening web pages.
With this configuration file, the following command opens
https://wikipedia.org and file:///var/www/htdocs/index.html on
seamonkey(1):
$ plumb https://wikipedia.org file:///var/www/htdocs/index.html
The following command opens a PNG file on gimp for editing:
$ plumb -edit /home/user/photo.png
SEE ALSO
Rob Pike, Plumbing and Other Utilities, Bell Laboratories.
HISTORY
A plumb utility appeared in the Plan 9 operating system.
UNIX July 2, 2023 UNIX