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/el_pushenv.html | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 doc/el_pushenv.html (limited to 'doc/el_pushenv.html') diff --git a/doc/el_pushenv.html b/doc/el_pushenv.html new file mode 100644 index 0000000..2ae16dd --- /dev/null +++ b/doc/el_pushenv.html @@ -0,0 +1,173 @@ + + + + + execline: pushing and popping the environment + + + + + + +

+execline
+Software
+skarnet.org +

+ +

Pushing and popping the environment

+ +

+ The execlineb 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 command was impossible. +

+ + + +

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

+ + + +

+ Same goes for the other positional parameters. +

+ +

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

+ + + +

+ 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: +

+ + + +

+ Again, same goes for the other positional parameters.
+The runblock command will perform that +pop operation automatically; the standard "manual" way to +perform it is to use the emptyenv -P command. +

+ +

A pop example

+ +

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

+ + + +

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 and +emptyenv 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): +

+ + + + + -- cgit v1.3.1