Merge pull request #16752 from gpanders/lua-user-commands

feat(api): implement nvim_{add,del}_user_command

2 files changed, 80 insertions, 2 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 8b0139023e..efffca72ad 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -626,6 +626,56 @@ 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>|
+                               • 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". When
+                               using a Lua function for {command} you can also
+                               provide a "desc" key that will be displayed
+                               when listing commands. 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-complete-customlist|.
+
 nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                 Calls many API methods atomically.
 
@@ -714,6 +764,12 @@ nvim_del_mark({name})                                        *nvim_del_mark()*
                     |nvim_buf_del_mark()|
                     |nvim_get_mark()|
 
+nvim_del_user_command({name})                        *nvim_del_user_command()*
+                Delete a user-defined command.
+
+                Parameters: ~
+                    {name}  Name of the command to delete.
+
 nvim_del_var({name})                                          *nvim_del_var()*
                 Removes a global (g:) variable.
 
@@ -1790,6 +1846,16 @@ 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.
@@ -1925,6 +1991,18 @@ nvim_buf_del_mark({buffer}, {name})                      *nvim_buf_del_mark()*
                     |nvim_buf_set_mark()|
                     |nvim_del_mark()|
 
+                                                 *nvim_buf_del_user_command()*
+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
+                function.
+
+                Parameters: ~
+                    {buffer}  Buffer handle, or 0 for current buffer.
+                    {name}    Name of the command to delete.
+
 nvim_buf_del_var({buffer}, {name})                        *nvim_buf_del_var()*
                 Removes a buffer-scoped (b:) variable
 
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 238ef39bd3..f6d9e45d64 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1247,8 +1247,8 @@ See |:verbose-cmd| for more information.
 
 
 Command attributes ~
-
-User-defined commands are treated by Vim just like any other Ex commands.  They
+							*command-attributes*
+User-defined commands are treated by Nvim just like any other Ex commands.  They
 can have arguments, or have a range specified.  Arguments are subject to
 completion as filenames, buffers, etc.  Exactly how this works depends upon the
 command's attributes, which are specified when the command is defined.