diff options
Diffstat (limited to 'runtime/lua/vim')
| -rw-r--r-- | runtime/lua/vim/_meta/builtin.lua | 236 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/diff.lua | 67 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/json.lua | 35 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/misc.lua | 11 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/mpack.lua | 13 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/regex.lua | 34 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/spell.lua | 29 | ||||
| -rw-r--r-- | runtime/lua/vim/_options.lua | 381 | ||||
| -rw-r--r-- | runtime/lua/vim/highlight.lua | 65 |
9 files changed, 838 insertions, 33 deletions
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua new file mode 100644 index 0000000000..384dd4351d --- /dev/null +++ b/runtime/lua/vim/_meta/builtin.lua @@ -0,0 +1,236 @@ +---@meta + +---@defgroup lua-builtin +--- +---@brief <pre>help +---vim.api.{func}({...}) *vim.api* +--- Invokes Nvim |API| function {func} with arguments {...}. +--- Example: call the "nvim_get_current_line()" API function: >lua +--- print(tostring(vim.api.nvim_get_current_line())) +--- +---vim.NIL *vim.NIL* +--- Special value representing NIL in |RPC| and |v:null| in Vimscript +--- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua +--- table representing a Dictionary or Array, because it is treated as +--- missing: `{"foo", nil}` is the same as `{"foo"}`. +--- +---vim.type_idx *vim.type_idx* +--- Type index for use in |lua-special-tbl|. Specifying one of the values from +--- |vim.types| allows typing the empty table (it is unclear whether empty Lua +--- table represents empty list or empty array) and forcing integral numbers +--- to be |Float|. See |lua-special-tbl| for more details. +--- +---vim.val_idx *vim.val_idx* +--- Value index for tables representing |Float|s. A table representing +--- floating-point value 1.0 looks like this: >lua +--- { +--- [vim.type_idx] = vim.types.float, +--- [vim.val_idx] = 1.0, +--- } +---< See also |vim.type_idx| and |lua-special-tbl|. +--- +---vim.types *vim.types* +--- Table with possible values for |vim.type_idx|. Contains two sets of +--- key-value pairs: first maps possible values for |vim.type_idx| to +--- human-readable strings, second maps human-readable type names to values +--- for |vim.type_idx|. Currently contains pairs for `float`, `array` and +--- `dictionary` types. +--- +--- Note: One must expect that values corresponding to `vim.types.float`, +--- `vim.types.array` and `vim.types.dictionary` fall under only two following +--- assumptions: +--- 1. Value may serve both as a key and as a value in a table. Given the +--- properties of Lua tables this basically means “value is not `nil`”. +--- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the +--- same as `value`. +--- No other restrictions are put on types, and it is not guaranteed that +--- values corresponding to `vim.types.float`, `vim.types.array` and +--- `vim.types.dictionary` will not change or that `vim.types` table will only +--- contain values for these three types. +--- +--- *log_levels* *vim.log.levels* +---Log levels are one of the values defined in `vim.log.levels`: +--- +--- vim.log.levels.DEBUG +--- vim.log.levels.ERROR +--- vim.log.levels.INFO +--- vim.log.levels.TRACE +--- vim.log.levels.WARN +--- vim.log.levels.OFF +--- +---</pre> + +--- Returns true if the code is executing as part of a "fast" event handler, +--- where most of the API is disabled. These are low-level events (e.g. +--- |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. +--- When this is `false` most API functions are callable (but may be subject +--- to other restrictions such as |textlock|). +function vim.in_fast_event() end + +--- Creates a special empty table (marked with a metatable), which Nvim to an +--- empty dictionary when translating Lua values to Vimscript or API types. +--- Nvim by default converts an empty table `{}` without this metatable to an +--- list/array. +--- +--- Note: If numeric keys are present in the table, Nvim ignores the metatable +--- marker and converts the dict to a list/array anyway. +function vim.empty_dict() end + +--- Sends {event} to {channel} via |RPC| and returns immediately. If {channel} +--- is 0, the event is broadcast to all channels. +--- +--- This function also works in a fast callback |lua-loop-callbacks|. +--- @param channel integer +--- @param method string +--- @param args? any[] +--- @param ...? any +function vim.rpcnotify(channel, method, args, ...) end + +--- Sends a request to {channel} to invoke {method} via |RPC| and blocks until +--- a response is received. +--- +--- Note: NIL values as part of the return value is represented as |vim.NIL| +--- special value +--- @param channel integer +--- @param method string +--- @param args? any[] +--- @param ...? any +function vim.rpcrequest(channel, method, args, ...) end + +--- Compares strings case-insensitively. +--- @param a string +--- @param b string +--- @return 0|1|-1 +--- if strings are +--- equal, {a} is greater than {b} or {a} is lesser than {b}, respectively. +function vim.stricmp(a, b) end + +--- Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not +--- supplied, it defaults to false (use UTF-32). Returns the byte index. +--- +--- Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. +--- An {index} in the middle of a UTF-16 sequence is rounded upwards to +--- the end of that sequence. +--- @param str string +--- @param index number +--- @param use_utf16? any +function vim.str_byteindex(str, index, use_utf16) end + +--- Convert byte index to UTF-32 and UTF-16 indices. If {index} is not +--- supplied, the length of the string is used. All indices are zero-based. +--- +--- Embedded NUL bytes are treated as terminating the string. Invalid UTF-8 +--- bytes, and embedded surrogates are counted as one code point each. An +--- {index} in the middle of a UTF-8 sequence is rounded upwards to the end of +--- that sequence. +--- @param str string +--- @param index? number +--- @return integer UTF-32 index +--- @return integer UTF-16 index +function vim.str_utfindex(str, index) end + +--- The result is a String, which is the text {str} converted from +--- encoding {from} to encoding {to}. When the conversion fails `nil` is +--- returned. When some characters could not be converted they +--- are replaced with "?". +--- The encoding names are whatever the iconv() library function +--- can accept, see ":Man 3 iconv". +--- +--- @param str string Text to convert +--- @param from number Encoding of {str} +--- @param to number Target encoding +--- @param opts? table<string, any> +--- @return string|nil Converted string if conversion succeeds, `nil` otherwise. +function vim.iconv(str, from, to, opts) end + +--- Schedules {callback} to be invoked soon by the main event-loop. Useful +--- to avoid |textlock| or other temporary restrictions. +--- @param callback fun() +function vim.schedule(callback) end + +--- Wait for {time} in milliseconds until {callback} returns `true`. +--- +--- Executes {callback} immediately and at approximately {interval} +--- milliseconds (default 200). Nvim still processes other events during +--- this time. +--- +--- Examples: +--- <pre>lua +--- +--- --- +--- -- Wait for 100 ms, allowing other events to process +--- vim.wait(100, function() end) +--- +--- --- +--- -- Wait for 100 ms or until global variable set. +--- vim.wait(100, function() return vim.g.waiting_for_var end) +--- +--- --- +--- -- Wait for 1 second or until global variable set, checking every ~500 ms +--- vim.wait(1000, function() return vim.g.waiting_for_var end, 500) +--- +--- --- +--- -- Schedule a function to set a value in 100ms +--- vim.defer_fn(function() vim.g.timer_result = true end, 100) +--- +--- -- Would wait ten seconds if results blocked. Actually only waits 100 ms +--- if vim.wait(10000, function() return vim.g.timer_result end) then +--- print('Only waiting a little bit of time!') +--- end +--- </pre> +--- +--- @param time integer Number of milliseconds to wait +--- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true +--- @param interval? integer (Approximate) number of milliseconds to wait between polls +--- @param fast_only? boolean If true, only |api-fast| events will be processed. +--- If called from while in an |api-fast| event, will +--- automatically be set to `true`. +--- @return boolean, nil|-1|-2 +--- - If {callback} returns `true` during the {time}: `true, nil` +--- - If {callback} never returns `true` during the {time}: `false, -1` +--- - If {callback} is interrupted during the {time}: `false, -2` +--- - If {callback} errors, the error is raised. +function vim.wait(time, callback, interval, fast_only) end + +--- Attach to ui events, similar to |nvim_ui_attach()| but receive events +--- as Lua callback. Can be used to implement screen elements like +--- popupmenu or message handling in Lua. +--- +--- {options} should be a dictionary-like table, where `ext_...` options should +--- be set to true to receive events for the respective external element. +--- +--- {callback} receives event name plus additional parameters. See |ui-popupmenu| +--- and the sections below for event format for respective events. +--- +--- WARNING: This api is considered experimental. Usability will vary for +--- different screen elements. In particular `ext_messages` behavior is subject +--- to further changes and usability improvements. This is expected to be +--- used to handle messages when setting 'cmdheight' to zero (which is +--- likewise experimental). +--- +--- Example (stub for a |ui-popupmenu| implementation): +--- <pre>lua +--- +--- ns = vim.api.nvim_create_namespace('my_fancy_pum') +--- +--- vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...) +--- if event == "popupmenu_show" then +--- local items, selected, row, col, grid = ... +--- print("display pum ", #items) +--- elseif event == "popupmenu_select" then +--- local selected = ... +--- print("selected", selected) +--- elseif event == "popupmenu_hide" then +--- print("FIN") +--- end +--- end) +--- </pre> +--- @param ns integer +--- @param options table<string, any> +--- @param callback fun() +function vim.ui_attach(ns, options, callback) end + +--- Detach a callback previously attached with |vim.ui_attach()| for the +--- given namespace {ns}. +--- @param ns integer +function vim.ui_detach(ns) end diff --git a/runtime/lua/vim/_meta/diff.lua b/runtime/lua/vim/_meta/diff.lua new file mode 100644 index 0000000000..8e8aaf8b64 --- /dev/null +++ b/runtime/lua/vim/_meta/diff.lua @@ -0,0 +1,67 @@ +---@meta + +--- Run diff on strings {a} and {b}. Any indices returned by this function, +--- either directly or via callback arguments, are 1-based. +--- +--- Examples: +--- <pre>lua +--- vim.diff('a\\n', 'b\\nc\\n') +--- -- => +--- -- @@ -1 +1,2 @@ +--- -- -a +--- -- +b +--- -- +c +--- +--- vim.diff('a\\n', 'b\\nc\\n', {result_type = 'indices'}) +--- -- => +--- -- { +--- -- {1, 1, 1, 2} +--- -- } +--- </pre> +--- +--- @param a string First string to compare +--- @param b string Second string to compare +--- @param opts table<string,any> Optional parameters: +--- - `on_hunk` (callback): +--- Invoked for each hunk in the diff. Return a negative number +--- to cancel the callback for any remaining hunks. +--- Args: +--- - `start_a` (integer): Start line of hunk in {a}. +--- - `count_a` (integer): Hunk size in {a}. +--- - `start_b` (integer): Start line of hunk in {b}. +--- - `count_b` (integer): Hunk size in {b}. +--- - `result_type` (string): Form of the returned diff: +--- - "unified": (default) String in unified format. +--- - "indices": Array of hunk locations. +--- Note: This option is ignored if `on_hunk` is used. +--- - `linematch` (boolean|integer): Run linematch on the resulting hunks +--- from xdiff. When integer, only hunks upto this size in +--- lines are run through linematch. Requires `result_type = indices`, +--- ignored otherwise. +--- - `algorithm` (string): +--- Diff algorithm to use. Values: +--- - "myers" the default algorithm +--- - "minimal" spend extra time to generate the +--- smallest possible diff +--- - "patience" patience diff algorithm +--- - "histogram" histogram diff algorithm +--- - `ctxlen` (integer): Context length +--- - `interhunkctxlen` (integer): +--- Inter hunk context length +--- - `ignore_whitespace` (boolean): +--- Ignore whitespace +--- - `ignore_whitespace_change` (boolean): +--- Ignore whitespace change +--- - `ignore_whitespace_change_at_eol` (boolean) +--- Ignore whitespace change at end-of-line. +--- - `ignore_cr_at_eol` (boolean) +--- Ignore carriage return at end-of-line +--- - `ignore_blank_lines` (boolean) +--- Ignore blank lines +--- - `indent_heuristic` (boolean): +--- Use the indent heuristic for the internal +--- diff library. +--- +--- @return string|table|nil +--- See {opts.result_type}. `nil` if {opts.on_hunk} is given. +function vim.diff(a, b, opts) end diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua new file mode 100644 index 0000000000..15e81d5004 --- /dev/null +++ b/runtime/lua/vim/_meta/json.lua @@ -0,0 +1,35 @@ +--- @meta + +--- @defgroup lua-json +--- +--- @brief The \*vim.json\* module provides encoding and decoding of Lua objects to and +--- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + +--- Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. +--- +--- - Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below). +--- - Decodes empty object as |vim.empty_dict()|. +--- - Decodes empty array as `{}` (empty Lua table). +--- +--- Example: +--- <pre>lua +--- :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) +--- --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } +--- </pre> +--- Parameters: ~ +--- • {str} Stringified JSON data. +--- • {opts} Options map keys: +--- • luanil: { object: bool, array: bool } +--- • `luanil.object=true` converts `null` in JSON objects to +--- Lua `nil` instead of `vim.NIL`. +--- • `luanil.array=true` converts `null` in JSON arrays to Lua +--- `nil` instead of `vim.NIL`. +--- @param str string +--- @param opts? table<string, any> +--- @return any +function vim.json.decode(str, opts) end + +--- Encodes (or "packs") Lua object {obj} as JSON in a Lua string. +--- @param obj any +--- @return string +function vim.json.encode(obj) end diff --git a/runtime/lua/vim/_meta/misc.lua b/runtime/lua/vim/_meta/misc.lua new file mode 100644 index 0000000000..954e8b4675 --- /dev/null +++ b/runtime/lua/vim/_meta/misc.lua @@ -0,0 +1,11 @@ +---@meta + +--- Invokes |vim-function| or |user-function| {func} with arguments {...}. +--- See also |vim.fn|. +--- Equivalent to: +--- <pre>lua +--- vim.fn[func]({...}) +--- </pre> +--- @param func fun() +--- @param ... any +function vim.call(func, ...) end diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua new file mode 100644 index 0000000000..2764177e5c --- /dev/null +++ b/runtime/lua/vim/_meta/mpack.lua @@ -0,0 +1,13 @@ +--- @meta + +--- @defgroup lua-mpack +--- +--- @brief The \*vim.mpack\* module provides encoding and decoding of Lua objects to and +--- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + +--- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. +--- @param str string +function vim.mpack.decode(str) end + +--- Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. +function vim.mpack.encode(obj) end diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua new file mode 100644 index 0000000000..afa78772da --- /dev/null +++ b/runtime/lua/vim/_meta/regex.lua @@ -0,0 +1,34 @@ +--- @meta + +--- @defgroup lua-regex +--- +--- @brief Vim regexes can be used directly from Lua. Currently they only allow +--- matching within a single line. + +--- Parse the Vim regex {re} and return a regex object. Regexes are "magic" +--- and case-sensitive by default, regardless of 'magic' and 'ignorecase'. +--- They can be controlled with flags, see |/magic| and |/ignorecase|. +--- @param re string +--- @return vim.regex +function vim.regex(re) end + +--- @class vim.regex +local regex = {} + +--- Match the string against the regex. If the string should match the regex +--- precisely, surround the regex with `^` and `$`. If the was a match, the +--- byte indices for the beginning and end of the match is returned. When +--- there is no match, `nil` is returned. As any integer is truth-y, +--- `regex:match()` can be directly used as a condition in an if-statement. +--- @param str string +function regex:match_str(str) end + +--- Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end} +--- are supplied, match only this byte index range. Otherwise see +--- |regex:match_str()|. If {start} is used, then the returned byte indices +--- will be relative {start}. +--- @param bufnr integer +--- @param line_idx integer +--- @param start? integer +--- @param end_? integer +function regex:match_line(bufnr, line_idx, start, end_) end diff --git a/runtime/lua/vim/_meta/spell.lua b/runtime/lua/vim/_meta/spell.lua new file mode 100644 index 0000000000..926c8a686d --- /dev/null +++ b/runtime/lua/vim/_meta/spell.lua @@ -0,0 +1,29 @@ +--- @meta + +--- Check {str} for spelling errors. Similar to the Vimscript function +--- |spellbadword()|. +--- +--- Note: The behaviour of this function is dependent on: 'spelllang', +--- 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to +--- the buffer. Consider calling this with |nvim_buf_call()|. +--- +--- Example: +--- <pre>lua +--- vim.spell.check("the quik brown fox") +--- -- => +--- -- { +--- -- {'quik', 'bad', 5} +--- -- } +--- </pre> +--- +--- @param str string +--- @return {[1]: string, [2]: string, [3]: string}[] +--- List of tuples with three items: +--- - The badly spelled word. +--- - The type of the spelling error: +--- "bad" spelling mistake +--- "rare" rare word +--- "local" word only valid in another region +--- "caps" word should start with Capital +--- - The position in {str} where the word begins. +function vim.spell.check(str) end diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index 41e6e8be86..d498ae0a2c 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -1,3 +1,108 @@ +---@defgroup lua-vimscript +--- +---@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: +---<pre>lua +--- local list = { 1, 2, 3 } +--- vim.fn.remove(list, 0) +--- vim.print(list) --> "{ 1, 2, 3 }" +---</pre> + +---@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`. +--- +---vim.env *vim.env* +--- Environment variables defined in the editor session. +--- See |expand-env| and |:let-environment| for the Vimscript behavior. +--- Invalid or unset key returns `nil`. +--- Example: >lua +--- vim.env.FOO = 'bar' +--- print(vim.env.TERM) +---< +---</pre> + local api = vim.api -- TODO(tjdevries): Improve option metadata so that this doesn't have to be hardcoded. @@ -13,6 +118,7 @@ local key_value_options = { --- Convert a vimoption_T style dictionary to the correct OptionType associated with it. ---@return string +---@private local function get_option_metatype(name, info) if info.type == 'string' then if info.flaglist then @@ -51,6 +157,7 @@ vim.env = setmetatable({}, { end, }) +---@private local function opt_validate(option_name, target_scope) local scope = options_info[option_name].scope if scope ~= target_scope then @@ -67,6 +174,7 @@ local function opt_validate(option_name, target_scope) end end +---@private local function new_buf_opt_accessor(bufnr) return setmetatable({}, { __index = function(_, k) @@ -84,8 +192,7 @@ local function new_buf_opt_accessor(bufnr) }) end -vim.bo = new_buf_opt_accessor() - +---@private local function new_win_opt_accessor(winid, bufnr) return setmetatable({}, { __index = function(_, k) @@ -120,30 +227,118 @@ local function new_win_opt_accessor(winid, bufnr) }) end -vim.wo = new_win_opt_accessor() - --- vim global option --- this ONLY sets the global option. like `setglobal` -vim.go = setmetatable({}, { +---@addtogroup lua-vimscript +---@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|. +--- +--- Examples: ~ +--- +--- 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__'` +--- +---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> + +---@addtogroup lua-vimscript +---@brief <pre>help +---vim.o *vim.o* +--- Get or set |options|. Like `:set`. Invalid key is an error. +--- +--- Note: this works on both buffer-scoped and window-scoped options using the +--- current buffer and window. +--- +--- Example: >lua +--- vim.o.cmdheight = 4 +--- print(vim.o.columns) +--- print(vim.o.foo) -- error: invalid key +---< +---</pre> +vim.o = setmetatable({}, { __index = function(_, k) - return api.nvim_get_option_value(k, { scope = 'global' }) + return api.nvim_get_option_value(k, {}) end, __newindex = function(_, k, v) - return api.nvim_set_option_value(k, v, { scope = 'global' }) + return api.nvim_set_option_value(k, v, {}) end, }) --- vim `set` style options. --- it has no additional metamethod magic. -vim.o = setmetatable({}, { +---@addtogroup lua-vimscript +---@brief <pre>help +---vim.go *vim.go* +--- Get or set global |options|. Like `:setglobal`. Invalid key is +--- an error. +--- +--- Note: this is different from |vim.o| because this accesses the global +--- option value and thus is mostly useful for use with |global-local| +--- options. +--- +--- Example: >lua +--- vim.go.cmdheight = 4 +--- print(vim.go.columns) +--- print(vim.go.bar) -- error: invalid key +---< +---</pre> +vim.go = setmetatable({}, { __index = function(_, k) - return api.nvim_get_option_value(k, {}) + return api.nvim_get_option_value(k, { scope = 'global' }) end, __newindex = function(_, k, v) - return api.nvim_set_option_value(k, v, {}) + return api.nvim_set_option_value(k, v, { scope = 'global' }) end, }) +---@addtogroup lua-vimscript +---@brief <pre>help +---vim.bo[{bufnr}] *vim.bo* +--- 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. +--- +--- Note: this is equivalent to both `:set` and `:setlocal`. +--- +--- Example: >lua +--- local bufnr = vim.api.nvim_get_current_buf() +--- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true +--- print(vim.bo.comments) +--- print(vim.bo.baz) -- error: invalid key +---</pre> +vim.bo = new_buf_opt_accessor() + +---@addtogroup lua-vimscript +---@brief <pre>help +---vim.wo[{winid}][{bufnr}] *vim.wo* +--- 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. +--- +--- Note: only {bufnr} with value `0` (the current buffer in the window) is +--- supported. +--- +--- Example: >lua +--- local winid = vim.api.nvim_get_current_win() +--- vim.wo[winid].number = true -- same as vim.wo.number = true +--- print(vim.wo.foldmarker) +--- print(vim.wo.quux) -- error: invalid key +--- vim.wo[winid][0].spell = false -- like ':setlocal nospell' +---< +---</pre> +vim.wo = new_win_opt_accessor() + ---@brief [[ --- vim.opt, vim.opt_local and vim.opt_global implementation --- @@ -153,6 +348,7 @@ vim.o = setmetatable({}, { ---@brief ]] --- Preserves the order and does not mutate the original list +--- @private local function remove_duplicate_values(t) local result, seen = {}, {} for _, v in ipairs(t) do @@ -168,6 +364,7 @@ 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. +--- @private local function assert_valid_value(name, value, types) local type_of_value = type(value) for _, valid_type in ipairs(types) do @@ -186,14 +383,17 @@ local function assert_valid_value(name, value, types) ) end +--- @private local function passthrough(_, x) return x end +--- @private local function tbl_merge(left, right) return vim.tbl_extend('force', left, right) end +--- @private local function tbl_remove(t, value) if type(value) == 'string' then t[value] = nil @@ -275,6 +475,7 @@ local to_vim_value = { } --- Convert a Lua value to a vimoption_T value +--- @private local function convert_value_to_vim(name, info, value) if value == nil then return vim.NIL @@ -390,6 +591,7 @@ local to_lua_value = { } --- Converts a vimoption_T style value to a Lua value +--- @private local function convert_value_to_lua(info, option_value) return to_lua_value[info.metatype](info, option_value) end @@ -416,6 +618,7 @@ local prepend_methods = { } --- Handles the '^' operator +--- @private local function prepend_value(info, current, new) return prepend_methods[info.metatype]( convert_value_to_lua(info, current), @@ -445,6 +648,7 @@ local add_methods = { } --- Handles the '+' operator +--- @private local function add_value(info, current, new) return add_methods[info.metatype]( convert_value_to_lua(info, current), @@ -452,6 +656,7 @@ local function add_value(info, current, new) ) end +--- @private local function remove_one_item(t, val) if vim.tbl_islist(t) then local remove_index = nil @@ -495,13 +700,16 @@ local remove_methods = { } --- Handles the '-' operator +--- @private local function remove_value(info, current, new) return remove_methods[info.metatype](convert_value_to_lua(info, current), new) end +--- @private local function create_option_accessor(scope) local option_mt + --- @private local function make_option(name, value) local info = assert(options_info[name], 'Not a valid option name: ' .. name) @@ -570,6 +778,151 @@ 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 +local Option = {} + +---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: <pre>lua +--- vim.cmd [[set wildignore=*.pyc,*.o]] +--- +--- vim.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 +---</pre> +--- +---For values that are comma-separated maps, a table will be returned with +---the names as keys and the values as entries: <pre>lua +--- vim.cmd [[set listchars=space:_,tab:>~]] +--- +--- vim.print(vim.opt.listchars:get()) +--- -- { space = "_", tab = ">~", } +--- +--- for char, representation in pairs(vim.opt.listchars:get()) do +--- print(char, "=>", representation) +--- end +---</pre> +--- +---For values that are lists of flags, a set will be returned with the flags +---as keys and `true` as entries. <pre>lua +--- vim.cmd [[set formatoptions=njtcroql]] +--- +--- vim.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 +---</pre> +---@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+=| +--- +---These are equivalent: <pre>lua +--- vim.opt.formatoptions:append('j') +--- vim.opt.formatoptions = vim.opt.formatoptions + 'j' +---</pre> +---@param value string Value to append +--- @diagnostic disable-next-line:unused-local used for gen_vimdoc +function Option:append(value) end + +---Prepend a value to string-style options. See |:set^=| +--- +---These are equivalent: <pre>lua +--- vim.opt.wildignore:prepend('*.o') +--- vim.opt.wildignore = vim.opt.wildignore ^ '*.o' +---</pre> +---@param value string Value to prepend +---@diagnostic disable-next-line:unused-local used for gen_vimdoc +function Option:prepend(value) end + +---Remove a value from string-style options. See |:set-=| +--- +---These are equivalent: <pre>lua +--- vim.opt.wildignore:remove('*.pyc') +--- vim.opt.wildignore = vim.opt.wildignore - '*.pyc' +---</pre> +---@param value string Value to remove +---@diagnostic disable-next-line:unused-local used for gen_vimdoc +function Option:remove(value) end + vim.opt = create_option_accessor() vim.opt_local = create_option_accessor('local') vim.opt_global = create_option_accessor('global') diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua index 86e1adb49e..97a5a1233f 100644 --- a/runtime/lua/vim/highlight.lua +++ b/runtime/lua/vim/highlight.lua @@ -1,3 +1,36 @@ +---@defgroup lua-highlight +--- +---@brief +---Nvim includes a function for highlighting a selection on yank. +--- +---To enable it, add the following to your `init.vim`: +---<pre>vim +--- au TextYankPost * silent! lua vim.highlight.on_yank() +---</pre> +--- +---You can customize the highlight group and the duration of +---the highlight via: +---<pre>vim +--- au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} +---</pre> +--- +---If you want to exclude visual selections from highlighting on yank, use: +---<pre>vim +--- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} +---</pre> +--- +--- <pre>help +---vim.highlight.priorities *vim.highlight.priorities* +--- +--- Table with default priorities used for highlighting: +--- • `syntax`: `50`, used for standard syntax highlighting +--- • `treesitter`: `100`, used for tree-sitter-based highlighting +--- • `semantic_tokens`: `125`, used for LSP semantic token highlighting +--- • `diagnostics`: `150`, used for code analysis such as diagnostics +--- • `user`: `200`, used for user-triggered highlights such as LSP document +--- symbols or `on_yank` autocommands +---</pre> + local api = vim.api local M = {} @@ -10,7 +43,7 @@ M.priorities = { user = 200, } ---- Highlight range between two positions +--- Apply highlight group to range of text. --- ---@param bufnr integer Buffer number to apply highlighting to ---@param ns integer Namespace to add highlight to @@ -18,9 +51,9 @@ M.priorities = { ---@param start integer[]|string Start of region as a (line, column) tuple or string accepted by |getpos()| ---@param finish integer[]|string End of region as a (line, column) tuple or string accepted by |getpos()| ---@param opts table|nil Optional parameters --- - regtype type of range (see |setreg()|, default charwise) --- - inclusive boolean indicating whether the range is end-inclusive (default false) --- - priority number indicating priority of highlight (default priorities.user) +--- - regtype type of range (see |setreg()|, default charwise) +--- - inclusive boolean indicating whether the range is end-inclusive (default false) +--- - priority number indicating priority of highlight (default priorities.user) function M.range(bufnr, ns, higroup, start, finish, opts) opts = opts or {} local regtype = opts.regtype or 'v' @@ -46,22 +79,16 @@ end local yank_ns = api.nvim_create_namespace('hlyank') local yank_timer ---- Highlight the yanked region ---- ---- use from init.vim via ---- au TextYankPost * lua vim.highlight.on_yank() ---- customize highlight group and timeout via ---- au TextYankPost * lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} ---- customize conditions (here: do not highlight a visual selection) via ---- au TextYankPost * lua vim.highlight.on_yank {on_visual=false} + +--- Highlight the yanked text --- --- @param opts table|nil Optional parameters --- - higroup highlight group for yanked region (default "IncSearch") --- - timeout time in ms before highlight is cleared (default 150) --- - on_macro highlight when executing macro (default false) --- - on_visual highlight when yanking visual selection (default true) --- - event event structure (default vim.v.event) --- - priority integer priority (default |vim.highlight.priorities|`.user`) +--- @param opts table|nil Optional parameters +--- - higroup highlight group for yanked region (default "IncSearch") +--- - timeout time in ms before highlight is cleared (default 150) +--- - on_macro highlight when executing macro (default false) +--- - on_visual highlight when yanking visual selection (default true) +--- - event event structure (default vim.v.event) +--- - priority integer priority (default |vim.highlight.priorities|`.user`) function M.on_yank(opts) vim.validate({ opts = { |