MULTISUBSTITUTE(1)

NAME
multisubstitute - perform several substitutions at once in its argv, then execute another program

SYNOPSIS
In an execlineb(1) script:

multisubstitute {
[ define [-N | -n] [-s] [-C | -c] [-d delim] variable value]

[ importas [-i | -D default] [-N | -n] [-s] [-C | -c] [-d delim] variable envvar]

[ importas -S [-i | -D default] [-N | -n] [-s] [-C | -c] [-d delim] envvar]

[ elglob [-v] [-w] [-s] [-m] [-e] [-0] variable pattern]

[ elgetpositionals [-P sharp]]

[ multidefine value { variable... }]

...
}

prog...

DESCRIPTION
multisubstitute reads a block ( cf. execline-block(7)) containing a series of substitution commands. It performs all those substitutions ( cf. execline-substitute(7)) on prog... in parallel. Check the relevant documentation page to learn about the syntax of each substitution command.

multisubstitute then exec(3) s into the modified prog....

OPTIONS
If an ‘importas’ directive was given with the -i option, and the looked up variable is undefined, multisubstitute will exit 100. Like its direct program equivalent (cf. importas(1)), ‘importas’ has two modes: the normal one, which takes a variable and an envvar as argument and imports envvar under the name variable, and the -S one, which only takes one argument and imports an environment variable under the same name.

  Rationale
Security

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

    #!/command/execlineb
    export A wrong
    define B ${A}
    importas A 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}
      importas A 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 ( cf. execline-substitute(7)) 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[1] first originated the idea of the multisubstitute command and a possible syntax.

SEE ALSO
define(1), elgetpositionals(1), elglob(1), execlineb(1), importas(1), multidefine(1), exec(3), execline-block(7), execline-substitute(7)

[1] https://code.dogmap.org/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/execline/multisubstitute.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)