diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 81449bc454..d53b66a865 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -565,51 +565,31 @@ A subset of the `vim.*` API is available in threads. This includes: - `vim.is_thread()` returns true from a non-main thread. ------------------------------------------------------------------------------ +VIM.LPEG *lua-lpeg* + + *vim.lpeg* *vim.re* +The Lpeg library for parsing expression grammars is being included as +`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like +interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). + +============================================================================== VIM.HIGHLIGHT *lua-highlight* -Nvim includes a function for highlighting a selection on yank (see for example -https://github.com/machakann/vim-highlightedyank). To enable it, add ->vim + +Nvim includes a function for highlighting a selection on yank. + +To enable it, add the following to your `init.vim` : >vim au TextYankPost * silent! lua vim.highlight.on_yank() < -to your `init.vim`. You can customize the highlight group and the duration of -the highlight via ->vim + +You can customize the highlight group and the duration of the highlight +via: >vim au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} < -If you want to exclude visual selections from highlighting on yank, use ->vim + +If you want to exclude visual selections from highlighting on yank, use: >vim au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} < -vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* - Highlights the yanked text. The fields of the optional dict {opts} - control the highlight: - - {higroup} highlight group for yanked region (default |hl-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 |v:event|) - - {priority} priority of highlight (default |vim.highlight.priorities|`.user`) - - -vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts}) - *vim.highlight.range()* - - Apply highlight group to range of text. - - Parameters: ~ - • {bufnr} buffer number - • {ns} namespace for highlights - • {hlgroup} highlight group name - • {start} starting position (tuple {line,col}) - • {finish} finish position (tuple {line,col}) - • {opts} optional parameters: - • `regtype`: type of range (characterwise, linewise, - or blockwise, see |setreg()|), default `'v'` - • `inclusive`: range includes end position, - default `false` - • `priority`: priority of highlight, default - `vim.highlight.user` (see below) vim.highlight.priorities *vim.highlight.priorities* @@ -621,41 +601,83 @@ vim.highlight.priorities *vim.highlight.priorities* • `user`: `200`, used for user-triggered highlights such as LSP document symbols or `on_yank` autocommands ------------------------------------------------------------------------------- +vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* + Highlight the yanked text + + Parameters: ~ + • {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`) + + *vim.highlight.range()* +vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) + Apply highlight group to range of text. + + Parameters: ~ + • {bufnr} (integer) Buffer number to apply highlighting to + • {ns} (integer) Namespace to add highlight to + • {higroup} (string) Highlight group to use for highlighting + • {start} integer[]|string Start of region as a (line, column) tuple + or string accepted by |getpos()| + • {finish} integer[]|string End of region as a (line, column) tuple or + string accepted by |getpos()| + • {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) + + +============================================================================== VIM.REGEX *lua-regex* + Vim regexes can be used directly from Lua. Currently they only allow matching within a single line. + vim.regex({re}) *vim.regex()* 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|. -Methods on the regex object: + Parameters: ~ + • {re} (string) -regex:match_str({str}) *regex:match_str()* - 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. + Return: ~ + vim.regex -regex:match_line({bufnr}, {line_idx} [, {start}, {end}]) *regex:match_line()* + *regex:match_line()* +vim.regex:match_line({bufnr}, {line_idx}, {start}, {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}. ------------------------------------------------------------------------------- -VIM.LPEG *lua-lpeg* + Parameters: ~ + • {bufnr} (integer) + • {line_idx} (integer) + • {start} (integer|nil) + • {end_} (integer|nil) - *vim.lpeg* *vim.re* -The Lpeg library for parsing expression grammars is being included as -`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like -interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). +vim.regex:match_str({str}) *regex:match_str()* + 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. ------------------------------------------------------------------------------- + Parameters: ~ + • {str} (string) + + +============================================================================== VIM.DIFF *lua-diff* vim.diff({a}, {b}, {opts}) *vim.diff()* @@ -663,108 +685,127 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* either directly or via callback arguments, are 1-based. Examples: >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} - -- } + 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} + -- } < + Parameters: ~ - • {a} First string to compare - • {b} Second string to compare - • {opts} 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. + • {a} (string) First string to compare + • {b} (string) Second string to compare + • {opts} table 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: ~ - See {opts.result_type}. nil if {opts.on_hunk} is given. + string|table|nil See {opts.result_type}. `nil` if {opts.on_hunk} is + given. ------------------------------------------------------------------------------- + +============================================================================== VIM.MPACK *lua-mpack* -The *vim.mpack* module provides encoding and decoding of Lua objects to and -from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. -vim.mpack.encode({obj}) *vim.mpack.encode* - Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. +The *vim.mpack* module provides encoding and decoding of Lua objects to +and from msgpack-encoded strings. Supports |vim.NIL| and +|vim.empty_dict()|. -vim.mpack.decode({str}) *vim.mpack.decode* + +vim.mpack.decode({str}) *vim.mpack.decode()* Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. ------------------------------------------------------------------------------- + Parameters: ~ + • {str} (string) + +vim.mpack.encode({obj}) *vim.mpack.encode()* + Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. + + +============================================================================== VIM.JSON *lua-json* + The *vim.json* module provides encoding and decoding of Lua objects to and from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. -vim.json.encode({obj}) *vim.json.encode* - Encodes (or "packs") Lua object {obj} as JSON in a Lua string. -vim.json.decode({str}[, {opts}]) *vim.json.decode* +vim.json.decode({str}, {opts}) *vim.json.decode()* 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). + • 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: >lua - :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) - --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } -< - 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`. ------------------------------------------------------------------------------- + :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) + --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } + + < 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` . + + Parameters: ~ + • {str} (string) + • {opts} table + + Return: ~ + any + +vim.json.encode({obj}) *vim.json.encode()* + Encodes (or "packs") Lua object {obj} as JSON in a Lua string. + + Parameters: ~ + • {obj} any + + Return: ~ + (string) + + +============================================================================== VIM.SPELL *lua-spell* vim.spell.check({str}) *vim.spell.check()* @@ -776,205 +817,49 @@ vim.spell.check({str}) *vim.spell.check()* the buffer. Consider calling this with |nvim_buf_call()|. Example: >lua - vim.spell.check("the quik brown fox") - -- => - -- { - -- {'quik', 'bad', 5} - -- } + + vim.spell.check("the quik brown fox") + -- => + -- { + -- {'quik', 'bad', 5} + -- } < + Parameters: ~ - • {str} String to spell check. + • {str} (string) Return: ~ - 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. + {[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. ------------------------------------------------------------------------------- + +============================================================================== VIM *lua-builtin* -vim.api.{func}({...}) *vim.api* + +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.in_fast_event() *vim.in_fast_event()* - 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|). - -vim.NIL *vim.NIL* +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.empty_dict() *vim.empty_dict()* - 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. - -vim.rpcnotify({channel}, {method} [, {args}...]) *vim.rpcnotify()* - 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|. - -vim.rpcrequest({channel}, {method} [, {args}...]) *vim.rpcrequest()* - 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 - -vim.stricmp({a}, {b}) *vim.stricmp()* - Compares strings case-insensitively. Returns 0, 1 or -1 if strings are - equal, {a} is greater than {b} or {a} is lesser than {b}, respectively. - -vim.str_utfindex({str} [, {index}]) *vim.str_utfindex()* - 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. - Returns two values: the UTF-32 and UTF-16 indices respectively. - - 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. - -vim.str_byteindex({str}, {index} [, {use_utf16}]) *vim.str_byteindex()* - 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. - -vim.iconv({str}, {from}, {to}[, {opts}]) *vim.iconv()* - 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". - - Parameters: ~ - • {str} (string) Text to convert - • {from} (string) Encoding of {str} - • {to} (string) Target encoding - - Returns: ~ - Converted string if conversion succeeds, `nil` otherwise. - -vim.schedule({callback}) *vim.schedule()* - Schedules {callback} to be invoked soon by the main event-loop. Useful - to avoid |textlock| or other temporary restrictions. - -vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()* - 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. - - Parameters: ~ - • {time} Number of milliseconds to wait - • {callback} Optional callback. Waits until {callback} returns true - • {interval} (Approximate) number of milliseconds to wait between polls - • {fast_only} If true, only |api-fast| events will be processed. - If called from while in an |api-fast| event, will - automatically be set to `true`. - - Returns: ~ - 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. - - Examples: >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 -< - -vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* - 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): >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) - -vim.ui_detach({ns}) *vim.ui_detach()* - Detach a callback previously attached with |vim.ui_attach()| for the - given namespace {ns}. - -vim.type_idx *vim.type_idx* +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* +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 { @@ -983,7 +868,7 @@ vim.val_idx *vim.val_idx* } < See also |vim.type_idx| and |lua-special-tbl|. -vim.types *vim.types* +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 @@ -1012,28 +897,230 @@ Log levels are one of the values defined in `vim.log.levels`: vim.log.levels.WARN vim.log.levels.OFF ------------------------------------------------------------------------------- +vim.empty_dict() *vim.empty_dict()* + 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. + +vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* + 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". + + Parameters: ~ + • {str} (string) Text to convert + • {from} (number) Encoding of {str} + • {to} (number) Target encoding + • {opts} table + + Return: ~ + (string|nil) Converted string if conversion succeeds, `nil` otherwise. + +vim.in_fast_event() *vim.in_fast_event()* + 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|). + +vim.rpcnotify({channel}, {method}, {args}, {...}) *vim.rpcnotify()* + 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|. + + Parameters: ~ + • {channel} (integer) + • {method} (string) + • {args} any[]|nil + • {...} any|nil + +vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()* + 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 + + Parameters: ~ + • {channel} (integer) + • {method} (string) + • {args} any[]|nil + • {...} any|nil + +vim.schedule({callback}) *vim.schedule()* + Schedules {callback} to be invoked soon by the main event-loop. Useful to + avoid |textlock| or other temporary restrictions. + + Parameters: ~ + • {callback} fun() + +vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()* + 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. + + Parameters: ~ + • {str} (string) + • {index} (number) + • {use_utf16} any|nil + +vim.str_utfindex({str}, {index}) *vim.str_utfindex()* + 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. + + Parameters: ~ + • {str} (string) + • {index} (number|nil) + + Return (multiple): ~ + (integer) UTF-32 index + (integer) UTF-16 index + +vim.stricmp({a}, {b}) *vim.stricmp()* + Compares strings case-insensitively. + + Parameters: ~ + • {a} (string) + • {b} (string) + + Return: ~ + 0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser + than {b}, respectively. + +vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* + 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): >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) +< + + Parameters: ~ + • {ns} (integer) + • {options} table + • {callback} fun() + +vim.ui_detach({ns}) *vim.ui_detach()* + Detach a callback previously attached with |vim.ui_attach()| for the given + namespace {ns}. + + Parameters: ~ + • {ns} (integer) + +vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* + 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: >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 +< + + Parameters: ~ + • {time} (integer) Number of milliseconds to wait + • {callback} fun():|nil boolean Optional callback. Waits until + {callback} returns true + • {interval} (integer|nil) (Approximate) number of milliseconds to + wait between polls + • {fast_only} (boolean|nil) 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. + + +============================================================================== LUA-VIMSCRIPT BRIDGE *lua-vimscript* + 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: >lua - +"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 } vim.fn.remove(list, 0) vim.print(list) --> "{ 1, 2, 3 }" - +< 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()|. @@ -1115,7 +1202,7 @@ vim.env *vim.env* print(vim.env.TERM) < - *lua-options* +` ` *lua-options* *lua-vim-options* *lua-vim-set* *lua-vim-setlocal* @@ -1149,6 +1236,7 @@ vim.o *vim.o* print(vim.o.columns) print(vim.o.foo) -- error: invalid key < + vim.go *vim.go* Get or set global |options|. Like `:setglobal`. Invalid key is an error. @@ -1162,6 +1250,7 @@ vim.go *vim.go* print(vim.go.columns) print(vim.go.bar) -- error: invalid key < + 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 @@ -1174,7 +1263,7 @@ vim.bo[{bufnr}] * vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true print(vim.bo.comments) print(vim.bo.baz) -- error: invalid key -< + 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 @@ -1192,13 +1281,10 @@ vim.wo[{winid}][{bufnr}] * vim.wo[winid][0].spell = false -- like ':setlocal nospell' < - - - *vim.opt_local* +` ` *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. @@ -1258,11 +1344,18 @@ 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`. +Option:append({value}) *vim.opt:append()* + Append a value to string-style options. See |:set+=| + These are equivalent: >lua + vim.opt.formatoptions:append('j') + vim.opt.formatoptions = vim.opt.formatoptions + 'j' +< - *vim.opt:get()* -Option:get() + Parameters: ~ + • {value} (string) Value to append +Option:get() *vim.opt:get()* Returns a Lua-representation of the option. Boolean, number and string values will be returned in exactly the same fashion. @@ -1279,6 +1372,7 @@ Option:get() -- 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: >lua vim.cmd [[set listchars=space:_,tab:>~]] @@ -1290,6 +1384,7 @@ Option:get() 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. >lua vim.cmd [[set formatoptions=njtcroql]] @@ -1302,27 +1397,22 @@ Option:get() print("J is enabled!") end < - *vim.opt:append()* -Option:append(value) - Append a value to string-style options. See |:set+=| - - These are equivalent: >lua - vim.opt.formatoptions:append('j') - vim.opt.formatoptions = vim.opt.formatoptions + 'j' -< - *vim.opt:prepend()* -Option:prepend(value) + Return: ~ + string|integer|boolean|nil value of option +Option:prepend({value}) *vim.opt:prepend()* Prepend a value to string-style options. See |:set^=| These are equivalent: >lua vim.opt.wildignore:prepend('*.o') vim.opt.wildignore = vim.opt.wildignore ^ '*.o' < - *vim.opt:remove()* -Option:remove(value) + Parameters: ~ + • {value} (string) Value to prepend + +Option:remove({value}) *vim.opt:remove()* Remove a value from string-style options. See |:set-=| These are equivalent: >lua @@ -1330,10 +1420,14 @@ Option:remove(value) vim.opt.wildignore = vim.opt.wildignore - '*.pyc' < + Parameters: ~ + • {value} (string) Value to remove + + ============================================================================== Lua module: vim *lua-vim* -cmd({command}) *vim.cmd()* +vim.cmd({command}) *vim.cmd()* Execute Vim script commands. Note that `vim.cmd` can be indexed with a command name to return a @@ -1379,10 +1473,10 @@ cmd({command}) *vim.cmd()* • |ex-cmd-index| *vim.connection_failure_errmsg()* -connection_failure_errmsg({consequence}) +vim.connection_failure_errmsg({consequence}) TODO: Documentation -defer_fn({fn}, {timeout}) *vim.defer_fn()* +vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer that calls {fn} Note: The {fn} is @@ -1397,7 +1491,7 @@ defer_fn({fn}, {timeout}) *vim.defer_fn()* (table) timer luv timer object *vim.deprecate()* -deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) +vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Shows a deprecation message to the user. Parameters: ~ @@ -1411,7 +1505,7 @@ deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Return: ~ (string|nil) # Deprecated message, or nil if no message was shown. -inspect({object}, {options}) *vim.inspect()* +vim.inspect({object}, {options}) *vim.inspect()* Gets a human-readable representation of the given object. See also: ~ @@ -1419,7 +1513,7 @@ inspect({object}, {options}) *vim.inspect()* • https://github.com/kikito/inspect.lua • https://github.com/mpeterv/vinspect -keycode({str}) *vim.keycode()* +vim.keycode({str}) *vim.keycode()* Translate keycodes. Example: >lua @@ -1437,13 +1531,13 @@ keycode({str}) *vim.keycode()* See also: ~ • |nvim_replace_termcodes()| -lua_omnifunc({find_start}, {_}) *vim.lua_omnifunc()* +vim.lua_omnifunc({find_start}, {_}) *vim.lua_omnifunc()* Omnifunc for completing Lua values from the runtime Lua interpreter, similar to the builtin completion for the `:lua` command. Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer. -notify({msg}, {level}, {opts}) *vim.notify()* +vim.notify({msg}, {level}, {opts}) *vim.notify()* Display a notification to the user. This function can be overridden by plugins to display notifications using @@ -1455,7 +1549,7 @@ notify({msg}, {level}, {opts}) *vim.notify()* • {level} (integer|nil) One of the values from |vim.log.levels|. • {opts} (table|nil) Optional parameters. Unused by default. -notify_once({msg}, {level}, {opts}) *vim.notify_once()* +vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()* Display a notification only one time. Like |vim.notify()|, but subsequent calls with the same message will not @@ -1469,7 +1563,7 @@ notify_once({msg}, {level}, {opts}) *vim.notify_once()* Return: ~ (boolean) true if message was displayed, else false -on_key({fn}, {ns_id}) *vim.on_key()* +vim.on_key({fn}, {ns_id}) *vim.on_key()* Adds Lua function {fn} with namespace id {ns_id} as a listener to every, yes every, input key. @@ -1492,7 +1586,7 @@ on_key({fn}, {ns_id}) *vim.on_key()* (integer) Namespace id associated with {fn}. Or count of all callbacks if on_key() is called without arguments. -paste({lines}, {phase}) *vim.paste()* +vim.paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. @@ -1524,7 +1618,7 @@ paste({lines}, {phase}) *vim.paste()* See also: ~ • |paste| @alias paste_phase -1 | 1 | 2 | 3 -print({...}) *vim.print()* +vim.print({...}) *vim.print()* "Pretty prints" the given arguments and returns them unmodified. Example: >lua @@ -1539,7 +1633,8 @@ print({...}) *vim.print()* • |vim.inspect()| • |:=| -region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* + *vim.region()* +vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) Gets a dict of line segment ("chunk") positions for the region from `pos1` to `pos2`. @@ -1562,7 +1657,7 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* `endcol` is exclusive, and whole lines are returned as `{startcol,endcol} = {0,-1}`. -schedule_wrap({cb}) *vim.schedule_wrap()* +vim.schedule_wrap({cb}) *vim.schedule_wrap()* Defers callback `cb` until the Nvim API is safe to call. Parameters: ~ @@ -1576,7 +1671,7 @@ schedule_wrap({cb}) *vim.schedule_wrap()* • |vim.schedule()| • |vim.in_fast_event()| -system({cmd}, {opts}, {on_exit}) *vim.system()* +vim.system({cmd}, {opts}, {on_exit}) *vim.system()* Run a system command Examples: >lua @@ -1649,9 +1744,9 @@ system({cmd}, {opts}, {on_exit}) *vim.system()* ============================================================================== -Lua module: inspector *lua-inspector* +Lua module: vim.inspector *lua-inspector* -inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* +vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* Get all the items at a given buffer position. Can also be pretty-printed with `:Inspect!`. *:Inspect!* @@ -1684,7 +1779,7 @@ inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* • row: the row used to get the items • col: the col used to get the items -show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* +vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* Show all the items at a given buffer position. Can also be shown with `:Inspect`. *:Inspect* @@ -1700,7 +1795,7 @@ show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* -deep_equal({a}, {b}) *vim.deep_equal()* +vim.deep_equal({a}, {b}) *vim.deep_equal()* Deep compare values for equality Tables are compared recursively unless they both provide the `eq` metamethod. All other types are compared using the equality `==` operator. @@ -1712,7 +1807,7 @@ deep_equal({a}, {b}) *vim.deep_equal()* Return: ~ (boolean) `true` if values are equals, else `false` -deepcopy({orig}) *vim.deepcopy()* +vim.deepcopy({orig}) *vim.deepcopy()* Returns a deep copy of the given object. Non-table objects are copied as in a typical Lua assignment, whereas table objects are copied recursively. Functions are naively copied, so functions in the copied table point to @@ -1725,7 +1820,7 @@ deepcopy({orig}) *vim.deepcopy()* Return: ~ (table) Table of copied keys and (nested) values. -defaulttable({create}) *vim.defaulttable()* +vim.defaulttable({create}) *vim.defaulttable()* Creates a table whose members are automatically created when accessed, if they don't already exist. @@ -1748,7 +1843,7 @@ defaulttable({create}) *vim.defaulttable()* Return: ~ (table) Empty table with metamethod -endswith({s}, {suffix}) *vim.endswith()* +vim.endswith({s}, {suffix}) *vim.endswith()* Tests if `s` ends with `suffix`. Parameters: ~ @@ -1758,7 +1853,7 @@ endswith({s}, {suffix}) *vim.endswith()* Return: ~ (boolean) `true` if `suffix` is a suffix of `s` -gsplit({s}, {sep}, {opts}) *vim.gsplit()* +vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()* Splits a string at each instance of a separator. Example: >lua @@ -1794,7 +1889,7 @@ gsplit({s}, {sep}, {opts}) *vim.gsplit()* • https://www.lua.org/pil/20.2.html • http://lua-users.org/wiki/StringLibraryTutorial -is_callable({f}) *vim.is_callable()* +vim.is_callable({f}) *vim.is_callable()* Returns true if object `f` can be called as a function. Parameters: ~ @@ -1803,7 +1898,7 @@ is_callable({f}) *vim.is_callable()* Return: ~ (boolean) `true` if `f` is callable, else `false` -list_contains({t}, {value}) *vim.list_contains()* +vim.list_contains({t}, {value}) *vim.list_contains()* Checks if a list-like table (integer keys without gaps) contains `value`. Parameters: ~ @@ -1816,7 +1911,7 @@ list_contains({t}, {value}) *vim.list_contains()* See also: ~ • |vim.tbl_contains()| for checking values in general tables -list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* +vim.list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* Extends a list-like table with the values of another list-like table. NOTE: This mutates dst! @@ -1833,7 +1928,7 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* See also: ~ • |vim.tbl_extend()| -list_slice({list}, {start}, {finish}) *vim.list_slice()* +vim.list_slice({list}, {start}, {finish}) *vim.list_slice()* Creates a copy of a table containing only elements from start to end (inclusive) @@ -1845,7 +1940,7 @@ list_slice({list}, {start}, {finish}) *vim.list_slice()* Return: ~ (list) Copy of table sliced from start to finish (inclusive) -pesc({s}) *vim.pesc()* +vim.pesc({s}) *vim.pesc()* Escapes magic chars in |lua-patterns|. Parameters: ~ @@ -1857,7 +1952,7 @@ pesc({s}) *vim.pesc()* See also: ~ • https://github.com/rxi/lume -ringbuf({size}) *vim.ringbuf()* +vim.ringbuf({size}) *vim.ringbuf()* Create a ring buffer limited to a maximal number of items. Once the buffer is full, adding a new entry overrides the oldest entry. > @@ -1890,28 +1985,28 @@ ringbuf({size}) *vim.ringbuf()* Return: ~ (table) -Ringbuf:clear() *Ringbuf:clear()* +vim.Ringbuf:clear() *Ringbuf:clear()* Clear all items. -Ringbuf:peek() *Ringbuf:peek()* +vim.Ringbuf:peek() *Ringbuf:peek()* Returns the first unread item without removing it Return: ~ any?|ni -Ringbuf:pop() *Ringbuf:pop()* +vim.Ringbuf:pop() *Ringbuf:pop()* Removes and returns the first unread item Return: ~ any?|ni -Ringbuf:push({item}) *Ringbuf:push()* +vim.Ringbuf:push({item}) *Ringbuf:push()* Adds an item, overriding the oldest item if the buffer is full. Parameters: ~ • {item} any -spairs({t}) *vim.spairs()* +vim.spairs({t}) *vim.spairs()* Enumerate a table sorted by its keys. Parameters: ~ @@ -1923,7 +2018,7 @@ spairs({t}) *vim.spairs()* See also: ~ • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua -split({s}, {sep}, {opts}) *vim.split()* +vim.split({s}, {sep}, {opts}) *vim.split()* Splits a string at each instance of a separator. Examples: >lua @@ -1947,7 +2042,7 @@ split({s}, {sep}, {opts}) *vim.split()* • |vim.gsplit()| • |string.gmatch()| -startswith({s}, {prefix}) *vim.startswith()* +vim.startswith({s}, {prefix}) *vim.startswith()* Tests if `s` starts with `prefix`. Parameters: ~ @@ -1957,7 +2052,7 @@ startswith({s}, {prefix}) *vim.startswith()* Return: ~ (boolean) `true` if `prefix` is a prefix of `s` -tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* +vim.tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Add the reverse lookup values to an existing table. For example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` @@ -1969,7 +2064,7 @@ tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Return: ~ (table) o -tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* +vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* Checks if a table contains a given value, specified either directly or via a predicate that is checked for each value. @@ -1994,7 +2089,7 @@ tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* See also: ~ • |vim.list_contains()| for checking values in list-like tables -tbl_count({t}) *vim.tbl_count()* +vim.tbl_count({t}) *vim.tbl_count()* Counts the number of non-nil values in table `t`. >lua @@ -2012,7 +2107,7 @@ tbl_count({t}) *vim.tbl_count()* See also: ~ • https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua -tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* +vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* Merges recursively two or more tables. Parameters: ~ @@ -2029,7 +2124,7 @@ tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* See also: ~ • |vim.tbl_extend()| -tbl_extend({behavior}, {...}) *vim.tbl_extend()* +vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more tables. Parameters: ~ @@ -2046,7 +2141,7 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* See also: ~ • |extend()| -tbl_filter({func}, {t}) *vim.tbl_filter()* +vim.tbl_filter({func}, {t}) *vim.tbl_filter()* Filter a table using a predicate function Parameters: ~ @@ -2056,7 +2151,7 @@ tbl_filter({func}, {t}) *vim.tbl_filter()* Return: ~ (table) Table of filtered values -tbl_flatten({t}) *vim.tbl_flatten()* +vim.tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. @@ -2069,7 +2164,7 @@ tbl_flatten({t}) *vim.tbl_flatten()* See also: ~ • From https://github.com/premake/premake-core/blob/master/src/base/table.lua -tbl_get({o}, {...}) *vim.tbl_get()* +vim.tbl_get({o}, {...}) *vim.tbl_get()* Index into a table (first argument) via string keys passed as subsequent arguments. Return `nil` if the key does not exist. @@ -2087,7 +2182,7 @@ tbl_get({o}, {...}) *vim.tbl_get()* Return: ~ any Nested value indexed by key (if it exists), else nil -tbl_isarray({t}) *vim.tbl_isarray()* +vim.tbl_isarray({t}) *vim.tbl_isarray()* Tests if a Lua table can be treated as an array (a table indexed by integers). @@ -2101,7 +2196,7 @@ tbl_isarray({t}) *vim.tbl_isarray()* Return: ~ (boolean) `true` if array-like table, else `false`. -tbl_isempty({t}) *vim.tbl_isempty()* +vim.tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. Parameters: ~ @@ -2113,7 +2208,7 @@ tbl_isempty({t}) *vim.tbl_isempty()* See also: ~ • https://github.com/premake/premake-core/blob/master/src/base/table.lua -tbl_islist({t}) *vim.tbl_islist()* +vim.tbl_islist({t}) *vim.tbl_islist()* Tests if a Lua table can be treated as a list (a table indexed by consecutive integers starting from 1). @@ -2127,7 +2222,7 @@ tbl_islist({t}) *vim.tbl_islist()* Return: ~ (boolean) `true` if list-like table, else `false`. -tbl_keys({t}) *vim.tbl_keys()* +vim.tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order of the return table of keys is not guaranteed. @@ -2140,7 +2235,7 @@ tbl_keys({t}) *vim.tbl_keys()* See also: ~ • From https://github.com/premake/premake-core/blob/master/src/base/table.lua -tbl_map({func}, {t}) *vim.tbl_map()* +vim.tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. Parameters: ~ @@ -2150,7 +2245,7 @@ tbl_map({func}, {t}) *vim.tbl_map()* Return: ~ (table) Table of transformed values -tbl_values({t}) *vim.tbl_values()* +vim.tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. @@ -2160,7 +2255,7 @@ tbl_values({t}) *vim.tbl_values()* Return: ~ (list) List of values -trim({s}) *vim.trim()* +vim.trim({s}) *vim.trim()* Trim whitespace (Lua pattern "%s") from both sides of a string. Parameters: ~ @@ -2173,7 +2268,7 @@ trim({s}) *vim.trim()* • |luaref-patterns| • https://www.lua.org/pil/20.2.html -validate({opt}) *vim.validate()* +vim.validate({opt}) *vim.validate()* Validates a parameter specification (types and values). Usage example: >lua @@ -2229,21 +2324,21 @@ validate({opt}) *vim.validate()* ============================================================================== -Lua module: loader *lua-loader* +Lua module: vim.loader *lua-loader* -disable() *vim.loader.disable()* +vim.loader.disable() *vim.loader.disable()* Disables the experimental Lua module loader: • removes the loaders • adds the default Nvim loader -enable() *vim.loader.enable()* +vim.loader.enable() *vim.loader.enable()* Enables the experimental Lua module loader: • overrides loadfile • adds the Lua loader using the byte-compilation cache • adds the libs loader • removes the default Nvim loader -find({modname}, {opts}) *vim.loader.find()* +vim.loader.find({modname}, {opts}) *vim.loader.find()* Finds Lua modules for the given module name. Parameters: ~ @@ -2268,7 +2363,7 @@ find({modname}, {opts}) *vim.loader.find()* • stat: (table|nil) the fs_stat of the module path. Won't be returned for `modname="*"` -reset({path}) *vim.loader.reset()* +vim.loader.reset({path}) *vim.loader.reset()* Resets the cache for the path, or all the paths if path is nil. Parameters: ~ @@ -2276,9 +2371,9 @@ reset({path}) *vim.loader.reset()* ============================================================================== -Lua module: uri *lua-uri* +Lua module: vim.uri *lua-uri* -uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* +vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* Get a URI from a bufnr Parameters: ~ @@ -2287,7 +2382,7 @@ uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* Return: ~ (string) URI -uri_from_fname({path}) *vim.uri_from_fname()* +vim.uri_from_fname({path}) *vim.uri_from_fname()* Get a URI from a file path. Parameters: ~ @@ -2296,7 +2391,7 @@ uri_from_fname({path}) *vim.uri_from_fname()* Return: ~ (string) URI -uri_to_bufnr({uri}) *vim.uri_to_bufnr()* +vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()* Get the buffer for a uri. Creates a new unloaded buffer if no buffer for the uri already exists. @@ -2306,7 +2401,7 @@ uri_to_bufnr({uri}) *vim.uri_to_bufnr()* Return: ~ (integer) bufnr -uri_to_fname({uri}) *vim.uri_to_fname()* +vim.uri_to_fname({uri}) *vim.uri_to_fname()* Get a filename from a URI Parameters: ~ @@ -2317,9 +2412,9 @@ uri_to_fname({uri}) *vim.uri_to_fname()* ============================================================================== -Lua module: ui *lua-ui* +Lua module: vim.ui *lua-ui* -input({opts}, {on_confirm}) *vim.ui.input()* +vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* Prompts the user for input, allowing arbitrary (potentially asynchronous) work until `on_confirm`. @@ -2345,7 +2440,7 @@ input({opts}, {on_confirm}) *vim.ui.input()* typed (it might be an empty string if nothing was entered), or `nil` if the user aborted the dialog. -open({path}) *vim.ui.open()* +vim.ui.open({path}) *vim.ui.open()* Opens `path` with the system default handler (macOS `open`, Windows `explorer.exe`, Linux `xdg-open`, …), or returns (but does not show) an error message on failure. @@ -2369,7 +2464,7 @@ open({path}) *vim.ui.open()* See also: ~ • |vim.system()| -select({items}, {opts}, {on_choice}) *vim.ui.select()* +vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous) work until `on_choice`. @@ -2407,9 +2502,9 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* ============================================================================== -Lua module: filetype *lua-filetype* +Lua module: vim.filetype *lua-filetype* -add({filetypes}) *vim.filetype.add()* +vim.filetype.add({filetypes}) *vim.filetype.add()* Add new filetype mappings. Filetype mappings can be added either by extension or by filename (either @@ -2495,7 +2590,8 @@ add({filetypes}) *vim.filetype.add()* • {filetypes} (table) A table containing new filetype maps (see example). -get_option({filetype}, {option}) *vim.filetype.get_option()* + *vim.filetype.get_option()* +vim.filetype.get_option({filetype}, {option}) Get the default option value for a {filetype}. The returned value is what would be set in a new buffer after 'filetype' @@ -2518,7 +2614,7 @@ get_option({filetype}, {option}) *vim.filetype.get_option()* Return: ~ string|boolean|integer: Option value -match({args}) *vim.filetype.match()* +vim.filetype.match({args}) *vim.filetype.match()* Perform filetype detection. The filetype can be detected using one of three methods: @@ -2574,9 +2670,9 @@ match({args}) *vim.filetype.match()* ============================================================================== -Lua module: keymap *lua-keymap* +Lua module: vim.keymap *lua-keymap* -del({modes}, {lhs}, {opts}) *vim.keymap.del()* +vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* Remove an existing mapping. Examples: >lua vim.keymap.del('n', 'lhs') @@ -2592,7 +2688,7 @@ del({modes}, {lhs}, {opts}) *vim.keymap.del()* See also: ~ • |vim.keymap.set()| -set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* +vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* Adds a new |mapping|. Examples: >lua -- Map to a Lua function: @@ -2634,9 +2730,9 @@ set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* ============================================================================== -Lua module: fs *lua-fs* +Lua module: vim.fs *lua-fs* -basename({file}) *vim.fs.basename()* +vim.fs.basename({file}) *vim.fs.basename()* Return the basename of the given file or directory Parameters: ~ @@ -2645,7 +2741,7 @@ basename({file}) *vim.fs.basename()* Return: ~ (string|nil) Basename of {file} -dir({path}, {opts}) *vim.fs.dir()* +vim.fs.dir({path}, {opts}) *vim.fs.dir()* Return an iterator over the files and directories located in {path} Parameters: ~ @@ -2663,7 +2759,7 @@ dir({path}, {opts}) *vim.fs.dir()* two values: name and type. Each "name" is the basename of the file or directory relative to {path}. Type is one of "file" or "directory". -dirname({file}) *vim.fs.dirname()* +vim.fs.dirname({file}) *vim.fs.dirname()* Return the parent directory of the given file or directory Parameters: ~ @@ -2672,7 +2768,7 @@ dirname({file}) *vim.fs.dirname()* Return: ~ (string|nil) Parent directory of {file} -find({names}, {opts}) *vim.fs.find()* +vim.fs.find({names}, {opts}) *vim.fs.find()* Find files or directories in the given path. Finds any files or directories given in {names} starting from {path}. If @@ -2734,7 +2830,7 @@ find({names}, {opts}) *vim.fs.find()* (table) Normalized paths |vim.fs.normalize()| of all matching files or directories -joinpath({...}) *vim.fs.joinpath()* +vim.fs.joinpath({...}) *vim.fs.joinpath()* Concatenate directories and/or file paths into a single path with normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) @@ -2744,7 +2840,7 @@ joinpath({...}) *vim.fs.joinpath()* Return: ~ (string) -normalize({path}, {opts}) *vim.fs.normalize()* +vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* Normalize a path to a standard format. A tilde (~) character at the beginning of the path is expanded to the user's home directory and any backslash (\) characters are converted to forward slashes (/). Environment @@ -2771,7 +2867,7 @@ normalize({path}, {opts}) *vim.fs.normalize()* Return: ~ (string) Normalized path -parents({start}) *vim.fs.parents()* +vim.fs.parents({start}) *vim.fs.parents()* Iterate over all the parents of the given file or directory. Example: >lua @@ -2797,9 +2893,9 @@ parents({start}) *vim.fs.parents()* ============================================================================== -Lua module: secure *lua-secure* +Lua module: vim.secure *lua-secure* -read({path}) *vim.secure.read()* +vim.secure.read({path}) *vim.secure.read()* Attempt to read the file at {path} prompting the user if the file should be trusted. The user's choice is persisted in a trust database at $XDG_STATE_HOME/nvim/trust. @@ -2814,7 +2910,7 @@ read({path}) *vim.secure.read()* See also: ~ • |:trust| -trust({opts}) *vim.secure.trust()* +vim.secure.trust({opts}) *vim.secure.trust()* Manage the trust database. The trust database is located at |$XDG_STATE_HOME|/nvim/trust. @@ -2837,7 +2933,7 @@ trust({opts}) *vim.secure.trust()* ============================================================================== -Lua module: version *lua-version* +Lua module: vim.version *lua-version* The `vim.version` module provides functions for comparing versions and @@ -2897,7 +2993,7 @@ versions (1.2.3-rc1) are not matched. > < -cmp({v1}, {v2}) *vim.version.cmp()* +vim.version.cmp({v1}, {v2}) *vim.version.cmp()* Parses and compares two version objects (the result of |vim.version.parse()|, or specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`). @@ -2925,7 +3021,7 @@ cmp({v1}, {v2}) *vim.version.cmp()* Return: ~ (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. -eq({v1}, {v2}) *vim.version.eq()* +vim.version.eq({v1}, {v2}) *vim.version.eq()* Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. Parameters: ~ @@ -2935,7 +3031,7 @@ eq({v1}, {v2}) *vim.version.eq()* Return: ~ (boolean) -gt({v1}, {v2}) *vim.version.gt()* +vim.version.gt({v1}, {v2}) *vim.version.gt()* Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage. Parameters: ~ @@ -2945,7 +3041,7 @@ gt({v1}, {v2}) *vim.version.gt()* Return: ~ (boolean) -last({versions}) *vim.version.last()* +vim.version.last({versions}) *vim.version.last()* TODO: generalize this, move to func.lua Parameters: ~ @@ -2954,7 +3050,7 @@ last({versions}) *vim.version.last()* Return: ~ Version ?|ni -lt({v1}, {v2}) *vim.version.lt()* +vim.version.lt({v1}, {v2}) *vim.version.lt()* Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage. Parameters: ~ @@ -2964,7 +3060,7 @@ lt({v1}, {v2}) *vim.version.lt()* Return: ~ (boolean) -parse({version}, {opts}) *vim.version.parse()* +vim.version.parse({version}, {opts}) *vim.version.parse()* Parses a semantic version string and returns a version object which can be used with other `vim.version` functions. For example "1.0.1-rc1+build.2" returns: > @@ -2985,7 +3081,7 @@ parse({version}, {opts}) *vim.version.parse()* See also: ~ • # https://semver.org/spec/v2.0.0.html -range({spec}) *vim.version.range()* +vim.version.range({spec}) *vim.version.range()* Parses a semver |version-range| "spec" and returns a range object: > { @@ -3020,7 +3116,7 @@ range({spec}) *vim.version.range()* ============================================================================== -Lua module: iter *lua-iter* +Lua module: vim.iter *lua-iter* The *vim.iter* module provides a generic interface for working with 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 
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
+---
+---
+ +--- 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 +--- @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: +--- 
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
+---
+--- +--- @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): +--- 
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)
+---
+--- @param ns integer +--- @param options table +--- @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: +--- 
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}
+---     -- }
+---
+--- +--- @param a string First string to compare +--- @param b string Second string to compare +--- @param opts table 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: +--- 
lua
+--- :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
+--- --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
+---
+--- 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 +--- @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: +--- 
lua
+---     vim.fn[func]({...})
+---
+--- @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: +--- 
lua
+---     vim.spell.check("the quik brown fox")
+---     -- =>
+---     -- {
+---     --     {'quik', 'bad', 5}
+---     -- }
+---
+--- +--- @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: +---
lua
+---    local list = { 1, 2, 3 }
+---    vim.fn.remove(list, 0)
+---    vim.print(list)  --> "{ 1, 2, 3 }"
+---
+ +---@addtogroup lua-vimscript +---@brief 
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)
+---<
+---
+ 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,10 +227,71 @@ local function new_win_opt_accessor(winid, bufnr) }) end -vim.wo = new_win_opt_accessor() +---@addtogroup lua-vimscript +---@brief 
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|.
+---
--- vim global option --- this ONLY sets the global option. like `setglobal` +---@addtogroup lua-vimscript +---@brief 
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
+---<
+---
+vim.o = setmetatable({}, { + __index = function(_, k) + return api.nvim_get_option_value(k, {}) + end, + __newindex = function(_, k, v) + return api.nvim_set_option_value(k, v, {}) + end, +}) + +---@addtogroup lua-vimscript +---@brief 
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
+---<
+---
vim.go = setmetatable({}, { __index = function(_, k) return api.nvim_get_option_value(k, { scope = 'global' }) @@ -133,16 +301,43 @@ vim.go = setmetatable({}, { end, }) --- vim `set` style options. --- it has no additional metamethod magic. -vim.o = setmetatable({}, { - __index = function(_, k) - return api.nvim_get_option_value(k, {}) - end, - __newindex = function(_, k, v) - return api.nvim_set_option_value(k, v, {}) - end, -}) +---@addtogroup lua-vimscript +---@brief 
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
+---
+vim.bo = new_buf_opt_accessor() + +---@addtogroup lua-vimscript +---@brief 
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'
+---<
+---
+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 
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`.
+---
+ +--- @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: 
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
+---
+--- +---For values that are comma-separated maps, a table will be returned with +---the names as keys and the values as entries: 
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
+---
+--- +---For values that are lists of flags, a set will be returned with the flags +---as keys and `true` as entries. 
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
+---
+---@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: 
lua
+---    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 + +---Prepend a value to string-style options. See |:set^=| +--- +---These are equivalent: 
lua
+---    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 + +---Remove a value from string-style options. See |:set-=| +--- +---These are equivalent: 
lua
+---    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 + 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`: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank()
+---
+--- +---You can customize the highlight group and the duration of +---the highlight via: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
+---
+--- +---If you want to exclude visual selections from highlighting on yank, use: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+---
+--- +--- 
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
+---
+ 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 + +--- Highlight the yanked text --- ---- 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} ---- --- @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 = { diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 6ca330ae22..eacf4dc24d 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -144,6 +144,14 @@ CONFIG = { 'mode': 'lua', 'filename': 'lua.txt', 'section_order': [ + 'highlight.lua', + 'regex.lua', + 'diff.lua', + 'mpack.lua', + 'json.lua', + 'spell.lua', + 'builtin.lua', + '_options.lua', '_editor.lua', '_inspector.lua', 'shared.lua', @@ -160,6 +168,7 @@ CONFIG = { 'files': [ 'runtime/lua/vim/iter.lua', 'runtime/lua/vim/_editor.lua', + 'runtime/lua/vim/_options.lua', 'runtime/lua/vim/shared.lua', 'runtime/lua/vim/loader.lua', 'runtime/lua/vim/uri.lua', @@ -167,30 +176,48 @@ CONFIG = { 'runtime/lua/vim/filetype.lua', 'runtime/lua/vim/keymap.lua', 'runtime/lua/vim/fs.lua', + 'runtime/lua/vim/highlight.lua', 'runtime/lua/vim/secure.lua', 'runtime/lua/vim/version.lua', 'runtime/lua/vim/_inspector.lua', + 'runtime/lua/vim/_meta/builtin.lua', + 'runtime/lua/vim/_meta/diff.lua', + 'runtime/lua/vim/_meta/mpack.lua', + 'runtime/lua/vim/_meta/json.lua', + 'runtime/lua/vim/_meta/regex.lua', + 'runtime/lua/vim/_meta/spell.lua', ], 'file_patterns': '*.lua', 'fn_name_prefix': '', + 'fn_name_fmt': lambda fstem, name: ( + name if fstem in [ 'vim.iter' ] else + f'vim.{name}' if fstem in [ '_editor', 'vim.regex'] else + f'{fstem}.{name}' if fstem.startswith('vim') else + name + ), 'section_name': { 'lsp.lua': 'core', '_inspector.lua': 'inspector', }, 'section_fmt': lambda name: ( - 'Lua module: vim' - if name.lower() == '_editor' - else f'Lua module: {name.lower()}'), + 'Lua module: vim' if name.lower() == '_editor' else + 'LUA-VIMSCRIPT BRIDGE' if name.lower() == '_options' else + f'VIM.{name.upper()}' if name.lower() in [ 'highlight', 'mpack', 'json', 'diff', 'spell', 'regex' ] else + 'VIM' if name.lower() == 'builtin' else + f'Lua module: vim.{name.lower()}'), 'helptag_fmt': lambda name: ( - '*lua-vim*' - if name.lower() == '_editor' - else f'*lua-{name.lower()}*'), + '*lua-vim*' if name.lower() == '_editor' else + '*lua-vimscript*' if name.lower() == '_options' else + f'*lua-{name.lower()}*'), 'fn_helptag_fmt': lambda fstem, name: ( - f'*vim.{name}()*' - if fstem.lower() == '_editor' - else f'*{name}()*' - if name[0].isupper() - else f'*{fstem}.{name}()*'), + f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else + # Exclude fstem for methods + f'*{name}()*' if ':' in name else + f'*vim.{name}()*' if fstem.lower() == '_editor' else + # Prevents vim.regex.regex + f'*{fstem}()*' if fstem.endswith('.' + name) else + f'*{fstem}.{name}()*' + ), 'module_override': { # `shared` functions are exposed on the `vim` module. 'shared': 'vim', @@ -201,9 +228,16 @@ CONFIG = { 'filetype': 'vim.filetype', 'keymap': 'vim.keymap', 'fs': 'vim.fs', + 'highlight': 'vim.highlight', 'secure': 'vim.secure', 'version': 'vim.version', 'iter': 'vim.iter', + 'diff': 'vim', + 'builtin': 'vim', + 'mpack': 'vim.mpack', + 'json': 'vim.json', + 'regex': 'vim.regex', + 'spell': 'vim.spell', }, 'append_only': [ 'shared.lua', @@ -542,6 +576,8 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation, text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1]) elif o[0:4] == 'vim\n': text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1]) + elif o[0:5] == 'help\n': + text += o[4:-1] else: text += '>{}{}\n<'.format(ensure_nl, o) @@ -869,6 +905,9 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): fstem = CONFIG[target]['module_override'].get(fstem, fstem) vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name) + if 'fn_name_fmt' in CONFIG[target]: + name = CONFIG[target]['fn_name_fmt'](fstem, name) + prefix = '%s(' % name suffix = '%s)' % ', '.join('{%s}' % a[1] for a in params if a[0] not in ('void', 'Error', 'Arena',