Port capture() function

https://groups.google.com/forum/#!msg/vim_dev/H3Z3ChSUh_4/beZs6KzYdBsJ

2 files changed, 24 insertions, 2 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 8b23d2ff5f..b5fe9967b2 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1808,6 +1808,7 @@ byteidx({expr}, {nr})		Number	byte index of {nr}'th char in {expr}
 byteidxcomp({expr}, {nr})	Number	byte index of {nr}'th char in {expr}
 call({func}, {arglist} [, {dict}])
 				any	call {func} with arguments {arglist}
+capture({command})		String	capture output of {command}
 ceil({expr})			Float	round {expr} up
 changenr()			Number	current change number
 char2nr({expr}[, {utf8}])	Number	ASCII/UTF8 value of first char in {expr}
@@ -2481,6 +2482,26 @@ call({func}, {arglist} [, {dict}])			*call()* *E699*
 		{dict} is for functions with the "dict" attribute.  It will be
 		used to set the local variable "self". |Dictionary-function|
 
+capture({command})					*capture()*
+		Capture output of {command}.
+		If {command} is a |String|, it returns {command} output.
+		If {command} is a |List|, it returns concatenated outputs of
+		each item.
+		Examples: >
+			let a = capture('echon "foo"')
+			echo a
+<			foo >
+			let a = capture(['echon "foo"', 'echon "bar"'])
+			echo a
+<			foobar
+		This function is not available in the |sandbox|.
+		Note: The commands are run as if they were prepended with
+		|:silent| modifier.  |:redir| and |capture()| work together.
+		Unlike nested |:redir|s, outer capture will not catch
+		commands' output of the inner one, but the inner capture will
+		not cancel the outer.
+		Note: highlighting is ignored.
+
 ceil({expr})							*ceil()*
 		Return the smallest integral value greater than or equal to
 		{expr} as a |Float| (round up).
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index af4224993f..02c5fad22f 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -416,8 +416,9 @@ m  *+xpm_w32*		Win32 GUI only: pixmap support |w32-xpm-support|
 			To stop the messages and commands from being echoed to
 			the screen, put the commands in a function and call it
 			with ":silent call Function()".
-			An alternative is to use the 'verbosefile' option,
-			this can be used in combination with ":redir".
+			The alternatives are to use the 'verbosefile' option
+			or |capture()| function, these can be used in
+			combination with ":redir".
 
 :redi[r] >> {file}	Redirect messages to file {file}.  Append if {file}
 			already exists.