758 lines
29 KiB
Plaintext
758 lines
29 KiB
Plaintext
*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 Vimscript code in
|
|
your `init.lua`.
|
|
|
|
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.key2 = 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.
|
|
• {rhs} is either a string with a Vim command or a Lua function that should
|
|
be executed when the {lhs} is entered.
|
|
An empty string is equivalent to |<Nop>|, which disables a key.
|
|
|
|
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,
|
|
command = 'set shiftwidth=4',
|
|
})
|
|
vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, {
|
|
pattern = '*.html',
|
|
group = 'vimrc', -- equivalent to group=mygroup
|
|
command = '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,
|
|
command = '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-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 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-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:
|