execline: the multisubstitute command
Keywords: execline command multisubstitute

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 | -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...

- `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 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, `importas` has two modes: the normal one, which takes a variable and an envvar 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 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.