env: add -S/--split-string option

Adopted from FreeBSD's env(1), useful for specifing multiple
parameters on a shebang (#!) script line, e.g:

   #!/usr/bin/env -S perl -w -T

Discussed in https://lists.gnu.org/r/coreutils/2018-04/msg00011.html

* src/env.c (valid_escape_sequence,escape_char,scan_varname,
  extract_varname,validate_split_str,build_argv,
  parse_split_string): New functions.
  (main): Process new option and call parse_split_string.
  (usage): Mention new option.
* tests/misc/env-S.pl: Test new option from the command line.
* tests/misc/env-S-script.sh: Test new option from shebang scripts.
* tests/local.mk (all_tests): Add new tests.
* man/env.x (OPTIONS): Show a brief example of -S usage and point to
the full documentation for more information.
* doc/coreutils.texi (env invocation): Detail usage of -S/--split-string
option.
* NEWS: Mention new option.

1 files changed, 35 insertions, 0 deletions

diff --git a/man/env.x b/man/env.x
index 914fb9cdc..fb6665b81 100644
--- a/man/env.x
+++ b/man/env.x
@@ -1,4 +1,39 @@
+'\" Copyright (C) 1998-2018 Free Software Foundation, Inc.
+'\"
+'\" This is free software.  You may redistribute copies of it under the terms
+'\" of the GNU General Public License <https://www.gnu.org/licenses/gpl.html>.
+'\" There is NO WARRANTY, to the extent permitted by law.
 [NAME]
 env \- run a program in a modified environment
 [DESCRIPTION]
 .\" Add any additional description here
+[OPTIONS]
+.SS "\-S/\-\-split\-string usage in scripts"
+The
+.B \-S
+option allows specifing multiple parameters in a script.
+Running a script named
+.B 1.pl
+containing the following first line:
+.PP
+.RS
+.nf
+#!/usr/bin/env \-S perl \-w \-T
+...
+.fi
+.RE
+.PP
+Will execute
+.B "perl \-w \-T 1.pl".
+.PP
+Without the
+.B '\-S'
+parameter the script will likely fail with:
+.PP
+.RS
+.nf
+/usr/bin/env: 'perl \-w \-T': No such file or directory
+.fi
+.RE
+.PP
+See the full documentation for more details.