mirror of
https://github.com/neovim/neovim.git
synced 2025-10-21 01:02:09 +00:00
docs(lua): present vim.o as default and vim.opt as special-purpose #19982
Problem: People are confused about `vim.o` and `vim.opt`
Solution: Clarify that `vim.o` is the default interface, with `vim.opt`
specifically meant for interacting with list-style options.
This commit is contained in:
Christian Clason
@@ -1091,17 +1091,13 @@ vim.env *vim.env*
|
||||
print(vim.env.TERM)
|
||||
<
|
||||
|
||||
*lua-options*
|
||||
*lua-vim-options*
|
||||
*lua-vim-opt*
|
||||
*lua-vim-set*
|
||||
*lua-vim-optlocal*
|
||||
*lua-vim-setlocal*
|
||||
|
||||
In Vimscript, there is a way to set options |set-option|. In Lua, the
|
||||
corresponding method is `vim.opt`.
|
||||
|
||||
`vim.opt` provides several conveniences for setting and controlling options
|
||||
from within Lua.
|
||||
Vim options can be accessed through |vim.o|, which behaves like Vimscript
|
||||
|:set|.
|
||||
|
||||
Examples: ~
|
||||
|
||||
@@ -1110,148 +1106,26 @@ from within Lua.
|
||||
`set number`
|
||||
|
||||
In Lua:
|
||||
`vim.opt.number = true`
|
||||
`vim.o.number = true`
|
||||
|
||||
To set an array of values:
|
||||
To set a string value:
|
||||
In Vimscript:
|
||||
`set wildignore=*.o,*.a,__pycache__`
|
||||
|
||||
In Lua, there are two ways you can do this now. One is very similar to
|
||||
the Vimscript form:
|
||||
`vim.opt.wildignore = '*.o,*.a,__pycache__'`
|
||||
|
||||
However, vim.opt also supports a more elegent way of setting
|
||||
list-style options by using lua tables:
|
||||
`vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
|
||||
|
||||
To replicate the behavior of |:set+=|, use: >
|
||||
|
||||
-- vim.opt supports appending options via the "+" operator
|
||||
vim.opt.wildignore = vim.opt.wildignore + { "*.pyc", "node_modules" }
|
||||
|
||||
-- or using the `:append(...)` method
|
||||
vim.opt.wildignore:append { "*.pyc", "node_modules" }
|
||||
<
|
||||
To replicate the behavior of |:set^=|, use: >
|
||||
|
||||
-- vim.opt supports prepending options via the "^" operator
|
||||
vim.opt.wildignore = vim.opt.wildignore ^ { "new_first_value" }
|
||||
|
||||
-- or using the `:prepend(...)` method
|
||||
vim.opt.wildignore:prepend { "new_first_value" }
|
||||
<
|
||||
To replicate the behavior of |:set-=|, use: >
|
||||
|
||||
-- vim.opt supports removing options via the "-" operator
|
||||
vim.opt.wildignore = vim.opt.wildignore - { "node_modules" }
|
||||
|
||||
-- or using the `:remove(...)` method
|
||||
vim.opt.wildignore:remove { "node_modules" }
|
||||
<
|
||||
To set a map of values:
|
||||
In Vimscript:
|
||||
`set listchars=space:_,tab:>~`
|
||||
|
||||
In Lua:
|
||||
`vim.opt.listchars = { space = '_', tab = '>~' }`
|
||||
`vim.o.wildignore = '*.o,*.a,__pycache__'`
|
||||
|
||||
|
||||
In any of the above examples, to replicate the behavior |setlocal|, use
|
||||
`vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use
|
||||
`vim.opt_global`.
|
||||
*vim.opt*
|
||||
|
||||
|vim.opt| returns an Option object.
|
||||
|
||||
For example: `local listchar_object = vim.opt.listchars`
|
||||
|
||||
An `Option` has the following methods:
|
||||
|
||||
|
||||
*vim.opt:get()*
|
||||
Option:get()
|
||||
|
||||
Returns a lua-representation of the option. Boolean, number and string
|
||||
values will be returned in exactly the same fashion.
|
||||
|
||||
For values that are comma-separated lists, an array will be returned with
|
||||
the values as entries in the array: >
|
||||
vim.cmd [[set wildignore=*.pyc,*.o]]
|
||||
|
||||
print(vim.inspect(vim.opt.wildignore:get()))
|
||||
-- { "*.pyc", "*.o", }
|
||||
|
||||
for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
|
||||
print("Will ignore:", ignore_pattern)
|
||||
end
|
||||
-- Will ignore: *.pyc
|
||||
-- Will ignore: *.o
|
||||
<
|
||||
For values that are comma-separated maps, a table will be returned with
|
||||
the names as keys and the values as entries: >
|
||||
vim.cmd [[set listchars=space:_,tab:>~]]
|
||||
|
||||
print(vim.inspect(vim.opt.listchars:get()))
|
||||
-- { space = "_", tab = ">~", }
|
||||
|
||||
for char, representation in pairs(vim.opt.listchars:get()) do
|
||||
print(char, "->", representation)
|
||||
end
|
||||
<
|
||||
For values that are lists of flags, a set will be returned with the flags
|
||||
as keys and `true` as entries. >
|
||||
vim.cmd [[set formatoptions=njtcroql]]
|
||||
|
||||
print(vim.inspect(vim.opt.formatoptions:get()))
|
||||
-- { n = true, j = true, c = true, ... }
|
||||
|
||||
local format_opts = vim.opt.formatoptions:get()
|
||||
if format_opts.j then
|
||||
print("J is enabled!")
|
||||
end
|
||||
<
|
||||
*vim.opt:append()*
|
||||
Option:append(value)
|
||||
|
||||
Append a value to string-style options. See |:set+=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.formatoptions:append('j')`
|
||||
`vim.opt.formatoptions = vim.opt.formatoptions + 'j'`
|
||||
|
||||
*vim.opt:prepend()*
|
||||
Option:prepend(value)
|
||||
|
||||
Prepend a value to string-style options. See |:set^=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.wildignore:prepend('*.o')`
|
||||
`vim.opt.wildignore = vim.opt.wildignore ^ '*.o'`
|
||||
|
||||
*vim.opt:remove()*
|
||||
Option:remove(value)
|
||||
|
||||
Remove a value from string-style options. See |:set-=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.wildignore:remove('*.pyc')`
|
||||
`vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
|
||||
|
||||
|
||||
In general, using `vim.opt` will provide the expected result when the user is
|
||||
used to interacting with editor |options| via `set`. There are still times
|
||||
where the user may want to set particular options via a shorthand in Lua,
|
||||
which is where |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| come into play.
|
||||
|
||||
The behavior of |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| is designed to
|
||||
follow that of |:set|, |:setlocal|, and |:setglobal| which can be seen in the
|
||||
table below:
|
||||
Similarly, there exist |vim.bo| and |vim.wo| for setting buffer-local and
|
||||
window-local options, respectively, similarly to |:setlocal|. There is also
|
||||
|vim.go| that only sets the global value of a |global-local| option, see
|
||||
|:setglobal|. The following table summarizes this relation.
|
||||
|
||||
lua command global_value local_value ~
|
||||
vim.o :set set set
|
||||
vim.bo/vim.wo :setlocal - set
|
||||
vim.go :setglobal set -
|
||||
|
||||
|
||||
vim.o *vim.o*
|
||||
Get or set editor options, like |:set|. Invalid key is an error.
|
||||
|
||||
@@ -1303,6 +1177,146 @@ vim.wo[{winid}] *
|
||||
print(vim.wo.foldmarker)
|
||||
print(vim.wo.quux) -- error: invalid key
|
||||
<
|
||||
|
||||
|
||||
|
||||
*lua-vim-opt*
|
||||
*lua-vim-optlocal*
|
||||
*lua-vim-optglobal*
|
||||
*vim.opt*
|
||||
|
||||
|
||||
A special interface |vim.opt| exists for conveniently interacting with list-
|
||||
and map-style option from Lua: It allows accessing them as Lua tables and
|
||||
offers object-oriented method for adding and removing entries.
|
||||
|
||||
Examples: ~
|
||||
|
||||
The following methods of setting a list-style option are equivalent:
|
||||
In Vimscript:
|
||||
`set wildignore=*.o,*.a,__pycache__`
|
||||
|
||||
In Lua using `vim.o`:
|
||||
`vim.o.wildignore = '*.o,*.a,__pycache__'`
|
||||
|
||||
In Lua using `vim.opt`:
|
||||
`vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
|
||||
|
||||
To replicate the behavior of |:set+=|, use: >
|
||||
|
||||
vim.opt.wildignore:append { "*.pyc", "node_modules" }
|
||||
<
|
||||
To replicate the behavior of |:set^=|, use: >
|
||||
|
||||
vim.opt.wildignore:prepend { "new_first_value" }
|
||||
<
|
||||
To replicate the behavior of |:set-=|, use: >
|
||||
|
||||
vim.opt.wildignore:remove { "node_modules" }
|
||||
<
|
||||
The following methods of setting a map-style option are equivalent:
|
||||
In Vimscript:
|
||||
`set listchars=space:_,tab:>~`
|
||||
|
||||
In Lua using `vim.o`:
|
||||
`vim.o.listchars = 'space:_,tab:>~'`
|
||||
|
||||
In Lua using `vim.opt`:
|
||||
`vim.opt.listchars = { space = '_', tab = '>~' }`
|
||||
|
||||
|
||||
Note that |vim.opt| returns an `Option` object, not the value of the option,
|
||||
which is accessed through |Option:get()|:
|
||||
|
||||
Examples: ~
|
||||
|
||||
The following methods of getting a list-style option are equivalent:
|
||||
In Vimscript:
|
||||
`echo wildignore`
|
||||
|
||||
In Lua using `vim.o`:
|
||||
`print(vim.o.wildignore)`
|
||||
|
||||
In Lua using `vim.opt`:
|
||||
`vim.pretty_print(vim.opt.wildignore:get())`
|
||||
|
||||
|
||||
In any of the above examples, to replicate the behavior |setlocal|, use
|
||||
`vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use
|
||||
`vim.opt_global`.
|
||||
|
||||
|
||||
|
||||
*vim.opt:get()*
|
||||
Option:get()
|
||||
|
||||
Returns a lua-representation of the option. Boolean, number and string
|
||||
values will be returned in exactly the same fashion.
|
||||
|
||||
For values that are comma-separated lists, an array will be returned with
|
||||
the values as entries in the array: >
|
||||
vim.cmd [[set wildignore=*.pyc,*.o]]
|
||||
|
||||
vim.pretty_print(vim.opt.wildignore:get())
|
||||
-- { "*.pyc", "*.o", }
|
||||
|
||||
for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
|
||||
print("Will ignore:", ignore_pattern)
|
||||
end
|
||||
-- Will ignore: *.pyc
|
||||
-- Will ignore: *.o
|
||||
<
|
||||
For values that are comma-separated maps, a table will be returned with
|
||||
the names as keys and the values as entries: >
|
||||
vim.cmd [[set listchars=space:_,tab:>~]]
|
||||
|
||||
vim.pretty_print(vim.opt.listchars:get())
|
||||
-- { space = "_", tab = ">~", }
|
||||
|
||||
for char, representation in pairs(vim.opt.listchars:get()) do
|
||||
print(char, "->", representation)
|
||||
end
|
||||
<
|
||||
For values that are lists of flags, a set will be returned with the flags
|
||||
as keys and `true` as entries. >
|
||||
vim.cmd [[set formatoptions=njtcroql]]
|
||||
|
||||
vim.pretty_print(vim.opt.formatoptions:get())
|
||||
-- { n = true, j = true, c = true, ... }
|
||||
|
||||
local format_opts = vim.opt.formatoptions:get()
|
||||
if format_opts.j then
|
||||
print("J is enabled!")
|
||||
end
|
||||
<
|
||||
*vim.opt:append()*
|
||||
Option:append(value)
|
||||
|
||||
Append a value to string-style options. See |:set+=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.formatoptions:append('j')`
|
||||
`vim.opt.formatoptions = vim.opt.formatoptions + 'j'`
|
||||
|
||||
*vim.opt:prepend()*
|
||||
Option:prepend(value)
|
||||
|
||||
Prepend a value to string-style options. See |:set^=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.wildignore:prepend('*.o')`
|
||||
`vim.opt.wildignore = vim.opt.wildignore ^ '*.o'`
|
||||
|
||||
*vim.opt:remove()*
|
||||
Option:remove(value)
|
||||
|
||||
Remove a value from string-style options. See |:set-=|
|
||||
|
||||
These are equivalent:
|
||||
`vim.opt.wildignore:remove('*.pyc')`
|
||||
`vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
|
||||
|
||||
|
||||
==============================================================================
|
||||
Lua module: vim *lua-vim*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user