diff options
Diffstat (limited to 'index.org')
-rw-r--r-- | index.org | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/index.org b/index.org new file mode 100644 index 0000000..9c35b07 --- /dev/null +++ b/index.org @@ -0,0 +1,142 @@ +* 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. + +* 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 [[http://puszcza.gnu.org.ua/software/pies/][GNU pies]] as entrypoint for images I produce. It uses +[[https://www.gnu.org/software/m4][m4]] for preprocessing its configuration. Several mechanisms have +been proposed for expanding environment variables in it: implementing +special +[[http://puszcza.gnu.org.ua/software/pies/manual/Docker-Entrypoint.html][macros]] or a [[http://git.gnu.org.ua/cgit/gsc/m4env.git/][wrapper program]]. However, the shortcomings of both +became apparent and the need of something more convenient motivated +the inception of this utility. + +* 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*. + +* Documentation + +The documentaion for *xenv* is [[http://man.gnu.org.ua/manpage/?1+xenv][available online]]. + +* Downloads + +Download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz][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: + +#+BEGIN_SRC shell-script +gpg --keyserver keys.gnupg.net --recv-keys 3602B07F55D0C732 +#+END_SRC + +Then, download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz.sig][signature]] file and run + +#+BEGIN_SRC shell-script +gpg --verify xenv-1.1.tar.gz +#+END_SRC + +Checksums for this tarball are [[https://puszcza.gnu.org.ua/forum/forum.php?forum_id=1270][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). + +** Other references: + +- [[https://puszcza.gnu.org.ua/projects/xenv][Project development page]] + +- [[http://git.gnu.org.ua/cgit/xenv.git][Git repository]] + +* Bug reports + +If you think you found a bug in *xenv* or in its documentation, please +send a mail to [[mailto:gray@gnu.org][Sergey Poznyakoff]] or use the web [[https://puszcza.gnu.org.ua/bugs/?group=xenv][bug tracker]]. + +* 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. + +* Document settings :noexport: + +Please ignore this section. It supplies the variables necessary for +proper rendering of this document. + +:PROPERTIES: +:VISIBILITY: folded +:END: + +#+TITLE: xenv +#+STARTUP: showall +#+EXCLUDE_TAGS: noexport +#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" /> +#+OPTIONS: ^:nil + +# Local Variables: +# mode: org +# paragraph-separate: "[ ^L]*$" +# version-control: never +# End: |