xenv

Table of Contents

1 Overview

Xenv is a text preprocessor that expands references to environment variables in the input text to their actual values. Environment variables are referenced using POSIX-compatible shell syntax. Text is read from the standard input and expanded text goes to the standard output.

2 Rationale

It became a de-facto practice to configure docker containers using environment variables. The method is obvious when configuration is consumed by some programming language (php, python or the like). However, sometimes the need arises to expand environment variables in configuration files of the utilities that provide no mechanism for this (such as mysqld or ldap, for instance).

I often use GNU pies as entrypoint for images I produce. It uses m4 for preprocessing its configuration. Several mechanisms have been proposed for expanding environment variables in it: implementing special macros or a wrapper program. However, the shortcomings of both became apparent and the need of something more convenient motivated the inception of this utility.

3 Variable references

The input text can reference the environment variables using the following constructs:

  • $ variable

    The value of variable is substituted.

  • ${ variable }

    The value of variable is substituted.

  • ${ variable :- word }

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

  • ${ variable := word }

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

  • ${ variable :? word }

    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 }

    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.

In the constructs above the colon can be omitted, resulting in a test only for a variable that is unset.

The indirection operator $ can be changed to another symbol using the command line option -S.

4 Documentation

The documentaion for xenv is available online.

5 Downloads

Download the latest version of xenv.

The tarball is signed using the author's GPG key. To verify it, import the author's key using the following command:

gpg --keyserver keys.gnupg.net --recv-keys 3602B07F55D0C732

Then, download the signature file and run

gpg --verify xenv-1.1.tar.gz

Checksums for this tarball are listed here.

This and other versions of the utility can be downloaded from https://download.gnu.org.ua/release/xenv (the ftp protocol is also supported).

6 Bug reports

If you think you found a bug in xenv or in its documentation, please send a mail to Sergey Poznyakoff or use the web bug tracker.

7 Copyright

Copyright (C) 2021 Sergey Poznyakoff

Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and this permission notice are preserved, thus giving the recipient permission to redistribute in turn.

Permission is granted to distribute modified versions of this document, or of portions of it, under the above conditions, provided also that they carry prominent notices stating who last changed them.

Author: Sergey Poznyakoff

Created: 2021-02-14 Sun 11:43

Emacs 25.3.1 (Org mode 8.2.10)

Validate