From fd089c8e50c211d7beae15dbc9492ae5a1a5f2e2 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 26 Jul 2023 09:50:54 +0100 Subject: [PATCH] feat(lua): typing for vim.fn.* (#24473) Problem: No LSP information for `vim.fn.*` Solution: Add meta file for `vim.fn.*`. --- .gitattributes | 2 + .github/workflows/api-docs.yml | 9 +- .luacheckrc | 1 + runtime/lua/vim/_meta/vimfn.lua | 11162 ++++++++++++++++++++++++++++++ scripts/gen_vimfn_types.lua | 244 + src/nvim/eval.lua | 299 +- 6 files changed, 11584 insertions(+), 133 deletions(-) create mode 100644 runtime/lua/vim/_meta/vimfn.lua create mode 100755 scripts/gen_vimfn_types.lua diff --git a/.gitattributes b/.gitattributes index 1128560dc2..6de8569184 100755 --- a/.gitattributes +++ b/.gitattributes @@ -4,6 +4,8 @@ runtime/doc/* linguist-documentation +runtime/lua/vim/_meta/vimfn.lua linguist-generated + src/xdiff/** linguist-vendored src/cjson/** linguist-vendored src/unicode/** linguist-vendored diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml index f083d32fce..432e91306c 100644 --- a/.github/workflows/api-docs.yml +++ b/.github/workflows/api-docs.yml @@ -1,14 +1,15 @@ # Check if any PR needs to run the autogenerate script -name: Autogenerate API docs +name: Autogenerate API docs and types on: pull_request: paths: - 'src/nvim/api/*.[ch]' + - 'src/nvim/eval.lua' - 'runtime/lua/**.lua' - 'runtime/doc/**' jobs: - regen-api-docs: + regen-api-docs-and-types: runs-on: ubuntu-latest permissions: contents: write @@ -28,11 +29,13 @@ jobs: id: docs run: | python3 scripts/gen_vimdoc.py + ./scripts/gen_vimfn_types.lua printf 'UPDATED_DOCS=%s\n' $([ -z "$(git diff)" ]; echo $?) >> $GITHUB_OUTPUT - name: FAIL, PR has not committed doc changes if: ${{ steps.docs.outputs.UPDATED_DOCS != 0 }} run: | - echo "Job failed, run ./scripts/gen_vimdoc.py and commit your doc changes" + echo "Job failed, run ./scripts/gen_vimdoc.py and/or ./scripts/gen_vimfn_types.lua" + echo "and commit your doc changes" echo "The doc generation produces the following changes:" git diff --color --exit-code diff --git a/.luacheckrc b/.luacheckrc index cbec2210d3..48d83c472a 100644 --- a/.luacheckrc +++ b/.luacheckrc @@ -44,5 +44,6 @@ globals = { exclude_files = { 'test/functional/fixtures/lua/syntax_error.lua', 'runtime/lua/vim/treesitter/_meta.lua', + 'runtime/lua/vim/_meta/vimfn.lua', 'runtime/lua/vim/re.lua', } diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua new file mode 100644 index 0000000000..b70e361e48 --- /dev/null +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -0,0 +1,11162 @@ +--- @meta +-- THIS FILE IS GENERATED +-- DO NOT EDIT + +--- 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 +--- abs() gives an error message and returns -1. +--- Examples: > +--- echo abs(1.456) +--- < 1.456 > +--- echo abs(-5.456) +--- < 5.456 > +--- echo abs(-4) +--- < 4 +--- +--- Can also be used as a |method|: > +--- Compute()->abs() +--- +--- @param expr any +--- @return any +function vim.fn.abs(expr) end + +--- 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 +--- [-1, 1]. +--- Returns NaN if {expr} is outside the range [-1, 1]. Returns +--- 0.0 if {expr} is not a |Float| or a |Number|. +--- Examples: > +--- :echo acos(0) +--- < 1.570796 > +--- :echo acos(-0.5) +--- < 2.094395 +--- +--- Can also be used as a |method|: > +--- Compute()->acos() +--- +--- @param expr any +--- @return number +function vim.fn.acos(expr) end + +--- Append the item {expr} to |List| or |Blob| {object}. Returns +--- the resulting |List| or |Blob|. Examples: > +--- :let alist = add([1, 2, 3], item) +--- :call add(mylist, "woodstock") +--- +--- mylist->add(val1)->add(val2) +--- +--- @param object any +--- @param expr any +--- @return any +function vim.fn.add(object, expr) end + +--- 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()`. +--- Example: > +--- :let flag = and(bits, 0x80) +--- +--- :let flag = bits->and(0x80) +--- +--- @param expr any +--- @param expr1 any +--- @return any +vim.fn['and'] = function(expr, expr1) end + +--- Returns Dictionary of |api-metadata|. +--- +--- View it in a nice human-readable format: > +--- :lua vim.print(vim.fn.api_info()) +--- +--- @return any +function vim.fn.api_info() end + +--- 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 +--- the current buffer. +--- Any type of item is accepted and converted to a String. +--- {lnum} can be zero to insert a line before the first one. +--- {lnum} is used like with |getline()|. +--- Returns 1 for failure ({lnum} out of range or out of memory), +--- 0 for success. Example: > +--- :let failed = append(line('$'), "# THE END") +--- :let failed = append(0, ["Chapter 1", "the beginning"]) +--- +--- +--- mylist->append(lnum) +--- +--- @param lnum integer +--- @param text any +--- @return any +function vim.fn.append(lnum, text) end + +--- Like |append()| but append the text in buffer {expr}. +--- +--- This function works only for loaded buffers. First call +--- |bufload()| if needed. +--- +--- For the use of {buf}, see |bufname()|. +--- +--- {lnum} is the line number to append below. Note that using +--- |line()| would use the current buffer, not the one appending +--- to. Use "$" to append at the end of the buffer. Other string +--- values are not supported. +--- +--- On success 0 is returned, on failure 1 is returned. +--- +--- If {buf} is not a valid buffer or {lnum} is not valid, an +--- error message is given. Example: > +--- :let failed = appendbufline(13, 0, "# THE START") +--- < +--- Can also be used as a |method| after a List: > +--- mylist->appendbufline(buf, lnum) +--- +--- @param buf any +--- @param lnum integer +--- @param text any +--- @return any +function vim.fn.appendbufline(buf, lnum, text) end + +--- The result is the number of files in the argument list. See +--- |arglist|. +--- If {winid} is not supplied, the argument list of the current +--- window is used. +--- If {winid} is -1, the global argument list is used. +--- Otherwise {winid} specifies the window of which the argument +--- list is used: either the window number or the window ID. +--- Returns -1 if the {winid} argument is invalid. +--- +--- *argidx()* +--- @param winid? integer +--- @return integer +function vim.fn.argc(winid) end + +--- the first file. argc() - 1 is the last one. See |arglist|. +--- +--- *arglistid()* +--- @return integer +function vim.fn.argidx() end + +--- Return the argument list ID. This is a number which +--- identifies the argument list being used. Zero is used for the +--- global argument list. See |arglist|. +--- Returns -1 if the arguments are invalid. +--- +--- Without arguments use the current window. +--- With {winnr} only use this window in the current tab page. +--- With {winnr} and {tabnr} use the window in the specified tab +--- page. +--- {winnr} can be the window number or the |window-ID|. +--- +--- *argv()* +--- @param winnr? integer +--- @param tabnr? integer +--- @return integer +function vim.fn.arglistid(winnr, tabnr) end + +--- The result is the {nr}th file in the argument list. See +--- |arglist|. "argv(0)" is the first one. Example: > +--- :let i = 0 +--- :while i < argc() +--- : let f = escape(fnameescape(argv(i)), '.') +--- : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '' +--- : let i = i + 1 +--- :endwhile +--- +--- :echo asin(0.8) +--- < 0.927295 > +--- :echo asin(-0.5) +--- < -0.523599 +--- +--- Can also be used as a |method|: > +--- Compute()->asin() +--- +--- +--- assert_ functions are documented here: |assert-functions-details| +--- +--- +--- @param expr any +--- @return any +function vim.fn.asin(expr) end + +--- Run {cmd} and add an error message to |v:errors| if it does +--- NOT produce a beep or visual bell. +--- Also see |assert_fails()|, |assert_nobeep()| and +--- |assert-return|. +--- +--- Can also be used as a |method|: > +--- GetCmd()->assert_beeps() +--- < +--- *assert_equal()* +--- @param cmd any +--- @return 0|1 +function vim.fn.assert_beeps(cmd) end + +--- 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| +--- The error is in the form "Expected {expected} but got +--- {actual}". When {msg} is present it is prefixed to that. +--- +--- There is no automatic conversion, the String "4" is different +--- from the Number 4. And the number 4 is different from the +--- Float 4.0. The value of 'ignorecase' is not used here, case +--- always matters. +--- Example: > +--- assert_equal('foo', 'bar') +--- +--- mylist->assert_equal([1, 2, 3]) +--- +--- < *assert_equalfile()* +--- @param expected any +--- @param actual any +--- @param msg? any +--- @return 0|1 +function vim.fn.assert_equal(expected, actual, msg) end + +--- When the files {fname-one} and {fname-two} do not contain +--- exactly the same text an error message is added to |v:errors|. +--- Also see |assert-return|. +--- When {fname-one} or {fname-two} does not exist the error will +--- mention that. +--- +--- Can also be used as a |method|: > +--- GetLog()->assert_equalfile('expected.log') +--- +--- @return any +function vim.fn.assert_equalfile() end + +--- When v:exception does not contain the string {error} an error +--- message is added to |v:errors|. Also see |assert-return|. +--- This can be used to assert that a command throws an exception. +--- Using the error number, followed by a colon, avoids problems +--- with translations: > +--- try +--- commandthatfails +--- call assert_false(1, 'command should have failed') +--- catch +--- call assert_exception('E492:') +--- endtry +--- < +--- *assert_fails()* +--- @param error any +--- @param msg? any +--- @return 0|1 +function vim.fn.assert_exception(error, msg) end + +--- Run {cmd} and add an error message to |v:errors| if it does +--- NOT produce an error or when {error} is not found in the +--- error message. Also see |assert-return|. +--- +--- When {error} is a string it must be found literally in the +--- first reported error. Most often this will be the error code, +--- including the colon, e.g. "E123:". > +--- assert_fails('bad cmd', 'E987:') +--- < +--- When {error} is a |List| with one or two strings, these are +--- used as patterns. The first pattern is matched against the +--- first reported error: > +--- assert_fails('cmd', ['E987:.*expected bool']) +--- +--- assert_fails('cmd', ['', 'E987:']) +--- < +--- If {msg} is empty then it is not used. Do this to get the +--- default message when passing the {lnum} argument. +--- +--- When {lnum} is present and not negative, and the {error} +--- argument is present and matches, then this is compared with +--- the line number at which the error was reported. That can be +--- the line number in a function or in a script. +--- +--- When {context} is present it is used as a pattern and matched +--- against the context (script name or function name) where +--- {lnum} is located in. +--- +--- Note that beeping is not considered an error, and some failing +--- commands only beep. Use |assert_beeps()| for those. +--- +--- Can also be used as a |method|: > +--- GetCmd()->assert_fails('E99:') +--- +--- @param cmd any +--- @param error? any +--- @param msg? any +--- @param lnum? integer +--- @param context? any +--- @return 0|1 +function vim.fn.assert_fails(cmd, error, msg, lnum, context) end + +--- 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}". +--- When {msg} is present it is prepended to that. +--- Also see |assert-return|. +--- +--- A value is false when it is zero. When {actual} is not a +--- number the assert fails. +--- +--- Can also be used as a |method|: > +--- GetResult()->assert_false() +--- +--- @param actual any +--- @param msg? any +--- @return 0|1 +function vim.fn.assert_false(actual, msg) end + +--- 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|. +--- The error is in the form "Expected range {lower} - {upper}, +--- but got {actual}". When {msg} is present it is prefixed to +--- that. +--- +--- *assert_match()* +--- @param lower any +--- @param upper any +--- @param actual any +--- @param msg? any +--- @return 0|1 +function vim.fn.assert_inrange(lower, upper, actual, msg) end + +--- When {pattern} does not match {actual} an error message is +--- added to |v:errors|. Also see |assert-return|. +--- The error is in the form "Pattern {pattern} does not match +--- {actual}". When {msg} is present it is prefixed to that. +--- +--- {pattern} is used as with |expr-=~|: The matching is always done +--- like 'magic' was set and 'cpoptions' is empty, no matter what +--- the actual value of 'magic' or 'cpoptions' is. +--- +--- {actual} is used as a string, automatic conversion applies. +--- Use "^" and "$" to match with the start and end of the text. +--- Use both to match the whole text. +--- +--- Example: > +--- assert_match('^f.*o$', 'foobar') +--- +--- getFile()->assert_match('foo.*') +--- < +--- @param pattern any +--- @param actual any +--- @param msg? any +--- @return 0|1 +function vim.fn.assert_match(pattern, actual, msg) end + +--- Run {cmd} and add an error message to |v:errors| if it +--- produces a beep or visual bell. +--- Also see |assert_beeps()|. +--- +--- Can also be used as a |method|: > +--- GetCmd()->assert_nobeep() +--- < +--- *assert_notequal()* +--- @param cmd any +--- @return 0|1 +function vim.fn.assert_nobeep(cmd) end + +--- The opposite of `assert_equal()`: add an error message to +--- |v:errors| when {expected} and {actual} are equal. +--- Also see |assert-return|. +--- +--- Can also be used as a |method|: > +--- mylist->assert_notequal([1, 2, 3]) +--- +--- < *assert_notmatch()* +--- @param expected any +--- @param actual any +--- @param msg? any +--- @return any +function vim.fn.assert_notequal(expected, actual, msg) end + +--- The opposite of `assert_match()`: add an error message to +--- |v:errors| when {pattern} matches {actual}. +--- Also see |assert-return|. +--- +--- Can also be used as a |method|: > +--- getFile()->assert_notmatch('bar.*') +--- +--- +--- @param pattern any +--- @param actual any +--- @param msg? any +--- @return any +function vim.fn.assert_notmatch(pattern, actual, msg) end + +--- Report a test failure directly, using String {msg}. +--- Always returns one. +--- +--- Can also be used as a |method|: > +--- GetMessage()->assert_report() +--- +--- +--- @param msg any +--- @return any +function vim.fn.assert_report(msg) end + +--- When {actual} is not true an error message is added to +--- |v:errors|, like with |assert_equal()|. +--- Also see |assert-return|. +--- A value is |TRUE| when it is a non-zero number or |v:true|. +--- When {actual} is not a number or |v:true| the assert fails. +--- When {msg} is given it precedes the default message. +--- +--- Can also be used as a |method|: > +--- GetResult()->assert_true() +--- < +--- +--- @param actual any +--- @param msg? any +--- @return any +function vim.fn.assert_true(actual, msg) end + +--- 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|. +--- Returns 0.0 if {expr} is not a |Float| or a |Number|. +--- Examples: > +--- :echo atan(100) +--- < 1.560797 > +--- :echo atan(-4.01) +--- < -1.326405 +--- +--- Can also be used as a |method|: > +--- Compute()->atan() +--- +--- @param expr any +--- @return number +function vim.fn.atan(expr) end + +--- 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|. +--- Returns 0.0 if {expr1} or {expr2} is not a |Float| or a +--- |Number|. +--- Examples: > +--- :echo atan2(-1, 1) +--- < -0.785398 > +--- :echo atan2(1, -1) +--- < 2.356194 +--- +--- Can also be used as a |method|: > +--- Compute()->atan2(1) +--- +--- @param expr1 any +--- @param expr2 any +--- @return number +function vim.fn.atan2(expr1, expr2) end + +--- Return a List containing the number value of each byte in Blob +--- {blob}. Examples: > +--- blob2list(0z0102.0304) returns [1, 2, 3, 4] +--- blob2list(0z) returns [] +--- +--- GetBlob()->blob2list() +--- < +--- *browse()* +--- @param blob any +--- @return any +function vim.fn.blob2list(blob) end + +--- Put up a file requester. This only works when "has("browse")" +--- returns |TRUE| (only in some GUI versions). +--- The input fields are: +--- {save} when |TRUE|, select file to write +--- {title} title for the requester +--- {initdir} directory to start browsing in +--- {default} default file name +--- An empty string is returned when the "Cancel" button is hit, +--- something went wrong, or browsing is not possible. +--- +--- *browsedir()* +--- @param save any +--- @param title any +--- @param initdir any +--- @param default any +--- @return any +function vim.fn.browse(save, title, initdir, default) end + +--- Put up a directory requester. This only works when +--- "has("browse")" returns |TRUE| (only in some GUI versions). +--- On systems where a directory browser is not supported a file +--- browser is used. In that case: select a file in the directory +--- to be used. +--- The input fields are: +--- {title} title for the requester +--- {initdir} directory to start browsing in +--- When the "Cancel" button is hit, something went wrong, or +--- browsing is not possible, an empty string is returned. +--- +--- @param title any +--- @param initdir any +--- @return any +function vim.fn.browsedir(title, initdir) end + +--- Add a buffer to the buffer list with name {name} (must be a +--- String). +--- If a buffer for file {name} already exists, return that buffer +--- number. Otherwise return the buffer number of the newly +--- created buffer. When {name} is an empty string then a new +--- buffer is always created. +--- The buffer will not have 'buflisted' set and not be loaded +--- yet. To add some text to the buffer use this: > +--- let bufnr = bufadd('someName') +--- call bufload(bufnr) +--- call setbufline(bufnr, 1, ['some', 'text']) +--- +--- let bufnr = 'somename'->bufadd() +--- +--- @param name string +--- @return integer +function vim.fn.bufadd(name) end + +--- The result is a Number, which is |TRUE| if a buffer called +--- {buf} exists. +--- If the {buf} argument is a number, buffer numbers are used. +--- Number zero is the alternate buffer for the current window. +--- +--- If the {buf} argument is a string it must match a buffer name +--- exactly. The name can be: +--- - Relative to the current directory. +--- - A full path. +--- - The name of a buffer with 'buftype' set to "nofile". +--- - A URL name. +--- Unlisted buffers will be found. +--- Note that help files are listed by their short name in the +--- output of |:buffers|, but bufexists() requires using their +--- long name to be able to find them. +--- bufexists() may report a buffer exists, but to use the name +--- with a |:buffer| command you may need to use |expand()|. Esp +--- for MS-Windows 8.3 names in the form "c:\DOCUME~1" +--- Use "bufexists(0)" to test for the existence of an alternate +--- file name. +--- +--- Can also be used as a |method|: > +--- let exists = 'somename'->bufexists() +--- +--- @param buf any +--- @return 0|1 +function vim.fn.bufexists(buf) end + +--- @deprecated +--- Obsolete name for |bufexists()|. +function vim.fn.buffer_exists(...) end + +--- @deprecated +--- Obsolete name for |bufname()|. +function vim.fn.buffer_name(...) end + +--- @deprecated +--- Obsolete name for |bufnr()|. +function vim.fn.buffer_number(...) end + +--- The result is a Number, which is |TRUE| if a buffer called +--- {buf} exists and is listed (has the 'buflisted' option set). +--- The {buf} argument is used like with |bufexists()|. +--- +--- Can also be used as a |method|: > +--- let listed = 'somename'->buflisted() +--- +--- @param buf any +--- @return 0|1 +function vim.fn.buflisted(buf) end + +--- Ensure the buffer {buf} is loaded. When the buffer name +--- refers to an existing file then the file is read. Otherwise +--- the buffer will be empty. If the buffer was already loaded +--- then there is no change. If the buffer is not related to a +--- file the no file is read (e.g., when 'buftype' is "nofile"). +--- If there is an existing swap file for the file of the buffer, +--- there will be no dialog, the buffer will be loaded anyway. +--- The {buf} argument is used like with |bufexists()|. +--- +--- Can also be used as a |method|: > +--- eval 'somename'->bufload() +--- +--- @param buf any +function vim.fn.bufload(buf) end + +--- The result is a Number, which is |TRUE| if a buffer called +--- {buf} exists and is loaded (shown in a window or hidden). +--- The {buf} argument is used like with |bufexists()|. +--- +--- Can also be used as a |method|: > +--- let loaded = 'somename'->bufloaded() +--- +--- @param buf any +--- @return 0|1 +function vim.fn.bufloaded(buf) end + +--- 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]". +--- If {buf} is omitted the current buffer is used. +--- If {buf} is a Number, that buffer number's name is given. +--- Number zero is the alternate buffer for the current window. +--- If {buf} is a String, it is used as a |file-pattern| to match +--- with the buffer names. This is always done like 'magic' is +--- set and 'cpoptions' is empty. When there is more than one +--- match an empty string is returned. +--- "" or "%" can be used for the current buffer, "#" for the +--- alternate buffer. +--- A full match is preferred, otherwise a match at the start, end +--- or middle of the buffer name is accepted. If you only want a +--- full match then put "^" at the start and "$" at the end of the +--- pattern. +--- Listed buffers are found first. If there is a single match +--- with a listed buffer, that one is returned. Next unlisted +--- buffers are searched for. +--- If the {buf} is a String, but you want to use it as a buffer +--- number, force it to be a Number by adding zero to it: > +--- :echo bufname("3" + 0) +--- +--- echo bufnr->bufname() +--- +--- +--- bufname("#") alternate buffer name +--- bufname(3) name of buffer 3 +--- bufname("%") name of current buffer +--- bufname("file2") name of buffer where "file2" matches. +--- < +--- *bufnr()* +--- @param buf? any +--- @return string +function vim.fn.bufname(buf) end + +--- The result is the number of a buffer, as it is displayed by +--- the `:ls` command. For the use of {buf}, see |bufname()| +--- above. +--- If the buffer doesn't exist, -1 is returned. Or, if the +--- {create} argument is present and TRUE, a new, unlisted, +--- buffer is created and its number is returned. +--- bufnr("$") is the last buffer: > +--- :let last_buffer = bufnr("$") +--- +--- echo bufref->bufnr() +--- +--- @param buf? any +--- @param create? any +--- @return integer +function vim.fn.bufnr(buf, create) end + +--- The result is a Number, which is 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 is returned. Example: > +--- +--- echo "A window containing buffer 1 is " .. (bufwinid(1)) +--- < +--- Only deals with the current tab page. See |win_findbuf()| for +--- finding more. +--- +--- Can also be used as a |method|: > +--- FindBuffer()->bufwinid() +--- +--- @param buf any +--- @return integer +function vim.fn.bufwinid(buf) end + +--- 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 +--- is returned. Example: > +--- +--- echo "A window containing buffer 1 is " .. (bufwinnr(1)) +--- +--- +--- FindBuffer()->bufwinnr() +--- +--- @param buf any +--- @return integer +function vim.fn.bufwinnr(buf) end + +--- Return the line number that contains the character at byte +--- count {byte} in the current buffer. This includes the +--- end-of-line character, depending on the 'fileformat' option +--- for the current buffer. The first character has byte count +--- one. +--- Also see |line2byte()|, |go| and |:goto|. +--- +--- Returns -1 if the {byte} value is invalid. +--- +--- Can also be used as a |method|: > +--- GetOffset()->byte2line() +--- +--- @param byte any +--- @return integer +function vim.fn.byte2line(byte) end + +--- Return byte index of the {nr}th character in the String +--- {expr}. Use zero for the first character, it then returns +--- zero. +--- If there are no multibyte characters the returned value is +--- equal to {nr}. +--- Composing characters are not counted separately, their byte +--- length is added to the preceding base character. See +--- |byteidxcomp()| below for counting composing characters +--- separately. +--- When {utf16} is present and TRUE, {nr} is used as the UTF-16 +--- index in the String {expr} instead of as the character index. +--- The UTF-16 index is the index in the string when it is encoded +--- with 16-bit words. If the specified UTF-16 index is in the +--- middle of a character (e.g. in a 4-byte character), then the +--- byte index of the first byte in the character is returned. +--- Refer to |string-offset-encoding| for more information. +--- Example : > +--- echo matchstr(str, ".", byteidx(str, 3)) +--- +--- let s = strpart(str, byteidx(str, 3)) +--- echo strpart(s, 0, byteidx(s, 1)) +--- +--- echo byteidx('a😊😊', 2) returns 5 +--- echo byteidx('a😊😊', 2, 1) returns 1 +--- echo byteidx('a😊😊', 3, 1) returns 5 +--- < +--- Can also be used as a |method|: > +--- GetName()->byteidx(idx) +--- +--- @param expr any +--- @param nr integer +--- @param utf16? any +--- @return integer +function vim.fn.byteidx(expr, nr, utf16) end + +--- Like byteidx(), except that a composing character is counted +--- as a separate character. Example: > +--- let s = 'e' .. nr2char(0x301) +--- echo byteidx(s, 1) +--- echo byteidxcomp(s, 1) +--- echo byteidxcomp(s, 2) +--- +--- GetName()->byteidxcomp(idx) +--- +--- @param expr any +--- @param nr integer +--- @param utf16? any +--- @return integer +function vim.fn.byteidxcomp(expr, nr, utf16) end + +--- Call function {func} with the items in |List| {arglist} as +--- arguments. +--- {func} can either be a |Funcref| or the name of a function. +--- a:firstline and a:lastline are set to the cursor line. +--- Returns the return value of the called function. +--- {dict} is for functions with the "dict" attribute. It will be +--- used to set the local variable "self". |Dictionary-function| +--- +--- Can also be used as a |method|: > +--- GetFunc()->call([arg, arg], dict) +--- +--- @param func any +--- @param arglist any +--- @param dict? any +--- @return any +function vim.fn.call(func, arglist, dict) end + +--- 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|. +--- Examples: > +--- echo ceil(1.456) +--- < 2.0 > +--- echo ceil(-5.456) +--- < -5.0 > +--- echo ceil(4.0) +--- < 4.0 +--- +--- Returns 0.0 if {expr} is not a |Float| or a |Number|. +--- +--- Can also be used as a |method|: > +--- Compute()->ceil() +--- +--- @param expr any +--- @return any +function vim.fn.ceil(expr) end + +--- Close a channel or a specific stream associated with it. +--- For a job, {stream} can be one of "stdin", "stdout", +--- "stderr" or "rpc" (closes stdin/stdout for a job started +--- with `"rpc":v:true`) If {stream} is omitted, all streams +--- are closed. If the channel is a pty, this will then close the +--- pty master, sending SIGHUP to the job process. +--- For a socket, there is only one stream, and {stream} should be +--- omitted. +--- +--- @param id any +--- @param stream? any +--- @return any +function vim.fn.chanclose(id, stream) end + +--- Return the number of the most recent change. This is the same +--- number as what is displayed with |:undolist| and can be used +--- with the |:undo| command. +--- When a change was made it is the number of that change. After +--- redo it is the number of the redone change. After undo it is +--- one less than the number of the undone change. +--- Returns 0 if the undo list is empty. +--- +--- @return integer +function vim.fn.changenr() end + +--- 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 +--- written if the write succeeded, 0 otherwise. +--- See |channel-bytes| for more information. +--- +--- {data} may be a string, string convertible, |Blob|, or a list. +--- If {data} is a list, the items will be joined by newlines; any +--- newlines in an item will be sent as NUL. To send a final +--- newline, include a final empty string. Example: > +--- :call chansend(id, ["abc", "123\n456", ""]) +--- 123456". +--- +--- chansend() writes raw data, not RPC messages. If the channel +--- was created with `"rpc":v:true` then the channel expects RPC +--- messages, use |rpcnotify()| and |rpcrequest()| instead. +--- +--- +--- @param id any +--- @param data any +--- @return any +function vim.fn.chansend(id, data) end + +--- Return Number value of the first char in {string}. +--- Examples: > +--- char2nr(" ") returns 32 +--- char2nr("ABC") returns 65 +--- char2nr("Γ‘") returns 225 +--- char2nr("Γ‘"[0]) returns 195 +--- char2nr("\") returns 128 +--- +--- GetChar()->char2nr() +--- +--- @param string string +--- @param utf8? any +--- @return any +function vim.fn.char2nr(string, utf8) end + +--- Return the character class of the first character in {string}. +--- The character class is one of: +--- 0 blank +--- 1 punctuation +--- 2 word character +--- 3 emoji +--- other specific Unicode class +--- The class is used in patterns and word motions. +--- Returns 0 if {string} is not a |String|. +--- +--- +--- @param string string +--- @return any +function vim.fn.charclass(string) end + +--- Same as |col()| but returns the character index of the column +--- position given with {expr} instead of the byte position. +--- +--- Example: +--- With the cursor on 'μ„Έ' in line 5 with text "μ—¬λ³΄μ„Έμš”": > +--- charcol('.') returns 3 +--- col('.') returns 7 +--- +--- +--- GetPos()->col() +--- < +--- *charidx()* +--- @param expr any +--- @param winid? integer +--- @return any +function vim.fn.charcol(expr, winid) end + +--- 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 +--- equal to {idx}. +--- +--- When {countcc} is omitted or |FALSE|, then composing characters +--- are not counted separately, their byte length is added to the +--- preceding base character. +--- When {countcc} is |TRUE|, then composing characters are +--- counted as separate characters. +--- +--- When {utf16} is present and TRUE, {idx} is used as the UTF-16 +--- index in the String {expr} instead of as the byte index. +--- +--- Returns -1 if the arguments are invalid or if there are less +--- than {idx} bytes. If there are exactly {idx} bytes the length +--- of the string in characters is returned. +--- +--- An error is given and -1 is returned if the first argument is +--- not a string, the second argument is not a number or when the +--- third argument is present and is not zero or one. +--- +--- See |byteidx()| and |byteidxcomp()| for getting the byte index +--- from the character index and |utf16idx()| for getting the +--- UTF-16 index from the character index. +--- Refer to |string-offset-encoding| for more information. +--- Examples: > +--- echo charidx('áb́ć', 3) returns 1 +--- echo charidx('áb́ć', 6, 1) returns 4 +--- echo charidx('áb́ć', 16) returns -1 +--- echo charidx('a😊😊', 4, 0, 1) returns 2 +--- < +--- Can also be used as a |method|: > +--- GetName()->charidx(idx) +--- +--- @param string string +--- @param idx integer +--- @param countcc? any +--- @param utf16? any +--- @return any +function vim.fn.charidx(string, idx, countcc, utf16) end + +--- Change the current working directory to {dir}. The scope of +--- the directory change depends on the directory of the current +--- window: +--- - If the current window has a window-local directory +--- (|:lcd|), then changes the window local directory. +--- - Otherwise, if the current tabpage has a local +--- directory (|:tcd|) then changes the tabpage local +--- directory. +--- - Otherwise, changes the global directory. +--- {dir} must be a String. +--- If successful, returns the previous working directory. Pass +--- this to another chdir() to restore the directory. +--- On failure, returns an empty string. +--- +--- Example: > +--- let save_dir = chdir(newdir) +--- if save_dir != "" +--- " ... do some work +--- call chdir(save_dir) +--- endif +--- +--- +--- GetDir()->chdir() +--- < +--- @param dir string +--- @return any +function vim.fn.chdir(dir) end + +--- Get the amount of indent for line {lnum} according the C +--- indenting rules, as with 'cindent'. +--- The indent is counted in spaces, the value of 'tabstop' is +--- relevant. {lnum} is used just like in |getline()|. +--- When {lnum} is invalid -1 is returned. +--- See |C-indenting|. +--- +--- Can also be used as a |method|: > +--- GetLnum()->cindent() +--- +--- @param lnum integer +--- @return any +function vim.fn.cindent(lnum) end + +--- Clears all matches previously defined for the current window +--- by |matchadd()| and the |:match| commands. +--- If {win} is specified, use the window with this number or +--- window ID instead of the current window. +--- +--- Can also be used as a |method|: > +--- GetWin()->clearmatches() +--- < +--- @param win? any +--- @return any +function vim.fn.clearmatches(win) end + +--- The result is a Number, which is the byte index of the column +--- position given with {expr}. The accepted positions are: +--- . the cursor position +--- $ the end of the cursor line (the result is the +--- number of bytes in the cursor line plus one) +--- 'x position of mark x (if the mark is not set, 0 is +--- returned) +--- v In Visual mode: the start of the Visual area (the +--- cursor is the end). When not in Visual mode +--- returns the cursor position. Differs from |'<| in +--- that it's updated right away. +--- Additionally {expr} can be [lnum, col]: a |List| with the line +--- and column number. Most useful when the column is "$", to get +--- the last column of a specific line. When "lnum" or "col" is +--- out of range then col() returns zero. +--- With the optional {winid} argument the values are obtained for +--- that window instead of the current window. +--- To get the line number use |line()|. To get both use +--- |getpos()|. +--- For the screen column position use |virtcol()|. For the +--- character position use |charcol()|. +--- Note that only marks in the current file can be used. +--- Examples: > +--- col(".") column of cursor +--- col("$") length of cursor line plus one +--- col("'t") column of mark t +--- col("'" .. markname) column of mark markname +--- mapping the cursor isn't +--- moved, this can be used to obtain the column in Insert mode: > +--- :imap echo col(".").."\n" +--- +--- +--- GetPos()->col() +--- < +--- +--- @param expr any +--- @param winid? integer +--- @return integer +function vim.fn.col(expr, winid) end + +--- Set the matches for Insert mode completion. +--- Can only be used in Insert mode. You need to use a mapping +--- with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O +--- or with an expression mapping. +--- {startcol} is the byte offset in the line where the completed +--- text start. The text up to the cursor is the original text +--- that will be replaced by the matches. Use col('.') for an +--- empty string. "col('.') - 1" will replace one character by a +--- match. +--- {matches} must be a |List|. Each |List| item is one match. +--- See |complete-items| for the kind of items that are possible. +--- "longest" in 'completeopt' is ignored. +--- Note that the after calling this function you need to avoid +--- inserting anything that would cause completion to stop. +--- The match can be selected with CTRL-N and CTRL-P as usual with +--- Insert mode completion. The popup menu will appear if +--- specified, see |ins-completion-menu|. +--- Example: > +--- inoremap =ListMonths() +--- +--- func ListMonths() +--- call complete(col('.'), ['January', 'February', 'March', +--- \ 'April', 'May', 'June', 'July', 'August', 'September', +--- \ 'October', 'November', 'December']) +--- return '' +--- endfunc +--- +--- GetMatches()->complete(col('.')) +--- +--- @param startcol any +--- @param matches any +function vim.fn.complete(startcol, matches) end + +--- Add {expr} to the list of matches. Only to be used by the +--- function specified with the 'completefunc' option. +--- Returns 0 for failure (empty string or out of memory), +--- 1 when the match was added, 2 when the match was already in +--- the list. +--- See |complete-functions| for an explanation of {expr}. It is +--- the same as one item in the list that 'omnifunc' would return. +--- +--- Can also be used as a |method|: > +--- GetMoreMatches()->complete_add() +--- +--- @param expr any +--- @return 0|1|2 +function vim.fn.complete_add(expr) end + +--- Check for a key typed while looking for completion matches. +--- This is to be used when looking for matches takes some time. +--- Returns |TRUE| when searching for matches is to be aborted, +--- zero otherwise. +--- Only to be used by the function specified with the +--- 'completefunc' option. +--- +--- +--- @return 0|1 +function vim.fn.complete_check() end + +--- Returns a |Dictionary| with information about Insert mode +--- completion. See |ins-completion|. +--- The items are: +--- mode Current completion mode name string. +--- See |complete_info_mode| for the values. +--- pum_visible |TRUE| if popup menu is visible. +--- See |pumvisible()|. +--- items List of completion matches. Each item is a +--- dictionary containing the entries "word", +--- "abbr", "menu", "kind", "info" and "user_data". +--- See |complete-items|. +--- selected Selected item index. First index is zero. +--- Index is -1 if no item is selected (showing +--- typed text only, or the last completion after +--- no item is selected when using the or +--- keys) +--- inserted Inserted string. [NOT IMPLEMENTED YET] +--- +--- *complete_info_mode* +--- mode values are: +--- "" Not in completion mode +--- "keyword" Keyword completion |i_CTRL-X_CTRL-N| +--- "ctrl_x" Just pressed CTRL-X |i_CTRL-X| +--- "scroll" Scrolling with |i_CTRL-X_CTRL-E| or +--- |i_CTRL-X_CTRL-Y| +--- "whole_line" Whole lines |i_CTRL-X_CTRL-L| +--- "files" File names |i_CTRL-X_CTRL-F| +--- "tags" Tags |i_CTRL-X_CTRL-]| +--- "path_defines" Definition completion |i_CTRL-X_CTRL-D| +--- "path_patterns" Include completion |i_CTRL-X_CTRL-I| +--- "dictionary" Dictionary |i_CTRL-X_CTRL-K| +--- "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| +--- "cmdline" Vim Command line |i_CTRL-X_CTRL-V| +--- "function" User defined completion |i_CTRL-X_CTRL-U| +--- "omni" Omni completion |i_CTRL-X_CTRL-O| +--- "spell" Spelling suggestions |i_CTRL-X_s| +--- "eval" |complete()| completion +--- "unknown" Other internal modes +--- +--- If the optional {what} list argument is supplied, then only +--- the items listed in {what} are returned. Unsupported items in +--- {what} are silently ignored. +--- +--- To get the position and size of the popup menu, see +--- |pum_getpos()|. It's also available in |v:event| during the +--- |CompleteChanged| event. +--- +--- Returns an empty |Dictionary| on error. +--- +--- Examples: > +--- " Get all items +--- call complete_info() +--- " Get only 'mode' +--- call complete_info(['mode']) +--- " Get only 'mode' and 'pum_visible' +--- call complete_info(['mode', 'pum_visible']) +--- +--- +--- GetItems()->complete_info() +--- < +--- *confirm()* +--- @param what? any +--- @return table +function vim.fn.complete_info(what) end + +--- confirm() offers the user a dialog, from which a choice can be +--- made. It returns the number of the choice. For the first +--- choice this is 1. +--- +--- {msg} is displayed in a dialog with {choices} as the +--- alternatives. When {choices} is missing or empty, "&OK" is +--- used (and translated). +--- {msg} is a String, use '\n' to include a newline. Only on +--- some systems the string is wrapped when it doesn't fit. +--- +--- {choices} is a String, with the individual choices separated +--- by '\n', e.g. > +--- confirm("Save changes?", "&Yes\n&No\n&Cancel") +--- +--- confirm("file has been modified", "&Save\nSave &All") +--- , CTRL-C, +--- or another valid interrupt key, confirm() returns 0. +--- +--- An example: > +--- let choice = confirm("What do you want?", +--- \ "&Apples\n&Oranges\n&Bananas", 2) +--- if choice == 0 +--- echo "make up your mind!" +--- elseif choice == 3 +--- echo "tasteful" +--- else +--- echo "I prefer bananas myself." +--- endif +--- +--- BuildMessage()->confirm("&Yes\n&No") +--- < +--- *copy()* +--- @param msg any +--- @param choices? any +--- @param default? any +--- @param type? any +--- @return any +function vim.fn.confirm(msg, choices, default, type) end + +--- different from using {expr} directly. +--- When {expr} is a |List| a shallow copy is created. This means +--- that the original |List| can be changed without changing the +--- copy, and vice versa. But the items are identical, thus +--- changing an item changes the contents of both |Lists|. +--- A |Dictionary| is copied in a similar way as a |List|. +--- Also see |deepcopy()|. +--- Can also be used as a |method|: > +--- mylist->copy() +--- +--- @param expr any +--- @return any +function vim.fn.copy(expr) end + +--- 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|. +--- Examples: > +--- :echo cos(100) +--- < 0.862319 > +--- :echo cos(-4.01) +--- < -0.646043 +--- +--- Can also be used as a |method|: > +--- Compute()->cos() +--- +--- @param expr any +--- @return any +function vim.fn.cos(expr) end + +--- Return the hyperbolic cosine of {expr} as a |Float| in the range +--- [1, inf]. +--- {expr} must evaluate to a |Float| or a |Number|. +--- Returns 0.0 if {expr} is not a |Float| or a |Number|. +--- Examples: > +--- :echo cosh(0.5) +--- < 1.127626 > +--- :echo cosh(-0.5) +--- < -1.127626 +--- +--- Can also be used as a |method|: > +--- Compute()->cosh() +--- +--- @param expr any +--- @return any +function vim.fn.cosh(expr) end + +--- Return the number of times an item with value {expr} appears +--- in |String|, |List| or |Dictionary| {comp}. +--- +--- If {start} is given then start with the item with this index. +--- {start} can only be used with a |List|. +--- +--- When {ic} is given and it's |TRUE| then case is ignored. +--- +--- When {comp} is a string then the number of not overlapping +--- occurrences of {expr} is returned. Zero is returned when +--- {expr} is an empty string. +--- +--- Can also be used as a |method|: > +--- mylist->count(val) +--- < +--- @param comp any +--- @param expr any +--- @param ic? any +--- @param start? any +--- @return any +function vim.fn.count(comp, expr, ic, start) end + +--- Returns a |Dictionary| representing the |context| at {index} +--- from the top of the |context-stack| (see |context-dict|). +--- If {index} is not given, it is assumed to be 0 (i.e.: top). +--- +--- @param index? any +--- @return any +function vim.fn.ctxget(index) end + +--- Pops and restores the |context| at the top of the +--- |context-stack|. +--- +--- @return any +function vim.fn.ctxpop() end + +--- Pushes the current editor state (|context|) on the +--- |context-stack|. +--- If {types} is given and is a |List| of |String|s, it specifies +--- which |context-types| to include in the pushed context. +--- Otherwise, all context types are included. +--- +--- @param types? any +--- @return any +function vim.fn.ctxpush(types) end + +--- Sets the |context| at {index} from the top of the +--- |context-stack| to that represented by {context}. +--- {context} is a Dictionary with context data (|context-dict|). +--- If {index} is not given, it is assumed to be 0 (i.e.: top). +--- +--- @param context any +--- @param index? any +--- @return any +function vim.fn.ctxset(context, index) end + +--- Returns the size of the |context-stack|. +--- +--- @return any +function vim.fn.ctxsize() end + +--- Positions the cursor at the column (byte count) {col} in the +--- line {lnum}. The first column is one. +--- +--- When there is one argument {list} this is used as a |List| +--- with two, three or four item: +--- [{lnum}, {col}] +--- [{lnum}, {col}, {off}] +--- [{lnum}, {col}, {off}, {curswant}] +--- This is like the return value of |getpos()| or |getcurpos()|, +--- but without the first item. +--- +--- To position the cursor using {col} as the character count, use +--- |setcursorcharpos()|. +--- +--- Does not change the jumplist. +--- {lnum} is used like with |getline()|, except that if {lnum} is +--- zero, the cursor will stay in the current line. +--- If {lnum} is greater than the number of lines in the buffer, +--- the cursor will be positioned at the last line in the buffer. +--- If {col} is greater than the number of bytes in the line, +--- the cursor will be positioned at the last character in the +--- line. +--- If {col} is zero, the cursor will stay in the current column. +--- If {curswant} is given it is used to set the preferred column +--- for vertical movement. Otherwise {col} is used. +--- +--- When 'virtualedit' is used {off} specifies the offset in +--- screen columns from the start of the character. E.g., a +--- position within a or after the last character. +--- Returns 0 when the position could be set, -1 otherwise. +--- +--- Can also be used as a |method|: > +--- GetCursorPos()->cursor() +--- +--- @param list any +--- @return any +function vim.fn.cursor(list) end + +--- 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|. +--- (Sends a SIGINT to a process {pid} other than MS-Windows) +--- +--- Returns |TRUE| if successfully interrupted the program. +--- Otherwise returns |FALSE|. +--- +--- Can also be used as a |method|: > +--- GetPid()->debugbreak() +--- +--- @param pid any +--- @return any +function vim.fn.debugbreak(pid) end + +--- 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 +--- that the original |List| can be changed without changing the +--- copy, and vice versa. When an item is a |List|, a copy for it +--- is made, recursively. Thus changing an item in the copy does +--- not change the contents of the original |List|. +--- +--- When {noref} is omitted or zero a contained |List| or +--- |Dictionary| is only copied once. All references point to +--- this single copy. With {noref} set to 1 every occurrence of a +--- |List| or |Dictionary| results in a new copy. This also means +--- that a cyclic reference causes deepcopy() to fail. +--- *E724* +--- Nesting is possible up to 100 levels. When there is an item +--- that refers back to a higher level making a deep copy with +--- {noref} set to 1 will fail. +--- Also see |copy()|. +--- +--- Can also be used as a |method|: > +--- GetObject()->deepcopy() +--- +--- @param expr any +--- @param noref? any +--- @return any +function vim.fn.deepcopy(expr, noref) end + +--- Without {flags} or with {flags} empty: Deletes the file by the +--- name {fname}. +--- +--- This also works when {fname} is a symbolic link. The symbolic +--- link itself is deleted, not what it points to. +--- +--- When {flags} is "d": Deletes the directory by the name +--- {fname}. This fails when directory {fname} is not empty. +--- +--- When {flags} is "rf": Deletes the directory by the name +--- {fname} and everything in it, recursively. BE CAREFUL! +--- Note: on MS-Windows it is not possible to delete a directory +--- that is being used. +--- +--- The result is a Number, which is 0/false if the delete +--- operation was successful and -1/true when the deletion failed +--- or partly failed. +--- +--- Can also be used as a |method|: > +--- GetName()->delete() +--- +--- @param fname integer +--- @param flags? string +--- @return integer +function vim.fn.delete(fname, flags) end + +--- 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. +--- +--- This function works only for loaded buffers. First call +--- |bufload()| if needed. +--- +--- For the use of {buf}, see |bufname()| above. +--- +--- {first} and {last} are used like with |getline()|. Note that +--- when using |line()| this refers to the current buffer. Use "$" +--- to refer to the last line in buffer {buf}. +--- +--- Can also be used as a |method|: > +--- GetBuffer()->deletebufline(1) +--- < +--- @param buf any +--- @param first any +--- @param last? any +--- @return any +function vim.fn.deletebufline(buf, first, last) end + +--- Adds a watcher to a dictionary. A dictionary watcher is +--- identified by three components: +--- +--- - A dictionary({dict}); +--- - A key pattern({pattern}). +--- - A function({callback}). +--- +--- After this is called, every change on {dict} and on keys +--- matching {pattern} will result in {callback} being invoked. +--- +--- For example, to watch all global variables: > +--- silent! call dictwatcherdel(g:, '*', 'OnDictChanged') +--- function! OnDictChanged(d,k,z) +--- echomsg string(a:k) string(a:z) +--- endfunction +--- call dictwatcheradd(g:, '*', 'OnDictChanged') +--- < +--- For now {pattern} only accepts very simple patterns that can +--- contain a "*" at the end of the string, in which case it will +--- match every key that begins with the substring before the "*". +--- That means if "*" is not the last character of {pattern}, only +--- keys that are exactly equal as {pattern} will be matched. +--- +--- The {callback} receives three arguments: +--- +--- - The dictionary being watched. +--- - The key which changed. +--- - A dictionary containing the new and old values for the key. +--- +--- The type of change can be determined by examining the keys +--- present on the third argument: +--- +--- - If contains both `old` and `new`, the key was updated. +--- - If it contains only `new`, the key was added. +--- - If it contains only `old`, the key was deleted. +--- +--- This function can be used by plugins to implement options with +--- validation and parsing logic. +--- +--- @param dict any +--- @param pattern any +--- @param callback any +--- @return any +function vim.fn.dictwatcheradd(dict, pattern, callback) end + +--- Removes a watcher added with |dictwatcheradd()|. All three +--- arguments must match the ones passed to |dictwatcheradd()| in +--- order for the watcher to be successfully deleted. +--- +--- *did_filetype()* +--- @param dict any +--- @param pattern any +--- @param callback any +--- @return any +function vim.fn.dictwatcherdel(dict, pattern, callback) end + +--- FileType event has been triggered at least once. Can be used +--- to avoid triggering the FileType event again in the scripts +--- that detect the file type. |FileType| +--- Returns |FALSE| when `:setf FALLBACK` was used. +--- When editing another file, the counter is reset, thus this +--- really checks if the FileType event has been triggered for the +--- current buffer. This allows an autocommand that starts +--- editing another buffer to set 'filetype' and load a syntax +--- file. +--- +--- @return any +function vim.fn.did_filetype() end + +--- Returns the number of filler lines above line {lnum}. +--- These are the lines that were inserted at this point in +--- another diff'ed window. These filler lines are shown in the +--- display but don't exist in the buffer. +--- {lnum} is used like with |getline()|. Thus "." is the current +--- line, "'m" mark m, etc. +--- Returns 0 if the current window is not in diff mode. +--- +--- Can also be used as a |method|: > +--- GetLnum()->diff_filler() +--- +--- @param lnum integer +--- @return any +function vim.fn.diff_filler(lnum) end + +--- Returns the highlight ID for diff mode at line {lnum} column +--- {col} (byte index). When the current line does not have a +--- diff change zero is returned. +--- {lnum} is used like with |getline()|. Thus "." is the current +--- line, "'m" mark m, etc. +--- {col} is 1 for the leftmost column, {lnum} is 1 for the first +--- line. +--- The highlight ID can be used with |synIDattr()| to obtain +--- syntax information about the highlighting. +--- +--- Can also be used as a |method|: > +--- GetLnum()->diff_hlID(col) +--- < +--- +--- @param lnum integer +--- @param col integer +--- @return any +function vim.fn.diff_hlID(lnum, col) end + +--- Return the digraph of {chars}. This should be a string with +--- exactly two characters. If {chars} are not just two +--- characters, or the digraph of {chars} does not exist, an error +--- is given and an empty string is returned. +--- +--- Also see |digraph_getlist()|. +--- +--- Examples: > +--- " Get a built-in digraph +--- :echo digraph_get('00') " Returns '∞' +--- +--- " Get a user-defined digraph +--- :call digraph_set('aa', 'あ') +--- :echo digraph_get('aa') " Returns 'あ' +--- < +--- Can also be used as a |method|: > +--- GetChars()->digraph_get() +--- < +--- +--- @param chars any +--- @return any +function vim.fn.digraph_get(chars) end + +--- Return a list of digraphs. If the {listall} argument is given +--- and it is TRUE, return all digraphs, including the default +--- digraphs. Otherwise, return only user-defined digraphs. +--- +--- Also see |digraph_get()|. +--- +--- Examples: > +--- " Get user-defined digraphs +--- :echo digraph_getlist() +--- +--- " Get all the digraphs, including default digraphs +--- :echo digraph_getlist(1) +--- < +--- Can also be used as a |method|: > +--- GetNumber()->digraph_getlist() +--- < +--- +--- @param listall? any +--- @return any +function vim.fn.digraph_getlist(listall) end + +--- Add digraph {chars} to the list. {chars} must be a string +--- with two characters. {digraph} is a string with one UTF-8 +--- encoded character. *E1215* +--- Be careful, composing characters are NOT ignored. This +--- function is similar to |:digraphs| command, but useful to add +--- digraphs start with a white space. +--- +--- The function result is v:true if |digraph| is registered. If +--- this fails an error message is given and v:false is returned. +--- +--- If you want to define multiple digraphs at once, you can use +--- |digraph_setlist()|. +--- +--- Example: > +--- call digraph_set(' ', 'あ') +--- < +--- Can be used as a |method|: > +--- GetString()->digraph_set('あ') +--- < +--- +--- @param chars any +--- @param digraph any +--- @return any +function vim.fn.digraph_set(chars, digraph) end + +--- Similar to |digraph_set()| but this function can add multiple +--- digraphs at once. {digraphlist} is a list composed of lists, +--- where each list contains two strings with {chars} and +--- {digraph} as in |digraph_set()|. *E1216* +--- Example: > +--- call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) +--- < +--- It is similar to the following: > +--- for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] +--- call digraph_set(chars, digraph) +--- endfor +--- +--- GetList()->digraph_setlist() +--- < +--- +--- @param digraphlist any +--- @return any +function vim.fn.digraph_setlist(digraphlist) end + +--- Return the Number 1 if {expr} is empty, zero otherwise. +--- - A |List| or |Dictionary| is empty when it does not have any +--- items. +--- - A |String| is empty when its length is zero. +--- - A |Number| and |Float| are empty when their value is zero. +--- - |v:false| and |v:null| are empty, |v:true| is not. +--- - A |Blob| is empty when its length is zero. +--- +--- Can also be used as a |method|: > +--- mylist->empty() +--- +--- @param expr any +--- @return any +function vim.fn.empty(expr) end + +--- Return all of environment variables as dictionary. You can +--- check if an environment variable exists like this: > +--- :echo has_key(environ(), 'HOME') +--- +--- :echo index(keys(environ()), 'HOME', 0, 1) != -1 +--- +--- @return any +function vim.fn.environ() end + +--- Escape the characters in {chars} that occur in {string} with a +--- backslash. Example: > +--- :echo escape('c:\program files\vim', ' \') +--- +--- c:\\program\ files\\vim +--- +--- GetText()->escape(' \') +--- < +--- *eval()* +--- @param string string +--- @param chars any +--- @return any +function vim.fn.escape(string, chars) end + +--- turn the result of |string()| back into the original value. +--- This works for Numbers, Floats, Strings, Blobs and composites +--- of them. Also works for |Funcref|s that refer to existing +--- functions. +--- +--- Can also be used as a |method|: > +--- argv->join()->eval() +--- +--- @param string string +--- @return any +function vim.fn.eval(string) end + +--- Returns 1 when inside an event handler. That is that Vim got +--- interrupted while waiting for the user to type a character, +--- e.g., when dropping a file on Vim. This means interactive +--- commands cannot be used. Otherwise zero is returned. +--- +--- @return any +function vim.fn.eventhandler() end + +--- This function checks if an executable with the name {expr} +--- exists. {expr} must be the name of the program without any +--- arguments. +--- executable() uses the value of $PATH and/or the normal +--- searchpath for programs. *PATHEXT* +--- On MS-Windows the ".exe", ".bat", etc. can optionally be +--- included. Then the extensions in $PATHEXT are tried. Thus if +--- "foo.exe" does not exist, "foo.exe.bat" can be found. If +--- $PATHEXT is not set then ".exe;.com;.bat;.cmd" is used. A dot +--- by itself can be used in $PATHEXT to try using the name +--- without an extension. When 'shell' looks like a Unix shell, +--- then the name is also tried without adding an extension. +--- On MS-Windows it only checks if the file exists and is not a +--- directory, not if it's really executable. +--- On Windows an executable in the same directory as Vim is +--- always found (it is added to $PATH at |startup|). +--- The result is a Number: +--- 1 exists +--- 0 does not exist +--- -1 not implemented on this system +--- |exepath()| can be used to get the full path of an executable. +--- +--- Can also be used as a |method|: > +--- GetCommand()->executable() +--- +--- @param expr any +--- @return any +function vim.fn.executable(expr) end + +--- Execute {command} and capture its output. +--- If {command} is a |String|, returns {command} output. +--- If {command} is a |List|, returns concatenated outputs. +--- Line continuations in {command} are not recognized. +--- Examples: > +--- echo execute('echon "foo"') +--- < foo > +--- echo execute(['echon "foo"', 'echon "bar"']) +--- < foobar +--- +--- The optional {silent} argument can have these values: +--- "" no `:silent` used +--- "silent" `:silent` used +--- "silent!" `:silent!` used +--- The default is "silent". Note that with "silent!", unlike +--- `:redir`, error messages are dropped. +--- +--- To get a list of lines use `split()` on the result: > +--- execute('args')->split("\n") +--- +--- +--- GetCommand()->execute() +--- +--- @param command any +--- @param silent? boolean +--- @return any +function vim.fn.execute(command, silent) end + +--- Returns the full path of {expr} if it is an executable and +--- given as a (partial or full) path or is found in $PATH. +--- Returns empty string otherwise. +--- If {expr} starts with "./" the |current-directory| is used. +--- +--- Can also be used as a |method|: > +--- GetCommand()->exepath() +--- < +--- *exists()* +--- @param expr any +--- @return any +function vim.fn.exepath(expr) end + +--- defined, zero otherwise. +--- +--- For checking for a supported feature use |has()|. +--- For checking if a file exists use |filereadable()|. +--- +--- The {expr} argument is a string, which contains one of these: +--- varname internal variable (see +--- dict.key |internal-variables|). Also works +--- list[i] for |curly-braces-names|, |Dictionary| +--- entries, |List| items, etc. +--- Beware that evaluating an index may +--- cause an error message for an invalid +--- expression. E.g.: > +--- :let l = [1, 2, 3] +--- :echo exists("l[5]") +--- < 0 > +--- :echo exists("l[xx]") +--- < E121: Undefined variable: xx +--- 0 +--- &option-name Vim option (only checks if it exists, +--- not if it really works) +--- +option-name Vim option that works. +--- $ENVNAME environment variable (could also be +--- done by comparing with an empty +--- string) +--- `*funcname` built-in function (see |functions|) +--- or user defined function (see +--- |user-function|). Also works for a +--- variable that is a Funcref. +--- :cmdname Ex command: built-in command, user +--- command or command modifier |:command|. +--- Returns: +--- 1 for match with start of a command +--- 2 full match with a command +--- 3 matches several user commands +--- To check for a supported command +--- always check the return value to be 2. +--- :2match The |:2match| command. +--- :3match The |:3match| command (but you +--- probably should not use it, it is +--- reserved for internal usage) +--- #event autocommand defined for this event +--- #event#pattern autocommand defined for this event and +--- pattern (the pattern is taken +--- literally and compared to the +--- autocommand patterns character by +--- character) +--- #group autocommand group exists +--- #group#event autocommand defined for this group and +--- event. +--- #group#event#pattern +--- autocommand defined for this group, +--- event and pattern. +--- ##event autocommand for this event is +--- supported. +--- +--- Examples: > +--- exists("&mouse") +--- exists("$HOSTNAME") +--- exists("*strftime") +--- exists("*s:MyFunc") +--- exists("*MyFunc") +--- exists("bufcount") +--- exists(":Make") +--- exists("#CursorHold") +--- exists("#BufReadPre#*.gz") +--- exists("#filetypeindent") +--- exists("#filetypeindent#FileType") +--- exists("#filetypeindent#FileType#*") +--- exists("##ColorScheme") +--- +--- exists(":make") +--- +--- exists(":make install") +--- +--- +--- exists(bufcount) +--- +--- Varname()->exists() +--- +--- @param expr any +--- @return 0|1 +function vim.fn.exists(expr) end + +--- Return the exponential of {expr} as a |Float| in the range +--- [0, inf]. +--- {expr} must evaluate to a |Float| or a |Number|. +--- Returns 0.0 if {expr} is not a |Float| or a |Number|. +--- Examples: > +--- :echo exp(2) +--- < 7.389056 > +--- :echo exp(-1) +--- < 0.367879 +--- +--- Can also be used as a |method|: > +--- Compute()->exp() +--- +--- @param expr any +--- @return any +function vim.fn.exp(expr) end + +--- Expand wildcards and the following special keywords in +--- {string}. 'wildignorecase' applies. +--- +--- If {list} is given and it is |TRUE|, a List will be returned. +--- Otherwise the result is a String and when there are several +--- matches, they are separated by characters. +--- +--- If the expansion fails, the result is an empty string. A name +--- for a non-existing file is not included, unless {string} does +--- not start with '%', '#' or '<', see below. +--- +--- When {string} starts with '%', '#' or '<', the expansion is +--- done like for the |cmdline-special| variables with their +--- associated modifiers. Here is a short overview: +--- +--- % current file name +--- # alternate file name +--- #n alternate file name n +--- file name under the cursor +--- autocmd file name +--- autocmd buffer number (as a String!) +--- autocmd matched name +--- C expression under the cursor +--- sourced script file or function name +--- sourced script line number or function +--- line number +--- script file line number, also when in +--- a function +--- "123_" where "123" is the +--- current script ID || +---