API: rename nvim_execute_lua => nvim_exec_lua

- We already find ourselves renaming nvim_execute_lua in tests and
  scripts, which suggests "exec" is the verb we actually want.
- Add "exec" verb to `:help dev-api`.

runtime/doc/api.txt

@@ -483,7 +483,8 @@ nvim_exec({src}, {output})                                       *nvim_exec()*
                 Executes Vimscript (multiline block of Ex-commands), like
                 anonymous |:source|.
 
-                Optionally returns (non-error, non-shell |:!|) output.
+                Unlike |nvim_command()| this function supports heredocs,
+                script-scope (s:), etc.
 
                 On execution error: fails with VimL error, does not update
                 v:errmsg.
@@ -493,6 +494,10 @@ nvim_exec({src}, {output})                                       *nvim_exec()*
                     {output}  Capture and return all (non-error, non-shell
                               |:!|) output
 
+                Return: ~
+                    Output (non-error, non-shell |:!|) if `output` is true,
+                    else empty string.
+
                 See also: ~
                     |execute()|
                     |nvim_command()|
@@ -643,7 +648,7 @@ nvim_eval({expr})                                                *nvim_eval()*
                 Return: ~
                     Evaluation result or expanded object
 
-nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
+nvim_exec_lua({code}, {args})                                *nvim_exec_lua()*
                 Execute Lua code. Parameters (if any) are available as `...`
                 inside the chunk. The chunk can return a value.
 

runtime/doc/deprecated.txt

@@ -15,6 +15,7 @@ updated.
 API ~
 *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
 *nvim_command_output()*		Use |nvim_exec()| instead.
+*nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
 
 Commands ~
 *:rv*

runtime/doc/develop.txt

@@ -236,10 +236,11 @@ with a {thing} that groups functions under a common concept).
 
 Use existing common {action} names if possible:
     add   Append to, or insert into, a collection
-    get   Get a thing (or group of things by query)
-    set   Set a thing (or group of things)
     del   Delete a thing (or group of things)
+    exec  Execute code
+    get   Get a thing (or group of things by query)
     list  Get all things
+    set   Set a thing (or group of things)
 
 Use consistent names for {thing} in all API functions. E.g. a buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.

src/nvim/api/vim.c

@@ -447,6 +447,15 @@ Object nvim_eval(String expr, Error *err)
   return rv;
 }
 
+/// @deprecated Use nvim_exec_lua() instead.
+Object nvim_execute_lua(String code, Array args, Error *err)
+  FUNC_API_SINCE(3)
+  FUNC_API_DEPRECATED_SINCE(7)
+  FUNC_API_REMOTE_ONLY
+{
+  return executor_exec_lua_api(code, args, err);
+}
+
 /// Execute Lua code. Parameters (if any) are available as `...` inside the
 /// chunk. The chunk can return a value.
 ///
@@ -459,8 +468,9 @@ Object nvim_eval(String expr, Error *err)
 ///                   or executing the Lua code.
 ///
 /// @return           Return value of Lua code if present or NIL.
-Object nvim_execute_lua(String code, Array args, Error *err)
+Object nvim_exec_lua(String code, Array args, Error *err)
-  FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY
+  FUNC_API_SINCE(7)
+  FUNC_API_REMOTE_ONLY
 {
   return executor_exec_lua_api(code, args, err);
 }
@@ -1275,8 +1285,8 @@ Boolean nvim_paste(String data, Boolean crlf, Integer phase, Error *err)
   Array lines = string_to_array(data, crlf);
   ADD(args, ARRAY_OBJ(lines));
   ADD(args, INTEGER_OBJ(phase));
-  rv = nvim_execute_lua(STATIC_CSTR_AS_STRING("return vim.paste(...)"), args,
+  rv = nvim_exec_lua(STATIC_CSTR_AS_STRING("return vim.paste(...)"), args,
-                        err);
+                     err);
   if (ERROR_SET(err)) {
     draining = true;
     goto theend;
@@ -2410,7 +2420,7 @@ Array nvim_get_proc_children(Integer pid, Error *err)
     Array a = ARRAY_DICT_INIT;
     ADD(a, INTEGER_OBJ(pid));
     String s = cstr_to_string("return vim._os_proc_children(select(1, ...))");
-    Object o = nvim_execute_lua(s, a, err);
+    Object o = nvim_exec_lua(s, a, err);
     api_free_string(s);
     api_free_array(a);
     if (o.type == kObjectTypeArray) {
@@ -2456,7 +2466,7 @@ Object nvim_get_proc(Integer pid, Error *err)
   Array a = ARRAY_DICT_INIT;
   ADD(a, INTEGER_OBJ(pid));
   String s = cstr_to_string("return vim._os_proc_info(select(1, ...))");
-  Object o = nvim_execute_lua(s, a, err);
+  Object o = nvim_exec_lua(s, a, err);
   api_free_string(s);
   api_free_array(a);
   if (o.type == kObjectTypeArray && o.data.array.size == 0) {

src/nvim/eval.c

@@ -20527,7 +20527,7 @@ static hashtab_T *get_funccal_local_ht(void)
   return &get_funccal()->l_vars.dv_hashtab;
 }
 
-/// Find the dict and hashtable used for a variable
+/// Finds the dict (g:, l:, s:, …) and hashtable used for a variable.
 ///
 /// @param[in]  name  Variable name, possibly with scope prefix.
 /// @param[in]  name_len  Variable name length.

src/nvim/lua/executor.c

@@ -798,9 +798,9 @@ static void typval_exec_lua(const char *lcmd, size_t lcmd_len, const char *name,
   }
 }
 
-/// Execute lua string
+/// Execute Lua string
 ///
-/// Used for nvim_execute_lua().
+/// Used for nvim_exec_lua().
 ///
 /// @param[in]  str  String to execute.
 /// @param[in]  args array of ... args

test/functional/api/vim_spec.lua

@@ -433,41 +433,44 @@ describe('API', function()
     end)
   end)
 
-  describe('nvim_execute_lua', function()
+  describe('nvim_exec_lua', function()
     it('works', function()
-      meths.execute_lua('vim.api.nvim_set_var("test", 3)', {})
+      meths.exec_lua('vim.api.nvim_set_var("test", 3)', {})
       eq(3, meths.get_var('test'))
 
-      eq(17, meths.execute_lua('a, b = ...\nreturn a + b', {10,7}))
+      eq(17, meths.exec_lua('a, b = ...\nreturn a + b', {10,7}))
 
-      eq(NIL, meths.execute_lua('function xx(a,b)\nreturn a..b\nend',{}))
+      eq(NIL, meths.exec_lua('function xx(a,b)\nreturn a..b\nend',{}))
+      eq("xy", meths.exec_lua('return xx(...)', {'x','y'}))
+
+      -- Deprecated name: nvim_execute_lua.
       eq("xy", meths.execute_lua('return xx(...)', {'x','y'}))
     end)
 
     it('reports errors', function()
       eq([[Error loading lua: [string "<nvim>"]:1: '=' expected near '+']],
-        pcall_err(meths.execute_lua, 'a+*b', {}))
+        pcall_err(meths.exec_lua, 'a+*b', {}))
 
       eq([[Error loading lua: [string "<nvim>"]:1: unexpected symbol near '1']],
-        pcall_err(meths.execute_lua, '1+2', {}))
+        pcall_err(meths.exec_lua, '1+2', {}))
 
       eq([[Error loading lua: [string "<nvim>"]:1: unexpected symbol]],
-        pcall_err(meths.execute_lua, 'aa=bb\0', {}))
+        pcall_err(meths.exec_lua, 'aa=bb\0', {}))
 
       eq([[Error executing lua: [string "<nvim>"]:1: attempt to call global 'bork' (a nil value)]],
-        pcall_err(meths.execute_lua, 'bork()', {}))
+        pcall_err(meths.exec_lua, 'bork()', {}))
 
       eq('Error executing lua: [string "<nvim>"]:1: did\nthe\nfail',
-        pcall_err(meths.execute_lua, 'error("did\\nthe\\nfail")', {}))
+        pcall_err(meths.exec_lua, 'error("did\\nthe\\nfail")', {}))
     end)
 
     it('uses native float values', function()
-      eq(2.5, meths.execute_lua("return select(1, ...)", {2.5}))
+      eq(2.5, meths.exec_lua("return select(1, ...)", {2.5}))
-      eq("2.5", meths.execute_lua("return vim.inspect(...)", {2.5}))
+      eq("2.5", meths.exec_lua("return vim.inspect(...)", {2.5}))
 
       -- "special" float values are still accepted as return values.
-      eq(2.5, meths.execute_lua("return vim.api.nvim_eval('2.5')", {}))
+      eq(2.5, meths.exec_lua("return vim.api.nvim_eval('2.5')", {}))
-      eq("{\n  [false] = 2.5,\n  [true] = 3\n}", meths.execute_lua("return vim.inspect(vim.api.nvim_eval('2.5'))", {}))
+      eq("{\n  [false] = 2.5,\n  [true] = 3\n}", meths.exec_lua("return vim.inspect(vim.api.nvim_eval('2.5'))", {}))
     end)
   end)
 
@@ -573,7 +576,7 @@ describe('API', function()
       eq({0,3,14,0}, funcs.getpos('.'))
     end)
     it('vim.paste() failure', function()
-      nvim('execute_lua', 'vim.paste = (function(lines, phase) error("fake fail") end)', {})
+      nvim('exec_lua', 'vim.paste = (function(lines, phase) error("fake fail") end)', {})
       eq([[Error executing lua: [string "<nvim>"]:1: fake fail]],
         pcall_err(request, 'nvim_paste', 'line 1\nline 2\nline 3', false, 1))
     end)
@@ -797,7 +800,7 @@ describe('API', function()
       ok(nil ~= string.find(rv, 'noequalalways\n'..
         '\tLast set from API client %(channel id %d+%)'))
 
-      nvim('execute_lua', 'vim.api.nvim_set_option("equalalways", true)', {})
+      nvim('exec_lua', 'vim.api.nvim_set_option("equalalways", true)', {})
       status, rv = pcall(nvim, 'command_output',
         'verbose set equalalways?')
       eq(true, status)

test/functional/helpers.lua

@@ -706,7 +706,7 @@ module.curwinmeths = module.create_callindex(module.curwin)
 module.curtabmeths = module.create_callindex(module.curtab)
 
 function module.exec_lua(code, ...)
-  return module.meths.execute_lua(code, {...})
+  return module.meths.exec_lua(code, {...})
 end
 
 function module.redir_exec(cmd)

test/functional/lua/overrides_spec.lua

@@ -299,14 +299,11 @@ describe('package.path/package.cpath', function()
     end
     return new_paths
   end
-  local function execute_lua(cmd, ...)
-    return meths.execute_lua(cmd, {...})
-  end
   local function eval_lua(expr, ...)
-    return meths.execute_lua('return ' .. expr, {...})
+    return meths.exec_lua('return '..expr, {...})
   end
   local function set_path(which, value)
-    return execute_lua('package[select(1, ...)] = select(2, ...)', which, value)
+    return exec_lua('package[select(1, ...)] = select(2, ...)', which, value)
   end
 
   it('contains directories from &runtimepath on first invocation', function()

test/functional/terminal/tui_spec.lua

@@ -486,7 +486,7 @@ describe('TUI', function()
   end)
 
   it('paste: recovers from vim.paste() failure', function()
-    child_session:request('nvim_execute_lua', [[
+    child_session:request('nvim_exec_lua', [[
       _G.save_paste_fn = vim.paste
       vim.paste = function(lines, phase) error("fake fail") end
     ]], {})
@@ -544,7 +544,7 @@ describe('TUI', function()
       {3:-- TERMINAL --}                                    |
     ]]}
     -- Paste works if vim.paste() succeeds.
-    child_session:request('nvim_execute_lua', [[
+    child_session:request('nvim_exec_lua', [[
       vim.paste = _G.save_paste_fn
     ]], {})
     feed_data('\027[200~line A\nline B\n\027[201~')
@@ -563,7 +563,7 @@ describe('TUI', function()
   it('paste: vim.paste() cancel (retval=false) #10865', function()
     -- This test only exercises the "cancel" case.  Use-case would be "dangling
     -- paste", but that is not implemented yet. #10865
-    child_session:request('nvim_execute_lua', [[
+    child_session:request('nvim_exec_lua', [[
       vim.paste = function(lines, phase) return false end
     ]], {})
     feed_data('\027[200~line A\nline B\n\027[201~')