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.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 (can be double indexed)
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
vim.wo[0].number = true -- same as above
vim.wo[0][0].number = true -- sets number to true in current buffer
-- in current window only
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',