kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-23 20:55:18 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(lua): add guide to using Lua in Neovim (#21137)

Browse Source 
Add introductory guide explaining how to use Lua in Neovim:
where to put Lua files, how to set variables and options, how
to create mappings, autocommands, and user commands.

Adapted with kind permission from
https://github.com/nanotee/nvim-lua-guide
This commit is contained in:
dundargoc 2022-12-08 11:21:42 +01:00 committed by Christian Clason
parent 342312b8ad
commit cc02cfee2f
3 changed files with 760 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
runtime/doc/help.txt
View File

@ -97,6 +97,7 @@ General subjects ~
|nvim.txt| Transitioning from Vim
|help.txt| overview and quick reference (this file)
|helphelp.txt| about using the help files
|lua-guide| Nvim Lua guide
|index.txt| alphabetical index of all commands
|tips.txt| various tips on using Vim
|message.txt| (error) messages and explanations

757
runtime/doc/lua-guide.txt Normal file
View File

@ -0,0 +1,757 @@
*lua-guide.txt* Nvim
NVIM REFERENCE MANUAL
Guide to using Lua in Nvim
Type |gO| to see the table of contents.
==============================================================================
Introduction *lua-guide*
This guide will go through the basics of using Lua in Neovim. It is not meant
to be a comprehensive encyclopedia of all available features, nor will it
detail all intricacies. Think of it as a survival kit -- the bare minimum
needed to know to comfortably get started on using Lua in Neovim.
An important thing to note is that this isn't a guide to the Lua language
itself. Rather, this is a guide on how to configure and modify Neovim through
the Lua language and the functions we provide to help with this. Take a look
at |luaref| and |lua-concepts| if you'd like to learn more about Lua itself.
Similarly, this guide assumes some familiarity with the basics of Neovim
(commands, options, mappings, autocommands), which are covered in the
|user-manual|.
------------------------------------------------------------------------------
Some words on the API *lua-guide-api*
The purpose of this guide is to introduce the different ways of interacting
with Neovim through Lua (the "API"). This API consists of three different
layers:
1. The "Vim API" inherited from Vim: |ex-commands| and |builtin-functions| as
well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
below.
2. The "Neovim API" written in C for use in remote plugins and GUIs; see |api|.
These functions are accessed through |vim.api|.
3. The "Lua API" written in and specifically for Lua. These are any other
functions accessible through `vim.*` not mentioned already; see |lua-stdlib|.
This distinction is important, as API functions inherit behavior from their
original layer: For example, Neovim API functions always need all arguments to
be specified even if Lua itself allows omitting arguments (which are then
passed as `nil`); and Vim API functions can use 0-based indexing even if Lua
arrays are 1-indexed by default.
Through this, any possible interaction can be done through Lua without writing
a complete new API from scratch. For this reason, functions are usually not
duplicated between layers unless there is a significant benefit in
functionality or performance (e.g., you can map Lua functions directly through
|nvim_create_autocmd()| but not through |:autocmd|). In case there are multiple
ways of achieving the same thing, this guide will only cover what is most
convenient to use from Lua.
==============================================================================
Using Lua *lua-guide-using-Lua*
To run Lua code from the Neovim command line, use the |:lua| command:
>vim
:lua print("Hello!")
<
Note: each |:lua| command has its own scope and variables declared with the
local keyword are not accessible outside of the command. This won't work:
>vim
:lua local foo = 1
:lua print(foo)
" prints "nil" instead of "1"
<
You can also use `:lua=`, which is the same as `:lua vim.pretty_print(...)`,
to conveniently check the value of a variable or a table:
>lua
:lua=package
<
To run a Lua script in an external file, you can use the |:source| command
exactly like for a Vimscript file:
>vim
:source ~/programs/baz/myluafile.lua
<
Finally, you can include Lua code in a Vimscript file by putting it inside a
|lua-heredoc| block:
>vim
lua << EOF
local tbl = {1, 2, 3}
for k, v in ipairs(tbl) do
print(v)
end
EOF
<
------------------------------------------------------------------------------
Using Lua files on startup *lua-guide-config*
Neovim supports using `init.vim` or `init.lua` as the configuration file, but
not both at the same time. This should be placed in your |config| directory,
which is typically `~/.config/nvim` for Linux, BSD, or macOS, and
`~/AppData/Local/nvim/` for Windows. Note that you can use Lua in `init.vim`
and Vimscript in `init.lua`, which will be covered below.
If you'd like to run any other Lua script on |startup| automatically, then you
can simply put it in `plugin/` in your |'runtimepath'|.
------------------------------------------------------------------------------
Lua modules *lua-guide-modules*
If you want to load Lua files on demand, you can place them in the `lua/`
directory in your |'runtimepath'| and load them with `require`. (This is the
Lua equivalent of Vimscript's |autoload| mechanism.)
Let's assume you have the following directory structure:
>
~/.config/nvim
|-- after/
|-- ftplugin/
|-- lua/
| |-- myluamodule.lua
| |-- other_modules/
| |-- anothermodule.lua
| |-- init.lua
|-- plugin/
|-- syntax/
|-- init.vim
<
Then the following Lua code will load `myluamodule.lua`:
>lua
require("myluamodule")
<
Note the absence of a `.lua` extension.
Similarly, loading `other_modules/anothermodule.lua` is done via
>lua
require('other_modules/anothermodule')
-- or
require('other_modules.anothermodule')
<
Note how "submodules" are just subdirectories; the `.` is equivalent to the
path separator `/` (even on Windows).
A folder containing an |init.lua| file can be required directly, without
having to specify the name of the file:
>lua
require('other_modules') -- loads other_modules/init.lua
<
Requiring a nonexistent module or a module which contains syntax errors aborts
the currently executing script. `pcall()` may be used to catch such errors. The
following example tries to load the `module_with_error` and only calls one of
its functions if this succeeds and prints an error message otherwise:
>lua
local ok, mymod = pcall(require, 'module_with_error')
if not ok then
print("Module had an error")
else
mymod.function()
end
<
In contrast to |:source|, |require()| not only searches through all `lua/` directories
under |'runtimepath'|, it also cache the module on first use. Calling
`require()` a second time will therefore _not_ execute the script again and
instead return the cached file. To rerun the file, you need to remove it from
the cache manually first:
>lua
package.loaded['myluamodule'] = nil
require('myluamodule') -- read and execute the module again from disk
<
------------------------------------------------------------------------------
See also:
• |lua-require|
• |luaref-pcall()|
==============================================================================
Using Vim commands and functions from Lua *lua-guide-vimscript*
All Vim commands and functions are accessible from Lua.
------------------------------------------------------------------------------
Vim commands *lua-guide-vim-commands*
To run an arbitrary Vim command from Lua, pass it as a string to |vim.cmd()|:
>lua
vim.cmd("colorscheme habamax")
<
Note that special characters will need to be escaped with backslashes:
>lua
vim.cmd("%s/\\Vfoo/bar/g")
<
An alternative is to use a literal string (see |luaref-literal|) delimited by
double brackets `[[ ]]` as in
>lua
vim.cmd([[%s/\Vfoo/bar/g]])
<
Another benefit of using literal strings is that they can be multiple lines;
this allows you to pass multiple commands to a single call of |vim.cmd()|:
>lua
vim.cmd([[
highlight Error guibg=red
highlight link Warning Error
]])
<
This is the converse of |lua-heredoc| and allows you to include Lua code in
your `init.vim`.
If you want to build your Vim command programmatically, the following form can
be useful (all these are equivalent to the corresponding line above):
>lua
vim.cmd.colorscheme("habamax")
vim.cmd.highlight({ "Error", "guibg=red" })
vim.cmd.highlight({ "link", "Warning", "Error" })
<
------------------------------------------------------------------------------
Vimscript functions *lua-guide-vim-functions*
Use |vim.fn| to call Vimscript functions from Lua. Data types between Lua and
Vimscript are automatically converted:
>lua
print(vim.fn.printf('Hello from %s', 'Lua'))
local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' })
print(vim.inspect(reversed_list)) -- { "c", "b", "a" }
local function print_stdout(chan_id, data, name)
print(data[1])
end
vim.fn.jobstart('ls', { on_stdout = print_stdout })
print(vim.fn.printf('Hello from %s', 'Lua'))
<
This works for both |builtin-functions| and |user-function|s.
Note that hashes (`#`) are not valid characters for identifiers in Lua, so,
e.g., |autoload| functions have to be called with this syntax:
>lua
vim.fn['my#autoload#function']()
<
------------------------------------------------------------------------------
See also:
• |builtin-functions|: alphabetic list of all Vimscript functions
• |function-list|: list of all Vimscript functions grouped by topic
• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'|
• |package.path|: list of all paths searched by `require()`
==============================================================================
Variables *lua-guide-variables*
Variables can be set and read using the following wrappers, which directly
correspond to their |variable-scope|:
• |vim.g|: global variables (|g:|)
• |vim.b|: variables for the current buffer (|b:|)
• |vim.w|: variables for the current window (|w:|)
• |vim.t|: variables for the current tabpage (|t:|)
• |vim.v|: predefined Vim variables (|v:|)
• |vim.env|: environment variables defined in the editor session
Data types are converted automatically. For example:
>lua
vim.g.some_global_variable = {
key1 = "value",
key2 = 300
}
print(vim.inspect(vim.g.some_global_variable))
--> { key1 = "value", key2 = 300 }
<
You can target specific buffers (via number), windows (via |window-ID|), or
tabpages by indexing the wrappers:
>lua
vim.b[2].myvar = 1 -- set myvar for buffer number 2
vim.w[1005].myothervar = true -- set myothervar for window ID 1005
<
Some variable names may contain characters that cannot be used for identifiers
in Lua. You can still manipulate these variables by using the syntax
>lua
vim.g['my#variable'] = 1
<
Note that you cannot directly change fields of array variables. This won't
work:
>lua
vim.g.some_global_variable.key2 = 400
vim.pretty_print(vim.g.some_global_variable)
--> { key1 = "value", key2 = 300 }
<
Instead, you need to create an intermediate Lua table and change this:
>lua
local temp_table = vim.g.some_global_variable
temp_table = keys = 400
vim.g.some_global_variable = temp_table
vim.pretty_print(vim.g.some_global_variable)
--> { key1 = "value", key2 = 400 }
<
To delete a variable, simply set it to `nil`:
>lua
vim.g.myvar = nil
<
------------------------------------------------------------------------------
See also:
• |lua-vim-variables|
==============================================================================
Options *lua-guide-options*
There are two complementary ways of setting |options| via Lua.
------------------------------------------------------------------------------
vim.opt
The most convenient way for setting global and local options, e.g., in `init.lua`,
is through `vim.opt` and friends:
• |vim.opt|: behaves like |:set|
• |vim.opt_global|: behaves like |:setglobal|
• |vim.opt_local|: behaves like |:setlocal|
For example, the Vimscript commands
>vim
set smarttab
set nosmarttab
<
are equivalent to
>lua
vim.opt.smarttab = true
vim.opt.smarttab = false
<
In particular, they allow an easy way to working with list-like, map-like, and
set-like options through Lua tables: Instead of
>vim
set wildignore=*.o,*.a,__pycache__
set listchars=space:_,tab:>~
set formatoptions=njt
<
you can use
>lua
vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
vim.opt.listchars = { space = '_', tab = '>~' }
vim.opt.formatoptions = { n = true, j = true, t = true }
<
These wrappers also come with methods that work similarly to their |:set+=|,
|:set^=| and |:set-=| counterparts in Vimscript:
>lua
vim.opt.shortmess:append({ I = true })
vim.opt.wildignore:prepend('*.o')
vim.opt.whichwrap:remove({ 'b', 's' })
<
The price to pay is that you cannot access the option values directly but must
use |vim.opt:get()|:
>lua
print(vim.opt.smarttab)
--> {...} (big table)
print(vim.opt.smarttab:get())
--> false
vim.pretty_print(vim.opt.listchars:get())
--> { space = '_', tab = '>~' }
<
------------------------------------------------------------------------------
vim.o
For this reason, there exists a more direct variable-like access using `vim.o`
and friends, similarly to how you can get and set options via `:echo &number`
and `:let &listchars='space:_,tab:>~'`:
• |vim.o|: behaves like |:set|
• |vim.go|: behaves like |:setglobal|
• |vim.bo|: for buffer-scoped options
• |vim.wo|: for window-scoped options
For example:
>lua
vim.o.smarttab = false -- :set nosmarttab
print(vim.o.smarttab)
--> false
vim.o.listchars = 'space:_,tab:>~' -- :set listchars='space:_,tab:>~'
print(vim.o.listchars)
--> 'space:_,tab:>~'
vim.o.isfname = vim.o.isfname .. ',@-@' -- :set isfname+=@-@
print(vim.o.isfname)
--> '@,48-57,/,.,-,_,+,,,#,$,%,~,=,@-@'
vim.bo.shiftwidth = 4 -- :setlocal shiftwidth=4
print(vim.bo.shiftwidth)
--> 4
<
Just like variables, you can specify a buffer number or |window-ID| for buffer
and window options, respectively. If no number is given, the current buffer or
window is used:
>lua
vim.bo[4].expandtab = true -- sets expandtab to true in buffer 4
vim.wo.number = true -- sets number to true in current window
print(vim.wo[0].number) --> true
<
------------------------------------------------------------------------------
See also:
• |lua-options|
==============================================================================
Mappings *lua-guide-mappings*
You can map either Vim commands or Lua functions to key sequences.
------------------------------------------------------------------------------
Creating mappings *lua-guide-mappings-set*
Mappings can be created using |vim.keymap.set()|. This function takes three
mandatory arguments:
• {mode} is a string or a table of strings containing the mode
prefix for which the mapping will take effect. The prefixes are the ones
listed in |:map-modes|, or "!" for |:map!|, or empty string for |:map|.
• {lhs} is a string with the key sequences that should trigger the mapping.
An empty string is equivalent to |<Nop>|, which disables a key.
• {rhs} is either a string with a Vim command or a Lua function that should
be execucted when the {lhs} is entered.
Examples:
>lua
-- Normal mode mapping for Vim command
vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>')
-- Normal and Command-line mode mapping for Vim command
vim.keymap.set({'n', 'c'}, '<Leader>ex2', '<cmd>echo "Example 2"<cr>')
-- Normal mode mapping for Lua function
vim.keymap.set('n', '<Leader>ex3', vim.treesitter.start)
-- Normal mode mapping for Lua function with arguments
vim.keymap.set('n', '<Leader>ex4', function() print('Example 4') end)
<
You can map functions from Lua modules via
>lua
vim.keymap.set('n', '<Leader>pl1', require('plugin').action)
<
Note that this loads the plugin at the time the mapping is defined. If you
want to defer the loading to the time when the mapping is executed (as for
|autoload| functions), wrap it in `function() end`:
>lua
vim.keymap.set('n', '<Leader>pl2', function() require('plugin').action() end)
<
The fourth, optional, argument is a table with keys that modify the behavior
of the mapping such as those from |:map-arguments|. The following are the most
useful options:
• `buffer`: If given, only set the mapping for the buffer with the specified
number; `0` or `true` means the current buffer. >lua
-- set mapping for the current buffer
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buffer = true })
-- set mapping for the buffer number 4
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buffer = 4 })
<
• `silent`: If set to `true`, suppress output such as error messages. >lua
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { silent = true })
<
• `expr`: If set to `true`, do not execute the {rhs} but use the return value
as input. Special |keycodes| are converted automatically. For example, the following
mapping replaces <down> with <c-n> in the popupmenu only: >lua
vim.keymap.set('c', '<down>', function()
if vim.fn.pumvisible() == 1 then return '<c-n>' end
return '<down>'
end, { expr = true })
<
• `desc`: A string that is shown when listing mappings with, e.g., |:map|.
This is useful since Lua functions as {rhs} are otherwise only listed as
`Lua: <number> <source file>:<line>`. Plugins should therefore always use this
for mappings they create. >lua
vim.keymap.set('n', '<Leader>pl1', require('plugin').action,
{ desc = 'Execute action from plugin' })
<
• `remap`: By default, all mappings are nonrecursive by default (i.e.,
|vim.keymap.set()| behaves like |:noremap|). If the {rhs} is itself a mapping
that should be executed, set `remap = true`: >lua
vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>')
-- add a shorter mapping
vim.keymap.set('n', 'e', '<Leader>ex1', { remap = true })
<
Note: |<Plug>| mappings are always expanded even with the default `remap = false`: >lua
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
<
------------------------------------------------------------------------------
Removing mappings *lua-guide-mappings-del*
A specific mapping can be removed with |vim.keymap.del()|:
>lua
vim.keymap.del('n', '<Leader>ex1')
vim.keymap.del({'n', 'c'}, '<Leader>ex2', {buffer = true})
<
------------------------------------------------------------------------------
See also:
• `vim.api.`|nvim_get_keymap()|: return all global mapping
• `vim.api.`|nvim_buf_get_keymap()|: return all mappings for buffer
==============================================================================
Autocommands *lua-guide-autocommands*
An |autocommand| is a Vim command or a Lua function that is automatically
executed whenever one or more |events| are triggered, e.g., when a file is
read or written, or when a window is created. These are accessible from Lua
through the Neovim API.
------------------------------------------------------------------------------
Creating autocommands *lua-guide-autocommand-create*
Autocommands are created using `vim.api.`|nvim_create_autocmd()|, which takes
two mandatory arguments:
• {event}: a string or table of strings containing the event(s) which should
trigger the command or function.
• {opts}: a table with keys that control what should happen when the event(s)
are triggered.
The most important options are:
• `pattern`: A string or table of strings containing the |autocmd-pattern|.
Note: Environment variable like `$HOME` and `~` are not automatically
expanded; you need to explicitly use `vim.fn.`|expand()| for this.
• `command`: A string containing a Vim command.
• `callback`: A Lua function.
You must specify one and only one of `command` and `callback`. If `pattern` is
omitted, it defaults to `pattern = '*'`.
Examples:
>lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
command = "echo 'Entering a C or C++ file'",
})
-- Same autocommand written with a Lua function instead
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
callback = function() print("Entering a C or C++ file") end,
})
-- User event triggered by MyPlugin
vim.api.nvim_create_autocmd("User", {
pattern = "MyPlugin",
callback = function() print("My Plugin Works!") end,
})
<
Neovim will always call a Lua function with a single table containing information
about the triggered autocommand. The most useful keys are
• `match`: a string that matched the `pattern` (see |<amatch>|)
• `buf`: the number of the buffer the event was triggered in (see |<abuf>|)
• `file`: the file name of the buffer the event was triggered in (see |<afile>|)
• `data`: a table with other relevant data that is passed for some events
For example, this allows you to set buffer-local mappings for some filetypes:
>lua
vim.api.nvim.create_autocmd("FileType", {
pattern = "lua",
callback = function(args)
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
end
})
<
This means that if your callback itself takes an (even optional) argument, you
must wrap it in `function() end` to avoid an error:
>lua
vim.api.nvim_create_autocmd('TextYankPost', {
callback = function() vim.highlight.on_yank() end
})
<
(Since unused arguments can be omitted in Lua function definitions, this is
equivalent to `function(args) ... end`.)
Instead of using a pattern, you can create a buffer-local autocommand (see
|autocmd-buflocal|) with `buffer`; in this case, `pattern` cannot be used:
>lua
-- set autocommand for current buffer
vim.api.nvim_create_autocmd("CursorHold", {
buffer = 0,
callback = function() print("hold") end,
})
-- set autocommand for buffer number 33
vim.api.nvim_create_autocmd("CursorHold", {
buffer = 33,
callback = function() print("hold") end,
})
<
Similarly to mappings, you can (and should) add a description using `desc`:
>lua
vim.api.nvim_create_autocmd('TextYankPost', {
callback = function() vim.highlight.on_yank() end,
desc = "Briefly highlight yanked text"
})
<
Finally, you can group autocommands using the `group` key; this will be
covered in detail in the next section.
------------------------------------------------------------------------------
Grouping autocommands *lua-guide-autocommands-group*
Autocommand groups can be used to group related autocommands together; see
|autocmd-groups|. This is useful for organizing autocommands and especially
for preventing autocommands to be set multiple times.
Groups can be created with `vim.api.`|nvim_create_augroup()|. This function
takes two mandatory arguments: a string with the name of a group and a table
determining whether the group should be cleared (i.e., all grouped
autocommands removed) if it already exists. The function returns a number that
is the internal identifier of the group. Groups can be specified either by
this identifier or by the name (but only if the group has been created first).
For example, a common Vimscript pattern for autocommands defined in files that
may be reloaded is
>vim
augroup vimrc
" Remove all vimrc autocommands
autocmd!
au BufNewFile,BufRead *.html set shiftwidth=4
au BufNewFile,BufRead *.html set expandtab
augroup END
<
This is equivalent to the following Lua code:
>lua
local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = true })
vim.api.nvim_create_autocmd( {'BufNewFile', 'BufRead' }, {
pattern = '*.html',
group = mygroup,
cmd = 'set shiftwidth=4',
})
vim.api.nvim_create_autocmd( {'BufNewFile', 'BufRead' }, {
pattern = '*.html',
group = 'vimrc', -- equivalent to group=mygroup
cmd = 'set expandtab',
})
<
Autocommand groups are unique for a given name, so you can reuse them, e.g.,
in a different file:
>lua
local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = false })
vim.api.nvim_create_autocmd( {'BufNewFile', 'BufRead' }, {
pattern = '*.html',
group = mygroup,
cmd = 'set shiftwidth=4',
})
<
------------------------------------------------------------------------------
Deleting autocommands *lua-guide-autocommands-delete*
You can use `vim.api.`|nvim_clear_autocmds()| to remove autocommands. This
function takes a single mandatory argument that is a table of keys describing
the autocommands that are to be removed:
>lua
-- Delete all BufEnter and InsertLeave autocommands
vim.api.nvim_clear_autocmds({event = {"BufEnter", "InsertLeave"}})
-- Delete all autocommands that uses "*.py" pattern
vim.api.nvim_clear_autocmds({pattern = "*.py"})
-- Delete all autocommands in group "scala"
vim.api.nvim_clear_autocmds({group = "scala"})
-- Delete all ColorScheme autocommands in current buffer
vim.api.nvim_clear_autocmds({event = "ColorScheme", buffer = 0 })
<
Note: Autocommands in groups will only be removed if the `group` key is
specified, even if another option matches it.
------------------------------------------------------------------------------
See also
• |nvim_get_autocmds()|: return all matching autocommands
• |nvim_exec_autocmds()|: execute all matching autocommands
==============================================================================
User commands *lua-guide-usercommands*
|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-usercommands-create*
User commands can be created through the Neovim API with
`vim.api.`|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-usercommands-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:

9
runtime/doc/lua.txt
View File

@ -21,12 +21,7 @@ Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the
which can be used from Lua code (|lua-vimscript| |vim.api|). Together these
"namespaces" form the Nvim programming interface.
The |:source| and |:runtime| commands can run Lua scripts. Lua modules can be
loaded with `require('name')`, which by convention usually returns a table.
See |lua-require| for how Nvim finds and loads Lua modules.
See this page for more insight into Nvim Lua:
https://github.com/nanotee/nvim-lua-guide
See the |lua-guide| for an introduction to using Lua in Neovim.
*lua-compat*
Lua 5.1 is the permanent interface for Nvim Lua. Plugins need only consider
@ -125,7 +120,7 @@ Examples using |string.match()|: >
For more complex matching you can use Vim regex from Lua via |vim.regex()|.
==============================================================================
IMPORTING LUA MODULES *lua-require*
IMPORTING LUA MODULES *require()* *lua-require*
Modules are searched for under the directories specified in 'runtimepath', in
the order they appear. Any "." in the module name is treated as a directory