Merge pull request #18071 from gpanders/create_uc

refactor!: Rename nvim_add_user_command to nvim_create_user_command

runtime/doc/api.txt

@@ -627,62 +627,6 @@ nvim__stats()                                                  *nvim__stats()*
                 Return: ~
                     Map of various internal stats.
 
-                                                     *nvim_add_user_command()*
-nvim_add_user_command({name}, {command}, {*opts})
-                Create a new user command |user-commands|
-
-                {name} is the name of the new command. The name must begin
-                with an uppercase letter.
-
-                {command} is the replacement text or Lua function to execute.
-
-                Example: >
-                   :call nvim_add_user_command('SayHello', 'echo "Hello world!"', {})
-                   :SayHello
-                   Hello world!
-<
-
-                Parameters: ~
-                    {name}     Name of the new user command. Must begin with
-                               an uppercase letter.
-                    {command}  Replacement command to execute when this user
-                               command is executed. When called from Lua, the
-                               command can also be a Lua function. The
-                               function is called with a single table argument
-                               that contains the following keys:
-                               • args: (string) The args passed to the
-                                 command, if any |<args>|
-                               • fargs: (table) The args split by unescaped
-                                 whitespace (when more than one argument is
-                                 allowed), if any |<f-args>|
-                               • bang: (boolean) "true" if the command was
-                                 executed with a ! modifier |<bang>|
-                               • line1: (number) The starting line of the
-                                 command range |<line1>|
-                               • line2: (number) The final line of the command
-                                 range |<line2>|
-                               • range: (number) The number of items in the
-                                 command range: 0, 1, or 2 |<range>|
-                               • count: (number) Any count supplied |<count>|
-                               • reg: (string) The optional register, if
-                                 specified |<reg>|
-                               • mods: (string) Command modifiers, if any
-                                 |<mods>|
-                    {opts}     Optional command attributes. See
-                               |command-attributes| for more details. To use
-                               boolean attributes (such as |:command-bang| or
-                               |:command-bar|) set the value to "true". In
-                               addition to the string options listed in
-                               |:command-complete|, the "complete" key also
-                               accepts a Lua function which works like the
-                               "customlist" completion mode
-                               |:command-completion-customlist|. Additional
-                               parameters:
-                               • desc: (string) Used for listing the command
-                                 when a Lua function is used for {command}.
-                               • force: (boolean, default true) Override any
-                                 previous definition.
-
 nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                 Calls many API methods atomically.
 
@@ -740,6 +684,62 @@ nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
                 See also: ~
                     buf_open_scratch
 
+                                                  *nvim_create_user_command()*
+nvim_create_user_command({name}, {command}, {*opts})
+                Create a new user command |user-commands|
+
+                {name} is the name of the new command. The name must begin
+                with an uppercase letter.
+
+                {command} is the replacement text or Lua function to execute.
+
+                Example: >
+                   :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
+                   :SayHello
+                   Hello world!
+<
+
+                Parameters: ~
+                    {name}     Name of the new user command. Must begin with
+                               an uppercase letter.
+                    {command}  Replacement command to execute when this user
+                               command is executed. When called from Lua, the
+                               command can also be a Lua function. The
+                               function is called with a single table argument
+                               that contains the following keys:
+                               • args: (string) The args passed to the
+                                 command, if any |<args>|
+                               • fargs: (table) The args split by unescaped
+                                 whitespace (when more than one argument is
+                                 allowed), if any |<f-args>|
+                               • bang: (boolean) "true" if the command was
+                                 executed with a ! modifier |<bang>|
+                               • line1: (number) The starting line of the
+                                 command range |<line1>|
+                               • line2: (number) The final line of the command
+                                 range |<line2>|
+                               • range: (number) The number of items in the
+                                 command range: 0, 1, or 2 |<range>|
+                               • count: (number) Any count supplied |<count>|
+                               • reg: (string) The optional register, if
+                                 specified |<reg>|
+                               • mods: (string) Command modifiers, if any
+                                 |<mods>|
+                    {opts}     Optional command attributes. See
+                               |command-attributes| for more details. To use
+                               boolean attributes (such as |:command-bang| or
+                               |:command-bar|) set the value to "true". In
+                               addition to the string options listed in
+                               |:command-complete|, the "complete" key also
+                               accepts a Lua function which works like the
+                               "customlist" completion mode
+                               |:command-completion-customlist|. Additional
+                               parameters:
+                               • desc: (string) Used for listing the command
+                                 when a Lua function is used for {command}.
+                               • force: (boolean, default true) Override any
+                                 previous definition.
+
 nvim_del_current_line()                              *nvim_del_current_line()*
                 Deletes the current line.
 
@@ -1864,16 +1864,6 @@ nvim__buf_redraw_range({buffer}, {first}, {last})
 nvim__buf_stats({buffer})                                  *nvim__buf_stats()*
                 TODO: Documentation
 
-                                                 *nvim_buf_add_user_command()*
-nvim_buf_add_user_command({buffer}, {name}, {command}, {*opts})
-                Create a new user command |user-commands| in the given buffer.
-
-                Parameters: ~
-                    {buffer}  Buffer handle, or 0 for current buffer.
-
-                See also: ~
-                    nvim_add_user_command
-
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                 Activates buffer-update events on a channel, or as Lua
                 callbacks.
@@ -1983,6 +1973,16 @@ nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
                     Return value of function. NB: will deepcopy lua values
                     currently, use upvalues to send lua references in and out.
 
+                                              *nvim_buf_create_user_command()*
+nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
+                Create a new user command |user-commands| in the given buffer.
+
+                Parameters: ~
+                    {buffer}  Buffer handle, or 0 for current buffer.
+
+                See also: ~
+                    nvim_create_user_command
+
 nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
                 Unmaps a buffer-local |mapping| for the given mode.
 
@@ -2015,7 +2015,7 @@ nvim_buf_del_user_command({buffer}, {name})
                 Delete a buffer-local user-defined command.
 
                 Only commands created with |:command-buffer| or
-                |nvim_buf_add_user_command()| can be deleted with this
+                |nvim_buf_create_user_command()| can be deleted with this
                 function.
 
                 Parameters: ~

runtime/doc/develop.txt

@@ -243,12 +243,13 @@ If the function acts on an object then {thing} is the name of that object
 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
+    add     Append to, or insert into, a collection
-    del   Delete a thing (or group of things)
+    create  Create a new thing
-    exec  Execute code
+    del     Delete a thing (or group of things)
-    get   Get a thing (or group of things by query)
+    exec    Execute code
-    list  Get all things
+    get     Get a thing (or group of things by query)
-    set   Set a thing (or group of things)
+    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/buffer.c

@@ -1377,9 +1377,9 @@ Object nvim_buf_call(Buffer buffer, LuaRef fun, Error *err)
 ///
 /// @param  buffer  Buffer handle, or 0 for current buffer.
 /// @param[out] err Error details, if any.
-/// @see nvim_add_user_command
+/// @see nvim_create_user_command
-void nvim_buf_add_user_command(Buffer buffer, String name, Object command, Dict(user_command) *opts,
+void nvim_buf_create_user_command(Buffer buffer, String name, Object command,
-                               Error *err)
+                                  Dict(user_command) *opts, Error *err)
   FUNC_API_SINCE(9)
 {
   buf_T *target_buf = find_buffer_by_handle(buffer, err);
@@ -1389,14 +1389,14 @@ void nvim_buf_add_user_command(Buffer buffer, String name, Object command, Dict(
 
   buf_T *save_curbuf = curbuf;
   curbuf = target_buf;
-  add_user_command(name, command, opts, UC_BUFFER, err);
+  create_user_command(name, command, opts, UC_BUFFER, err);
   curbuf = save_curbuf;
 }
 
 /// Delete a buffer-local user-defined command.
 ///
 /// Only commands created with |:command-buffer| or
-/// |nvim_buf_add_user_command()| can be deleted with this function.
+/// |nvim_buf_create_user_command()| can be deleted with this function.
 ///
 /// @param  buffer  Buffer handle, or 0 for current buffer.
 /// @param  name    Name of the command to delete.

src/nvim/api/private/helpers.c

@@ -1416,7 +1416,8 @@ const char *get_default_stl_hl(win_T *wp)
   }
 }
 
-void add_user_command(String name, Object command, Dict(user_command) *opts, int flags, Error *err)
+void create_user_command(String name, Object command, Dict(user_command) *opts, int flags,
+                         Error *err)
 {
   uint32_t argt = 0;
   long def = -1;

src/nvim/api/vim.c

@@ -2408,7 +2408,7 @@ Dictionary nvim_eval_statusline(String str, Dict(eval_statusline) *opts, Error *
 ///
 /// Example:
 /// <pre>
-///    :call nvim_add_user_command('SayHello', 'echo "Hello world!"', {})
+///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
 ///    :SayHello
 ///    Hello world!
 /// </pre>
@@ -2436,10 +2436,10 @@ Dictionary nvim_eval_statusline(String str, Dict(eval_statusline) *opts, Error *
 ///                                  {command}.
 ///                 - force: (boolean, default true) Override any previous definition.
 /// @param[out] err Error details, if any.
-void nvim_add_user_command(String name, Object command, Dict(user_command) *opts, Error *err)
+void nvim_create_user_command(String name, Object command, Dict(user_command) *opts, Error *err)
   FUNC_API_SINCE(9)
 {
-  add_user_command(name, command, opts, 0, err);
+  create_user_command(name, command, opts, 0, err);
 }
 
 /// Delete a user-defined command.

test/functional/api/command_spec.lua

@@ -92,11 +92,11 @@ describe('nvim_get_commands', function()
   end)
 end)
 
-describe('nvim_add_user_command', function()
+describe('nvim_create_user_command', function()
   before_each(clear)
 
   it('works with strings', function()
-    meths.add_user_command('SomeCommand', 'let g:command_fired = <args>', {nargs = 1})
+    meths.create_user_command('SomeCommand', 'let g:command_fired = <args>', {nargs = 1})
     meths.command('SomeCommand 42')
     eq(42, meths.eval('g:command_fired'))
   end)
@@ -104,7 +104,7 @@ describe('nvim_add_user_command', function()
   it('works with Lua functions', function()
     exec_lua [[
       result = {}
-      vim.api.nvim_add_user_command('CommandWithLuaCallback', function(opts)
+      vim.api.nvim_create_user_command('CommandWithLuaCallback', function(opts)
         result = opts
       end, {
         nargs = "*",
@@ -176,7 +176,7 @@ describe('nvim_add_user_command', function()
     -- f-args doesn't split when command nargs is 1 or "?"
     exec_lua [[
       result = {}
-      vim.api.nvim_add_user_command('CommandWithOneArg', function(opts)
+      vim.api.nvim_create_user_command('CommandWithOneArg', function(opts)
         result = opts
       end, {
         nargs = "?",
@@ -204,7 +204,7 @@ describe('nvim_add_user_command', function()
 
   it('can define buffer-local commands', function()
     local bufnr = meths.create_buf(false, false)
-    bufmeths.add_user_command(bufnr, "Hello", "", {})
+    bufmeths.create_user_command(bufnr, "Hello", "", {})
     matches("Not an editor command: Hello", pcall_err(meths.command, "Hello"))
     meths.set_current_buf(bufnr)
     meths.command("Hello")
@@ -213,7 +213,7 @@ describe('nvim_add_user_command', function()
 
   it('can use a Lua complete function', function()
     exec_lua [[
-      vim.api.nvim_add_user_command('Test', '', {
+      vim.api.nvim_create_user_command('Test', '', {
         nargs = "*",
         complete = function(arg, cmdline, pos)
           local options = {"aaa", "bbb", "ccc"}
@@ -236,23 +236,23 @@ describe('nvim_add_user_command', function()
 
   it('does not allow invalid command names', function()
     matches("'name' must begin with an uppercase letter", pcall_err(exec_lua, [[
-      vim.api.nvim_add_user_command('test', 'echo "hi"', {})
+      vim.api.nvim_create_user_command('test', 'echo "hi"', {})
     ]]))
 
     matches('Invalid command name', pcall_err(exec_lua, [[
-      vim.api.nvim_add_user_command('t@', 'echo "hi"', {})
+      vim.api.nvim_create_user_command('t@', 'echo "hi"', {})
     ]]))
 
     matches('Invalid command name', pcall_err(exec_lua, [[
-      vim.api.nvim_add_user_command('T@st', 'echo "hi"', {})
+      vim.api.nvim_create_user_command('T@st', 'echo "hi"', {})
     ]]))
 
     matches('Invalid command name', pcall_err(exec_lua, [[
-      vim.api.nvim_add_user_command('Test!', 'echo "hi"', {})
+      vim.api.nvim_create_user_command('Test!', 'echo "hi"', {})
     ]]))
 
     matches('Invalid command name', pcall_err(exec_lua, [[
-      vim.api.nvim_add_user_command('💩', 'echo "hi"', {})
+      vim.api.nvim_create_user_command('💩', 'echo "hi"', {})
     ]]))
   end)
 end)
@@ -261,14 +261,14 @@ describe('nvim_del_user_command', function()
   before_each(clear)
 
   it('can delete global commands', function()
-    meths.add_user_command('Hello', 'echo "Hi"', {})
+    meths.create_user_command('Hello', 'echo "Hi"', {})
     meths.command('Hello')
     meths.del_user_command('Hello')
     matches("Not an editor command: Hello", pcall_err(meths.command, "Hello"))
   end)
 
   it('can delete buffer-local commands', function()
-    bufmeths.add_user_command(0, 'Hello', 'echo "Hi"', {})
+    bufmeths.create_user_command(0, 'Hello', 'echo "Hi"', {})
     meths.command('Hello')
     bufmeths.del_user_command(0, 'Hello')
     matches("Not an editor command: Hello", pcall_err(meths.command, "Hello"))

test/functional/ex_cmds/verbose_spec.lua

@@ -31,7 +31,7 @@ vim.api.nvim_exec("augroup test_group\
                   ", false)
 
 vim.api.nvim_command("command Bdelete :bd")
-vim.api.nvim_add_user_command("TestCommand", ":echo 'Hello'", {})
+vim.api.nvim_create_user_command("TestCommand", ":echo 'Hello'", {})
 
 vim.api.nvim_exec ("\
 function Close_Window() abort\
@@ -114,7 +114,7 @@ test_group  FileType
        script_location), result)
   end)
 
-  it('"Last set" for command defined by nvim_add_user_command', function()
+  it('"Last set" for command defined by nvim_create_user_command', function()
     local result = exec_capture(':verbose command TestCommand')
     eq(string.format([[
     Name              Args Address Complete    Definition