/*=gfunc sub_shell_str
*
* what: back quoted (sub-)shell string
* general_use:
*
* exparg: string, string to transform
*
* doc:
* This function is substantially identical to @code{shell-str}, except
* that the quoting character is @code{`} and the "leave the escape alone"
* character is @code{"}.
=*/
SCM
ag_scm_sub_shell_str(SCM obj)
{
return shell_stringify(obj, (unsigned char)'`');
}
/*=gfunc shell_str
*
* what: double quote shell string
* general_use:
*
* exparg: string, string to transform
*
* doc:
*
* 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 @code{\\} before two special characters to
* accomplish this: the backslash @code{\\} and double quote @code{"}.
*
* @strong{Notice}: some shells will not correctly handle unusual
* non-printing characters. This routine works for most reasonably
* conventional ASCII strings.
*
* @strong{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 @code{sub-shell-str} variation of this routine behaves identically,
* except that the extra backslash is omitted in front of @code{"} instead
* of @code{`}. 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 @code{foo}s, 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
* @code{raw-shell-str}, @code{shell-str} and @code{sub-shell-str} functions.
*
* @example
* foo[0] ''foo'' 'foo' "foo" `foo` $foo
* raw-shell-str -> \'\''foo'\'\'' '\''foo'\'' "foo" `foo` $foo'
* shell-str -> "''foo'' 'foo' \"foo\" `foo` $foo"
* sub-shell-str -> `''foo'' '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`
* @end example
*
* 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.
=*/
SCM
ag_scm_shell_str(SCM obj)
{
return shell_stringify(obj, (unsigned)'"');
}
