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/execlineb.html | 246 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 doc/execlineb.html (limited to 'doc/execlineb.html') diff --git a/doc/execlineb.html b/doc/execlineb.html new file mode 100644 index 0000000..64f29bd --- /dev/null +++ b/doc/execlineb.html @@ -0,0 +1,246 @@ + + + + + execline: the execlineb command + + + + + + +

+execline
+Software
+skarnet.org +

+ +

The `execlineb` program

+ +

+execlineb reads and executes a script. +

+ +

Interface

+ +

+     execlineb [ -q | -w | -W ] [ -p | -P | -S nmin ] -c script [ args... ]
+

+ +

+or +

+ +

+     execlineb [ -q | -w | -W ] [ -p | -P | -S nmin ] scriptfile [ args... ]
+

+ +

+or in an executable file: +

+ +

+#!/command/execlineb [ -qwWpPSnmin ]
+script
+

+ +

+ Parsing phase. +

+ +

execlineb reads and parses the script it is given. +It exits 100 on a syntax error and 111 on a temporary error. +It makes an argv, i.e. a system command line, with the +parsed script. If the argv is empty, execlineb +exits 0.

+ +

+ Environment management phase. +

+ +

Pushing the current stack frame. If neither the +-p nor the -P nor the -S option is set: +execlineb pushes +the current positional parameters, i.e. environment variables that +start with #, 0, 1, ..., 9. +To get the previous values back, use +emptyenv -P.
Setting the new stack frame. If neither the -P +nor the -S option is set: +
- execlineb sets the # environment variable to +the number n of args it is given.
- It sets the 0 environment variable to the name +of the script - or to the execlineb invocation name +if the -c option is used.
- It sets the 1, 2, ... n +environment variables to the different args.

+ +

+ Execution phase. +

+ +

execlineb executes into the argv it +has built from the script. +There is only one command line for the +whole script: the execlineb binary is a launcher, +whose sole purpose is to execute into that command line. It does +not stay in memory like a traditional interpreter would.

+ +

Options

+ +

-c script : execute script, do not +look for a file.

+ +

+ See below for the other options. +

+ +

Syntax of scripts

+ +

+ An execlineb script is a string that must not contain the null character. +execlineb parses it and divides it into words. + + The parser recognizes the following components: +

+ +

whitespace is defined as spaces, tabs, newlines and +carriage returns. Words are always separated by whitespace.
A quoted string begins with a doublequote (") +and ends with another doublequote. Quoted doublequotes must be prefixed +by a backslash (\). Quoted strings always evaluate to exactly +one word. For instance, "" evaluates to the empty word.
The \a, \b, \t, \n, \v, +\f, and \r sequences are recognized in quoted +strings, and are converted to the ASCII numbers 7, 8, 9, 10, 11, 12 and +13 respectively.
Inside a quoted string, backslashed +newlines disappear completely.
\0xab sequences are recognized in quoted strings +and evaluate to ASCII hexadecimal number ab.
\0abc sequences are recognized in quoted strings +and evaluate to ASCII octal number abc.
\abc sequences are recognized in quoted strings +and evaluate to ASCII decimal number abc. a must not +be zero.
A comment starts with a # and ends with the line. Comments +are not recognized inside quoted strings.
Anything else is an unquoted string, that can evaluate to +zero or more words.
Any character can be escaped in unquoted strings by prepending +it with a backslash. It works the same way in quoted strings, except +for the special sequences described above.

+ +

+ You can see an example of distinct execlineb components +here. +

+ +

+ In addition to that simple lexing, +execlineb performs the following higher-level parsing: +

+ +

A word consisting of a single opening brace ({) +increments an internal level counter, blevel, and disappears from the +argv. Quoted open braces do not have that behaviour.
A word consisting of a single closing brace (}) +decrements blevel, and is replaced with the empty word. +Quoted closing braces do not have that behaviour.
If execlineb finds that braces are unmatched (i.e. +blevel goes below 0 during the parsing, or is not 0 at the end +of the script), it exits 100 with an error message.
execlineb automatically quotes +blocks. Which means that everytime it +finds a word, it prepends it with blevel spaces.

+ +

+For proper execution, the sequence of words must follow +the execline grammar. +

+ +

Options for block syntax checking

+ +

+ External execline commands that read blocks, like +foreground, use the EXECLINE_STRICT +environment variable: if it is set to 1, they will print a warning message +on stderr if they find their blocks not to be properly quoted. If it is set +to 2, they will also die. If it is set to 0, or unset, they won't complain +at all. +

+ +

+ Normally the EXECLINE_STRICT environment variable is +inherited from the caller. You can +force it unset, set to 1, or set to 2 by giving respectively the +-q, -w or -W option to execlineb. +

+ +

Options for environment management

+ +

+ Normally, execline scripts are reentrant: environment variables +potentially overwritten by execlineb, such as # or +0, are +pushed. This is the standard, safe +behaviour. Nevertheless, it is rather costly, and may be unneeded for +small scripts: for those cases, execline comes with two options +that bypass the environment management. Be warned that the purpose +of these options is optimization, and you should not +use them if you're not familiar with the way execlineb uses the +environment to store positional parameters. Alternatively, there's also +an integrated substitution mechanism that doesn't make use +of the environment at all. +

+ +

The -p option will bypass the +push phase: the current frame of positional +parameters will be overwritten. The script will not be +reentrant.
The -P option will bypass positional parameter handling +completely: the environment will not be pushed, and positional +parameters will be ignored. execlineb -P -c "script" is +equivalent to, but more efficient than, execlineb -c +"emptyenv -P script". You should use the -P option +only in standalone scripts that take no arguments, such as +s6's or +runit's run scripts.
The -S nmin option will substitute the +positional parameters - up to at least nmin - but will not +push nor set environment +variables. execlineb -S3 -c "script" is equivalent to, +but more efficient than, execlineb -c "elgetpositionals -P3 emptyenv +-P script". See +the details.

+ +

Current limitations

+ +

+ execlineb builds and executes a unique +argv with the script: hence scripts are subject to OS-dependent +limitations such as the kernel buffer size for argv and envp + - at least 64 kB on most systems. This means that execlineb cannot +execute arbitrarily large scripts. Be careful with deeply nested scripts too: +without the -p/-P/-S option, each execlineb +invocation uses up some space in the environment. +

+ + + -- cgit v1.3.1