Skip to content

Plumbing Reference

Anvil allows you to define special actions that are taken when using ALT-Right Click on a word or selection, which override the default behaviour of trying to open that object as a file.

These actions are defined as rules in the file "plumbing" in the Anvil configuration directory. Each rule consists of two parts: a regular expression pattern, and an action to take. When the word or selection (a text object) is clicked, Anvil considers each rule in the order they are defined in the plumbing file, and if the text object matches the pattern of a rule, then the action of that rule is performed and no more rules are considered. The action of a rule can be an OS command, or an Anvil command.

If a plumbing rule is executed from a remote window, the command in the action is run remotely.

Plumbing File Format

Lines beginning with '#' in the plumbing file are comments and not executed.

Each rule in the plumbing file consists of a match line that defines the pattern, followed by a do line that defines the action to take:

match <pattern>
do <command>

The <pattern> is a regular expression. The <command> is an OS or Anvil command. In the command, $0 is substituted with the entire match text that matched <pattern>. Terms of the form $N (for N = 1, 2, 3, ...) are substituted with the first, second, third, and higher groups in the regular expression. Groups in the regular expression are enclosed with '(' and ')'. $N may be written ${N}.

Here is an example of a simple plumbing file:

match https?://[^ ]*
do firefox --new-tab --url $0

match .*\.jpg$
do eog $0

match .*\.pdf$
do evince '$0'

match ^.*\.dump$
do Load ${0}

This example contains four rules:

  • the first rule matches URLs, and when matched opens that URL in Firefox
  • the second matches JPEG files and opens Eye of Gnome to view the image
  • the third matches PDF files and launches Evince to view them
  • The fourth matches an Anvil dump file, and loads it in Anvil