EXECLINE-PUSHENV(7)

NAME
execline-pushenv - pushing and popping the environment

DESCRIPTION
The execlineb(1) launcher can store positional parameters, i.e. arguments given to your script, into the environment. The # variable contains the number of arguments; the 0 variable contains the name of your execline script; the 1 variable contains the first argument; and so on.

Up to execline-1.04, this could create problems with nested scripts: the inner script would overwrite the outer script's parameters, and there was no way to get them back. In particular, writing execline commands in the execline language via the runblock(1) command was impossible.

  Push
To solve that issue, execline now implements a kind of environment stack. When execlineb(1) reads the arguments, it does not overwrite the positional parameters, but pushes them on a stack:

•   # will be set to the current number of arguments

•   but if a variable named # existed before, it is renamed #:1

•   and if a variable named #:1 also existed, it is renamed #:2

•   ... and so on until #:n+1 doesn't exist.

Same goes for the other positional parameters.

The script then runs; and commands such as elgetpositionals(1) use the current frame of positional parameters, without paying attention to the deeper levels.

  Pop
When you are done with the arguments, it is advisable to drop the current frame, and pop the environment stack to get it back to its previous state:

•   # will be unset

•   but if #:1 exists, it will be renamed #

•   and if #:2 exists, it will be renamed #:1 ... and so on until #:n+1 doesn't exist.

Again, same goes for the other positional parameters. The runblock(1) command will perform that pop operation automatically; the standard “manual” way to perform it is to use the ‘emptyenv -P’ command.

  Substituting positional parameters without touching the environment
Most of the time, you just need to substitute the positional parameters in your execline script, and don't need to go through the whole elgetpositionals(1) and emptyenv(1) chain. execline comes with an integrated substitution mechanism, that does not touch the environment at all: the ‘-S n’ option.

Scripts beginning with:

    #!/command/execlineb -Sn
    foobar...

are equivalent to:

    #!/command/execlineb
    elgetpositionals -Pn
    emptyenv -P
    foobar...

So, to summarize, from most efficient (but less flexible) to least efficient (but more flexible):

•   Use ‘execlineb -P’ if you don't need positional parameters at all; for instance, in s6[1] or runit[2] run scripts.

•   Use ‘execlineb -S n’ if you need only simple positional parameter substitution in your script - no shift(1) or elgetopt(1), no ‘importas 1 1’.

•   Use ‘execlineb -p’, then elgetpositionals(1) if you don't mind overwriting the current stack of positional parameters.

•   Use execlineb(1), then elgetpositionals(1), then ‘emptyenv -P’ if you need the full power of positional parameter handling.

EXAMPLES
Suppose you want to run the long-lived program prog after printing the list of its arguments.

    #!/command/execlineb
    elgetpositionals
    foreground { echo $0 $@ }
    prog $@

will work, but will pollute prog' s environment with a set of positional parameters that have no meaning to it. A better script is:

    #!/command/execlineb
    elgetpositionals
    foreground { echo $0 $@ }
    emptyenv -P
    prog $@

which will run prog with the same environment as the script's caller.

SEE ALSO
elgetopt(1), elgetpositionals(1), emptyenv(1), execlineb(1), runblock(1), shift(1)

[1] https://skarnet.org/software/s6/

[2] http://smarden.org/runit/

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

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