From f316a2ed52195135a35e32d7096e876357c48c69 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 20:03:23 +0000 Subject: initial commit: rc for execline-2.0.0.0 --- doc/multisubstitute.html | 121 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 doc/multisubstitute.html (limited to 'doc/multisubstitute.html') diff --git a/doc/multisubstitute.html b/doc/multisubstitute.html new file mode 100644 index 0000000..6400187 --- /dev/null +++ b/doc/multisubstitute.html @@ -0,0 +1,121 @@ + + + + + execline: the multisubstitute command + + + + + + +

+execline
+Software
+skarnet.org +

+ +

The `multisubstitute` program

+ +

+multisubstitute performs several substitutions at once in +its argv, then executes another program. +

+ +

Interface

+ +

+ In an execlineb script: +

+ +

+     multisubstitute
+     {
+       [ define [ -n ] [ -s ] [ -C | -c ] [ -d delim ] variable value ]
+       [ importas [ -i | -D default ] [ -n ] [ -s ] [ -C | -c ] [ -d delim ] variable envvar ]
+       [ import [ -i | -D default ] [ -n ] [ -s ] [ -C | -c ] [ -d delim ] envvar ]
+       [ elglob [ -v ] [ -w ] [ -s ] [ -m ] [ -e ] [ -0 ] variable pattern ]
+       [ elgetpositionals [ -P sharp ] ]
+       [ multidefine value { variable... } ]
+       ...
+     }
+     prog...
+

+ +

multisubstitute reads a block +containing a series of substitution commands. It performs all +those substitutions on +prog... in parallel. Check the relevant documentation page +to learn about the syntax of each substitution command.
multisubstitute then execs into the modified prog....

+ +

Options

+ +

If a backtick directive was given with the -i option, +and command crashes or exits nonzero, multisubstitute will +also exit with the same exit code.
If an import or importas directive was given with the +-i option, and the looked up variable is undefined, +multisubstitute will exit 100.

+ +

Rationale

+ +

Security

+ +

+ multisubstitute can be used to avoid unwanted +serial substitutions. Consider the following script: +

+ +

+ #!/command/execlineb
+ export A wrong
+ define B ${A}
+ import A
+ echo ${B}
+

+ +

+ Running it will print wrong, because A is substituted +after B. On the contrary, the following script: +

+ +

+ #!/command/execlineb
+ export A wrong
+ multisubstitute
+ {
+   define B ${A}
+   import A
+ }
+ echo ${B}
+

+ +

+ will print ${A}, because A and B are substituted at the same +time. Serial substitution may be what you want - but when in doubt, +always perform parallel substitution. +

+ +

Efficiency

+ +

+Substitution is a costly mechanism: +the whole argv is read three times and rewritten twice. +Serial substitution multiplies the cost by the number of +substitutions, whereas parallel substitution pays the price only once. +

+ +

Credits

+ +

+Paul Jarc first originated the +idea of the multisubstitute command and a possible syntax. +

+ + + -- cgit v1.2.3