Merge pull request #5943 from lilyball/string_collect

Add new `string` subcommand `string collect`

sphinx_doc_src/cmds/string.rst

@@ -6,6 +6,8 @@ string - manipulate strings
 Synopsis
 --------
 
+``string collect [(-N | --no-trim-newlines)] [STRING...]``
+
 ``string escape [(-n | --no-quoted)] [--style=xxx] [STRING...]``
 
 ``string join [(-q | --quiet)] SEP [STRING...]``
@@ -48,6 +50,17 @@ Most subcommands accept a ``-q`` or ``--quiet`` switch, which suppresses the usu
 
 The following subcommands are available.
 
+"collect" subcommand
+--------------------
+
+``string collect [(-N | --no-trim-newlines)] [STRING...]``
+
+``string collect`` collects its input into a single output argument, without splitting the output when used in a command substitution. This is useful when trying to collect multiline output from another command into a variable. Exit status: 0 if any output argument is non-empty, or 1 otherwise.
+
+If invoked with multiple arguments instead of input, ``string collect`` preserves each argument separately, where the number of output arguments is equal to the number of arguments given to ``string collect``.
+
+Any trailing newlines on the input are trimmed, just as with ``"$(cmd)"`` substitution in sh. ``--no-trim-newlines`` can be used to disable this behavior, which may be useful when running a command such as ``set contents (cat filename | string collect -N)``.
+
 "escape" and "unescape" subcommands
 -----------------------------------
 
@@ -329,6 +342,22 @@ Examples
     a1_20b2__c_E6_85_A1
 
 
+
+
+::
+
+    >_ echo \"(echo one\ntwo\nthree | string collect)\"
+    "one
+    two
+    three
+    "
+    
+    >_ echo \"(echo one\ntwo\nthree | string collect -N)\"
+    "one
+    two
+    three"
+
+
 Match Glob Examples
 -------------------