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
2022-08-30 14:46:38 +02:00
committed by GitHub
parent 981ae83fad
commit 9397e70b9e

View File

@@ -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*