From aeba27f37bc3acd41febf55eec871f3f7c2acca3 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 4 Apr 2025 16:12:22 +0100 Subject: [PATCH] feat(doc): document Lua alternative for vim.fn AI-assisted: Codex --- runtime/doc/news.txt | 4 +- runtime/doc/vimfn.txt | 549 +++++++++++++++++++++++++++- runtime/lua/vim/_meta/vimfn.gen.lua | 414 ++++++++++++++++++++- src/gen/gen_eval_files.lua | 74 ++++ src/nvim/eval.lua | 415 ++++++++++++++++++++- 5 files changed, 1441 insertions(+), 15 deletions(-) diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index eea4403c0b..94e65736ef 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -163,7 +163,9 @@ LUA • |vim.filetype.inspect()| returns a copy of the internal tables used for filetype detection. • Added `__eq` metamethod to |vim.VersionRange|. 2 distinct but representing -the same range instances now compare equal. + the same range instances now compare equal. +• Documentation for |vim.fn| now points to preferred Lua alternatives when + available. OPTIONS diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 1ec9374d17..e5ebb7f905 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -13,6 +13,8 @@ For functions grouped by what they are used for see |function-list|. 1. Details *vimscript-functions-details* abs({expr}) *abs()* + Lua: Prefer |math.abs()|. + Return the absolute value of {expr}. When {expr} evaluates to a |Float| abs() returns a |Float|. When {expr} can be converted to a |Number| abs() returns a |Number|. Otherwise @@ -32,6 +34,8 @@ abs({expr}) *abs()* (`number`) acos({expr}) *acos()* + Lua: Prefer |math.acos()|. + Return the arc cosine of {expr} measured in radians, as a |Float| in the range of [0, pi]. {expr} must evaluate to a |Float| or a |Number| in the range @@ -51,6 +55,8 @@ acos({expr}) *acos()* (`number`) add({object}, {expr}) *add()* + Lua: Prefer |table.insert()| for lists and `..` for blobs. + Append the item {expr} to |List| or |Blob| {object}. Returns the resulting |List| or |Blob|. Examples: >vim let alist = add([1, 2, 3], item) @@ -70,6 +76,8 @@ add({object}, {expr}) *add()* a |List| or a |Blob|. and({expr}, {expr}) *and()* + Lua: Prefer |bit.band()|. + Bitwise AND on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see |or()| and |xor()|. @@ -95,6 +103,8 @@ api_info() *api_info()* (`table`) append({lnum}, {text}) *append()* + Lua: Prefer |nvim_buf_set_lines()|. + When {text} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. Otherwise append {text} as one text line below line {lnum} in @@ -117,6 +127,8 @@ append({lnum}, {text}) *append()* (`0|1`) appendbufline({buf}, {lnum}, {text}) *appendbufline()* + Lua: Prefer |nvim_buf_set_lines()|. + Like |append()| but append the text in buffer {buf}. This function works only for loaded buffers. First call @@ -214,6 +226,8 @@ argv([{nr} [, {winid}]]) *argv()* (`string|string[]`) asin({expr}) *asin()* + Lua: Prefer |math.asin()|. + Return the arc sine of {expr} measured in radians, as a |Float| in the range of [-pi/2, pi/2]. {expr} must evaluate to a |Float| or a |Number| in the range @@ -245,6 +259,8 @@ assert_beeps({cmd}) *assert_beeps()* (`0|1`) assert_equal({expected}, {actual} [, {msg}]) *assert_equal()* + Lua: Prefer |assert()| with |vim.deep_equal()|. + When {expected} and {actual} are not equal an error message is added to |v:errors| and 1 is returned. Otherwise zero is returned. |assert-return| @@ -351,6 +367,8 @@ assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) (`0|1`) assert_false({actual} [, {msg}]) *assert_false()* + Lua: Prefer |assert()|. + When {actual} is not false an error message is added to |v:errors|, like with |assert_equal()|. The error is in the form "Expected False but got {actual}". @@ -369,6 +387,8 @@ assert_false({actual} [, {msg}]) *assert_false()* (`0|1`) assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* + Lua: Prefer |assert()|. + This asserts number and |Float| values. When {actual} is lower than {lower} or higher than {upper} an error message is added to |v:errors|. Also see |assert-return|. @@ -462,6 +482,8 @@ assert_report({msg}) *assert_report()* (`0|1`) assert_true({actual} [, {msg}]) *assert_true()* + Lua: Prefer |assert()|. + When {actual} is not true an error message is added to |v:errors|, like with |assert_equal()|. Also see |assert-return|. @@ -478,6 +500,8 @@ assert_true({actual} [, {msg}]) *assert_true()* (`0|1`) atan({expr}) *atan()* + Lua: Prefer |math.atan()|. + Return the principal value of the arc tangent of {expr}, in the range [-pi/2, +pi/2] radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. @@ -495,6 +519,8 @@ atan({expr}) *atan()* (`number`) atan2({expr1}, {expr2}) *atan2()* + Lua: Prefer |math.atan2()|. + Return the arc tangent of {expr1} / {expr2}, measured in radians, as a |Float| in the range [-pi, pi]. {expr1} and {expr2} must evaluate to a |Float| or a |Number|. @@ -587,6 +613,9 @@ bufadd({name}) *bufadd()* (`integer`) bufexists({buf}) *bufexists()* + Lua: Prefer |nvim_buf_is_valid()| after resolving {buf} to a + bufnr. + Checks whether a buffer with the name or number {buf} exists. Returns |TRUE| if the buffer exists, |FALSE| otherwise. If the {buf} argument is a number, buffer numbers are used. @@ -615,6 +644,9 @@ bufexists({buf}) *bufexists()* (`0|1`) buflisted({buf}) *buflisted()* + Lua: Prefer |vim.bo| or |nvim_get_option_value()| after + resolving {buf} to a bufnr. + Checks whether a buffer called {buf} exists and is listed (has the 'buflisted' option set). Returns |TRUE| if so, |FALSE| otherwise. @@ -640,6 +672,9 @@ bufload({buf}) *bufload()* • {buf} (`any`) bufloaded({buf}) *bufloaded()* + Lua: Prefer |nvim_buf_is_loaded()| after resolving {buf} to a + bufnr. + Checks whether a buffer called {buf} exists and is loaded (shown in a window or hidden). Returns |TRUE| if so, |FALSE| otherwise. @@ -652,6 +687,9 @@ bufloaded({buf}) *bufloaded()* (`0|1`) bufname([{buf}]) *bufname()* + Lua: Prefer |nvim_buf_get_name()| after resolving {buf} to a + bufnr. + The result is the name of a buffer. Mostly as it is displayed by the `:ls` command, but not using special names such as "[No Name]". @@ -689,6 +727,10 @@ bufname([{buf}]) *bufname()* (`string`) bufnr([{buf} [, {create}]]) *bufnr()* + Lua: Prefer |nvim_get_current_buf()| when omitted, or + |nvim_create_buf()| with |nvim_buf_set_name()| for creating; + name lookup, "$", "%", "#", and {create} semantics differ. + The result is the number of a buffer, as it is displayed by the `:ls` command. For the use of {buf}, see |bufname()| above. @@ -714,6 +756,10 @@ bufnr([{buf} [, {create}]]) *bufnr()* (`integer`) bufwinid({buf}) *bufwinid()* + Lua: Prefer |nvim_tabpage_list_wins()| with + |nvim_win_get_buf()| after resolving {buf}; only the current + tabpage is checked and no-match semantics differ. + Returns the |window-ID| of the first window associated with buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} doesn't exist or there is no such window, -1 @@ -731,6 +777,11 @@ bufwinid({buf}) *bufwinid()* (`integer`) bufwinnr({buf}) *bufwinnr()* + Lua: Prefer |nvim_tabpage_list_wins()| with + |nvim_win_get_buf()| and |nvim_win_get_number()| after + resolving {buf}; only the current tabpage is checked and + no-match semantics differ. + Like |bufwinid()| but return the window number instead of the |window-ID|. If buffer {buf} doesn't exist or there is no such window, -1 @@ -764,6 +815,10 @@ byte2line({byte}) *byte2line()* (`integer`) byteidx({expr}, {nr} [, {utf16}]) *byteidx()* + Lua: Prefer |vim.str_byteindex()| for string input with + `"utf-32"` or `"utf-16"` and `strict_indexing = false`; + composing characters and out-of-range semantics differ. + Return byte index of the {nr}th character in the String {expr}. Use zero for the first character, it then returns zero. @@ -808,6 +863,9 @@ byteidx({expr}, {nr} [, {utf16}]) *byteidx()* (`integer`) byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* + Lua: Prefer |vim.str_byteindex()| with `"utf-32"` or + `"utf-16"` and `strict_indexing = false`. + Like |byteidx()|, except that a composing character is counted as a separate character. Example: >vim let s = 'e' .. nr2char(0x301) @@ -844,6 +902,8 @@ call({func}, {arglist} [, {dict}]) *call()* *E69 (`any`) ceil({expr}) *ceil()* + Lua: Prefer |math.ceil()|. + Return the smallest integral value greater than or equal to {expr} as a |Float| (round up). {expr} must evaluate to a |Float| or a |Number|. @@ -893,6 +953,9 @@ changenr() *changenr()* (`integer`) chansend({id}, {data}) *chansend()* + Lua: Prefer |nvim_chan_send()| for string data; list input and + the return value differ. + Send data to channel {id}. For a job, it writes it to the stdin of the process. For the stdio channel |channel-stdio|, it writes to Nvim's stdout. Returns the number of bytes @@ -918,6 +981,8 @@ chansend({id}, {data}) *chansend()* (`0|1`) char2nr({string} [, {utf8}]) *char2nr()* + Lua: Prefer |string.byte()|: only works with ASCII. + Return Number value of the first char in {string}. Examples: >vim echo char2nr(" ") " returns 32 @@ -957,6 +1022,11 @@ charclass({string}) *charclass()* (`0|1|2|3|'other'`) charcol({expr} [, {winid}]) *charcol()* + Lua: Prefer |nvim_win_get_cursor()| with |vim.str_utfindex()| + for ".", or |nvim_get_current_line()| with + |vim.str_utfindex()| for "$"; marks, list input, and window + semantics differ. + Same as |col()| but returns the character index of the column position given with {expr} instead of the byte position. @@ -974,6 +1044,10 @@ charcol({expr} [, {winid}]) *charcol()* (`integer`) charidx({string}, {idx} [, {countcc} [, {utf16}]]) *charidx()* + Lua: Prefer |vim.str_utfindex()| for string input with + `"utf-32"` or `"utf-16"` and `strict_indexing = false`; + `countcc = false` and out-of-range semantics differ. + Return the character index of the byte at {idx} in {string}. The index of the first character is zero. If there are no multibyte characters the returned value is @@ -1017,6 +1091,9 @@ charidx({string}, {idx} [, {countcc} [, {utf16}]]) *charidx()* (`integer`) chdir({dir} [, {scope}]) *chdir()* + Lua: Prefer |nvim_set_current_dir()| for the global directory; + tab-local, window-local, and return semantics differ. + Changes the current working directory to {dir}. The scope of the change is determined as follows: If {scope} is not present, the current working directory is @@ -1101,6 +1178,10 @@ cmdcomplete_info() *cmdcomplete_info()* (`table`) col({expr} [, {winid}]) *col()* + Lua: Prefer |nvim_win_get_cursor()| for "." (add 1), or Lua + `#` on |nvim_get_current_line()| for "$"; marks, list input, + and `virtualedit` differ. + Returns the byte index of the column position given with {expr}. For accepted positions see |getpos()|. @@ -1349,6 +1430,8 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) *confirm()* (`integer`) copy({expr}) *copy()* + Lua: Prefer |vim.deepcopy()|; deeper than Vimscript |copy()|. + Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a shallow copy is created. This means @@ -1365,6 +1448,8 @@ copy({expr}) *copy()* (`T`) cos({expr}) *cos()* + Lua: Prefer |math.cos()|. + Return the cosine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -1381,6 +1466,8 @@ cos({expr}) *cos()* (`number`) cosh({expr}) *cosh()* + Lua: Prefer |math.cosh()|. + Return the hyperbolic cosine of {expr} as a |Float| in the range [1, inf]. {expr} must evaluate to a |Float| or a |Number|. @@ -1471,6 +1558,9 @@ ctxsize() *ctxsize()* cursor({lnum}, {col} [, {off}]) *cursor()* cursor({list}) + Lua: Prefer |nvim_win_set_cursor()| with `{lnum, col - 1}`; + `off`, `curswant`, and failure semantics differ. + Positions the cursor at the column (byte count) {col} in the line {lnum}. The first column is one. @@ -1509,6 +1599,9 @@ cursor({list}) (`any`) debugbreak({pid}) *debugbreak()* + Lua: Prefer |uv.kill()| with `"sigtrap"` (or `"sigint"` + outside MS-Windows); exact semantics differ. + Specifically used to interrupt a program being debugged. It will cause process {pid} to get a SIGTRAP. Behavior for other processes is undefined. See |terminal-debug|. @@ -1524,6 +1617,8 @@ debugbreak({pid}) *debugbreak()* (`any`) deepcopy({expr} [, {noref}]) *deepcopy()* *E698* + Lua: Prefer |vim.deepcopy()|. + Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a full copy is created. This means @@ -1551,7 +1646,7 @@ deepcopy({expr} [, {noref}]) *deepcopy()* *E69 (`T`) delete({fname} [, {flags}]) *delete()* - Lua: see |vim.fs.rm()|. + Lua: Prefer |vim.fs.rm()|. Without {flags} or with {flags} empty: Deletes the file by the name {fname}. @@ -1579,6 +1674,8 @@ delete({fname} [, {flags}]) *delete()* (`integer`) deletebufline({buf}, {first} [, {last}]) *deletebufline()* + Lua: Prefer |nvim_buf_set_lines()|. + Delete lines {first} to {last} (inclusive) from buffer {buf}. If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. @@ -1800,6 +1897,9 @@ digraph_setlist({digraphlist}) *digraph_setlist()* (`any`) empty({expr}) *empty()* + Lua: Prefer plain Lua emptiness checks, or |vim.tbl_isempty()| + for tables. + Return the Number 1 if {expr} is empty, zero otherwise. - A |List| or |Dictionary| is empty when it does not have any items. @@ -1815,6 +1915,9 @@ empty({expr}) *empty()* (`integer`) environ() *environ()* + Lua: Prefer |uv.os_environ()| for the full environment table; + |vim.env| for keyed access. + Return all of environment variables as dictionary. You can check if an environment variable exists like this: >vim echo has_key(environ(), 'HOME') @@ -1904,6 +2007,8 @@ executable({expr}) *executable()* (`0|1`) execute({command} [, {silent}]) *execute()* + Lua: Prefer |nvim_exec()| or |vim.cmd()|. + Execute {command} and capture its output. If {command} is a |String|, returns {command} output. If {command} is a |List|, returns concatenated outputs. @@ -2046,6 +2151,8 @@ exists({expr}) *exists()* (`0|1`) exp({expr}) *exp()* + Lua: Prefer |math.exp()|. + Return the exponential of {expr} as a |Float| in the range [0, inf]. {expr} must evaluate to a |Float| or a |Number|. @@ -2197,6 +2304,10 @@ expandcmd({string} [, {options}]) *expandcmd()* (`any`) extend({expr1}, {expr2} [, {expr3}]) *extend()* + Lua: Prefer |vim.list_extend()| for lists, or + |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; + insertion and keep/force/error behavior differ. + {expr1} and {expr2} must be both |Lists| or both |Dictionaries|. @@ -2242,6 +2353,10 @@ extend({expr1}, {expr2} [, {expr3}]) *extend()* (`any`) extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* + Lua: Prefer |vim.list_extend()| on a copy for lists, or + |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; + insertion and keep/force/error behavior differ. + Like |extend()| but instead of adding items to {expr1} a new List or Dictionary is created and returned. {expr1} remains unchanged. @@ -2255,6 +2370,8 @@ extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* (`any`) feedkeys({string} [, {mode}]) *feedkeys()* + Lua: Prefer |nvim_feedkeys()|. + Characters in {string} are queued for processing as if they come from a mapping or were typed by the user. @@ -2308,6 +2425,9 @@ feedkeys({string} [, {mode}]) *feedkeys()* (`any`) filecopy({from}, {to}) *filecopy()* + Lua: Prefer |uv.fs_copyfile()| with `{ excl = true }`; return + semantics differ. + Copy the file pointed to by the name {from} to {to}. The result is a Number, which is |TRUE| if the file was copied successfully, and |FALSE| when it failed. @@ -2324,6 +2444,9 @@ filecopy({from}, {to}) *filecopy()* (`0|1`) filereadable({file}) *filereadable()* + Lua: Prefer |uv.fs_access()| with `"R"` and |uv.fs_stat()| to + exclude directories. + Returns |TRUE| if {file} exists, can be read, and is not a directory, else |FALSE|. @@ -2347,6 +2470,9 @@ filereadable({file}) *filereadable()* (`0|1`) filewritable({file}) *filewritable()* + Lua: Prefer |uv.fs_access()| with `"W"` and |uv.fs_stat()| if + you need Vim's `2` return for directories. + Checks whether a file with the name {file} exists and can be written. Returns 1 if so. If {file} doesn't exist, or is not writable, the result is 0. If {file} is a @@ -2359,6 +2485,9 @@ filewritable({file}) *filewritable()* (`0|1`) filter({expr1}, {expr2}) *filter()* + Lua: Prefer |vim.tbl_filter()| for lists; dicts, strings, and + blobs differ. + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. For each item in {expr1} evaluate {expr2} and when the result is zero or false remove the item from the |List| or @@ -2419,6 +2548,9 @@ filter({expr1}, {expr2}) *filter()* (`any`) finddir({name} [, {path} [, {count}]]) *finddir()* + Lua: Prefer |vim.fs.find()| with `type = 'directory'`; `path`, + `count`, and return semantics differ. + Find directory {name} in {path}. Supports both downwards and upwards recursive directory searches. See |file-searching| for the syntax of {path}. @@ -2445,6 +2577,9 @@ finddir({name} [, {path} [, {count}]]) *finddir()* (`string|string[]`) findfile({name} [, {path} [, {count}]]) *findfile()* + Lua: Prefer |vim.fs.find()|; `path`, `count`, return + semantics, and |'suffixesadd'| handling differ. + Just like |finddir()|, but find a file instead of a directory. Uses 'suffixesadd'. Example: >vim @@ -2461,6 +2596,9 @@ findfile({name} [, {path} [, {count}]]) *findfile()* (`string|string[]`) flatten({list} [, {maxdepth}]) *flatten()* + Lua: Prefer `vim.iter(list):flatten():totable()` for a new + flattened list; in-place updates and `maxdepth` differ. + Flatten {list} up to {maxdepth} levels. Without {maxdepth} the result is a |List| without nesting, as if {maxdepth} is a very large number. @@ -2487,6 +2625,9 @@ flatten({list} [, {maxdepth}]) *flatten()* (`any[]|0`) flattennew({list} [, {maxdepth}]) *flattennew()* + Lua: Prefer `vim.iter(list):flatten():totable()` for a new + flattened list; `maxdepth` differs. + Like |flatten()| but first make a copy of {list}. Parameters: ~ @@ -2497,6 +2638,8 @@ flattennew({list} [, {maxdepth}]) *flattennew()* (`any[]|0`) float2nr({expr}) *float2nr()* + Lua: Prefer |math.modf()| (first return value). + Convert {expr} to a Number by omitting the part after the decimal point. {expr} must evaluate to a |Float| or a |Number|. @@ -2525,6 +2668,8 @@ float2nr({expr}) *float2nr()* (`any`) floor({expr}) *floor()* + Lua: Prefer |math.floor()|. + Return the largest integral value less than or equal to {expr} as a |Float| (round down). {expr} must evaluate to a |Float| or a |Number|. @@ -2544,6 +2689,8 @@ floor({expr}) *floor()* (`any`) fmod({expr1}, {expr2}) *fmod()* + Lua: Prefer |math.fmod()|. + Return the remainder of {expr1} / {expr2}, even if the division is not representable. Returns {expr1} - i * {expr2} for some integer i such that if {expr2} is non-zero, the @@ -2567,6 +2714,9 @@ fmod({expr1}, {expr2}) *fmod()* (`any`) fnameescape({string}) *fnameescape()* + Lua: Prefer |nvim_cmd()| or |vim.cmd()| with structured + arguments to avoid Ex filename escaping. + Escape {string} for use as file name command argument. All characters that have a special meaning, such as `'%'` and `'|'` are escaped with a backslash. For most systems the characters @@ -2591,6 +2741,10 @@ fnameescape({string}) *fnameescape()* (`string`) fnamemodify({fname}, {mods}) *fnamemodify()* + Lua: Prefer |vim.fs.dirname()|, |vim.fs.basename()|, + |vim.fs.abspath()|, and |vim.fs.normalize()| for common path + modifiers; modifier coverage differs. + Modify file name {fname} according to {mods}. {mods} is a string of characters like it is used for file names on the command line. See |filename-modifiers|. @@ -2695,6 +2849,8 @@ foldtextresult({lnum}) *foldtextresult()* (`string`) foreach({expr1}, {expr2}) *foreach()* + Lua: Prefer |pairs()| or |ipairs()|. + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. For each item in {expr1} execute {expr2}. {expr1} is not modified; its values may be, as with |:lockvar| 1. |E741| @@ -3037,6 +3193,8 @@ getbufinfo([{dict}]) (`vim.fn.getbufinfo.ret.item[]`) getbufline({buf}, {lnum} [, {end}]) *getbufline()* + Lua: Prefer |nvim_buf_get_lines()|. + Return a |List| with the lines starting from {lnum} to {end} (inclusive) in the buffer {buf}. If {end} is omitted, a |List| with only the line {lnum} is returned. See @@ -3071,6 +3229,8 @@ getbufline({buf}, {lnum} [, {end}]) *getbufline()* (`string[]`) getbufoneline({buf}, {lnum}) *getbufoneline()* + Lua: Prefer |nvim_buf_get_lines()|. + Just like `getbufline()` but only get one line and return it as a string. @@ -3082,6 +3242,10 @@ getbufoneline({buf}, {lnum}) *getbufoneline()* (`string`) getbufvar({buf}, {varname} [, {def}]) *getbufvar()* + Lua: Prefer |nvim_buf_get_var()| or |vim.b| after resolving + {buf} to a bufnr; option names use |nvim_get_option_value()| + or |vim.bo|. + The result is the value of option or local buffer variable {varname} in buffer {buf}. Note that the name without "b:" must be used. @@ -3512,6 +3676,9 @@ getcompletiontype({pat}) *getcompletiontype()* (`string`) getcurpos([{winid}]) *getcurpos()* + Lua: Prefer |nvim_win_get_cursor()|; return shape, 0-based + column, and `curswant`/invalid-window semantics differ. + Get the position of the cursor. This is like getpos('.'), but includes an extra "curswant" item in the list: [0, lnum, col, off, curswant] ~ @@ -3559,6 +3726,9 @@ getcursorcharpos([{winid}]) *getcursorcharpos()* (`any`) getcwd([{winnr} [, {tabnr}]]) *getcwd()* + Lua: Prefer |uv.cwd()| for the global working directory; + tab-local and window-local scopes differ. + With no arguments, returns the name of the effective |current-directory|. With {winnr} or {tabnr} the working directory of that scope is returned, and 'autochdir' is @@ -3585,6 +3755,8 @@ getcwd([{winnr} [, {tabnr}]]) *getcwd()* (`string`) getenv({name}) *getenv()* + Lua: Prefer |vim.env|. + Return the value of environment variable {name}. The {name} argument is a string, without a leading '$'. Example: >vim myHome = getenv('HOME') @@ -3618,6 +3790,8 @@ getfontname([{name}]) *getfontname()* (`string`) getfperm({fname}) *getfperm()* + Lua: Prefer |uv.fs_stat()|. + Returns the file permissions of the given file {fname} as a String. If {fname} does not exist or its directory cannot be read, an empty string is returned. @@ -3640,6 +3814,8 @@ getfperm({fname}) *getfperm()* (`string`) getfsize({fname}) *getfsize()* + Lua: Prefer |uv.fs_stat()|. + Returns the size in bytes of the given file {fname}. If {fname} is a directory, 0 is returned. If the file {fname} can't be found, -1 is returned. @@ -3653,6 +3829,8 @@ getfsize({fname}) *getfsize()* (`integer`) getftime({fname}) *getftime()* + Lua: Prefer |uv.fs_stat()|. + Returns the last modification time ("mtime") of file {fname}. The value is measured as seconds since 1st Jan 1970, and may be passed to |strftime()|. See also @@ -3666,6 +3844,8 @@ getftime({fname}) *getftime()* (`integer`) getftype({fname}) *getftype()* + Lua: Prefer |uv.fs_stat()|. + Returns a description of the type of file {fname} as a String. If {fname} does not exist an empty string is returned. @@ -3692,6 +3872,9 @@ getftype({fname}) *getftype()* (`'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other'`) getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* + Lua: Prefer |nvim_get_context()| for current jump history; + window/tab arguments and return shape differ. + Returns the |jumplist| for the specified window. Without arguments use the current window. @@ -3719,6 +3902,9 @@ getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* (`vim.fn.getjumplist.ret`) getline({lnum} [, {end}]) *getline()* + Lua: Prefer |nvim_get_current_line()| or + |nvim_buf_get_lines()|. + Without {end} the result is a String, which is line {lnum} from the current buffer. Example: >vim getline(1) @@ -3887,6 +4073,8 @@ getmousepos() *getmousepos()* (`vim.fn.getmousepos.ret`) getpid() *getpid()* + Lua: Prefer |uv.os_getpid()|. + Return a Number which is the process ID of the Vim process. This is a unique number, until Vim exits. @@ -3894,6 +4082,10 @@ getpid() *getpid()* (`integer`) getpos({expr}) *getpos()* + Lua: Prefer |nvim_win_get_cursor()| for "." or + |nvim_buf_get_mark()| for marks; return shape, `off`, and + special-position semantics differ. + Gets a position, where {expr} is one of: . Cursor position. $ Last line in the current buffer. @@ -4303,6 +4495,8 @@ getscriptinfo([{opts}]) *getscriptinfo()* (`vim.fn.getscriptinfo.ret[]`) getstacktrace() *getstacktrace()* + Lua: Prefer |debug.traceback()|. + Returns the current stack trace of Vim scripts. Stack trace is a |List|, of which each item is a |Dictionary| with the following items: @@ -4337,6 +4531,8 @@ gettabinfo([{tabnr}]) *gettabinfo()* (`any`) gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* + Lua: Prefer |nvim_tabpage_get_var()| or |vim.t|. + Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| Tabs are numbered starting with one. @@ -4355,6 +4551,10 @@ gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* (`any`) gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* + Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving + {tabnr} and {winnr} to a winid; option names use + |nvim_get_option_value()| or |vim.wo|. + Get the value of window-local variable {varname} in window {winnr} in tab page {tabnr}. The {varname} argument is a string. When {varname} is empty a @@ -4529,6 +4729,10 @@ getwinposy() *getwinposy()* (`integer`) getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* + Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving + {winnr}; option names use |nvim_get_option_value()| or + |vim.wo|. + Like |gettabwinvar()| for the current tabpage. Examples: >vim let list_is_on = getwinvar(2, '&list') @@ -4733,6 +4937,8 @@ has({feature}) *has()* (`0|1`) has_key({dict}, {key}) *has_key()* + Lua: Prefer `dict[key] ~= nil`. + Checks whether |Dictionary| {dict} has an entry with key {key}. Returns TRUE if so, FALSE otherwise. The {key} argument is a string. @@ -4914,6 +5120,8 @@ histnr({history}) *histnr()* (`integer`) hlID({name}) *hlID()* + Lua: Prefer |nvim_get_hl()|. + Returns the numeric ID of the highlight group with name {name}. When the highlight group doesn't exist, zero is returned. @@ -4930,6 +5138,8 @@ hlID({name}) *hlID()* (`integer`) hlexists({name}) *hlexists()* + Lua: Prefer |nvim_get_hl()|. + Checks whether a highlight group called {name} exists. Returns TRUE if the group has been defined in some way. Not necessarily when highlighting has been defined for it, it may @@ -4942,6 +5152,8 @@ hlexists({name}) *hlexists()* (`0|1`) hostname() *hostname()* + Lua: Prefer |uv.os_gethostname()|. + Returns the hostname of the machine on which the Nvim server (not the UI client) is currently running. @@ -4949,6 +5161,8 @@ hostname() *hostname()* (`string`) iconv({string}, {from}, {to}) *iconv()* + Lua: Prefer |vim.iconv()|. + Converts the encoding of {string} from {from} to {to}. Returns the converted String. When the conversion completely fails an empty string is @@ -5007,6 +5221,10 @@ indent({lnum}) *indent()* (`integer`) index({object}, {expr} [, {start} [, {ic}]]) *index()* + Lua: Prefer |vim.iter()| with |Iter:enumerate()| and + |Iter:find()| for lists; result is 1-based, and `start`, `ic`, + and Blob semantics differ. + Find {expr} in {object} and return its index. See |indexof()| for using a lambda to select the item. @@ -5044,6 +5262,10 @@ index({object}, {expr} [, {start} [, {ic}]]) *index()* (`integer`) indexof({object}, {expr} [, {opts}]) *indexof()* + Lua: Prefer |vim.iter()| with |Iter:enumerate()| and + |Iter:find()| for list predicates; result is 1-based, and + `startidx` and Blob semantics differ. + Returns the index of an item in {object} where {expr} is v:true. {object} must be a |List| or a |Blob|. @@ -5091,6 +5313,8 @@ indexof({object}, {expr} [, {opts}]) *indexof()* (`integer`) input({prompt} [, {text} [, {completion}]]) *input()* + Lua: Prefer |vim.ui.input()| for callback-based input. + Parameters: ~ • {prompt} (`string`) @@ -5101,6 +5325,8 @@ input({prompt} [, {text} [, {completion}]]) *input()* (`string`) input({opts}) + Lua: Prefer |vim.ui.input()| for callback-based input. + Prompts the user to enter text on the command-line, and returns the text as a String. The {prompt} argument is either a prompt string, or a blank string (for no prompt). A '\n' @@ -5218,6 +5444,9 @@ input({opts}) (`string`) inputlist({textlist}) *inputlist()* + Lua: Prefer |vim.ui.select()| for simple selection menus; + callback, returned item, and out-of-range semantics differ. + Displays a list of strings and prompts the user to select one by entering a number. {textlist} must be a |List| of strings. Returns the number the user entered. @@ -5281,6 +5510,9 @@ inputsecret({prompt} [, {text}]) *inputsecret()* (`string`) insert({object}, {item} [, {idx}]) *insert()* + Lua: Prefer |table.insert()| for lists; blob insertion and + negative indexes differ. + When {object} is a |List| or a |Blob| insert {item} at the start of it. @@ -5323,6 +5555,8 @@ interrupt() *interrupt()* (`any`) invert({expr}) *invert()* + Lua: Prefer |bit.bnot()|. + Bitwise invert. The argument is converted to a number. A List, Dict or Float argument causes an error. Example: >vim let bits = invert(bits) @@ -5357,6 +5591,8 @@ isabsolutepath({path}) *isabsolutepath()* (`0|1`) isdirectory({directory}) *isdirectory()* + Lua: Prefer |uv.fs_stat()| and check `type == "directory"`. + Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't exist or isn't a directory. {directory} is any expression, which is used as a String. @@ -5368,6 +5604,9 @@ isdirectory({directory}) *isdirectory()* (`0|1`) isinf({expr}) *isinf()* + Lua: Prefer + `expr == math.huge and 1 or expr == -math.huge and -1 or 0`. + Return 1 if {expr} is a positive infinity, or -1 a negative infinity, otherwise 0. >vim echo isinf(1.0 / 0.0) @@ -5402,6 +5641,8 @@ islocked({expr}) *islocked()* *E78 (`0|1`) isnan({expr}) *isnan()* + Lua: Prefer `expr ~= expr`. + Return |TRUE| if {expr} is a float with value NaN. >vim echo isnan(0.0 / 0.0) < 1 @@ -5413,6 +5654,8 @@ isnan({expr}) *isnan()* (`0|1`) items({expr}) *items()* + Lua: Prefer |pairs()| or |ipairs()|. + Return a |List| with all key/index and value pairs of {expr}. Each |List| item is a list with two items: - for a |Dict|: the key and the value @@ -5439,6 +5682,9 @@ items({expr}) *items()* (`any`) jobpid({job}) *jobpid()* + Lua: Prefer |vim.system()| object `.pid`; |job-id| and channel + semantics differ. + Return the PID (process id) of |job-id| {job}. Parameters: ~ @@ -5461,7 +5707,9 @@ jobresize({job}, {width}, {height}) *jobresize()* (`any`) jobstart({cmd} [, {opts}]) *jobstart()* - Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`). + Lua: Prefer |vim.system()| for simple processes; |RPC|, + PTY/term, streaming callbacks, and shell-string behavior + differ. Spawns {cmd} as a job. If {cmd} is a List it runs directly (no 'shell'). @@ -5561,6 +5809,9 @@ jobstart({cmd} [, {opts}]) *jobstart()* (`integer`) jobstop({id}) *jobstop()* + Lua: Prefer |SystemObj:kill()| on a |vim.system()| object; + |job-id| semantics differ. + Stop |job-id| {id} by sending SIGTERM to the job process. If the process does not terminate after a timeout then SIGKILL will be sent. When the job terminates its |on_exit| handler @@ -5577,6 +5828,9 @@ jobstop({id}) *jobstop()* (`integer`) jobwait({jobs} [, {timeout}]) *jobwait()* + Lua: Prefer |SystemObj:wait()| on a |vim.system()| object; + list input and status values differ. + Waits for jobs and their |on_exit| handlers to complete. {jobs} is a List of |job-id|s to wait for. @@ -5605,6 +5859,9 @@ jobwait({jobs} [, {timeout}]) *jobwait()* (`integer[]`) join({list} [, {sep}]) *join()* + Lua: Prefer |table.concat()| for string lists; non-string + values stringify differently. + Join the items in {list} together into one String. When {sep} is specified it is put in between the items. If {sep} is omitted a single space is used. @@ -5623,6 +5880,8 @@ join({list} [, {sep}]) *join()* (`string`) json_decode({expr}) *json_decode()* + Lua: Prefer |vim.json.decode()|. + Convert {expr} from JSON object. Accepts |readfile()|-style list as the input, as well as regular string. May output any Vim value. In the following cases it will output @@ -5644,6 +5903,8 @@ json_decode({expr}) *json_decode()* (`any`) json_encode({expr}) *json_encode()* + Lua: Prefer |vim.json.encode()|. + Convert {expr} into a JSON string. Accepts |msgpack-special-dict| as the input. Will not convert |Funcref|s, mappings with non-string keys (can be created as @@ -5662,6 +5923,8 @@ json_encode({expr}) *json_encode()* (`string`) keys({dict}) *keys()* + Lua: Prefer |vim.tbl_keys()|. + Return a |List| with all the keys of {dict}. The |List| is in arbitrary order. Also see |items()| and |values()|. @@ -5685,6 +5948,9 @@ keytrans({string}) *keytrans()* (`string`) len({expr}) *len()* *E701* + Lua: Prefer Lua `#` operator for strings and lists or + `#vim.tbl_keys(expr)` for dicts. + Returns the length of the argument. When {expr} is a String or a Number the length in bytes is used, as with |strlen()|. @@ -5702,6 +5968,8 @@ len({expr}) *len()* *E70 (`integer`) libcall({libname}, {funcname}, {argument}) *libcall()* *E364* *E368* + Lua: Prefer |package.loadlib()| or `ffi.load()`. + Call function {funcname} in the run-time library {libname} with single argument {argument}. This is useful to call functions in a library that you @@ -5753,6 +6021,8 @@ libcall({libname}, {funcname}, {argument}) *libcall()* *E364* *E (`any`) libcallnr({libname}, {funcname}, {argument}) *libcallnr()* + Lua: Prefer |package.loadlib()| or `ffi.load()`. + Just like |libcall()|, but used for a function that returns an int instead of a string. Examples: >vim @@ -5770,6 +6040,10 @@ libcallnr({libname}, {funcname}, {argument}) *libcallnr()* (`any`) line({expr} [, {winid}]) *line()* + Lua: Prefer |nvim_win_get_cursor()| for "." or + |nvim_buf_line_count()| for "$"; marks, lists, and other + position expressions differ. + See |getpos()| for accepted positions. To get the column number use |col()|. To get both use @@ -5797,6 +6071,9 @@ line({expr} [, {winid}]) *line()* (`integer`) line2byte({lnum}) *line2byte()* + Lua: Prefer |nvim_buf_get_offset()| with `lnum - 1`; + 'fileformat' and invalid-line semantics differ. + Return the byte count from the start of the buffer for line {lnum}. This includes the end-of-line character, depending on the 'fileformat' option for the current buffer. The first @@ -5868,6 +6145,8 @@ list2str({list} [, {utf8}]) *list2str()* (`string`) localtime() *localtime()* + Lua: Prefer |os.time()|. + Return the current time, measured as seconds since 1st Jan 1970. See also |strftime()|, |strptime()| and |getftime()|. @@ -5875,6 +6154,8 @@ localtime() *localtime()* (`integer`) log({expr}) *log()* + Lua: Prefer |math.log()|. + Return the natural logarithm (base e) of {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number| in the range (0, inf]. @@ -5892,6 +6173,8 @@ log({expr}) *log()* (`number`) log10({expr}) *log10()* + Lua: Prefer |math.log10()|. + Return the logarithm of Float {expr} to base 10 as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -5908,6 +6191,8 @@ log10({expr}) *log10()* (`number`) luaeval({expr} [, {expr}]) *luaeval()* + Lua: Prefer plain Lua expressions and values directly. + Evaluate Lua expression {expr} and return its result converted to Vim data structures. See |lua-eval| for details. @@ -5921,6 +6206,9 @@ luaeval({expr} [, {expr}]) *luaeval()* (`any`) map({expr1}, {expr2}) *map()* + Lua: Prefer |vim.tbl_map()| for array-like tables; dict, + string, blob, and in-place behavior differ. + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. When {expr1} is a |List| or |Dictionary|, replace each item in {expr1} with the result of evaluating {expr2}. @@ -6143,6 +6431,9 @@ maplist([{abbr}]) *maplist()* (`table[]`) mapnew({expr1}, {expr2}) *mapnew()* + Lua: Prefer |vim.tbl_map()| for tables; string, blob, and + `v:key` callback behavior differ. + Like |map()| but instead of replacing items in {expr1} a new List or Dictionary is created and returned. {expr1} remains unchanged. Items can still be changed by {expr2}, if you @@ -6716,6 +7007,9 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* (`table`) max({expr}) *max()* + Lua: Prefer |math.max()| with `unpack(expr)` for lists; dict + values and empty inputs need custom handling. + Return the maximum value of all items in {expr}. Example: >vim echo max([apples, pears, oranges]) @@ -6863,6 +7157,9 @@ menu_info({name} [, {mode}]) *menu_info()* (`any`) min({expr}) *min()* + Lua: Prefer |math.min()| with `unpack(expr)` for lists; dict + values and empty inputs need custom handling. + Return the minimum value of all items in {expr}. Example: >vim echo min([apples, pears, oranges]) @@ -6879,6 +7176,9 @@ min({expr}) *min()* (`number`) mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739* + Lua: Prefer |uv.fs_mkdir()| for simple directory creation; + `"p"`, `"D"`, `"R"`, and return semantics differ. + Create directory {name}. When {flags} is present it must be a string. An empty string @@ -6926,6 +7226,10 @@ mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E73 (`integer`) mode([{expr}]) *mode()* + Lua: Prefer |nvim_get_mode()|; use the `.mode` field. It + always returns the full mode string, unlike |mode()| without a + non-zero {expr}. + Return a string that indicates the current mode. If {expr} is supplied and it evaluates to a non-zero Number or a non-empty String (|non-zero-arg|), then the full mode is @@ -6986,6 +7290,9 @@ mode([{expr}]) *mode()* (`any`) msgpackdump({list} [, {type}]) *msgpackdump()* + Lua: Prefer |vim.mpack.encode()|; list wrapping, return shape, + and special-dict semantics differ. + Convert a list of Vimscript objects to msgpack. Returned value is a |readfile()|-style list. When {type} contains "B", a |Blob| is returned instead. Example: >vim @@ -7012,6 +7319,9 @@ msgpackdump({list} [, {type}]) *msgpackdump()* (`any`) msgpackparse({data}) *msgpackparse()* + Lua: Prefer |vim.mpack.decode()|; input and special-dict + semantics differ. + Convert a |readfile()|-style list or a |Blob| to a list of Vimscript objects. Example: >vim @@ -7101,6 +7411,8 @@ nextnonblank({lnum}) *nextnonblank()* (`integer`) nr2char({expr} [, {utf8}]) *nr2char()* + Lua: Prefer |string.char()|: only works with ASCII. + Return a string with a single character, which has the number value {expr}. Examples: >vim echo nr2char(64) " returns '@' @@ -7123,6 +7435,8 @@ nr2char({expr} [, {utf8}]) *nr2char()* (`string`) nvim_...({...}) *nvim_...()* *E5555* *eval-api* + Lua: Prefer |vim.api|. + Call nvim |api| functions. The type checking of arguments will be stricter than for most other builtins. For instance, if Integer is expected, a |Number| must be passed in, a @@ -7140,6 +7454,8 @@ nvim_...({...}) *nvim_...()* *E5555* *eval- (`any`) or({expr}, {expr}) *or()* + Lua: Prefer |bit.bor()|. + Bitwise OR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see `and()` and `xor()`. @@ -7201,6 +7517,8 @@ perleval({expr}) *perleval()* (`any`) pow({x}, {y}) *pow()* + Lua: Prefer |math.pow()|. + Return the power of {x} to the exponent {y} as a |Float|. {x} and {y} must evaluate to a |Float| or a |Number|. Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. @@ -7244,6 +7562,8 @@ prevnonblank({lnum}) *prevnonblank()* (`integer`) printf({fmt}, {expr1} ...) *printf()* + Lua: Prefer |string.format()|. + Return a String with {fmt}, where "%" items are replaced by the formatted form of their respective arguments. Example: >vim echo printf("%4d: E%d %.30s", lnum, errno, msg) @@ -7765,6 +8085,8 @@ pyxeval({expr}) *pyxeval()* (`any`) rand([{expr}]) *rand()* + Lua: Prefer |math.random()|. + Return a pseudo-random Number generated with an xoshiro128** algorithm using seed {expr}. The returned number is 32 bits, also on 64 bits systems, for consistency. @@ -7814,6 +8136,9 @@ range({expr} [, {max} [, {stride}]]) *range()* *E726* *E (`any`) readblob({fname} [, {offset} [, {size}]]) *readblob()* + Lua: Prefer |io.open()| with `:read("*a")` in binary mode for + whole-file reads; offset, size, and Blob return differ. + Read file {fname} in binary mode and return a |Blob|. If {offset} is specified, read the file from the specified offset. If it is a negative value, it is used as an offset @@ -7846,6 +8171,9 @@ readblob({fname} [, {offset} [, {size}]]) *readblob()* (`any`) readdir({directory} [, {expr}]) *readdir()* + Lua: Prefer |vim.fs.dir()| as an iterator, then collect and + filter results as needed. + Return a list with file and directory names in {directory}. You can also use |glob()| if you don't need to do complicated things, such as limiting the number of matches. @@ -7883,6 +8211,9 @@ readdir({directory} [, {expr}]) *readdir()* (`any`) readfile({fname} [, {type} [, {max}]]) *readfile()* + Lua: Prefer |io.open()| with `:read("*a")`, then split lines + as needed; `{type}`, `{max}`, and Blob return differ. + Read file {fname} and return a |List|, each line of the file as an item. Lines are broken at NL characters. Macintosh files separated with CR will result in a single long line @@ -7924,6 +8255,8 @@ readfile({fname} [, {type} [, {max}]]) *readfile()* (`string[]`) reduce({object}, {func} [, {initial}]) *reduce()* *E998* + Lua: Prefer |Iter:fold()|. + {func} is called for every item in {object}, which can be a |String|, |List| or a |Blob|. {func} is called with two arguments: the result so far and current item. After @@ -7975,6 +8308,8 @@ reg_recording() *reg_recording()* reltime() *reltime()* reltime({start}) reltime({start}, {end}) + Lua: Prefer |uv.hrtime()|. + Return an item that represents a time value. The item is a list with items that depend on the system. The item can be passed to |reltimestr()| to convert it to a @@ -8002,6 +8337,9 @@ reltime({start}, {end}) (`any`) reltimefloat({time}) *reltimefloat()* + Lua: Prefer |uv.hrtime()| with `(finish - start) / 1e9` for + elapsed seconds. + Return a Float that represents the time value of {time}. Unit of time is seconds. Example: @@ -8039,6 +8377,8 @@ reltimestr({time}) *reltimestr()* (`any`) remove({list}, {idx}) *remove()* + Lua: Prefer |table.remove()|. + remove({list}, {idx}, {end}) Without {end}: Remove the item at {idx} from |List| {list} and return the item. @@ -8085,6 +8425,9 @@ remove({blob}, {idx}, {end}) (`any`) remove({dict}, {key}) + Lua: Prefer `local value = dict[key]; dict[key] = nil` for + dicts; missing-key behavior differs. + Remove the entry from {dict} with key {key} and return it. Example: >vim echo "removed " .. remove(dict, "one") @@ -8099,6 +8442,8 @@ remove({dict}, {key}) (`any`) rename({from}, {to}) *rename()* + Lua: Prefer |uv.fs_rename()| or |os.rename()|. + Rename the file by the name {from} to the name {to}. This should also work to move files across file systems. The result is a Number, which is 0 if the file was renamed @@ -8114,6 +8459,9 @@ rename({from}, {to}) *rename()* (`integer`) repeat({expr}, {count}) *repeat()* + Lua: Prefer |string.rep()| for strings; lists need manual + repetition. + Repeat {expr} {count} times and return the concatenated result. Example: >vim let separator = repeat('-', 80) @@ -8150,6 +8498,9 @@ resolve({filename}) *resolve()* *E65 (`string`) reverse({object}) *reverse()* + Lua: Prefer `vim.iter(list):rev():totable()` for lists; + strings, blobs, and in-place behavior differ. + Reverse the order of items in {object}. {object} can be a |List|, a |Blob| or a |String|. For a List and a Blob the items are reversed in-place and {object} is returned. @@ -8167,6 +8518,10 @@ reverse({object}) *reverse()* (`T[]`) round({expr}) *round()* + Lua: Prefer + `expr >= 0 and math.floor(expr + 0.5) or math.ceil(expr - 0.5)` + for half-away-from-zero rounding. + Round off {expr} to the nearest integral value and return it as a |Float|. If {expr} lies halfway between two integral values, then use the larger one (away from zero). @@ -8187,6 +8542,8 @@ round({expr}) *round()* (`number`) rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* + Lua: Prefer |vim.rpcnotify()|. + Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. Example: >vim @@ -8202,6 +8559,8 @@ rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* (`integer`) rpcrequest({channel}, {method} [, {args}...]) *rpcrequest()* + Lua: Prefer |vim.rpcrequest()|. + Sends a request to {channel} to invoke {method} via |RPC| and blocks until a response is received. Example: >vim @@ -8843,6 +9202,8 @@ serverstop({address}) *serverstop()* (`integer`) setbufline({buf}, {lnum}, {text}) *setbufline()* + Lua: Prefer |nvim_buf_set_lines()|. + Set line {lnum} to {text} in buffer {buf}. This works like |setline()| for the specified buffer. @@ -8876,6 +9237,9 @@ setbufline({buf}, {lnum}, {text}) *setbufline()* (`integer`) setbufvar({buf}, {varname}, {val}) *setbufvar()* + Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving + {buf} to a bufnr; option names use |nvim_set_option_value()|. + Set option or local variable {varname} in buffer {buf} to {val}. This also works for a global or local window option, but it @@ -8938,6 +9302,10 @@ setcellwidths({list}) *setcellwidths()* (`any`) setcharpos({expr}, {list}) *setcharpos()* + Lua: Prefer |nvim_win_set_cursor()| or |nvim_buf_set_mark()| + with |vim.str_byteindex()|; special positions, `off`, and + `curswant` differ. + Same as |setpos()| but uses the specified column number as the character index instead of the byte index in the line. @@ -9017,7 +9385,15 @@ setcmdpos({pos}) *setcmdpos()* (`any`) setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* + Lua: Prefer |nvim_win_set_cursor()| with + |vim.str_byteindex()|; `off`, return values, and special line + forms differ. + setcursorcharpos({list}) + Lua: Prefer |nvim_win_set_cursor()| with + |vim.str_byteindex()|; list shape, `off`, and return values + differ. + Same as |cursor()| but uses the specified column number as the character index instead of the byte index in the line. @@ -9037,6 +9413,8 @@ setcursorcharpos({list}) (`any`) setenv({name}, {val}) *setenv()* + Lua: Prefer |vim.env|. + Set environment variable {name} to {val}. Example: >vim call setenv('HOME', '/home/myhome') @@ -9051,6 +9429,8 @@ setenv({name}, {val}) *setenv()* (`any`) setfperm({fname}, {mode}) *setfperm()* *chmod* + Lua: Prefer |uv.fs_chmod()|. + Set the file permissions for {fname} to {mode}. {mode} must be a string with 9 characters. It is of the form "rwxrwxrwx", where each group of "rwx" flags represent, in @@ -9075,6 +9455,9 @@ setfperm({fname}, {mode}) *setfperm()* *chmo (`any`) setline({lnum}, {text}) *setline()* + Lua: Prefer |nvim_set_current_line()| or + |nvim_buf_set_lines()|. + Set line {lnum} of the current buffer to {text}. To insert lines use |append()|. To set lines in another buffer use |setbufline()|. @@ -9150,6 +9533,10 @@ setmatches({list} [, {win}]) *setmatches()* (`any`) setpos({expr}, {list}) *setpos()* + Lua: Prefer |nvim_win_set_cursor()| for "." or + |nvim_buf_set_mark()| for marks; special positions, `off`, and + `curswant` differ. + Set the position for String {expr}. Possible values: . the cursor 'x mark x @@ -9400,6 +9787,8 @@ setreg({regname}, {value} [, {options}]) *setreg()* (`any`) settabvar({tabnr}, {varname}, {val}) *settabvar()* + Lua: Prefer |nvim_tabpage_set_var()| or |vim.t|. + Set tab-local variable {varname} to {val} in tab page {tabnr}. |t:var| The {varname} argument is a string. @@ -9416,6 +9805,10 @@ settabvar({tabnr}, {varname}, {val}) *settabvar()* (`any`) settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* + Lua: Prefer |nvim_win_set_var()| or |vim.w| after resolving + {tabnr} and {winnr} to a winid; option names use + |nvim_set_option_value()|. + Set option or local variable {varname} in window {winnr} to {val}. Tabs are numbered starting with one. For the current tabpage @@ -9483,6 +9876,9 @@ settagstack({nr}, {dict} [, {action}]) *settagstack()* (`any`) setwinvar({nr}, {varname}, {val}) *setwinvar()* + Lua: Prefer |nvim_win_set_var()| or |vim.w| after resolving + {nr} to a winid; option names use |nvim_set_option_value()|. + Like |settabwinvar()| for the current tab page. Examples: >vim call setwinvar(1, "&list", 0) @@ -9509,6 +9905,9 @@ sha256({expr}) *sha256()* (`string`) shellescape({string} [, {special}]) *shellescape()* + Lua: Prefer |vim.system()| with list args to avoid shell + escaping; `:!` and {special} semantics differ. + Escape {string} for use as a shell command argument. On Windows when 'shellslash' is not set, encloses {string} in @@ -9548,6 +9947,10 @@ shellescape({string} [, {special}]) *shellescape()* (`string`) shiftwidth([{col}]) *shiftwidth()* + Lua: Prefer |vim.bo| for simple cases: + `vim.bo.shiftwidth > 0 and vim.bo.shiftwidth or vim.bo.tabstop`; + `{col}` and 'vartabstop' semantics differ. + Returns the effective value of 'shiftwidth'. This is the 'shiftwidth' value unless it is zero, in which case it is the 'tabstop' value. To be backwards compatible in indent @@ -10004,6 +10407,9 @@ sign_unplacelist({list}) *sign_unplacelist()* (`(0|-1)[]`) simplify({filename}) *simplify()* + Lua: Prefer |vim.fs.normalize()|; `~`/$VAR expansion and + leading `./` or trailing `/` handling differ. + Simplify the file name as much as possible without changing the meaning. Shortcuts (on MS-Windows) or symbolic links (on Unix) are not resolved. If the first path component in @@ -10027,6 +10433,8 @@ simplify({filename}) *simplify()* (`string`) sin({expr}) *sin()* + Lua: Prefer |math.sin()|. + Return the sine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -10043,6 +10451,8 @@ sin({expr}) *sin()* (`number`) sinh({expr}) *sinh()* + Lua: Prefer |math.sinh()|. + Return the hyperbolic sine of {expr} as a |Float| in the range [-inf, inf]. {expr} must evaluate to a |Float| or a |Number|. @@ -10111,6 +10521,9 @@ sockconnect({mode}, {address} [, {opts}]) *sockconnect()* (`any`) sort({list} [, {how} [, {dict}]]) *sort()* *E702* + Lua: Prefer |table.sort()| with a custom comparator; it is not + stable and Vim's `i`/`l`/`n`/`N`/`f` modes differ. + Sort the items in {list} in-place. Returns {list}. If you want a list to remain unmodified make a copy first: >vim @@ -10206,6 +10619,10 @@ soundfold({word}) *soundfold()* (`string`) spellbadword([{sentence}]) *spellbadword()* + Lua: Prefer |vim.spell.check()| for string input; it returns + all matches with positions, not just the first one or + cursor-moving behavior. + Without argument: The result is the badly spelled word under or after the cursor. The cursor is moved to the start of the bad word. When no bad word is found in the cursor line the @@ -10265,6 +10682,8 @@ spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()* (`string[]`) split({string} [, {pattern} [, {keepempty}]]) *split()* + Lua: Prefer |vim.split()|. + Make a |List| out of {string}. When {pattern} is omitted or empty each white space separated sequence of characters becomes an item. @@ -10298,6 +10717,8 @@ split({string} [, {pattern} [, {keepempty}]]) *split()* (`string[]`) sqrt({expr}) *sqrt()* + Lua: Prefer |math.sqrt()|. + Return the non-negative square root of Float {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number|. When {expr} @@ -10317,6 +10738,8 @@ sqrt({expr}) *sqrt()* (`any`) srand([{expr}]) *srand()* + Lua: Prefer |math.randomseed()|. + Initialize seed used by |rand()|: - If {expr} is not given, seed values are initialized by reading from /dev/urandom, if possible, or using time(NULL) @@ -10432,6 +10855,9 @@ stdpath({what}) *stdpath()* *E610 (`string|string[]`) str2float({string} [, {quoted}]) *str2float()* + Lua: Prefer |tonumber()| for simple numbers; quoted digits, + hex forms, and trailing text differ. + Convert String {string} to a Float. This mostly works the same as when using a floating point number in an expression, see |floating-point-format|. But it's a bit more permissive. @@ -10478,6 +10904,9 @@ str2list({string} [, {utf8}]) *str2list()* (`any`) str2nr({string} [, {base}]) *str2nr()* + Lua: Prefer |tonumber()| for simple numbers; quoted digits, + base prefixes, and trailing text differ. + Convert string {string} to a number. {base} is the conversion base, it can be 2, 8, 10 or 16. When {quoted} is present and non-zero then embedded single @@ -10543,6 +10972,9 @@ strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* (`string`) strchars({string} [, {skipcc}]) *strchars()* + Lua: Prefer |vim.str_utfindex()| for codepoint counts; + `skipcc` handling differs. + Returns the number of characters in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. @@ -10578,6 +11010,9 @@ strchars({string} [, {skipcc}]) *strchars()* (`integer`) strdisplaywidth({string} [, {col}]) *strdisplaywidth()* + Lua: Prefer |nvim_strwidth()| when `{col}` is 0; Tab expansion + and window-option semantics differ. + Returns the number of display cells String {string} occupies on the screen when it starts at {col} (first column is zero). Returns zero on error. @@ -10602,6 +11037,8 @@ strdisplaywidth({string} [, {col}]) *strdisplaywidth()* (`integer`) strftime({format} [, {time}]) *strftime()* + Lua: Prefer |os.date()|. + Formats a date and time String specified by {format}. The given {time} is used, or the current time if no time is given. The {format} depends on your system, this is not portable! @@ -10642,6 +11079,10 @@ strgetchar({str}, {index}) *strgetchar()* (`integer`) stridx({haystack}, {needle} [, {start}]) *stridx()* + Lua: Prefer |string.find()| with `plain = true` and + `start + 1`, then subtract 1; missing matches return nil + instead of -1. + Returns the byte index of the first occurrence of {needle} in {haystack}. If {start} is specified, the search starts at index {start}. @@ -10669,6 +11110,9 @@ stridx({haystack}, {needle} [, {start}]) *stridx()* (`integer`) string({expr}) *string()* + Lua: Prefer |vim.inspect()| for tables, or |tostring()| for + scalars. + Converts {expr} to a String. If {expr} is a Number, Float, String, Blob or a composition of them, the result can be parsed back with |eval()|. @@ -10702,6 +11146,8 @@ string({expr}) *string()* (`string`) strlen({string}) *strlen()* + Lua: Prefer |string.len()|. + Returns the length of String {string} in bytes. If the argument is a Number it is first converted to a String. For other types an error is given and zero is returned. @@ -10716,6 +11162,9 @@ strlen({string}) *strlen()* (`integer`) strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* + Lua: Prefer |string.sub()| for byte slices; negative `start` + and the `chars` flag differ. + Gets a substring from {src}, starting from byte {start}, with byte length {len}. Returns empty string on error. @@ -10780,6 +11229,10 @@ strptime({format}, {timestring}) *strptime()* (`integer`) strridx({haystack}, {needle} [, {start}]) *strridx()* + Lua: Prefer |string.find()| in a loop with `plain = true`, + then subtract 1; empty-needle and missing-match semantics + differ. + Returns the byte index of the last occurrence of {needle} in {haystack}. When {start} is specified, matches beyond this index are @@ -10822,6 +11275,9 @@ strtrans({string}) *strtrans()* (`string`) strutf16len({string} [, {countcc}]) *strutf16len()* + Lua: Prefer |vim.str_utfindex()| with `"utf-16"`; + `countcc = false` semantics differ. + Returns the number of UTF-16 code units in String {string} (after converting it to UTF-16). @@ -10849,6 +11305,8 @@ strutf16len({string} [, {countcc}]) *strutf16len()* (`integer`) strwidth({string}) *strwidth()* + Lua: Prefer |nvim_strwidth()|. + Returns the number of display cells String {string} occupies. A Tab character is counted as one cell, alternatively use |strdisplaywidth()|. @@ -10900,6 +11358,9 @@ submatch({nr} [, {list}]) *submatch()* *E93 (`string`) substitute({string}, {pat}, {sub}, {flags}) *substitute()* + Lua: Prefer |string.gsub()| for common substitutions; Vim + patterns, flags, and replacement semantics differ. + Performs string substitution. Returns a copy of {string} in which the first match of {pat} is replaced with {sub}. When {flags} is "g", all matches of {pat} in {string} are @@ -11172,7 +11633,9 @@ synstack({lnum}, {col}) *synstack()* (`integer[]`) system({cmd} [, {input}]) *system()* *E677* - Lua: Prefer |vim.system()|. + Lua: Prefer `vim.system(...):wait().stdout` for string output; + string commands use the shell in Vimscript, not by default in + Lua. Gets the output of {cmd} as a |string| (|systemlist()| returns a |List|) and sets |v:shell_error| to the error code. @@ -11228,6 +11691,10 @@ system({cmd} [, {input}]) *system()* *E67 (`string`) systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* + Lua: Prefer `vim.system(...):wait().stdout` split into lines; + string commands use the shell in Vimscript, not by default in + Lua. + Same as |system()|, but returns a |List| with lines (parts of output separated by NL) with NULs transformed into NLs. Output is the same as |readfile()| will output with {binary} @@ -11250,6 +11717,10 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* (`string[]`) tabpagebuflist([{arg}]) *tabpagebuflist()* + Lua: Prefer |nvim_tabpage_list_wins()| with + |nvim_win_get_buf()|; invalid tabpages error instead of + returning 0. + Returns a |List| of buffer numbers, one for each window in the specified tab page. {arg} specifies the number of the tab page to be used. When @@ -11269,6 +11740,10 @@ tabpagebuflist([{arg}]) *tabpagebuflist()* (`any`) tabpagenr([{arg}]) *tabpagenr()* + Lua: Prefer |nvim_tabpage_get_number()| with + |nvim_get_current_tabpage()| for the current tab, or + `#vim.api.nvim_list_tabpages()` for "$"; "#" differs. + Returns the number of the current tab page. The first tab page has number 1. @@ -11289,6 +11764,11 @@ tabpagenr([{arg}]) *tabpagenr()* (`integer`) tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* + Lua: Prefer |nvim_win_get_number()| with + |nvim_tabpage_get_win()| for the current window, or the length + of |nvim_tabpage_list_wins()| for "$"; "#" and invalid-tab + behavior differ. + Like |winnr()| but for tab page {tabarg}. {tabarg} specifies the number of tab page to be used. {arg} is used like with |winnr()|: @@ -11366,6 +11846,8 @@ taglist({expr} [, {filename}]) *taglist()* (`any`) tan({expr}) *tan()* + Lua: Prefer |math.tan()|. + Return the tangent of {expr}, measured in radians, as a |Float| in the range [-inf, inf]. {expr} must evaluate to a |Float| or a |Number|. @@ -11383,6 +11865,8 @@ tan({expr}) *tan()* (`number`) tanh({expr}) *tanh()* + Lua: Prefer |math.tanh()|. + Return the hyperbolic tangent of {expr} as a |Float| in the range [-1, 1]. {expr} must evaluate to a |Float| or a |Number|. @@ -11400,6 +11884,9 @@ tanh({expr}) *tanh()* (`number`) tempname() *tempname()* + Lua: Prefer |os.tmpname()| for a temporary name; Nvim's + |tempdir| and nonexistence are not guaranteed. + Generates a (non-existent) filename located in the Nvim root |tempdir|. Scripts can use the filename as a temporary file. Example: >vim @@ -11461,6 +11948,10 @@ timer_pause({timer}, {paused}) *timer_pause()* (`any`) timer_start({time}, {callback} [, {options}]) *timer_start()* *timer* + Lua: Prefer |vim.defer_fn()| for one-shot timers, or + |uv.new_timer()| for repeating timers; callback and handle + semantics differ. + Create a timer and return the timer ID. {time} is the waiting time in milliseconds. This is the @@ -11499,6 +11990,9 @@ timer_start({time}, {callback} [, {options}]) *timer_start()* *time (`any`) timer_stop({timer}) *timer_stop()* + Lua: Prefer |uv.timer_stop()| and |uv.close()| on a stored + |uv.new_timer()| handle; timer IDs differ. + Stop a timer. The timer callback will no longer be invoked. {timer} is an ID returned by |timer_start()|, thus it must be a Number. If {timer} does not exist there is no error. @@ -11518,6 +12012,8 @@ timer_stopall() *timer_stopall()* (`any`) tolower({expr}) *tolower()* + Lua: Prefer |string.lower()|. + Converts a String to lowercase (like applying |gu|). Returns empty string on error. @@ -11528,6 +12024,8 @@ tolower({expr}) *tolower()* (`string`) toupper({expr}) *toupper()* + Lua: Prefer |string.upper()|. + Converts a String to uppercase (like applying |gU|). Returns empty string on error. @@ -11560,6 +12058,8 @@ tr({src}, {fromstr}, {tostr}) *tr()* (`string`) trim({text} [, {mask} [, {dir}]]) *trim()* + Lua: Prefer |vim.trim()|. + Return {text} as a String where any character in {mask} is removed from the beginning and/or end of {text}. @@ -11596,6 +12096,8 @@ trim({text} [, {mask} [, {dir}]]) *trim()* (`string`) trunc({expr}) *trunc()* + Lua: Prefer |math.modf()| (first return value). + Return the largest integral value with magnitude less than or equal to {expr} as a |Float| (truncate towards zero). {expr} must evaluate to a |Float| or a |Number|. @@ -11615,6 +12117,9 @@ trunc({expr}) *trunc()* (`integer`) type({expr}) *type()* + Lua: Prefer |lua-type()| for most Lua type checks; Vim type + IDs differ. + Returns the type of {expr} as a Number. Instead of using the number directly, it is better to use the v:t_ variable that has the value: @@ -11737,6 +12242,10 @@ uniq({list} [, {func} [, {dict}]]) *uniq()* *E88 (`any[]|0`) utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) *utf16idx()* + Lua: Prefer |vim.str_utfindex()| with `"utf-16"` and + `strict_indexing = false`; `countcc` and `charidx` semantics + differ. + Same as |charidx()| but returns the UTF-16 code unit index of the byte at {idx} in {string} (after converting it to UTF-16). @@ -11775,6 +12284,8 @@ utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) *utf16idx()* (`integer`) values({dict}) *values()* + Lua: Prefer |vim.tbl_values()|. + Return a |List| with all the values of {dict}. The |List| is in arbitrary order. Also see |items()| and |keys()|. Returns zero if {dict} is not a |Dict|. @@ -11896,6 +12407,8 @@ visualmode([{expr}]) *visualmode()* (`string`) wait({timeout}, {condition} [, {interval}]) *wait()* + Lua: Prefer |vim.wait()|. + Waits until {condition} evaluates to |TRUE|, where {condition} is a |Funcref| or |string| containing an expression. @@ -11958,6 +12471,8 @@ wildtrigger() *wildtrigger()* (`number`) win_execute({id}, {command} [, {silent}]) *win_execute()* + Lua: Prefer |nvim_win_call()|. + Like `execute()` but in the context of window {id}. The window will temporarily be made the current window, without triggering autocommands or changing directory. When @@ -11980,6 +12495,8 @@ win_execute({id}, {command} [, {silent}]) *win_execute()* (`any`) win_findbuf({bufnr}) *win_findbuf()* + Lua: Prefer |nvim_list_wins()| with |nvim_win_get_buf()|. + Returns a |List| with |window-ID|s for windows that contain buffer {bufnr}. When there is none the list is empty. @@ -11990,6 +12507,10 @@ win_findbuf({bufnr}) *win_findbuf()* (`integer[]`) win_getid([{win} [, {tab}]]) *win_getid()* + Lua: Prefer |nvim_get_current_win()| when omitted, or + |nvim_tabpage_list_wins()| with |nvim_win_get_number()| after + resolving {tab}; invalid windows return 0 in Vimscript. + Get the |window-ID| for the specified window. When {win} is missing use the current window. With {win} this is the window number. The top window has @@ -12030,6 +12551,9 @@ win_gettype([{nr}]) *win_gettype()* (`'autocmd'|'command'|''|'loclist'|'popup'|'preview'|'quickfix'|'unknown'`) win_gotoid({expr}) *win_gotoid()* + Lua: Prefer |nvim_set_current_win()|; invalid IDs error + instead of returning FALSE. + Go to window with ID {expr}. This may also change the current tabpage. Return TRUE if successful, FALSE if the window cannot be @@ -12042,6 +12566,10 @@ win_gotoid({expr}) *win_gotoid()* (`0|1`) win_id2tabwin({expr}) *win_id2tabwin()* + Lua: Prefer |nvim_win_get_tabpage()| and + |nvim_win_get_number()| for valid windows; invalid IDs error + instead of returning `[0, 0]`. + Return a list with the tab number and window number of window with ID {expr}: [tabnr, winnr]. Return [0, 0] if the window cannot be found. @@ -12053,6 +12581,9 @@ win_id2tabwin({expr}) *win_id2tabwin()* (`any`) win_id2win({expr}) *win_id2win()* + Lua: Prefer |nvim_win_get_number()| for valid windows; windows + outside the current tabpage and invalid IDs differ. + Return the window number of window with ID {expr}. Return 0 if the window cannot be found in the current tabpage. @@ -12104,6 +12635,9 @@ win_move_statusline({nr}, {offset}) *win_move_statusline()* (`any`) win_screenpos({nr}) *win_screenpos()* + Lua: Prefer |nvim_win_get_position()| and add 1 to row and + col; invalid-window semantics differ. + Return the screen position of window {nr} as a list with two numbers: [row, col]. The first window always has position [1, 1], unless there is a tabline, then it is [2, 1]. @@ -12146,6 +12680,8 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* (`any`) winbufnr({nr}) *winbufnr()* + Lua: Prefer |nvim_win_get_buf()|. + Returns the buffer number associated with window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero, the number of the buffer in the current @@ -12248,6 +12784,11 @@ winline() *winline()* (`integer`) winnr([{arg}]) *winnr()* + Lua: Prefer |nvim_win_get_number()| with + |nvim_get_current_win()| for the current window, or + |nvim_tabpage_list_wins()| with |nvim_get_current_tabpage()| + for "$"; "#", motion args, and hidden windows differ. + Returns the number of the current window. The top window has number 1. Returns zero for a hidden or non |focusable| window, unless it is the current window. @@ -12457,6 +12998,8 @@ writefile({data}, {fname} [, {flags}]) *writefile()* (`any`) xor({expr}, {expr}) *xor()* + Lua: Prefer |bit.bxor()|. + Bitwise XOR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see `and()` and `or()`. diff --git a/runtime/lua/vim/_meta/vimfn.gen.lua b/runtime/lua/vim/_meta/vimfn.gen.lua index 19f55259e7..6784ba6cd2 100644 --- a/runtime/lua/vim/_meta/vimfn.gen.lua +++ b/runtime/lua/vim/_meta/vimfn.gen.lua @@ -4,6 +4,8 @@ -- error('Cannot require a meta file') +--- Lua: Prefer |math.abs()|. +--- --- Return the absolute value of {expr}. When {expr} evaluates to --- a |Float| abs() returns a |Float|. When {expr} can be --- converted to a |Number| abs() returns a |Number|. Otherwise @@ -20,6 +22,8 @@ error('Cannot require a meta file') --- @return number function vim.fn.abs(expr) end +--- Lua: Prefer |math.acos()|. +--- --- Return the arc cosine of {expr} measured in radians, as a --- |Float| in the range of [0, pi]. --- {expr} must evaluate to a |Float| or a |Number| in the range @@ -36,6 +40,8 @@ function vim.fn.abs(expr) end --- @return number function vim.fn.acos(expr) end +--- Lua: Prefer |table.insert()| for lists and `..` for blobs. +--- --- Append the item {expr} to |List| or |Blob| {object}. Returns --- the resulting |List| or |Blob|. Examples: >vim --- let alist = add([1, 2, 3], item) @@ -51,6 +57,8 @@ function vim.fn.acos(expr) end --- @return any # Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|. function vim.fn.add(object, expr) end +--- Lua: Prefer |bit.band()|. +--- --- Bitwise AND on the two arguments. The arguments are converted --- to a number. A List, Dict or Float argument causes an error. --- Also see |or()| and |xor()|. @@ -72,6 +80,8 @@ vim.fn['and'] = function(expr, expr1) end --- @return table function vim.fn.api_info() end +--- Lua: Prefer |nvim_buf_set_lines()|. +--- --- When {text} is a |List|: Append each item of the |List| as a --- text line below line {lnum} in the current buffer. --- Otherwise append {text} as one text line below line {lnum} in @@ -91,6 +101,8 @@ function vim.fn.api_info() end --- @return 0|1 function vim.fn.append(lnum, text) end +--- Lua: Prefer |nvim_buf_set_lines()|. +--- --- Like |append()| but append the text in buffer {buf}. --- --- This function works only for loaded buffers. First call @@ -175,6 +187,8 @@ function vim.fn.arglistid(winnr, tabnr) end --- @return string|string[] function vim.fn.argv(nr, winid) end +--- Lua: Prefer |math.asin()|. +--- --- Return the arc sine of {expr} measured in radians, as a |Float| --- in the range of [-pi/2, pi/2]. --- {expr} must evaluate to a |Float| or a |Number| in the range @@ -200,6 +214,8 @@ function vim.fn.asin(expr) end --- @return 0|1 function vim.fn.assert_beeps(cmd) end +--- Lua: Prefer |assert()| with |vim.deep_equal()|. +--- --- When {expected} and {actual} are not equal an error message is --- added to |v:errors| and 1 is returned. Otherwise zero is --- returned. |assert-return| @@ -293,6 +309,8 @@ function vim.fn.assert_exception(error, msg) end --- @return 0|1 function vim.fn.assert_fails(cmd, error, msg, lnum, context) end +--- Lua: Prefer |assert()|. +--- --- When {actual} is not false an error message is added to --- |v:errors|, like with |assert_equal()|. --- The error is in the form "Expected False but got {actual}". @@ -308,6 +326,8 @@ function vim.fn.assert_fails(cmd, error, msg, lnum, context) end --- @return 0|1 function vim.fn.assert_false(actual, msg) end +--- Lua: Prefer |assert()|. +--- --- This asserts number and |Float| values. When {actual} is lower --- than {lower} or higher than {upper} an error message is added --- to |v:errors|. Also see |assert-return|. @@ -383,6 +403,8 @@ function vim.fn.assert_notmatch(pattern, actual, msg) end --- @return 0|1 function vim.fn.assert_report(msg) end +--- Lua: Prefer |assert()|. +--- --- When {actual} is not true an error message is added to --- |v:errors|, like with |assert_equal()|. --- Also see |assert-return|. @@ -396,6 +418,8 @@ function vim.fn.assert_report(msg) end --- @return 0|1 function vim.fn.assert_true(actual, msg) end +--- Lua: Prefer |math.atan()|. +--- --- Return the principal value of the arc tangent of {expr}, in --- the range [-pi/2, +pi/2] radians, as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. @@ -410,6 +434,8 @@ function vim.fn.assert_true(actual, msg) end --- @return number function vim.fn.atan(expr) end +--- Lua: Prefer |math.atan2()|. +--- --- Return the arc tangent of {expr1} / {expr2}, measured in --- radians, as a |Float| in the range [-pi, pi]. --- {expr1} and {expr2} must evaluate to a |Float| or a |Number|. @@ -487,6 +513,8 @@ function vim.fn.browsedir(title, initdir) end --- @return integer function vim.fn.bufadd(name) end +--- Lua: Prefer |nvim_buf_is_valid()| after resolving {buf} to a bufnr. +--- --- Checks whether a buffer with the name or number {buf} exists. --- Returns |TRUE| if the buffer exists, |FALSE| otherwise. --- If the {buf} argument is a number, buffer numbers are used. @@ -513,6 +541,8 @@ function vim.fn.bufadd(name) end function vim.fn.bufexists(buf) end --- @deprecated +--- Lua: Prefer |nvim_buf_is_valid()| after resolving {buf} to a bufnr. +--- --- Obsolete name for |bufexists()|. --- --- @param ... any @@ -520,6 +550,8 @@ function vim.fn.bufexists(buf) end function vim.fn.buffer_exists(...) end --- @deprecated +--- Lua: Prefer |nvim_buf_get_name()| after resolving {buf} to a bufnr. +--- --- Obsolete name for |bufname()|. --- --- @param ... any @@ -527,12 +559,16 @@ function vim.fn.buffer_exists(...) end function vim.fn.buffer_name(...) end --- @deprecated +--- Lua: Prefer |nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ. +--- --- Obsolete name for |bufnr()|. --- --- @param ... any --- @return integer function vim.fn.buffer_number(...) end +--- Lua: Prefer |vim.bo| or |nvim_get_option_value()| after resolving {buf} to a bufnr. +--- --- Checks whether a buffer called {buf} exists and is listed --- (has the 'buflisted' option set). Returns |TRUE| if so, --- |FALSE| otherwise. @@ -554,6 +590,8 @@ function vim.fn.buflisted(buf) end --- @param buf any function vim.fn.bufload(buf) end +--- Lua: Prefer |nvim_buf_is_loaded()| after resolving {buf} to a bufnr. +--- --- Checks whether a buffer called {buf} exists and is loaded --- (shown in a window or hidden). Returns |TRUE| if so, --- |FALSE| otherwise. @@ -563,6 +601,8 @@ function vim.fn.bufload(buf) end --- @return 0|1 function vim.fn.bufloaded(buf) end +--- Lua: Prefer |nvim_buf_get_name()| after resolving {buf} to a bufnr. +--- --- The result is the name of a buffer. Mostly as it is displayed --- by the `:ls` command, but not using special names such as --- "[No Name]". @@ -597,6 +637,8 @@ function vim.fn.bufloaded(buf) end --- @return string function vim.fn.bufname(buf) end +--- Lua: Prefer |nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ. +--- --- The result is the number of a buffer, as it is displayed by --- the `:ls` command. For the use of {buf}, see |bufname()| --- above. @@ -619,6 +661,8 @@ function vim.fn.bufname(buf) end --- @return integer function vim.fn.bufnr(buf, create) end +--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ. +--- --- Returns the |window-ID| of the first window associated with --- buffer {buf}. For the use of {buf}, see |bufname()| above. --- If buffer {buf} doesn't exist or there is no such window, -1 @@ -633,6 +677,8 @@ function vim.fn.bufnr(buf, create) end --- @return integer function vim.fn.bufwinid(buf) end +--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()| and |nvim_win_get_number()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ. +--- --- Like |bufwinid()| but return the window number instead of the --- |window-ID|. --- If buffer {buf} doesn't exist or there is no such window, -1 @@ -660,6 +706,8 @@ function vim.fn.bufwinnr(buf) end --- @return integer function vim.fn.byte2line(byte) end +--- Lua: Prefer |vim.str_byteindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; composing characters and out-of-range semantics differ. +--- --- Return byte index of the {nr}th character in the String --- {expr}. Use zero for the first character, it then returns --- zero. @@ -701,6 +749,8 @@ function vim.fn.byte2line(byte) end --- @return integer function vim.fn.byteidx(expr, nr, utf16) end +--- Lua: Prefer |vim.str_byteindex()| with `"utf-32"` or `"utf-16"` and `strict_indexing = false`. +--- --- Like |byteidx()|, except that a composing character is counted --- as a separate character. Example: >vim --- let s = 'e' .. nr2char(0x301) @@ -731,6 +781,8 @@ function vim.fn.byteidxcomp(expr, nr, utf16) end --- @return any function vim.fn.call(func, arglist, dict) end +--- Lua: Prefer |math.ceil()|. +--- --- Return the smallest integral value greater than or equal to --- {expr} as a |Float| (round up). --- {expr} must evaluate to a |Float| or a |Number|. @@ -773,6 +825,8 @@ function vim.fn.chanclose(id, stream) end --- @return integer function vim.fn.changenr() end +--- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ. +--- --- Send data to channel {id}. For a job, it writes it to the --- stdin of the process. For the stdio channel |channel-stdio|, --- it writes to Nvim's stdout. Returns the number of bytes @@ -795,6 +849,8 @@ function vim.fn.changenr() end --- @return 0|1 function vim.fn.chansend(id, data) end +--- Lua: Prefer |string.byte()|: only works with ASCII. +--- --- Return Number value of the first char in {string}. --- Examples: >vim --- echo char2nr(" ") " returns 32 @@ -828,6 +884,8 @@ function vim.fn.char2nr(string, utf8) end --- @return 0|1|2|3|'other' function vim.fn.charclass(string) end +--- Lua: Prefer |nvim_win_get_cursor()| with |vim.str_utfindex()| for ".", or |nvim_get_current_line()| with |vim.str_utfindex()| for "$"; marks, list input, and window semantics differ. +--- --- Same as |col()| but returns the character index of the column --- position given with {expr} instead of the byte position. --- @@ -842,6 +900,8 @@ function vim.fn.charclass(string) end --- @return integer function vim.fn.charcol(expr, winid) end +--- Lua: Prefer |vim.str_utfindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; `countcc = false` and out-of-range semantics differ. +--- --- Return the character index of the byte at {idx} in {string}. --- The index of the first character is zero. --- If there are no multibyte characters the returned value is @@ -882,6 +942,8 @@ function vim.fn.charcol(expr, winid) end --- @return integer function vim.fn.charidx(string, idx, countcc, utf16) end +--- Lua: Prefer |nvim_set_current_dir()| for the global directory; tab-local, window-local, and return semantics differ. +--- --- Changes the current working directory to {dir}. The scope of --- the change is determined as follows: --- If {scope} is not present, the current working directory is @@ -958,6 +1020,8 @@ function vim.fn.clearmatches(win) end --- @return table function vim.fn.cmdcomplete_info() end +--- Lua: Prefer |nvim_win_get_cursor()| for "." (add 1), or Lua `#` on |nvim_get_current_line()| for "$"; marks, list input, and `virtualedit` differ. +--- --- Returns the byte index of the column position given with --- {expr}. --- For accepted positions see |getpos()|. @@ -1192,6 +1256,8 @@ function vim.fn.complete_info(what) end --- @return integer function vim.fn.confirm(msg, choices, default, type) end +--- Lua: Prefer |vim.deepcopy()|; deeper than Vimscript |copy()|. +--- --- Make a copy of {expr}. For Numbers and Strings this isn't --- different from using {expr} directly. --- When {expr} is a |List| a shallow copy is created. This means @@ -1206,6 +1272,8 @@ function vim.fn.confirm(msg, choices, default, type) end --- @return T function vim.fn.copy(expr) end +--- Lua: Prefer |math.cos()|. +--- --- Return the cosine of {expr}, measured in radians, as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -1219,6 +1287,8 @@ function vim.fn.copy(expr) end --- @return number function vim.fn.cos(expr) end +--- Lua: Prefer |math.cosh()|. +--- --- Return the hyperbolic cosine of {expr} as a |Float| in the range --- [1, inf]. --- {expr} must evaluate to a |Float| or a |Number|. @@ -1297,6 +1367,8 @@ function vim.fn.ctxsize() end --- @return any function vim.fn.cursor(lnum, col, off) end +--- Lua: Prefer |nvim_win_set_cursor()| with `{lnum, col - 1}`; `off`, `curswant`, and failure semantics differ. +--- --- Positions the cursor at the column (byte count) {col} in the --- line {lnum}. The first column is one. --- @@ -1332,6 +1404,8 @@ function vim.fn.cursor(lnum, col, off) end --- @return any function vim.fn.cursor(list) end +--- Lua: Prefer |uv.kill()| with `"sigtrap"` (or `"sigint"` outside MS-Windows); exact semantics differ. +--- --- Specifically used to interrupt a program being debugged. It --- will cause process {pid} to get a SIGTRAP. Behavior for other --- processes is undefined. See |terminal-debug|. @@ -1344,6 +1418,8 @@ function vim.fn.cursor(list) end --- @return any function vim.fn.debugbreak(pid) end +--- Lua: Prefer |vim.deepcopy()|. +--- --- Make a copy of {expr}. For Numbers and Strings this isn't --- different from using {expr} directly. --- When {expr} is a |List| a full copy is created. This means @@ -1369,7 +1445,7 @@ function vim.fn.debugbreak(pid) end --- @return T function vim.fn.deepcopy(expr, noref) end ---- Lua: see |vim.fs.rm()|. +--- Lua: Prefer |vim.fs.rm()|. --- --- Without {flags} or with {flags} empty: Deletes the file by the --- name {fname}. @@ -1394,6 +1470,8 @@ function vim.fn.deepcopy(expr, noref) end --- @return integer function vim.fn.delete(fname, flags) end +--- Lua: Prefer |nvim_buf_set_lines()|. +--- --- Delete lines {first} to {last} (inclusive) from buffer {buf}. --- If {last} is omitted then delete line {first} only. --- On success 0 is returned, on failure 1 is returned. @@ -1587,6 +1665,8 @@ function vim.fn.digraph_set(chars, digraph) end --- @return any function vim.fn.digraph_setlist(digraphlist) end +--- Lua: Prefer plain Lua emptiness checks, or |vim.tbl_isempty()| for tables. +--- --- Return the Number 1 if {expr} is empty, zero otherwise. --- - A |List| or |Dictionary| is empty when it does not have any --- items. @@ -1599,6 +1679,8 @@ function vim.fn.digraph_setlist(digraphlist) end --- @return integer function vim.fn.empty(expr) end +--- Lua: Prefer |uv.os_environ()| for the full environment table; |vim.env| for keyed access. +--- --- Return all of environment variables as dictionary. You can --- check if an environment variable exists like this: >vim --- echo has_key(environ(), 'HOME') @@ -1677,6 +1759,8 @@ function vim.fn.eventhandler() end --- @return 0|1 function vim.fn.executable(expr) end +--- Lua: Prefer |nvim_exec()| or |vim.cmd()|. +--- --- Execute {command} and capture its output. --- If {command} is a |String|, returns {command} output. --- If {command} is a |List|, returns concatenated outputs. @@ -1810,6 +1894,8 @@ function vim.fn.exepath(expr) end --- @return 0|1 function vim.fn.exists(expr) end +--- Lua: Prefer |math.exp()|. +--- --- Return the exponential of {expr} as a |Float| in the range --- [0, inf]. --- {expr} must evaluate to a |Float| or a |Number|. @@ -1958,6 +2044,8 @@ function vim.fn.expand(string, nosuf, list) end --- @return any function vim.fn.expandcmd(string, options) end +--- Lua: Prefer |vim.list_extend()| for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ. +--- --- {expr1} and {expr2} must be both |Lists| or both --- |Dictionaries|. --- @@ -2000,6 +2088,8 @@ function vim.fn.expandcmd(string, options) end --- @return any function vim.fn.extend(expr1, expr2, expr3) end +--- Lua: Prefer |vim.list_extend()| on a copy for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ. +--- --- Like |extend()| but instead of adding items to {expr1} a new --- List or Dictionary is created and returned. {expr1} remains --- unchanged. @@ -2010,6 +2100,8 @@ function vim.fn.extend(expr1, expr2, expr3) end --- @return any function vim.fn.extendnew(expr1, expr2, expr3) end +--- Lua: Prefer |nvim_feedkeys()|. +--- --- Characters in {string} are queued for processing as if they --- come from a mapping or were typed by the user. --- @@ -2061,12 +2153,16 @@ function vim.fn.extendnew(expr1, expr2, expr3) end function vim.fn.feedkeys(string, mode) end --- @deprecated +--- Lua: Prefer |uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories. +--- --- Obsolete name for |filereadable()|. --- --- @param file string --- @return any function vim.fn.file_readable(file) end +--- Lua: Prefer |uv.fs_copyfile()| with `{ excl = true }`; return semantics differ. +--- --- Copy the file pointed to by the name {from} to {to}. The --- result is a Number, which is |TRUE| if the file was copied --- successfully, and |FALSE| when it failed. @@ -2080,6 +2176,8 @@ function vim.fn.file_readable(file) end --- @return 0|1 function vim.fn.filecopy(from, to) end +--- Lua: Prefer |uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories. +--- --- Returns |TRUE| if {file} exists, can be read, and is not --- a directory, else |FALSE|. --- @@ -2100,6 +2198,8 @@ function vim.fn.filecopy(from, to) end --- @return 0|1 function vim.fn.filereadable(file) end +--- Lua: Prefer |uv.fs_access()| with `"W"` and |uv.fs_stat()| if you need Vim's `2` return for directories. +--- --- Checks whether a file with the name {file} exists and can --- be written. Returns 1 if so. If {file} doesn't exist, or --- is not writable, the result is 0. If {file} is a @@ -2109,6 +2209,8 @@ function vim.fn.filereadable(file) end --- @return 0|1 function vim.fn.filewritable(file) end +--- Lua: Prefer |vim.tbl_filter()| for lists; dicts, strings, and blobs differ. +--- --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. --- For each item in {expr1} evaluate {expr2} and when the result --- is zero or false remove the item from the |List| or @@ -2166,6 +2268,8 @@ function vim.fn.filewritable(file) end --- @return any function vim.fn.filter(expr1, expr2) end +--- Lua: Prefer |vim.fs.find()| with `type = 'directory'`; `path`, `count`, and return semantics differ. +--- --- Find directory {name} in {path}. Supports both downwards and --- upwards recursive directory searches. See |file-searching| --- for the syntax of {path}. @@ -2189,6 +2293,8 @@ function vim.fn.filter(expr1, expr2) end --- @return string|string[] function vim.fn.finddir(name, path, count) end +--- Lua: Prefer |vim.fs.find()|; `path`, `count`, return semantics, and |'suffixesadd'| handling differ. +--- --- Just like |finddir()|, but find a file instead of a directory. --- Uses 'suffixesadd'. --- Example: >vim @@ -2202,6 +2308,8 @@ function vim.fn.finddir(name, path, count) end --- @return string|string[] function vim.fn.findfile(name, path, count) end +--- Lua: Prefer `vim.iter(list):flatten():totable()` for a new flattened list; in-place updates and `maxdepth` differ. +--- --- Flatten {list} up to {maxdepth} levels. Without {maxdepth} --- the result is a |List| without nesting, as if {maxdepth} is --- a very large number. @@ -2225,6 +2333,8 @@ function vim.fn.findfile(name, path, count) end --- @return any[]|0 function vim.fn.flatten(list, maxdepth) end +--- Lua: Prefer `vim.iter(list):flatten():totable()` for a new flattened list; `maxdepth` differs. +--- --- Like |flatten()| but first make a copy of {list}. --- --- @param list any[] @@ -2232,6 +2342,8 @@ function vim.fn.flatten(list, maxdepth) end --- @return any[]|0 function vim.fn.flattennew(list, maxdepth) end +--- Lua: Prefer |math.modf()| (first return value). +--- --- Convert {expr} to a Number by omitting the part after the --- decimal point. --- {expr} must evaluate to a |Float| or a |Number|. @@ -2257,6 +2369,8 @@ function vim.fn.flattennew(list, maxdepth) end --- @return any function vim.fn.float2nr(expr) end +--- Lua: Prefer |math.floor()|. +--- --- Return the largest integral value less than or equal to --- {expr} as a |Float| (round down). --- {expr} must evaluate to a |Float| or a |Number|. @@ -2273,6 +2387,8 @@ function vim.fn.float2nr(expr) end --- @return any function vim.fn.floor(expr) end +--- Lua: Prefer |math.fmod()|. +--- --- Return the remainder of {expr1} / {expr2}, even if the --- division is not representable. Returns {expr1} - i * {expr2} --- for some integer i such that if {expr2} is non-zero, the @@ -2293,6 +2409,8 @@ function vim.fn.floor(expr) end --- @return any function vim.fn.fmod(expr1, expr2) end +--- Lua: Prefer |nvim_cmd()| or |vim.cmd()| with structured arguments to avoid Ex filename escaping. +--- --- Escape {string} for use as file name command argument. All --- characters that have a special meaning, such as `'%'` and `'|'` --- are escaped with a backslash. For most systems the characters @@ -2314,6 +2432,8 @@ function vim.fn.fmod(expr1, expr2) end --- @return string function vim.fn.fnameescape(string) end +--- Lua: Prefer |vim.fs.dirname()|, |vim.fs.basename()|, |vim.fs.abspath()|, and |vim.fs.normalize()| for common path modifiers; modifier coverage differs. +--- --- Modify file name {fname} according to {mods}. {mods} is a --- string of characters like it is used for file names on the --- command line. See |filename-modifiers|. @@ -2402,6 +2522,8 @@ function vim.fn.foldtext() end --- @return string function vim.fn.foldtextresult(lnum) end +--- Lua: Prefer |pairs()| or |ipairs()|. +--- --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. --- For each item in {expr1} execute {expr2}. {expr1} is not --- modified; its values may be, as with |:lockvar| 1. |E741| @@ -2717,6 +2839,8 @@ function vim.fn.getbufinfo(buf) end --- @return vim.fn.getbufinfo.ret.item[] function vim.fn.getbufinfo(dict) end +--- Lua: Prefer |nvim_buf_get_lines()|. +--- --- Return a |List| with the lines starting from {lnum} to {end} --- (inclusive) in the buffer {buf}. If {end} is omitted, a --- |List| with only the line {lnum} is returned. See @@ -2748,6 +2872,8 @@ function vim.fn.getbufinfo(dict) end --- @return string[] function vim.fn.getbufline(buf, lnum, end_) end +--- Lua: Prefer |nvim_buf_get_lines()|. +--- --- Just like `getbufline()` but only get one line and return it --- as a string. --- @@ -2756,6 +2882,8 @@ function vim.fn.getbufline(buf, lnum, end_) end --- @return string function vim.fn.getbufoneline(buf, lnum) end +--- Lua: Prefer |nvim_buf_get_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_get_option_value()| or |vim.bo|. +--- --- The result is the value of option or local buffer variable --- {varname} in buffer {buf}. Note that the name without "b:" --- must be used. @@ -3154,6 +3282,8 @@ function vim.fn.getcompletion(pat, type, filtered) end --- @return string function vim.fn.getcompletiontype(pat) end +--- Lua: Prefer |nvim_win_get_cursor()|; return shape, 0-based column, and `curswant`/invalid-window semantics differ. +--- --- Get the position of the cursor. This is like getpos('.'), but --- includes an extra "curswant" item in the list: --- [0, lnum, col, off, curswant] ~ @@ -3195,6 +3325,8 @@ function vim.fn.getcurpos(winid) end --- @return any function vim.fn.getcursorcharpos(winid) end +--- Lua: Prefer |uv.cwd()| for the global working directory; tab-local and window-local scopes differ. +--- --- With no arguments, returns the name of the effective --- |current-directory|. With {winnr} or {tabnr} the working --- directory of that scope is returned, and 'autochdir' is @@ -3218,6 +3350,8 @@ function vim.fn.getcursorcharpos(winid) end --- @return string function vim.fn.getcwd(winnr, tabnr) end +--- Lua: Prefer |vim.env|. +--- --- Return the value of environment variable {name}. The {name} --- argument is a string, without a leading '$'. Example: >vim --- myHome = getenv('HOME') @@ -3245,6 +3379,8 @@ function vim.fn.getenv(name) end --- @return string function vim.fn.getfontname(name) end +--- Lua: Prefer |uv.fs_stat()|. +--- --- Returns the file permissions of the given file {fname} as a --- String. If {fname} does not exist or its directory cannot be --- read, an empty string is returned. @@ -3264,6 +3400,8 @@ function vim.fn.getfontname(name) end --- @return string function vim.fn.getfperm(fname) end +--- Lua: Prefer |uv.fs_stat()|. +--- --- Returns the size in bytes of the given file {fname}. --- If {fname} is a directory, 0 is returned. --- If the file {fname} can't be found, -1 is returned. @@ -3274,6 +3412,8 @@ function vim.fn.getfperm(fname) end --- @return integer function vim.fn.getfsize(fname) end +--- Lua: Prefer |uv.fs_stat()|. +--- --- Returns the last modification time ("mtime") of file {fname}. --- The value is measured as seconds since 1st Jan 1970, and may --- be passed to |strftime()|. See also @@ -3284,6 +3424,8 @@ function vim.fn.getfsize(fname) end --- @return integer function vim.fn.getftime(fname) end +--- Lua: Prefer |uv.fs_stat()|. +--- --- Returns a description of the type of file {fname} as a --- String. If {fname} does not exist an empty string is --- returned. @@ -3307,6 +3449,8 @@ function vim.fn.getftime(fname) end --- @return 'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other' function vim.fn.getftype(fname) end +--- Lua: Prefer |nvim_get_context()| for current jump history; window/tab arguments and return shape differ. +--- --- Returns the |jumplist| for the specified window. --- --- Without arguments use the current window. @@ -3331,6 +3475,8 @@ function vim.fn.getftype(fname) end --- @return vim.fn.getjumplist.ret function vim.fn.getjumplist(winnr, tabnr) end +--- Lua: Prefer |nvim_get_current_line()| or |nvim_buf_get_lines()|. +--- --- Without {end} the result is a String, which is line {lnum} --- from the current buffer. Example: >vim --- getline(1) @@ -3360,6 +3506,8 @@ function vim.fn.getjumplist(winnr, tabnr) end --- @return string function vim.fn.getline(lnum, end_) end +--- Lua: Prefer |nvim_get_current_line()| or |nvim_buf_get_lines()|. +--- --- @param lnum integer|string --- @param end_ true|number|string|table --- @return string|string[] @@ -3491,12 +3639,16 @@ function vim.fn.getmatches(win) end --- @return vim.fn.getmousepos.ret function vim.fn.getmousepos() end +--- Lua: Prefer |uv.os_getpid()|. +--- --- Return a Number which is the process ID of the Vim process. --- This is a unique number, until Vim exits. --- --- @return integer function vim.fn.getpid() end +--- Lua: Prefer |nvim_win_get_cursor()| for "." or |nvim_buf_get_mark()| for marks; return shape, `off`, and special-position semantics differ. +--- --- Gets a position, where {expr} is one of: --- . Cursor position. --- $ Last line in the current buffer. @@ -3887,6 +4039,8 @@ function vim.fn.getregtype(regname) end --- @return vim.fn.getscriptinfo.ret[] function vim.fn.getscriptinfo(opts) end +--- Lua: Prefer |debug.traceback()|. +--- --- Returns the current stack trace of Vim scripts. --- Stack trace is a |List|, of which each item is a |Dictionary| --- with the following items: @@ -3917,6 +4071,8 @@ function vim.fn.getstacktrace() end --- @return any function vim.fn.gettabinfo(tabnr) end +--- Lua: Prefer |nvim_tabpage_get_var()| or |vim.t|. +--- --- Get the value of a tab-local variable {varname} in tab page --- {tabnr}. |t:var| --- Tabs are numbered starting with one. @@ -3932,6 +4088,8 @@ function vim.fn.gettabinfo(tabnr) end --- @return any function vim.fn.gettabvar(tabnr, varname, def) end +--- Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving {tabnr} and {winnr} to a winid; option names use |nvim_get_option_value()| or |vim.wo|. +--- --- Get the value of window-local variable {varname} in window --- {winnr} in tab page {tabnr}. --- The {varname} argument is a string. When {varname} is empty a @@ -4089,6 +4247,8 @@ function vim.fn.getwinposx() end --- @return integer function vim.fn.getwinposy() end +--- Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving {winnr}; option names use |nvim_get_option_value()| or |vim.wo|. +--- --- Like |gettabwinvar()| for the current tabpage. --- Examples: >vim --- let list_is_on = getwinvar(2, '&list') @@ -4278,6 +4438,8 @@ function vim.fn.globpath(path, expr, nosuf, list, allinks) end --- @return 0|1 function vim.fn.has(feature) end +--- Lua: Prefer `dict[key] ~= nil`. +--- --- Checks whether |Dictionary| {dict} has an entry with key --- {key}. Returns TRUE if so, FALSE otherwise. The {key} --- argument is a string. @@ -4345,6 +4507,8 @@ function vim.fn.haslocaldir(winnr, tabnr) end function vim.fn.hasmapto(what, mode, abbr) end --- @deprecated +--- Lua: Prefer |nvim_get_hl()|. +--- --- Obsolete name for |hlID()|. --- --- @param name string @@ -4352,6 +4516,8 @@ function vim.fn.hasmapto(what, mode, abbr) end function vim.fn.highlightID(name) end --- @deprecated +--- Lua: Prefer |nvim_get_hl()|. +--- --- Obsolete name for |hlexists()|. --- --- @param name string @@ -4452,6 +4618,8 @@ function vim.fn.histget(history, index) end --- @return integer function vim.fn.histnr(history) end +--- Lua: Prefer |nvim_get_hl()|. +--- --- Returns the numeric ID of the highlight group with name --- {name}. When the highlight group doesn't exist, zero is --- returned. @@ -4465,6 +4633,8 @@ function vim.fn.histnr(history) end --- @return integer function vim.fn.hlID(name) end +--- Lua: Prefer |nvim_get_hl()|. +--- --- Checks whether a highlight group called {name} exists. --- Returns TRUE if the group has been defined in some way. Not --- necessarily when highlighting has been defined for it, it may @@ -4474,12 +4644,16 @@ function vim.fn.hlID(name) end --- @return 0|1 function vim.fn.hlexists(name) end +--- Lua: Prefer |uv.os_gethostname()|. +--- --- Returns the hostname of the machine on which the Nvim server --- (not the UI client) is currently running. --- --- @return string function vim.fn.hostname() end +--- Lua: Prefer |vim.iconv()|. +--- --- Converts the encoding of {string} from {from} to {to}. --- Returns the converted String. --- When the conversion completely fails an empty string is @@ -4529,6 +4703,8 @@ function vim.fn.id(expr) end --- @return integer function vim.fn.indent(lnum) end +--- Lua: Prefer |vim.iter()| with |Iter:enumerate()| and |Iter:find()| for lists; result is 1-based, and `start`, `ic`, and Blob semantics differ. +--- --- Find {expr} in {object} and return its index. See --- |indexof()| for using a lambda to select the item. --- @@ -4563,6 +4739,8 @@ function vim.fn.indent(lnum) end --- @return integer function vim.fn.index(object, expr, start, ic) end +--- Lua: Prefer |vim.iter()| with |Iter:enumerate()| and |Iter:find()| for list predicates; result is 1-based, and `startidx` and Blob semantics differ. +--- --- Returns the index of an item in {object} where {expr} is --- v:true. {object} must be a |List| or a |Blob|. --- @@ -4607,6 +4785,8 @@ function vim.fn.index(object, expr, start, ic) end --- @return integer function vim.fn.indexof(object, expr, opts) end +--- Lua: Prefer |vim.ui.input()| for callback-based input. +--- --- --- @param prompt string --- @param text? string @@ -4614,6 +4794,8 @@ function vim.fn.indexof(object, expr, opts) end --- @return string function vim.fn.input(prompt, text, completion) end +--- Lua: Prefer |vim.ui.input()| for callback-based input. +--- --- Prompts the user to enter text on the command-line, and --- returns the text as a String. The {prompt} argument is either --- a prompt string, or a blank string (for no prompt). A '\n' @@ -4729,12 +4911,16 @@ function vim.fn.input(prompt, text, completion) end function vim.fn.input(opts) end --- @deprecated +--- Lua: Prefer |vim.ui.input()| for callback-based input. +--- --- Use |input()| instead. --- --- @param ... any --- @return any function vim.fn.inputdialog(...) end +--- Lua: Prefer |vim.ui.select()| for simple selection menus; callback, returned item, and out-of-range semantics differ. +--- --- Displays a list of strings and prompts the user to select --- one by entering a number. {textlist} must be a |List| of --- strings. Returns the number the user entered. @@ -4790,6 +4976,8 @@ function vim.fn.inputsave() end --- @return string function vim.fn.inputsecret(prompt, text) end +--- Lua: Prefer |table.insert()| for lists; blob insertion and negative indexes differ. +--- --- When {object} is a |List| or a |Blob| insert {item} at the start --- of it. --- @@ -4828,6 +5016,8 @@ function vim.fn.insert(object, item, idx) end --- @return any function vim.fn.interrupt() end +--- Lua: Prefer |bit.bnot()|. +--- --- Bitwise invert. The argument is converted to a number. A --- List, Dict or Float argument causes an error. Example: >vim --- let bits = invert(bits) @@ -4856,6 +5046,8 @@ function vim.fn.invert(expr) end --- @return 0|1 function vim.fn.isabsolutepath(path) end +--- Lua: Prefer |uv.fs_stat()| and check `type == "directory"`. +--- --- Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't --- exist or isn't a directory. {directory} is any expression, --- which is used as a String. @@ -4864,6 +5056,8 @@ function vim.fn.isabsolutepath(path) end --- @return 0|1 function vim.fn.isdirectory(directory) end +--- Lua: Prefer `expr == math.huge and 1 or expr == -math.huge and -1 or 0`. +--- --- Return 1 if {expr} is a positive infinity, or -1 a negative --- infinity, otherwise 0. >vim --- echo isinf(1.0 / 0.0) @@ -4892,6 +5086,8 @@ function vim.fn.isinf(expr) end --- @return 0|1 function vim.fn.islocked(expr) end +--- Lua: Prefer `expr ~= expr`. +--- --- Return |TRUE| if {expr} is a float with value NaN. >vim --- echo isnan(0.0 / 0.0) --- < 1 @@ -4900,6 +5096,8 @@ function vim.fn.islocked(expr) end --- @return 0|1 function vim.fn.isnan(expr) end +--- Lua: Prefer |pairs()| or |ipairs()|. +--- --- Return a |List| with all key/index and value pairs of {expr}. --- Each |List| item is a list with two items: --- - for a |Dict|: the key and the value @@ -4930,6 +5128,8 @@ function vim.fn.items(expr) end --- @return any function vim.fn.jobclose(...) end +--- Lua: Prefer |vim.system()| object `.pid`; |job-id| and channel semantics differ. +--- --- Return the PID (process id) of |job-id| {job}. --- --- @param job integer @@ -4947,13 +5147,15 @@ function vim.fn.jobpid(job) end function vim.fn.jobresize(job, width, height) end --- @deprecated +--- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ. +--- --- Obsolete name for |chansend()| --- --- @param ... any --- @return any function vim.fn.jobsend(...) end ---- Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`). +--- Lua: Prefer |vim.system()| for simple processes; |RPC|, PTY/term, streaming callbacks, and shell-string behavior differ. --- --- Spawns {cmd} as a job. --- If {cmd} is a List it runs directly (no 'shell'). @@ -5050,6 +5252,8 @@ function vim.fn.jobsend(...) end --- @return integer function vim.fn.jobstart(cmd, opts) end +--- Lua: Prefer |SystemObj:kill()| on a |vim.system()| object; |job-id| semantics differ. +--- --- Stop |job-id| {id} by sending SIGTERM to the job process. If --- the process does not terminate after a timeout then SIGKILL --- will be sent. When the job terminates its |on_exit| handler @@ -5063,6 +5267,8 @@ function vim.fn.jobstart(cmd, opts) end --- @return integer function vim.fn.jobstop(id) end +--- Lua: Prefer |SystemObj:wait()| on a |vim.system()| object; list input and status values differ. +--- --- Waits for jobs and their |on_exit| handlers to complete. --- --- {jobs} is a List of |job-id|s to wait for. @@ -5088,6 +5294,8 @@ function vim.fn.jobstop(id) end --- @return integer[] function vim.fn.jobwait(jobs, timeout) end +--- Lua: Prefer |table.concat()| for string lists; non-string values stringify differently. +--- --- Join the items in {list} together into one String. --- When {sep} is specified it is put in between the items. If --- {sep} is omitted a single space is used. @@ -5103,6 +5311,8 @@ function vim.fn.jobwait(jobs, timeout) end --- @return string function vim.fn.join(list, sep) end +--- Lua: Prefer |vim.json.decode()|. +--- --- Convert {expr} from JSON object. Accepts |readfile()|-style --- list as the input, as well as regular string. May output any --- Vim value. In the following cases it will output @@ -5121,6 +5331,8 @@ function vim.fn.join(list, sep) end --- @return any function vim.fn.json_decode(expr) end +--- Lua: Prefer |vim.json.encode()|. +--- --- Convert {expr} into a JSON string. Accepts --- |msgpack-special-dict| as the input. Will not convert --- |Funcref|s, mappings with non-string keys (can be created as @@ -5136,6 +5348,8 @@ function vim.fn.json_decode(expr) end --- @return string function vim.fn.json_encode(expr) end +--- Lua: Prefer |vim.tbl_keys()|. +--- --- Return a |List| with all the keys of {dict}. The |List| is in --- arbitrary order. Also see |items()| and |values()|. --- @@ -5159,6 +5373,8 @@ function vim.fn.keytrans(string) end --- @return any function vim.fn.last_buffer_nr() end +--- Lua: Prefer Lua `#` operator for strings and lists or `#vim.tbl_keys(expr)` for dicts. +--- --- Returns the length of the argument. --- When {expr} is a String or a Number the length in bytes is --- used, as with |strlen()|. @@ -5173,6 +5389,8 @@ function vim.fn.last_buffer_nr() end --- @return integer function vim.fn.len(expr) end +--- Lua: Prefer |package.loadlib()| or `ffi.load()`. +--- --- Call function {funcname} in the run-time library {libname} --- with single argument {argument}. --- This is useful to call functions in a library that you @@ -5221,6 +5439,8 @@ function vim.fn.len(expr) end --- @return any function vim.fn.libcall(libname, funcname, argument) end +--- Lua: Prefer |package.loadlib()| or `ffi.load()`. +--- --- Just like |libcall()|, but used for a function that returns an --- int instead of a string. --- Examples: >vim @@ -5235,6 +5455,8 @@ function vim.fn.libcall(libname, funcname, argument) end --- @return any function vim.fn.libcallnr(libname, funcname, argument) end +--- Lua: Prefer |nvim_win_get_cursor()| for "." or |nvim_buf_line_count()| for "$"; marks, lists, and other position expressions differ. +--- --- See |getpos()| for accepted positions. --- --- To get the column number use |col()|. To get both use @@ -5259,6 +5481,8 @@ function vim.fn.libcallnr(libname, funcname, argument) end --- @return integer function vim.fn.line(expr, winid) end +--- Lua: Prefer |nvim_buf_get_offset()| with `lnum - 1`; 'fileformat' and invalid-line semantics differ. +--- --- Return the byte count from the start of the buffer for line --- {lnum}. This includes the end-of-line character, depending on --- the 'fileformat' option for the current buffer. The first @@ -5318,12 +5542,16 @@ function vim.fn.list2blob(list) end --- @return string function vim.fn.list2str(list, utf8) end +--- Lua: Prefer |os.time()|. +--- --- Return the current time, measured as seconds since 1st Jan --- 1970. See also |strftime()|, |strptime()| and |getftime()|. --- --- @return integer function vim.fn.localtime() end +--- Lua: Prefer |math.log()|. +--- --- Return the natural logarithm (base e) of {expr} as a |Float|. --- {expr} must evaluate to a |Float| or a |Number| in the range --- (0, inf]. @@ -5338,6 +5566,8 @@ function vim.fn.localtime() end --- @return number function vim.fn.log(expr) end +--- Lua: Prefer |math.log10()|. +--- --- Return the logarithm of Float {expr} to base 10 as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -5351,6 +5581,8 @@ function vim.fn.log(expr) end --- @return number function vim.fn.log10(expr) end +--- Lua: Prefer |vim.tbl_map()| for array-like tables; dict, string, blob, and in-place behavior differ. +--- --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. --- When {expr1} is a |List| or |Dictionary|, replace each --- item in {expr1} with the result of evaluating {expr2}. @@ -5568,6 +5800,8 @@ function vim.fn.mapcheck(name, mode, abbr) end --- @return table[] function vim.fn.maplist(abbr) end +--- Lua: Prefer |vim.tbl_map()| for tables; string, blob, and `v:key` callback behavior differ. +--- --- Like |map()| but instead of replacing items in {expr1} a new --- List or Dictionary is created and returned. {expr1} remains --- unchanged. Items can still be changed by {expr2}, if you @@ -6100,6 +6334,8 @@ function vim.fn.matchstrlist(list, pat, dict) end --- @return table function vim.fn.matchstrpos(expr, pat, start, count) end +--- Lua: Prefer |math.max()| with `unpack(expr)` for lists; dict values and empty inputs need custom handling. +--- --- Return the maximum value of all items in {expr}. Example: >vim --- echo max([apples, pears, oranges]) --- @@ -6238,6 +6474,8 @@ function vim.fn.menu_get(path, modes) end --- @return any function vim.fn.menu_info(name, mode) end +--- Lua: Prefer |math.min()| with `unpack(expr)` for lists; dict values and empty inputs need custom handling. +--- --- Return the minimum value of all items in {expr}. Example: >vim --- echo min([apples, pears, oranges]) --- @@ -6251,6 +6489,8 @@ function vim.fn.menu_info(name, mode) end --- @return number function vim.fn.min(expr) end +--- Lua: Prefer |uv.fs_mkdir()| for simple directory creation; `"p"`, `"D"`, `"R"`, and return semantics differ. +--- --- Create directory {name}. --- --- When {flags} is present it must be a string. An empty string @@ -6295,6 +6535,8 @@ function vim.fn.min(expr) end --- @return integer function vim.fn.mkdir(name, flags, prot) end +--- Lua: Prefer |nvim_get_mode()|; use the `.mode` field. It always returns the full mode string, unlike |mode()| without a non-zero {expr}. +--- --- Return a string that indicates the current mode. --- If {expr} is supplied and it evaluates to a non-zero Number or --- a non-empty String (|non-zero-arg|), then the full mode is @@ -6352,6 +6594,8 @@ function vim.fn.mkdir(name, flags, prot) end --- @return any function vim.fn.mode(expr) end +--- Lua: Prefer |vim.mpack.encode()|; list wrapping, return shape, and special-dict semantics differ. +--- --- Convert a list of Vimscript objects to msgpack. Returned value is a --- |readfile()|-style list. When {type} contains "B", a |Blob| is --- returned instead. Example: >vim @@ -6375,6 +6619,8 @@ function vim.fn.mode(expr) end --- @return any function vim.fn.msgpackdump(list, type) end +--- Lua: Prefer |vim.mpack.decode()|; input and special-dict semantics differ. +--- --- Convert a |readfile()|-style list or a |Blob| to a list of --- Vimscript objects. --- Example: >vim @@ -6458,6 +6704,8 @@ function vim.fn.msgpackparse(data) end --- @return integer function vim.fn.nextnonblank(lnum) end +--- Lua: Prefer |string.char()|: only works with ASCII. +--- --- Return a string with a single character, which has the number --- value {expr}. Examples: >vim --- echo nr2char(64) " returns '\@' @@ -6477,6 +6725,8 @@ function vim.fn.nextnonblank(lnum) end --- @return string function vim.fn.nr2char(expr, utf8) end +--- Lua: Prefer |bit.bor()|. +--- --- Bitwise OR on the two arguments. The arguments are converted --- to a number. A List, Dict or Float argument causes an error. --- Also see `and()` and `xor()`. @@ -6529,6 +6779,8 @@ function vim.fn.pathshorten(path, len) end --- @return any function vim.fn.perleval(expr) end +--- Lua: Prefer |math.pow()|. +--- --- Return the power of {x} to the exponent {y} as a |Float|. --- {x} and {y} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. @@ -6565,6 +6817,8 @@ function vim.fn.preinserted() end --- @return integer function vim.fn.prevnonblank(lnum) end +--- Lua: Prefer |string.format()|. +--- --- Return a String with {fmt}, where "%" items are replaced by --- the formatted form of their respective arguments. Example: >vim --- echo printf("%4d: E%d %.30s", lnum, errno, msg) @@ -7054,6 +7308,8 @@ function vim.fn.pyeval(expr) end --- @return any function vim.fn.pyxeval(expr) end +--- Lua: Prefer |math.random()|. +--- --- Return a pseudo-random Number generated with an xoshiro128** --- algorithm using seed {expr}. The returned number is 32 bits, --- also on 64 bits systems, for consistency. @@ -7097,6 +7353,8 @@ function vim.fn.rand(expr) end --- @return any function vim.fn.range(expr, max, stride) end +--- Lua: Prefer |io.open()| with `:read("*a")` in binary mode for whole-file reads; offset, size, and Blob return differ. +--- --- Read file {fname} in binary mode and return a |Blob|. --- If {offset} is specified, read the file from the specified --- offset. If it is a negative value, it is used as an offset @@ -7126,6 +7384,8 @@ function vim.fn.range(expr, max, stride) end --- @return any function vim.fn.readblob(fname, offset, size) end +--- Lua: Prefer |vim.fs.dir()| as an iterator, then collect and filter results as needed. +--- --- Return a list with file and directory names in {directory}. --- You can also use |glob()| if you don't need to do complicated --- things, such as limiting the number of matches. @@ -7160,6 +7420,8 @@ function vim.fn.readblob(fname, offset, size) end --- @return any function vim.fn.readdir(directory, expr) end +--- Lua: Prefer |io.open()| with `:read("*a")`, then split lines as needed; `{type}`, `{max}`, and Blob return differ. +--- --- Read file {fname} and return a |List|, each line of the file --- as an item. Lines are broken at NL characters. Macintosh --- files separated with CR will result in a single long line @@ -7198,6 +7460,8 @@ function vim.fn.readdir(directory, expr) end --- @return string[] function vim.fn.readfile(fname, type, max) end +--- Lua: Prefer |Iter:fold()|. +--- --- {func} is called for every item in {object}, which can be a --- |String|, |List| or a |Blob|. {func} is called with two --- arguments: the result so far and current item. After @@ -7249,6 +7513,8 @@ function vim.fn.reltime() end --- @return any function vim.fn.reltime(start) end +--- Lua: Prefer |uv.hrtime()|. +--- --- Return an item that represents a time value. The item is a --- list with items that depend on the system. --- The item can be passed to |reltimestr()| to convert it to a @@ -7273,6 +7539,8 @@ function vim.fn.reltime(start) end --- @return any function vim.fn.reltime(start, end_) end +--- Lua: Prefer |uv.hrtime()| with `(finish - start) / 1e9` for elapsed seconds. +--- --- Return a Float that represents the time value of {time}. --- Unit of time is seconds. --- Example: @@ -7304,6 +7572,8 @@ function vim.fn.reltimefloat(time) end --- @return any function vim.fn.reltimestr(time) end +--- Lua: Prefer |table.remove()|. +--- --- @param list any --- @param idx integer --- @return any @@ -7352,6 +7622,8 @@ function vim.fn.remove(blob, idx) end --- @return any function vim.fn.remove(blob, idx, end_) end +--- Lua: Prefer `local value = dict[key]; dict[key] = nil` for dicts; missing-key behavior differs. +--- --- Remove the entry from {dict} with key {key} and return it. --- Example: >vim --- echo "removed " .. remove(dict, "one") @@ -7363,6 +7635,8 @@ function vim.fn.remove(blob, idx, end_) end --- @return any function vim.fn.remove(dict, key) end +--- Lua: Prefer |uv.fs_rename()| or |os.rename()|. +--- --- Rename the file by the name {from} to the name {to}. This --- should also work to move files across file systems. The --- result is a Number, which is 0 if the file was renamed @@ -7375,6 +7649,8 @@ function vim.fn.remove(dict, key) end --- @return integer function vim.fn.rename(from, to) end +--- Lua: Prefer |string.rep()| for strings; lists need manual repetition. +--- --- Repeat {expr} {count} times and return the concatenated --- result. Example: >vim --- let separator = repeat('-', 80) @@ -7405,6 +7681,8 @@ vim.fn['repeat'] = function(expr, count) end --- @return string function vim.fn.resolve(filename) end +--- Lua: Prefer `vim.iter(list):rev():totable()` for lists; strings, blobs, and in-place behavior differ. +--- --- Reverse the order of items in {object}. {object} can be a --- |List|, a |Blob| or a |String|. For a List and a Blob the --- items are reversed in-place and {object} is returned. @@ -7420,6 +7698,8 @@ function vim.fn.resolve(filename) end --- @return T[] function vim.fn.reverse(object) end +--- Lua: Prefer `expr >= 0 and math.floor(expr + 0.5) or math.ceil(expr - 0.5)` for half-away-from-zero rounding. +--- --- Round off {expr} to the nearest integral value and return it --- as a |Float|. If {expr} lies halfway between two integral --- values, then use the larger one (away from zero). @@ -7437,6 +7717,8 @@ function vim.fn.reverse(object) end --- @return number function vim.fn.round(expr) end +--- Lua: Prefer |vim.rpcnotify()|. +--- --- Sends {event} to {channel} via |RPC| and returns immediately. --- If {channel} is 0, the event is broadcast to all channels. --- Example: >vim @@ -7449,6 +7731,8 @@ function vim.fn.round(expr) end --- @return integer function vim.fn.rpcnotify(channel, event, ...) end +--- Lua: Prefer |vim.rpcrequest()|. +--- --- Sends a request to {channel} to invoke {method} via --- |RPC| and blocks until a response is received. --- Example: >vim @@ -8059,6 +8343,8 @@ function vim.fn.serverstart(address) end --- @return integer function vim.fn.serverstop(address) end +--- Lua: Prefer |nvim_buf_set_lines()|. +--- --- Set line {lnum} to {text} in buffer {buf}. This works like --- |setline()| for the specified buffer. --- @@ -8089,6 +8375,8 @@ function vim.fn.serverstop(address) end --- @return integer function vim.fn.setbufline(buf, lnum, text) end +--- Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|. +--- --- Set option or local variable {varname} in buffer {buf} to --- {val}. --- This also works for a global or local window option, but it @@ -8145,6 +8433,8 @@ function vim.fn.setbufvar(buf, varname, val) end --- @return any function vim.fn.setcellwidths(list) end +--- Lua: Prefer |nvim_win_set_cursor()| or |nvim_buf_set_mark()| with |vim.str_byteindex()|; special positions, `off`, and `curswant` differ. +--- --- Same as |setpos()| but uses the specified column number as the --- character index instead of the byte index in the line. --- @@ -8212,12 +8502,16 @@ function vim.fn.setcmdline(str, pos) end --- @return any function vim.fn.setcmdpos(pos) end +--- Lua: Prefer |nvim_win_set_cursor()| with |vim.str_byteindex()|; `off`, return values, and special line forms differ. +--- --- @param lnum integer|string --- @param col? integer --- @param off? integer --- @return any function vim.fn.setcursorcharpos(lnum, col, off) end +--- Lua: Prefer |nvim_win_set_cursor()| with |vim.str_byteindex()|; list shape, `off`, and return values differ. +--- --- Same as |cursor()| but uses the specified column number as the --- character index instead of the byte index in the line. --- @@ -8234,6 +8528,8 @@ function vim.fn.setcursorcharpos(lnum, col, off) end --- @return any function vim.fn.setcursorcharpos(list) end +--- Lua: Prefer |vim.env|. +--- --- Set environment variable {name} to {val}. Example: >vim --- call setenv('HOME', '/home/myhome') --- @@ -8245,6 +8541,8 @@ function vim.fn.setcursorcharpos(list) end --- @return any function vim.fn.setenv(name, val) end +--- Lua: Prefer |uv.fs_chmod()|. +--- --- Set the file permissions for {fname} to {mode}. --- {mode} must be a string with 9 characters. It is of the form --- "rwxrwxrwx", where each group of "rwx" flags represent, in @@ -8266,6 +8564,8 @@ function vim.fn.setenv(name, val) end --- @return any function vim.fn.setfperm(fname, mode) end +--- Lua: Prefer |nvim_set_current_line()| or |nvim_buf_set_lines()|. +--- --- Set line {lnum} of the current buffer to {text}. To insert --- lines use |append()|. To set lines in another buffer use --- |setbufline()|. @@ -8332,6 +8632,8 @@ function vim.fn.setloclist(nr, list, action, what) end --- @return any function vim.fn.setmatches(list, win) end +--- Lua: Prefer |nvim_win_set_cursor()| for "." or |nvim_buf_set_mark()| for marks; special positions, `off`, and `curswant` differ. +--- --- Set the position for String {expr}. Possible values: --- . the cursor --- 'x mark x @@ -8573,6 +8875,8 @@ function vim.fn.setqflist(list, action, what) end --- @return any function vim.fn.setreg(regname, value, options) end +--- Lua: Prefer |nvim_tabpage_set_var()| or |vim.t|. +--- --- Set tab-local variable {varname} to {val} in tab page {tabnr}. --- |t:var| --- The {varname} argument is a string. @@ -8586,6 +8890,8 @@ function vim.fn.setreg(regname, value, options) end --- @return any function vim.fn.settabvar(tabnr, varname, val) end +--- Lua: Prefer |nvim_win_set_var()| or |vim.w| after resolving {tabnr} and {winnr} to a winid; option names use |nvim_set_option_value()|. +--- --- Set option or local variable {varname} in window {winnr} to --- {val}. --- Tabs are numbered starting with one. For the current tabpage @@ -8647,6 +8953,8 @@ function vim.fn.settabwinvar(tabnr, winnr, varname, val) end --- @return any function vim.fn.settagstack(nr, dict, action) end +--- Lua: Prefer |nvim_win_set_var()| or |vim.w| after resolving {nr} to a winid; option names use |nvim_set_option_value()|. +--- --- Like |settabwinvar()| for the current tab page. --- Examples: >vim --- call setwinvar(1, "&list", 0) @@ -8667,6 +8975,8 @@ function vim.fn.setwinvar(nr, varname, val) end --- @return string function vim.fn.sha256(expr) end +--- Lua: Prefer |vim.system()| with list args to avoid shell escaping; `:!` and {special} semantics differ. +--- --- Escape {string} for use as a shell command argument. --- --- On Windows when 'shellslash' is not set, encloses {string} in @@ -8703,6 +9013,8 @@ function vim.fn.sha256(expr) end --- @return string function vim.fn.shellescape(string, special) end +--- Lua: Prefer |vim.bo| for simple cases: `vim.bo.shiftwidth > 0 and vim.bo.shiftwidth or vim.bo.tabstop`; `{col}` and 'vartabstop' semantics differ. +--- --- Returns the effective value of 'shiftwidth'. This is the --- 'shiftwidth' value unless it is zero, in which case it is the --- 'tabstop' value. To be backwards compatible in indent @@ -9136,6 +9448,8 @@ function vim.fn.sign_unplace(group, dict) end --- @return (0|-1)[] function vim.fn.sign_unplacelist(list) end +--- Lua: Prefer |vim.fs.normalize()|; `~`/$VAR expansion and leading `./` or trailing `/` handling differ. +--- --- Simplify the file name as much as possible without changing --- the meaning. Shortcuts (on MS-Windows) or symbolic links (on --- Unix) are not resolved. If the first path component in @@ -9156,6 +9470,8 @@ function vim.fn.sign_unplacelist(list) end --- @return string function vim.fn.simplify(filename) end +--- Lua: Prefer |math.sin()|. +--- --- Return the sine of {expr}, measured in radians, as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. @@ -9169,6 +9485,8 @@ function vim.fn.simplify(filename) end --- @return number function vim.fn.sin(expr) end +--- Lua: Prefer |math.sinh()|. +--- --- Return the hyperbolic sine of {expr} as a |Float| in the range --- [-inf, inf]. --- {expr} must evaluate to a |Float| or a |Number|. @@ -9228,6 +9546,8 @@ function vim.fn.slice(expr, start, end_) end --- @return any function vim.fn.sockconnect(mode, address, opts) end +--- Lua: Prefer |table.sort()| with a custom comparator; it is not stable and Vim's `i`/`l`/`n`/`N`/`f` modes differ. +--- --- Sort the items in {list} in-place. Returns {list}. --- --- If you want a list to remain unmodified make a copy first: >vim @@ -9318,6 +9638,8 @@ function vim.fn.sort(list, how, dict) end --- @return string function vim.fn.soundfold(word) end +--- Lua: Prefer |vim.spell.check()| for string input; it returns all matches with positions, not just the first one or cursor-moving behavior. +--- --- Without argument: The result is the badly spelled word under --- or after the cursor. The cursor is moved to the start of the --- bad word. When no bad word is found in the cursor line the @@ -9371,6 +9693,8 @@ function vim.fn.spellbadword(sentence) end --- @return string[] function vim.fn.spellsuggest(word, max, capital) end +--- Lua: Prefer |vim.split()|. +--- --- Make a |List| out of {string}. When {pattern} is omitted or --- empty each white space separated sequence of characters --- becomes an item. @@ -9401,6 +9725,8 @@ function vim.fn.spellsuggest(word, max, capital) end --- @return string[] function vim.fn.split(string, pattern, keepempty) end +--- Lua: Prefer |math.sqrt()|. +--- --- Return the non-negative square root of Float {expr} as a --- |Float|. --- {expr} must evaluate to a |Float| or a |Number|. When {expr} @@ -9417,6 +9743,8 @@ function vim.fn.split(string, pattern, keepempty) end --- @return any function vim.fn.sqrt(expr) end +--- Lua: Prefer |math.randomseed()|. +--- --- Initialize seed used by |rand()|: --- - If {expr} is not given, seed values are initialized by --- reading from /dev/urandom, if possible, or using time(NULL) @@ -9527,6 +9855,8 @@ function vim.fn.stdpath(what) end --- @return string[] function vim.fn.stdpath(what) end +--- Lua: Prefer |tonumber()| for simple numbers; quoted digits, hex forms, and trailing text differ. +--- --- Convert String {string} to a Float. This mostly works the --- same as when using a floating point number in an expression, --- see |floating-point-format|. But it's a bit more permissive. @@ -9567,6 +9897,8 @@ function vim.fn.str2float(string, quoted) end --- @return any function vim.fn.str2list(string, utf8) end +--- Lua: Prefer |tonumber()| for simple numbers; quoted digits, base prefixes, and trailing text differ. +--- --- Convert string {string} to a number. --- {base} is the conversion base, it can be 2, 8, 10 or 16. --- When {quoted} is present and non-zero then embedded single @@ -9623,6 +9955,8 @@ function vim.fn.strcharlen(string) end --- @return string function vim.fn.strcharpart(src, start, len, skipcc) end +--- Lua: Prefer |vim.str_utfindex()| for codepoint counts; `skipcc` handling differs. +--- --- Returns the number of characters in String {string}. --- When {skipcc} is omitted or zero, composing characters are --- counted separately. @@ -9655,6 +9989,8 @@ function vim.fn.strcharpart(src, start, len, skipcc) end --- @return integer function vim.fn.strchars(string, skipcc) end +--- Lua: Prefer |nvim_strwidth()| when `{col}` is 0; Tab expansion and window-option semantics differ. +--- --- Returns the number of display cells String {string} occupies --- on the screen when it starts at {col} (first column is zero). --- Returns zero on error. @@ -9676,6 +10012,8 @@ function vim.fn.strchars(string, skipcc) end --- @return integer function vim.fn.strdisplaywidth(string, col) end +--- Lua: Prefer |os.date()|. +--- --- Formats a date and time String specified by {format}. The --- given {time} is used, or the current time if no time is given. --- The {format} depends on your system, this is not portable! @@ -9710,6 +10048,8 @@ function vim.fn.strftime(format, time) end --- @return integer function vim.fn.strgetchar(str, index) end +--- Lua: Prefer |string.find()| with `plain = true` and `start + 1`, then subtract 1; missing matches return nil instead of -1. +--- --- Returns the byte index of the first occurrence of {needle} --- in {haystack}. --- If {start} is specified, the search starts at index {start}. @@ -9734,6 +10074,8 @@ function vim.fn.strgetchar(str, index) end --- @return integer function vim.fn.stridx(haystack, needle, start) end +--- Lua: Prefer |vim.inspect()| for tables, or |tostring()| for scalars. +--- --- Converts {expr} to a String. If {expr} is a Number, Float, --- String, Blob or a composition of them, the result can be --- parsed back with |eval()|. @@ -9764,6 +10106,8 @@ function vim.fn.stridx(haystack, needle, start) end --- @return string function vim.fn.string(expr) end +--- Lua: Prefer |string.len()|. +--- --- Returns the length of String {string} in bytes. --- If the argument is a Number it is first converted to a String. --- For other types an error is given and zero is returned. @@ -9775,6 +10119,8 @@ function vim.fn.string(expr) end --- @return integer function vim.fn.strlen(string) end +--- Lua: Prefer |string.sub()| for byte slices; negative `start` and the `chars` flag differ. +--- --- Gets a substring from {src}, starting from byte {start}, with --- byte length {len}. Returns empty string on error. --- @@ -9833,6 +10179,8 @@ function vim.fn.strpart(src, start, len, chars) end --- @return integer function vim.fn.strptime(format, timestring) end +--- Lua: Prefer |string.find()| in a loop with `plain = true`, then subtract 1; empty-needle and missing-match semantics differ. +--- --- Returns the byte index of the last occurrence of {needle} --- in {haystack}. --- When {start} is specified, matches beyond this index are @@ -9869,6 +10217,8 @@ function vim.fn.strridx(haystack, needle, start) end --- @return string function vim.fn.strtrans(string) end +--- Lua: Prefer |vim.str_utfindex()| with `"utf-16"`; `countcc = false` semantics differ. +--- --- Returns the number of UTF-16 code units in String {string} --- (after converting it to UTF-16). --- @@ -9893,6 +10243,8 @@ function vim.fn.strtrans(string) end --- @return integer function vim.fn.strutf16len(string, countcc) end +--- Lua: Prefer |nvim_strwidth()|. +--- --- Returns the number of display cells String {string} occupies. --- A Tab character is counted as one cell, alternatively use --- |strdisplaywidth()|. @@ -9943,6 +10295,8 @@ function vim.fn.submatch(nr, list) end --- @return string|string[] function vim.fn.submatch(nr, list) end +--- Lua: Prefer |string.gsub()| for common substitutions; Vim patterns, flags, and replacement semantics differ. +--- --- Performs string substitution. Returns a copy of {string} --- in which the first match of {pat} is replaced with {sub}. --- When {flags} is "g", all matches of {pat} in {string} are @@ -10190,7 +10544,7 @@ function vim.fn.synconcealed(lnum, col) end --- @return integer[] function vim.fn.synstack(lnum, col) end ---- Lua: Prefer |vim.system()|. +--- Lua: Prefer `vim.system(...):wait().stdout` for string output; string commands use the shell in Vimscript, not by default in Lua. --- --- Gets the output of {cmd} as a |string| (|systemlist()| returns --- a |List|) and sets |v:shell_error| to the error code. @@ -10243,6 +10597,8 @@ function vim.fn.synstack(lnum, col) end --- @return string function vim.fn.system(cmd, input) end +--- Lua: Prefer `vim.system(...):wait().stdout` split into lines; string commands use the shell in Vimscript, not by default in Lua. +--- --- Same as |system()|, but returns a |List| with lines (parts of --- output separated by NL) with NULs transformed into NLs. --- Output is the same as |readfile()| will output with {binary} @@ -10262,6 +10618,8 @@ function vim.fn.system(cmd, input) end --- @return string[] function vim.fn.systemlist(cmd, input, keepempty) end +--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()|; invalid tabpages error instead of returning 0. +--- --- Returns a |List| of buffer numbers, one for each window in --- the specified tab page. --- {arg} specifies the number of the tab page to be used. When @@ -10278,6 +10636,8 @@ function vim.fn.systemlist(cmd, input, keepempty) end --- @return any function vim.fn.tabpagebuflist(arg) end +--- Lua: Prefer |nvim_tabpage_get_number()| with |nvim_get_current_tabpage()| for the current tab, or `#vim.api.nvim_list_tabpages()` for "$"; "#" differs. +--- --- Returns the number of the current tab page. The first tab --- page has number 1. --- @@ -10295,6 +10655,8 @@ function vim.fn.tabpagebuflist(arg) end --- @return integer function vim.fn.tabpagenr(arg) end +--- Lua: Prefer |nvim_win_get_number()| with |nvim_tabpage_get_win()| for the current window, or the length of |nvim_tabpage_list_wins()| for "$"; "#" and invalid-tab behavior differ. +--- --- Like |winnr()| but for tab page {tabarg}. --- {tabarg} specifies the number of tab page to be used. --- {arg} is used like with |winnr()|: @@ -10365,6 +10727,8 @@ function vim.fn.tagfiles() end --- @return any function vim.fn.taglist(expr, filename) end +--- Lua: Prefer |math.tan()|. +--- --- Return the tangent of {expr}, measured in radians, as a |Float| --- in the range [-inf, inf]. --- {expr} must evaluate to a |Float| or a |Number|. @@ -10379,6 +10743,8 @@ function vim.fn.taglist(expr, filename) end --- @return number function vim.fn.tan(expr) end +--- Lua: Prefer |math.tanh()|. +--- --- Return the hyperbolic tangent of {expr} as a |Float| in the --- range [-1, 1]. --- {expr} must evaluate to a |Float| or a |Number|. @@ -10393,6 +10759,8 @@ function vim.fn.tan(expr) end --- @return number function vim.fn.tanh(expr) end +--- Lua: Prefer |os.tmpname()| for a temporary name; Nvim's |tempdir| and nonexistence are not guaranteed. +--- --- Generates a (non-existent) filename located in the Nvim root --- |tempdir|. Scripts can use the filename as a temporary file. --- Example: >vim @@ -10446,6 +10814,8 @@ function vim.fn.timer_info(id) end --- @return any function vim.fn.timer_pause(timer, paused) end +--- Lua: Prefer |vim.defer_fn()| for one-shot timers, or |uv.new_timer()| for repeating timers; callback and handle semantics differ. +--- --- Create a timer and return the timer ID. --- --- {time} is the waiting time in milliseconds. This is the @@ -10481,6 +10851,8 @@ function vim.fn.timer_pause(timer, paused) end --- @return any function vim.fn.timer_start(time, callback, options) end +--- Lua: Prefer |uv.timer_stop()| and |uv.close()| on a stored |uv.new_timer()| handle; timer IDs differ. +--- --- Stop a timer. The timer callback will no longer be invoked. --- {timer} is an ID returned by |timer_start()|, thus it must be a --- Number. If {timer} does not exist there is no error. @@ -10496,6 +10868,8 @@ function vim.fn.timer_stop(timer) end --- @return any function vim.fn.timer_stopall() end +--- Lua: Prefer |string.lower()|. +--- --- Converts a String to lowercase (like applying |gu|). --- Returns empty string on error. --- @@ -10503,6 +10877,8 @@ function vim.fn.timer_stopall() end --- @return string function vim.fn.tolower(expr) end +--- Lua: Prefer |string.upper()|. +--- --- Converts a String to uppercase (like applying |gU|). --- Returns empty string on error. --- @@ -10529,6 +10905,8 @@ function vim.fn.toupper(expr) end --- @return string function vim.fn.tr(src, fromstr, tostr) end +--- Lua: Prefer |vim.trim()|. +--- --- Return {text} as a String where any character in {mask} is --- removed from the beginning and/or end of {text}. --- @@ -10562,6 +10940,8 @@ function vim.fn.tr(src, fromstr, tostr) end --- @return string function vim.fn.trim(text, mask, dir) end +--- Lua: Prefer |math.modf()| (first return value). +--- --- Return the largest integral value with magnitude less than or --- equal to {expr} as a |Float| (truncate towards zero). --- {expr} must evaluate to a |Float| or a |Number|. @@ -10578,6 +10958,8 @@ function vim.fn.trim(text, mask, dir) end --- @return integer function vim.fn.trunc(expr) end +--- Lua: Prefer |lua-type()| for most Lua type checks; Vim type IDs differ. +--- --- Returns the type of {expr} as a Number. --- Instead of using the number directly, it is better to use the --- v:t_ variable that has the value: @@ -10688,6 +11070,8 @@ function vim.fn.undotree(buf) end --- @return any[]|0 function vim.fn.uniq(list, func, dict) end +--- Lua: Prefer |vim.str_utfindex()| with `"utf-16"` and `strict_indexing = false`; `countcc` and `charidx` semantics differ. +--- --- Same as |charidx()| but returns the UTF-16 code unit index of --- the byte at {idx} in {string} (after converting it to UTF-16). --- @@ -10723,6 +11107,8 @@ function vim.fn.uniq(list, func, dict) end --- @return integer function vim.fn.utf16idx(string, idx, countcc, charidx) end +--- Lua: Prefer |vim.tbl_values()|. +--- --- Return a |List| with all the values of {dict}. The |List| is --- in arbitrary order. Also see |items()| and |keys()|. --- Returns zero if {dict} is not a |Dict|. @@ -10832,6 +11218,8 @@ function vim.fn.virtcol2col(winid, lnum, col) end --- @return string function vim.fn.visualmode(expr) end +--- Lua: Prefer |vim.wait()|. +--- --- Waits until {condition} evaluates to |TRUE|, where {condition} --- is a |Funcref| or |string| containing an expression. --- @@ -10889,6 +11277,8 @@ function vim.fn.wildmenumode() end --- @return number function vim.fn.wildtrigger() end +--- Lua: Prefer |nvim_win_call()|. +--- --- Like `execute()` but in the context of window {id}. --- The window will temporarily be made the current window, --- without triggering autocommands or changing directory. When @@ -10908,6 +11298,8 @@ function vim.fn.wildtrigger() end --- @return any function vim.fn.win_execute(id, command, silent) end +--- Lua: Prefer |nvim_list_wins()| with |nvim_win_get_buf()|. +--- --- Returns a |List| with |window-ID|s for windows that contain --- buffer {bufnr}. When there is none the list is empty. --- @@ -10915,6 +11307,8 @@ function vim.fn.win_execute(id, command, silent) end --- @return integer[] function vim.fn.win_findbuf(bufnr) end +--- Lua: Prefer |nvim_get_current_win()| when omitted, or |nvim_tabpage_list_wins()| with |nvim_win_get_number()| after resolving {tab}; invalid windows return 0 in Vimscript. +--- --- Get the |window-ID| for the specified window. --- When {win} is missing use the current window. --- With {win} this is the window number. The top window has @@ -10949,6 +11343,8 @@ function vim.fn.win_getid(win, tab) end --- @return 'autocmd'|'command'|''|'loclist'|'popup'|'preview'|'quickfix'|'unknown' function vim.fn.win_gettype(nr) end +--- Lua: Prefer |nvim_set_current_win()|; invalid IDs error instead of returning FALSE. +--- --- Go to window with ID {expr}. This may also change the current --- tabpage. --- Return TRUE if successful, FALSE if the window cannot be @@ -10958,6 +11354,8 @@ function vim.fn.win_gettype(nr) end --- @return 0|1 function vim.fn.win_gotoid(expr) end +--- Lua: Prefer |nvim_win_get_tabpage()| and |nvim_win_get_number()| for valid windows; invalid IDs error instead of returning `[0, 0]`. +--- --- Return a list with the tab number and window number of window --- with ID {expr}: [tabnr, winnr]. --- Return [0, 0] if the window cannot be found. @@ -10966,6 +11364,8 @@ function vim.fn.win_gotoid(expr) end --- @return any function vim.fn.win_id2tabwin(expr) end +--- Lua: Prefer |nvim_win_get_number()| for valid windows; windows outside the current tabpage and invalid IDs differ. +--- --- Return the window number of window with ID {expr}. --- Return 0 if the window cannot be found in the current tabpage. --- @@ -11008,6 +11408,8 @@ function vim.fn.win_move_separator(nr, offset) end --- @return any function vim.fn.win_move_statusline(nr, offset) end +--- Lua: Prefer |nvim_win_get_position()| and add 1 to row and col; invalid-window semantics differ. +--- --- Return the screen position of window {nr} as a list with two --- numbers: [row, col]. The first window always has position --- [1, 1], unless there is a tabline, then it is [2, 1]. @@ -11044,6 +11446,8 @@ function vim.fn.win_screenpos(nr) end --- @return any function vim.fn.win_splitmove(nr, target, options) end +--- Lua: Prefer |nvim_win_get_buf()|. +--- --- Returns the buffer number associated with window {nr}. --- {nr} can be the window number or the |window-ID|. --- When {nr} is zero, the number of the buffer in the current @@ -11134,6 +11538,8 @@ function vim.fn.winlayout(tabnr) end --- @return integer function vim.fn.winline() end +--- Lua: Prefer |nvim_win_get_number()| with |nvim_get_current_win()| for the current window, or |nvim_tabpage_list_wins()| with |nvim_get_current_tabpage()| for "$"; "#", motion args, and hidden windows differ. +--- --- Returns the number of the current window. The top window has --- number 1. Returns zero for a hidden or non |focusable| --- window, unless it is the current window. @@ -11328,6 +11734,8 @@ function vim.fn.wordcount() end --- @return any function vim.fn.writefile(data, fname, flags) end +--- Lua: Prefer |bit.bxor()|. +--- --- Bitwise XOR on the two arguments. The arguments are converted --- to a number. A List, Dict or Float argument causes an error. --- Also see `and()` and `or()`. diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua index e55c8aeca7..5cc9e6a99c 100755 --- a/src/gen/gen_eval_files.lua +++ b/src/gen/gen_eval_files.lua @@ -251,6 +251,76 @@ local function norm_text(x, special) ) end +--- @param items string[] +--- @param conjunction string +--- @return string +--- Example: "foo, bar, or baz" +local function join_with_conjunction(items, conjunction) + if #items == 0 then + return '' + elseif #items == 1 then + return items[1] + elseif #items == 2 then + return items[1] .. ' ' .. conjunction .. ' ' .. items[2] + end + + local parts = {} --- @type string[] + for i = 1, #items - 1 do + parts[#parts + 1] = items[i] + end + return table.concat(parts, ', ') .. ', ' .. conjunction .. ' ' .. items[#items] +end + +--- @param fun vim.EvalFn +--- @return string? +--- Example: "Lua: Prefer |math.abs()|." +local function see_lua_text(fun) + if not fun.see_lua or fun.see_lua == false then + return + end + + return 'Lua: Prefer ' .. join_with_conjunction(fun.see_lua, 'or') .. '.' +end + +local VIMDOC_PARAGRAPH_PREFIX = '\t\t' +local VIMDOC_PARAGRAPH_INDENT = 16 -- Two tabs in rendered vimdoc. + +--- @param text string +--- @return string +--- Example: "\t\tLua: Prefer |math.abs()|." +local function tab_indent_vimdoc(text) + return VIMDOC_PARAGRAPH_PREFIX + .. util + .md_to_vimdoc(text, 0, 0, TEXT_WIDTH - VIMDOC_PARAGRAPH_INDENT) + :gsub('\n', '\n' .. VIMDOC_PARAGRAPH_PREFIX) +end + +--- @param fun vim.EvalFn +--- @param write fun(line: string) +--- Example first line: "--- Lua: Prefer |math.abs()|." +local function render_eval_see_lua_meta(fun, write) + local text = see_lua_text(fun) + if not text then + return + end + + write('--- ' .. text) + write('---') +end + +--- @param fun vim.EvalFn +--- @param write fun(line: string) +--- Example first line: "\t\tLua: Prefer |math.abs()|." +local function render_eval_see_lua_doc(fun, write) + local text = see_lua_text(fun) + if not text then + return + end + + write(tab_indent_vimdoc(text)) + write('') +end + --- Generates LuaLS docstring for an API function. --- @param _f string --- @param fun vim.EvalFn @@ -394,6 +464,8 @@ local function render_eval_meta(f, fun, write) write('--- @deprecated') end + render_eval_see_lua_meta(fun, write) + local desc = fun.desc --[[@as string?]] if desc then @@ -474,6 +546,8 @@ local function render_eval_doc(f, fun, write) render_sig_and_tag(fun.name or f, not f:find('__%d+$'), fun, write) + render_eval_see_lua_doc(fun, write) + if not fun.desc then return end diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index f8cf01f8a3..84f0d7b91e 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -17,6 +17,10 @@ --- @field params [string, string, string][] --- @field notes? string[] --- @field see? string[] +--- +--- Recommended alternatives if calling from Lua. +--- `false` means there is no useful Lua replacement to suggest. +--- @field see_lua? string[]|false --- @field lua? false Do not render type information --- @field tags? string[] Extra tags --- @field data? string Used by gen_eval.lua @@ -52,6 +56,7 @@ M.funcs = { params = { { 'expr', 'number' } }, signature = 'abs({expr})', returns = 'number', + see_lua = { '|math.abs()|' }, }, acos = { args = 1, @@ -75,6 +80,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'acos({expr})', + see_lua = { '|math.acos()|' }, }, add = { args = 2, @@ -96,6 +102,7 @@ M.funcs = { returns = 'any', returns_desc = [=[Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|.]=], signature = 'add({object}, {expr})', + see_lua = { '|table.insert()| for lists and `..` for blobs' }, }, ['and'] = { args = 2, @@ -112,6 +119,7 @@ M.funcs = { params = { { 'expr', 'number' }, { 'expr', 'number' } }, returns = 'integer', signature = 'and({expr}, {expr})', + see_lua = { '|bit.band()|' }, }, api_info = { desc = [=[ @@ -150,6 +158,7 @@ M.funcs = { params = { { 'lnum', 'integer|string' }, { 'text', 'string|string[]' } }, returns = '0|1', signature = 'append({lnum}, {text})', + see_lua = { '|nvim_buf_set_lines()|' }, }, appendbufline = { args = 3, @@ -180,6 +189,7 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'text', 'string' } }, returns = '0|1', signature = 'appendbufline({buf}, {lnum}, {text})', + see_lua = { '|nvim_buf_set_lines()|' }, }, argc = { args = { 0, 1 }, @@ -275,6 +285,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'number', signature = 'asin({expr})', + see_lua = { '|math.asin()|' }, }, assert_beeps = { args = 1, @@ -316,6 +327,7 @@ M.funcs = { params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, returns = '0|1', signature = 'assert_equal({expected}, {actual} [, {msg}])', + see_lua = { '|assert()| with |vim.deep_equal()|' }, }, assert_equalfile = { args = { 2, 3 }, @@ -353,6 +365,7 @@ M.funcs = { params = { { 'error', 'any' }, { 'msg', 'any' } }, returns = '0|1', signature = 'assert_exception({error} [, {msg}])', + see_lua = false, }, assert_fails = { args = { 1, 5 }, @@ -402,6 +415,7 @@ M.funcs = { }, returns = '0|1', signature = 'assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])', + see_lua = false, }, assert_false = { args = { 1, 2 }, @@ -422,6 +436,7 @@ M.funcs = { params = { { 'actual', 'any' }, { 'msg', 'any' } }, returns = '0|1', signature = 'assert_false({actual} [, {msg}])', + see_lua = { '|assert()|' }, }, assert_inrange = { args = { 3, 4 }, @@ -443,6 +458,7 @@ M.funcs = { }, returns = '0|1', signature = 'assert_inrange({lower}, {upper}, {actual} [, {msg}])', + see_lua = { '|assert()|' }, }, assert_match = { args = { 2, 3 }, @@ -545,6 +561,7 @@ M.funcs = { params = { { 'actual', 'any' }, { 'msg', 'string' } }, returns = '0|1', signature = 'assert_true({actual} [, {msg}])', + see_lua = { '|assert()|' }, }, atan = { args = 1, @@ -566,6 +583,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'atan({expr})', + see_lua = { '|math.atan()|' }, }, atan2 = { args = 2, @@ -587,6 +605,7 @@ M.funcs = { params = { { 'expr1', 'number' }, { 'expr2', 'number' } }, returns = 'number', signature = 'atan2({expr1}, {expr2})', + see_lua = { '|math.atan2()|' }, }, blob2list = { args = 1, @@ -604,6 +623,7 @@ M.funcs = { params = { { 'blob', 'any' } }, returns = 'any[]', signature = 'blob2list({blob})', + see_lua = false, }, browse = { args = 4, @@ -668,6 +688,7 @@ M.funcs = { params = { { 'name', 'string' } }, returns = 'integer', signature = 'bufadd({name})', + see_lua = false, }, bufexists = { args = 1, @@ -699,6 +720,7 @@ M.funcs = { params = { { 'buf', 'any' } }, returns = '0|1', signature = 'bufexists({buf})', + see_lua = { '|nvim_buf_is_valid()| after resolving {buf} to a bufnr' }, }, buffer_exists = { args = 1, @@ -712,6 +734,7 @@ M.funcs = { params = VARARGS, returns = '0|1', signature = 'buffer_exists({buf})', + see_lua = { '|nvim_buf_is_valid()| after resolving {buf} to a bufnr' }, }, buffer_name = { args = { 0, 1 }, @@ -725,6 +748,7 @@ M.funcs = { params = VARARGS, returns = 'string', signature = 'buffer_name([{buf}])', + see_lua = { '|nvim_buf_get_name()| after resolving {buf} to a bufnr' }, }, buffer_number = { args = { 0, 1 }, @@ -738,6 +762,9 @@ M.funcs = { params = VARARGS, returns = 'integer', signature = 'buffer_number([{buf} [, {create}]])', + see_lua = { + '|nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ', + }, }, buflisted = { args = 1, @@ -753,6 +780,7 @@ M.funcs = { params = { { 'buf', 'any' } }, returns = '0|1', signature = 'buflisted({buf})', + see_lua = { '|vim.bo| or |nvim_get_option_value()| after resolving {buf} to a bufnr' }, }, bufload = { args = 1, @@ -787,6 +815,7 @@ M.funcs = { params = { { 'buf', 'any' } }, returns = '0|1', signature = 'bufloaded({buf})', + see_lua = { '|nvim_buf_is_loaded()| after resolving {buf} to a bufnr' }, }, bufname = { args = { 0, 1 }, @@ -826,6 +855,7 @@ M.funcs = { params = { { 'buf', 'integer|string' } }, returns = 'string', signature = 'bufname([{buf}])', + see_lua = { '|nvim_buf_get_name()| after resolving {buf} to a bufnr' }, }, bufnr = { args = { 0, 2 }, @@ -853,6 +883,9 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'create', 'any' } }, returns = 'integer', signature = 'bufnr([{buf} [, {create}]])', + see_lua = { + '|nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ', + }, }, bufwinid = { args = 1, @@ -873,6 +906,9 @@ M.funcs = { params = { { 'buf', 'any' } }, returns = 'integer', signature = 'bufwinid({buf})', + see_lua = { + '|nvim_tabpage_list_wins()| with |nvim_win_get_buf()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ', + }, }, bufwinnr = { args = 1, @@ -893,6 +929,9 @@ M.funcs = { params = { { 'buf', 'any' } }, returns = 'integer', signature = 'bufwinnr({buf})', + see_lua = { + '|nvim_tabpage_list_wins()| with |nvim_win_get_buf()| and |nvim_win_get_number()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ', + }, }, byte2line = { args = 1, @@ -957,6 +996,9 @@ M.funcs = { params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } }, returns = 'integer', signature = 'byteidx({expr}, {nr} [, {utf16}])', + see_lua = { + '|vim.str_byteindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; composing characters and out-of-range semantics differ', + }, }, byteidxcomp = { args = { 2, 3 }, @@ -978,6 +1020,9 @@ M.funcs = { params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } }, returns = 'integer', signature = 'byteidxcomp({expr}, {nr} [, {utf16}])', + see_lua = { + '|vim.str_byteindex()| with `"utf-32"` or `"utf-16"` and `strict_indexing = false`', + }, }, call = { args = { 2, 3 }, @@ -997,6 +1042,7 @@ M.funcs = { returns = 'any', signature = 'call({func}, {arglist} [, {dict}])', tags = { 'E699' }, + see_lua = false, }, ceil = { args = 1, @@ -1021,6 +1067,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'ceil({expr})', + see_lua = { '|math.ceil()|' }, }, chanclose = { args = { 1, 2 }, @@ -1078,6 +1125,7 @@ M.funcs = { params = { { 'id', 'number' }, { 'data', 'string|string[]' } }, returns = '0|1', signature = 'chansend({id}, {data})', + see_lua = { '|nvim_chan_send()| for string data; list input and the return value differ' }, }, char2nr = { args = { 1, 2 }, @@ -1103,6 +1151,7 @@ M.funcs = { params = { { 'string', 'string' }, { 'utf8', 'any' } }, returns = '0|1', signature = 'char2nr({string} [, {utf8}])', + see_lua = { '|string.byte()|: only works with ASCII' }, }, charclass = { args = 1, @@ -1141,6 +1190,9 @@ M.funcs = { params = { { 'expr', 'string|any[]' }, { 'winid', 'integer' } }, returns = 'integer', signature = 'charcol({expr} [, {winid}])', + see_lua = { + '|nvim_win_get_cursor()| with |vim.str_utfindex()| for ".", or |nvim_get_current_line()| with |vim.str_utfindex()| for "$"; marks, list input, and window semantics differ', + }, }, charidx = { args = { 2, 4 }, @@ -1188,6 +1240,9 @@ M.funcs = { }, returns = 'integer', signature = 'charidx({string}, {idx} [, {countcc} [, {utf16}]])', + see_lua = { + '|vim.str_utfindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; `countcc = false` and out-of-range semantics differ', + }, }, chdir = { args = { 1, 2 }, @@ -1227,6 +1282,9 @@ M.funcs = { params = { { 'dir', 'string' }, { 'scope', 'string' } }, returns = 'string', signature = 'chdir({dir} [, {scope}])', + see_lua = { + '|nvim_set_current_dir()| for the global directory; tab-local, window-local, and return semantics differ', + }, }, cindent = { args = 1, @@ -1245,6 +1303,7 @@ M.funcs = { params = { { 'lnum', 'integer|string' } }, returns = 'integer', signature = 'cindent({lnum})', + see_lua = false, }, clearmatches = { args = { 0, 1 }, @@ -1335,6 +1394,9 @@ M.funcs = { params = { { 'expr', 'string|any[]' }, { 'winid', 'integer' } }, returns = 'integer', signature = 'col({expr} [, {winid}])', + see_lua = { + '|nvim_win_get_cursor()| for "." (add 1), or Lua `#` on |nvim_get_current_line()| for "$"; marks, list input, and `virtualedit` differ', + }, }, complete = { args = 2, @@ -1576,6 +1638,7 @@ M.funcs = { params = { { 'expr', 'T' } }, returns = 'T', signature = 'copy({expr})', + see_lua = { '|vim.deepcopy()|; deeper than Vimscript |copy()|' }, }, cos = { args = 1, @@ -1596,6 +1659,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'cos({expr})', + see_lua = { '|math.cos()|' }, }, cosh = { args = 1, @@ -1617,6 +1681,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'cosh({expr})', + see_lua = { '|math.cosh()|' }, }, count = { args = { 2, 4 }, @@ -1707,6 +1772,7 @@ M.funcs = { name = 'cursor', params = { { 'lnum', 'integer|string' }, { 'col', 'integer' }, { 'off', 'integer' } }, signature = 'cursor({lnum}, {col} [, {off}])', + see_lua = false, -- see cursor__1 }, cursor__1 = { args = { 1, 3 }, @@ -1747,6 +1813,9 @@ M.funcs = { name = 'cursor', params = { { 'list', 'integer[]' } }, signature = 'cursor({list})', + see_lua = { + '|nvim_win_set_cursor()| with `{lnum, col - 1}`; `off`, `curswant`, and failure semantics differ', + }, }, debugbreak = { args = { 1, 1 }, @@ -1764,6 +1833,9 @@ M.funcs = { name = 'debugbreak', params = { { 'pid', 'integer' } }, signature = 'debugbreak({pid})', + see_lua = { + '|uv.kill()| with `"sigtrap"` (or `"sigint"` outside MS-Windows); exact semantics differ', + }, }, deepcopy = { args = { 1, 2 }, @@ -1795,13 +1867,12 @@ M.funcs = { params = { { 'expr', 'T' }, { 'noref', 'boolean' } }, returns = 'T', signature = 'deepcopy({expr} [, {noref}])', + see_lua = { '|vim.deepcopy()|' }, }, delete = { args = { 1, 2 }, base = 1, desc = [=[ - Lua: see |vim.fs.rm()|. - Without {flags} or with {flags} empty: Deletes the file by the name {fname}. @@ -1825,6 +1896,7 @@ M.funcs = { params = { { 'fname', 'string' }, { 'flags', 'string' } }, returns = 'integer', signature = 'delete({fname} [, {flags}])', + see_lua = { '|vim.fs.rm()|' }, }, deletebufline = { args = { 2, 3 }, @@ -1851,6 +1923,7 @@ M.funcs = { { 'last', 'integer|string' }, }, signature = 'deletebufline({buf}, {first} [, {last}])', + see_lua = { '|nvim_buf_set_lines()|' }, }, dictwatcheradd = { args = 3, @@ -1897,6 +1970,7 @@ M.funcs = { name = 'dictwatcheradd', params = { { 'dict', 'table' }, { 'pattern', 'string' }, { 'callback', 'function' } }, signature = 'dictwatcheradd({dict}, {pattern}, {callback})', + see_lua = false, }, dictwatcherdel = { args = 3, @@ -1908,6 +1982,7 @@ M.funcs = { name = 'dictwatcherdel', params = { { 'dict', 'any' }, { 'pattern', 'string' }, { 'callback', 'function' } }, signature = 'dictwatcherdel({dict}, {pattern}, {callback})', + see_lua = false, }, did_filetype = { desc = [=[ @@ -2078,6 +2153,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'integer', signature = 'empty({expr})', + see_lua = { 'plain Lua emptiness checks, or |vim.tbl_isempty()| for tables' }, }, environ = { desc = [=[ @@ -2094,6 +2170,7 @@ M.funcs = { name = 'environ', params = {}, signature = 'environ()', + see_lua = { '|uv.os_environ()| for the full environment table; |vim.env| for keyed access' }, }, escape = { args = 2, @@ -2127,6 +2204,7 @@ M.funcs = { name = 'eval', params = { { 'string', 'string' } }, signature = 'eval({string})', + see_lua = false, }, eventhandler = { desc = [=[ @@ -2222,6 +2300,7 @@ M.funcs = { }, returns = 'string', signature = 'execute({command} [, {silent}])', + see_lua = { '|nvim_exec()|', '|vim.cmd()|' }, }, exepath = { args = 1, @@ -2356,6 +2435,7 @@ M.funcs = { name = 'exp', params = { { 'expr', 'number' } }, signature = 'exp({expr})', + see_lua = { '|math.exp()|' }, }, expand = { args = { 1, 3 }, @@ -2547,6 +2627,9 @@ M.funcs = { name = 'extend', params = { { 'expr1', 'table' }, { 'expr2', 'table' }, { 'expr3', 'table' } }, signature = 'extend({expr1}, {expr2} [, {expr3}])', + see_lua = { + '|vim.list_extend()| for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ', + }, }, extendnew = { args = { 2, 3 }, @@ -2559,6 +2642,9 @@ M.funcs = { name = 'extendnew', params = { { 'expr1', 'table' }, { 'expr2', 'table' }, { 'expr3', 'table' } }, signature = 'extendnew({expr1}, {expr2} [, {expr3}])', + see_lua = { + '|vim.list_extend()| on a copy for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ', + }, }, feedkeys = { args = { 1, 2 }, @@ -2613,6 +2699,7 @@ M.funcs = { name = 'feedkeys', params = { { 'string', 'string' }, { 'mode', 'string' } }, signature = 'feedkeys({string} [, {mode}])', + see_lua = { '|nvim_feedkeys()|' }, }, file_readable = { args = 1, @@ -2625,6 +2712,7 @@ M.funcs = { name = 'file_readable', params = { { 'file', 'string' } }, signature = 'file_readable({file})', + see_lua = { '|uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories' }, }, filecopy = { args = 2, @@ -2642,6 +2730,7 @@ M.funcs = { params = { { 'from', 'string' }, { 'to', 'string' } }, returns = '0|1', signature = 'filecopy({from}, {to})', + see_lua = { '|uv.fs_copyfile()| with `{ excl = true }`; return semantics differ' }, }, filereadable = { args = 1, @@ -2669,6 +2758,7 @@ M.funcs = { params = { { 'file', 'string' } }, returns = '0|1', signature = 'filereadable({file})', + see_lua = { '|uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories' }, }, filewritable = { args = 1, @@ -2685,6 +2775,9 @@ M.funcs = { params = { { 'file', 'string' } }, returns = '0|1', signature = 'filewritable({file})', + see_lua = { + '|uv.fs_access()| with `"W"` and |uv.fs_stat()| if you need Vim\'s `2` return for directories', + }, }, filter = { args = 2, @@ -2746,6 +2839,7 @@ M.funcs = { name = 'filter', params = { { 'expr1', 'string|table' }, { 'expr2', 'string|function' } }, signature = 'filter({expr1}, {expr2})', + see_lua = { '|vim.tbl_filter()| for lists; dicts, strings, and blobs differ' }, }, finddir = { args = { 1, 3 }, @@ -2773,6 +2867,9 @@ M.funcs = { params = { { 'name', 'string' }, { 'path', 'string' }, { 'count', 'integer' } }, returns = 'string|string[]', signature = 'finddir({name} [, {path} [, {count}]])', + see_lua = { + "|vim.fs.find()| with `type = 'directory'`; `path`, `count`, and return semantics differ", + }, }, findfile = { args = { 1, 3 }, @@ -2790,6 +2887,9 @@ M.funcs = { params = { { 'name', 'string' }, { 'path', 'string' }, { 'count', 'integer' } }, returns = 'string|string[]', signature = 'findfile({name} [, {path} [, {count}]])', + see_lua = { + "|vim.fs.find()|; `path`, `count`, return semantics, and |'suffixesadd'| handling differ", + }, }, flatten = { args = { 1, 2 }, @@ -2818,6 +2918,9 @@ M.funcs = { params = { { 'list', 'any[]' }, { 'maxdepth', 'integer' } }, returns = 'any[]|0', signature = 'flatten({list} [, {maxdepth}])', + see_lua = { + '`vim.iter(list):flatten():totable()` for a new flattened list; in-place updates and `maxdepth` differ', + }, }, flattennew = { args = { 1, 2 }, @@ -2829,6 +2932,9 @@ M.funcs = { params = { { 'list', 'any[]' }, { 'maxdepth', 'integer' } }, returns = 'any[]|0', signature = 'flattennew({list} [, {maxdepth}])', + see_lua = { + '`vim.iter(list):flatten():totable()` for a new flattened list; `maxdepth` differs', + }, }, float2nr = { args = 1, @@ -2859,6 +2965,7 @@ M.funcs = { name = 'float2nr', params = { { 'expr', 'number' } }, signature = 'float2nr({expr})', + see_lua = { '|math.modf()| (first return value)' }, }, floor = { args = 1, @@ -2881,6 +2988,7 @@ M.funcs = { name = 'floor', params = { { 'expr', 'number' } }, signature = 'floor({expr})', + see_lua = { '|math.floor()|' }, }, fmod = { args = 2, @@ -2905,6 +3013,7 @@ M.funcs = { name = 'fmod', params = { { 'expr1', 'number' }, { 'expr2', 'number' } }, signature = 'fmod({expr1}, {expr2})', + see_lua = { '|math.fmod()|' }, }, fnameescape = { args = 1, @@ -2932,6 +3041,9 @@ M.funcs = { params = { { 'string', 'string' } }, returns = 'string', signature = 'fnameescape({string})', + see_lua = { + '|nvim_cmd()| or |vim.cmd()| with structured arguments to avoid Ex filename escaping', + }, }, fnamemodify = { args = 2, @@ -2959,6 +3071,9 @@ M.funcs = { params = { { 'fname', 'string' }, { 'mods', 'string' } }, returns = 'string', signature = 'fnamemodify({fname}, {mods})', + see_lua = { + '|vim.fs.dirname()|, |vim.fs.basename()|, |vim.fs.abspath()|, and |vim.fs.normalize()| for common path modifiers; modifier coverage differs', + }, }, foldclosed = { args = 1, @@ -3096,6 +3211,7 @@ M.funcs = { params = { { 'expr1', 'string|table' }, { 'expr2', 'string|function' } }, returns = 'string|table', signature = 'foreach({expr1}, {expr2})', + see_lua = { '|pairs()|', '|ipairs()|' }, }, foreground = { args = 0, @@ -3142,6 +3258,7 @@ M.funcs = { name = 'funcref', params = { { 'name', 'string' }, { 'arglist', 'any' }, { 'dict', 'any' } }, signature = 'funcref({name} [, {arglist}] [, {dict}])', + see_lua = false, }, ['function'] = { args = { 1, 3 }, @@ -3233,6 +3350,7 @@ M.funcs = { params = { { 'name', 'string' }, { 'arglist', 'any' }, { 'dict', 'any' } }, signature = 'function({name} [, {arglist}] [, {dict}])', tags = { 'partial', 'E700', 'E923' }, + see_lua = false, }, garbagecollect = { args = { 0, 1 }, @@ -3259,6 +3377,7 @@ M.funcs = { name = 'garbagecollect', params = { { 'atexit', 'boolean' } }, signature = 'garbagecollect([{atexit}])', + see_lua = false, }, get = { args = { 2, 3 }, @@ -3272,6 +3391,7 @@ M.funcs = { params = { { 'list', 'any[]' }, { 'idx', 'integer' }, { 'default', 'any' } }, signature = 'get({list}, {idx} [, {default}])', tags = { 'get()-list' }, + see_lua = false, }, get__1 = { args = { 2, 3 }, @@ -3285,6 +3405,7 @@ M.funcs = { params = { { 'blob', 'string' }, { 'idx', 'integer' }, { 'default', 'any' } }, signature = 'get({blob}, {idx} [, {default}])', tags = { 'get()-blob' }, + see_lua = false, }, get__2 = { args = { 2, 3 }, @@ -3301,6 +3422,7 @@ M.funcs = { params = { { 'dict', 'table' }, { 'key', 'string' }, { 'default', 'any' } }, signature = 'get({dict}, {key} [, {default}])', tags = { 'get()-dict' }, + see_lua = false, }, get__3 = { args = { 2, 3 }, @@ -3332,6 +3454,7 @@ M.funcs = { returns = 'any', signature = 'get({func}, {what})', tags = { 'get()-func' }, + see_lua = false, }, getbufinfo = { args = { 0, 1 }, @@ -3451,6 +3574,7 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'end', 'integer' } }, returns = 'string[]', signature = 'getbufline({buf}, {lnum} [, {end}])', + see_lua = { '|nvim_buf_get_lines()|' }, }, getbufoneline = { args = 2, @@ -3463,6 +3587,7 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' } }, signature = 'getbufoneline({buf}, {lnum})', returns = 'string', + see_lua = { '|nvim_buf_get_lines()|' }, }, getbufvar = { args = { 2, 3 }, @@ -3492,6 +3617,9 @@ M.funcs = { name = 'getbufvar', params = { { 'buf', 'integer|string' }, { 'varname', 'string' }, { 'def', 'any' } }, signature = 'getbufvar({buf}, {varname} [, {def}])', + see_lua = { + '|nvim_buf_get_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_get_option_value()| or |vim.bo|', + }, }, getcellwidths = { desc = [=[ @@ -3966,6 +4094,9 @@ M.funcs = { params = { { 'winid', 'integer' } }, returns = '[integer, integer, integer, integer, integer]', signature = 'getcurpos([{winid}])', + see_lua = { + '|nvim_win_get_cursor()|; return shape, 0-based column, and `curswant`/invalid-window semantics differ', + }, }, getcursorcharpos = { args = { 0, 1 }, @@ -4011,6 +4142,9 @@ M.funcs = { params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } }, returns = 'string', signature = 'getcwd([{winnr} [, {tabnr}]])', + see_lua = { + '|uv.cwd()| for the global working directory; tab-local and window-local scopes differ', + }, }, getenv = { args = 1, @@ -4029,6 +4163,7 @@ M.funcs = { params = { { 'name', 'string' } }, returns = 'string', signature = 'getenv({name})', + see_lua = { '|vim.env|' }, }, getfontname = { args = { 0, 1 }, @@ -4073,6 +4208,7 @@ M.funcs = { params = { { 'fname', 'string' } }, returns = 'string', signature = 'getfperm({fname})', + see_lua = { '|uv.fs_stat()|' }, }, getfsize = { args = 1, @@ -4090,6 +4226,7 @@ M.funcs = { params = { { 'fname', 'string' } }, returns = 'integer', signature = 'getfsize({fname})', + see_lua = { '|uv.fs_stat()|' }, }, getftime = { args = 1, @@ -4107,6 +4244,7 @@ M.funcs = { params = { { 'fname', 'string' } }, returns = 'integer', signature = 'getftime({fname})', + see_lua = { '|uv.fs_stat()|' }, }, getftype = { args = 1, @@ -4137,6 +4275,7 @@ M.funcs = { params = { { 'fname', 'string' } }, returns = "'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other'", signature = 'getftype({fname})', + see_lua = { '|uv.fs_stat()|' }, }, getjumplist = { args = { 0, 2 }, @@ -4166,6 +4305,9 @@ M.funcs = { params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } }, signature = 'getjumplist([{winnr} [, {tabnr}]])', returns = 'vim.fn.getjumplist.ret', + see_lua = { + '|nvim_get_context()| for current jump history; window/tab arguments and return shape differ', + }, }, getline = { args = { 1, 2 }, @@ -4199,6 +4341,7 @@ M.funcs = { params = { { 'lnum', 'integer|string' }, { 'end', 'nil|false' } }, signature = 'getline({lnum} [, {end}])', returns = 'string', + see_lua = { '|nvim_get_current_line()|', '|nvim_buf_get_lines()|' }, }, getline__1 = { args = { 2 }, @@ -4206,6 +4349,7 @@ M.funcs = { name = 'getline', params = { { 'lnum', 'integer|string' }, { 'end', 'true|number|string|table' } }, returns = 'string|string[]', + see_lua = { '|nvim_get_current_line()|', '|nvim_buf_get_lines()|' }, }, getloclist = { args = { 1, 2 }, @@ -4359,6 +4503,7 @@ M.funcs = { params = {}, returns = 'integer', signature = 'getpid()', + see_lua = { '|uv.os_getpid()|' }, }, getpos = { args = 1, @@ -4429,6 +4574,9 @@ M.funcs = { params = { { 'expr', 'string' } }, returns = '[integer, integer, integer, integer]', signature = 'getpos({expr})', + see_lua = { + '|nvim_win_get_cursor()| for "." or |nvim_buf_get_mark()| for marks; return shape, `off`, and special-position semantics differ', + }, }, getqflist = { args = { 0, 1 }, @@ -4812,6 +4960,7 @@ M.funcs = { params = {}, returns = 'table[]', signature = 'getstacktrace()', + see_lua = { '|debug.traceback()|' }, }, gettabinfo = { args = { 0, 1 }, @@ -4851,6 +5000,7 @@ M.funcs = { name = 'gettabvar', params = { { 'tabnr', 'integer' }, { 'varname', 'string' }, { 'def', 'any' } }, signature = 'gettabvar({tabnr}, {varname} [, {def}])', + see_lua = { '|nvim_tabpage_get_var()|', '|vim.t|' }, }, gettabwinvar = { args = { 3, 4 }, @@ -4890,6 +5040,9 @@ M.funcs = { { 'def', 'any' }, }, signature = 'gettabwinvar({tabnr}, {winnr}, {varname} [, {def}])', + see_lua = { + '|nvim_win_get_var()| or |vim.w| after resolving {tabnr} and {winnr} to a winid; option names use |nvim_get_option_value()| or |vim.wo|', + }, }, gettagstack = { args = { 0, 1 }, @@ -5056,6 +5209,9 @@ M.funcs = { name = 'getwinvar', params = { { 'winnr', 'integer' }, { 'varname', 'string' }, { 'def', 'any' } }, signature = 'getwinvar({winnr}, {varname} [, {def}])', + see_lua = { + '|nvim_win_get_var()| or |vim.w| after resolving {winnr}; option names use |nvim_get_option_value()| or |vim.wo|', + }, }, glob = { args = { 1, 4 }, @@ -5272,6 +5428,7 @@ M.funcs = { params = { { 'dict', 'table' }, { 'key', 'string' } }, returns = '0|1', signature = 'has_key({dict}, {key})', + see_lua = { '`dict[key] ~= nil`' }, }, haslocaldir = { args = { 0, 2 }, @@ -5349,6 +5506,7 @@ M.funcs = { func = 'f_hlID', params = { { 'name', 'string' } }, signature = 'highlightID({name})', + see_lua = { '|nvim_get_hl()|' }, }, highlight_exists = { args = 1, @@ -5360,6 +5518,7 @@ M.funcs = { func = 'f_hlexists', params = { { 'name', 'string' } }, signature = 'highlight_exists({name})', + see_lua = { '|nvim_get_hl()|' }, }, histadd = { args = 2, @@ -5491,6 +5650,7 @@ M.funcs = { params = { { 'name', 'string' } }, returns = 'integer', signature = 'hlID({name})', + see_lua = { '|nvim_get_hl()|' }, }, hlexists = { args = 1, @@ -5506,6 +5666,7 @@ M.funcs = { params = { { 'name', 'string' } }, returns = '0|1', signature = 'hlexists({name})', + see_lua = { '|nvim_get_hl()|' }, }, hostname = { desc = [=[ @@ -5518,6 +5679,7 @@ M.funcs = { params = {}, returns = 'string', signature = 'hostname()', + see_lua = { '|uv.os_gethostname()|' }, }, iconv = { args = 3, @@ -5540,6 +5702,7 @@ M.funcs = { params = { { 'string', 'string' }, { 'from', 'string' }, { 'to', 'string' } }, returns = 'string', signature = 'iconv({string}, {from}, {to})', + see_lua = { '|vim.iconv()|' }, }, id = { args = 1, @@ -5564,6 +5727,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'string', signature = 'id({expr})', + see_lua = false, }, indent = { args = 1, @@ -5619,6 +5783,9 @@ M.funcs = { params = { { 'object', 'any' }, { 'expr', 'any' }, { 'start', 'integer' }, { 'ic', 'boolean' } }, returns = 'integer', signature = 'index({object}, {expr} [, {start} [, {ic}]])', + see_lua = { + '|vim.iter()| with |Iter:enumerate()| and |Iter:find()| for lists; result is 1-based, and `start`, `ic`, and Blob semantics differ', + }, }, indexof = { args = { 2, 3 }, @@ -5667,6 +5834,9 @@ M.funcs = { params = { { 'object', 'any' }, { 'expr', 'any' }, { 'opts', 'table' } }, returns = 'integer', signature = 'indexof({object}, {expr} [, {opts}])', + see_lua = { + '|vim.iter()| with |Iter:enumerate()| and |Iter:find()| for list predicates; result is 1-based, and `startidx` and Blob semantics differ', + }, }, input = { args = { 1, 3 }, @@ -5676,6 +5846,7 @@ M.funcs = { params = { { 'prompt', 'string' }, { 'text', 'string' }, { 'completion', 'string' } }, returns = 'string', signature = 'input({prompt} [, {text} [, {completion}]])', + see_lua = { '|vim.ui.input()| for callback-based input' }, }, input__1 = { args = { 1, 3 }, @@ -5796,6 +5967,7 @@ M.funcs = { params = { { 'opts', 'table' } }, returns = 'string', signature = 'input({opts})', + see_lua = { '|vim.ui.input()| for callback-based input' }, }, inputdialog = { args = { 1, 3 }, @@ -5806,6 +5978,7 @@ M.funcs = { ]=], params = VARARGS, signature = 'input(...)', + see_lua = { '|vim.ui.input()| for callback-based input' }, }, inputlist = { args = 1, @@ -5831,6 +6004,9 @@ M.funcs = { name = 'inputlist', params = { { 'textlist', 'string[]' } }, signature = 'inputlist({textlist})', + see_lua = { + '|vim.ui.select()| for simple selection menus; callback, returned item, and out-of-range semantics differ', + }, }, inputrestore = { desc = [=[ @@ -5903,6 +6079,7 @@ M.funcs = { name = 'insert', params = { { 'object', 'any' }, { 'item', 'any' }, { 'idx', 'integer' } }, signature = 'insert({object}, {item} [, {idx}])', + see_lua = { '|table.insert()| for lists; blob insertion and negative indexes differ' }, }, interrupt = { args = 0, @@ -5923,6 +6100,7 @@ M.funcs = { name = 'interrupt', params = {}, signature = 'interrupt()', + see_lua = false, }, invert = { args = 1, @@ -5937,6 +6115,7 @@ M.funcs = { params = { { 'expr', 'integer' } }, returns = 'integer', signature = 'invert({expr})', + see_lua = { '|bit.bnot()|' }, }, isabsolutepath = { args = 1, @@ -5977,6 +6156,7 @@ M.funcs = { params = { { 'directory', 'string' } }, returns = '0|1', signature = 'isdirectory({directory})', + see_lua = { '|uv.fs_stat()| and check `type == "directory"`' }, }, isinf = { args = 1, @@ -5994,6 +6174,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = '1|0|-1', signature = 'isinf({expr})', + see_lua = { '`expr == math.huge and 1 or expr == -math.huge and -1 or 0`' }, }, islocked = { args = 1, @@ -6018,6 +6199,7 @@ M.funcs = { returns = '0|1', signature = 'islocked({expr})', tags = { 'E786' }, + see_lua = false, }, isnan = { args = 1, @@ -6032,6 +6214,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = '0|1', signature = 'isnan({expr})', + see_lua = { '`expr ~= expr`' }, }, items = { args = 1, @@ -6059,6 +6242,7 @@ M.funcs = { name = 'items', params = { { 'expr', 'table|string' } }, signature = 'items({expr})', + see_lua = { '|pairs()|', '|ipairs()|' }, }, jobclose = { args = { 1, 2 }, @@ -6079,6 +6263,7 @@ M.funcs = { params = { { 'job', 'integer' } }, returns = 'integer', signature = 'jobpid({job})', + see_lua = { '|vim.system()| object `.pid`; |job-id| and channel semantics differ' }, }, jobresize = { args = 3, @@ -6100,12 +6285,11 @@ M.funcs = { func = 'f_chansend', params = VARARGS, signature = 'jobsend({id}, {data})', + see_lua = { '|nvim_chan_send()| for string data; list input and the return value differ' }, }, jobstart = { args = { 1, 2 }, desc = [=[ - Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`). - Spawns {cmd} as a job. If {cmd} is a List it runs directly (no 'shell'). If {cmd} is a String it runs in the 'shell', like this: >vim @@ -6200,6 +6384,9 @@ M.funcs = { params = { { 'cmd', 'string|string[]' }, { 'opts', 'table' } }, returns = 'integer', signature = 'jobstart({cmd} [, {opts}])', + see_lua = { + '|vim.system()| for simple processes; |RPC|, PTY/term, streaming callbacks, and shell-string behavior differ', + }, }, jobstop = { args = 1, @@ -6217,6 +6404,7 @@ M.funcs = { params = { { 'id', 'integer' } }, returns = 'integer', signature = 'jobstop({id})', + see_lua = { '|SystemObj:kill()| on a |vim.system()| object; |job-id| semantics differ' }, }, jobwait = { args = { 1, 2 }, @@ -6245,6 +6433,9 @@ M.funcs = { params = { { 'jobs', 'integer[]' }, { 'timeout', 'integer' } }, returns = 'integer[]', signature = 'jobwait({jobs} [, {timeout}])', + see_lua = { + '|SystemObj:wait()| on a |vim.system()| object; list input and status values differ', + }, }, join = { args = { 1, 2 }, @@ -6265,6 +6456,7 @@ M.funcs = { params = { { 'list', 'any[]' }, { 'sep', 'string' } }, returns = 'string', signature = 'join({list} [, {sep}])', + see_lua = { '|table.concat()| for string lists; non-string values stringify differently' }, }, json_decode = { args = 1, @@ -6288,6 +6480,7 @@ M.funcs = { name = 'json_decode', params = { { 'expr', 'any' } }, signature = 'json_decode({expr})', + see_lua = { '|vim.json.decode()|' }, }, json_encode = { args = 1, @@ -6309,6 +6502,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'string', signature = 'json_encode({expr})', + see_lua = { '|vim.json.encode()|' }, }, keys = { args = 1, @@ -6322,6 +6516,7 @@ M.funcs = { params = { { 'dict', 'table' } }, returns = 'string[]', signature = 'keys({dict})', + see_lua = { '|vim.tbl_keys()|' }, }, keytrans = { args = 1, @@ -6367,6 +6562,7 @@ M.funcs = { returns = 'integer', signature = 'len({expr})', tags = { 'E701' }, + see_lua = { 'Lua `#` operator for strings and lists', '`#vim.tbl_keys(expr)` for dicts' }, }, libcall = { args = 3, @@ -6418,6 +6614,7 @@ M.funcs = { params = { { 'libname', 'string' }, { 'funcname', 'string' }, { 'argument', 'any' } }, signature = 'libcall({libname}, {funcname}, {argument})', tags = { 'E364', 'E368' }, + see_lua = { '|package.loadlib()|', '`ffi.load()`' }, }, libcallnr = { args = 3, @@ -6434,6 +6631,7 @@ M.funcs = { name = 'libcallnr', params = { { 'libname', 'string' }, { 'funcname', 'string' }, { 'argument', 'any' } }, signature = 'libcallnr({libname}, {funcname}, {argument})', + see_lua = { '|package.loadlib()|', '`ffi.load()`' }, }, line = { args = { 1, 2 }, @@ -6463,6 +6661,9 @@ M.funcs = { params = { { 'expr', 'string|integer[]' }, { 'winid', 'integer' } }, returns = 'integer', signature = 'line({expr} [, {winid}])', + see_lua = { + '|nvim_win_get_cursor()| for "." or |nvim_buf_line_count()| for "$"; marks, lists, and other position expressions differ', + }, }, line2byte = { args = 1, @@ -6485,6 +6686,9 @@ M.funcs = { params = { { 'lnum', 'integer|string' } }, returns = 'integer', signature = 'line2byte({lnum})', + see_lua = { + "|nvim_buf_get_offset()| with `lnum - 1`; 'fileformat' and invalid-line semantics differ", + }, }, lispindent = { args = 1, @@ -6520,6 +6724,7 @@ M.funcs = { params = { { 'list', 'any[]' } }, returns = 'string', signature = 'list2blob({list})', + see_lua = false, }, list2str = { args = { 1, 2 }, @@ -6545,6 +6750,7 @@ M.funcs = { params = { { 'list', 'any[]' }, { 'utf8', 'boolean' } }, returns = 'string', signature = 'list2str({list} [, {utf8}])', + see_lua = false, }, localtime = { desc = [=[ @@ -6555,6 +6761,7 @@ M.funcs = { params = {}, returns = 'integer', signature = 'localtime()', + see_lua = { '|os.time()|' }, }, log = { args = 1, @@ -6576,6 +6783,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'log({expr})', + see_lua = { '|math.log()|' }, }, log10 = { args = 1, @@ -6596,6 +6804,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'log10({expr})', + see_lua = { '|math.log10()|' }, }, luaeval = { args = { 1, 2 }, @@ -6611,6 +6820,7 @@ M.funcs = { name = 'luaeval', params = { { 'expr', 'string' }, { 'expr', 'any[]' } }, signature = 'luaeval({expr} [, {expr}])', + see_lua = { 'plain Lua expressions and values directly' }, }, map = { args = 2, @@ -6673,6 +6883,9 @@ M.funcs = { name = 'map', params = { { 'expr1', 'string|table|any[]' }, { 'expr2', 'string|function' } }, signature = 'map({expr1}, {expr2})', + see_lua = { + '|vim.tbl_map()| for array-like tables; dict, string, blob, and in-place behavior differ', + }, }, maparg = { args = { 1, 4 }, @@ -6865,6 +7078,9 @@ M.funcs = { name = 'mapnew', params = { { 'expr1', 'any' }, { 'expr2', 'any' } }, signature = 'mapnew({expr1}, {expr2})', + see_lua = { + '|vim.tbl_map()| for tables; string, blob, and `v:key` callback behavior differ', + }, }, mapset = { args = { 1, 3 }, @@ -7495,6 +7711,9 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'number', signature = 'max({expr})', + see_lua = { + '|math.max()| with `unpack(expr)` for lists; dict values and empty inputs need custom handling', + }, }, menu_get = { args = { 1, 2 }, @@ -7644,6 +7863,9 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'number', signature = 'min({expr})', + see_lua = { + '|math.min()| with `unpack(expr)` for lists; dict values and empty inputs need custom handling', + }, }, mkdir = { args = { 1, 3 }, @@ -7693,6 +7915,9 @@ M.funcs = { returns = 'integer', signature = 'mkdir({name} [, {flags} [, {prot}]])', tags = { 'E739' }, + see_lua = { + '|uv.fs_mkdir()| for simple directory creation; `"p"`, `"D"`, `"R"`, and return semantics differ', + }, }, mode = { args = { 0, 1 }, @@ -7755,6 +7980,9 @@ M.funcs = { name = 'mode', params = { { 'expr', 'any' } }, signature = 'mode([{expr}])', + see_lua = { + '|nvim_get_mode()|; use the `.mode` field. It always returns the full mode string, unlike |mode()| without a non-zero {expr}', + }, }, msgpackdump = { args = { 1, 2 }, @@ -7780,6 +8008,9 @@ M.funcs = { name = 'msgpackdump', params = { { 'list', 'any' }, { 'type', 'any' } }, signature = 'msgpackdump({list} [, {type}])', + see_lua = { + '|vim.mpack.encode()|; list wrapping, return shape, and special-dict semantics differ', + }, }, msgpackparse = { args = 1, @@ -7854,6 +8085,7 @@ M.funcs = { name = 'msgpackparse', params = { { 'data', 'any' } }, signature = 'msgpackparse({data})', + see_lua = { '|vim.mpack.decode()|; input and special-dict semantics differ' }, }, nextnonblank = { args = 1, @@ -7896,6 +8128,7 @@ M.funcs = { params = { { 'expr', 'integer' }, { 'utf8', 'boolean' } }, returns = 'string', signature = 'nr2char({expr} [, {utf8}])', + see_lua = { '|string.char()|: only works with ASCII' }, }, nvim_api__ = { args = 1, @@ -7916,6 +8149,7 @@ M.funcs = { params = VARARGS, signature = 'nvim_...({...})', tags = { 'E5555', 'eval-api' }, + see_lua = { '|vim.api|' }, }, ['or'] = { args = 2, @@ -7935,6 +8169,7 @@ M.funcs = { name = 'or', params = { { 'expr', 'number' }, { 'expr', 'number' } }, signature = 'or({expr}, {expr})', + see_lua = { '|bit.bor()|' }, }, pathshorten = { args = { 1, 2 }, @@ -8002,6 +8237,7 @@ M.funcs = { params = { { 'x', 'number' }, { 'y', 'number' } }, returns = 'number', signature = 'pow({x}, {y})', + see_lua = { '|math.pow()|' }, }, preinserted = { desc = [=[ @@ -8365,6 +8601,7 @@ M.funcs = { params = { { 'fmt', 'string' }, { 'expr1', 'any' } }, signature = 'printf({fmt}, {expr1} ...)', returns = 'string', + see_lua = { '|string.format()|' }, }, prompt_appendbuf = { args = 2, @@ -8597,6 +8834,7 @@ M.funcs = { name = 'rand', params = { { 'expr', 'number' } }, signature = 'rand([{expr}])', + see_lua = { '|math.random()|' }, }, range = { args = { 1, 3 }, @@ -8655,6 +8893,9 @@ M.funcs = { name = 'readblob', params = { { 'fname', 'string' }, { 'offset', 'integer' }, { 'size', 'integer' } }, signature = 'readblob({fname} [, {offset} [, {size}]])', + see_lua = { + '|io.open()| with `:read("*a")` in binary mode for whole-file reads; offset, size, and Blob return differ', + }, }, readdir = { args = { 1, 2 }, @@ -8693,6 +8934,7 @@ M.funcs = { name = 'readdir', params = { { 'directory', 'string' }, { 'expr', 'integer|string|fun(name: string): integer' } }, signature = 'readdir({directory} [, {expr}])', + see_lua = { '|vim.fs.dir()| as an iterator, then collect and filter results as needed' }, }, readfile = { args = { 1, 3 }, @@ -8735,6 +8977,9 @@ M.funcs = { params = { { 'fname', 'string' }, { 'type', 'string' }, { 'max', 'integer' } }, returns = 'string[]', signature = 'readfile({fname} [, {type} [, {max}]])', + see_lua = { + '|io.open()| with `:read("*a")`, then split lines as needed; `{type}`, `{max}`, and Blob return differ', + }, }, reduce = { args = { 2, 3 }, @@ -8767,6 +9012,7 @@ M.funcs = { }, returns = 'T', signature = 'reduce({object}, {func} [, {initial}])', + see_lua = { '|Iter:fold()|' }, }, reg_executing = { desc = [=[ @@ -8840,6 +9086,7 @@ M.funcs = { name = 'reltime', params = { { 'start', 'any' }, { 'end', 'any' } }, signature = 'reltime({start}, {end})', + see_lua = { '|uv.hrtime()|' }, }, reltimefloat = { args = 1, @@ -8860,6 +9107,7 @@ M.funcs = { name = 'reltimefloat', params = { { 'time', 'any' } }, signature = 'reltimefloat({time})', + see_lua = { '|uv.hrtime()| with `(finish - start) / 1e9` for elapsed seconds' }, }, reltimestr = { args = 1, @@ -8890,6 +9138,7 @@ M.funcs = { name = 'remove', params = { { 'list', 'any' }, { 'idx', 'integer' } }, signature = 'remove({list}, {idx})', + see_lua = { '|table.remove()|' }, }, remove__1 = { args = { 2, 3 }, @@ -8954,6 +9203,9 @@ M.funcs = { name = 'remove', params = { { 'dict', 'any' }, { 'key', 'string' } }, signature = 'remove({dict}, {key})', + see_lua = { + '`local value = dict[key]; dict[key] = nil` for dicts; missing-key behavior differs', + }, }, rename = { args = 2, @@ -8971,6 +9223,7 @@ M.funcs = { params = { { 'from', 'string' }, { 'to', 'string' } }, returns = 'integer', signature = 'rename({from}, {to})', + see_lua = { '|uv.fs_rename()|', '|os.rename()|' }, }, ['repeat'] = { args = 2, @@ -8990,6 +9243,7 @@ M.funcs = { name = 'repeat', params = { { 'expr', 'any' }, { 'count', 'integer' } }, signature = 'repeat({expr}, {count})', + see_lua = { '|string.rep()| for strings; lists need manual repetition' }, }, resolve = { args = 1, @@ -9034,6 +9288,9 @@ M.funcs = { params = { { 'object', 'T[]' } }, returns = 'T[]', signature = 'reverse({object})', + see_lua = { + '`vim.iter(list):rev():totable()` for lists; strings, blobs, and in-place behavior differ', + }, }, round = { args = 1, @@ -9058,6 +9315,9 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'round({expr})', + see_lua = { + '`expr >= 0 and math.floor(expr + 0.5) or math.ceil(expr - 0.5)` for half-away-from-zero rounding', + }, }, rpcnotify = { args = { 2 }, @@ -9072,6 +9332,7 @@ M.funcs = { params = { { 'channel', 'integer' }, { 'event', 'string' }, { '...', 'any' } }, returns = 'integer', signature = 'rpcnotify({channel}, {event} [, {args}...])', + see_lua = { '|vim.rpcnotify()|' }, }, rpcrequest = { args = { 2 }, @@ -9085,6 +9346,7 @@ M.funcs = { name = 'rpcrequest', params = { { 'channel', 'integer' }, { 'method', 'string' }, { '...', 'any' } }, signature = 'rpcrequest({channel}, {method} [, {args}...])', + see_lua = { '|vim.rpcrequest()|' }, }, rpcstart = { deprecated = true, @@ -9805,6 +10067,7 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'text', 'string|string[]' } }, returns = 'integer', signature = 'setbufline({buf}, {lnum}, {text})', + see_lua = { '|nvim_buf_set_lines()|' }, }, setbufvar = { args = 3, @@ -9827,6 +10090,9 @@ M.funcs = { name = 'setbufvar', params = { { 'buf', 'integer|string' }, { 'varname', 'string' }, { 'val', 'any' } }, signature = 'setbufvar({buf}, {varname}, {val})', + see_lua = { + '|nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|', + }, }, setcellwidths = { args = 1, @@ -9887,6 +10153,9 @@ M.funcs = { name = 'setcharpos', params = { { 'expr', 'string' }, { 'list', 'integer[]' } }, signature = 'setcharpos({expr}, {list})', + see_lua = { + '|nvim_win_set_cursor()| or |nvim_buf_set_mark()| with |vim.str_byteindex()|; special positions, `off`, and `curswant` differ', + }, }, setcharsearch = { args = 1, @@ -9961,6 +10230,9 @@ M.funcs = { name = 'setcursorcharpos', params = { { 'lnum', 'integer|string' }, { 'col', 'integer' }, { 'off', 'integer' } }, signature = 'setcursorcharpos({lnum}, {col} [, {off}])', + see_lua = { + '|nvim_win_set_cursor()| with |vim.str_byteindex()|; `off`, return values, and special line forms differ', + }, }, setcursorcharpos__1 = { args = { 1, 3 }, @@ -9981,6 +10253,9 @@ M.funcs = { name = 'setcursorcharpos', params = { { 'list', 'integer[]' } }, signature = 'setcursorcharpos({list})', + see_lua = { + '|nvim_win_set_cursor()| with |vim.str_byteindex()|; list shape, `off`, and return values differ', + }, }, setenv = { args = 2, @@ -9996,6 +10271,7 @@ M.funcs = { name = 'setenv', params = { { 'name', 'string' }, { 'val', 'string' } }, signature = 'setenv({name}, {val})', + see_lua = { '|vim.env|' }, }, setfperm = { args = 2, @@ -10021,6 +10297,7 @@ M.funcs = { name = 'setfperm', params = { { 'fname', 'string' }, { 'mode', 'string' } }, signature = 'setfperm({fname}, {mode})', + see_lua = { '|uv.fs_chmod()|' }, }, setline = { args = 2, @@ -10057,6 +10334,7 @@ M.funcs = { name = 'setline', params = { { 'lnum', 'integer|string' }, { 'text', 'any' } }, signature = 'setline({lnum}, {text})', + see_lua = { '|nvim_set_current_line()|', '|nvim_buf_set_lines()|' }, }, setloclist = { args = { 2, 4 }, @@ -10164,6 +10442,9 @@ M.funcs = { name = 'setpos', params = { { 'expr', 'string' }, { 'list', 'integer[]' } }, signature = 'setpos({expr}, {list})', + see_lua = { + '|nvim_win_set_cursor()| for "." or |nvim_buf_set_mark()| for marks; special positions, `off`, and `curswant` differ', + }, }, setqflist = { args = { 1, 3 }, @@ -10373,6 +10654,7 @@ M.funcs = { name = 'settabvar', params = { { 'tabnr', 'integer' }, { 'varname', 'string' }, { 'val', 'any' } }, signature = 'settabvar({tabnr}, {varname}, {val})', + see_lua = { '|nvim_tabpage_set_var()|', '|vim.t|' }, }, settabwinvar = { args = 4, @@ -10402,6 +10684,9 @@ M.funcs = { { 'val', 'any' }, }, signature = 'settabwinvar({tabnr}, {winnr}, {varname}, {val})', + see_lua = { + '|nvim_win_set_var()| or |vim.w| after resolving {tabnr} and {winnr} to a winid; option names use |nvim_set_option_value()|', + }, }, settagstack = { args = { 2, 3 }, @@ -10457,6 +10742,9 @@ M.funcs = { name = 'setwinvar', params = { { 'nr', 'integer' }, { 'varname', 'string' }, { 'val', 'any' } }, signature = 'setwinvar({nr}, {varname}, {val})', + see_lua = { + '|nvim_win_set_var()| or |vim.w| after resolving {nr} to a winid; option names use |nvim_set_option_value()|', + }, }, sha256 = { args = 1, @@ -10512,6 +10800,9 @@ M.funcs = { params = { { 'string', 'string' }, { 'special', 'boolean' } }, returns = 'string', signature = 'shellescape({string} [, {special}])', + see_lua = { + '|vim.system()| with list args to avoid shell escaping; `:!` and {special} semantics differ', + }, }, shiftwidth = { args = { 0, 1 }, @@ -10542,6 +10833,9 @@ M.funcs = { params = { { 'col', 'integer' } }, signature = 'shiftwidth([{col}])', returns = 'integer', + see_lua = { + "|vim.bo| for simple cases: `vim.bo.shiftwidth > 0 and vim.bo.shiftwidth or vim.bo.tabstop`; `{col}` and 'vartabstop' semantics differ", + }, }, sign_define = { args = { 1, 2 }, @@ -10550,6 +10844,7 @@ M.funcs = { params = { { 'name', 'string' }, { 'dict', 'vim.fn.sign_define.dict' } }, signature = 'sign_define({name} [, {dict}])', returns = '0|-1', + see_lua = false, }, sign_define__1 = { args = { 1, 2 }, @@ -10605,6 +10900,7 @@ M.funcs = { params = { { 'list', 'vim.fn.sign_define.dict[]' } }, signature = 'sign_define({list})', returns = '(0|-1)[]', + see_lua = false, }, sign_getdefined = { args = { 0, 1 }, @@ -10650,6 +10946,7 @@ M.funcs = { params = { { 'name', 'string' } }, signature = 'sign_getdefined([{name}])', returns = 'vim.fn.sign_getdefined.ret.item[]', + see_lua = false, }, sign_getplaced = { args = { 0, 2 }, @@ -10719,6 +11016,7 @@ M.funcs = { params = { { 'buf', 'integer|string' }, { 'dict', 'vim.fn.sign_getplaced.dict' } }, signature = 'sign_getplaced([{buf} [, {dict}]])', returns = 'vim.fn.sign_getplaced.ret.item[]', + see_lua = false, }, sign_jump = { args = 3, @@ -10743,6 +11041,7 @@ M.funcs = { params = { { 'id', 'integer' }, { 'group', 'string' }, { 'buf', 'integer|string' } }, signature = 'sign_jump({id}, {group}, {buf})', returns = 'integer', + see_lua = false, }, sign_place = { args = { 4, 5 }, @@ -10806,6 +11105,7 @@ M.funcs = { }, signature = 'sign_place({id}, {group}, {name}, {buf} [, {dict}])', returns = 'integer', + see_lua = false, }, sign_placelist = { args = 1, @@ -10874,6 +11174,7 @@ M.funcs = { params = { { 'list', 'vim.fn.sign_placelist.list.item[]' } }, signature = 'sign_placelist({list})', returns = 'integer[]', + see_lua = false, }, sign_undefine = { args = { 0, 1 }, @@ -10882,6 +11183,7 @@ M.funcs = { params = { { 'name', 'string' } }, signature = 'sign_undefine([{name}])', returns = '0|-1', + see_lua = false, }, sign_undefine__1 = { args = { 0, 1 }, @@ -10913,6 +11215,7 @@ M.funcs = { params = { { 'list', 'string[]' } }, signature = 'sign_undefine({list})', returns = 'integer[]', + see_lua = false, }, sign_unplace = { args = { 1, 2 }, @@ -10964,6 +11267,7 @@ M.funcs = { params = { { 'group', 'string' }, { 'dict', 'vim.fn.sign_unplace.dict' } }, signature = 'sign_unplace({group} [, {dict}])', returns = '0|-1', + see_lua = false, }, sign_unplacelist = { args = 1, @@ -11001,6 +11305,7 @@ M.funcs = { params = { { 'list', 'vim.fn.sign_unplacelist.list.item' } }, signature = 'sign_unplacelist({list})', returns = '(0|-1)[]', + see_lua = false, }, simplify = { args = 1, @@ -11027,6 +11332,9 @@ M.funcs = { params = { { 'filename', 'string' } }, returns = 'string', signature = 'simplify({filename})', + see_lua = { + '|vim.fs.normalize()|; `~`/$VAR expansion and leading `./` or trailing `/` handling differ', + }, }, sin = { args = 1, @@ -11047,6 +11355,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'sin({expr})', + see_lua = { '|math.sin()|' }, }, sinh = { args = 1, @@ -11067,6 +11376,7 @@ M.funcs = { name = 'sinh', params = { { 'expr', 'number' } }, signature = 'sinh({expr})', + see_lua = { '|math.sinh()|' }, }, slice = { args = { 2, 3 }, @@ -11199,6 +11509,9 @@ M.funcs = { params = { { 'list', 'T[]' }, { 'how', 'string|function' }, { 'dict', 'any' } }, returns = 'T[]', signature = 'sort({list} [, {how} [, {dict}]])', + see_lua = { + "|table.sort()| with a custom comparator; it is not stable and Vim's `i`/`l`/`n`/`N`/`f` modes differ", + }, }, soundfold = { args = 1, @@ -11248,6 +11561,9 @@ M.funcs = { name = 'spellbadword', params = { { 'sentence', 'string' } }, signature = 'spellbadword([{sentence}])', + see_lua = { + '|vim.spell.check()| for string input; it returns all matches with positions, not just the first one or cursor-moving behavior', + }, }, spellsuggest = { args = { 1, 3 }, @@ -11312,6 +11628,7 @@ M.funcs = { params = { { 'string', 'string' }, { 'pattern', 'string' }, { 'keepempty', 'boolean' } }, returns = 'string[]', signature = 'split({string} [, {pattern} [, {keepempty}]])', + see_lua = { '|vim.split()|' }, }, sqrt = { args = 1, @@ -11334,6 +11651,7 @@ M.funcs = { name = 'sqrt', params = { { 'expr', 'number' } }, signature = 'sqrt({expr})', + see_lua = { '|math.sqrt()|' }, }, srand = { args = { 0, 1 }, @@ -11356,6 +11674,7 @@ M.funcs = { name = 'srand', params = { { 'expr', 'number' } }, signature = 'srand([{expr}])', + see_lua = { '|math.randomseed()|' }, }, state = { args = { 0, 1 }, @@ -11495,6 +11814,9 @@ M.funcs = { name = 'str2float', params = { { 'string', 'string' }, { 'quoted', 'boolean' } }, signature = 'str2float({string} [, {quoted}])', + see_lua = { + '|tonumber()| for simple numbers; quoted digits, hex forms, and trailing text differ', + }, }, str2list = { args = { 1, 2 }, @@ -11542,6 +11864,9 @@ M.funcs = { name = 'str2nr', params = { { 'string', 'string' }, { 'base', 'integer' } }, signature = 'str2nr({string} [, {base}])', + see_lua = { + '|tonumber()| for simple numbers; quoted digits, base prefixes, and trailing text differ', + }, }, strcharlen = { args = 1, @@ -11626,6 +11951,7 @@ M.funcs = { params = { { 'string', 'string' }, { 'skipcc', '0|1|boolean' } }, returns = 'integer', signature = 'strchars({string} [, {skipcc}])', + see_lua = { '|vim.str_utfindex()| for codepoint counts; `skipcc` handling differs' }, }, strdisplaywidth = { args = { 1, 2 }, @@ -11652,6 +11978,9 @@ M.funcs = { params = { { 'string', 'string' }, { 'col', 'integer' } }, returns = 'integer', signature = 'strdisplaywidth({string} [, {col}])', + see_lua = { + '|nvim_strwidth()| when `{col}` is 0; Tab expansion and window-option semantics differ', + }, }, strftime = { args = { 1, 2 }, @@ -11677,6 +12006,7 @@ M.funcs = { params = { { 'format', 'string' }, { 'time', 'number' } }, returns = 'string', signature = 'strftime({format} [, {time}])', + see_lua = { '|os.date()|' }, }, strgetchar = { args = 2, @@ -11724,6 +12054,9 @@ M.funcs = { params = { { 'haystack', 'string' }, { 'needle', 'string' }, { 'start', 'integer' } }, returns = 'integer', signature = 'stridx({haystack}, {needle} [, {start}])', + see_lua = { + '|string.find()| with `plain = true` and `start + 1`, then subtract 1; missing matches return nil instead of -1', + }, }, string = { args = 1, @@ -11760,6 +12093,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'string', signature = 'string({expr})', + see_lua = { '|vim.inspect()| for tables, or |tostring()| for scalars' }, }, strlen = { args = 1, @@ -11777,6 +12111,7 @@ M.funcs = { params = { { 'string', 'string' } }, returns = 'integer', signature = 'strlen({string})', + see_lua = { '|string.len()|' }, }, strpart = { args = { 2, 4 }, @@ -11818,6 +12153,7 @@ M.funcs = { }, returns = 'string', signature = 'strpart({src}, {start} [, {len} [, {chars}]])', + see_lua = { '|string.sub()| for byte slices; negative `start` and the `chars` flag differ' }, }, strptime = { args = 2, @@ -11880,6 +12216,9 @@ M.funcs = { }, returns = 'integer', signature = 'strridx({haystack}, {needle} [, {start}])', + see_lua = { + '|string.find()| in a loop with `plain = true`, then subtract 1; empty-needle and missing-match semantics differ', + }, }, strtrans = { args = 1, @@ -11928,6 +12267,7 @@ M.funcs = { params = { { 'string', 'string' }, { 'countcc', '0|1' } }, returns = 'integer', signature = 'strutf16len({string} [, {countcc}])', + see_lua = { '|vim.str_utfindex()| with `"utf-16"`; `countcc = false` semantics differ' }, }, strwidth = { args = 1, @@ -11948,6 +12288,7 @@ M.funcs = { params = { { 'string', 'string' } }, returns = 'integer', signature = 'strwidth({string})', + see_lua = { '|nvim_strwidth()|' }, }, submatch = { args = { 1, 2 }, @@ -12050,6 +12391,9 @@ M.funcs = { }, returns = 'string', signature = 'substitute({string}, {pat}, {sub}, {flags})', + see_lua = { + '|string.gsub()| for common substitutions; Vim patterns, flags, and replacement semantics differ', + }, }, swapfilelist = { desc = [=[ @@ -12286,8 +12630,6 @@ M.funcs = { base = 1, tags = { 'E677' }, desc = [=[ - Lua: Prefer |vim.system()|. - Gets the output of {cmd} as a |string| (|systemlist()| returns a |List|) and sets |v:shell_error| to the error code. {cmd} is treated as in |jobstart()|: @@ -12342,6 +12684,9 @@ M.funcs = { }, returns = 'string', signature = 'system({cmd} [, {input}])', + see_lua = { + '`vim.system(...):wait().stdout` for string output; string commands use the shell in Vimscript, not by default in Lua', + }, }, systemlist = { args = { 1, 3 }, @@ -12371,6 +12716,9 @@ M.funcs = { -- returns = "string[]|''", returns = 'string[]', signature = 'systemlist({cmd} [, {input} [, {keepempty}]])', + see_lua = { + '`vim.system(...):wait().stdout` split into lines; string commands use the shell in Vimscript, not by default in Lua', + }, }, tabpagebuflist = { args = { 0, 1 }, @@ -12392,6 +12740,9 @@ M.funcs = { name = 'tabpagebuflist', params = { { 'arg', 'integer' } }, signature = 'tabpagebuflist([{arg}])', + see_lua = { + '|nvim_tabpage_list_wins()| with |nvim_win_get_buf()|; invalid tabpages error instead of returning 0', + }, }, tabpagenr = { args = { 0, 1 }, @@ -12413,6 +12764,9 @@ M.funcs = { params = { { 'arg', "'$'|'#'" } }, returns = 'integer', signature = 'tabpagenr([{arg}])', + see_lua = { + '|nvim_tabpage_get_number()| with |nvim_get_current_tabpage()| for the current tab, or `#vim.api.nvim_list_tabpages()` for "$"; "#" differs', + }, }, tabpagewinnr = { args = { 1, 2 }, @@ -12435,6 +12789,9 @@ M.funcs = { params = { { 'tabarg', 'integer' }, { 'arg', "'$'|'#'" } }, returns = 'integer', signature = 'tabpagewinnr({tabarg} [, {arg}])', + see_lua = { + '|nvim_win_get_number()| with |nvim_tabpage_get_win()| for the current window, or the length of |nvim_tabpage_list_wins()| for "$"; "#" and invalid-tab behavior differ', + }, }, tagfiles = { desc = [=[ @@ -12517,6 +12874,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'tan({expr})', + see_lua = { '|math.tan()|' }, }, tanh = { args = 1, @@ -12538,6 +12896,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'number', signature = 'tanh({expr})', + see_lua = { '|math.tanh()|' }, }, tempname = { desc = [=[ @@ -12552,6 +12911,9 @@ M.funcs = { params = {}, returns = 'string', signature = 'tempname()', + see_lua = { + "|os.tmpname()| for a temporary name; Nvim's |tempdir| and nonexistence are not guaranteed", + }, }, termopen = { deprecated = true, @@ -12663,6 +13025,9 @@ M.funcs = { name = 'timer_start', params = { { 'time', 'number' }, { 'callback', 'string|function' }, { 'options', 'table' } }, signature = 'timer_start({time}, {callback} [, {options}])', + see_lua = { + '|vim.defer_fn()| for one-shot timers, or |uv.new_timer()| for repeating timers; callback and handle semantics differ', + }, }, timer_stop = { args = 1, @@ -12676,6 +13041,9 @@ M.funcs = { name = 'timer_stop', params = { { 'timer', 'integer' } }, signature = 'timer_stop({timer})', + see_lua = { + '|uv.timer_stop()| and |uv.close()| on a stored |uv.new_timer()| handle; timer IDs differ', + }, }, timer_stopall = { args = 0, @@ -12701,6 +13069,7 @@ M.funcs = { params = { { 'expr', 'string' } }, returns = 'string', signature = 'tolower({expr})', + see_lua = { '|string.lower()|' }, }, toupper = { args = 1, @@ -12715,6 +13084,7 @@ M.funcs = { params = { { 'expr', 'string' } }, returns = 'string', signature = 'toupper({expr})', + see_lua = { '|string.upper()|' }, }, tr = { args = 3, @@ -12775,6 +13145,7 @@ M.funcs = { params = { { 'text', 'string' }, { 'mask', 'string' }, { 'dir', '0|1|2' } }, returns = 'string', signature = 'trim({text} [, {mask} [, {dir}]])', + see_lua = { '|vim.trim()|' }, }, trunc = { args = 1, @@ -12798,6 +13169,7 @@ M.funcs = { params = { { 'expr', 'number' } }, returns = 'integer', signature = 'trunc({expr})', + see_lua = { '|math.modf()| (first return value)' }, }, type = { args = 1, @@ -12836,6 +13208,7 @@ M.funcs = { params = { { 'expr', 'any' } }, returns = 'integer', signature = 'type({expr})', + see_lua = { '|lua-type()| for most Lua type checks; Vim type IDs differ' }, }, undofile = { args = 1, @@ -12914,8 +13287,6 @@ M.funcs = { base = 1, tags = { 'E882' }, desc = [=[ - Lua: Prefer |vim.list.unique()|. - Remove second and succeeding copies of repeated adjacent {list} items in-place. Returns {list}. If you want a list to remain unmodified make a copy first: >vim @@ -12931,6 +13302,7 @@ M.funcs = { params = { { 'list', 'any' }, { 'func', 'any' }, { 'dict', 'any' } }, returns = 'any[]|0', signature = 'uniq({list} [, {func} [, {dict}]])', + see_lua = { '|vim.list.unique()|' }, }, utf16idx = { args = { 2, 4 }, @@ -12973,6 +13345,9 @@ M.funcs = { }, returns = 'integer', signature = 'utf16idx({string}, {idx} [, {countcc} [, {charidx}]])', + see_lua = { + '|vim.str_utfindex()| with `"utf-16"` and `strict_indexing = false`; `countcc` and `charidx` semantics differ', + }, }, values = { args = 1, @@ -12986,6 +13361,7 @@ M.funcs = { name = 'values', params = { { 'dict', 'any' } }, signature = 'values({dict})', + see_lua = { '|vim.tbl_values()|' }, }, virtcol = { args = { 1, 3 }, @@ -13121,6 +13497,7 @@ M.funcs = { name = 'wait', params = { { 'timeout', 'integer' }, { 'condition', 'any' }, { 'interval', 'number' } }, signature = 'wait({timeout}, {condition} [, {interval}])', + see_lua = { '|vim.wait()|' }, }, wildmenumode = { desc = [=[ @@ -13186,6 +13563,7 @@ M.funcs = { name = 'win_execute', params = { { 'id', 'integer' }, { 'command', 'string' }, { 'silent', 'boolean' } }, signature = 'win_execute({id}, {command} [, {silent}])', + see_lua = { '|nvim_win_call()|' }, }, win_findbuf = { args = 1, @@ -13199,6 +13577,7 @@ M.funcs = { params = { { 'bufnr', 'integer' } }, returns = 'integer[]', signature = 'win_findbuf({bufnr})', + see_lua = { '|nvim_list_wins()| with |nvim_win_get_buf()|' }, }, win_getid = { args = { 0, 2 }, @@ -13217,6 +13596,9 @@ M.funcs = { params = { { 'win', 'integer' }, { 'tab', 'integer' } }, returns = 'integer', signature = 'win_getid([{win} [, {tab}]])', + see_lua = { + '|nvim_get_current_win()| when omitted, or |nvim_tabpage_list_wins()| with |nvim_win_get_number()| after resolving {tab}; invalid windows return 0 in Vimscript', + }, }, win_gettype = { args = { 0, 1 }, @@ -13259,6 +13641,7 @@ M.funcs = { params = { { 'expr', 'integer' } }, returns = '0|1', signature = 'win_gotoid({expr})', + see_lua = { '|nvim_set_current_win()|; invalid IDs error instead of returning FALSE' }, }, win_id2tabwin = { args = 1, @@ -13272,6 +13655,9 @@ M.funcs = { name = 'win_id2tabwin', params = { { 'expr', 'integer' } }, signature = 'win_id2tabwin({expr})', + see_lua = { + '|nvim_win_get_tabpage()| and |nvim_win_get_number()| for valid windows; invalid IDs error instead of returning `[0, 0]`', + }, }, win_id2win = { args = 1, @@ -13285,6 +13671,9 @@ M.funcs = { params = { { 'expr', 'integer' } }, returns = 'integer', signature = 'win_id2win({expr})', + see_lua = { + '|nvim_win_get_number()| for valid windows; windows outside the current tabpage and invalid IDs differ', + }, }, win_move_separator = { args = 2, @@ -13343,6 +13732,9 @@ M.funcs = { name = 'win_screenpos', params = { { 'nr', 'integer' } }, signature = 'win_screenpos({nr})', + see_lua = { + '|nvim_win_get_position()| and add 1 to row and col; invalid-window semantics differ', + }, }, win_splitmove = { args = { 2, 3 }, @@ -13389,6 +13781,7 @@ M.funcs = { params = { { 'nr', 'integer' } }, returns = 'integer', signature = 'winbufnr({nr})', + see_lua = { '|nvim_win_get_buf()|' }, }, wincol = { desc = [=[ @@ -13432,6 +13825,7 @@ M.funcs = { params = { { 'nr', 'integer' } }, returns = 'integer', signature = 'winheight({nr})', + see_lua = false, }, winlayout = { args = { 0, 1 }, @@ -13529,6 +13923,9 @@ M.funcs = { params = { { 'arg', 'string|integer' } }, returns = 'integer', signature = 'winnr([{arg}])', + see_lua = { + '|nvim_win_get_number()| with |nvim_get_current_win()| for the current window, or |nvim_tabpage_list_wins()| with |nvim_get_current_tabpage()| for "$"; "#", motion args, and hidden windows differ', + }, }, winrestcmd = { desc = [=[ @@ -13629,6 +14026,7 @@ M.funcs = { params = { { 'nr', 'integer' } }, returns = 'integer', signature = 'winwidth({nr})', + see_lua = false, }, wordcount = { desc = [=[ @@ -13728,6 +14126,7 @@ M.funcs = { params = { { 'expr', 'integer' }, { 'expr', 'integer' } }, returns = 'integer', signature = 'xor({expr}, {expr})', + see_lua = { '|bit.bxor()|' }, }, }