Appendix A Legacy Syntax of the environ Statement

This appendix describes the syntax of the environ statement used in GNU direvent versions 5.2 and earlier. The use of this legacy syntax is discouraged. It is supported for backward compatibility only and will be removed in future versions.

legacy syntax: environ args

Modify command environment. Arguments are a single environment modification directive, a whitespace-delimited list of directives, or a proper list (see list) of directives.

The following directives are available. To facilitate switching to the modern environ syntax, the discussion below lists, for each legacy directive, its modern syntax equivalent (see environ).

‘-’ (a single dash)

Clear the inherited environment, but retain the variables added by direvent itself. The removed environment variables can be selectively restored using the directives discussed below.

If used, this must be the first directive in the list.

The modern syntax equivalent is:

environ {
  clear;
  keep "DIREVENT_*";
}

‘--’ (double-dash)

Clear the entire environment, including the variables added by direvent.

If used, this must be the first directive in the list.

The modern syntax equivalent is:

environ {
  clear;
}

-name

Unset the variable name.

The modern syntax equivalent is

environ {
  unset name;
}

-name=val

Unset the environment variable name only if its value is val. The modern syntax equivalent is:

environ {
  unset "name=val";
}

name

Restore the environment variable name. This directive is useful after ‘-’ or ‘--’ to retain some variables from the environment. The modern syntax equivalent is:

keep name;

name=value

Define environment variable name to have given value. It is equivalent to:

environ {
  keep "name=value";
}

name+=value

Retain variable name and append value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value begins with a punctuation character, this character is removed from it before the assignment. This is convenient for using this construct with environment variables like PATH, e.g.:

PATH+=:/sbin

In this example, if PATH exists, ‘:/sbin’ will be appended to it. Otherwise, it will be created and ‘/sbin’ will be assigned to it.

In modern syntax, use shell variable references, e.g.:

environ {
  set "PATH=${PATH}${PATH:+:}/sbin";
}

name=+value

Retain variable name and prepend value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value ends with a punctuation character, this character is removed from it before assignment.

In modern syntax, use shell variable references, e.g. instead of doing

environ PATH=+/sbin:

use

environ {
  set "PATH=/sbin${PATH:+:}$PATH";
}