diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 095f74b65d..858258320d 100644 --- a/runtime/doc/api.txt +++ b/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 || - • fargs: (table) The args split by unescaped - whitespace (when more than one argument is - allowed), if any || - • bang: (boolean) "true" if the command was - executed with a ! modifier || - • line1: (number) The starting line of the - command range || - • line2: (number) The final line of the command - range || - • range: (number) The number of items in the - command range: 0, 1, or 2 || - • count: (number) Any count supplied || - • reg: (string) The optional register, if - specified || - • mods: (string) Command modifiers, if any - || - {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 || + • fargs: (table) The args split by unescaped + whitespace (when more than one argument is + allowed), if any || + • bang: (boolean) "true" if the command was + executed with a ! modifier || + • line1: (number) The starting line of the + command range || + • line2: (number) The final line of the command + range || + • range: (number) The number of items in the + command range: 0, 1, or 2 || + • count: (number) Any count supplied || + • reg: (string) The optional register, if + specified || + • mods: (string) Command modifiers, if any + || + {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: ~ diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index cc146fcf6e..b31ac47bda 100644 --- a/runtime/doc/develop.txt +++ b/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 - 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) + add Append to, or insert into, a collection + create Create a new thing + 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. diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 18f7177489..6d5803a5fe 100644 --- a/src/nvim/api/buffer.c +++ b/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 -void nvim_buf_add_user_command(Buffer buffer, String name, Object command, Dict(user_command) *opts, - Error *err) +/// @see nvim_create_user_command +void nvim_buf_create_user_command(Buffer buffer, String name, Object command, + 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. diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c index 88954a1aa2..5ba4700f62 100644 --- a/src/nvim/api/private/helpers.c +++ b/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; diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 503a1c9f23..626f7dc3eb 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -2408,7 +2408,7 @@ Dictionary nvim_eval_statusline(String str, Dict(eval_statusline) *opts, Error * /// /// Example: /// 
-///    :call nvim_add_user_command('SayHello', 'echo "Hello world!"', {})
+///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
 ///    :SayHello
 ///    Hello world!
 ///
@@ -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. diff --git a/test/functional/api/command_spec.lua b/test/functional/api/command_spec.lua index 94176fc2ce..ad162473ec 100644 --- a/test/functional/api/command_spec.lua +++ b/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 = ', {nargs = 1}) + meths.create_user_command('SomeCommand', 'let g:command_fired = ', {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")) diff --git a/test/functional/ex_cmds/verbose_spec.lua b/test/functional/ex_cmds/verbose_spec.lua index 326104dc3c..e6f67ef18e 100644 --- a/test/functional/ex_cmds/verbose_spec.lua +++ b/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