/ [xenv] / xenv / index.html
To checkout: cvs -d:pserver:anonymous@cvs.gnu.org.ua:/webcvs/xenv co xenv/index.html
Puszcza

Contents of /xenv/index.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (show annotations)
Tue Jul 27 21:23:28 2021 UTC (6 months ago) by gray
Branch: MAIN
Changes since 1.5: +11 -7 lines
File MIME type: text/html
Version 2.1

1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
5 <head>
6 <title>xenv</title>
7 <!-- 2021-07-28 Wed 00:21 -->
8 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
9 <meta name="generator" content="Org-mode" />
10 <meta name="author" content="Sergey Poznyakoff" />
11 <style type="text/css">
12 <!--/*--><![CDATA[/*><!--*/
13 .title { text-align: center; }
14 .todo { font-family: monospace; color: red; }
15 .done { color: green; }
16 .tag { background-color: #eee; font-family: monospace;
17 padding: 2px; font-size: 80%; font-weight: normal; }
18 .timestamp { color: #bebebe; }
19 .timestamp-kwd { color: #5f9ea0; }
20 .right { margin-left: auto; margin-right: 0px; text-align: right; }
21 .left { margin-left: 0px; margin-right: auto; text-align: left; }
22 .center { margin-left: auto; margin-right: auto; text-align: center; }
23 .underline { text-decoration: underline; }
24 #postamble p, #preamble p { font-size: 90%; margin: .2em; }
25 p.verse { margin-left: 3%; }
26 pre {
27 border: 1px solid #ccc;
28 box-shadow: 3px 3px 3px #eee;
29 padding: 8pt;
30 font-family: monospace;
31 overflow: auto;
32 margin: 1.2em;
33 }
34 pre.src {
35 position: relative;
36 overflow: visible;
37 padding-top: 1.2em;
38 }
39 pre.src:before {
40 display: none;
41 position: absolute;
42 background-color: white;
43 top: -10px;
44 right: 10px;
45 padding: 3px;
46 border: 1px solid black;
47 }
48 pre.src:hover:before { display: inline;}
49 pre.src-sh:before { content: 'sh'; }
50 pre.src-bash:before { content: 'sh'; }
51 pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
52 pre.src-R:before { content: 'R'; }
53 pre.src-perl:before { content: 'Perl'; }
54 pre.src-java:before { content: 'Java'; }
55 pre.src-sql:before { content: 'SQL'; }
56
57 table { border-collapse:collapse; }
58 caption.t-above { caption-side: top; }
59 caption.t-bottom { caption-side: bottom; }
60 td, th { vertical-align:top; }
61 th.right { text-align: center; }
62 th.left { text-align: center; }
63 th.center { text-align: center; }
64 td.right { text-align: right; }
65 td.left { text-align: left; }
66 td.center { text-align: center; }
67 dt { font-weight: bold; }
68 .footpara:nth-child(2) { display: inline; }
69 .footpara { display: block; }
70 .footdef { margin-bottom: 1em; }
71 .figure { padding: 1em; }
72 .figure p { text-align: center; }
73 .inlinetask {
74 padding: 10px;
75 border: 2px solid gray;
76 margin: 10px;
77 background: #ffffcc;
78 }
79 #org-div-home-and-up
80 { text-align: right; font-size: 70%; white-space: nowrap; }
81 textarea { overflow-x: auto; }
82 .linenr { font-size: smaller }
83 .code-highlighted { background-color: #ffff00; }
84 .org-info-js_info-navigation { border-style: none; }
85 #org-info-js_console-label
86 { font-size: 10px; font-weight: bold; white-space: nowrap; }
87 .org-info-js_search-highlight
88 { background-color: #ffff00; color: #000000; font-weight: bold; }
89 /*]]>*/-->
90 </style>
91 <link rel="stylesheet" type="text/css" href="style.css" />
92 <script type="text/javascript">
93 /*
94 @licstart The following is the entire license notice for the
95 JavaScript code in this tag.
96
97 Copyright (C) 2012-2013 Free Software Foundation, Inc.
98
99 The JavaScript code in this tag is free software: you can
100 redistribute it and/or modify it under the terms of the GNU
101 General Public License (GNU GPL) as published by the Free Software
102 Foundation, either version 3 of the License, or (at your option)
103 any later version. The code is distributed WITHOUT ANY WARRANTY;
104 without even the implied warranty of MERCHANTABILITY or FITNESS
105 FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
106
107 As additional permission under GNU GPL version 3 section 7, you
108 may distribute non-source (e.g., minimized or compacted) forms of
109 that code without the copy of the GNU GPL normally required by
110 section 4, provided you include this license notice and a URL
111 through which recipients can access the Corresponding Source.
112
113
114 @licend The above is the entire license notice
115 for the JavaScript code in this tag.
116 */
117 <!--/*--><![CDATA[/*><!--*/
118 function CodeHighlightOn(elem, id)
119 {
120 var target = document.getElementById(id);
121 if(null != target) {
122 elem.cacheClassElem = elem.className;
123 elem.cacheClassTarget = target.className;
124 target.className = "code-highlighted";
125 elem.className = "code-highlighted";
126 }
127 }
128 function CodeHighlightOff(elem, id)
129 {
130 var target = document.getElementById(id);
131 if(elem.cacheClassElem)
132 elem.className = elem.cacheClassElem;
133 if(elem.cacheClassTarget)
134 target.className = elem.cacheClassTarget;
135 }
136 /*]]>*///-->
137 </script>
138 </head>
139 <body>
140 <div id="content">
141 <h1 class="title">xenv</h1>
142 <div id="table-of-contents">
143 <h2>Table of Contents</h2>
144 <div id="text-table-of-contents">
145 <ul>
146 <li><a href="#sec-1">1. Overview</a></li>
147 <li><a href="#sec-2">2. Rationale</a></li>
148 <li><a href="#sec-3">3. Variable references</a></li>
149 <li><a href="#sec-4">4. Command substitution</a></li>
150 <li><a href="#sec-5">5. Documentation</a></li>
151 <li><a href="#sec-6">6. Downloads</a>
152 <ul>
153 <li><a href="#sec-6-1">6.1. Other references:</a></li>
154 </ul>
155 </li>
156 <li><a href="#sec-7">7. Bug reports</a></li>
157 <li><a href="#sec-8">8. Copyright</a></li>
158 </ul>
159 </div>
160 </div>
161 <div id="outline-container-sec-1" class="outline-2">
162 <h2 id="sec-1"><span class="section-number-2">1</span> Overview</h2>
163 <div class="outline-text-2" id="text-1">
164 <p>
165 <b>Xenv</b> is a text preprocessor that performs environment variable
166 expansion and shell command substitution on the input text.
167 Text is read from the standard input and expanded text goes to the
168 standard output.
169 </p>
170 </div>
171 </div>
172
173 <div id="outline-container-sec-2" class="outline-2">
174 <h2 id="sec-2"><span class="section-number-2">2</span> Rationale</h2>
175 <div class="outline-text-2" id="text-2">
176 <p>
177 It became a de-facto practice to configure docker containers using
178 environment variables. The method is obvious when configuration
179 is consumed by some programming language (<b>php</b>, <b>python</b> or the
180 like). It is difficult, however, to expand environment variables
181 in configuration files of the utilities that provide no mechanism for
182 this (such as <b>mysqld</b> or <b>ldap</b>, for instance).
183 </p>
184
185 <p>
186 To solve this, it has been proposed to use <a href="https://www.gnu.org/software/m4">GNU m4</a>, either with a set
187 of <a href="http://puszcza.gnu.org.ua/software/pies/manual/Docker-Entrypoint.html">special macros</a> or via a <a href="http://git.gnu.org.ua/cgit/gsc/m4env.git/">wrapper program</a>. However, the
188 shortcomings of both approaches became apparent and the need of
189 something more convenient motivated the inception of this utility.
190 </p>
191 </div>
192 </div>
193
194 <div id="outline-container-sec-3" class="outline-2">
195 <h2 id="sec-3"><span class="section-number-2">3</span> Variable references</h2>
196 <div class="outline-text-2" id="text-3">
197 <p>
198 The input text can reference the environment variables using the
199 following constructs:
200 </p>
201
202 <ul class="org-ul">
203 <li>$ <span class="underline">variable</span>
204
205 <p>
206 The value of <span class="underline">variable</span> is substituted.
207 </p>
208 </li>
209
210 <li>${ <span class="underline">variable</span> }
211
212 <p>
213 The value of <span class="underline">variable</span> is substituted.
214 </p>
215 </li>
216
217 <li>${ <span class="underline">variable</span> :- <span class="underline">word</span> }
218
219 <p>
220 If <span class="underline">variable</span> is unset or null, the expansion of <span class="underline">word</span> is substituted.
221 Otherwise, the value of <span class="underline">variable</span> is substituted.
222 </p>
223 </li>
224
225 <li>${ <span class="underline">variable</span> := <span class="underline">word</span> }
226
227 <p>
228 If <span class="underline">variable</span> is unset or null, the expansion of <span class="underline">word</span> is
229 assigned to <span class="underline">variable</span>. The value of <span class="underline">variable</span> is then substituted.
230 </p>
231 </li>
232
233 <li>${ <span class="underline">variable</span> :? <span class="underline">word</span> }
234
235 <p>
236 If <span class="underline">variable</span> is null or unset, the expansion of <span class="underline">word</span> (or a
237 message to that effect if word is not present) is output to standard error.
238 Otherwise, the value of <span class="underline">variable</span> is substituted.
239 </p>
240 </li>
241
242 <li>${ <span class="underline">variable</span> :+ <span class="underline">word</span> }
243
244 <p>
245 If <span class="underline">variable</span> is null or unset, nothing is substituted, otherwise the
246 expansion of <span class="underline">word</span> is substituted.
247 </p>
248 </li>
249
250 <li>${ <span class="underline">variable</span> :| <span class="underline">word1</span> | <span class="underline">word2</span> }
251
252 <p>
253 Unless <span class="underline">variable</span> is null or unset, substitutes the expansion of
254 <span class="underline">word1</span>, otherwise the expansion of <span class="underline">word2</span>.
255 </p>
256 </li>
257 </ul>
258
259 <p>
260 In the constructs above the colon can be omitted, resulting in a test
261 only for a variable that is unset.
262 </p>
263
264 <p>
265 The <span class="underline">word</span> part is treated exactly as in Bourne shell. In particular,
266 it can contain quoted parts, which are interpreted as follows:
267 the quotes are removed, the text enclosed in double quotes is
268 subject to both variable substitution and command expansion, whereas
269 the text between single quotes is reproduced as is. Within double
270 quoted part, a backslash can be used to escape the sigil character,
271 double or single quote character and itself.
272 </p>
273
274 <p>
275 The <span class="underline">indirection operator</span> <b>$</b> can be changed to another symbol using
276 the command line option <code>-S</code>.
277 </p>
278 </div>
279 </div>
280
281 <div id="outline-container-sec-4" class="outline-2">
282 <h2 id="sec-4"><span class="section-number-2">4</span> Command substitution</h2>
283 <div class="outline-text-2" id="text-4">
284 <p>
285 A construct
286 </p>
287
288 <pre class="example">
289 $(command)
290 </pre>
291
292 <p>
293 is replaced with the output of <span class="underline">command</span>. <b>Xenv</b> performs
294 substitution by running
295 </p>
296
297 <pre class="example">
298 $SHELL -c command
299 </pre>
300
301 <p>
302 and replacing the construct with the standard output of the command,
303 with any trailing newlines removed. If the <code>SHELL</code> variable is not
304 set, the default <code>/bin/sh</code> is assumed.
305 </p>
306
307 <p>
308 Execution time of command substitution can be limited using the <code>-t</code>
309 command line option.
310 </p>
311 </div>
312 </div>
313
314 <div id="outline-container-sec-5" class="outline-2">
315 <h2 id="sec-5"><span class="section-number-2">5</span> Documentation</h2>
316 <div class="outline-text-2" id="text-5">
317 <p>
318 The documentaion for <b>xenv</b> is <a href="http://man.gnu.org.ua/manpage/?1+xenv">available online</a>.
319 </p>
320 </div>
321 </div>
322
323 <div id="outline-container-sec-6" class="outline-2">
324 <h2 id="sec-6"><span class="section-number-2">6</span> Downloads</h2>
325 <div class="outline-text-2" id="text-6">
326 <p>
327 Download the <a href="https://download.gnu.org.ua/release/xenv/xenv-2.1.tar.gz">latest version</a> of <b>xenv</b>.
328 </p>
329
330 <p>
331 The tarball is signed using the author's GPG key. To verify it,
332 import the author's key using the following command:
333 </p>
334
335 <div class="org-src-container">
336
337 <pre class="src src-shell-script">gpg --keyserver keyserver.ubuntu.com --recv-keys 3602B07F55D0C732
338 </pre>
339 </div>
340
341 <p>
342 (you may also try other key servers such as pgp.mit.edu)
343 </p>
344
345 <p>
346 Then, download the <a href="https://download.gnu.org.ua/release/xenv/xenv-2.1.tar.gz.sig">signature</a> file and run
347 </p>
348
349 <div class="org-src-container">
350
351 <pre class="src src-shell-script">gpg --verify xenv-2.1.tar.gz
352 </pre>
353 </div>
354
355 <p>
356 Checksums for this tarball are <a href="https://puszcza.gnu.org.ua/forum/forum.php?forum_id=1285">listed here</a>.
357 </p>
358
359 <p>
360 This and other versions of the utility can be downloaded from
361 <a href="https://download.gnu.org.ua/release/xenv">https://download.gnu.org.ua/release/xenv</a> (the <b>ftp</b> protocol
362 is also supported).
363 </p>
364 </div>
365
366 <div id="outline-container-sec-6-1" class="outline-3">
367 <h3 id="sec-6-1"><span class="section-number-3">6.1</span> Other references:</h3>
368 <div class="outline-text-3" id="text-6-1">
369 <ul class="org-ul">
370 <li><a href="https://puszcza.gnu.org.ua/projects/xenv">Project development page</a>
371 </li>
372
373 <li><a href="http://git.gnu.org.ua/cgit/xenv.git">Git repository</a>
374 </li>
375 </ul>
376 </div>
377 </div>
378 </div>
379
380 <div id="outline-container-sec-7" class="outline-2">
381 <h2 id="sec-7"><span class="section-number-2">7</span> Bug reports</h2>
382 <div class="outline-text-2" id="text-7">
383 <p>
384 If you think you found a bug in <b>xenv</b> or in its documentation, please
385 send a mail to <a href="mailto:gray@gnu.org">Sergey Poznyakoff</a> or use the web <a href="https://puszcza.gnu.org.ua/bugs/?group=xenv">bug tracker</a>.
386 </p>
387 </div>
388 </div>
389
390 <div id="outline-container-sec-8" class="outline-2">
391 <h2 id="sec-8"><span class="section-number-2">8</span> Copyright</h2>
392 <div class="outline-text-2" id="text-8">
393 <p>
394 Copyright (C) 2021 Sergey Poznyakoff
395 </p>
396
397 <p>
398 Permission is granted to anyone to make or distribute verbatim copies
399 of this document as received, in any medium, provided that the
400 copyright notice and this permission notice are preserved,
401 thus giving the recipient permission to redistribute in turn.
402 </p>
403
404 <p>
405 Permission is granted to distribute modified versions
406 of this document, or of portions of it,
407 under the above conditions, provided also that they
408 carry prominent notices stating who last changed them.
409 </p>
410 </div>
411 </div>
412 </div>
413 <div id="postamble" class="status">
414 <p class="author">Author: Sergey Poznyakoff</p>
415 <p class="date">Created: 2021-07-28 Wed 00:21</p>
416 <p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 25.3.1 (<a href="http://orgmode.org">Org</a> mode 8.2.10)</p>
417 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
418 </div>
419 </body>
420 </html>

Send suggestions and bug reports to Sergey Poznyakoff
ViewVC Help
Powered by ViewVC 1.1.20