EXECLINE-PUSHENV(7)

📦 version 2.9.9.2, in nixpkgs unstable

💖 EXECLINE-PUSHENV(7) 💖

Okay so this is the execline-pushenv(7) page from the Miscellaneous Information Manual, and we are about to talk about pushing and popping the environment like it's a group chat with too many pinned messages 🫶✨

🌸 NAME 🌸

execline-pushenv — pushing and popping the environment 💅

🦋 DESCRIPTION 🦋

So the execlineb(1) launcher can slide your positional parameters — aka the arguments you gave your script — straight into the environment. The # variable holds the number of arguments; the 0 variable holds the name of your execline script; the 1 variable holds the first argument; and yeah, it keeps going like that, bestie.

Up to execline-1.04, this could cause drama with nested scripts: the inner script would overwrite the outer script's parameters, and there was literally no way to get them back. Especially iconic problem: writing execline commands in the execline language via the runblock(1) command was impossible. Not the vibe 😭

🎀 Push 🎀

To fix that whole situation, execline now has a kind of environment stack. When execlineb(1) reads the arguments, it does not overwrite the positional parameters — it pushes them onto the 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. Then the script runs, and commands like elgetpositionals(1) use the current frame of positional parameters without paying attention to the deeper levels. It's giving “look at the top layer only” energy 👑

🦋 Pop 🦋

When you're done with the arguments, it is advisable to drop the current frame and pop the environment stack so it goes 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. Slay, automatic cleanup 💅

🌈 Substituting positional parameters without touching the environment 🌈

Most of the time, you just need to substitute the positional parameters in your execline script — you 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. Obsessed with the efficiency tbh ✨

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. Clean, considerate, main character behavior 💖

👑 SEE ALSO 👑

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)

Cute sign-off bestie: this page is from Debian, dated February 8, 2021 — mwah 🎀💖

📦 where this page comes from