eval.c: rename capture() to execute() (#5132)

runtime/autoload/remote/host.vim

@@ -121,7 +121,7 @@ endfunction
 function! s:GetManifest() abort
   let prefix = exists('$MYVIMRC')
         \ ? $MYVIMRC
-        \ : matchstr(get(split(capture('scriptnames'), '\n'), 0, ''), '\f\+$')
+        \ : matchstr(get(split(execute('scriptnames'), '\n'), 0, ''), '\f\+$')
   return fnamemodify(expand(prefix, 1), ':h')
         \.'/.'.fnamemodify(prefix, ':t').'-rplugin~'
 endfunction

runtime/doc/eval.txt

@@ -1809,7 +1809,6 @@ 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}
@@ -1845,6 +1844,7 @@ escape({string}, {chars})	String	escape {chars} in {string} with '\'
 eval({string})			any	evaluate {string} into its value
 eventhandler()			Number	TRUE if inside an event handler
 executable({expr})		Number	1 if executable {expr} exists
+execute({command})		String	execute and capture output of {command}
 exepath({expr})		String  full path of the command {expr}
 exists({expr})			Number	TRUE if {expr} exists
 extend({expr1}, {expr2} [, {expr3}])
@@ -2524,21 +2524,6 @@ 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|, returns {command} output.
-		If {command} is a |List|, returns concatenated outputs.
-		Examples: >
-			echo capture('echon "foo"')
-<			foo >
-			echo capture(['echon "foo"', 'echon "bar"'])
-<			foobar
-		This function is not available in the |sandbox|.
-		Note: {command} executes as if prepended with |:silent|
-		(output is collected, but not displayed).  If nested, an outer
-		capture() will not observe the output of inner calls.
-		Note: Text attributes (highlights) are not captured.
-
 ceil({expr})							*ceil()*
 		Return the smallest integral value greater than or equal to
 		{expr} as a |Float| (round up).
@@ -2989,6 +2974,21 @@ executable({expr})					*executable()*
 			0	does not exist
 			-1	not implemented on this system
 
+execute({command})					*execute()*
+		Execute {command} and capture its output.
+		If {command} is a |String|, returns {command} output.
+		If {command} is a |List|, returns concatenated outputs.
+		Examples: >
+			echo execute('echon "foo"')
+<			foo >
+			echo execute(['echon "foo"', 'echon "bar"'])
+<			foobar
+		This function is not available in the |sandbox|.
+		Note: {command} executes as if prepended with |:silent|
+		(output is collected but not displayed).  If nested, an outer
+		execute() will not observe output of the inner calls.
+		Note: Text attributes (highlights) are not captured.
+
 exepath({expr})						*exepath()*
 		If {expr} is an executable and is either an absolute path, a
 		relative path or found in $PATH, return the full path.

runtime/doc/various.txt

@@ -417,7 +417,7 @@ m  *+xpm_w32*		Win32 GUI only: pixmap support |w32-xpm-support|
 			the screen, put the commands in a function and call it
 			with ":silent call Function()".
 			Alternatives are the 'verbosefile' option or
-			|capture()| function, these can be used in combination
+			|execute()| function, these can be used in combination
 			with ":redir".
 
 :redi[r] >> {file}	Redirect messages to file {file}.  Append if {file}

runtime/doc/vim_diff.txt

@@ -98,7 +98,7 @@ Commands:
   |:CheckHealth|
 
 Functions:
-  |capture()|
+  |execute()| works with |:redir|
 
 Events:
   |TabNew|

src/nvim/eval.c

@@ -6727,7 +6727,6 @@ static struct fst {
   { "byteidx",           2, 2, f_byteidx },
   { "byteidxcomp",       2, 2, f_byteidxcomp },
   { "call",              2, 3, f_call },
-  { "capture",           1, 1, f_capture },
   { "ceil",              1, 1, f_ceil },
   { "changenr",          0, 0, f_changenr },
   { "char2nr",           1, 2, f_char2nr },
@@ -6756,6 +6755,7 @@ static struct fst {
   { "eval",              1, 1, f_eval },
   { "eventhandler",      0, 0, f_eventhandler },
   { "executable",        1, 1, f_executable },
+  { "execute",           1, 1, f_execute },
   { "exepath",           1, 1, f_exepath },
   { "exists",            1, 1, f_exists },
   { "exp",               1, 1, f_exp },
@@ -8153,38 +8153,6 @@ static void f_call(typval_T *argvars, typval_T *rettv)
   (void)func_call(func, &argvars[1], selfdict, rettv);
 }
 
-// "capture(command)" function
-static void f_capture(typval_T *argvars, typval_T *rettv)
-{
-    int save_msg_silent = msg_silent;
-    garray_T *save_capture_ga = capture_ga;
-
-    if (check_secure()) {
-      return;
-    }
-
-    garray_T capture_local;
-    capture_ga = &capture_local;
-    ga_init(capture_ga, (int)sizeof(char), 80);
-
-    msg_silent++;
-    if (argvars[0].v_type != VAR_LIST) {
-      do_cmdline_cmd((char *)get_tv_string(&argvars[0]));
-    } else if (argvars[0].vval.v_list != NULL) {
-      for (listitem_T *li = argvars[0].vval.v_list->lv_first;
-           li != NULL; li = li->li_next) {
-        do_cmdline_cmd((char *)get_tv_string(&li->li_tv));
-      }
-    }
-    msg_silent = save_msg_silent;
-
-    ga_append(capture_ga, NUL);
-    rettv->v_type = VAR_STRING;
-    rettv->vval.v_string = capture_ga->ga_data;
-
-    capture_ga = save_capture_ga;
-}
-
 /*
  * "ceil({float})" function
  */
@@ -8869,6 +8837,38 @@ static void f_executable(typval_T *argvars, typval_T *rettv)
            || (gettail_dir(name) != name && os_can_exe(name, NULL, false));
 }
 
+// "execute(command)" function
+static void f_execute(typval_T *argvars, typval_T *rettv)
+{
+    int save_msg_silent = msg_silent;
+    garray_T *save_capture_ga = capture_ga;
+
+    if (check_secure()) {
+      return;
+    }
+
+    garray_T capture_local;
+    capture_ga = &capture_local;
+    ga_init(capture_ga, (int)sizeof(char), 80);
+
+    msg_silent++;
+    if (argvars[0].v_type != VAR_LIST) {
+      do_cmdline_cmd((char *)get_tv_string(&argvars[0]));
+    } else if (argvars[0].vval.v_list != NULL) {
+      for (listitem_T *li = argvars[0].vval.v_list->lv_first;
+           li != NULL; li = li->li_next) {
+        do_cmdline_cmd((char *)get_tv_string(&li->li_tv));
+      }
+    }
+    msg_silent = save_msg_silent;
+
+    ga_append(capture_ga, NUL);
+    rettv->v_type = VAR_STRING;
+    rettv->vval.v_string = capture_ga->ga_data;
+
+    capture_ga = save_capture_ga;
+}
+
 /// "exepath()" function
 static void f_exepath(typval_T *argvars, typval_T *rettv)
 {

src/nvim/globals.h

@@ -986,7 +986,7 @@ EXTERN int redir_off INIT(= false);         // no redirection for a moment
 EXTERN FILE *redir_fd INIT(= NULL);         // message redirection file
 EXTERN int redir_reg INIT(= 0);             // message redirection register
 EXTERN int redir_vname INIT(= 0);           // message redirection variable
-EXTERN garray_T *capture_ga INIT(= NULL);   // capture() buffer
+EXTERN garray_T *capture_ga INIT(= NULL);   // captured output for execute()
 
 EXTERN char_u langmap_mapchar[256];     /* mapping for language keys */
 

src/nvim/message.c

@@ -2396,7 +2396,7 @@ static void redir_write(char_u *str, int maxlen)
     return;
   }
 
-  // Append output to capture().
+  // Append output for execute().
   if (capture_ga) {
     size_t len = 0;
     while (str[len] && (maxlen < 0 ? 1 : (len < (size_t)maxlen))) {

test/functional/eval/execute_spec.lua

@@ -9,16 +9,16 @@ local funcs = helpers.funcs
 local Screen = require('test.functional.ui.screen')
 local feed = helpers.feed
 
-describe('capture()', function()
+describe('execute()', function()
   before_each(clear)
 
   it('returns the same result with :redir', function()
-    eq(redir_exec('messages'), funcs.capture('messages'))
+    eq(redir_exec('messages'), funcs.execute('messages'))
   end)
 
   it('returns the output of the commands if the argument is List', function()
-    eq("foobar", funcs.capture({'echon "foo"', 'echon "bar"'}))
-    eq("\nfoo\nbar", funcs.capture({'echo "foo"', 'echo "bar"'}))
+    eq("foobar", funcs.execute({'echon "foo"', 'echon "bar"'}))
+    eq("\nfoo\nbar", funcs.execute({'echo "foo"', 'echo "bar"'}))
   end)
 
   it('supports the nested redirection', function()
@@ -38,34 +38,34 @@ describe('capture()', function()
       return a
     endfunction
     ]])
-    eq('foo', funcs.capture('call g:Bar()'))
+    eq('foo', funcs.execute('call g:Bar()'))
 
-    eq('42', funcs.capture([[echon capture("echon capture('echon 42')")]]))
+    eq('42', funcs.execute([[echon execute("echon execute('echon 42')")]]))
   end)
 
   it('returns the transformed string', function()
-    eq('^A', funcs.capture('echon "\\<C-a>"'))
+    eq('^A', funcs.execute('echon "\\<C-a>"'))
   end)
 
   it('returns the empty string if the argument list is empty', function()
-    eq('', funcs.capture({}))
-    eq(0, exc_exec('let g:ret = capture(v:_null_list)'))
+    eq('', funcs.execute({}))
+    eq(0, exc_exec('let g:ret = execute(v:_null_list)'))
     eq('', eval('g:ret'))
   end)
 
   it('returns the errors', function()
     local ret
-    ret = exc_exec('call capture(0.0)')
+    ret = exc_exec('call execute(0.0)')
     eq('Vim(call):E806: using Float as a String', ret)
-    ret = exc_exec('call capture(v:_null_dict)')
+    ret = exc_exec('call execute(v:_null_dict)')
     eq('Vim(call):E731: using Dictionary as a String', ret)
-    ret = exc_exec('call capture(function("tr"))')
+    ret = exc_exec('call execute(function("tr"))')
     eq('Vim(call):E729: using Funcref as a String', ret)
-    ret = exc_exec('call capture(["echo 42", 0.0, "echo 44"])')
+    ret = exc_exec('call execute(["echo 42", 0.0, "echo 44"])')
     eq('Vim(call):E806: using Float as a String', ret)
-    ret = exc_exec('call capture(["echo 42", v:_null_dict, "echo 44"])')
+    ret = exc_exec('call execute(["echo 42", v:_null_dict, "echo 44"])')
     eq('Vim(call):E731: using Dictionary as a String', ret)
-    ret = exc_exec('call capture(["echo 42", function("tr"), "echo 44"])')
+    ret = exc_exec('call execute(["echo 42", function("tr"), "echo 44"])')
     eq('Vim(call):E729: using Funcref as a String', ret)
   end)
 
@@ -73,7 +73,7 @@ describe('capture()', function()
     local screen = Screen.new(20, 5)
     screen:attach()
     screen:set_default_attr_ignore({{bold=true, foreground=255}})
-    feed(':let g:mes = capture("echon 42")<CR>')
+    feed(':let g:mes = execute("echon 42")<CR>')
     screen:expect([[
     ^                    |
     ~                   |