Neovim provides several Lua-based interfaces for setting and getting configuration options. The highest-level (and generally most-convenient) interface uses:
vim.opt
which provides a convenient way to deal with list-like and map-like options.
For those people coming from Vim, Lua-based configuration looks a bit different than Vimscript. For example, the following are equivalent:
| Lua | Vimscript |
|---|---|
| vim.opt.smarttab = true | set smarttab |
| vim.opt.smarttab = false | set nosmarttab |
| vim.opt.wildignore = {'.o', '.a', '__pycache__'} | set wildignore=.o,.a,__pycache__ |
| vim.opt.listchars = {space='_', tab='>~'} | set listchars=space:_,tab:>~ |
| vim.opt.formatoptions = {n=true, j=true, t=true} | set formatoptions=njt |
This interface provides methods to simplify modifying option values. Assuming an option name with the following value:
vim.opt.name = {"a", "b", "c"}
| Operation | After |
|---|---|
| vim.opt.name:append("d") | {"a", "b", "c", "d"} |
| vim.opt.name:prepend("d") | {"d", "a", "b", "c"} |
| vim.opt.name:remove("c") | {"a", "b"} |
In order to get the value of a config option with this interface, one uses the get method:
vim.opt:get("name")
The vim.opt interface gets and sets both global and local config. In some cases you only want to set (or get) the buffer-local or window-local config. In these cases you can use the complementary interfaces:
vim.opt_local
and
vim.opt_global
which operate with the buffer-local or window-local configuration, or global configuration, respectively.
When the convenience of working with list-like and map-like configuration values is not required, the short-hand interface
vim.o
can be used. When this interface is used like-like and map-like values are assigned and read as strings.
This shorthand interface allows one to work with global and local config using:
vim.go
for global config,
vim.wo[{winid}]
for window-local config, where winid specifies which window, and
vim.bo[{bufnr}]
for buffer-local config, where bufnr specified which buffer.
winid and bufnr can be set to 0 to specify the current window or buffer, respectively. When specifying the current window or buffer, an additional shorthand notation may be used:
vim.wo
and
vim.bo
refer to the current window and buffer, respectively.
Finally, the Neovim Lua API also provides a programmatic interface:
vim.api.nvim_get_option_value(name, opts)
where name is the name of the config option and opts is a table of options that defines the scope and optional target of the operation.
vim.api.nvim_set_option_value(name, value, opts)
where name is the name of the config option, value is the value to set, and opts is a table of options that defines the scope and optional target of the operation.