GNU Rush
	Restricted User Shell	Sergey Poznyakoff

• Main
• Downloads
• Documentation

3.2 Transformations

Special actions that modify the original command line are called transformations. GNU Rush supports several kinds of transformations: ‘set’, ‘transform’, ‘delete’, ‘map’. All of them operate on command line split into words. Additionally, ‘set’ and ‘transform’ can operate on the entire command line.

Rush performs word splitting using the same rules as sh. Transformation actions refer to words by their index. Three kinds of indexes are supported. First of all, a word may be referred to by its ordinal number in the command line. The command name itself has index ‘0’. For example, given the command line:

/bin/scp -t /upload

one gets:

Negative indexes can also be used. They refer to words in the reverse order, as illustrated in the following table:

Notice that negative indexes are 1-based.

Finally, two special notations are available. The last word may be referred to as ‘$’, and the command name itself as ‘^’. There is a subtle difference between ‘0’ and ‘^’. The notation ‘^’ refers to the name of the program that rush will execute at the end of the matching rule, whereas the notation ‘0’ refers to the 0th argument that will be passed to that program (‘argv[0]’). Most of the time the two values coincide. Unless the rule modifies ‘^’, ‘0’th word will be used as the program name. There exist some cases when you need to explicitly set ‘^’. See Interactive, for a possible use of this feature.

In the detailed discussion below, arguments to some transformations are referred to as patterns. A pattern is a string which, prior to its actual use, is subject to variable and backreference expansions.

During variable expansion all references to variables in the string are replaced with the actual values of the corresponding variables. Variables are referred to using the following syntax: ‘$x’ or ‘${x}’, where x is the variable name. The latter notation serves two purposes. First, it should be used if the variable reference is immediately followed by an alphanumeric symbol, which will otherwise be considered part of it. Consider, for example the string ‘${home}dir’. Here, the curly braces separate the name of the variable ‘home’ from the string that follows it. Secondly, this form allows for specifying the action to take if the variable is undefined or expands to an empty value. The following constructs test for a variable that is unset or null. Omitting the colon results in a test only for a variable that is unset.

${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

All variables fall into two categories: built-in and user-defined. Built-in variables are always defined. User-defined variables are created using the ‘setvar’ statement and can be undefined using the ‘unsetvar’ statement (see below).

The built-in variables are summarized in the table below:

During the backreference expansion, references to parenthesized subgroups from the last regexp match are replaced by the text that matched each subgroup. Syntactically a backreference consists of a percent sign followed by a decimal number of the subgroup in range between 0 and 9, inclusively. Consider the following rule:

rule chdir
  command ^cd (.+) && (.+)
  chdir %1
  set %2
  fall-through

It splits the compound command into the working directory and the command itself. Then it remembers the name of the working directory (first parenthesized group – ‘%1’) for changing to it later and resets the command line to the part of the string that follows the ‘&&’ token. Finally, it passes control to another rules (‘fall-through’).