GNU Rush
	Restricted User Shell	Sergey Poznyakoff

• Main
• Downloads
• Documentation

4.4.1.5 Variable Expansion

Most statements in the configuration file undergo variable expansion prior to their use. During variable expansion, references to variables in the string are replaced with their actual values. A variable reference has two basic forms:

  $v
  ${v}

where v is either the name of the variable (request, environment, or user-defined), or the index of the positional variable. The notation in curly braces serves several purposes. First, it is obligatory if v is an index of the positional variable that is negative or greater than 9. Secondly, it should be used if the variable reference is immediately followed by an alphanumeric symbol, which will otherwise be considered part of it (as in ‘${home}dir’). Finally, this form allows for specifying the action to take if the variable is undefined or expands to an empty value.

The following special forms are recognized:

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

These constructs test for a variable that is unset or null. Omitting the colon results in a test only for a variable that is unset.

When expanding a variable reference, the variable name is first looked among the request variables. If it is not found, it is looked up in the user-defined variable list. If it is not there, the look up in the environment is attempted.

If the variable name is not found in any of these lists, the default rush behavior is to report the error of ‘config-error’ class (see Error Messages) and exit. To gracefully handle such cases, use the default value construct, defined above. For example, the following statement safely appends the string ‘/opt/man’ to the value of the MANPATH environment variable:

setenv MANPATH = "${MANPATH:-""}${MANPATH:+:}/opt/man"

The ‘${MANPATH:-""}’ reference ensures no error is reported if the variable is undefined. The ‘${MANPATH:+:}’ reference appends a semicolon to the value, if the variable is defined. Finally the string ‘/opt/man’ is appended to the resulting value.

Another way to gracefully handle undefined variables, is to use the expand-undefined global setting. If you place the following statement at the beginning of your configuration file, any undefined variable will be silently expanded to empty string:

global
  expand-undefined true

This statement affects variable expansion in statements that follow it in the configuration file. So you can place it in some point after which this behavior is needed, and then disable it where it is no longer desired, by using the following global statement:

global
  expand-undefined false