mirror of
https://github.com/neovim/neovim.git
synced 2025-12-09 08:02:38 +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)
|
print(vim.env.TERM)
|
||||||
<
|
<
|
||||||
|
|
||||||
|
*lua-options*
|
||||||
*lua-vim-options*
|
*lua-vim-options*
|
||||||
*lua-vim-opt*
|
|
||||||
*lua-vim-set*
|
*lua-vim-set*
|
||||||
*lua-vim-optlocal*
|
|
||||||
*lua-vim-setlocal*
|
*lua-vim-setlocal*
|
||||||
|
|
||||||
In Vimscript, there is a way to set options |set-option|. In Lua, the
|
Vim options can be accessed through |vim.o|, which behaves like Vimscript
|
||||||
corresponding method is `vim.opt`.
|
|:set|.
|
||||||
|
|
||||||
`vim.opt` provides several conveniences for setting and controlling options
|
|
||||||
from within Lua.
|
|
||||||
|
|
||||||
Examples: ~
|
Examples: ~
|
||||||
|
|
||||||
@@ -1110,148 +1106,26 @@ from within Lua.
|
|||||||
`set number`
|
`set number`
|
||||||
|
|
||||||
In Lua:
|
In Lua:
|
||||||
`vim.opt.number = true`
|
`vim.o.number = true`
|
||||||
|
|
||||||
To set an array of values:
|
To set a string value:
|
||||||
In Vimscript:
|
In Vimscript:
|
||||||
`set wildignore=*.o,*.a,__pycache__`
|
`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:
|
In Lua:
|
||||||
`vim.opt.listchars = { space = '_', tab = '>~' }`
|
`vim.o.wildignore = '*.o,*.a,__pycache__'`
|
||||||
|
|
||||||
|
Similarly, there exist |vim.bo| and |vim.wo| for setting buffer-local and
|
||||||
In any of the above examples, to replicate the behavior |setlocal|, use
|
window-local options, respectively, similarly to |:setlocal|. There is also
|
||||||
`vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use
|
|vim.go| that only sets the global value of a |global-local| option, see
|
||||||
`vim.opt_global`.
|
|:setglobal|. The following table summarizes this relation.
|
||||||
*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:
|
|
||||||
|
|
||||||
lua command global_value local_value ~
|
lua command global_value local_value ~
|
||||||
vim.o :set set set
|
vim.o :set set set
|
||||||
vim.bo/vim.wo :setlocal - set
|
vim.bo/vim.wo :setlocal - set
|
||||||
vim.go :setglobal set -
|
vim.go :setglobal set -
|
||||||
|
|
||||||
|
|
||||||
vim.o *vim.o*
|
vim.o *vim.o*
|
||||||
Get or set editor options, like |:set|. Invalid key is an error.
|
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.foldmarker)
|
||||||
print(vim.wo.quux) -- error: invalid key
|
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*
|
Lua module: vim *lua-vim*
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user