execline
Software
www.skarnet.org
The execlineb program
execlineb reads and executes a script.
Interface
execlineb [ -q | -w | -W ] [ -p | -P ] -c script [ args... ]
or
execlineb [ -q | -w | -W ] [ -p | -P ] scriptfile [ args... ]
or in an executable file:
#!/command/execlineb [ -qwWpP ]
script
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.
- Starting with execline-1.05: 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 "natural" parsing, that the
execline command performs as well,
execlineb includes the following specific support:
- 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 by a single semicolon (;)
- always in one 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 tildas (~).
Here is an example: this execlineb script
makes heavy use of blocks.
execlineb parses it into a command line that looks closely like
this script.
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 unset (or
inherited from the caller if the -P option is given). 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 #,
0 or EXECLINE_STRICT, are
pushed. This is the standard, safe
behaviour. Nevertheless, it is rather costly, and may be unneeded for
small scripts: for those cases, execline-1.05 comes with two options
that bypass the environment management. Be warned that the sole 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.
- The -p option will bypass the
push phase: the current frame of positional
parameters will be overwritten. The script will not be
reentrant, just as with pre-1.05.
- 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
daemontools' or
runit's run scripts.
Please note that if you use the -p option, the
EXECLINE_STRICT variable will be inherited from the caller:
don't forget to set -q explicitly if needed. If you use the
-P option, your script may also inherit meaningless #,
0, and such variables from the caller.
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 option, each execlineb invocation uses up some space
in the environment.