7 Directives

The two ‘$’ characters appearing at the beginning of line (with optional preceding whitespace) introduce special preprocessor directives.

This feature can be disabled using the -Wno-directive option (see feature control).

The following directives are recognized:

Directive: $$source file

Directive: $$include file

Causes file to be read and processed at the current point. When the end of the file is reached, input is resumed from the previous input file.

If the file does not exist or cannot be read, xenv reports an error and exits with code 66 (see Exit codes).

Unless file is an absolute file name, it will be searched in the include search path. This path, initially empty, is initialized using the -I command line option. Its argument names a directory to be added to the include search path.

Directive: $$sinclude file

Same as $$include, except that if the file is not found, no error is reported.

Directive: $$verbatim

Begins a verbatim text block. The material up to the next $$end statement is reproduced on the output verbatim. Example:

$$verbatim
the $name construct is
not expanded here
$$end

See also the $[ ... ] construct (see inline verbatim), which introduces the same feature for inline portions of text.

Directive: $$ifdef name

Directive: $$ifndef name

Conditional expansion directive. The full syntax is:

$$ifdef name
text1
$$else
text2
$$endif

This construct is replaced with text1, if the environment variable name is defined, and with text2 otherwise. The use of $$ifndef reverts the logic: text1 is substituted if name is not defined.

Directive: $$ifset name

Directive: $$ifnset name

Another conditional expansion directive. The syntax is similar to the above:

$$ifset name
text1
$$else
text2
$$endif

text1 is substituted if name is defined and its value is not empty, otherwise text2 is substituted.

The logic is inverted if $$ifnset is used instead.

Two more conditional directives are provided that analyze a boolean value of a variable. An environment variable is said to evaluate to true if its value is ‘1’. It is said to evaluate to false if its value is ‘0’. These default boolean constants can be changed using the -Wbooleans option (see -Wbooleans).

The directives $$iftrue and $$iffalse control expansion using boolean evaluation:

Directive: $$iftrue name

Conditional expansion based on boolean true. The syntax is similar to the above:

$$iftrue name
text1
$$else
text2
$$endif

If name is set and has a true boolean value, text1 is substituted. Otherwise, if name is unset or evaluates to boolean false, text2 is substituted.

Directive: $$iffalse name

Conditional expansion based on boolean false. The syntax is:

$$iftrue name
text1
$$else
text2
$$endif

If name is unset or evaluates to boolean false, text1 is substituted. Otherwise, if name evaluates to boolean true, text2 is substituted.

Directive: $$ifcom command

Directive: $$ifncom command

Conditional expansion depending on the exit code of a shell command:

$$ifcom command
text1
$$else
text2
$$endif

This directive runs command (via SHELL -c). If the exit code is 0, text1 is substituted, otherwise text2 is substituted.

$$ifncom inverts the logic (i.e. text1 is substituted if command fails, i.e. exits with a non-zero status code).

A ‘\newline’ pair in command is treated as a line continuation: it is removed from the input stream and effectively ignored. This allows for splitting excessively long commands over multiple physical lines. To end command in a backslash, put two backslashes before the newline.

The command is run in the same manner as during command substitution (see Command substitution), except that its standard output is ignored. This means that it is passed to the shell verbatim (so that options -u, -r, and -e don’t apply) and its execution time is controlled by the -t option (see command execution timeout).

In all conditional constructs described above the $$else part is optional. Conditional constructs can be nested to any depth.

Directive: $$set name

Sets the variable name to empty string.

Directive: $$set name "value"

Sets the variable name to value. value can occupy multiple lines and is subject to variable expansion, command substitution, and directive expansion, insofar as permitted by the -W option.

Directive: $$set name 'value'

Sets the variable name to value. value can occupy multiple lines. Neither variable expansion nor command substitution occurs in it.

Directive: $$unset name

Unsets the variable name.