execline
Software
skarnet.org

Value transformation

You can apply 3 kinds of transformations to a value which is to be substituted for a variable: crunching, chomping and splitting. They always occur in that order.

Delimiters

The transformations work around delimiters. Delimiters are the semantic bounds of the "words" in your value. You can use any character (except the null character, which you cannot use in execline scripts) as a delimiter, by giving a string consisting of all the delimiters you want as the argument to the -d option used by substitution commands. By default, the string " \n\r\t" is used, which means that the default delimiters are spaces, newlines, carriage returns and tabs.

(The forstdin command is a small exception: by default, it only recognizes newlines as delimiters.)

Crunching

You can tell the substitution command to merge sets of consecutive delimiters into a single delimiter. For instance, to replace three consecutive spaces, or a space and 4 tab characters, with a single space. This is called crunching, and it is done by giving the -C switch to the substitution command. The remaining delimiter will always be the first in the sequence. Crunching is off by default, or if you give the -c switch.

Crunching is mainly useful when also splitting.

Chomping

Sometimes you don't want the last delimiter in a value. Chomping deletes the last character of a value if it is a delimiter. It is requested by giving the -n switch to the substitution command. You can turn it off by giving the -N switch. It is off by default unless mentioned in the documentation page of specific binaries. Note that chomping always happens after crunching, which means you can use crunching+chomping to ignore, for instance, a set of trailing spaces.

Splitting

In a shell, when you write

 $ A='foo bar' ; echo $A

the echo command is given two arguments, foo and bar. The $A value has been split, and the space between foo and bar acted as a delimiter.

If you want to avoid splitting, you must write something like

 $ A='foo bar' ; echo "$A"

The doublequotes "protect" the spaces. Unfortunately, it's easy to forget them and perform unwanted splits during script execution - countless bugs happen because of the shell's splitting behaviour.

execline provides a splitting facility, with several advantages over the shell's:

How it works

Decoding netstrings

Netstrings are a way to reliably encode strings containing arbitrary characters. execline takes advantage of this to offer a completely safe splitting mechanism. If a substitution command is given an empty delimiter string (by use of the -d "" option), the splitting function will try to interpret the value as a sequence of netstrings, every netstring representing a word. For instance, in the following command line:

 $ define -s -d "" A '1:a,2:bb,0:,7:xyz 123,1: ,' echo '$A'

the echo command will be given five arguments:

However, if the value is not a valid sequence of netstrings, the substitution command will die with an error message.

The dollarat command, for instance, can produce a sequence of netstrings (encoding all the arguments given to an execline script), meant to be decoded by a substitution command with the -d "" option.