aboutsummaryrefslogtreecommitdiff
path: root/runtime/lua/vim/_options.lua
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/lua/vim/_options.lua')
-rw-r--r--runtime/lua/vim/_options.lua433
1 files changed, 228 insertions, 205 deletions
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index b83a8dd4b1..13ad6cc58f 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -1,12 +1,10 @@
----@defgroup lua-vimscript
+--- @brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
+--- functions, and editor commands and options.
---
----@brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
----functions, and editor commands and options.
----
----Objects passed over this bridge are COPIED (marshalled): there are no
----"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
----a Lua list copies the list object to Vimscript and does NOT modify the Lua
----list:
+--- Objects passed over this bridge are COPIED (marshalled): there are no
+--- "references". |lua-guide-variables| For example, using `vim.fn.remove()` on
+--- a Lua list copies the list object to Vimscript and does NOT modify the Lua
+--- list:
---
--- ```lua
--- local list = { 1, 2, 3 }
@@ -14,86 +12,85 @@
--- vim.print(list) --> "{ 1, 2, 3 }"
--- ```
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.call({func}, {...}) *vim.call()*
---- Invokes |vim-function| or |user-function| {func} with arguments {...}.
---- See also |vim.fn|.
---- Equivalent to: >lua
---- vim.fn[func]({...})
----<
----vim.cmd({command})
---- See |vim.cmd()|.
----
----vim.fn.{func}({...}) *vim.fn*
---- Invokes |vim-function| or |user-function| {func} with arguments {...}.
---- To call autoload functions, use the syntax: >lua
---- vim.fn['some\#function']({...})
----<
---- Unlike vim.api.|nvim_call_function()| this converts directly between Vim
---- objects and Lua objects. If the Vim function returns a float, it will be
---- represented directly as a Lua number. Empty lists and dictionaries both
---- are represented by an empty table.
----
---- Note: |v:null| values as part of the return value is represented as
---- |vim.NIL| special value
----
---- Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
---- enumerates functions that were called at least once.
----
---- Note: The majority of functions cannot run in |api-fast| callbacks with some
---- undocumented exceptions which are allowed.
----
---- *lua-vim-variables*
----The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
----from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
----described below. In this way you can easily read and modify global Vimscript
----variables from Lua.
----
----Example: >lua
----
---- vim.g.foo = 5 -- Set the g:foo Vimscript variable.
---- print(vim.g.foo) -- Get and print the g:foo Vimscript variable.
---- vim.g.foo = nil -- Delete (:unlet) the Vimscript variable.
---- vim.b[2].foo = 6 -- Set b:foo for buffer 2
----<
----
----Note that setting dictionary fields directly will not write them back into
----Nvim. This is because the index into the namespace simply returns a copy.
----Instead the whole dictionary must be written as one. This can be achieved by
----creating a short-lived temporary.
----
----Example: >lua
----
---- vim.g.my_dict.field1 = 'value' -- Does not work
----
---- local my_dict = vim.g.my_dict --
---- my_dict.field1 = 'value' -- Instead do
---- vim.g.my_dict = my_dict --
----
----vim.g *vim.g*
---- Global (|g:|) editor variables.
---- Key with no value returns `nil`.
----
----vim.b *vim.b*
---- Buffer-scoped (|b:|) variables for the current buffer.
---- Invalid or unset key returns `nil`. Can be indexed with
---- an integer to access variables for a specific buffer.
----
----vim.w *vim.w*
---- Window-scoped (|w:|) variables for the current window.
---- Invalid or unset key returns `nil`. Can be indexed with
---- an integer to access variables for a specific window.
----
----vim.t *vim.t*
---- Tabpage-scoped (|t:|) variables for the current tabpage.
---- Invalid or unset key returns `nil`. Can be indexed with
---- an integer to access variables for a specific tabpage.
----
----vim.v *vim.v*
---- |v:| variables.
---- Invalid or unset key returns `nil`.
----</pre>
+--- @brief <pre>help
+--- vim.call({func}, {...}) *vim.call()*
+--- Invokes |vim-function| or |user-function| {func} with arguments {...}.
+--- See also |vim.fn|.
+--- Equivalent to: >lua
+--- vim.fn[func]({...})
+--- <
+--- vim.cmd({command})
+--- See |vim.cmd()|.
+---
+--- vim.fn.{func}({...}) *vim.fn*
+--- Invokes |vim-function| or |user-function| {func} with arguments {...}.
+--- To call autoload functions, use the syntax: >lua
+--- vim.fn['some#function']({...})
+--- <
+--- Unlike vim.api.|nvim_call_function()| this converts directly between Vim
+--- objects and Lua objects. If the Vim function returns a float, it will be
+--- represented directly as a Lua number. Empty lists and dictionaries both
+--- are represented by an empty table.
+---
+--- Note: |v:null| values as part of the return value is represented as
+--- |vim.NIL| special value
+---
+--- Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+--- enumerates functions that were called at least once.
+---
+--- Note: The majority of functions cannot run in |api-fast| callbacks with some
+--- undocumented exceptions which are allowed.
+---
+--- *lua-vim-variables*
+--- The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
+--- from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
+--- described below. In this way you can easily read and modify global Vimscript
+--- variables from Lua.
+---
+--- Example: >lua
+---
+--- vim.g.foo = 5 -- Set the g:foo Vimscript variable.
+--- print(vim.g.foo) -- Get and print the g:foo Vimscript variable.
+--- vim.g.foo = nil -- Delete (:unlet) the Vimscript variable.
+--- vim.b[2].foo = 6 -- Set b:foo for buffer 2
+--- <
+---
+--- Note that setting dictionary fields directly will not write them back into
+--- Nvim. This is because the index into the namespace simply returns a copy.
+--- Instead the whole dictionary must be written as one. This can be achieved by
+--- creating a short-lived temporary.
+---
+--- Example: >lua
+---
+--- vim.g.my_dict.field1 = 'value' -- Does not work
+---
+--- local my_dict = vim.g.my_dict --
+--- my_dict.field1 = 'value' -- Instead do
+--- vim.g.my_dict = my_dict --
+---
+--- vim.g *vim.g*
+--- Global (|g:|) editor variables.
+--- Key with no value returns `nil`.
+---
+--- vim.b *vim.b*
+--- Buffer-scoped (|b:|) variables for the current buffer.
+--- Invalid or unset key returns `nil`. Can be indexed with
+--- an integer to access variables for a specific buffer.
+---
+--- vim.w *vim.w*
+--- Window-scoped (|w:|) variables for the current window.
+--- Invalid or unset key returns `nil`. Can be indexed with
+--- an integer to access variables for a specific window.
+---
+--- vim.t *vim.t*
+--- Tabpage-scoped (|t:|) variables for the current tabpage.
+--- Invalid or unset key returns `nil`. Can be indexed with
+--- an integer to access variables for a specific tabpage.
+---
+--- vim.v *vim.v*
+--- |v:| variables.
+--- Invalid or unset key returns `nil`.
+--- </pre>
local api = vim.api
@@ -108,6 +105,10 @@ local key_value_options = {
winhl = true,
}
+--- @nodoc
+--- @class vim._option.Info : vim.api.keyset.get_option_info
+--- @field metatype 'boolean'|'string'|'number'|'map'|'array'|'set'
+
--- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
---@return string
local function get_option_metatype(name, info)
@@ -126,8 +127,10 @@ local function get_option_metatype(name, info)
end
--- @param name string
+--- @return vim._option.Info
local function get_options_info(name)
local info = api.nvim_get_option_info2(name, {})
+ --- @cast info vim._option.Info
info.metatype = get_option_metatype(name, info)
return info
end
@@ -142,8 +145,6 @@ end
--- vim.env.FOO = 'bar'
--- print(vim.env.TERM)
--- ```
----
----@param var string
vim.env = setmetatable({}, {
__index = function(_, k)
local v = vim.fn.getenv(k)
@@ -205,31 +206,30 @@ local function new_win_opt_accessor(winid, bufnr)
})
end
----@addtogroup lua-vimscript
----@brief <pre>help
----` ` *lua-options*
---- *lua-vim-options*
---- *lua-vim-set*
---- *lua-vim-setlocal*
+--- @brief <pre>help
+--- *lua-options*
+--- *lua-vim-options*
+--- *lua-vim-set*
+--- *lua-vim-setlocal*
---
----Vim options can be accessed through |vim.o|, which behaves like Vimscript
----|:set|.
+--- Vim options can be accessed through |vim.o|, which behaves like Vimscript
+--- |:set|.
---
---- Examples: ~
+--- Examples: ~
---
---- To set a boolean toggle:
---- Vimscript: `set number`
---- Lua: `vim.o.number = true`
+--- To set a boolean toggle:
+--- Vimscript: `set number`
+--- Lua: `vim.o.number = true`
---
---- To set a string value:
---- Vimscript: `set wildignore=*.o,*.a,__pycache__`
---- Lua: `vim.o.wildignore = '*.o,*.a,__pycache__'`
+--- To set a string value:
+--- Vimscript: `set wildignore=*.o,*.a,__pycache__`
+--- Lua: `vim.o.wildignore = '*.o,*.a,__pycache__'`
---
----Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
----window-scoped options. Note that this must NOT be confused with
----|local-options| and |:setlocal|. There is also |vim.go| that only accesses the
----global value of a |global-local| option, see |:setglobal|.
----</pre>
+--- Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
+--- window-scoped options. Note that this must NOT be confused with
+--- |local-options| and |:setlocal|. There is also |vim.go| that only accesses the
+--- global value of a |global-local| option, see |:setglobal|.
+--- </pre>
--- Get or set |options|. Like `:set`. Invalid key is an error.
---
@@ -276,10 +276,10 @@ vim.go = setmetatable({}, {
})
--- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
---- buffer is used. Invalid {bufnr} or key is an error.
+--- If {bufnr} is omitted then the current buffer is used.
+--- Invalid {bufnr} or key is an error.
---
---- Note: this is equivalent to both `:set` and `:setlocal`.
+--- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise.
---
--- Example:
---
@@ -292,9 +292,9 @@ vim.go = setmetatable({}, {
vim.bo = new_buf_opt_accessor()
--- Get or set window-scoped |options| for the window with handle {winid} and
---- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
---- `:set` otherwise. If [{winid}] is omitted then the current window is
---- used. Invalid {winid}, {bufnr} or key is an error.
+--- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option
+--- or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then
+--- the current window is used. Invalid {winid}, {bufnr} or key is an error.
---
--- Note: only {bufnr} with value `0` (the current buffer in the window) is
--- supported.
@@ -310,18 +310,21 @@ vim.bo = new_buf_opt_accessor()
--- ```
vim.wo = new_win_opt_accessor()
----@brief [[
--- vim.opt, vim.opt_local and vim.opt_global implementation
---
--- To be used as helpers for working with options within neovim.
--- For information on how to use, see :help vim.opt
----
----@brief ]]
--- Preserves the order and does not mutate the original list
+--- @generic T
+--- @param t T[]
+--- @return T[]
local function remove_duplicate_values(t)
+ --- @type table, table<any,true>
local result, seen = {}, {}
- for _, v in ipairs(t) do
+ for _, v in
+ ipairs(t --[[@as any[] ]])
+ do
if not seen[v] then
table.insert(result, v)
end
@@ -332,8 +335,11 @@ local function remove_duplicate_values(t)
return result
end
--- Check whether the OptionTypes is allowed for vim.opt
--- If it does not match, throw an error which indicates which option causes the error.
+--- Check whether the OptionTypes is allowed for vim.opt
+--- If it does not match, throw an error which indicates which option causes the error.
+--- @param name any
+--- @param value any
+--- @param types string[]
local function assert_valid_value(name, value, types)
local type_of_value = type(value)
for _, valid_type in ipairs(types) do
@@ -360,6 +366,8 @@ local function tbl_merge(left, right)
return vim.tbl_extend('force', left, right)
end
+--- @param t table<any,any>
+--- @param value any|any[]
local function tbl_remove(t, value)
if type(value) == 'string' then
t[value] = nil
@@ -388,6 +396,8 @@ local to_vim_value = {
number = passthrough,
string = passthrough,
+ --- @param info vim._option.Info
+ --- @param value string|table<string,true>
set = function(info, value)
if type(value) == 'string' then
return value
@@ -415,6 +425,8 @@ local to_vim_value = {
end
end,
+ --- @param info vim._option.Info
+ --- @param value string|string[]
array = function(info, value)
if type(value) == 'string' then
return value
@@ -425,6 +437,7 @@ local to_vim_value = {
return table.concat(value, ',')
end,
+ --- @param value string|table<string,string>
map = function(_, value)
if type(value) == 'string' then
return value
@@ -474,7 +487,8 @@ local to_lua_value = {
end
-- Handles unescaped commas in a list.
- if string.find(value, ',,,') then
+ if value:find(',,,') then
+ --- @type string, string
local left, right = unpack(vim.split(value, ',,,'))
local result = {}
@@ -487,8 +501,9 @@ local to_lua_value = {
return result
end
- if string.find(value, ',^,,', 1, true) then
- local left, right = unpack(vim.split(value, ',^,,', true))
+ if value:find(',^,,', 1, true) then
+ --- @type string, string
+ local left, right = unpack(vim.split(value, ',^,,', { plain = true }))
local result = {}
vim.list_extend(result, vim.split(left, ','))
@@ -516,22 +531,20 @@ local to_lua_value = {
assert(info.flaglist, 'That is the only one I know how to handle')
+ local result = {} --- @type table<string,true>
+
if info.flaglist and info.commalist then
local split_value = vim.split(value, ',')
- local result = {}
for _, v in ipairs(split_value) do
result[v] = true
end
-
- return result
else
- local result = {}
for i = 1, #value do
result[value:sub(i, i)] = true
end
-
- return result
end
+
+ return result
end,
map = function(info, raw_value)
@@ -541,10 +554,11 @@ local to_lua_value = {
assert(info.commalist, 'Only commas are supported currently')
- local result = {}
+ local result = {} --- @type table<string,string>
local comma_split = vim.split(raw_value, ',')
for _, key_value_str in ipairs(comma_split) do
+ --- @type string, string
local key, value = unpack(vim.split(key_value_str, ':'))
key = vim.trim(key)
@@ -590,14 +604,21 @@ local function prepend_value(info, current, new)
end
local add_methods = {
+ --- @param left integer
+ --- @param right integer
number = function(left, right)
return left + right
end,
+ --- @param left string
+ --- @param right string
string = function(left, right)
return left .. right
end,
+ --- @param left string[]
+ --- @param right string[]
+ --- @return string[]
array = function(left, right)
for _, v in ipairs(right) do
table.insert(left, v)
@@ -618,6 +639,8 @@ local function add_value(info, current, new)
)
end
+--- @param t table<any,any>
+--- @param val any
local function remove_one_item(t, val)
if vim.tbl_islist(t) then
local remove_index = nil
@@ -636,6 +659,8 @@ local function remove_one_item(t, val)
end
local remove_methods = {
+ --- @param left integer
+ --- @param right integer
number = function(left, right)
return left - right
end,
@@ -644,6 +669,9 @@ local remove_methods = {
error('Subtraction not supported for strings.')
end,
+ --- @param left string[]
+ --- @param right string[]
+ --- @return string[]
array = function(left, right)
if type(right) == 'string' then
remove_one_item(left, right)
@@ -739,74 +767,74 @@ local function create_option_accessor(scope)
})
end
----@addtogroup lua-vimscript
----@brief <pre>help
----` ` *vim.opt_local*
---- *vim.opt_global*
---- *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: >vim
---- set wildignore=*.o,*.a,__pycache__
----<
---- In Lua using `vim.o`: >lua
---- vim.o.wildignore = '*.o,*.a,__pycache__'
----<
---- In Lua using `vim.opt`: >lua
---- vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
----<
---- To replicate the behavior of |:set+=|, use: >lua
----
---- vim.opt.wildignore:append { "*.pyc", "node_modules" }
----<
---- To replicate the behavior of |:set^=|, use: >lua
----
---- vim.opt.wildignore:prepend { "new_first_value" }
----<
---- To replicate the behavior of |:set-=|, use: >lua
----
---- vim.opt.wildignore:remove { "node_modules" }
----<
---- The following methods of setting a map-style option are equivalent:
---- In Vimscript: >vim
---- set listchars=space:_,tab:>~
----<
---- In Lua using `vim.o`: >lua
---- vim.o.listchars = 'space:_,tab:>~'
----<
---- In Lua using `vim.opt`: >lua
---- vim.opt.listchars = { space = '_', tab = '>~' }
----<
----
----Note that |vim.opt| returns an `Option` object, not the value of the option,
----which is accessed through |vim.opt:get()|:
----
---- Examples: ~
----
---- The following methods of getting a list-style option are equivalent:
---- In Vimscript: >vim
---- echo wildignore
----<
---- In Lua using `vim.o`: >lua
---- print(vim.o.wildignore)
----<
---- In Lua using `vim.opt`: >lua
---- vim.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`.
----</pre>
-
---- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+--- @brief <pre>help
+--- *vim.opt_local*
+--- *vim.opt_global*
+--- *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: >vim
+--- set wildignore=*.o,*.a,__pycache__
+--- <
+--- In Lua using `vim.o`: >lua
+--- vim.o.wildignore = '*.o,*.a,__pycache__'
+--- <
+--- In Lua using `vim.opt`: >lua
+--- vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+--- <
+--- To replicate the behavior of |:set+=|, use: >lua
+---
+--- vim.opt.wildignore:append { "*.pyc", "node_modules" }
+--- <
+--- To replicate the behavior of |:set^=|, use: >lua
+---
+--- vim.opt.wildignore:prepend { "new_first_value" }
+--- <
+--- To replicate the behavior of |:set-=|, use: >lua
+---
+--- vim.opt.wildignore:remove { "node_modules" }
+--- <
+--- The following methods of setting a map-style option are equivalent:
+--- In Vimscript: >vim
+--- set listchars=space:_,tab:>~
+--- <
+--- In Lua using `vim.o`: >lua
+--- vim.o.listchars = 'space:_,tab:>~'
+--- <
+--- In Lua using `vim.opt`: >lua
+--- vim.opt.listchars = { space = '_', tab = '>~' }
+--- <
+---
+--- Note that |vim.opt| returns an `Option` object, not the value of the option,
+--- which is accessed through |vim.opt:get()|:
+---
+--- Examples: ~
+---
+--- The following methods of getting a list-style option are equivalent:
+--- In Vimscript: >vim
+--- echo wildignore
+--- <
+--- In Lua using `vim.o`: >lua
+--- print(vim.o.wildignore)
+--- <
+--- In Lua using `vim.opt`: >lua
+--- vim.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`.
+--- </pre>
+
+--- @nodoc
+--- @class vim.Option
local Option = {} -- luacheck: no unused
--- Returns a Lua-representation of the option. Boolean, number and string
@@ -856,9 +884,7 @@ local Option = {} -- luacheck: no unused
--- print("J is enabled!")
--- end
--- ```
----
---@return string|integer|boolean|nil value of option
----@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:get() end
--- Append a value to string-style options. See |:set+=|
@@ -869,7 +895,6 @@ function Option:get() end
--- vim.opt.formatoptions:append('j')
--- vim.opt.formatoptions = vim.opt.formatoptions + 'j'
--- ```
----
---@param value string Value to append
---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:append(value) end -- luacheck: no unused
@@ -882,7 +907,6 @@ function Option:append(value) end -- luacheck: no unused
--- vim.opt.wildignore:prepend('*.o')
--- vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
--- ```
----
---@param value string Value to prepend
---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:prepend(value) end -- luacheck: no unused
@@ -895,7 +919,6 @@ function Option:prepend(value) end -- luacheck: no unused
--- vim.opt.wildignore:remove('*.pyc')
--- vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
--- ```
----
---@param value string Value to remove
---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:remove(value) end -- luacheck: no unused
generated by cgit (git 2.34.1) at 2025-04-28 13:44:28 +0000