*lua-guide-commands*

|user-commands| are custom Vim commands that call a Vimscript or Lua function.
Just like built-in commands, they can have arguments, act on ranges, or have
custom completion of arguments. As these are most useful for plugins, we will
cover only the basics of this advanced topic.

------------------------------------------------------------------------------
Creating user commands                           *lua-guide-commands-create*

User commands can be created via |nvim_create_user_command()|. This function
takes three mandatory arguments:
• a string that is the name of the command (which must start with an uppercase
  letter to distinguish it from builtin commands);
• a string containing Vim commands or a Lua function that is executed when the
  command is invoked;
• a table with |command-attributes|; in addition, it can contain the keys
  `desc` (a string describing the command); `force` (set to `false` to avoid
  replacing an already existing command with the same name), and `preview` (a
  Lua function that is used for |:command-preview|).

Example:
>lua
    vim.api.nvim_create_user_command('Test', 'echo "It works!"', {})
    vim.cmd.Test()
    --> It works!
<
(Note that the third argument is mandatory even if no attributes are given.)

Lua functions are called with a single table argument containing arguments and
modifiers. The most important are:
• `name`: a string with the command name
• `fargs`: a table containing the command arguments split by whitespace (see |<f-args>|)
• `bang`: `true` if the command was executed with a `!` modifier (see |<bang>|)
• `line1`: the starting line number of the command range (see |<line1>|)
• `line2`: the final line number of the command range (see |<line2>|)
• `range`: the number of items in the command range: 0, 1, or 2 (see |<range>|)
• `count`: any count supplied (see |<count>|)
• `smods`: a table containing the command modifiers (see |<mods>|)

For example:
>lua
    vim.api.nvim_create_user_command('Upper',
      function(opts)
        print(string.upper(opts.fargs[1]))
      end,
      { nargs = 1 })

    vim.cmd.Upper('foo')
    --> FOO
<
The `complete` attribute can take a Lua function in addition to the
attributes listed in |:command-complete|. >lua

    vim.api.nvim_create_user_command('Upper',
      function(opts)
        print(string.upper(opts.fargs[1]))
      end,
      { nargs = 1,
        complete = function(ArgLead, CmdLine, CursorPos)
          -- return completion candidates as a list-like table
          return { "foo", "bar", "baz" }
        end,
    })
<
Buffer-local user commands are created with `vim.api.`|nvim_buf_create_user_command()|.
Here the first argument is the buffer number (`0` being the current buffer);
the remaining arguments are the same as for |nvim_create_user_command()|:
>lua
    vim.api.nvim_buf_create_user_command(0, 'Upper',
      function(opts)
        print(string.upper(opts.fargs[1]))
      end,
      { nargs = 1 })
<
------------------------------------------------------------------------------
Deleting user commands                           *lua-guide-commands-delete*

User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only
argument is the name of the command:
>lua
    vim.api.nvim_del_user_command('Upper')
<
To delete buffer-local user commands use `vim.api.`|nvim_buf_del_user_command()|.
Here the first argument is the buffer number (`0` being the current buffer),
and second is command name:
>lua
    vim.api.nvim_buf_del_user_command(4, 'Upper')
<
==============================================================================
Credits                                                      *lua-guide-credits*
This guide is in large part taken from nanotee's Lua guide:
https://github.com/nanotee/nvim-lua-guide

Thank you @nanotee!

vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: