XENV

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
SEE ALSO
COPYRIGHT

---

NAME

xenv − expand shell variables in input files

SYNOPSIS

xenv [−hnrsu] [−D NAME[=VALUE]] [−S [$@%&#]] [−U NAME] [FILE...]

DESCRIPTION

Reads input from FILEs (or the standard input, if none are supplied) and prints it on the standard output, expanding references to environment variables with their actual values.

Variable expansion
A reference is one of the following constructs:

$NAME

Expands to the value of the variable NAME, or to an empty string, if it is unset.

${NAME}

Same as above.

The following forms cause xenv to 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 standard error. 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.

${variable:|word1|word2}

Unless variable is null or unset, substitues the expansion of word1, otherwise the expansion of word2.

The above notation is consistent with the POSIX shell, except for the ${variable:|word1|word2} form, which is an extension of xenv.

Comments
Comments are multiline. They are introduced with the characters ${* and extend up to the nearest pair of characters *}. Comments are removed from the input.

Conditionals
The following conditional statements expand to a given fragment of text depending on whether an environment variable is defined.
Expand if defined

The construct

$$ifdef NAME
TEXT1
$$else
TEXT2
$$endif

is replaced with the expansion of TEXT1 if the environment variable NAME is defined (including if it has a null value) and to TEXT2 otherwise.

If the construct begins with $$ifndef, the sense is inverted.

Expand if set

The construct

$$ifset NAME
TEXT1
$$else
TEXT2
$$endif

is replaced with the expansion of TEXT1 if the environment variable NAME is set and has a non-null value and to TEXT2 otherwise.

If the construct begins with $$ifnset, the sense is inverted.

In the conditional constructs above, the $$else part is optional.

Optional whitespace allowed between the beginning of the line and the $$ marker, as well as between it and the keyword. This allows for indenting the nested constructs in a more natural way, e.g.:

$$ifdef LOG_HOST
$$ ifdef LOG_PORT
  logger $LOG_HOST:$LOG_PORT;
$$ else
  logger $LOG_HOST
$$ endif
$$endif

Setting and unsetting variables
$$set NAME

Sets the variable NAME to empty string.

$$set NAME "STRING"

Sets the variable NAME STRING. Within STRING, each occurrence of a backslash followed by another character is replaced by that character alone.

$$unset NAME

Unsets the variable NAME.

Quoting and escaping
To deprive the $ character of its special meaning, precede it with a backslash. For example:

\${NAME}

To reproduce a portion of text verbatim, enclose it in $( and ).

Changing the sigil
If the use of $ character to indicate variable substitution is not desirable for some reason, it can be changed using the −S command line option. The argument to that option is the character to use instead of $. Only four characters are eligible for such use: @, %, &, and #. For example, the command xenv -S @ will treat $ as a regular character, but will expand the constructs:

@variable
@{variable}
@{variable:-word}
@{variable:=word}
@{variable:?word}
@{variable:+word}
@{variable:|word1|word2}

Additionally, comments will be denoted by @{* ... *}, and @( ... ) will be used as quotation marks.

Notice, that this does not affect the keywords that begin with $$ (e.g. $$set is still understood).

OPTIONS

	−h		Print a short command line summary and exit.
	−n		Dry-run mode. Process the input files without producing any output. Report any errors. Useful together with the −u option to discover undefined variables.
	−r		Retain references to undefined variables in output. By default, an undefined variable expands to an empty string. This option instructs xenv to reproduce the variable reference verbatim in the output. Naturally, this affects only $X and ${X} references.

−S CHAR

Changes sigil (a character that starts variable substitution) to CHAR. Allowed characters are: $ (the default), @, %, &, and #.

−s

Generate synchronization directives, i.e. lines of the form #line NUM "FILE", which mean that the following line originated at line NUM in file FILE.

Synchronization directives are emitted when variable or preprocessor directive expansion causes removal or insertion of one or more lines to the output. Each synchronization directive occupies a single line by itself. If a synchronization discrepancy occurs in the middle of an output line, emission of the synchronization directive is delayed until the next newline that does not occur in the middle of a quoted string (both single and double quotes are understood).

−u

Treat unset variables as an error.

−D NAME[=VALUE]

Define environment variable NAME to the VALUE, or an empty string, if it is not given.

−U NAME

Undefine the environment variable NAME.

SEE ALSO

dbe(1), m4env(1).

COPYRIGHT

Copyright © 2021 Sergey Poznyakoff <gray@gnu.org>
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---