From 42333ea98dfcd2994ee128a3467dfe68205154cd Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 28 Jul 2023 14:48:41 +0100 Subject: feat(docs): generate builtin.txt (#24493) - eval.lua is now the source of truth. - Formatting is much more consistent. - Fixed Lua type generation for polymorphic functions (get(), etc). - Removed "Overview" section from builtin.txt - Can generate this if we really want it. - Moved functions from sign.txt and testing.txt into builtin.txt. - Removed the *timer* *timers* tags since libuv timers via vim.uv should be preferred. - Removed the temp-file-name tag from tempname() - Moved lueval() from lua.txt to builtin.txt. * Fix indent * fixup! * fixup! fixup! * fixup! better tag formatting * fixup: revert changes no longer needed * fixup! CI --------- Co-authored-by: zeertzjq --- src/nvim/eval.lua | 13886 +++++++++++++++++++++++++++++++++++-- src/nvim/generators/gen_eval.lua | 12 +- 2 files changed, 13416 insertions(+), 482 deletions(-) (limited to 'src') diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 173c99e271..266873308c 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -3,6 +3,7 @@ -- Keys: -- --- @class vim.EvalFn +--- @field name? string --- @field args? integer|integer[] Number of arguments, list with maximum and minimum number of arguments --- or list with a minimum number of arguments only. Defaults to zero --- arguments. @@ -11,502 +12,13429 @@ --- Defaults to BASE_NONE (function cannot be used as a method). --- @field func? string Name of the C function which implements the Vimscript function. Defaults to --- `f_{funcname}`. +--- @field float_func? string --- @field fast? boolean Function can run in |api-fast| events. Defaults to false. ---- @field deprecated? string[] +--- @field deprecated? true --- @field returns? string|false +--- @field signature string +--- @field desc? string +--- @field params {[1]:string, [2]:string}[] +--- @field lua? false Do not render type information +--- @field tags? string[] Extra tags +--- @field data? string Used by gen_eval.lua -- Usable with the base key: use the last function argument as the method base. -- Value is from funcs.h file. "BASE_" prefix is omitted. -- local LAST = "BASE_LAST" (currently unused after port of v8.2.1168) -local VIMBOOL = '0|1' - -return { - --- @type table - funcs={ - abs={args=1, base=1}, - acos={args=1, base=1, float_func="acos", returns='number'}, -- WJMc - add={args=2, base=1}, - ['and']={args=2, base=1}, - api_info={fast=true}, - append={args=2, base=2}, - appendbufline={args=3, base=3}, - argc={args={0, 1}, returns='integer'}, - argidx={returns='integer'}, - arglistid={args={0, 2}, returns='integer'}, - argv={args={0, 2}}, - asin={args=1, base=1, float_func="asin"}, -- WJMc - assert_beeps={args=1, base=1, returns=VIMBOOL}, - assert_equal={args={2, 3}, base=2, returns=VIMBOOL}, - assert_equalfile={args={2, 3}, base=1}, - assert_exception={args={1, 2}, returns=VIMBOOL}, - assert_fails={args={1, 5}, base=1, returns=VIMBOOL}, - assert_false={args={1, 2}, base=1, returns=VIMBOOL}, - assert_inrange={args={3, 4}, base=3, returns=VIMBOOL}, - assert_match={args={2, 3}, base=2, returns=VIMBOOL}, - assert_nobeep={args=1, base=1, returns=VIMBOOL}, - assert_notequal={args={2, 3}, base=2}, - assert_notmatch={args={2, 3}, base=2}, - assert_report={args=1, base=1}, - assert_true={args={1, 2}, base=1}, - atan={args=1, base=1, float_func="atan", returns='number'}, - atan2={args=2, base=1, returns='number'}, - blob2list={args=1, base=1}, - browse={args=4}, - browsedir={args=2}, - bufadd={args=1, base=1, returns='integer'}, - bufexists={args=1, base=1, returns=VIMBOOL}, - buffer_exists={ - args=1, base=1, func='f_bufexists', - deprecated = { 'Obsolete name for |bufexists()|.' } +local M = {} + +local VARARGS = { { '...', 'any' } } + +--- @type table +M.funcs = { + abs = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'abs', + params = { { 'expr', 'any' } }, + signature = 'abs({expr})', + returns = 'number' + }, + acos = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + float_func = 'acos', + name = 'acos', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'acos({expr})', + }, + add = { + args = 2, + base = 1, + desc = [=[ + 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) + + ]=], + name = 'add', + params = { { 'object', 'any' }, { 'expr', 'any' } }, + returns = 'any', + signature = 'add({object}, {expr})', + }, + ['and'] = { + args = 2, + base = 1, + desc = [=[ + 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) + + ]=], + name = 'and', + params = { { 'expr', 'any' }, { 'expr', 'any' } }, + returns = 'integer', + signature = 'and({expr}, {expr})', + }, + api_info = { + desc = [=[ + Returns Dictionary of |api-metadata|. + + View it in a nice human-readable format: > + :lua vim.print(vim.fn.api_info()) + + ]=], + fast = true, + name = 'api_info', + params = {}, + returns = 'table', + signature = 'api_info()', + }, + append = { + args = 2, + base = 2, + desc = [=[ + 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) + + ]=], + name = 'append', + params = { { 'lnum', 'integer' }, { 'text', 'any' } }, + returns = '0|1', + signature = 'append({lnum}, {text})', + }, + appendbufline = { + args = 3, + base = 3, + desc = [=[ + 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) + + ]=], + name = 'appendbufline', + params = { { 'buf', 'any' }, { 'lnum', 'integer' }, { 'text', 'string' } }, + returns = '0|1', + signature = 'appendbufline({buf}, {lnum}, {text})', + }, + argc = { + args = { 0, 1 }, + desc = [=[ + 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. + ]=], + name = 'argc', + params = { { 'winid', 'integer' } }, + returns = 'integer', + signature = 'argc([{winid}])', + }, + argidx = { + desc = [=[ + The result is the current index in the argument list. 0 is + the first file. argc() - 1 is the last one. See |arglist|. + ]=], + name = 'argidx', + params = {}, + returns = 'integer', + signature = 'argidx()', + }, + arglistid = { + args = { 0, 2 }, + desc = [=[ + 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|. + ]=], + name = 'arglistid', + params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } }, + returns = 'integer', + signature = 'arglistid([{winnr} [, {tabnr}]])', + }, + argv = { + args = { 0, 2 }, + desc = [=[ + 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() + < + ]=], + float_func = 'asin', + name = 'asin', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'asin({expr})', + }, + assert_beeps = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'assert_beeps', + params = { { 'cmd', 'any' } }, + returns = '0|1', + signature = 'assert_beeps({cmd})', + }, + assert_equal = { + args = { 2, 3 }, + base = 2, + desc = [=[ + 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]) + ]=], + name = 'assert_equal', + params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_equal({expected}, {actual} [, {msg}])', + }, + assert_equalfile = { + args = { 2, 3 }, + base = 1, + desc = [=[ + 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') + ]=], + name = 'assert_equalfile', + params = {}, + returns = '0|1', + signature = 'assert_equalfile({fname-one}, {fname-two})', + }, + assert_exception = { + args = { 1, 2 }, + desc = [=[ + 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 + < + ]=], + name = 'assert_exception', + params = { { 'error', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_exception({error} [, {msg}])', + }, + assert_fails = { + args = { 1, 5 }, + base = 1, + desc = [=[ + 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:') + + ]=], + name = 'assert_fails', + params = { + { 'cmd', 'any' }, + { 'error', 'any' }, + { 'msg', 'any' }, + { 'lnum', 'integer' }, + { 'context', 'any' }, }, - buffer_name={ - args={0, 1}, base=1, func='f_bufname', - deprecated = { 'Obsolete name for |bufname()|.' } + returns = '0|1', + signature = 'assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])', + }, + assert_false = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'assert_false', + params = { { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_false({actual} [, {msg}])', + }, + assert_inrange = { + args = { 3, 4 }, + base = 3, + desc = [=[ + 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. + ]=], + name = 'assert_inrange', + params = { { 'lower', 'any' }, { 'upper', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_inrange({lower}, {upper}, {actual} [, {msg}])', + }, + assert_match = { + args = { 2, 3 }, + base = 2, + desc = [=[ + 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.*') + < + ]=], + name = 'assert_match', + params = { { 'pattern', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_match({pattern}, {actual} [, {msg}])', + }, + assert_nobeep = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'assert_nobeep', + params = { { 'cmd', 'any' } }, + returns = '0|1', + signature = 'assert_nobeep({cmd})', + }, + assert_notequal = { + args = { 2, 3 }, + base = 2, + desc = [=[ + 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]) + + < + ]=], + name = 'assert_notequal', + params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_notequal({expected}, {actual} [, {msg}])', + }, + assert_notmatch = { + args = { 2, 3 }, + base = 2, + desc = [=[ + 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.*') + < + ]=], + name = 'assert_notmatch', + params = { { 'pattern', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_notmatch({pattern}, {actual} [, {msg}])', + }, + assert_report = { + args = 1, + base = 1, + desc = [=[ + Report a test failure directly, using String {msg}. + Always returns one. + + Can also be used as a |method|: > + GetMessage()->assert_report() + < + ]=], + name = 'assert_report', + params = { { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_report({msg})', + }, + assert_true = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'assert_true', + params = { { 'actual', 'any' }, { 'msg', 'any' } }, + returns = '0|1', + signature = 'assert_true({actual} [, {msg}])', + }, + atan = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + float_func = 'atan', + name = 'atan', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'atan({expr})', + }, + atan2 = { + args = 2, + base = 1, + desc = [=[ + 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) + + ]=], + name = 'atan2', + params = { { 'expr1', 'any' }, { 'expr2', 'any' } }, + returns = 'number', + signature = 'atan2({expr1}, {expr2})', + }, + blob2list = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'blob2list', + params = { { 'blob', 'any' } }, + returns = 'any[]', + signature = 'blob2list({blob})', + }, + browse = { + args = 4, + desc = [=[ + 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. + ]=], + name = 'browse', + params = { { 'save', 'any' }, { 'title', 'any' }, { 'initdir', 'any' }, { 'default', 'any' } }, + returns = '0|1', + signature = 'browse({save}, {title}, {initdir}, {default})', + }, + browsedir = { + args = 2, + desc = [=[ + 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. + + ]=], + name = 'browsedir', + params = { { 'title', 'any' }, { 'initdir', 'any' } }, + returns = '0|1', + signature = 'browsedir({title}, {initdir})', + }, + bufadd = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufadd', + params = { { 'name', 'string' } }, + returns = 'integer', + signature = 'bufadd({name})', + }, + bufexists = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufexists', + params = { { 'buf', 'any' } }, + returns = '0|1', + signature = 'bufexists({buf})', + }, + buffer_exists = { + args = 1, + base = 1, + deprecated = true, + desc = [=[ + Obsolete name for |bufexists()|. + ]=], + func = 'f_bufexists', + name = 'buffer_exists', + params = VARARGS, + returns = '0|1', + signature = 'buffer_exists({buf})', + }, + buffer_name = { + args = { 0, 1 }, + base = 1, + deprecated = true, + desc = [=[ + Obsolete name for |bufname()|. + ]=], + func = 'f_bufname', + name = 'buffer_name', + params = VARARGS, + returns = 'string', + signature = 'buffer_name([{buf}])', + }, + buffer_number = { + args = { 0, 1 }, + base = 1, + deprecated = true, + desc = [=[ + Obsolete name for |bufnr()|. + ]=], + func = 'f_bufnr', + name = 'buffer_number', + params = VARARGS, + returns = 'integer', + signature = 'buffer_number([{buf} [, {create}]])', + }, + buflisted = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'buflisted', + params = { { 'buf', 'any' } }, + returns = '0|1', + signature = 'buflisted({buf})', + }, + bufload = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufload', + params = { { 'buf', 'any' } }, + returns = false, + signature = 'bufload({buf})', + }, + bufloaded = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufloaded', + params = { { 'buf', 'any' } }, + returns = '0|1', + signature = 'bufloaded({buf})', + }, + bufname = { + args = { 0, 1 }, + base = 1, + desc = [=[ + 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. + < + ]=], + name = 'bufname', + params = { { 'buf', 'any' } }, + returns = 'string', + signature = 'bufname([{buf}])', + }, + bufnr = { + args = { 0, 2 }, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufnr', + params = { { 'buf', 'any' }, { 'create', 'any' } }, + returns = 'integer', + signature = 'bufnr([{buf} [, {create}]])', + }, + bufwinid = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufwinid', + params = { { 'buf', 'any' } }, + returns = 'integer', + signature = 'bufwinid({buf})', + }, + bufwinnr = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'bufwinnr', + params = { { 'buf', 'any' } }, + returns = 'integer', + signature = 'bufwinnr({buf})', + }, + byte2line = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'byte2line', + params = { { 'byte', 'any' } }, + returns = 'integer', + signature = 'byte2line({byte})', + }, + byteidx = { + args = { 2, 3 }, + base = 1, + desc = [=[ + 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) + + ]=], + fast = true, + name = 'byteidx', + params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } }, + returns = 'integer', + signature = 'byteidx({expr}, {nr} [, {utf16}])', + }, + byteidxcomp = { + args = { 2, 3 }, + base = 1, + desc = [=[ + 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) + + ]=], + fast = true, + name = 'byteidxcomp', + params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } }, + returns = 'integer', + signature = 'byteidxcomp({expr}, {nr} [, {utf16}])', + }, + call = { + args = { 2, 3 }, + base = 1, + desc = [=[ + 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) + < + ]=], + name = 'call', + params = { { 'func', 'any' }, { 'arglist', 'any' }, { 'dict', 'any' } }, + returns = 'any', + signature = 'call({func}, {arglist} [, {dict}])', + tags = { 'E699' }, + }, + ceil = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + float_func = 'ceil', + name = 'ceil', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'ceil({expr})', + }, + chanclose = { + args = { 1, 2 }, + desc = [=[ + 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. + ]=], + name = 'chanclose', + params = { { 'id', 'any' }, { 'stream', 'any' } }, + returns = '0|1', + signature = 'chanclose({id} [, {stream}])', + }, + changenr = { + desc = [=[ + 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. + ]=], + name = 'changenr', + params = {}, + returns = 'integer', + signature = 'changenr()', + }, + chansend = { + args = 2, + desc = [=[ + 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. + + ]=], + name = 'chansend', + params = { { 'id', 'any' }, { 'data', 'any' } }, + returns = '0|1', + signature = 'chansend({id}, {data})', + }, + char2nr = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + + ]=], + fast = true, + name = 'char2nr', + params = { { 'string', 'string' }, { 'utf8', 'any' } }, + returns = '0|1', + signature = 'char2nr({string} [, {utf8}])', + }, + charclass = { + args = 1, + base = 1, + desc = [=[ + 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|. + ]=], + name = 'charclass', + params = { { 'string', 'string' } }, + returns = "0|1|2|3|'other'", + signature = 'charclass({string})', + }, + charcol = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'charcol', + params = { { 'expr', 'any' }, { 'winid', 'integer' } }, + returns = 'integer', + signature = 'charcol({expr} [, {winid}])', + }, + charidx = { + args = { 2, 4 }, + base = 1, + desc = [=[ + 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) + + ]=], + name = 'charidx', + params = { + { 'string', 'string' }, + { 'idx', 'integer' }, + { 'countcc', 'any' }, + { 'utf16', 'any' }, }, - buffer_number={ - args={0, 1}, base=1, func='f_bufnr', - deprecated = { 'Obsolete name for |bufnr()|.' } + returns = 'integer', + signature = 'charidx({string}, {idx} [, {countcc} [, {utf16}]])', + }, + chdir = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'chdir', + params = { { 'dir', 'string' } }, + returns = 'string', + signature = 'chdir({dir})', + }, + cindent = { + args = 1, + base = 1, + desc = [=[ + 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() + ]=], + name = 'cindent', + params = { { 'lnum', 'integer' } }, + returns = 'integer', + signature = 'cindent({lnum})', + }, + clearmatches = { + args = { 0, 1 }, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'clearmatches', + params = { { 'win', 'any' } }, + returns = false, + signature = 'clearmatches([{win}])', + }, + col = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + < + + ]=], + name = 'col', + params = { { 'expr', 'any' }, { 'winid', 'integer' } }, + returns = 'integer', + signature = 'col({expr} [, {winid}])', + }, + complete = { + args = 2, + base = 2, + desc = [=[ + 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('.')) + + ]=], + name = 'complete', + params = { { 'startcol', 'any' }, { 'matches', 'any' } }, + returns = false, + signature = 'complete({startcol}, {matches})', + tags = { 'E785' }, + }, + complete_add = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'complete_add', + params = { { 'expr', 'any' } }, + returns = '0|1|2', + signature = 'complete_add({expr})', + }, + complete_check = { + desc = [=[ + 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. + ]=], + name = 'complete_check', + params = {}, + returns = '0|1', + signature = 'complete_check()', + }, + complete_info = { + args = { 0, 1 }, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'complete_info', + params = { { 'what', 'any' } }, + returns = 'table', + signature = 'complete_info([{what}])', + }, + confirm = { + args = { 1, 4 }, + base = 1, + desc = [=[ + 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") + < + ]=], + name = 'confirm', + params = { { 'msg', 'any' }, { 'choices', 'any' }, { 'default', 'any' }, { 'type', 'any' } }, + returns = 'integer', + signature = 'confirm({msg} [, {choices} [, {default} [, {type}]]])', + }, + copy = { + args = 1, + base = 1, + desc = [=[ + 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 + 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() + ]=], + name = 'copy', + params = { { 'expr', 'any' } }, + returns = 'any', + signature = 'copy({expr})', + }, + cos = { + args = 1, + base = 1, + desc = [=[ + 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() + ]=], + float_func = 'cos', + name = 'cos', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'cos({expr})', + }, + cosh = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + float_func = 'cosh', + name = 'cosh', + params = { { 'expr', 'any' } }, + returns = 'number', + signature = 'cosh({expr})', + }, + count = { + args = { 2, 4 }, + base = 1, + desc = [=[ + 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) + < + ]=], + name = 'count', + params = { { 'comp', 'any' }, { 'expr', 'any' }, { 'ic', 'any' }, { 'start', 'any' } }, + returns = 'integer', + signature = 'count({comp}, {expr} [, {ic} [, {start}]])', + }, + ctxget = { + args = { 0, 1 }, + desc = [=[ + 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). + ]=], + name = 'ctxget', + params = { { 'index', 'any' } }, + returns = 'table', + signature = 'ctxget([{index}])', + }, + ctxpop = { + desc = [=[ + Pops and restores the |context| at the top of the + |context-stack|. + ]=], + name = 'ctxpop', + params = {}, + signature = 'ctxpop()', + }, + ctxpush = { + args = { 0, 1 }, + desc = [=[ + 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. + + ]=], + name = 'ctxpush', + params = { { 'types', 'any' } }, + signature = 'ctxpush([{types}])', + }, + ctxset = { + args = { 1, 2 }, + desc = [=[ + 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). + + ]=], + name = 'ctxset', + params = { { 'context', 'any' }, { 'index', 'any' } }, + signature = 'ctxset({context} [, {index}])', + }, + ctxsize = { + desc = [=[ + Returns the size of the |context-stack|. + + ]=], + name = 'ctxsize', + params = {}, + signature = 'ctxsize()', + }, + cursor = { + args = { 1, 3 }, + base = 1, + name = 'cursor', + params = { { 'lnum', 'integer' }, { 'col', 'integer' }, { 'off', 'any' } }, + signature = 'cursor({lnum}, {col} [, {off}])', + }, + cursor__1 = { + args = { 1, 3 }, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'cursor', + params = { { 'list', 'any' } }, + signature = 'cursor({list})', + }, + debugbreak = { + args = { 1, 1 }, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'debugbreak', + params = { { 'pid', 'any' } }, + signature = 'debugbreak({pid})', + }, + deepcopy = { + args = { 1, 2 }, + base = 1, + tags = { 'E698' }, + desc = [=[ + 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() + + ]=], + name = 'deepcopy', + params = { { 'expr', 'any' }, { 'noref', 'any' } }, + signature = 'deepcopy({expr} [, {noref}])', + }, + delete = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'delete', + params = { { 'fname', 'integer' }, { 'flags', 'string' } }, + returns = 'integer', + signature = 'delete({fname} [, {flags}])', + }, + deletebufline = { + args = { 2, 3 }, + base = 1, + desc = [=[ + 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) + < + ]=], + name = 'deletebufline', + params = { { 'buf', 'any' }, { 'first', 'any' }, { 'last', 'any' } }, + signature = 'deletebufline({buf}, {first} [, {last}])', + }, + dictwatcheradd = { + args = 3, + desc = [=[ + 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. + + ]=], + name = 'dictwatcheradd', + params = { { 'dict', 'any' }, { 'pattern', 'any' }, { 'callback', 'any' } }, + signature = 'dictwatcheradd({dict}, {pattern}, {callback})', + }, + dictwatcherdel = { + args = 3, + desc = [=[ + 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. + ]=], + name = 'dictwatcherdel', + params = { { 'dict', 'any' }, { 'pattern', 'any' }, { 'callback', 'any' } }, + signature = 'dictwatcherdel({dict}, {pattern}, {callback})', + }, + did_filetype = { + desc = [=[ + Returns |TRUE| when autocommands are being executed and the + 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. + + ]=], + fast = true, + name = 'did_filetype', + params = {}, + signature = 'did_filetype()', + }, + diff_filler = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'diff_filler', + params = { { 'lnum', 'integer' } }, + signature = 'diff_filler({lnum})', + }, + diff_hlID = { + args = 2, + base = 1, + desc = [=[ + 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) + < + + ]=], + name = 'diff_hlID', + params = { { 'lnum', 'integer' }, { 'col', 'integer' } }, + signature = 'diff_hlID({lnum}, {col})', + }, + digraph_get = { + args = 1, + base = 1, + tags = { 'E1214' }, + desc = [=[ + 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() + < + + ]=], + name = 'digraph_get', + params = { { 'chars', 'any' } }, + signature = 'digraph_get({chars})', + }, + digraph_getlist = { + args = { 0, 1 }, + base = 1, + desc = [=[ + 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() + < + + ]=], + name = 'digraph_getlist', + params = { { 'listall', 'any' } }, + signature = 'digraph_getlist([{listall}])', + }, + digraph_set = { + args = 2, + base = 1, + desc = [=[ + 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('あ') + < + + ]=], + name = 'digraph_set', + params = { { 'chars', 'any' }, { 'digraph', 'any' } }, + signature = 'digraph_set({chars}, {digraph})', + }, + digraph_setlist = { + args = 1, + base = 1, + desc = [=[ + 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() + < + + ]=], + name = 'digraph_setlist', + params = { { 'digraphlist', 'any' } }, + signature = 'digraph_setlist({digraphlist})', + }, + empty = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'empty', + params = { { 'expr', 'any' } }, + signature = 'empty({expr})', + }, + environ = { + desc = [=[ + 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 + + ]=], + fast = true, + name = 'environ', + params = {}, + signature = 'environ()', + }, + escape = { + args = 2, + base = 1, + desc = [=[ + 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(' \') + < + ]=], + fast = true, + name = 'escape', + params = { { 'string', 'string' }, { 'chars', 'any' } }, + signature = 'escape({string}, {chars})', + }, + eval = { + args = 1, + base = 1, + desc = [=[ + Evaluate {string} and return the result. Especially useful to + 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() + + ]=], + name = 'eval', + params = { { 'string', 'string' } }, + signature = 'eval({string})', + }, + eventhandler = { + desc = [=[ + 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. + + ]=], + name = 'eventhandler', + params = {}, + signature = 'eventhandler()', + }, + executable = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + fast = true, + name = 'executable', + params = { { 'expr', 'any' } }, + signature = 'executable({expr})', + }, + execute = { + args = { 1, 2 }, + base = 1, + desc = [=[ + 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() + + ]=], + name = 'execute', + params = { { 'command', 'any' }, { 'silent', 'boolean' } }, + signature = 'execute({command} [, {silent}])', + }, + exepath = { + args = 1, + base = 1, + desc = [=[ + 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() + < + ]=], + name = 'exepath', + params = { { 'expr', 'any' } }, + signature = 'exepath({expr})', + }, + exists = { + args = 1, + base = 1, + desc = [=[ + The result is a Number, which is |TRUE| if {expr} is + 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() + + ]=], + name = 'exists', + params = { { 'expr', 'any' } }, + returns = '0|1', + signature = 'exists({expr})', + }, + exp = { + args = 1, + base = 1, + desc = [=[ + 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() + + ]=], + float_func = 'exp', + name = 'exp', + params = { { 'expr', 'any' } }, + signature = 'exp({expr})', + }, + expand = { + args = { 1, 3 }, + base = 1, + desc = [=[ + 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 || +