3.5.23 `shell-str' - double quote shell string

Usage: (shell-str string)
Convert the text of the string into a double quoted string that a normal shell will process into the original string, almost. It will add the escape character \\ before two special characters to accomplish this: the backslash \\ and double quote ".

NOTE: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.

WARNING:
This function omits the extra backslash in front of a backslash, however, if it is followed by either a backquote or a dollar sign. It must do this because otherwise it would be impossible to protect the dollar sign or backquote from shell evaluation. Consequently, it is not possible to render the strings "\\$" or "\\`". The lesser of two evils.

All others characters are copied directly into the output.

The sub-shell-str variation of this routine behaves identically, except that the extra backslash is omitted in front of " instead of `. You have to think about it. I'm open to suggestions.

Meanwhile, the best way to document is with a detailed output example. If the backslashes make it through the text processing correctly, below you will see what happens with three example strings. The first example string contains a list of quoted foos, the second is the same with a single backslash before the quote characters and the last is with two backslash escapes. Below each is the result of the raw-shell-str, shell-str and sub-shell-str functions.

foo[0]           'foo' "foo" `foo` $foo
raw-shell-str -> ''\''foo'\'' "foo" `foo` $foo'
shell-str     -> "'foo' \"foo\" `foo` $foo"
sub-shell-str -> `'foo' "foo" \`foo\` $foo`

foo[1]           \'bar\' \"bar\" \`bar\` \$bar
raw-shell-str -> '\'\''bar\'\'' \"bar\" \`bar\` \$bar'
shell-str     -> "\\'bar\\' \\\"bar\\\" \`bar\` \$bar"
sub-shell-str -> `\\'bar\\' \"bar\" \\\`bar\\\` \$bar`

foo[2]           \\'BAZ\\' \\"BAZ\\" \\`BAZ\\` \\$BAZ
raw-shell-str -> '\\'\''BAZ\\'\'' \\"BAZ\\" \\`BAZ\\` \\$BAZ'
shell-str     -> "\\\\'BAZ\\\\' \\\\\"BAZ\\\\\" \\\`BAZ\\\` \\\$BAZ"
sub-shell-str -> `\\\\'BAZ\\\\' \\\"BAZ\\\" \\\\\`BAZ\\\\\` \\\$BAZ`

There should be four, three, five and three backslashes for the four examples on the last line, respectively. The next to last line should have four, five, three and three backslashes. If this was not accurately reproduced, take a look at the agen5/test/shell.test test. Notice the backslashes in front of the dollar signs. It goes from zero to one to three for the "cooked" string examples.

Arguments:
string - string to transform