--- @meta _ -- THIS FILE IS GENERATED -- DO NOT EDIT error('Cannot require a meta file') --- 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: >vim --- echo abs(1.456) --- < 1.456 >vim --- echo abs(-5.456) --- < 5.456 >vim --- echo abs(-4) --- < 4 --- --- @param expr any --- @return number 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: >vim --- echo acos(0) --- < 1.570796 >vim --- echo acos(-0.5) --- < 2.094395 --- --- @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: >vim --- let alist = add([1, 2, 3], item) --- call add(mylist, "woodstock") --- <Note that when {expr} is a |List| it is appended as a single --- item. Use |extend()| to concatenate |Lists|. --- When {object} is a |Blob| then {expr} must be a number. --- Use |insert()| to add an item at another position. --- Returns 1 if {object} is not a |List| or a |Blob|. --- --- @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: >vim --- let flag = and(bits, 0x80) --- < --- --- @param expr any --- @param expr1 any --- @return integer vim.fn['and'] = function(expr, expr1) end --- Returns Dictionary of |api-metadata|. --- --- View it in a nice human-readable format: >vim --- lua vim.print(vim.fn.api_info()) --- < --- --- @return table 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. When {text} is an empty list zero is returned, --- no matter the value of {lnum}. Example: >vim --- let failed = append(line('$'), "# THE END") --- let failed = append(0, ["Chapter 1", "the beginning"]) --- < --- --- @param lnum integer --- @param text any --- @return 0|1 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: >vim --- let failed = appendbufline(13, 0, "# THE START") --- <However, when {text} is an empty list then no error is given --- for an invalid {lnum}, since {lnum} isn't actually used. --- --- @param buf any --- @param lnum integer --- @param text string --- @return 0|1 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. --- --- @param winid? integer --- @return integer function vim.fn.argc(winid) end --- The result is the current index in the argument list. 0 is --- the first file. argc() - 1 is the last one. See |arglist|. --- --- @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|. --- --- @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: >vim --- let i = 0 --- while i < argc() --- let f = escape(fnameescape(argv(i)), '.') --- exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>' --- let i = i + 1 --- endwhile --- <Without the {nr} argument, or when {nr} is -1, a |List| with --- the whole |arglist| is returned. --- --- The {winid} argument specifies the window ID, see |argc()|. --- For the Vim command line arguments see |v:argv|. --- --- Returns an empty string if {nr}th argument is not present in --- the argument list. Returns an empty List if the {winid} --- argument is invalid. --- --- @param nr? integer --- @param winid? integer --- @return string|string[] function vim.fn.argv(nr, winid) end --- Return the arc sine of {expr} measured in radians, as a |Float| --- in the range of [-pi/2, pi/2]. --- {expr} must evaluate to a |Float| or a |Number| in the range --- [-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: >vim --- echo asin(0.8) --- < 0.927295 >vim --- echo asin(-0.5) --- < -0.523599 --- --- @param expr any --- @return number 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|. --- --- @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: >vim --- assert_equal('foo', 'bar') --- <Will result in a string to be added to |v:errors|: --- test.vim line 12: Expected 'foo' but got 'bar' ~ --- --- @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. --- --- @return 0|1 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: >vim --- try --- commandthatfails --- call assert_false(1, 'command should have failed') --- catch --- call assert_exception('E492:') --- endtry --- < --- --- @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:". >vim --- 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: >vim --- assert_fails('cmd', ['E987:.*expected bool']) --- <The second pattern, if present, is matched against the last --- reported error. To only match the last error use an empty --- string for the first error: >vim --- 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. --- --- @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. --- --- @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. --- --- @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: >vim --- assert_match('^f.*o$', 'foobar') --- <Will result in a string to be added to |v:errors|: --- test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ --- --- @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()|. --- --- @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|. --- --- @param expected any --- @param actual any --- @param msg? any --- @return 0|1 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|. --- --- @param pattern any --- @param actual any --- @param msg? any --- @return 0|1 function vim.fn.assert_notmatch(pattern, actual, msg) end --- Report a test failure directly, using String {msg}. --- Always returns one. --- --- @param msg any --- @return 0|1 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. --- --- @param actual any --- @param msg? any --- @return 0|1 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: >vim --- echo atan(100) --- < 1.560797 >vim --- echo atan(-4.01) --- < -1.326405 --- --- @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: >vim --- echo atan2(-1, 1) --- < -0.785398 >vim --- echo atan2(1, -1) --- < 2.356194 --- --- @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: >vim --- blob2list(0z0102.0304) " returns [1, 2, 3, 4] --- blob2list(0z) " returns [] --- <Returns an empty List on error. |list2blob()| does the --- opposite. --- --- @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. --- --- @param save any --- @param title any --- @param initdir any --- @param default any --- @return 0|1 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 0|1 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: >vim --- let bufnr = bufadd('someName') --- call bufload(bufnr) --- call setbufline(bufnr, 1, ['some', 'text']) --- <Returns 0 on error. --- --- @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. --- --- @param buf any --- @return 0|1 function vim.fn.bufexists(buf) end --- @deprecated --- Obsolete name for |bufexists()|. --- --- @param ... any --- @return 0|1 function vim.fn.buffer_exists(...) end --- @deprecated --- Obsolete name for |bufname()|. --- --- @param ... any --- @return string function vim.fn.buffer_name(...) end --- @deprecated --- Obsolete name for |bufnr()|. --- --- @param ... any --- @return integer 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()|. --- --- @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 then 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()|. --- --- @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()|. --- --- @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: >vim --- echo bufname("3" + 0) --- <If the buffer doesn't exist, or doesn't have a name, an empty --- string is returned. >vim --- echo bufname("#") " alternate buffer name --- echo bufname(3) " name of buffer 3 --- echo bufname("%") " name of current buffer --- echo bufname("file2") " name of buffer where "file2" matches. --- < --- --- @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: >vim --- let last_buffer = bufnr("$") --- <The result is a Number, which is the highest buffer number --- of existing buffers. Note that not all buffers with a smaller --- number necessarily exist, because ":bwipeout" may have removed --- them. Use bufexists() to test for the existence of a buffer. --- --- @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: >vim --- --- echo "A window containing buffer 1 is " .. (bufwinid(1)) --- < --- Only deals with the current tab page. See |win_findbuf()| for --- finding more. --- --- @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: >vim --- --- echo "A window containing buffer 1 is " .. (bufwinnr(1)) --- --- <The number can be used with |CTRL-W_w| and ":wincmd w" --- |:wincmd|. --- --- @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. --- --- @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 : >vim --- echo matchstr(str, ".", byteidx(str, 3)) --- <will display the fourth character. Another way to do the --- same: >vim --- let s = strpart(str, byteidx(str, 3)) --- echo strpart(s, 0, byteidx(s, 1)) --- <Also see |strgetchar()| and |strcharpart()|. --- --- If there are less than {nr} characters -1 is returned. --- If there are exactly {nr} characters the length of the string --- in bytes is returned. --- See |charidx()| and |utf16idx()| for getting the character and --- UTF-16 index respectively from the byte index. --- Examples: >vim --- echo byteidx('aππ', 2) " returns 5 --- echo byteidx('aππ', 2, 1) " returns 1 --- echo byteidx('aππ', 3, 1) " returns 5 --- < --- --- @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: >vim --- let s = 'e' .. nr2char(0x301) --- echo byteidx(s, 1) --- echo byteidxcomp(s, 1) --- echo byteidxcomp(s, 2) --- <The first and third echo result in 3 ('e' plus composing --- character is 3 bytes), the second echo results in 1 ('e' is --- one byte). --- --- @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| --- --- @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: >vim --- echo ceil(1.456) --- < 2.0 >vim --- echo ceil(-5.456) --- < -5.0 >vim --- echo ceil(4.0) --- < 4.0 --- --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- --- @param expr any --- @return number 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 0|1 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: >vim --- call chansend(id, ["abc", "123\n456", ""]) --- <will send "abc<NL>123<NUL>456<NL>". --- --- 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 0|1 function vim.fn.chansend(id, data) end --- Return Number value of the first char in {string}. --- Examples: >vim --- echo char2nr(" ") " returns 32 --- echo char2nr("ABC") " returns 65 --- echo char2nr("Γ‘") " returns 225 --- echo char2nr("Γ‘"[0]) " returns 195 --- echo char2nr("\<M-x>") " returns 128 --- <Non-ASCII characters are always treated as UTF-8 characters. --- {utf8} is ignored, it exists only for backwards-compatibility. --- A combining character is a separate character. --- |nr2char()| does the opposite. --- --- Returns 0 if {string} is not a |String|. --- --- @param string string --- @param utf8? any --- @return 0|1 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 0|1|2|3|'other' 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 "μ¬λ³΄μΈμ": >vim --- echo charcol('.') " returns 3 --- echo col('.') " returns 7 --- --- @param expr any --- @param winid? integer --- @return integer 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: >vim --- echo charidx('aΜbΜcΜ', 3) " returns 1 --- echo charidx('aΜbΜcΜ', 6, 1) " returns 4 --- echo charidx('aΜbΜcΜ', 16) " returns -1 --- echo charidx('aππ', 4, 0, 1) " returns 2 --- < --- --- @param string string --- @param idx integer --- @param countcc? any --- @param utf16? any --- @return integer 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: >vim --- let save_dir = chdir(newdir) --- if save_dir != "" --- " ... do some work --- call chdir(save_dir) --- endif --- --- @param dir string --- @return string 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|. --- --- @param lnum integer --- @return integer 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. --- --- @param win? 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: >vim --- echo col(".") " column of cursor --- echo col("$") " length of cursor line plus one --- echo col("'t") " column of mark t --- echo col("'" .. markname) " column of mark markname --- <The first column is 1. Returns 0 if {expr} is invalid or when --- the window with ID {winid} is not found. --- For an uppercase mark the column may actually be in another --- buffer. --- For the cursor position, when 'virtualedit' is active, the --- column is one higher if the cursor is after the end of the --- line. Also, when using a <Cmd> mapping the cursor isn't --- moved, this can be used to obtain the column in Insert mode: >vim --- imap <F2> <Cmd>echo col(".").."\n"<CR> --- --- @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: >vim --- inoremap <F5> <C-R>=ListMonths()<CR> --- --- func ListMonths() --- call complete(col('.'), ['January', 'February', 'March', --- \ 'April', 'May', 'June', 'July', 'August', 'September', --- \ 'October', 'November', 'December']) --- return '' --- endfunc --- <This isn't very useful, but it shows how it works. Note that --- an empty string is returned to avoid a zero being inserted. --- --- @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. --- --- @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 <Up> or --- <Down> 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: >vim --- " 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']) --- --- @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. >vim --- confirm("Save changes?", "&Yes\n&No\n&Cancel") --- <The letter after the '&' is the shortcut key for that choice. --- Thus you can type 'c' to select "Cancel". The shortcut does --- not need to be the first letter: >vim --- confirm("file has been modified", "&Save\nSave &All") --- <For the console, the first letter of each choice is used as --- the default shortcut key. Case is ignored. --- --- The optional {type} String argument gives the type of dialog. --- It can be one of these values: "Error", "Question", "Info", --- "Warning" or "Generic". Only the first character is relevant. --- When {type} is omitted, "Generic" is used. --- --- The optional {type} argument gives the type of dialog. This --- is only used for the icon of the Win32 GUI. It can be one of --- these values: "Error", "Question", "Info", "Warning" or --- "Generic". Only the first character is relevant. --- When {type} is omitted, "Generic" is used. --- --- If the user aborts the dialog by pressing <Esc>, CTRL-C, --- or another valid interrupt key, confirm() returns 0. --- --- An example: >vim --- 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 --- <In a GUI dialog, buttons are used. The layout of the buttons --- depends on the 'v' flag in 'guioptions'. If it is included, --- the buttons are always put vertically. Otherwise, confirm() --- tries to put the buttons in one horizontal line. If they --- don't fit, a vertical layout is used anyway. For some systems --- the horizontal layout is always used. --- --- @param msg any --- @param choices? any --- @param default? any --- @param type? any --- @return integer function vim.fn.confirm(msg, choices, default, type) end --- 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()|. --- --- @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: >vim --- echo cos(100) --- < 0.862319 >vim --- echo cos(-4.01) --- < -0.646043 --- --- @param expr any --- @return number 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: >vim --- echo cosh(0.5) --- < 1.127626 >vim --- echo cosh(-0.5) --- < -1.127626 --- --- @param expr any --- @return number 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. --- --- @param comp any --- @param expr any --- @param ic? any --- @param start? any --- @return integer 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 table 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 --- @param lnum integer --- @param col? integer --- @param off? any --- @return any function vim.fn.cursor(lnum, col, off) 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 <Tab> or after the last character. --- Returns 0 when the position could be set, -1 otherwise. --- --- @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|. --- --- @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()|. --- --- @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. --- --- @param fname string --- @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}. --- --- @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: >vim --- 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. --- --- @param dict any --- @param pattern any --- @param callback any --- @return any function vim.fn.dictwatcherdel(dict, pattern, callback) end --- 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. --- --- @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. --- --- @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. --- --- @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: >vim --- " Get a built-in digraph --- echo digraph_get('00') " Returns 'β' --- --- " Get a user-defined digraph --- call digraph_set('aa', 'γ') --- echo digraph_get('aa') " Returns 'γ' --- < --- --- @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: >vim --- " Get user-defined digraphs --- echo digraph_getlist() --- --- " Get all the digraphs, including default digraphs --- echo digraph_getlist(1) --- < --- --- @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: >vim --- call digraph_set(' ', 'γ') --- < --- Can be used as a |method|: >vim --- 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: >vim --- call digraph_setlist([['aa', 'γ'], ['ii', 'γ']]) --- < --- It is similar to the following: >vim --- for [chars, digraph] in [['aa', 'γ'], ['ii', 'γ']] --- call digraph_set(chars, digraph) --- endfor --- <Except that the function returns after the first error, --- following digraphs will not be added. --- --- Can be used as a |method|: >vim --- 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. --- --- @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: >vim --- echo has_key(environ(), 'HOME') --- <Note that the variable name may be CamelCase; to ignore case --- use this: >vim --- 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: >vim --- echo escape('c:\program files\vim', ' \') --- <results in: > --- c:\\program\ files\\vim --- <Also see |shellescape()| and |fnameescape()|. --- --- @param string string --- @param chars any --- @return any function vim.fn.escape(string, chars) end --- 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. --- --- @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. --- --- @param expr any --- @return 0|1|-1 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: >vim --- echo execute('echon "foo"') --- < foo >vim --- 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: >vim --- execute('args')->split("\n") --- --- <This function is not available in the |sandbox|. --- Note: If nested, an outer execute() will not observe output of --- the inner calls. --- Note: Text attributes (highlights) are not captured. --- To execute a command in another window than the current one --- use `win_execute()`. --- --- @param command string|string[] --- @param silent? ''|'silent'|'silent!' --- @return string 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. --- --- @param expr any --- @return any function vim.fn.exepath(expr) end --- 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.: >vim --- let l = [1, 2, 3] --- echo exists("l[5]") --- < 0 >vim --- 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: >vim --- echo exists("&mouse") --- echo exists("$HOSTNAME") --- echo exists("*strftime") --- echo exists("*s:MyFunc") --- echo exists("*MyFunc") --- echo exists("bufcount") --- echo exists(":Make") --- echo exists("#CursorHold") --- echo exists("#BufReadPre#*.gz") --- echo exists("#filetypeindent") --- echo exists("#filetypeindent#FileType") --- echo exists("#filetypeindent#FileType#*") --- echo exists("##ColorScheme") --- <There must be no space between the symbol (&/$/*/#) and the --- name. --- There must be no extra characters after the name, although in --- a few cases this is ignored. That may become stricter in the --- future, thus don't count on it! --- Working example: >vim --- echo exists(":make") --- <NOT working example: >vim --- echo exists(":make install") --- --- <Note that the argument must be a string, not the name of the --- variable itself. For example: >vim --- echo exists(bufcount) --- <This doesn't check for existence of the "bufcount" variable, --- but gets the value of "bufcount", and checks if that 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: >vim --- echo exp(2) --- < 7.389056 >vim --- echo exp(-1) --- < 0.367879 --- --- @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 <NL> 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 --- <cfile> file name under the cursor --- <afile> autocmd file name --- <abuf> autocmd buffer number (as a String!) --- <amatch> autocmd matched name --- <cexpr> C expression under the cursor --- <sfile> sourced script file or function name --- <slnum> sourced script line number or function --- line number --- <sflnum> script file line number, also when in --- a function --- <SID> "<SNR>123_" where "123" is the --- current script ID |<SID>| --- <script> sourced script file, or script file --- where the current function was defined --- <stack> call stack --- <cword> word under the cursor --- <cWORD> WORD under the cursor --- <client> the {clientid} of the last received --- message --- Modifiers: --- :p expand to full path --- :h head (last path component removed) --- :t tail (last path component only) --- :r root (one extension removed) --- :e extension only --- --- Example: >vim --- let &tags = expand("%:p:h") .. "/tags" --- <Note that when expanding a string that starts with '%', '#' or --- '<', any following text is ignored. This does NOT work: >vim --- let doesntwork = expand("%:h.bak") --- <Use this: >vim --- let doeswork = expand("%:h") .. ".bak" --- <Also note that expanding "<cfile>" and others only returns the --- referenced file name without further expansion. If "<cfile>" --- is "~/.cshrc", you need to do another expand() to have the --- "~/" expanded into the path of the home directory: >vim --- echo expand(expand("<cfile>")) --- < --- There cannot be white space between the variables and the --- following modifier. The |fnamemodify()| function can be used --- to modify normal file names. --- --- When using '%' or '#', and the current or alternate file name --- is not defined, an empty string is used. Using "%:p" in a --- buffer with no name, results in the current directory, with a --- '/' added. --- When 'verbose' is set then expanding '%', '#' and <> items --- will result in an error message if the argument cannot be --- expanded. --- --- When {string} does not start with '%', '#' or '<', it is --- expanded like a file name is expanded on the command line. --- 'suffixes' and 'wildignore' are used, unless the optional --- {nosuf} argument is given and it is |TRUE|. --- Names for non-existing files are included. The "**" item can --- be used to search in a directory tree. For example, to find --- all "README" files in the current directory and below: >vim --- echo expand("**/README") --- < --- expand() can also be used to expand variables and environment --- variables that are only known in a shell. But this can be --- slow, because a shell may be used to do the expansion. See --- |expr-env-expand|. --- The expanded variable is still handled like a list of file --- names. When an environment variable cannot be expanded, it is --- left unchanged. Thus ":echo expand('$FOOBAR')" results in --- "$FOOBAR". --- --- See |glob()| for finding existing files. See |system()| for --- getting the raw output of an external command. --- --- @param string string --- @param nosuf? boolean --- @param list? any --- @return string|string[] function vim.fn.expand(string, nosuf, list) end --- Expand special items in String {string} like what is done for --- an Ex command such as `:edit`. This expands special keywords, --- like with |expand()|, and environment variables, anywhere in --- {string}. "~user" and "~/path" are only expanded at the --- start. --- --- The following items are supported in the {options} Dict --- argument: --- errmsg If set to TRUE, error messages are displayed --- if an error is encountered during expansion. --- By default, error messages are not displayed. --- --- Returns the expanded string. If an error is encountered --- during expansion, the unmodified {string} is returned. --- --- Example: >vim --- echo expandcmd('make %<.o') --- < > --- make /path/runtime/doc/builtin.o --- < >vim --- echo expandcmd('make %<.o', {'errmsg': v:true}) --- < --- --- @param string string --- @param options? table --- @return any function vim.fn.expandcmd(string, options) end --- {expr1} and {expr2} must be both |Lists| or both --- |Dictionaries|. --- --- If they are |Lists|: Append {expr2} to {expr1}. --- If {expr3} is given insert the items of {expr2} before the --- item with index {expr3} in {expr1}. When {expr3} is zero --- insert before the first item. When {expr3} is equal to --- len({expr1}) then {expr2} is appended. --- Examples: >vim --- echo sort(extend(mylist, [7, 5])) --- call extend(mylist, [2, 3], 1) --- <When {expr1} is the same List as {expr2} then the number of --- items copied is equal to the original length of the List. --- E.g., when {expr3} is 1 you get N new copies of the first item --- (where N is the original length of the List). --- Use |add()| to concatenate one item to a list. To concatenate --- two lists into a new list use the + operator: >vim --- let newlist = [1, 2, 3] + [4, 5] --- < --- If they are |Dictionaries|: --- Add all entries from {expr2} to {expr1}. --- If a key exists in both {expr1} and {expr2} then {expr3} is --- used to decide what to do: --- {expr3} = "keep": keep the value of {expr1} --- {expr3} = "force": use the value of {expr2} --- {expr3} = "error": give an error message *E737* --- When {expr3} is omitted then "force" is assumed. --- --- {expr1} is changed when {expr2} is not empty. If necessary --- make a copy of {expr1} first. --- {expr2} remains unchanged. --- When {expr1} is locked and {expr2} is not empty the operation --- fails. --- Returns {expr1}. Returns 0 on error. --- --- @param expr1 any --- @param expr2 any --- @param expr3? any --- @return any function vim.fn.extend(expr1, expr2, expr3) end --- Like |extend()| but instead of adding items to {expr1} a new --- List or Dictionary is created and returned. {expr1} remains --- unchanged. --- --- @param expr1 any --- @param expr2 any --- @param expr3? any --- @return any function vim.fn.extendnew(expr1, expr2, expr3) end --- Characters in {string} are queued for processing as if they --- come from a mapping or were typed by the user. --- --- By default the string is added to the end of the typeahead --- buffer, thus if a mapping is still being executed the --- characters come after them. Use the 'i' flag to insert before --- other characters, they will be executed next, before any --- characters from a mapping. --- --- The function does not wait for processing of keys contained in --- {string}. --- --- To include special keys into {string}, use double-quotes --- and "\..." notation |expr-quote|. For example, --- feedkeys("\<CR>") simulates pressing of the <Enter> key. But --- feedkeys('\<CR>') pushes 5 characters. --- The |<Ignore>| keycode may be used to exit the --- wait-for-character without doing anything. --- --- {mode} is a String, which can contain these character flags: --- 'm' Remap keys. This is default. If {mode} is absent, --- keys are remapped. --- 'n' Do not remap keys. --- 't' Handle keys as if typed; otherwise they are handled as --- if coming from a mapping. This matters for undo, --- opening folds, etc. --- 'i' Insert the string instead of appending (see above). --- 'x' Execute commands until typeahead is empty. This is --- similar to using ":normal!". You can call feedkeys() --- several times without 'x' and then one time with 'x' --- (possibly with an empty {string}) to execute all the --- typeahead. Note that when Vim ends in Insert mode it --- will behave as if <Esc> is typed, to avoid getting --- stuck, waiting for a character to be typed before the --- script continues. --- Note that if you manage to call feedkeys() while --- executing commands, thus calling it recursively, then --- all typeahead will be consumed by the last call. --- '!' When used with 'x' will not end Insert mode. Can be --- used in a test when a timer is set to exit Insert mode --- a little later. Useful for testing CursorHoldI. --- --- Return value is always 0. --- --- @param string string --- @param mode? string --- @return any function vim.fn.feedkeys(string, mode) end --- @deprecated --- Obsolete name for |filereadable()|. --- --- @param file string --- @return any function vim.fn.file_readable(file) end --- The result is a Number, which is |TRUE| when a file with the --- name {file} exists, and can be read. If {file} doesn't exist, --- or is a directory, the result is |FALSE|. {file} is any --- expression, which is used as a String. --- If you don't care about the file being readable you can use --- |glob()|. --- {file} is used as-is, you may want to expand wildcards first: >vim --- echo filereadable('~/.vimrc') --- < > --- 0 --- < >vim --- echo filereadable(expand('~/.vimrc')) --- < > --- 1 --- < --- --- @param file string --- @return 0|1 function vim.fn.filereadable(file) end --- The result is a Number, which is 1 when a file with the --- name {file} exists, and can be written. If {file} doesn't --- exist, or is not writable, the result is 0. If {file} is a --- directory, and we can write to it, the result is 2. --- --- @param file string --- @return 0|1 function vim.fn.filewritable(file) end --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. --- For each item in {expr1} evaluate {expr2} and when the result --- is zero or false remove the item from the |List| or --- |Dictionary|. Similarly for each byte in a |Blob| and each --- character in a |String|. --- --- {expr2} must be a |string| or |Funcref|. --- --- If {expr2} is a |string|, inside {expr2} |v:val| has the value --- of the current item. For a |Dictionary| |v:key| has the key --- of the current item and for a |List| |v:key| has the index of --- the current item. For a |Blob| |v:key| has the index of the --- current byte. For a |String| |v:key| has the index of the --- current character. --- Examples: >vim --- call filter(mylist, 'v:val !~ "OLD"') --- <Removes the items where "OLD" appears. >vim --- call filter(mydict, 'v:key >= 8') --- <Removes the items with a key below 8. >vim --- call filter(var, 0) --- <Removes all the items, thus clears the |List| or |Dictionary|. --- --- Note that {expr2} is the result of expression and is then --- used as an expression again. Often it is good to use a --- |literal-string| to avoid having to double backslashes. --- --- If {expr2} is a |Funcref| it must take two arguments: --- 1. the key or the index of the current item. --- 2. the value of the current item. --- The function must return |TRUE| if the item should be kept. --- Example that keeps the odd items of a list: >vim --- func Odd(idx, val) --- return a:idx % 2 == 1 --- endfunc --- call filter(mylist, function('Odd')) --- <It is shorter when using a |lambda|: >vim --- call filter(myList, {idx, val -> idx * val <= 42}) --- <If you do not use "val" you can leave it out: >vim --- call filter(myList, {idx -> idx % 2 == 1}) --- < --- For a |List| and a |Dictionary| the operation is done --- in-place. If you want it to remain unmodified make a copy --- first: >vim --- let l = filter(copy(mylist), 'v:val =~ "KEEP"') --- --- <Returns {expr1}, the |List| or |Dictionary| that was filtered, --- or a new |Blob| or |String|. --- When an error is encountered while evaluating {expr2} no --- further items in {expr1} are processed. --- When {expr2} is a Funcref errors inside a function are ignored, --- unless it was defined with the "abort" flag. --- --- @param expr1 any --- @param expr2 any --- @return any function vim.fn.filter(expr1, expr2) end --- Find directory {name} in {path}. Supports both downwards and --- upwards recursive directory searches. See |file-searching| --- for the syntax of {path}. --- --- Returns the path of the first found match. When the found --- directory is below the current directory a relative path is --- returned. Otherwise a full path is returned. --- If {path} is omitted or empty then 'path' is used. --- --- If the optional {count} is given, find {count}'s occurrence of --- {name} in {path} instead of the first one. --- When {count} is negative return all the matches in a |List|. --- --- Returns an empty string if the directory is not found. --- --- This is quite similar to the ex-command `:find`. --- --- @param name string --- @param path? string --- @param count? any --- @return any function vim.fn.finddir(name, path, count) end --- Just like |finddir()|, but find a file instead of a directory. --- Uses 'suffixesadd'. --- Example: >vim --- echo findfile("tags.vim", ".;") --- <Searches from the directory of the current file upwards until --- it finds the file "tags.vim". --- --- @param name string --- @param path? string --- @param count? any --- @return any function vim.fn.findfile(name, path, count) end --- Flatten {list} up to {maxdepth} levels. Without {maxdepth} --- the result is a |List| without nesting, as if {maxdepth} is --- a very large number. --- The {list} is changed in place, use |flattennew()| if you do --- not want that. --- *E900* --- {maxdepth} means how deep in nested lists changes are made. --- {list} is not modified when {maxdepth} is 0. --- {maxdepth} must be positive number. --- --- If there is an error the number zero is returned. --- --- Example: >vim --- echo flatten([1, [2, [3, 4]], 5]) --- < [1, 2, 3, 4, 5] >vim --- echo flatten([1, [2, [3, 4]], 5], 1) --- < [1, 2, [3, 4], 5] --- --- @param list any --- @param maxdepth? any --- @return any[]|0 function vim.fn.flatten(list, maxdepth) end --- Like |flatten()| but first make a copy of {list}. --- --- @param list any --- @param maxdepth? any --- @return any[]|0 function vim.fn.flattennew(list, maxdepth) end --- Convert {expr} to a Number by omitting the part after the --- decimal point. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0 if {expr} is not a |Float| or a |Number|. --- When the value of {expr} is out of range for a |Number| the --- result is truncated to 0x7fffffff or -0x7fffffff (or when --- 64-bit Number support is enabled, 0x7fffffffffffffff or --- -0x7fffffffffffffff). NaN results in -0x80000000 (or when --- 64-bit Number support is enabled, -0x8000000000000000). --- Examples: >vim --- echo float2nr(3.95) --- < 3 >vim --- echo float2nr(-23.45) --- < -23 >vim --- echo float2nr(1.0e100) --- < 2147483647 (or 9223372036854775807) >vim --- echo float2nr(-1.0e150) --- < -2147483647 (or -9223372036854775807) >vim --- echo float2nr(1.0e-100) --- < 0 --- --- @param expr any --- @return any function vim.fn.float2nr(expr) end --- Return the largest integral value less than or equal to --- {expr} as a |Float| (round down). --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo floor(1.856) --- < 1.0 >vim --- echo floor(-5.456) --- < -6.0 >vim --- echo floor(4.0) --- < 4.0 --- --- @param expr any --- @return any function vim.fn.floor(expr) end --- Return the remainder of {expr1} / {expr2}, even if the --- division is not representable. Returns {expr1} - i * {expr2} --- for some integer i such that if {expr2} is non-zero, the --- result has the same sign as {expr1} and magnitude less than --- the magnitude of {expr2}. If {expr2} is zero, the value --- returned is zero. The value returned is a |Float|. --- {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: >vim --- echo fmod(12.33, 1.22) --- < 0.13 >vim --- echo fmod(-12.33, 1.22) --- < -0.13 --- --- @param expr1 any --- @param expr2 any --- @return any function vim.fn.fmod(expr1, expr2) end --- Escape {string} for use as file name command argument. All --- characters that have a special meaning, such as `'%'` and `'|'` --- are escaped with a backslash. --- For most systems the characters escaped are --- " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash --- appears in a filename, it depends on the value of 'isfname'. --- A leading '+' and '>' is also escaped (special after |:edit| --- and |:write|). And a "-" by itself (special after |:cd|). --- Returns an empty string on error. --- Example: >vim --- let fname = '+some str%nge|name' --- exe "edit " .. fnameescape(fname) --- <results in executing: >vim --- edit \+some\ str\%nge\|name --- < --- --- @param string string --- @return string function vim.fn.fnameescape(string) end --- Modify file name {fname} according to {mods}. {mods} is a --- string of characters like it is used for file names on the --- command line. See |filename-modifiers|. --- Example: >vim --- echo fnamemodify("main.c", ":p:h") --- <results in: > --- /home/user/vim/vim/src --- <If {mods} is empty or an unsupported modifier is used then --- {fname} is returned. --- When {fname} is empty then with {mods} ":h" returns ".", so --- that `:cd` can be used with it. This is different from --- expand('%:h') without a buffer name, which returns an empty --- string. --- Note: Environment variables don't work in {fname}, use --- |expand()| first then. --- --- @param fname string --- @param mods string --- @return string function vim.fn.fnamemodify(fname, mods) end --- The result is a Number. If the line {lnum} is in a closed --- fold, the result is the number of the first line in that fold. --- If the line {lnum} is not in a closed fold, -1 is returned. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- --- @param lnum integer --- @return integer function vim.fn.foldclosed(lnum) end --- The result is a Number. If the line {lnum} is in a closed --- fold, the result is the number of the last line in that fold. --- If the line {lnum} is not in a closed fold, -1 is returned. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- --- @param lnum integer --- @return integer function vim.fn.foldclosedend(lnum) end --- The result is a Number, which is the foldlevel of line {lnum} --- in the current buffer. For nested folds the deepest level is --- returned. If there is no fold at line {lnum}, zero is --- returned. It doesn't matter if the folds are open or closed. --- When used while updating folds (from 'foldexpr') -1 is --- returned for lines where folds are still to be updated and the --- foldlevel is unknown. As a special case the level of the --- previous line is usually available. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- --- @param lnum integer --- @return integer function vim.fn.foldlevel(lnum) end --- Returns a String, to be displayed for a closed fold. This is --- the default function used for the 'foldtext' option and should --- only be called from evaluating 'foldtext'. It uses the --- |v:foldstart|, |v:foldend| and |v:folddashes| variables. --- The returned string looks like this: > --- +-- 45 lines: abcdef --- <The number of leading dashes depends on the foldlevel. The --- "45" is the number of lines in the fold. "abcdef" is the text --- in the first non-blank line of the fold. Leading white space, --- "//" or "/*" and the text from the 'foldmarker' and --- 'commentstring' options is removed. --- When used to draw the actual foldtext, the rest of the line --- will be filled with the fold char from the 'fillchars' --- setting. --- Returns an empty string when there is no fold. --- --- @return string function vim.fn.foldtext() end --- Returns the text that is displayed for the closed fold at line --- {lnum}. Evaluates 'foldtext' in the appropriate context. --- When there is no closed fold at {lnum} an empty string is --- returned. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- Useful when exporting folded text, e.g., to HTML. --- --- @param lnum integer --- @return string function vim.fn.foldtextresult(lnum) end --- Get the full command name from a short abbreviated command --- name; see |20.2| for details on command abbreviations. --- --- The string argument {name} may start with a `:` and can --- include a [range], these are skipped and not returned. --- Returns an empty string if a command doesn't exist or if it's --- ambiguous (for user-defined commands). --- --- For example `fullcommand('s')`, `fullcommand('sub')`, --- `fullcommand(':%substitute')` all return "substitute". --- --- @param name string --- @return string function vim.fn.fullcommand(name) end --- Just like |function()|, but the returned Funcref will lookup --- the function by reference, not by name. This matters when the --- function {name} is redefined later. --- --- Unlike |function()|, {name} must be an existing user function. --- It only works for an autoloaded function if it has already --- been loaded (to avoid mistakenly loading the autoload script --- when only intending to use the function name, use |function()| --- instead). {name} cannot be a builtin function. --- Returns 0 on error. --- --- @param name string --- @param arglist? any --- @param dict? any --- @return any function vim.fn.funcref(name, arglist, dict) end --- Return a |Funcref| variable that refers to function {name}. --- {name} can be the name of a user defined function or an --- internal function. --- --- {name} can also be a Funcref or a partial. When it is a --- partial the dict stored in it will be used and the {dict} --- argument is not allowed. E.g.: >vim --- let FuncWithArg = function(dict.Func, [arg]) --- let Broken = function(dict.Func, [arg], dict) --- < --- When using the Funcref the function will be found by {name}, --- also when it was redefined later. Use |funcref()| to keep the --- same function. --- --- When {arglist} or {dict} is present this creates a partial. --- That means the argument list and/or the dictionary is stored in --- the Funcref and will be used when the Funcref is called. --- --- The arguments are passed to the function in front of other --- arguments, but after any argument from |method|. Example: >vim --- func Callback(arg1, arg2, name) --- "... --- endfunc --- let Partial = function('Callback', ['one', 'two']) --- "... --- call Partial('name') --- <Invokes the function as with: >vim --- call Callback('one', 'two', 'name') --- --- <With a |method|: >vim --- func Callback(one, two, three) --- "... --- endfunc --- let Partial = function('Callback', ['two']) --- "... --- eval 'one'->Partial('three') --- <Invokes the function as with: >vim --- call Callback('one', 'two', 'three') --- --- <The function() call can be nested to add more arguments to the --- Funcref. The extra arguments are appended to the list of --- arguments. Example: >vim --- func Callback(arg1, arg2, name) --- "... --- endfunc --- let Func = function('Callback', ['one']) --- let Func2 = function(Func, ['two']) --- "... --- call Func2('name') --- <Invokes the function as with: >vim --- call Callback('one', 'two', 'name') --- --- <The Dictionary is only useful when calling a "dict" function. --- In that case the {dict} is passed in as "self". Example: >vim --- function Callback() dict --- echo "called for " .. self.name --- endfunction --- "... --- let context = {"name": "example"} --- let Func = function('Callback', context) --- "... --- call Func() " will echo: called for example --- <The use of function() is not needed when there are no extra --- arguments, these two are equivalent, if Callback() is defined --- as context.Callback(): >vim --- let Func = function('Callback', context) --- let Func = context.Callback --- --- <The argument list and the Dictionary can be combined: >vim --- function Callback(arg1, count) dict --- "... --- endfunction --- let context = {"name": "example"} --- let Func = function('Callback', ['one'], context) --- "... --- call Func(500) --- <Invokes the function as with: >vim --- call context.Callback('one', 500) --- < --- Returns 0 on error. --- --- @param name string --- @param arglist? any --- @param dict? any --- @return any vim.fn['function'] = function(name, arglist, dict) end --- Cleanup unused |Lists| and |Dictionaries| that have circular --- references. --- --- There is hardly ever a need to invoke this function, as it is --- automatically done when Vim runs out of memory or is waiting --- for the user to press a key after 'updatetime'. Items without --- circular references are always freed when they become unused. --- This is useful if you have deleted a very big |List| and/or --- |Dictionary| with circular references in a script that runs --- for a long time. --- --- When the optional {atexit} argument is one, garbage --- collection will also be done when exiting Vim, if it wasn't --- done before. This is useful when checking for memory leaks. --- --- The garbage collection is not done immediately but only when --- it's safe to perform. This is when waiting for the user to --- type a character. --- --- @param atexit? any --- @return any function vim.fn.garbagecollect(atexit) end --- Get item {idx} from |List| {list}. When this item is not --- available return {default}. Return zero when {default} is --- omitted. --- --- @param list any[] --- @param idx integer --- @param default? any --- @return any function vim.fn.get(list, idx, default) end --- Get byte {idx} from |Blob| {blob}. When this byte is not --- available return {default}. Return -1 when {default} is --- omitted. --- --- @param blob string --- @param idx integer --- @param default? any --- @return any function vim.fn.get(blob, idx, default) end --- Get item with key {key} from |Dictionary| {dict}. When this --- item is not available return {default}. Return zero when --- {default} is omitted. Useful example: >vim --- let val = get(g:, 'var_name', 'default') --- <This gets the value of g:var_name if it exists, and uses --- "default" when it does not exist. --- --- @param dict table<string,any> --- @param key string --- @param default? any --- @return any function vim.fn.get(dict, key, default) end --- Get item {what} from Funcref {func}. Possible values for --- {what} are: --- "name" The function name --- "func" The function --- "dict" The dictionary --- "args" The list with arguments --- Returns zero on error. --- --- @param func function --- @param what string --- @return any function vim.fn.get(func, what) end --- @param buf? integer|string --- @return vim.fn.getbufinfo.ret.item[] function vim.fn.getbufinfo(buf) end --- Get information about buffers as a List of Dictionaries. --- --- Without an argument information about all the buffers is --- returned. --- --- When the argument is a |Dictionary| only the buffers matching --- the specified criteria are returned. The following keys can --- be specified in {dict}: --- buflisted include only listed buffers. --- bufloaded include only loaded buffers. --- bufmodified include only modified buffers. --- --- Otherwise, {buf} specifies a particular buffer to return --- information for. For the use of {buf}, see |bufname()| --- above. If the buffer is found the returned List has one item. --- Otherwise the result is an empty list. --- --- Each returned List item is a dictionary with the following --- entries: --- bufnr Buffer number. --- changed TRUE if the buffer is modified. --- changedtick Number of changes made to the buffer. --- hidden TRUE if the buffer is hidden. --- lastused Timestamp in seconds, like --- |localtime()|, when the buffer was --- last used. --- listed TRUE if the buffer is listed. --- lnum Line number used for the buffer when --- opened in the current window. --- Only valid if the buffer has been --- displayed in the window in the past. --- If you want the line number of the --- last known cursor position in a given --- window, use |line()|: >vim --- echo line('.', {winid}) --- < --- linecount Number of lines in the buffer (only --- valid when loaded) --- loaded TRUE if the buffer is loaded. --- name Full path to the file in the buffer. --- signs List of signs placed in the buffer. --- Each list item is a dictionary with --- the following fields: --- id sign identifier --- lnum line number --- name sign name --- variables A reference to the dictionary with --- buffer-local variables. --- windows List of |window-ID|s that display this --- buffer --- --- Examples: >vim --- for buf in getbufinfo() --- echo buf.name --- endfor --- for buf in getbufinfo({'buflisted':1}) --- if buf.changed --- " .... --- endif --- endfor --- < --- To get buffer-local options use: >vim --- getbufvar({bufnr}, '&option_name') --- < --- --- @param dict? vim.fn.getbufinfo.dict --- @return vim.fn.getbufinfo.ret.item[] function vim.fn.getbufinfo(dict) end --- Return a |List| with the lines starting from {lnum} to {end} --- (inclusive) in the buffer {buf}. If {end} is omitted, a --- |List| with only the line {lnum} is returned. See --- `getbufoneline()` for only getting the line. --- --- For the use of {buf}, see |bufname()| above. --- --- For {lnum} and {end} "$" can be used for the last line of the --- buffer. Otherwise a number must be used. --- --- When {lnum} is smaller than 1 or bigger than the number of --- lines in the buffer, an empty |List| is returned. --- --- When {end} is greater than the number of lines in the buffer, --- it is treated as {end} is set to the number of lines in the --- buffer. When {end} is before {lnum} an empty |List| is --- returned. --- --- This function works only for loaded buffers. For unloaded and --- non-existing buffers, an empty |List| is returned. --- --- Example: >vim --- let lines = getbufline(bufnr("myfile"), 1, "$") --- --- @param buf any --- @param lnum integer --- @param end_? integer --- @return any function vim.fn.getbufline(buf, lnum, end_) end --- Just like `getbufline()` but only get one line and return it --- as a string. --- --- @param buf integer|string --- @param lnum integer --- @return string function vim.fn.getbufoneline(buf, lnum) end --- The result is the value of option or local buffer variable --- {varname} in buffer {buf}. Note that the name without "b:" --- must be used. --- The {varname} argument is a string. --- When {varname} is empty returns a |Dictionary| with all the --- buffer-local variables. --- When {varname} is equal to "&" returns a |Dictionary| with all --- the buffer-local options. --- Otherwise, when {varname} starts with "&" returns the value of --- a buffer-local option. --- This also works for a global or buffer-local option, but it --- doesn't work for a global variable, window-local variable or --- window-local option. --- For the use of {buf}, see |bufname()| above. --- When the buffer or variable doesn't exist {def} or an empty --- string is returned, there is no error message. --- Examples: >vim --- let bufmodified = getbufvar(1, "&mod") --- echo "todo myvar = " .. getbufvar("todo", "myvar") --- --- @param buf any --- @param varname string --- @param def? any --- @return any function vim.fn.getbufvar(buf, varname, def) end --- Returns a |List| of cell widths of character ranges overridden --- by |setcellwidths()|. The format is equal to the argument of --- |setcellwidths()|. If no character ranges have their cell --- widths overridden, an empty List is returned. --- --- @return any function vim.fn.getcellwidths() end --- Returns the |changelist| for the buffer {buf}. For the use --- of {buf}, see |bufname()| above. If buffer {buf} doesn't --- exist, an empty list is returned. --- --- The returned list contains two entries: a list with the change --- locations and the current position in the list. Each --- entry in the change list is a dictionary with the following --- entries: --- col column number --- coladd column offset for 'virtualedit' --- lnum line number --- If buffer {buf} is the current buffer, then the current --- position refers to the position in the list. For other --- buffers, it is set to the length of the list. --- --- @param buf? integer|string --- @return table[] function vim.fn.getchangelist(buf) end --- Get a single character from the user or input stream. --- If [expr] is omitted, wait until a character is available. --- If [expr] is 0, only get a character when one is available. --- Return zero otherwise. --- If [expr] is 1, only check if a character is available, it is --- not consumed. Return zero if no character available. --- If you prefer always getting a string use |getcharstr()|. --- --- Without [expr] and when [expr] is 0 a whole character or --- special key is returned. If it is a single character, the --- result is a Number. Use |nr2char()| to convert it to a String. --- Otherwise a String is returned with the encoded character. --- For a special key it's a String with a sequence of bytes --- starting with 0x80 (decimal: 128). This is the same value as --- the String "\<Key>", e.g., "\<Left>". The returned value is --- also a String when a modifier (shift, control, alt) was used --- that is not included in the character. --- --- When [expr] is 0 and Esc is typed, there will be a short delay --- while Vim waits to see if this is the start of an escape --- sequence. --- --- When [expr] is 1 only the first byte is returned. For a --- one-byte character it is the character itself as a number. --- Use nr2char() to convert it to a String. --- --- Use getcharmod() to obtain any additional modifiers. --- --- When the user clicks a mouse button, the mouse event will be --- returned. The position can then be found in |v:mouse_col|, --- |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. --- |getmousepos()| can also be used. Mouse move events will be --- ignored. --- This example positions the mouse as it would normally happen: >vim --- let c = getchar() --- if c == "\<LeftMouse>" && v:mouse_win > 0 --- exe v:mouse_win .. "wincmd w" --- exe v:mouse_lnum --- exe "normal " .. v:mouse_col .. "|" --- endif --- < --- There is no prompt, you will somehow have to make clear to the --- user that a character has to be typed. The screen is not --- redrawn, e.g. when resizing the window. --- --- There is no mapping for the character. --- Key codes are replaced, thus when the user presses the <Del> --- key you get the code for the <Del> key, not the raw character --- sequence. Examples: >vim --- getchar() == "\<Del>" --- getchar() == "\<S-Left>" --- <This example redefines "f" to ignore case: >vim --- nmap f :call FindChar()<CR> --- function FindChar() --- let c = nr2char(getchar()) --- while col('.') < col('$') - 1 --- normal l --- if getline('.')[col('.') - 1] ==? c --- break --- endif --- endwhile --- endfunction --- < --- --- @return integer function vim.fn.getchar() end --- The result is a Number which is the state of the modifiers for --- the last obtained character with getchar() or in another way. --- These values are added together: --- 2 shift --- 4 control --- 8 alt (meta) --- 16 meta (when it's different from ALT) --- 32 mouse double click --- 64 mouse triple click --- 96 mouse quadruple click (== 32 + 64) --- 128 command (Macintosh only) --- Only the modifiers that have not been included in the --- character itself are obtained. Thus Shift-a results in "A" --- without a modifier. Returns 0 if no modifiers are used. --- --- @return integer function vim.fn.getcharmod() end --- Get the position for String {expr}. Same as |getpos()| but the --- column number in the returned List is a character index --- instead of a byte index. --- If |getpos()| returns a very large column number, equal to --- |v:maxcol|, then getcharpos() will return the character index --- of the last character. --- --- Example: --- With the cursor on 'μΈ' in line 5 with text "μ¬λ³΄μΈμ": >vim --- getcharpos('.') returns [0, 5, 3, 0] --- getpos('.') returns [0, 5, 7, 0] --- < --- --- @param expr any --- @return integer[] function vim.fn.getcharpos(expr) end --- Return the current character search information as a {dict} --- with the following entries: --- --- char character previously used for a character --- search (|t|, |f|, |T|, or |F|); empty string --- if no character search has been performed --- forward direction of character search; 1 for forward, --- 0 for backward --- until type of character search; 1 for a |t| or |T| --- character search, 0 for an |f| or |F| --- character search --- --- This can be useful to always have |;| and |,| search --- forward/backward regardless of the direction of the previous --- character search: >vim --- nnoremap <expr> ; getcharsearch().forward ? ';' : ',' --- nnoremap <expr> , getcharsearch().forward ? ',' : ';' --- <Also see |setcharsearch()|. --- --- @return table[] function vim.fn.getcharsearch() end --- Get a single character from the user or input stream as a --- string. --- If [expr] is omitted, wait until a character is available. --- If [expr] is 0 or false, only get a character when one is --- available. Return an empty string otherwise. --- If [expr] is 1 or true, only check if a character is --- available, it is not consumed. Return an empty string --- if no character is available. --- Otherwise this works like |getchar()|, except that a number --- result is converted to a string. --- --- @return string function vim.fn.getcharstr() end --- Return the type of the current command-line completion. --- Only works when the command line is being edited, thus --- requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. --- See |:command-completion| for the return string. --- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and --- |setcmdline()|. --- Returns an empty string when completion is not defined. --- --- @return string function vim.fn.getcmdcompltype() end --- Return the current command-line. Only works when the command --- line is being edited, thus requires use of |c_CTRL-\_e| or --- |c_CTRL-R_=|. --- Example: >vim --- cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> --- <Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and --- |setcmdline()|. --- Returns an empty string when entering a password or using --- |inputsecret()|. --- --- @return string function vim.fn.getcmdline() end --- Return the position of the cursor in the command line as a --- byte count. The first column is 1. --- Only works when editing the command line, thus requires use of --- |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. --- Returns 0 otherwise. --- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and --- |setcmdline()|. --- --- @return integer function vim.fn.getcmdpos() end --- Return the screen position of the cursor in the command line --- as a byte count. The first column is 1. --- Instead of |getcmdpos()|, it adds the prompt position. --- Only works when editing the command line, thus requires use of --- |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. --- Returns 0 otherwise. --- Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and --- |setcmdline()|. --- --- @return any function vim.fn.getcmdscreenpos() end --- Return the current command-line type. Possible return values --- are: --- : normal Ex command --- > debug mode command |debug-mode| --- / forward search command --- ? backward search command --- \@ |input()| command --- `-` |:insert| or |:append| command --- = |i_CTRL-R_=| --- Only works when editing the command line, thus requires use of --- |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. --- Returns an empty string otherwise. --- Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. --- --- @return ':'|'>'|'/'|'?'|'@'|'-'|'=' function vim.fn.getcmdtype() end --- Return the current |command-line-window| type. Possible return --- values are the same as |getcmdtype()|. Returns an empty string --- when not in the command-line window. --- --- @return ':'|'>'|'/'|'?'|'@'|'-'|'=' function vim.fn.getcmdwintype() end --- Return a list of command-line completion matches. The String --- {type} argument specifies what for. The following completion --- types are supported: --- --- arglist file names in argument list --- augroup autocmd groups --- buffer buffer names --- breakpoint |:breakadd| and |:breakdel| suboptions --- cmdline |cmdline-completion| result --- color color schemes --- command Ex command --- compiler compilers --- custom,{func} custom completion, defined via {func} --- customlist,{func} custom completion, defined via {func} --- diff_buffer |:diffget| and |:diffput| completion --- dir directory names --- environment environment variable names --- event autocommand events --- expression Vim expression --- file file and directory names --- file_in_path file and directory names in |'path'| --- filetype filetype names |'filetype'| --- function function name --- help help subjects --- highlight highlight groups --- history |:history| suboptions --- locale locale names (as output of locale -a) --- mapclear buffer argument --- mapping mapping name --- menu menus --- messages |:messages| suboptions --- option options --- packadd optional package |pack-add| names --- runtime |:runtime| completion --- scriptnames sourced script names |:scriptnames| --- shellcmd Shell command --- sign |:sign| suboptions --- syntax syntax file names |'syntax'| --- syntime |:syntime| suboptions --- tag tags --- tag_listfiles tags, file names --- user user names --- var user variables --- --- If {pat} is an empty string, then all the matches are --- returned. Otherwise only items matching {pat} are returned. --- See |wildcards| for the use of special characters in {pat}. --- --- If the optional {filtered} flag is set to 1, then 'wildignore' --- is applied to filter the results. Otherwise all the matches --- are returned. The 'wildignorecase' option always applies. --- --- If the 'wildoptions' option contains "fuzzy", then fuzzy --- matching is used to get the completion matches. Otherwise --- regular expression matching is used. Thus this function --- follows the user preference, what happens on the command line. --- If you do not want this you can make 'wildoptions' empty --- before calling getcompletion() and restore it afterwards. --- --- If {type} is "cmdline", then the |cmdline-completion| result is --- returned. For example, to complete the possible values after --- a ":call" command: >vim --- echo getcompletion('call ', 'cmdline') --- < --- If there are no matches, an empty list is returned. An --- invalid value for {type} produces an error. --- --- @param pat any --- @param type any --- @param filtered? any --- @return string[] function vim.fn.getcompletion(pat, type, filtered) end --- Get the position of the cursor. This is like getpos('.'), but --- includes an extra "curswant" item in the list: --- [0, lnum, col, off, curswant] ~ --- The "curswant" number is the preferred column when moving the --- cursor vertically. After |$| command it will be a very large --- number equal to |v:maxcol|. Also see |getcursorcharpos()| and --- |getpos()|. --- The first "bufnum" item is always zero. The byte position of --- the cursor is returned in "col". To get the character --- position, use |getcursorcharpos()|. --- --- The optional {winid} argument can specify the window. It can --- be the window number or the |window-ID|. The last known --- cursor position is returned, this may be invalid for the --- current value of the buffer if it is not the current window. --- If {winid} is invalid a list with zeroes is returned. --- --- This can be used to save and restore the cursor position: >vim --- let save_cursor = getcurpos() --- MoveTheCursorAround --- call setpos('.', save_cursor) --- <Note that this only works within the window. See --- |winrestview()| for restoring more state. --- --- @param winid? integer --- @return any function vim.fn.getcurpos(winid) end --- Same as |getcurpos()| but the column number in the returned --- List is a character index instead of a byte index. --- --- Example: --- With the cursor on '보' in line 3 with text "μ¬λ³΄μΈμ": >vim --- getcursorcharpos() " returns [0, 3, 2, 0, 3] --- getcurpos() " returns [0, 3, 4, 0, 3] --- < --- --- @param winid? integer --- @return any function vim.fn.getcursorcharpos(winid) end --- With no arguments, returns the name of the effective --- |current-directory|. With {winnr} or {tabnr} the working --- directory of that scope is returned, and 'autochdir' is --- ignored. --- Tabs and windows are identified by their respective numbers, --- 0 means current tab or window. Missing tab number implies 0. --- Thus the following are equivalent: >vim --- getcwd(0) --- getcwd(0, 0) --- <If {winnr} is -1 it is ignored, only the tab is resolved. --- {winnr} can be the window number or the |window-ID|. --- If both {winnr} and {tabnr} are -1 the global working --- directory is returned. --- Throw error if the arguments are invalid. |E5000| |E5001| |E5002| --- --- @param winnr? integer --- @param tabnr? integer --- @return string function vim.fn.getcwd(winnr, tabnr) end --- Return the value of environment variable {name}. The {name} --- argument is a string, without a leading '$'. Example: >vim --- myHome = getenv('HOME') --- --- <When the variable does not exist |v:null| is returned. That --- is different from a variable set to an empty string. --- See also |expr-env|. --- --- @param name string --- @return string function vim.fn.getenv(name) end --- Without an argument returns the name of the normal font being --- used. Like what is used for the Normal highlight group --- |hl-Normal|. --- With an argument a check is done whether String {name} is a --- valid font name. If not then an empty string is returned. --- Otherwise the actual font name is returned, or {name} if the --- GUI does not support obtaining the real name. --- Only works when the GUI is running, thus not in your vimrc or --- gvimrc file. Use the |GUIEnter| autocommand to use this --- function just after the GUI has started. --- --- @param name? string --- @return string function vim.fn.getfontname(name) end --- The result is a String, which is the read, write, and execute --- permissions of the given file {fname}. --- If {fname} does not exist or its directory cannot be read, an --- empty string is returned. --- The result is of the form "rwxrwxrwx", where each group of --- "rwx" flags represent, in turn, the permissions of the owner --- of the file, the group the file belongs to, and other users. --- If a user does not have a given permission the flag for this --- is replaced with the string "-". Examples: >vim --- echo getfperm("/etc/passwd") --- echo getfperm(expand("~/.config/nvim/init.vim")) --- <This will hopefully (from a security point of view) display --- the string "rw-r--r--" or even "rw-------". --- --- For setting permissions use |setfperm()|. --- --- @param fname string --- @return string function vim.fn.getfperm(fname) end --- The result is a Number, which is the size in bytes of the --- given file {fname}. --- If {fname} is a directory, 0 is returned. --- If the file {fname} can't be found, -1 is returned. --- If the size of {fname} is too big to fit in a Number then -2 --- is returned. --- --- @param fname string --- @return integer function vim.fn.getfsize(fname) end --- The result is a Number, which is the last modification time of --- the given file {fname}. The value is measured as seconds --- since 1st Jan 1970, and may be passed to strftime(). See also --- |localtime()| and |strftime()|. --- If the file {fname} can't be found -1 is returned. --- --- @param fname string --- @return integer function vim.fn.getftime(fname) end --- The result is a String, which is a description of the kind of --- file of the given file {fname}. --- If {fname} does not exist an empty string is returned. --- Here is a table over different kinds of files and their --- results: --- Normal file "file" --- Directory "dir" --- Symbolic link "link" --- Block device "bdev" --- Character device "cdev" --- Socket "socket" --- FIFO "fifo" --- All other "other" --- Example: >vim --- getftype("/home") --- <Note that a type such as "link" will only be returned on --- systems that support it. On some systems only "dir" and --- "file" are returned. --- --- @param fname string --- @return 'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other' function vim.fn.getftype(fname) end --- Returns the |jumplist| for the specified window. --- --- Without arguments use the current window. --- With {winnr} only use this window in the current tab page. --- {winnr} can also be a |window-ID|. --- With {winnr} and {tabnr} use the window in the specified tab --- page. If {winnr} or {tabnr} is invalid, an empty list is --- returned. --- --- The returned list contains two entries: a list with the jump --- locations and the last used jump position number in the list. --- Each entry in the jump location list is a dictionary with --- the following entries: --- bufnr buffer number --- col column number --- coladd column offset for 'virtualedit' --- filename filename if available --- lnum line number --- --- @param winnr? integer --- @param tabnr? integer --- @return vim.fn.getjumplist.ret function vim.fn.getjumplist(winnr, tabnr) end --- Without {end} the result is a String, which is line {lnum} --- from the current buffer. Example: >vim --- getline(1) --- <When {lnum} is a String that doesn't start with a --- digit, |line()| is called to translate the String into a Number. --- To get the line under the cursor: >vim --- getline(".") --- <When {lnum} is a number smaller than 1 or bigger than the --- number of lines in the buffer, an empty string is returned. --- --- When {end} is given the result is a |List| where each item is --- a line from the current buffer in the range {lnum} to {end}, --- including line {end}. --- {end} is used in the same way as {lnum}. --- Non-existing lines are silently omitted. --- When {end} is before {lnum} an empty |List| is returned. --- Example: >vim --- let start = line('.') --- let end = search("^$") - 1 --- let lines = getline(start, end) --- --- <To get lines from another buffer see |getbufline()| and --- |getbufoneline()| --- --- @param lnum integer --- @param end_? any --- @return string|string[] function vim.fn.getline(lnum, end_) end --- Returns a |List| with all the entries in the location list for --- window {nr}. {nr} can be the window number or the |window-ID|. --- When {nr} is zero the current window is used. --- --- For a location list window, the displayed location list is --- returned. For an invalid window number {nr}, an empty list is --- returned. Otherwise, same as |getqflist()|. --- --- If the optional {what} dictionary argument is supplied, then --- returns the items listed in {what} as a dictionary. Refer to --- |getqflist()| for the supported items in {what}. --- --- In addition to the items supported by |getqflist()| in {what}, --- the following item is supported by |getloclist()|: --- --- filewinid id of the window used to display files --- from the location list. This field is --- applicable only when called from a --- location list window. See --- |location-list-file-window| for more --- details. --- --- Returns a |Dictionary| with default values if there is no --- location list for the window {nr}. --- Returns an empty Dictionary if window {nr} does not exist. --- --- Examples (See also |getqflist-examples|): >vim --- echo getloclist(3, {'all': 0}) --- echo getloclist(5, {'filewinid': 0}) --- < --- --- @param nr integer --- @param what? any --- @return any function vim.fn.getloclist(nr, what) end --- Without the {buf} argument returns a |List| with information --- about all the global marks. |mark| --- --- If the optional {buf} argument is specified, returns the --- local marks defined in buffer {buf}. For the use of {buf}, --- see |bufname()|. If {buf} is invalid, an empty list is --- returned. --- --- Each item in the returned List is a |Dict| with the following: --- mark name of the mark prefixed by "'" --- pos a |List| with the position of the mark: --- [bufnum, lnum, col, off] --- Refer to |getpos()| for more information. --- file file name --- --- Refer to |getpos()| for getting information about a specific --- mark. --- --- @param buf? any --- @return any function vim.fn.getmarklist(buf) end --- Returns a |List| with all matches previously defined for the --- current window by |matchadd()| and the |:match| commands. --- |getmatches()| is useful in combination with |setmatches()|, --- as |setmatches()| can restore a list of matches saved by --- |getmatches()|. --- If {win} is specified, use the window with this number or --- window ID instead of the current window. If {win} is invalid, --- an empty list is returned. --- Example: >vim --- echo getmatches() --- < > --- [{"group": "MyGroup1", "pattern": "TODO", --- "priority": 10, "id": 1}, {"group": "MyGroup2", --- "pattern": "FIXME", "priority": 10, "id": 2}] --- < >vim --- let m = getmatches() --- call clearmatches() --- echo getmatches() --- < > --- [] --- < >vim --- call setmatches(m) --- echo getmatches() --- < > --- [{"group": "MyGroup1", "pattern": "TODO", --- "priority": 10, "id": 1}, {"group": "MyGroup2", --- "pattern": "FIXME", "priority": 10, "id": 2}] --- < >vim --- unlet m --- < --- --- @param win? any --- @return any function vim.fn.getmatches(win) end --- Returns a |Dictionary| with the last known position of the --- mouse. This can be used in a mapping for a mouse click. The --- items are: --- screenrow screen row --- screencol screen column --- winid Window ID of the click --- winrow row inside "winid" --- wincol column inside "winid" --- line text line inside "winid" --- column text column inside "winid" --- coladd offset (in screen columns) from the --- start of the clicked char --- All numbers are 1-based. --- --- If not over a window, e.g. when in the command line, then only --- "screenrow" and "screencol" are valid, the others are zero. --- --- When on the status line below a window or the vertical --- separator right of a window, the "line" and "column" values --- are zero. --- --- When the position is after the text then "column" is the --- length of the text in bytes plus one. --- --- If the mouse is over a focusable floating window then that --- window is used. --- --- When using |getchar()| the Vim variables |v:mouse_lnum|, --- |v:mouse_col| and |v:mouse_winid| also provide these values. --- --- @return vim.fn.getmousepos.ret function vim.fn.getmousepos() end --- Return a Number which is the process ID of the Vim process. --- This is a unique number, until Vim exits. --- --- @return integer function vim.fn.getpid() end --- Get the position for String {expr}. For possible values of --- {expr} see |line()|. For getting the cursor position see --- |getcurpos()|. --- The result is a |List| with four numbers: --- [bufnum, lnum, col, off] --- "bufnum" is zero, unless a mark like '0 or 'A is used, then it --- is the buffer number of the mark. --- "lnum" and "col" are the position in the buffer. The first --- column is 1. --- The "off" number is zero, unless 'virtualedit' is used. Then --- it is the offset in screen columns from the start of the --- character. E.g., a position within a <Tab> or after the last --- character. --- Note that for '< and '> Visual mode matters: when it is "V" --- (visual line mode) the column of '< is zero and the column of --- '> is a large number equal to |v:maxcol|. --- The column number in the returned List is the byte position --- within the line. To get the character position in the line, --- use |getcharpos()|. --- A very large column number equal to |v:maxcol| can be returned, --- in which case it means "after the end of the line". --- If {expr} is invalid, returns a list with all zeros. --- This can be used to save and restore the position of a mark: >vim --- let save_a_mark = getpos("'a") --- " ... --- call setpos("'a", save_a_mark) --- <Also see |getcharpos()|, |getcurpos()| and |setpos()|. --- --- @param expr string --- @return integer[] function vim.fn.getpos(expr) end --- Returns a |List| with all the current quickfix errors. Each --- list item is a dictionary with these entries: --- bufnr number of buffer that has the file name, use --- bufname() to get the name --- module module name --- lnum line number in the buffer (first line is 1) --- end_lnum --- end of line number if the item is multiline --- col column number (first column is 1) --- end_col end of column number if the item has range --- vcol |TRUE|: "col" is visual column --- |FALSE|: "col" is byte index --- nr error number --- pattern search pattern used to locate the error --- text description of the error --- type type of the error, 'E', '1', etc. --- valid |TRUE|: recognized error message --- user_data --- custom data associated with the item, can be --- any type. --- --- When there is no error list or it's empty, an empty list is --- returned. Quickfix list entries with a non-existing buffer --- number are returned with "bufnr" set to zero (Note: some --- functions accept buffer number zero for the alternate buffer, --- you may need to explicitly check for zero). --- --- Useful application: Find pattern matches in multiple files and --- do something with them: >vim --- vimgrep /theword/jg *.c --- for d in getqflist() --- echo bufname(d.bufnr) ':' d.lnum '=' d.text --- endfor --- < --- If the optional {what} dictionary argument is supplied, then --- returns only the items listed in {what} as a dictionary. The --- following string items are supported in {what}: --- changedtick get the total number of changes made --- to the list |quickfix-changedtick| --- context get the |quickfix-context| --- efm errorformat to use when parsing "lines". If --- not present, then the 'errorformat' option --- value is used. --- id get information for the quickfix list with --- |quickfix-ID|; zero means the id for the --- current list or the list specified by "nr" --- idx get information for the quickfix entry at this --- index in the list specified by "id" or "nr". --- If set to zero, then uses the current entry. --- See |quickfix-index| --- items quickfix list entries --- lines parse a list of lines using 'efm' and return --- the resulting entries. Only a |List| type is --- accepted. The current quickfix list is not --- modified. See |quickfix-parse|. --- nr get information for this quickfix list; zero --- means the current quickfix list and "$" means --- the last quickfix list --- qfbufnr number of the buffer displayed in the quickfix --- window. Returns 0 if the quickfix buffer is --- not present. See |quickfix-buffer|. --- size number of entries in the quickfix list --- title get the list title |quickfix-title| --- winid get the quickfix |window-ID| --- all all of the above quickfix properties --- Non-string items in {what} are ignored. To get the value of a --- particular item, set it to zero. --- If "nr" is not present then the current quickfix list is used. --- If both "nr" and a non-zero "id" are specified, then the list --- specified by "id" is used. --- To get the number of lists in the quickfix stack, set "nr" to --- "$" in {what}. The "nr" value in the returned dictionary --- contains the quickfix stack size. --- When "lines" is specified, all the other items except "efm" --- are ignored. The returned dictionary contains the entry --- "items" with the list of entries. --- --- The returned dictionary contains the following entries: --- changedtick total number of changes made to the --- list |quickfix-changedtick| --- context quickfix list context. See |quickfix-context| --- If not present, set to "". --- id quickfix list ID |quickfix-ID|. If not --- present, set to 0. --- idx index of the quickfix entry in the list. If not --- present, set to 0. --- items quickfix list entries. If not present, set to --- an empty list. --- nr quickfix list number. If not present, set to 0 --- qfbufnr number of the buffer displayed in the quickfix --- window. If not present, set to 0. --- size number of entries in the quickfix list. If not --- present, set to 0. --- title quickfix list title text. If not present, set --- to "". --- winid quickfix |window-ID|. If not present, set to 0 --- --- Examples (See also |getqflist-examples|): >vim --- echo getqflist({'all': 1}) --- echo getqflist({'nr': 2, 'title': 1}) --- echo getqflist({'lines' : ["F1:10:L10"]}) --- < --- --- @param what? any --- @return any function vim.fn.getqflist(what) end --- The result is a String, which is the contents of register --- {regname}. Example: >vim --- let cliptext = getreg('*') --- <When register {regname} was not set the result is an empty --- string. --- The {regname} argument must be a string. --- --- getreg('=') returns the last evaluated value of the expression --- register. (For use in maps.) --- getreg('=', 1) returns the expression itself, so that it can --- be restored with |setreg()|. For other registers the extra --- argument is ignored, thus you can always give it. --- --- If {list} is present and |TRUE|, the result type is changed --- to |List|. Each list item is one text line. Use it if you care --- about zero bytes possibly present inside register: without --- third argument both NLs and zero bytes are represented as NLs --- (see |NL-used-for-Nul|). --- When the register was not set an empty list is returned. --- --- If {regname} is not specified, |v:register| is used. --- --- @param regname? string --- @param list? any --- @return string|string[] function vim.fn.getreg(regname, list) end --- Returns detailed information about register {regname} as a --- Dictionary with the following entries: --- regcontents List of lines contained in register --- {regname}, like --- getreg({regname}, 1, 1). --- regtype the type of register {regname}, as in --- |getregtype()|. --- isunnamed Boolean flag, v:true if this register --- is currently pointed to by the unnamed --- register. --- points_to for the unnamed register, gives the --- single letter name of the register --- currently pointed to (see |quotequote|). --- For example, after deleting a line --- with `dd`, this field will be "1", --- which is the register that got the --- deleted text. --- --- The {regname} argument is a string. If {regname} is invalid --- or not set, an empty Dictionary will be returned. --- If {regname} is not specified, |v:register| is used. --- The returned Dictionary can be passed to |setreg()|. --- --- @param regname? string --- @return table function vim.fn.getreginfo(regname) end --- The result is a String, which is type of register {regname}. --- The value will be one of: --- "v" for |charwise| text --- "V" for |linewise| text --- "<CTRL-V>{width}" for |blockwise-visual| text --- "" for an empty or unknown register --- <CTRL-V> is one character with value 0x16. --- The {regname} argument is a string. If {regname} is not --- specified, |v:register| is used. --- --- @param regname? string --- @return string function vim.fn.getregtype(regname) end --- Returns a |List| with information about all the sourced Vim --- scripts in the order they were sourced, like what --- `:scriptnames` shows. --- --- The optional Dict argument {opts} supports the following --- optional items: --- name Script name match pattern. If specified, --- and "sid" is not specified, information about --- scripts with a name that match the pattern --- "name" are returned. --- sid Script ID |<SID>|. If specified, only --- information about the script with ID "sid" is --- returned and "name" is ignored. --- --- Each item in the returned List is a |Dict| with the following --- items: --- autoload Always set to FALSE. --- functions List of script-local function names defined in --- the script. Present only when a particular --- script is specified using the "sid" item in --- {opts}. --- name Vim script file name. --- sid Script ID |<SID>|. --- variables A dictionary with the script-local variables. --- Present only when a particular script is --- specified using the "sid" item in {opts}. --- Note that this is a copy, the value of --- script-local variables cannot be changed using --- this dictionary. --- version Vimscript version, always 1 --- --- Examples: >vim --- echo getscriptinfo({'name': 'myscript'}) --- echo getscriptinfo({'sid': 15}).variables --- < --- --- @param opts? table --- @return any function vim.fn.getscriptinfo(opts) end --- If {tabnr} is not specified, then information about all the --- tab pages is returned as a |List|. Each List item is a --- |Dictionary|. Otherwise, {tabnr} specifies the tab page --- number and information about that one is returned. If the tab --- page does not exist an empty List is returned. --- --- Each List item is a |Dictionary| with the following entries: --- tabnr tab page number. --- variables a reference to the dictionary with --- tabpage-local variables --- windows List of |window-ID|s in the tab page. --- --- @param tabnr? integer --- @return any function vim.fn.gettabinfo(tabnr) end --- Get the value of a tab-local variable {varname} in tab page --- {tabnr}. |t:var| --- Tabs are numbered starting with one. --- The {varname} argument is a string. When {varname} is empty a --- dictionary with all tab-local variables is returned. --- Note that the name without "t:" must be used. --- When the tab or variable doesn't exist {def} or an empty --- string is returned, there is no error message. --- --- @param tabnr integer --- @param varname string --- @param def? any --- @return any function vim.fn.gettabvar(tabnr, varname, def) end --- Get the value of window-local variable {varname} in window --- {winnr} in tab page {tabnr}. --- The {varname} argument is a string. When {varname} is empty a --- dictionary with all window-local variables is returned. --- When {varname} is equal to "&" get the values of all --- window-local options in a |Dictionary|. --- Otherwise, when {varname} starts with "&" get the value of a --- window-local option. --- Note that {varname} must be the name without "w:". --- Tabs are numbered starting with one. For the current tabpage --- use |getwinvar()|. --- {winnr} can be the window number or the |window-ID|. --- When {winnr} is zero the current window is used. --- This also works for a global option, buffer-local option and --- window-local option, but it doesn't work for a global variable --- or buffer-local variable. --- When the tab, window or variable doesn't exist {def} or an --- empty string is returned, there is no error message. --- Examples: >vim --- let list_is_on = gettabwinvar(1, 2, '&list') --- echo "myvar = " .. gettabwinvar(3, 1, 'myvar') --- < --- To obtain all window-local variables use: >vim --- gettabwinvar({tabnr}, {winnr}, '&') --- < --- --- @param tabnr integer --- @param winnr integer --- @param varname string --- @param def? any --- @return any function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end --- The result is a Dict, which is the tag stack of window {winnr}. --- {winnr} can be the window number or the |window-ID|. --- When {winnr} is not specified, the current window is used. --- When window {winnr} doesn't exist, an empty Dict is returned. --- --- The returned dictionary contains the following entries: --- curidx Current index in the stack. When at --- top of the stack, set to (length + 1). --- Index of bottom of the stack is 1. --- items List of items in the stack. Each item --- is a dictionary containing the --- entries described below. --- length Number of entries in the stack. --- --- Each item in the stack is a dictionary with the following --- entries: --- bufnr buffer number of the current jump --- from cursor position before the tag jump. --- See |getpos()| for the format of the --- returned list. --- matchnr current matching tag number. Used when --- multiple matching tags are found for a --- name. --- tagname name of the tag --- --- See |tagstack| for more information about the tag stack. --- --- @param winnr? integer --- @return any function vim.fn.gettagstack(winnr) end --- Translate String {text} if possible. --- This is mainly for use in the distributed Vim scripts. When --- generating message translations the {text} is extracted by --- xgettext, the translator can add the translated message in the --- .po file and Vim will lookup the translation when gettext() is --- called. --- For {text} double quoted strings are preferred, because --- xgettext does not understand escaping in single quoted --- strings. --- --- @param text any --- @return any function vim.fn.gettext(text) end --- Returns information about windows as a |List| with Dictionaries. --- --- If {winid} is given Information about the window with that ID --- is returned, as a |List| with one item. If the window does not --- exist the result is an empty list. --- --- Without {winid} information about all the windows in all the --- tab pages is returned. --- --- Each List item is a |Dictionary| with the following entries: --- botline last complete displayed buffer line --- bufnr number of buffer in the window --- height window height (excluding winbar) --- loclist 1 if showing a location list --- quickfix 1 if quickfix or location list window --- terminal 1 if a terminal window --- tabnr tab page number --- topline first displayed buffer line --- variables a reference to the dictionary with --- window-local variables --- width window width --- winbar 1 if the window has a toolbar, 0 --- otherwise --- wincol leftmost screen column of the window; --- "col" from |win_screenpos()| --- textoff number of columns occupied by any --- 'foldcolumn', 'signcolumn' and line --- number in front of the text --- winid |window-ID| --- winnr window number --- winrow topmost screen line of the window; --- "row" from |win_screenpos()| --- --- @param winid? integer --- @return vim.fn.getwininfo.ret.item[] function vim.fn.getwininfo(winid) end --- The result is a |List| with two numbers, the result of --- |getwinposx()| and |getwinposy()| combined: --- [x-pos, y-pos] --- {timeout} can be used to specify how long to wait in msec for --- a response from the terminal. When omitted 100 msec is used. --- --- Use a longer time for a remote terminal. --- When using a value less than 10 and no response is received --- within that time, a previously reported position is returned, --- if available. This can be used to poll for the position and --- do some work in the meantime: >vim --- while 1 --- let res = getwinpos(1) --- if res[0] >= 0 --- break --- endif --- " Do some work here --- endwhile --- < --- --- @param timeout? integer --- @return any function vim.fn.getwinpos(timeout) end --- The result is a Number, which is the X coordinate in pixels of --- the left hand side of the GUI Vim window. The result will be --- -1 if the information is not available. --- The value can be used with `:winpos`. --- --- @return integer function vim.fn.getwinposx() end --- The result is a Number, which is the Y coordinate in pixels of --- the top of the GUI Vim window. The result will be -1 if the --- information is not available. --- The value can be used with `:winpos`. --- --- @return integer function vim.fn.getwinposy() end --- Like |gettabwinvar()| for the current tabpage. --- Examples: >vim --- let list_is_on = getwinvar(2, '&list') --- echo "myvar = " .. getwinvar(1, 'myvar') --- --- @param winnr integer --- @param varname string --- @param def? any --- @return any function vim.fn.getwinvar(winnr, varname, def) end --- Expand the file wildcards in {expr}. See |wildcards| for the --- use of special characters. --- --- Unless the optional {nosuf} argument is given and is |TRUE|, --- the 'suffixes' and 'wildignore' options apply: Names matching --- one of the patterns in 'wildignore' will be skipped and --- 'suffixes' affect the ordering of matches. --- 'wildignorecase' always applies. --- --- When {list} is present and it is |TRUE| the result is a |List| --- with all matching files. The advantage of using a List is, --- you also get filenames containing newlines correctly. --- Otherwise the result is a String and when there are several --- matches, they are separated by <NL> characters. --- --- If the expansion fails, the result is an empty String or List. --- --- You can also use |readdir()| if you need to do complicated --- things, such as limiting the number of matches. --- --- A name for a non-existing file is not included. A symbolic --- link is only included if it points to an existing file. --- However, when the {alllinks} argument is present and it is --- |TRUE| then all symbolic links are included. --- --- For most systems backticks can be used to get files names from --- any external command. Example: >vim --- let tagfiles = glob("`find . -name tags -print`") --- let &tags = substitute(tagfiles, "\n", ",", "g") --- <The result of the program inside the backticks should be one --- item per line. Spaces inside an item are allowed. --- --- See |expand()| for expanding special Vim variables. See --- |system()| for getting the raw output of an external command. --- --- @param expr any --- @param nosuf? boolean --- @param list? any --- @param alllinks? any --- @return any function vim.fn.glob(expr, nosuf, list, alllinks) end --- Convert a file pattern, as used by glob(), into a search --- pattern. The result can be used to match with a string that --- is a file name. E.g. >vim --- if filename =~ glob2regpat('Make*.mak') --- " ... --- endif --- <This is equivalent to: >vim --- if filename =~ '^Make.*\.mak$' --- " ... --- endif --- <When {string} is an empty string the result is "^$", match an --- empty string. --- Note that the result depends on the system. On MS-Windows --- a backslash usually means a path separator. --- --- @param string string --- @return any function vim.fn.glob2regpat(string) end --- Perform glob() for String {expr} on all directories in {path} --- and concatenate the results. Example: >vim --- echo globpath(&rtp, "syntax/c.vim") --- < --- {path} is a comma-separated list of directory names. Each --- directory name is prepended to {expr} and expanded like with --- |glob()|. A path separator is inserted when needed. --- To add a comma inside a directory name escape it with a --- backslash. Note that on MS-Windows a directory may have a --- trailing backslash, remove it if you put a comma after it. --- If the expansion fails for one of the directories, there is no --- error message. --- --- Unless the optional {nosuf} argument is given and is |TRUE|, --- the 'suffixes' and 'wildignore' options apply: Names matching --- one of the patterns in 'wildignore' will be skipped and --- 'suffixes' affect the ordering of matches. --- --- When {list} is present and it is |TRUE| the result is a |List| --- with all matching files. The advantage of using a List is, you --- also get filenames containing newlines correctly. Otherwise --- the result is a String and when there are several matches, --- they are separated by <NL> characters. Example: >vim --- echo globpath(&rtp, "syntax/c.vim", 0, 1) --- < --- {allinks} is used as with |glob()|. --- --- The "**" item can be used to search in a directory tree. --- For example, to find all "README.txt" files in the directories --- in 'runtimepath' and below: >vim --- echo globpath(&rtp, "**/README.txt") --- <Upwards search and limiting the depth of "**" is not --- supported, thus using 'path' will not always work properly. --- --- @param path string --- @param expr any --- @param nosuf? boolean --- @param list? any --- @param allinks? any --- @return any function vim.fn.globpath(path, expr, nosuf, list, allinks) end --- Returns 1 if {feature} is supported, 0 otherwise. The --- {feature} argument is a feature name like "nvim-0.2.1" or --- "win32", see below. See also |exists()|. --- --- To get the system name use |vim.uv|.os_uname() in Lua: >lua --- print(vim.uv.os_uname().sysname) --- --- <If the code has a syntax error then Vimscript may skip the --- rest of the line. Put |:if| and |:endif| on separate lines to --- avoid the syntax error: >vim --- if has('feature') --- let x = this_breaks_without_the_feature() --- endif --- < --- Vim's compile-time feature-names (prefixed with "+") are not --- recognized because Nvim is always compiled with all possible --- features. |feature-compile| --- --- Feature names can be: --- 1. Nvim version. For example the "nvim-0.2.1" feature means --- that Nvim is version 0.2.1 or later: >vim --- if has("nvim-0.2.1") --- " ... --- endif --- --- <2. Runtime condition or other pseudo-feature. For example the --- "win32" feature checks if the current system is Windows: >vim --- if has("win32") --- " ... --- endif --- < *feature-list* --- List of supported pseudo-feature names: --- acl |ACL| support. --- bsd BSD system (not macOS, use "mac" for that). --- clipboard |clipboard| provider is available. --- fname_case Case in file names matters (for Darwin and MS-Windows --- this is not present). --- gui_running Nvim has a GUI. --- iconv Can use |iconv()| for conversion. --- linux Linux system. --- mac MacOS system. --- nvim This is Nvim. --- python3 Legacy Vim |python3| interface. |has-python| --- pythonx Legacy Vim |python_x| interface. |has-pythonx| --- sun SunOS system. --- ttyin input is a terminal (tty). --- ttyout output is a terminal (tty). --- unix Unix system. --- *vim_starting* True during |startup|. --- win32 Windows system (32 or 64 bit). --- win64 Windows system (64 bit). --- wsl WSL (Windows Subsystem for Linux) system. --- --- *has-patch* --- 3. Vim patch. For example the "patch123" feature means that --- Vim patch 123 at the current |v:version| was included: >vim --- if v:version > 602 || v:version == 602 && has("patch148") --- " ... --- endif --- --- <4. Vim version. For example the "patch-7.4.237" feature means --- that Nvim is Vim-compatible to version 7.4.237 or later. >vim --- if has("patch-7.4.237") --- " ... --- endif --- < --- --- @param feature any --- @return 0|1 function vim.fn.has(feature) end --- The result is a Number, which is TRUE if |Dictionary| {dict} --- has an entry with key {key}. FALSE otherwise. The {key} --- argument is a string. --- --- @param dict any --- @param key any --- @return 0|1 function vim.fn.has_key(dict, key) end --- The result is a Number, which is 1 when the window has set a --- local path via |:lcd| or when {winnr} is -1 and the tabpage --- has set a local path via |:tcd|, otherwise 0. --- --- Tabs and windows are identified by their respective numbers, --- 0 means current tab or window. Missing argument implies 0. --- Thus the following are equivalent: >vim --- echo haslocaldir() --- echo haslocaldir(0) --- echo haslocaldir(0, 0) --- <With {winnr} use that window in the current tabpage. --- With {winnr} and {tabnr} use the window in that tabpage. --- {winnr} can be the window number or the |window-ID|. --- If {winnr} is -1 it is ignored, only the tab is resolved. --- Throw error if the arguments are invalid. |E5000| |E5001| |E5002| --- --- @param winnr? integer --- @param tabnr? integer --- @return 0|1 function vim.fn.haslocaldir(winnr, tabnr) end --- The result is a Number, which is TRUE if there is a mapping --- that contains {what} in somewhere in the rhs (what it is --- mapped to) and this mapping exists in one of the modes --- indicated by {mode}. --- The arguments {what} and {mode} are strings. --- When {abbr} is there and it is |TRUE| use abbreviations --- instead of mappings. Don't forget to specify Insert and/or --- Command-line mode. --- Both the global mappings and the mappings local to the current --- buffer are checked for a match. --- If no matching mapping is found FALSE is returned. --- The following characters are recognized in {mode}: --- n Normal mode --- v Visual and Select mode --- x Visual mode --- s Select mode --- o Operator-pending mode --- i Insert mode --- l Language-Argument ("r", "f", "t", etc.) --- c Command-line mode --- When {mode} is omitted, "nvo" is used. --- --- This function is useful to check if a mapping already exists --- to a function in a Vim script. Example: >vim --- if !hasmapto('\ABCdoit') --- map <Leader>d \ABCdoit --- endif --- <This installs the mapping to "\ABCdoit" only if there isn't --- already a mapping to "\ABCdoit". --- --- @param what any --- @param mode? string --- @param abbr? any --- @return 0|1 function vim.fn.hasmapto(what, mode, abbr) end --- @deprecated --- Obsolete name for |hlID()|. --- --- @param name string --- @return any function vim.fn.highlightID(name) end --- @deprecated --- Obsolete name for |hlexists()|. --- --- @param name string --- @return any function vim.fn.highlight_exists(name) end --- Add the String {item} to the history {history} which can be --- one of: *hist-names* --- "cmd" or ":" command line history --- "search" or "/" search pattern history --- "expr" or "=" typed expression history --- "input" or "\@" input line history --- "debug" or ">" debug command history --- empty the current or last used history --- The {history} string does not need to be the whole name, one --- character is sufficient. --- If {item} does already exist in the history, it will be --- shifted to become the newest entry. --- The result is a Number: TRUE if the operation was successful, --- otherwise FALSE is returned. --- --- Example: >vim --- call histadd("input", strftime("%Y %b %d")) --- let date=input("Enter date: ") --- <This function is not available in the |sandbox|. --- --- @param history any --- @param item any --- @return 0|1 function vim.fn.histadd(history, item) end --- Clear {history}, i.e. delete all its entries. See |hist-names| --- for the possible values of {history}. --- --- If the parameter {item} evaluates to a String, it is used as a --- regular expression. All entries matching that expression will --- be removed from the history (if there are any). --- Upper/lowercase must match, unless "\c" is used |/\c|. --- If {item} evaluates to a Number, it will be interpreted as --- an index, see |:history-indexing|. The respective entry will --- be removed if it exists. --- --- The result is TRUE for a successful operation, otherwise FALSE --- is returned. --- --- Examples: --- Clear expression register history: >vim --- call histdel("expr") --- < --- Remove all entries starting with "*" from the search history: >vim --- call histdel("/", '^\*') --- < --- The following three are equivalent: >vim --- call histdel("search", histnr("search")) --- call histdel("search", -1) --- call histdel("search", '^' .. histget("search", -1) .. '$') --- < --- To delete the last search pattern and use the last-but-one for --- the "n" command and 'hlsearch': >vim --- call histdel("search", -1) --- let \@/ = histget("search", -1) --- < --- --- @param history any --- @param item? any --- @return 0|1 function vim.fn.histdel(history, item) end --- The result is a String, the entry with Number {index} from --- {history}. See |hist-names| for the possible values of --- {history}, and |:history-indexing| for {index}. If there is --- no such entry, an empty String is returned. When {index} is --- omitted, the most recent item from the history is used. --- --- Examples: --- Redo the second last search from history. >vim --- execute '/' .. histget("search", -2) --- --- <Define an Ex command ":H {num}" that supports re-execution of --- the {num}th entry from the output of |:history|. >vim --- command -nargs=1 H execute histget("cmd", 0+<args>) --- < --- --- @param history any --- @param index? any --- @return string function vim.fn.histget(history, index) end --- The result is the Number of the current entry in {history}. --- See |hist-names| for the possible values of {history}. --- If an error occurred, -1 is returned. --- --- Example: >vim --- let inp_index = histnr("expr") --- --- @param history any --- @return integer function vim.fn.histnr(history) end --- The result is a Number, which is the ID of the highlight group --- with name {name}. When the highlight group doesn't exist, --- zero is returned. --- This can be used to retrieve information about the highlight --- group. For example, to get the background color of the --- "Comment" group: >vim --- echo synIDattr(synIDtrans(hlID("Comment")), "bg") --- < --- --- @param name string --- @return integer function vim.fn.hlID(name) end --- The result is a Number, which is TRUE if a highlight group --- called {name} exists. This is when the group has been --- defined in some way. Not necessarily when highlighting has --- been defined for it, it may also have been used for a syntax --- item. --- --- @param name string --- @return 0|1 function vim.fn.hlexists(name) end --- The result is a String, which is the name of the machine on --- which Vim is currently running. Machine names greater than --- 256 characters long are truncated. --- --- @return string function vim.fn.hostname() end --- The result is a String, which is the text {string} converted --- from encoding {from} to encoding {to}. --- When the conversion completely fails an empty string is --- returned. When some characters could not be converted they --- are replaced with "?". --- The encoding names are whatever the iconv() library function --- can accept, see ":!man 3 iconv". --- Note that Vim uses UTF-8 for all Unicode encodings, conversion --- from/to UCS-2 is automatically changed to use UTF-8. You --- cannot use UCS-2 in a string anyway, because of the NUL bytes. --- --- @param string string --- @param from any --- @param to any --- @return any function vim.fn.iconv(string, from, to) end --- Returns a |String| which is a unique identifier of the --- container type (|List|, |Dict|, |Blob| and |Partial|). It is --- guaranteed that for the mentioned types `id(v1) ==# id(v2)` --- returns true iff `type(v1) == type(v2) && v1 is v2`. --- Note that `v:_null_string`, `v:_null_list`, `v:_null_dict` and --- `v:_null_blob` have the same `id()` with different types --- because they are internally represented as NULL pointers. --- `id()` returns a hexadecimal representanion of the pointers to --- the containers (i.e. like `0x994a40`), same as `printf("%p", --- {expr})`, but it is advised against counting on the exact --- format of the return value. --- --- It is not guaranteed that `id(no_longer_existing_container)` --- will not be equal to some other `id()`: new containers may --- reuse identifiers of the garbage-collected ones. --- --- @param expr any --- @return any function vim.fn.id(expr) end --- The result is a Number, which is indent of line {lnum} in the --- current buffer. 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. --- --- @param lnum integer --- @return integer function vim.fn.indent(lnum) end --- Find {expr} in {object} and return its index. See --- |indexof()| for using a lambda to select the item. --- --- If {object} is a |List| return the lowest index where the item --- has a value equal to {expr}. There is no automatic --- conversion, so 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 matters as indicated by --- the {ic} argument. --- --- If {object} is a |Blob| return the lowest index where the byte --- value is equal to {expr}. --- --- If {start} is given then start looking at the item with index --- {start} (may be negative for an item relative to the end). --- --- When {ic} is given and it is |TRUE|, ignore case. Otherwise --- case must match. --- --- -1 is returned when {expr} is not found in {object}. --- Example: >vim --- let idx = index(words, "the") --- if index(numbers, 123) >= 0 --- " ... --- endif --- --- @param object any --- @param expr any --- @param start? any --- @param ic? any --- @return any function vim.fn.index(object, expr, start, ic) end --- Returns the index of an item in {object} where {expr} is --- v:true. {object} must be a |List| or a |Blob|. --- --- If {object} is a |List|, evaluate {expr} for each item in the --- List until the expression is v:true and return the index of --- this item. --- --- If {object} is a |Blob| evaluate {expr} for each byte in the --- Blob until the expression is v:true and return the index of --- this byte. --- --- {expr} must be a |string| or |Funcref|. --- --- If {expr} is a |string|: If {object} is a |List|, inside --- {expr} |v:key| has the index of the current List item and --- |v:val| has the value of the item. If {object} is a |Blob|, --- inside {expr} |v:key| has the index of the current byte and --- |v:val| has the byte value. --- --- If {expr} is a |Funcref| it must take two arguments: --- 1. the key or the index of the current item. --- 2. the value of the current item. --- The function must return |TRUE| if the item is found and the --- search should stop. --- --- The optional argument {opts} is a Dict and supports the --- following items: --- startidx start evaluating {expr} at the item with this --- index; may be negative for an item relative to --- the end --- Returns -1 when {expr} evaluates to v:false for all the items. --- Example: >vim --- let l = [#{n: 10}, #{n: 20}, #{n: 30}] --- echo indexof(l, "v:val.n == 20") --- echo indexof(l, {i, v -> v.n == 30}) --- echo indexof(l, "v:val.n == 20", #{startidx: 1}) --- --- @param object any --- @param expr any --- @param opts? table --- @return any function vim.fn.indexof(object, expr, opts) end --- --- @param prompt any --- @param text? any --- @param completion? any --- @return any function vim.fn.input(prompt, text, completion) end --- The result is a String, which is whatever the user typed on --- the command-line. The {prompt} argument is either a prompt --- string, or a blank string (for no prompt). A '\n' can be used --- in the prompt to start a new line. --- --- In the second form it accepts a single dictionary with the --- following keys, any of which may be omitted: --- --- Key Default Description ~ --- prompt "" Same as {prompt} in the first form. --- default "" Same as {text} in the first form. --- completion nothing Same as {completion} in the first form. --- cancelreturn "" The value returned when the dialog is --- cancelled. --- highlight nothing Highlight handler: |Funcref|. --- --- The highlighting set with |:echohl| is used for the prompt. --- The input is entered just like a command-line, with the same --- editing commands and mappings. There is a separate history --- for lines typed for input(). --- Example: >vim --- if input("Coffee or beer? ") == "beer" --- echo "Cheers!" --- endif --- < --- If the optional {text} argument is present and not empty, this --- is used for the default reply, as if the user typed this. --- Example: >vim --- let color = input("Color? ", "white") --- --- <The optional {completion} argument specifies the type of --- completion supported for the input. Without it completion is --- not performed. The supported completion types are the same as --- that can be supplied to a user-defined command using the --- "-complete=" argument. Refer to |:command-completion| for --- more information. Example: >vim --- let fname = input("File: ", "", "file") --- --- < *input()-highlight* *E5400* *E5402* --- The optional `highlight` key allows specifying function which --- will be used for highlighting user input. This function --- receives user input as its only argument and must return --- a list of 3-tuples [hl_start_col, hl_end_col + 1, hl_group] --- where --- hl_start_col is the first highlighted column, --- hl_end_col is the last highlighted column (+ 1!), --- hl_group is |:hi| group used for highlighting. --- *E5403* *E5404* *E5405* *E5406* --- Both hl_start_col and hl_end_col + 1 must point to the start --- of the multibyte character (highlighting must not break --- multibyte characters), hl_end_col + 1 may be equal to the --- input length. Start column must be in range [0, len(input)), --- end column must be in range (hl_start_col, len(input)], --- sections must be ordered so that next hl_start_col is greater --- then or equal to previous hl_end_col. --- --- Example (try some input with parentheses): >vim --- highlight RBP1 guibg=Red ctermbg=red --- highlight RBP2 guibg=Yellow ctermbg=yellow --- highlight RBP3 guibg=Green ctermbg=green --- highlight RBP4 guibg=Blue ctermbg=blue --- let g:rainbow_levels = 4 --- function! RainbowParens(cmdline) --- let ret = [] --- let i = 0 --- let lvl = 0 --- while i < len(a:cmdline) --- if a:cmdline[i] is# '(' --- call add(ret, [i, i + 1, 'RBP' .. ((lvl % g:rainbow_levels) + 1)]) --- let lvl += 1 --- elseif a:cmdline[i] is# ')' --- let lvl -= 1 --- call add(ret, [i, i + 1, 'RBP' .. ((lvl % g:rainbow_levels) + 1)]) --- endif --- let i += 1 --- endwhile --- return ret --- endfunction --- call input({'prompt':'>','highlight':'RainbowParens'}) --- < --- Highlight function is called at least once for each new --- displayed input string, before command-line is redrawn. It is --- expected that function is pure for the duration of one input() --- call, i.e. it produces the same output for the same input, so --- output may be memoized. Function is run like under |:silent| --- modifier. If the function causes any errors, it will be --- skipped for the duration of the current input() call. --- --- Highlighting is disabled if command-line contains arabic --- characters. --- --- NOTE: This function must not be used in a startup file, for --- the versions that only run in GUI mode (e.g., the Win32 GUI). --- Note: When input() is called from within a mapping it will --- consume remaining characters from that mapping, because a --- mapping is handled like the characters were typed. --- Use |inputsave()| before input() and |inputrestore()| --- after input() to avoid that. Another solution is to avoid --- that further characters follow in the mapping, e.g., by using --- |:execute| or |:normal|. --- --- Example with a mapping: >vim --- nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR> --- function GetFoo() --- call inputsave() --- let g:Foo = input("enter search pattern: ") --- call inputrestore() --- endfunction --- --- @param opts table --- @return any function vim.fn.input(opts) end --- @deprecated --- Use |input()| instead. --- --- @param ... any --- @return any function vim.fn.inputdialog(...) end --- {textlist} must be a |List| of strings. This |List| is --- displayed, one string per line. The user will be prompted to --- enter a number, which is returned. --- The user can also select an item by clicking on it with the --- mouse, if the mouse is enabled in the command line ('mouse' is --- "a" or includes "c"). For the first string 0 is returned. --- When clicking above the first item a negative number is --- returned. When clicking on the prompt one more than the --- length of {textlist} is returned. --- Make sure {textlist} has less than 'lines' entries, otherwise --- it won't work. It's a good idea to put the entry number at --- the start of the string. And put a prompt in the first item. --- Example: >vim --- let color = inputlist(['Select color:', '1. red', --- \ '2. green', '3. blue']) --- --- @param textlist any --- @return any function vim.fn.inputlist(textlist) end --- Restore typeahead that was saved with a previous |inputsave()|. --- Should be called the same number of times inputsave() is --- called. Calling it more often is harmless though. --- Returns TRUE when there is nothing to restore, FALSE otherwise. --- --- @return any function vim.fn.inputrestore() end --- Preserve typeahead (also from mappings) and clear it, so that --- a following prompt gets input from the user. Should be --- followed by a matching inputrestore() after the prompt. Can --- be used several times, in which case there must be just as --- many inputrestore() calls. --- Returns TRUE when out of memory, FALSE otherwise. --- --- @return any function vim.fn.inputsave() end --- This function acts much like the |input()| function with but --- two exceptions: --- a) the user's response will be displayed as a sequence of --- asterisks ("*") thereby keeping the entry secret, and --- b) the user's response will not be recorded on the input --- |history| stack. --- The result is a String, which is whatever the user actually --- typed on the command-line in response to the issued prompt. --- NOTE: Command-line completion is not supported. --- --- @param prompt any --- @param text? any --- @return any function vim.fn.inputsecret(prompt, text) end --- When {object} is a |List| or a |Blob| insert {item} at the start --- of it. --- --- If {idx} is specified insert {item} before the item with index --- {idx}. If {idx} is zero it goes before the first item, just --- like omitting {idx}. A negative {idx} is also possible, see --- |list-index|. -1 inserts just before the last item. --- --- Returns the resulting |List| or |Blob|. Examples: >vim --- let mylist = insert([2, 3, 5], 1) --- call insert(mylist, 4, -1) --- call insert(mylist, 6, len(mylist)) --- <The last example can be done simpler with |add()|. --- Note that when {item} is a |List| it is inserted as a single --- item. Use |extend()| to concatenate |Lists|. --- --- @param object any --- @param item any --- @param idx? integer --- @return any function vim.fn.insert(object, item, idx) end --- Interrupt script execution. It works more or less like the --- user typing CTRL-C, most commands won't execute and control --- returns to the user. This is useful to abort execution --- from lower down, e.g. in an autocommand. Example: >vim --- function s:check_typoname(file) --- if fnamemodify(a:file, ':t') == '[' --- echomsg 'Maybe typo' --- call interrupt() --- endif --- endfunction --- au BufWritePre * call s:check_typoname(expand('<amatch>')) --- < --- --- @return any function vim.fn.interrupt() end --- Bitwise invert. The argument is converted to a number. A --- List, Dict or Float argument causes an error. Example: >vim --- let bits = invert(bits) --- < --- --- @param expr any --- @return any function vim.fn.invert(expr) end --- The result is a Number, which is |TRUE| when a directory --- with the name {directory} exists. If {directory} doesn't --- exist, or isn't a directory, the result is |FALSE|. {directory} --- is any expression, which is used as a String. --- --- @param directory any --- @return 0|1 function vim.fn.isdirectory(directory) end --- Return 1 if {expr} is a positive infinity, or -1 a negative --- infinity, otherwise 0. >vim --- echo isinf(1.0 / 0.0) --- < 1 >vim --- echo isinf(-1.0 / 0.0) --- < -1 --- --- @param expr any --- @return 1|0|-1 function vim.fn.isinf(expr) end --- The result is a Number, which is |TRUE| when {expr} is the --- name of a locked variable. --- The string argument {expr} must be the name of a variable, --- |List| item or |Dictionary| entry, not the variable itself! --- Example: >vim --- let alist = [0, ['a', 'b'], 2, 3] --- lockvar 1 alist --- echo islocked('alist') " 1 --- echo islocked('alist[1]') " 0 --- --- <When {expr} is a variable that does not exist you get an error --- message. Use |exists()| to check for existence. --- --- @param expr any --- @return 0|1 function vim.fn.islocked(expr) end --- Return |TRUE| if {expr} is a float with value NaN. >vim --- echo isnan(0.0 / 0.0) --- < 1 --- --- @param expr any --- @return 0|1 function vim.fn.isnan(expr) end --- Return a |List| with all the key-value pairs of {dict}. Each --- |List| item is a list with two items: the key of a {dict} --- entry and the value of this entry. The |List| is in arbitrary --- order. Also see |keys()| and |values()|. --- Example: >vim --- for [key, value] in items(mydict) --- echo key .. ': ' .. value --- endfor --- --- @param dict any --- @return any function vim.fn.items(dict) end --- @deprecated --- Obsolete name for |chanclose()| --- --- @param ... any --- @return any function vim.fn.jobclose(...) end --- Return the PID (process id) of |job-id| {job}. --- --- @param job any --- @return integer function vim.fn.jobpid(job) end --- Resize the pseudo terminal window of |job-id| {job} to {width} --- columns and {height} rows. --- Fails if the job was not started with `"pty":v:true`. --- --- @param job any --- @param width integer --- @param height integer --- @return any function vim.fn.jobresize(job, width, height) end --- @deprecated --- Obsolete name for |chansend()| --- --- @param ... any --- @return any function vim.fn.jobsend(...) end --- Note: Prefer |vim.system()| in Lua (unless using the `pty` option). --- --- Spawns {cmd} as a job. --- If {cmd} is a List it runs directly (no 'shell'). --- If {cmd} is a String it runs in the 'shell', like this: >vim --- call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) --- <(See |shell-unquoting| for details.) --- --- Example: >vim --- call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) --- < --- Returns |job-id| on success, 0 on invalid arguments (or job --- table is full), -1 if {cmd}[0] or 'shell' is not executable. --- The returned job-id is a valid |channel-id| representing the --- job's stdio streams. Use |chansend()| (or |rpcnotify()| and --- |rpcrequest()| if "rpc" was enabled) to send data to stdin and --- |chanclose()| to close the streams without stopping the job. --- --- See |job-control| and |RPC|. --- --- NOTE: on Windows if {cmd} is a List: --- - cmd[0] must be an executable (not a "built-in"). If it is --- in $PATH it can be called by name, without an extension: >vim --- call jobstart(['ping', 'neovim.io']) --- < If it is a full or partial path, extension is required: >vim --- call jobstart(['System32\ping.exe', 'neovim.io']) --- < - {cmd} is collapsed to a string of quoted args as expected --- by CommandLineToArgvW https://msdn.microsoft.com/bb776391 --- unless cmd[0] is some form of "cmd.exe". --- --- *jobstart-env* --- The job environment is initialized as follows: --- $NVIM is set to |v:servername| of the parent Nvim --- $NVIM_LISTEN_ADDRESS is unset --- $NVIM_LOG_FILE is unset --- $VIM is unset --- $VIMRUNTIME is unset --- You can set these with the `env` option. --- --- *jobstart-options* --- {opts} is a dictionary with these keys: --- clear_env: (boolean) `env` defines the job environment --- exactly, instead of merging current environment. --- cwd: (string, default=|current-directory|) Working --- directory of the job. --- detach: (boolean) Detach the job process: it will not be --- killed when Nvim exits. If the process exits --- before Nvim, `on_exit` will be invoked. --- env: (dict) Map of environment variable name:value --- pairs extending (or replace with "clear_env") --- the current environment. |jobstart-env| --- height: (number) Height of the `pty` terminal. --- |on_exit|: (function) Callback invoked when the job exits. --- |on_stdout|: (function) Callback invoked when the job emits --- stdout data. --- |on_stderr|: (function) Callback invoked when the job emits --- stderr data. --- overlapped: (boolean) Sets FILE_FLAG_OVERLAPPED for the --- stdio passed to the child process. Only on --- MS-Windows; ignored on other platforms. --- pty: (boolean) Connect the job to a new pseudo --- terminal, and its streams to the master file --- descriptor. `on_stdout` receives all output, --- `on_stderr` is ignored. |terminal-start| --- rpc: (boolean) Use |msgpack-rpc| to communicate with --- the job over stdio. Then `on_stdout` is ignored, --- but `on_stderr` can still be used. --- stderr_buffered: (boolean) Collect data until EOF (stream closed) --- before invoking `on_stderr`. |channel-buffered| --- stdout_buffered: (boolean) Collect data until EOF (stream --- closed) before invoking `on_stdout`. |channel-buffered| --- stdin: (string) Either "pipe" (default) to connect the --- job's stdin to a channel or "null" to disconnect --- stdin. --- width: (number) Width of the `pty` terminal. --- --- {opts} is passed as |self| dictionary to the callback; the --- caller may set other keys to pass application-specific data. --- --- Returns: --- - |channel-id| on success --- - 0 on invalid arguments --- - -1 if {cmd}[0] is not executable. --- See also |job-control|, |channel|, |msgpack-rpc|. --- --- @param cmd any --- @param opts? table --- @return any function vim.fn.jobstart(cmd, opts) end --- Stop |job-id| {id} by sending SIGTERM to the job process. If --- the process does not terminate after a timeout then SIGKILL --- will be sent. When the job terminates its |on_exit| handler --- (if any) will be invoked. --- See |job-control|. --- --- Returns 1 for valid job id, 0 for invalid id, including jobs have --- exited or stopped. --- --- @param id any --- @return any function vim.fn.jobstop(id) end --- Waits for jobs and their |on_exit| handlers to complete. --- --- {jobs} is a List of |job-id|s to wait for. --- {timeout} is the maximum waiting time in milliseconds. If --- omitted or -1, wait forever. --- --- Timeout of 0 can be used to check the status of a job: >vim --- let running = jobwait([{job-id}], 0)[0] == -1 --- < --- During jobwait() callbacks for jobs not in the {jobs} list may --- be invoked. The screen will not redraw unless |:redraw| is --- invoked by a callback. --- --- Returns a list of len({jobs}) integers, where each integer is --- the status of the corresponding job: --- Exit-code, if the job exited --- -1 if the timeout was exceeded --- -2 if the job was interrupted (by |CTRL-C|) --- -3 if the job-id is invalid --- --- @param jobs any --- @param timeout? integer --- @return any function vim.fn.jobwait(jobs, timeout) end --- Join the items in {list} together into one String. --- When {sep} is specified it is put in between the items. If --- {sep} is omitted a single space is used. --- Note that {sep} is not added at the end. You might want to --- add it there too: >vim --- let lines = join(mylist, "\n") .. "\n" --- <String items are used as-is. |Lists| and |Dictionaries| are --- converted into a string like with |string()|. --- The opposite function is |split()|. --- --- @param list any --- @param sep? any --- @return any function vim.fn.join(list, sep) end --- Convert {expr} from JSON object. Accepts |readfile()|-style --- list as the input, as well as regular string. May output any --- Vim value. In the following cases it will output --- |msgpack-special-dict|: --- 1. Dictionary contains duplicate key. --- 2. Dictionary contains empty key. --- 3. String contains NUL byte. Two special dictionaries: for --- dictionary and for string will be emitted in case string --- with NUL byte was a dictionary key. --- --- Note: function treats its input as UTF-8 always. The JSON --- standard allows only a few encodings, of which UTF-8 is --- recommended and the only one required to be supported. --- Non-UTF-8 characters are an error. --- --- @param expr any --- @return any function vim.fn.json_decode(expr) end --- Convert {expr} into a JSON string. Accepts --- |msgpack-special-dict| as the input. Will not convert --- |Funcref|s, mappings with non-string keys (can be created as --- |msgpack-special-dict|), values with self-referencing --- containers, strings which contain non-UTF-8 characters, --- pseudo-UTF-8 strings which contain codepoints reserved for --- surrogate pairs (such strings are not valid UTF-8 strings). --- Non-printable characters are converted into "\u1234" escapes --- or special escapes like "\t", other are dumped as-is. --- |Blob|s are converted to arrays of the individual bytes. --- --- @param expr any --- @return any function vim.fn.json_encode(expr) end --- Return a |List| with all the keys of {dict}. The |List| is in --- arbitrary order. Also see |items()| and |values()|. --- --- @param dict any --- @return any function vim.fn.keys(dict) end --- Turn the internal byte representation of keys into a form that --- can be used for |:map|. E.g. >vim --- let xx = "\<C-Home>" --- echo keytrans(xx) --- < <C-Home> --- --- @param string string --- @return any function vim.fn.keytrans(string) end --- @deprecated --- Obsolete name for bufnr("$"). --- --- @return any function vim.fn.last_buffer_nr() end --- The result is a Number, which is the length of the argument. --- When {expr} is a String or a Number the length in bytes is --- used, as with |strlen()|. --- When {expr} is a |List| the number of items in the |List| is --- returned. --- When {expr} is a |Blob| the number of bytes is returned. --- When {expr} is a |Dictionary| the number of entries in the --- |Dictionary| is returned. --- Otherwise an error is given and returns zero. --- --- @param expr any --- @return any function vim.fn.len(expr) end --- Call function {funcname} in the run-time library {libname} --- with single argument {argument}. --- This is useful to call functions in a library that you --- especially made to be used with Vim. Since only one argument --- is possible, calling standard library functions is rather --- limited. --- The result is the String returned by the function. If the --- function returns NULL, this will appear as an empty string "" --- to Vim. --- If the function returns a number, use libcallnr()! --- If {argument} is a number, it is passed to the function as an --- int; if {argument} is a string, it is passed as a --- null-terminated string. --- --- libcall() allows you to write your own 'plug-in' extensions to --- Vim without having to recompile the program. It is NOT a --- means to call system functions! If you try to do so Vim will --- very probably crash. --- --- For Win32, the functions you write must be placed in a DLL --- and use the normal C calling convention (NOT Pascal which is --- used in Windows System DLLs). The function must take exactly --- one parameter, either a character pointer or a long integer, --- and must return a character pointer or NULL. The character --- pointer returned must point to memory that will remain valid --- after the function has returned (e.g. in static data in the --- DLL). If it points to allocated memory, that memory will --- leak away. Using a static buffer in the function should work, --- it's then freed when the DLL is unloaded. --- --- WARNING: If the function returns a non-valid pointer, Vim may --- crash! This also happens if the function returns a number, --- because Vim thinks it's a pointer. --- For Win32 systems, {libname} should be the filename of the DLL --- without the ".DLL" suffix. A full path is only required if --- the DLL is not in the usual places. --- For Unix: When compiling your own plugins, remember that the --- object code must be compiled as position-independent ('PIC'). --- Examples: >vim --- echo libcall("libc.so", "getenv", "HOME") --- --- @param libname string --- @param funcname string --- @param argument any --- @return any function vim.fn.libcall(libname, funcname, argument) end --- Just like |libcall()|, but used for a function that returns an --- int instead of a string. --- Examples: >vim --- echo libcallnr("/usr/lib/libc.so", "getpid", "") --- call libcallnr("libc.so", "printf", "Hello World!\n") --- call libcallnr("libc.so", "sleep", 10) --- < --- --- @param libname string --- @param funcname string --- @param argument any --- @return any function vim.fn.libcallnr(libname, funcname, argument) end --- The result is a Number, which is the line number of the file --- position given with {expr}. The {expr} argument is a string. --- The accepted positions are: --- . the cursor position --- $ the last line in the current buffer --- 'x position of mark x (if the mark is not set, 0 is --- returned) --- w0 first line visible in current window (one if the --- display isn't updated, e.g. in silent Ex mode) --- w$ last line visible in current window (this is one --- less than "w0" if no lines are visible) --- 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. --- Note that a mark in another file can be used. The line number --- then applies to another buffer. --- To get the column number use |col()|. To get both use --- |getpos()|. --- With the optional {winid} argument the values are obtained for --- that window instead of the current window. --- Returns 0 for invalid values of {expr} and {winid}. --- Examples: >vim --- echo line(".") " line number of the cursor --- echo line(".", winid) " idem, in window "winid" --- echo line("'t") " line number of mark t --- echo line("'" .. marker) " line number of mark marker --- < --- To jump to the last known position when opening a file see --- |last-position-jump|. --- --- @param expr any --- @param winid? integer --- @return integer function vim.fn.line(expr, winid) end --- Return the byte count from the start of the buffer for line --- {lnum}. This includes the end-of-line character, depending on --- the 'fileformat' option for the current buffer. The first --- line returns 1. UTF-8 encoding is used, 'fileencoding' is --- ignored. This can also be used to get the byte count for the --- line just below the last line: >vim --- echo line2byte(line("$") + 1) --- <This is the buffer size plus one. If 'fileencoding' is empty --- it is the file size plus one. {lnum} is used like with --- |getline()|. When {lnum} is invalid -1 is returned. --- Also see |byte2line()|, |go| and |:goto|. --- --- @param lnum integer --- @return integer function vim.fn.line2byte(lnum) end --- Get the amount of indent for line {lnum} according the lisp --- indenting rules, as with 'lisp'. --- 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. --- --- @param lnum integer --- @return any function vim.fn.lispindent(lnum) end --- Return a Blob concatenating all the number values in {list}. --- Examples: >vim --- echo list2blob([1, 2, 3, 4]) " returns 0z01020304 --- echo list2blob([]) " returns 0z --- <Returns an empty Blob on error. If one of the numbers is --- negative or more than 255 error *E1239* is given. --- --- |blob2list()| does the opposite. --- --- @param list any --- @return any function vim.fn.list2blob(list) end --- Convert each number in {list} to a character string can --- concatenate them all. Examples: >vim --- echo list2str([32]) " returns " " --- echo list2str([65, 66, 67]) " returns "ABC" --- <The same can be done (slowly) with: >vim --- echo join(map(list, {nr, val -> nr2char(val)}), '') --- <|str2list()| does the opposite. --- --- UTF-8 encoding is always used, {utf8} option has no effect, --- and exists only for backwards-compatibility. --- With UTF-8 composing characters work as expected: >vim --- echo list2str([97, 769]) " returns "aΜ" --- < --- Returns an empty string on error. --- --- @param list any --- @param utf8? any --- @return any function vim.fn.list2str(list, utf8) end --- Return the current time, measured as seconds since 1st Jan --- 1970. See also |strftime()|, |strptime()| and |getftime()|. --- --- @return any function vim.fn.localtime() end --- Return the natural logarithm (base e) of {expr} as a |Float|. --- {expr} must evaluate to a |Float| or a |Number| in the range --- (0, inf]. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo log(10) --- < 2.302585 >vim --- echo log(exp(5)) --- < 5.0 --- --- @param expr any --- @return any function vim.fn.log(expr) end --- Return the logarithm of Float {expr} to base 10 as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo log10(1000) --- < 3.0 >vim --- echo log10(0.01) --- < -2.0 --- --- @param expr any --- @return any function vim.fn.log10(expr) end --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. --- When {expr1} is a |List|| or |Dictionary|, replace each --- item in {expr1} with the result of evaluating {expr2}. --- For a |Blob| each byte is replaced. --- For a |String|, each character, including composing --- characters, is replaced. --- If the item type changes you may want to use |mapnew()| to --- create a new List or Dictionary. --- --- {expr2} must be a |String| or |Funcref|. --- --- If {expr2} is a |String|, inside {expr2} |v:val| has the value --- of the current item. For a |Dictionary| |v:key| has the key --- of the current item and for a |List| |v:key| has the index of --- the current item. For a |Blob| |v:key| has the index of the --- current byte. For a |String| |v:key| has the index of the --- current character. --- Example: >vim --- call map(mylist, '"> " .. v:val .. " <"') --- <This puts "> " before and " <" after each item in "mylist". --- --- Note that {expr2} is the result of an expression and is then --- used as an expression again. Often it is good to use a --- |literal-string| to avoid having to double backslashes. You --- still have to double ' quotes --- --- If {expr2} is a |Funcref| it is called with two arguments: --- 1. The key or the index of the current item. --- 2. the value of the current item. --- The function must return the new value of the item. Example --- that changes each value by "key-value": >vim --- func KeyValue(key, val) --- return a:key .. '-' .. a:val --- endfunc --- call map(myDict, function('KeyValue')) --- <It is shorter when using a |lambda|: >vim --- call map(myDict, {key, val -> key .. '-' .. val}) --- <If you do not use "val" you can leave it out: >vim --- call map(myDict, {key -> 'item: ' .. key}) --- <If you do not use "key" you can use a short name: >vim --- call map(myDict, {_, val -> 'item: ' .. val}) --- < --- The operation is done in-place for a |List| and |Dictionary|. --- If you want it to remain unmodified make a copy first: >vim --- let tlist = map(copy(mylist), ' v:val .. "\t"') --- --- <Returns {expr1}, the |List| or |Dictionary| that was filtered, --- or a new |Blob| or |String|. --- When an error is encountered while evaluating {expr2} no --- further items in {expr1} are processed. --- When {expr2} is a Funcref errors inside a function are ignored, --- unless it was defined with the "abort" flag. --- --- @param expr1 any --- @param expr2 any --- @return any function vim.fn.map(expr1, expr2) end --- When {dict} is omitted or zero: Return the rhs of mapping --- {name} in mode {mode}. The returned String has special --- characters translated like in the output of the ":map" command --- listing. --- --- When there is no mapping for {name}, an empty String is --- returned if {dict} is FALSE, otherwise returns an empty Dict. --- When the mapping for {name} is empty, then "<Nop>" is --- returned. --- --- The {name} can have special key names, like in the ":map" --- command. --- --- {mode} can be one of these strings: --- "n" Normal --- "v" Visual (including Select) --- "o" Operator-pending --- "i" Insert --- "c" Cmd-line --- "s" Select --- "x" Visual --- "l" langmap |language-mapping| --- "t" Terminal --- "" Normal, Visual and Operator-pending --- When {mode} is omitted, the modes for "" are used. --- --- When {abbr} is there and it is |TRUE| use abbreviations --- instead of mappings. --- --- When {dict} is there and it is |TRUE| return a dictionary --- containing all the information of the mapping with the --- following items: --- "lhs" The {lhs} of the mapping as it would be typed --- "lhsraw" The {lhs} of the mapping as raw bytes --- "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate --- form, only present when it differs from "lhsraw" --- "rhs" The {rhs} of the mapping as typed. --- "silent" 1 for a |:map-silent| mapping, else 0. --- "noremap" 1 if the {rhs} of the mapping is not remappable. --- "script" 1 if mapping was defined with <script>. --- "expr" 1 for an expression mapping (|:map-<expr>|). --- "buffer" 1 for a buffer local mapping (|:map-local|). --- "mode" Modes for which the mapping is defined. In --- addition to the modes mentioned above, these --- characters will be used: --- " " Normal, Visual and Operator-pending --- "!" Insert and Commandline mode --- (|mapmode-ic|) --- "sid" The script local ID, used for <sid> mappings --- (|<SID>|). Negative for special contexts. --- "lnum" The line number in "sid", zero if unknown. --- "nowait" Do not wait for other, longer mappings. --- (|:map-<nowait>|). --- --- The dictionary can be used to restore a mapping with --- |mapset()|. --- --- The mappings local to the current buffer are checked first, --- then the global mappings. --- This function can be used to map a key even when it's already --- mapped, and have it do the original mapping too. Sketch: >vim --- exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n') --- --- @param name string --- @param mode? string --- @param abbr? boolean --- @param dict? boolean --- @return string|table<string,any> function vim.fn.maparg(name, mode, abbr, dict) end --- Check if there is a mapping that matches with {name} in mode --- {mode}. See |maparg()| for {mode} and special names in --- {name}. --- When {abbr} is there and it is non-zero use abbreviations --- instead of mappings. --- A match happens with a mapping that starts with {name} and --- with a mapping which is equal to the start of {name}. --- --- matches mapping "a" "ab" "abc" ~ --- mapcheck("a") yes yes yes --- mapcheck("abc") yes yes yes --- mapcheck("ax") yes no no --- mapcheck("b") no no no --- --- The difference with maparg() is that mapcheck() finds a --- mapping that matches with {name}, while maparg() only finds a --- mapping for {name} exactly. --- When there is no mapping that starts with {name}, an empty --- String is returned. If there is one, the RHS of that mapping --- is returned. If there are several mappings that start with --- {name}, the RHS of one of them is returned. This will be --- "<Nop>" if the RHS is empty. --- The mappings local to the current buffer are checked first, --- then the global mappings. --- This function can be used to check if a mapping can be added --- without being ambiguous. Example: >vim --- if mapcheck("_vv") == "" --- map _vv :set guifont=7x13<CR> --- endif --- <This avoids adding the "_vv" mapping when there already is a --- mapping for "_v" or for "_vvv". --- --- @param name string --- @param mode? string --- @param abbr? any --- @return any function vim.fn.mapcheck(name, mode, abbr) end --- Like |map()| but instead of replacing items in {expr1} a new --- List or Dictionary is created and returned. {expr1} remains --- unchanged. Items can still be changed by {expr2}, if you --- don't want that use |deepcopy()| first. --- --- @param expr1 any --- @param expr2 any --- @return any function vim.fn.mapnew(expr1, expr2) end --- Restore a mapping from a dictionary returned by |maparg()|. --- {mode} and {abbr} should be the same as for the call to --- |maparg()|. *E460* --- {mode} is used to define the mode in which the mapping is set, --- not the "mode" entry in {dict}. --- Example for saving and restoring a mapping: >vim --- let save_map = maparg('K', 'n', 0, 1) --- nnoremap K somethingelse --- " ... --- call mapset('n', 0, save_map) --- <Note that if you are going to replace a map in several modes, --- e.g. with `:map!`, you need to save the mapping for all of --- them, since they can differ. --- --- @param mode string --- @param abbr any --- @param dict any --- @return any function vim.fn.mapset(mode, abbr, dict) end --- When {expr} is a |List| then this returns the index of the --- first item where {pat} matches. Each item is used as a --- String, |Lists| and |Dictionaries| are used as echoed. --- --- Otherwise, {expr} is used as a String. The result is a --- Number, which gives the index (byte offset) in {expr} where --- {pat} matches. --- --- A match at the first character or |List| item returns zero. --- If there is no match -1 is returned. --- --- For getting submatches see |matchlist()|. --- Example: >vim --- echo match("testing", "ing") " results in 4 --- echo match([1, 'x'], '\a') " results in 1 --- <See |string-match| for how {pat} is used. --- *strpbrk()* --- Vim doesn't have a strpbrk() function. But you can do: >vim --- let sepidx = match(line, '[.,;: \t]') --- < *strcasestr()* --- Vim doesn't have a strcasestr() function. But you can add --- "\c" to the pattern to ignore case: >vim --- let idx = match(haystack, '\cneedle') --- < --- If {start} is given, the search starts from byte index --- {start} in a String or item {start} in a |List|. --- The result, however, is still the index counted from the --- first character/item. Example: >vim --- echo match("testing", "ing", 2) --- <result is again "4". >vim --- echo match("testing", "ing", 4) --- <result is again "4". >vim --- echo match("testing", "t", 2) --- <result is "3". --- For a String, if {start} > 0 then it is like the string starts --- {start} bytes later, thus "^" will match at {start}. Except --- when {count} is given, then it's like matches before the --- {start} byte are ignored (this is a bit complicated to keep it --- backwards compatible). --- For a String, if {start} < 0, it will be set to 0. For a list --- the index is counted from the end. --- If {start} is out of range ({start} > strlen({expr}) for a --- String or {start} > len({expr}) for a |List|) -1 is returned. --- --- When {count} is given use the {count}th match. When a match --- is found in a String the search for the next one starts one --- character further. Thus this example results in 1: >vim --- echo match("testing", "..", 0, 2) --- <In a |List| the search continues in the next item. --- Note that when {count} is added the way {start} works changes, --- see above. --- --- See |pattern| for the patterns that are accepted. --- The 'ignorecase' option is used to set the ignore-caseness of --- the pattern. 'smartcase' is NOT used. The matching is always --- done like 'magic' is set and 'cpoptions' is empty. --- Note that a match at the start is preferred, thus when the --- pattern is using "*" (any number of matches) it tends to find --- zero matches at the start instead of a number of matches --- further down in the text. --- --- @param expr any --- @param pat any --- @param start? any --- @param count? any --- @return any function vim.fn.match(expr, pat, start, count) end --- Defines a pattern to be highlighted in the current window (a --- "match"). It will be highlighted with {group}. Returns an --- identification number (ID), which can be used to delete the --- match using |matchdelete()|. The ID is bound to the window. --- Matching is case sensitive and magic, unless case sensitivity --- or magicness are explicitly overridden in {pattern}. The --- 'magic', 'smartcase' and 'ignorecase' options are not used. --- The "Conceal" value is special, it causes the match to be --- concealed. --- --- The optional {priority} argument assigns a priority to the --- match. A match with a high priority will have its --- highlighting overrule that of a match with a lower priority. --- A priority is specified as an integer (negative numbers are no --- exception). If the {priority} argument is not specified, the --- default priority is 10. The priority of 'hlsearch' is zero, --- hence all matches with a priority greater than zero will --- overrule it. Syntax highlighting (see 'syntax') is a separate --- mechanism, and regardless of the chosen priority a match will --- always overrule syntax highlighting. --- --- The optional {id} argument allows the request for a specific --- match ID. If a specified ID is already taken, an error --- message will appear and the match will not be added. An ID --- is specified as a positive integer (zero excluded). IDs 1, 2 --- and 3 are reserved for |:match|, |:2match| and |:3match|, --- respectively. 3 is reserved for use by the |matchparen| --- plugin. --- If the {id} argument is not specified or -1, |matchadd()| --- automatically chooses a free ID, which is at least 1000. --- --- The optional {dict} argument allows for further custom --- values. Currently this is used to specify a match specific --- conceal character that will be shown for |hl-Conceal| --- highlighted matches. The dict can have the following members: --- --- conceal Special character to show instead of the --- match (only for |hl-Conceal| highlighted --- matches, see |:syn-cchar|) --- window Instead of the current window use the --- window with this number or window ID. --- --- The number of matches is not limited, as it is the case with --- the |:match| commands. --- --- Returns -1 on error. --- --- Example: >vim --- highlight MyGroup ctermbg=green guibg=green --- let m = matchadd("MyGroup", "TODO") --- <Deletion of the pattern: >vim --- call matchdelete(m) --- --- <A list of matches defined by |matchadd()| and |:match| are --- available from |getmatches()|. All matches can be deleted in --- one operation by |clearmatches()|. --- --- @param group any --- @param pattern any --- @param priority? any --- @param id? any --- @param dict? any --- @return any function vim.fn.matchadd(group, pattern, priority, id, dict) end --- Same as |matchadd()|, but requires a list of positions {pos} --- instead of a pattern. This command is faster than |matchadd()| --- because it does not require to handle regular expressions and --- sets buffer line boundaries to redraw screen. It is supposed --- to be used when fast match additions and deletions are --- required, for example to highlight matching parentheses. --- *E5030* *E5031* --- {pos} is a list of positions. Each position can be one of --- these: --- - A number. This whole line will be highlighted. The first --- line has number 1. --- - A list with one number, e.g., [23]. The whole line with this --- number will be highlighted. --- - A list with two numbers, e.g., [23, 11]. The first number is --- the line number, the second one is the column number (first --- column is 1, the value must correspond to the byte index as --- |col()| would return). The character at this position will --- be highlighted. --- - A list with three numbers, e.g., [23, 11, 3]. As above, but --- the third number gives the length of the highlight in bytes. --- --- Entries with zero and negative line numbers are silently --- ignored, as well as entries with negative column numbers and --- lengths. --- --- Returns -1 on error. --- --- Example: >vim --- highlight MyGroup ctermbg=green guibg=green --- let m = matchaddpos("MyGroup", [[23, 24], 34]) --- <Deletion of the pattern: >vim --- call matchdelete(m) --- --- <Matches added by |matchaddpos()| are returned by --- |getmatches()|. --- --- @param group any --- @param pos any --- @param priority? any --- @param id? any --- @param dict? any --- @return any function vim.fn.matchaddpos(group, pos, priority, id, dict) end --- Selects the {nr} match item, as set with a |:match|, --- |:2match| or |:3match| command. --- Return a |List| with two elements: --- The name of the highlight group used --- The pattern used. --- When {nr} is not 1, 2 or 3 returns an empty |List|. --- When there is no match item set returns ['', '']. --- This is useful to save and restore a |:match|. --- Highlighting matches using the |:match| commands are limited --- to three matches. |matchadd()| does not have this limitation. --- --- @param nr integer --- @return any function vim.fn.matcharg(nr) end --- Deletes a match with ID {id} previously defined by |matchadd()| --- or one of the |:match| commands. Returns 0 if successful, --- otherwise -1. See example for |matchadd()|. All matches can --- be deleted in one operation by |clearmatches()|. --- If {win} is specified, use the window with this number or --- window ID instead of the current window. --- --- @param id any --- @param win? any --- @return any function vim.fn.matchdelete(id, win) end --- Same as |match()|, but return the index of first character --- after the match. Example: >vim --- echo matchend("testing", "ing") --- <results in "7". --- *strspn()* *strcspn()* --- Vim doesn't have a strspn() or strcspn() function, but you can --- do it with matchend(): >vim --- let span = matchend(line, '[a-zA-Z]') --- let span = matchend(line, '[^a-zA-Z]') --- <Except that -1 is returned when there are no matches. --- --- The {start}, if given, has the same meaning as for |match()|. >vim --- echo matchend("testing", "ing", 2) --- <results in "7". >vim --- echo matchend("testing", "ing", 5) --- <result is "-1". --- When {expr} is a |List| the result is equal to |match()|. --- --- @param expr any --- @param pat any --- @param start? any --- @param count? any --- @return any function vim.fn.matchend(expr, pat, start, count) end --- If {list} is a list of strings, then returns a |List| with all --- the strings in {list} that fuzzy match {str}. The strings in --- the returned list are sorted based on the matching score. --- --- The optional {dict} argument always supports the following --- items: --- matchseq When this item is present return only matches --- that contain the characters in {str} in the --- given sequence. --- limit Maximum number of matches in {list} to be --- returned. Zero means no limit. --- --- If {list} is a list of dictionaries, then the optional {dict} --- argument supports the following additional items: --- key Key of the item which is fuzzy matched against --- {str}. The value of this item should be a --- string. --- text_cb |Funcref| that will be called for every item --- in {list} to get the text for fuzzy matching. --- This should accept a dictionary item as the --- argument and return the text for that item to --- use for fuzzy matching. --- --- {str} is treated as a literal string and regular expression --- matching is NOT supported. The maximum supported {str} length --- is 256. --- --- When {str} has multiple words each separated by white space, --- then the list of strings that have all the words is returned. --- --- If there are no matching strings or there is an error, then an --- empty list is returned. If length of {str} is greater than --- 256, then returns an empty list. --- --- When {limit} is given, matchfuzzy() will find up to this --- number of matches in {list} and return them in sorted order. --- --- Refer to |fuzzy-matching| for more information about fuzzy --- matching strings. --- --- Example: >vim --- echo matchfuzzy(["clay", "crow"], "cay") --- <results in ["clay"]. >vim --- echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") --- <results in a list of buffer names fuzzy matching "ndl". >vim --- echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) --- <results in a list of buffer information dicts with buffer --- names fuzzy matching "ndl". >vim --- echo getbufinfo()->matchfuzzy("spl", --- \ {'text_cb' : {v -> v.name}}) --- <results in a list of buffer information dicts with buffer --- names fuzzy matching "spl". >vim --- echo v:oldfiles->matchfuzzy("test") --- <results in a list of file names fuzzy matching "test". >vim --- let l = readfile("buffer.c")->matchfuzzy("str") --- <results in a list of lines in "buffer.c" fuzzy matching "str". >vim --- echo ['one two', 'two one']->matchfuzzy('two one') --- <results in `['two one', 'one two']` . >vim --- echo ['one two', 'two one']->matchfuzzy('two one', --- \ {'matchseq': 1}) --- <results in `['two one']`. --- --- @param list any --- @param str any --- @param dict? any --- @return any function vim.fn.matchfuzzy(list, str, dict) end --- Same as |matchfuzzy()|, but returns the list of matched --- strings, the list of character positions where characters --- in {str} matches and a list of matching scores. You can --- use |byteidx()| to convert a character position to a byte --- position. --- --- If {str} matches multiple times in a string, then only the --- positions for the best match is returned. --- --- If there are no matching strings or there is an error, then a --- list with three empty list items is returned. --- --- Example: >vim --- echo matchfuzzypos(['testing'], 'tsg') --- <results in [["testing"], [[0, 2, 6]], [99]] >vim --- echo matchfuzzypos(['clay', 'lacy'], 'la') --- <results in [["lacy", "clay"], [[0, 1], [1, 2]], [153, 133]] >vim --- echo [{'text': 'hello', 'id' : 10}] --- \ ->matchfuzzypos('ll', {'key' : 'text'}) --- <results in `[[{"id": 10, "text": "hello"}], [[2, 3]], [127]]` --- --- @param list any --- @param str any --- @param dict? any --- @return any function vim.fn.matchfuzzypos(list, str, dict) end --- Same as |match()|, but return a |List|. The first item in the --- list is the matched string, same as what matchstr() would --- return. Following items are submatches, like "\1", "\2", etc. --- in |:substitute|. When an optional submatch didn't match an --- empty string is used. Example: >vim --- echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') --- <Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] --- When there is no match an empty list is returned. --- --- You can pass in a List, but that is not very useful. --- --- @param expr any --- @param pat any --- @param start? any --- @param count? any --- @return any function vim.fn.matchlist(expr, pat, start, count) end --- Same as |match()|, but return the matched string. Example: >vim --- echo matchstr("testing", "ing") --- <results in "ing". --- When there is no match "" is returned. --- The {start}, if given, has the same meaning as for |match()|. >vim --- echo matchstr("testing", "ing", 2) --- <results in "ing". >vim --- echo matchstr("testing", "ing", 5) --- <result is "". --- When {expr} is a |List| then the matching item is returned. --- The type isn't changed, it's not necessarily a String. --- --- @param expr any --- @param pat any --- @param start? any --- @param count? any --- @return any function vim.fn.matchstr(expr, pat, start, count) end --- Same as |matchstr()|, but return the matched string, the start --- position and the end position of the match. Example: >vim --- echo matchstrpos("testing", "ing") --- <results in ["ing", 4, 7]. --- When there is no match ["", -1, -1] is returned. --- The {start}, if given, has the same meaning as for |match()|. >vim --- echo matchstrpos("testing", "ing", 2) --- <results in ["ing", 4, 7]. >vim --- echo matchstrpos("testing", "ing", 5) --- <result is ["", -1, -1]. --- When {expr} is a |List| then the matching item, the index --- of first item where {pat} matches, the start position and the --- end position of the match are returned. >vim --- echo matchstrpos([1, '__x'], '\a') --- <result is ["x", 1, 2, 3]. --- The type isn't changed, it's not necessarily a String. --- --- @param expr any --- @param pat any --- @param start? any --- @param count? any --- @return any function vim.fn.matchstrpos(expr, pat, start, count) end --- Return the maximum value of all items in {expr}. Example: >vim --- echo max([apples, pears, oranges]) --- --- <{expr} can be a |List| or a |Dictionary|. For a Dictionary, --- it returns the maximum of all values in the Dictionary. --- If {expr} is neither a List nor a Dictionary, or one of the --- items in {expr} cannot be used as a Number this results in --- an error. An empty |List| or |Dictionary| results in zero. --- --- @param expr any --- @return any function vim.fn.max(expr) end --- Returns a |List| of |Dictionaries| describing |menus| (defined --- by |:menu|, |:amenu|, β¦), including |hidden-menus|. --- --- {path} matches a menu by name, or all menus if {path} is an --- empty string. Example: >vim --- echo menu_get('File','') --- echo menu_get('') --- < --- {modes} is a string of zero or more modes (see |maparg()| or --- |creating-menus| for the list of modes). "a" means "all". --- --- Example: >vim --- nnoremenu &Test.Test inormal --- inoremenu Test.Test insert --- vnoremenu Test.Test x --- echo menu_get("") --- --- <returns something like this: > --- --- [ { --- "hidden": 0, --- "name": "Test", --- "priority": 500, --- "shortcut": 84, --- "submenus": [ { --- "hidden": 0, --- "mappings": { --- i": { --- "enabled": 1, --- "noremap": 1, --- "rhs": "insert", --- "sid": 1, --- "silent": 0 --- }, --- n": { ... }, --- s": { ... }, --- v": { ... } --- }, --- "name": "Test", --- "priority": 500, --- "shortcut": 0 --- } ] --- } ] --- < --- --- @param path string --- @param modes? any --- @return any function vim.fn.menu_get(path, modes) end --- Return information about the specified menu {name} in --- mode {mode}. The menu name should be specified without the --- shortcut character ('&'). If {name} is "", then the top-level --- menu names are returned. --- --- {mode} can be one of these strings: --- "n" Normal --- "v" Visual (including Select) --- "o" Operator-pending --- "i" Insert --- "c" Cmd-line --- "s" Select --- "x" Visual --- "t" Terminal-Job --- "" Normal, Visual and Operator-pending --- "!" Insert and Cmd-line --- When {mode} is omitted, the modes for "" are used. --- --- Returns a |Dictionary| containing the following items: --- accel menu item accelerator text |menu-text| --- display display name (name without '&') --- enabled v:true if this menu item is enabled --- Refer to |:menu-enable| --- icon name of the icon file (for toolbar) --- |toolbar-icon| --- iconidx index of a built-in icon --- modes modes for which the menu is defined. In --- addition to the modes mentioned above, these --- characters will be used: --- " " Normal, Visual and Operator-pending --- name menu item name. --- noremenu v:true if the {rhs} of the menu item is not --- remappable else v:false. --- priority menu order priority |menu-priority| --- rhs right-hand-side of the menu item. The returned --- string has special characters translated like --- in the output of the ":menu" command listing. --- When the {rhs} of a menu item is empty, then --- "<Nop>" is returned. --- script v:true if script-local remapping of {rhs} is --- allowed else v:false. See |:menu-script|. --- shortcut shortcut key (character after '&' in --- the menu name) |menu-shortcut| --- silent v:true if the menu item is created --- with <silent> argument |:menu-silent| --- submenus |List| containing the names of --- all the submenus. Present only if the menu --- item has submenus. --- --- Returns an empty dictionary if the menu item is not found. --- --- Examples: >vim --- echo menu_info('Edit.Cut') --- echo menu_info('File.Save', 'n') --- --- " Display the entire menu hierarchy in a buffer --- func ShowMenu(name, pfx) --- let m = menu_info(a:name) --- call append(line('$'), a:pfx .. m.display) --- for child in m->get('submenus', []) --- call ShowMenu(a:name .. '.' .. escape(child, '.'), --- \ a:pfx .. ' ') --- endfor --- endfunc --- new --- for topmenu in menu_info('').submenus --- call ShowMenu(topmenu, '') --- endfor --- < --- --- @param name string --- @param mode? string --- @return any function vim.fn.menu_info(name, mode) end --- Return the minimum value of all items in {expr}. Example: >vim --- echo min([apples, pears, oranges]) --- --- <{expr} can be a |List| or a |Dictionary|. For a Dictionary, --- it returns the minimum of all values in the Dictionary. --- If {expr} is neither a List nor a Dictionary, or one of the --- items in {expr} cannot be used as a Number this results in --- an error. An empty |List| or |Dictionary| results in zero. --- --- @param expr any --- @return any function vim.fn.min(expr) end --- Create directory {name}. --- --- When {flags} is present it must be a string. An empty string --- has no effect. --- --- If {flags} contains "p" then intermediate directories are --- created as necessary. --- --- If {flags} contains "D" then {name} is deleted at the end of --- the current function, as with: >vim --- defer delete({name}, 'd') --- < --- If {flags} contains "R" then {name} is deleted recursively at --- the end of the current function, as with: >vim --- defer delete({name}, 'rf') --- <Note that when {name} has more than one part and "p" is used --- some directories may already exist. Only the first one that --- is created and what it contains is scheduled to be deleted. --- E.g. when using: >vim --- call mkdir('subdir/tmp/autoload', 'pR') --- <and "subdir" already exists then "subdir/tmp" will be --- scheduled for deletion, like with: >vim --- defer delete('subdir/tmp', 'rf') --- < --- If {prot} is given it is used to set the protection bits of --- the new directory. The default is 0o755 (rwxr-xr-x: r/w for --- the user, readable for others). Use 0o700 to make it --- unreadable for others. --- --- {prot} is applied for all parts of {name}. Thus if you create --- /tmp/foo/bar then /tmp/foo will be created with 0o700. Example: >vim --- call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700) --- --- <This function is not available in the |sandbox|. --- --- If you try to create an existing directory with {flags} set to --- "p" mkdir() will silently exit. --- --- The function result is a Number, which is TRUE if the call was --- successful or FALSE if the directory creation failed or partly --- failed. --- --- @param name string --- @param flags? string --- @param prot? any --- @return any function vim.fn.mkdir(name, flags, prot) end --- Return a string that indicates the current mode. --- If [expr] is supplied and it evaluates to a non-zero Number or --- a non-empty String (|non-zero-arg|), then the full mode is --- returned, otherwise only the first letter is returned. --- Also see |state()|. --- --- n Normal --- no Operator-pending --- nov Operator-pending (forced charwise |o_v|) --- noV Operator-pending (forced linewise |o_V|) --- noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|) --- CTRL-V is one character --- niI Normal using |i_CTRL-O| in |Insert-mode| --- niR Normal using |i_CTRL-O| in |Replace-mode| --- niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| --- nt Normal in |terminal-emulator| (insert goes to --- Terminal mode) --- ntT Normal using |t_CTRL-\_CTRL-O| in |Terminal-mode| --- v Visual by character --- vs Visual by character using |v_CTRL-O| in Select mode --- V Visual by line --- Vs Visual by line using |v_CTRL-O| in Select mode --- CTRL-V Visual blockwise --- CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode --- s Select by character --- S Select by line --- CTRL-S Select blockwise --- i Insert --- ic Insert mode completion |compl-generic| --- ix Insert mode |i_CTRL-X| completion --- R Replace |R| --- Rc Replace mode completion |compl-generic| --- Rx Replace mode |i_CTRL-X| completion --- Rv Virtual Replace |gR| --- Rvc Virtual Replace mode completion |compl-generic| --- Rvx Virtual Replace mode |i_CTRL-X| completion --- c Command-line editing --- cv Vim Ex mode |gQ| --- r Hit-enter prompt --- rm The -- more -- prompt --- r? A |:confirm| query of some sort --- ! Shell or external command is executing --- t Terminal mode: keys go to the job --- --- This is useful in the 'statusline' option or RPC calls. In --- most other places it always returns "c" or "n". --- Note that in the future more modes and more specific modes may --- be added. It's better not to compare the whole string but only --- the leading character(s). --- Also see |visualmode()|. --- --- @return any function vim.fn.mode() end --- Convert a list of Vimscript objects to msgpack. Returned value is a --- |readfile()|-style list. When {type} contains "B", a |Blob| is --- returned instead. Example: >vim --- call writefile(msgpackdump([{}]), 'fname.mpack', 'b') --- <or, using a |Blob|: >vim --- call writefile(msgpackdump([{}], 'B'), 'fname.mpack') --- < --- This will write the single 0x80 byte to a `fname.mpack` file --- (dictionary with zero items is represented by 0x80 byte in --- messagepack). --- --- Limitations: *E5004* *E5005* --- 1. |Funcref|s cannot be dumped. --- 2. Containers that reference themselves cannot be dumped. --- 3. Dictionary keys are always dumped as STR strings. --- 4. Other strings and |Blob|s are always dumped as BIN strings. --- 5. Points 3. and 4. do not apply to |msgpack-special-dict|s. --- --- @param list any --- @param type? any --- @return any function vim.fn.msgpackdump(list, type) end --- Convert a |readfile()|-style list or a |Blob| to a list of --- Vimscript objects. --- Example: >vim --- let fname = expand('~/.config/nvim/shada/main.shada') --- let mpack = readfile(fname, 'b') --- let shada_objects = msgpackparse(mpack) --- <This will read ~/.config/nvim/shada/main.shada file to --- `shada_objects` list. --- --- Limitations: --- 1. Mapping ordering is not preserved unless messagepack --- mapping is dumped using generic mapping --- (|msgpack-special-map|). --- 2. Since the parser aims to preserve all data untouched --- (except for 1.) some strings are parsed to --- |msgpack-special-dict| format which is not convenient to --- use. --- *msgpack-special-dict* --- Some messagepack strings may be parsed to special --- dictionaries. Special dictionaries are dictionaries which --- --- 1. Contain exactly two keys: `_TYPE` and `_VAL`. --- 2. `_TYPE` key is one of the types found in |v:msgpack_types| --- variable. --- 3. Value for `_VAL` has the following format (Key column --- contains name of the key from |v:msgpack_types|): --- --- Key Value ~ --- nil Zero, ignored when dumping. Not returned by --- |msgpackparse()| since |v:null| was introduced. --- boolean One or zero. When dumping it is only checked that --- value is a |Number|. Not returned by |msgpackparse()| --- since |v:true| and |v:false| were introduced. --- integer |List| with four numbers: sign (-1 or 1), highest two --- bits, number with bits from 62nd to 31st, lowest 31 --- bits. I.e. to get actual number one will need to use --- code like > --- _VAL[0] * ((_VAL[1] << 62) --- & (_VAL[2] << 31) --- & _VAL[3]) --- < Special dictionary with this type will appear in --- |msgpackparse()| output under one of the following --- circumstances: --- 1. |Number| is 32-bit and value is either above --- INT32_MAX or below INT32_MIN. --- 2. |Number| is 64-bit and value is above INT64_MAX. It --- cannot possibly be below INT64_MIN because msgpack --- C parser does not support such values. --- float |Float|. This value cannot possibly appear in --- |msgpackparse()| output. --- string |readfile()|-style list of strings. This value will --- appear in |msgpackparse()| output if string contains --- zero byte or if string is a mapping key and mapping is --- being represented as special dictionary for other --- reasons. --- binary |String|, or |Blob| if binary string contains zero --- byte. This value cannot appear in |msgpackparse()| --- output since blobs were introduced. --- array |List|. This value cannot appear in |msgpackparse()| --- output. --- *msgpack-special-map* --- map |List| of |List|s with two items (key and value) each. --- This value will appear in |msgpackparse()| output if --- parsed mapping contains one of the following keys: --- 1. Any key that is not a string (including keys which --- are binary strings). --- 2. String with NUL byte inside. --- 3. Duplicate key. --- 4. Empty key. --- ext |List| with two values: first is a signed integer --- representing extension type. Second is --- |readfile()|-style list of strings. --- --- @param data any --- @return any function vim.fn.msgpackparse(data) end --- Return the line number of the first line at or below {lnum} --- that is not blank. Example: >vim --- if getline(nextnonblank(1)) =~ "Java" | endif --- <When {lnum} is invalid or there is no non-blank line at or --- below it, zero is returned. --- {lnum} is used like with |getline()|. --- See also |prevnonblank()|. --- --- @param lnum integer --- @return any function vim.fn.nextnonblank(lnum) end --- Return a string with a single character, which has the number --- value {expr}. Examples: >vim --- echo nr2char(64) " returns '\@' --- echo nr2char(32) " returns ' ' --- <Example for "utf-8": >vim --- echo nr2char(300) " returns I with bow character --- < --- UTF-8 encoding is always used, {utf8} option has no effect, --- and exists only for backwards-compatibility. --- Note that a NUL character in the file is specified with --- nr2char(10), because NULs are represented with newline --- characters. nr2char(0) is a real NUL and terminates the --- string, thus results in an empty string. --- --- @param expr any --- @param utf8? any --- @return any function vim.fn.nr2char(expr, utf8) end --- Bitwise OR on the two arguments. The arguments are converted --- to a number. A List, Dict or Float argument causes an error. --- Also see `and()` and `xor()`. --- Example: >vim --- let bits = or(bits, 0x80) --- --- <Rationale: The reason this is a function and not using the "|" --- character like many languages, is that Vi has always used "|" --- to separate commands. In many places it would not be clear if --- "|" is an operator or a command separator. --- --- @param expr any --- @param expr1 any --- @return any vim.fn['or'] = function(expr, expr1) end --- Shorten directory names in the path {path} and return the --- result. The tail, the file name, is kept as-is. The other --- components in the path are reduced to {len} letters in length. --- If {len} is omitted or smaller than 1 then 1 is used (single --- letters). Leading '~' and '.' characters are kept. Examples: >vim --- echo pathshorten('~/.config/nvim/autoload/file1.vim') --- < ~/.c/n/a/file1.vim ~ --- >vim --- echo pathshorten('~/.config/nvim/autoload/file2.vim', 2) --- < ~/.co/nv/au/file2.vim ~ --- It doesn't matter if the path exists or not. --- Returns an empty string on error. --- --- @param path string --- @param len? any --- @return any function vim.fn.pathshorten(path, len) end --- Evaluate |perl| expression {expr} and return its result --- converted to Vim data structures. --- Numbers and strings are returned as they are (strings are --- copied though). --- Lists are represented as Vim |List| type. --- Dictionaries are represented as Vim |Dictionary| type, --- non-string keys result in error. --- --- Note: If you want an array or hash, {expr} must return a --- reference to it. --- Example: >vim --- echo perleval('[1 .. 4]') --- < [1, 2, 3, 4] --- --- @param expr any --- @return any function vim.fn.perleval(expr) end --- Return the power of {x} to the exponent {y} as a |Float|. --- {x} and {y} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. --- Examples: >vim --- echo pow(3, 3) --- < 27.0 >vim --- echo pow(2, 16) --- < 65536.0 >vim --- echo pow(32, 0.20) --- < 2.0 --- --- @param x any --- @param y any --- @return any function vim.fn.pow(x, y) end --- Return the line number of the first line at or above {lnum} --- that is not blank. Example: >vim --- let ind = indent(prevnonblank(v:lnum - 1)) --- <When {lnum} is invalid or there is no non-blank line at or --- above it, zero is returned. --- {lnum} is used like with |getline()|. --- Also see |nextnonblank()|. --- --- @param lnum integer --- @return any function vim.fn.prevnonblank(lnum) end --- Return a String with {fmt}, where "%" items are replaced by --- the formatted form of their respective arguments. Example: >vim --- echo printf("%4d: E%d %.30s", lnum, errno, msg) --- <May result in: --- " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ --- --- When used as a |method| the base is passed as the second --- argument: >vim --- Compute()->printf("result: %d") --- < --- You can use `call()` to pass the items as a list. --- --- Often used items are: --- %s string --- %6S string right-aligned in 6 display cells --- %6s string right-aligned in 6 bytes --- %.9s string truncated to 9 bytes --- %c single byte --- %d decimal number --- %5d decimal number padded with spaces to 5 characters --- %b binary number --- %08b binary number padded with zeros to at least 8 characters --- %B binary number using upper case letters --- %x hex number --- %04x hex number padded with zeros to at least 4 characters --- %X hex number using upper case letters --- %o octal number --- %f floating point number as 12.23, inf, -inf or nan --- %F floating point number as 12.23, INF, -INF or NAN --- %e floating point number as 1.23e3, inf, -inf or nan --- %E floating point number as 1.23E3, INF, -INF or NAN --- %g floating point number, as %f or %e depending on value --- %G floating point number, as %F or %E depending on value --- %% the % character itself --- %p representation of the pointer to the container --- --- Conversion specifications start with '%' and end with the --- conversion type. All other characters are copied unchanged to --- the result. --- --- The "%" starts a conversion specification. The following --- arguments appear in sequence: --- --- % [pos-argument] [flags] [field-width] [.precision] type --- --- pos-argument --- At most one positional argument specifier. These --- take the form {n$}, where n is >= 1. --- --- flags --- Zero or more of the following flags: --- --- # The value should be converted to an "alternate --- form". For c, d, and s conversions, this option --- has no effect. For o conversions, the precision --- of the number is increased to force the first --- character of the output string to a zero (except --- if a zero value is printed with an explicit --- precision of zero). --- For x and X conversions, a non-zero result has --- the string "0x" (or "0X" for X conversions) --- prepended to it. --- --- 0 (zero) Zero padding. For all conversions the converted --- value is padded on the left with zeros rather --- than blanks. If a precision is given with a --- numeric conversion (d, o, x, and X), the 0 flag --- is ignored. --- --- - A negative field width flag; the converted value --- is to be left adjusted on the field boundary. --- The converted value is padded on the right with --- blanks, rather than on the left with blanks or --- zeros. A - overrides a 0 if both are given. --- --- ' ' (space) A blank should be left before a positive --- number produced by a signed conversion (d). --- --- + A sign must always be placed before a number --- produced by a signed conversion. A + overrides --- a space if both are used. --- --- field-width --- An optional decimal digit string specifying a minimum --- field width. If the converted value has fewer bytes --- than the field width, it will be padded with spaces on --- the left (or right, if the left-adjustment flag has --- been given) to fill out the field width. For the S --- conversion the count is in cells. --- --- .precision --- An optional precision, in the form of a period '.' --- followed by an optional digit string. If the digit --- string is omitted, the precision is taken as zero. --- This gives the minimum number of digits to appear for --- d, o, x, and X conversions, the maximum number of --- bytes to be printed from a string for s conversions, --- or the maximum number of cells to be printed from a --- string for S conversions. --- For floating point it is the number of digits after --- the decimal point. --- --- type --- A character that specifies the type of conversion to --- be applied, see below. --- --- A field width or precision, or both, may be indicated by an --- asterisk "*" instead of a digit string. In this case, a --- Number argument supplies the field width or precision. A --- negative field width is treated as a left adjustment flag --- followed by a positive field width; a negative precision is --- treated as though it were missing. Example: >vim --- echo printf("%d: %.*s", nr, width, line) --- <This limits the length of the text used from "line" to --- "width" bytes. --- --- If the argument to be formatted is specified using a posional --- argument specifier, and a '*' is used to indicate that a --- number argument is to be used to specify the width or --- precision, the argument(s) to be used must also be specified --- using a {n$} positional argument specifier. See |printf-$|. --- --- The conversion specifiers and their meanings are: --- --- *printf-d* *printf-b* *printf-B* *printf-o* *printf-x* *printf-X* --- dbBoxX The Number argument is converted to signed decimal (d), --- unsigned binary (b and B), unsigned octal (o), or --- unsigned hexadecimal (x and X) notation. The letters --- "abcdef" are used for x conversions; the letters --- "ABCDEF" are used for X conversions. The precision, if --- any, gives the minimum number of digits that must --- appear; if the converted value requires fewer digits, it --- is padded on the left with zeros. In no case does a --- non-existent or small field width cause truncation of a --- numeric field; if the result of a conversion is wider --- than the field width, the field is expanded to contain --- the conversion result. --- The 'h' modifier indicates the argument is 16 bits. --- The 'l' modifier indicates the argument is a long --- integer. The size will be 32 bits or 64 bits --- depending on your platform. --- The "ll" modifier indicates the argument is 64 bits. --- The b and B conversion specifiers never take a width --- modifier and always assume their argument is a 64 bit --- integer. --- Generally, these modifiers are not useful. They are --- ignored when type is known from the argument. --- --- i alias for d --- D alias for ld --- U alias for lu --- O alias for lo --- --- *printf-c* --- c The Number argument is converted to a byte, and the --- resulting character is written. --- --- *printf-s* --- s The text of the String argument is used. If a --- precision is specified, no more bytes than the number --- specified are used. --- If the argument is not a String type, it is --- automatically converted to text with the same format --- as ":echo". --- *printf-S* --- S The text of the String argument is used. If a --- precision is specified, no more display cells than the --- number specified are used. --- --- *printf-f* *E807* --- f F The Float argument is converted into a string of the --- form 123.456. The precision specifies the number of --- digits after the decimal point. When the precision is --- zero the decimal point is omitted. When the precision --- is not specified 6 is used. A really big number --- (out of range or dividing by zero) results in "inf" --- or "-inf" with %f (INF or -INF with %F). --- "0.0 / 0.0" results in "nan" with %f (NAN with %F). --- Example: >vim --- echo printf("%.2f", 12.115) --- < 12.12 --- Note that roundoff depends on the system libraries. --- Use |round()| when in doubt. --- --- *printf-e* *printf-E* --- e E The Float argument is converted into a string of the --- form 1.234e+03 or 1.234E+03 when using 'E'. The --- precision specifies the number of digits after the --- decimal point, like with 'f'. --- --- *printf-g* *printf-G* --- g G The Float argument is converted like with 'f' if the --- value is between 0.001 (inclusive) and 10000000.0 --- (exclusive). Otherwise 'e' is used for 'g' and 'E' --- for 'G'. When no precision is specified superfluous --- zeroes and '+' signs are removed, except for the zero --- immediately after the decimal point. Thus 10000000.0 --- results in 1.0e7. --- --- *printf-%* --- % A '%' is written. No argument is converted. The --- complete conversion specification is "%%". --- --- When a Number argument is expected a String argument is also --- accepted and automatically converted. --- When a Float or String argument is expected a Number argument --- is also accepted and automatically converted. --- Any other argument type results in an error message. --- --- *E766* *E767* --- The number of {exprN} arguments must exactly match the number --- of "%" items. If there are not sufficient or too many --- arguments an error is given. Up to 18 arguments can be used. --- --- *printf-$* --- In certain languages, error and informative messages are --- more readable when the order of words is different from the --- corresponding message in English. To accommodate translations --- having a different word order, positional arguments may be --- used to indicate this. For instance: >vim --- --- #, c-format --- msgid "%s returning %s" --- msgstr "waarde %2$s komt terug van %1$s" --- < --- In this example, the sentence has its 2 string arguments reversed --- in the output. >vim --- --- echo printf( --- "In The Netherlands, vim's creator's name is: %1$s %2$s", --- "Bram", "Moolenaar") --- < In The Netherlands, vim's creator's name is: Bram Moolenaar >vim --- --- echo printf( --- "In Belgium, vim's creator's name is: %2$s %1$s", --- "Bram", "Moolenaar") --- < In Belgium, vim's creator's name is: Moolenaar Bram --- --- Width (and precision) can be specified using the '*' specifier. --- In this case, you must specify the field width position in the --- argument list. >vim --- --- echo printf("%1$*2$.*3$d", 1, 2, 3) --- < 001 >vim --- echo printf("%2$*3$.*1$d", 1, 2, 3) --- < 2 >vim --- echo printf("%3$*1$.*2$d", 1, 2, 3) --- < 03 >vim --- echo printf("%1$*2$.*3$g", 1.4142, 2, 3) --- < 1.414 --- --- You can mix specifying the width and/or precision directly --- and via positional arguments: >vim --- --- echo printf("%1$4.*2$f", 1.4142135, 6) --- < 1.414214 >vim --- echo printf("%1$*2$.4f", 1.4142135, 6) --- < 1.4142 >vim --- echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) --- < 1.41 --- --- *E1500* --- You cannot mix positional and non-positional arguments: >vim --- echo printf("%s%1$s", "One", "Two") --- < E1500: Cannot mix positional and non-positional --- arguments: %s%1$s --- --- *E1501* --- You cannot skip a positional argument in a format string: >vim --- echo printf("%3$s%1$s", "One", "Two", "Three") --- < E1501: format argument 2 unused in $-style --- format: %3$s%1$s --- --- *E1502* --- You can re-use a [field-width] (or [precision]) argument: >vim --- echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2) --- < 1 at width 2 is: 01 --- --- However, you can't use it as a different type: >vim --- echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2) --- < E1502: Positional argument 2 used as field --- width reused as different type: long int/int --- --- *E1503* --- When a positional argument is used, but not the correct number --- or arguments is given, an error is raised: >vim --- echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2) --- < E1503: Positional argument 3 out of bounds: --- %1$d at width %2$d is: %01$*2$.*3$d --- --- Only the first error is reported: >vim --- echo printf("%01$*2$.*3$d %4$d", 1, 2) --- < E1503: Positional argument 3 out of bounds: --- %01$*2$.*3$d %4$d --- --- *E1504* --- A positional argument can be used more than once: >vim --- echo printf("%1$s %2$s %1$s", "One", "Two") --- < One Two One --- --- However, you can't use a different type the second time: >vim --- echo printf("%1$s %2$s %1$d", "One", "Two") --- < E1504: Positional argument 1 type used --- inconsistently: int/string --- --- *E1505* --- Various other errors that lead to a format string being --- wrongly formatted lead to: >vim --- echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2) --- < E1505: Invalid format specifier: --- %1$d at width %2$d is: %01$*2$.3$d --- --- *E1507* --- This internal error indicates that the logic to parse a --- positional format argument ran into a problem that couldn't be --- otherwise reported. Please file a bug against Vim if you run --- into this, copying the exact format string and parameters that --- were used. --- --- @param fmt any --- @param expr1? any --- @return any function vim.fn.printf(fmt, expr1) end --- Returns the effective prompt text for buffer {buf}. {buf} can --- be a buffer name or number. See |prompt-buffer|. --- --- If the buffer doesn't exist or isn't a prompt buffer, an empty --- string is returned. --- --- @param buf any --- @return any function vim.fn.prompt_getprompt(buf) end --- Set prompt callback for buffer {buf} to {expr}. When {expr} --- is an empty string the callback is removed. This has only --- effect if {buf} has 'buftype' set to "prompt". --- --- The callback is invoked when pressing Enter. The current --- buffer will always be the prompt buffer. A new line for a --- prompt is added before invoking the callback, thus the prompt --- for which the callback was invoked will be in the last but one --- line. --- If the callback wants to add text to the buffer, it must --- insert it above the last line, since that is where the current --- prompt is. This can also be done asynchronously. --- The callback is invoked with one argument, which is the text --- that was entered at the prompt. This can be an empty string --- if the user only typed Enter. --- Example: >vim --- func s:TextEntered(text) --- if a:text == 'exit' || a:text == 'quit' --- stopinsert --- " Reset 'modified' to allow the buffer to be closed. --- " We assume there is nothing useful to be saved. --- set nomodified --- close --- else --- " Do something useful with "a:text". In this example --- " we just repeat it. --- call append(line('$') - 1, 'Entered: "' .. a:text .. '"') --- endif --- endfunc --- call prompt_setcallback(bufnr(), function('s:TextEntered')) --- --- @param buf any --- @param expr any --- @return any function vim.fn.prompt_setcallback(buf, expr) end --- Set a callback for buffer {buf} to {expr}. When {expr} is an --- empty string the callback is removed. This has only effect if --- {buf} has 'buftype' set to "prompt". --- --- This callback will be invoked when pressing CTRL-C in Insert --- mode. Without setting a callback Vim will exit Insert mode, --- as in any buffer. --- --- @param buf any --- @param expr any --- @return any function vim.fn.prompt_setinterrupt(buf, expr) end --- Set prompt for buffer {buf} to {text}. You most likely want --- {text} to end in a space. --- The result is only visible if {buf} has 'buftype' set to --- "prompt". Example: >vim --- call prompt_setprompt(bufnr(''), 'command: ') --- < --- --- @param buf any --- @param text any --- @return any function vim.fn.prompt_setprompt(buf, text) end --- If the popup menu (see |ins-completion-menu|) is not visible, --- returns an empty |Dictionary|, otherwise, returns a --- |Dictionary| with the following keys: --- height nr of items visible --- width screen cells --- row top screen row (0 first row) --- col leftmost screen column (0 first col) --- size total nr of items --- scrollbar |TRUE| if scrollbar is visible --- --- The values are the same as in |v:event| during |CompleteChanged|. --- --- @return any function vim.fn.pum_getpos() end --- Returns non-zero when the popup menu is visible, zero --- otherwise. See |ins-completion-menu|. --- This can be used to avoid some things that would remove the --- popup menu. --- --- @return any function vim.fn.pumvisible() end --- Evaluate Python expression {expr} and return its result --- converted to Vim data structures. --- Numbers and strings are returned as they are (strings are --- copied though, Unicode strings are additionally converted to --- UTF-8). --- Lists are represented as Vim |List| type. --- Dictionaries are represented as Vim |Dictionary| type with --- keys converted to strings. --- --- @param expr any --- @return any function vim.fn.py3eval(expr) end --- Evaluate Python expression {expr} and return its result --- converted to Vim data structures. --- Numbers and strings are returned as they are (strings are --- copied though). --- Lists are represented as Vim |List| type. --- Dictionaries are represented as Vim |Dictionary| type, --- non-string keys result in error. --- --- @param expr any --- @return any function vim.fn.pyeval(expr) end --- Evaluate Python expression {expr} and return its result --- converted to Vim data structures. --- Uses Python 2 or 3, see |python_x| and 'pyxversion'. --- See also: |pyeval()|, |py3eval()| --- --- @param expr any --- @return any function vim.fn.pyxeval(expr) end --- Return a pseudo-random Number generated with an xoshiro128** --- algorithm using seed {expr}. The returned number is 32 bits, --- also on 64 bits systems, for consistency. --- {expr} can be initialized by |srand()| and will be updated by --- rand(). If {expr} is omitted, an internal seed value is used --- and updated. --- Returns -1 if {expr} is invalid. --- --- Examples: >vim --- echo rand() --- let seed = srand() --- echo rand(seed) --- echo rand(seed) % 16 " random number 0 - 15 --- < --- --- @param expr? any --- @return any function vim.fn.rand(expr) end --- Returns a |List| with Numbers: --- - If only {expr} is specified: [0, 1, ..., {expr} - 1] --- - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] --- - If {stride} is specified: [{expr}, {expr} + {stride}, ..., --- {max}] (increasing {expr} with {stride} each time, not --- producing a value past {max}). --- When the maximum is one before the start the result is an --- empty list. When the maximum is more than one before the --- start this is an error. --- Examples: >vim --- echo range(4) " [0, 1, 2, 3] --- echo range(2, 4) " [2, 3, 4] --- echo range(2, 9, 3) " [2, 5, 8] --- echo range(2, -2, -1) " [2, 1, 0, -1, -2] --- echo range(0) " [] --- echo range(2, 0) " error! --- < --- --- @param expr any --- @param max? any --- @param stride? any --- @return any function vim.fn.range(expr, max, stride) end --- Read file {fname} in binary mode and return a |Blob|. --- If {offset} is specified, read the file from the specified --- offset. If it is a negative value, it is used as an offset --- from the end of the file. E.g., to read the last 12 bytes: >vim --- echo readblob('file.bin', -12) --- <If {size} is specified, only the specified size will be read. --- E.g. to read the first 100 bytes of a file: >vim --- echo readblob('file.bin', 0, 100) --- <If {size} is -1 or omitted, the whole data starting from --- {offset} will be read. --- This can be also used to read the data from a character device --- on Unix when {size} is explicitly set. Only if the device --- supports seeking {offset} can be used. Otherwise it should be --- zero. E.g. to read 10 bytes from a serial console: >vim --- echo readblob('/dev/ttyS0', 0, 10) --- <When the file can't be opened an error message is given and --- the result is an empty |Blob|. --- When the offset is beyond the end of the file the result is an --- empty blob. --- When trying to read more bytes than are available the result --- is truncated. --- Also see |readfile()| and |writefile()|. --- --- @param fname string --- @param offset? any --- @param size? any --- @return any function vim.fn.readblob(fname, offset, size) end --- Return a list with file and directory names in {directory}. --- You can also use |glob()| if you don't need to do complicated --- things, such as limiting the number of matches. --- --- When {expr} is omitted all entries are included. --- When {expr} is given, it is evaluated to check what to do: --- If {expr} results in -1 then no further entries will --- be handled. --- If {expr} results in 0 then this entry will not be --- added to the list. --- If {expr} results in 1 then this entry will be added --- to the list. --- Each time {expr} is evaluated |v:val| is set to the entry name. --- When {expr} is a function the name is passed as the argument. --- For example, to get a list of files ending in ".txt": >vim --- echo readdir(dirname, {n -> n =~ '.txt$'}) --- <To skip hidden and backup files: >vim --- echo readdir(dirname, {n -> n !~ '^\.\|\~$'}) --- --- <If you want to get a directory tree: >vim --- function! s:tree(dir) --- return {a:dir : map(readdir(a:dir), --- \ {_, x -> isdirectory(x) ? --- \ {x : s:tree(a:dir .. '/' .. x)} : x})} --- endfunction --- echo s:tree(".") --- < --- Returns an empty List on error. --- --- @param directory any --- @param expr? any --- @return any function vim.fn.readdir(directory, expr) end --- Read file {fname} and return a |List|, each line of the file --- as an item. Lines are broken at NL characters. Macintosh --- files separated with CR will result in a single long line --- (unless a NL appears somewhere). --- All NUL characters are replaced with a NL character. --- When {type} contains "b" binary mode is used: --- - When the last line ends in a NL an extra empty list item is --- added. --- - No CR characters are removed. --- Otherwise: --- - CR characters that appear before a NL are removed. --- - Whether the last line ends in a NL or not does not matter. --- - Any UTF-8 byte order mark is removed from the text. --- When {max} is given this specifies the maximum number of lines --- to be read. Useful if you only want to check the first ten --- lines of a file: >vim --- for line in readfile(fname, '', 10) --- if line =~ 'Date' | echo line | endif --- endfor --- <When {max} is negative -{max} lines from the end of the file --- are returned, or as many as there are. --- When {max} is zero the result is an empty list. --- Note that without {max} the whole file is read into memory. --- Also note that there is no recognition of encoding. Read a --- file into a buffer if you need to. --- Deprecated (use |readblob()| instead): When {type} contains --- "B" a |Blob| is returned with the binary data of the file --- unmodified. --- When the file can't be opened an error message is given and --- the result is an empty list. --- Also see |writefile()|. --- --- @param fname string --- @param type? any --- @param max? any --- @return any function vim.fn.readfile(fname, type, max) end --- {func} is called for every item in {object}, which can be a --- |String|, |List| or a |Blob|. {func} is called with two --- arguments: the result so far and current item. After --- processing all items the result is returned. --- --- {initial} is the initial result. When omitted, the first item --- in {object} is used and {func} is first called for the second --- item. If {initial} is not given and {object} is empty no --- result can be computed, an E998 error is given. --- --- Examples: >vim --- echo reduce([1, 3, 5], { acc, val -> acc + val }) --- echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') --- echo reduce(0z1122, { acc, val -> 2 * acc + val }) --- echo reduce('xyz', { acc, val -> acc .. ',' .. val }) --- < --- --- @param object any --- @param func any --- @param initial? any --- @return any function vim.fn.reduce(object, func, initial) end --- Returns the single letter name of the register being executed. --- Returns an empty string when no register is being executed. --- See |\@|. --- --- @return any function vim.fn.reg_executing() end --- Returns the single letter name of the last recorded register. --- Returns an empty string when nothing was recorded yet. --- See |q| and |Q|. --- --- @return any function vim.fn.reg_recorded() end --- Returns the single letter name of the register being recorded. --- Returns an empty string when not recording. See |q|. --- --- @return any function vim.fn.reg_recording() end --- @return any function vim.fn.reltime() end --- @param start? any --- @return any function vim.fn.reltime(start) end --- Return an item that represents a time value. The item is a --- list with items that depend on the system. --- The item can be passed to |reltimestr()| to convert it to a --- string or |reltimefloat()| to convert to a Float. --- --- Without an argument it returns the current "relative time", an --- implementation-defined value meaningful only when used as an --- argument to |reltime()|, |reltimestr()| and |reltimefloat()|. --- --- With one argument it returns the time passed since the time --- specified in the argument. --- With two arguments it returns the time passed between {start} --- and {end}. --- --- The {start} and {end} arguments must be values returned by --- reltime(). Returns zero on error. --- --- Note: |localtime()| returns the current (non-relative) time. --- --- @param start? any --- @param end_? any --- @return any function vim.fn.reltime(start, end_) end --- Return a Float that represents the time value of {time}. --- Unit of time is seconds. --- Example: --- let start = reltime() --- call MyFunction() --- let seconds = reltimefloat(reltime(start)) --- See the note of reltimestr() about overhead. --- Also see |profiling|. --- If there is an error an empty string is returned --- --- @param time any --- @return any function vim.fn.reltimefloat(time) end --- Return a String that represents the time value of {time}. --- This is the number of seconds, a dot and the number of --- microseconds. Example: >vim --- let start = reltime() --- call MyFunction() --- echo reltimestr(reltime(start)) --- <Note that overhead for the commands will be added to the time. --- Leading spaces are used to make the string align nicely. You --- can use split() to remove it. >vim --- echo split(reltimestr(reltime(start)))[0] --- <Also see |profiling|. --- If there is an error an empty string is returned --- --- @param time any --- @return any function vim.fn.reltimestr(time) end --- @param list any --- @param idx integer --- @return any function vim.fn.remove(list, idx) end --- Without {end}: Remove the item at {idx} from |List| {list} and --- return the item. --- With {end}: Remove items from {idx} to {end} (inclusive) and --- return a |List| with these items. When {idx} points to the same --- item as {end} a list with one item is returned. When {end} --- points to an item before {idx} this is an error. --- See |list-index| for possible values of {idx} and {end}. --- Returns zero on error. --- Example: >vim --- echo "last item: " .. remove(mylist, -1) --- call remove(mylist, 0, 9) --- < --- Use |delete()| to remove a file. --- --- @param list any --- @param idx integer --- @param end_? any --- @return any function vim.fn.remove(list, idx, end_) end --- @param blob any --- @param idx integer --- @return any function vim.fn.remove(blob, idx) end --- Without {end}: Remove the byte at {idx} from |Blob| {blob} and --- return the byte. --- With {end}: Remove bytes from {idx} to {end} (inclusive) and --- return a |Blob| with these bytes. When {idx} points to the same --- byte as {end} a |Blob| with one byte is returned. When {end} --- points to a byte before {idx} this is an error. --- Returns zero on error. --- Example: >vim --- echo "last byte: " .. remove(myblob, -1) --- call remove(mylist, 0, 9) --- < --- --- @param blob any --- @param idx integer --- @param end_? any --- @return any function vim.fn.remove(blob, idx, end_) end --- Remove the entry from {dict} with key {key} and return it. --- Example: >vim --- echo "removed " .. remove(dict, "one") --- <If there is no {key} in {dict} this is an error. --- Returns zero on error. --- --- @param dict any --- @param key any --- @return any function vim.fn.remove(dict, key) end --- Rename the file by the name {from} to the name {to}. This --- should also work to move files across file systems. The --- result is a Number, which is 0 if the file was renamed --- successfully, and non-zero when the renaming failed. --- NOTE: If {to} exists it is overwritten without warning. --- This function is not available in the |sandbox|. --- --- @param from any --- @param to any --- @return any function vim.fn.rename(from, to) end --- Repeat {expr} {count} times and return the concatenated --- result. Example: >vim --- let separator = repeat('-', 80) --- <When {count} is zero or negative the result is empty. --- When {expr} is a |List| or a |Blob| the result is {expr} --- concatenated {count} times. Example: >vim --- let longlist = repeat(['a', 'b'], 3) --- <Results in ['a', 'b', 'a', 'b', 'a', 'b']. --- --- @param expr any --- @param count any --- @return any vim.fn['repeat'] = function(expr, count) end --- On MS-Windows, when {filename} is a shortcut (a .lnk file), --- returns the path the shortcut points to in a simplified form. --- On Unix, repeat resolving symbolic links in all path --- components of {filename} and return the simplified result. --- To cope with link cycles, resolving of symbolic links is --- stopped after 100 iterations. --- On other systems, return the simplified {filename}. --- The simplification step is done as by |simplify()|. --- resolve() keeps a leading path component specifying the --- current directory (provided the result is still a relative --- path name) and also keeps a trailing path separator. --- --- @param filename any --- @return any function vim.fn.resolve(filename) end --- Reverse the order of items in {object}. {object} can be a --- |List|, a |Blob| or a |String|. For a List and a Blob the --- items are reversed in-place and {object} is returned. --- For a String a new String is returned. --- Returns zero if {object} is not a List, Blob or a String. --- If you want a List or Blob to remain unmodified make a copy --- first: >vim --- let revlist = reverse(copy(mylist)) --- < --- --- @param object any --- @return any function vim.fn.reverse(object) end --- Round off {expr} to the nearest integral value and return it --- as a |Float|. If {expr} lies halfway between two integral --- values, then use the larger one (away from zero). --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo round(0.456) --- < 0.0 >vim --- echo round(4.5) --- < 5.0 >vim --- echo round(-4.5) --- < -5.0 --- --- @param expr any --- @return any function vim.fn.round(expr) end --- Sends {event} to {channel} via |RPC| and returns immediately. --- If {channel} is 0, the event is broadcast to all channels. --- Example: >vim --- au VimLeave call rpcnotify(0, "leaving") --- < --- --- @param channel any --- @param event any --- @param args? any --- @return any function vim.fn.rpcnotify(channel, event, args) end --- Sends a request to {channel} to invoke {method} via --- |RPC| and blocks until a response is received. --- Example: >vim --- let result = rpcrequest(rpc_chan, "func", 1, 2, 3) --- < --- --- @param channel any --- @param method any --- @param args? any --- @return any function vim.fn.rpcrequest(channel, method, args) end --- Deprecated. Replace >vim --- let id = rpcstart('prog', ['arg1', 'arg2']) --- <with >vim --- let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) --- < --- --- @param prog any --- @param argv? any --- @return any function vim.fn.rpcstart(prog, argv) end --- @deprecated --- Use |jobstop()| instead to stop any job, or --- `chanclose(id, "rpc")` to close RPC communication --- without stopping the job. Use chanclose(id) to close --- any socket. --- --- @param ... any --- @return any function vim.fn.rpcstop(...) end --- Evaluate Ruby expression {expr} and return its result --- converted to Vim data structures. --- Numbers, floats and strings are returned as they are (strings --- are copied though). --- Arrays are represented as Vim |List| type. --- Hashes are represented as Vim |Dictionary| type. --- Other objects are represented as strings resulted from their --- "Object#to_s" method. --- --- @param expr any --- @return any function vim.fn.rubyeval(expr) end --- Like |screenchar()|, but return the attribute. This is a rather --- arbitrary number that can only be used to compare to the --- attribute at other positions. --- Returns -1 when row or col is out of range. --- --- @param row any --- @param col integer --- @return any function vim.fn.screenattr(row, col) end --- The result is a Number, which is the character at position --- [row, col] on the screen. This works for every possible --- screen position, also status lines, window separators and the --- command line. The top left position is row one, column one --- The character excludes composing characters. For double-byte --- encodings it may only be the first byte. --- This is mainly to be used for testing. --- Returns -1 when row or col is out of range. --- --- @param row any --- @param col integer --- @return any function vim.fn.screenchar(row, col) end --- The result is a |List| of Numbers. The first number is the same --- as what |screenchar()| returns. Further numbers are --- composing characters on top of the base character. --- This is mainly to be used for testing. --- Returns an empty List when row or col is out of range. --- --- @param row any --- @param col integer --- @return any function vim.fn.screenchars(row, col) end --- The result is a Number, which is the current screen column of --- the cursor. The leftmost column has number 1. --- This function is mainly used for testing. --- --- Note: Always returns the current screen column, thus if used --- in a command (e.g. ":echo screencol()") it will return the --- column inside the command line, which is 1 when the command is --- executed. To get the cursor position in the file use one of --- the following mappings: >vim --- nnoremap <expr> GG ":echom " .. screencol() .. "\n" --- nnoremap <silent> GG :echom screencol()<CR> --- noremap GG <Cmd>echom screencol()<Cr> --- < --- --- @return any function vim.fn.screencol() end --- The result is a Dict with the screen position of the text --- character in window {winid} at buffer line {lnum} and column --- {col}. {col} is a one-based byte index. --- The Dict has these members: --- row screen row --- col first screen column --- endcol last screen column --- curscol cursor screen column --- If the specified position is not visible, all values are zero. --- The "endcol" value differs from "col" when the character --- occupies more than one screen cell. E.g. for a Tab "col" can --- be 1 and "endcol" can be 8. --- The "curscol" value is where the cursor would be placed. For --- a Tab it would be the same as "endcol", while for a double --- width character it would be the same as "col". --- The |conceal| feature is ignored here, the column numbers are --- as if 'conceallevel' is zero. You can set the cursor to the --- right position and use |screencol()| to get the value with --- |conceal| taken into account. --- If the position is in a closed fold the screen position of the --- first character is returned, {col} is not used. --- Returns an empty Dict if {winid} is invalid. --- --- @param winid integer --- @param lnum integer --- @param col integer --- @return any function vim.fn.screenpos(winid, lnum, col) end --- The result is a Number, which is the current screen row of the --- cursor. The top line has number one. --- This function is mainly used for testing. --- Alternatively you can use |winline()|. --- --- Note: Same restrictions as with |screencol()|. --- --- @return any function vim.fn.screenrow() end --- The result is a String that contains the base character and --- any composing characters at position [row, col] on the screen. --- This is like |screenchars()| but returning a String with the --- characters. --- This is mainly to be used for testing. --- Returns an empty String when row or col is out of range. --- --- @param row any --- @param col integer --- @return any function vim.fn.screenstring(row, col) end --- Search for regexp pattern {pattern}. The search starts at the --- cursor position (you can use |cursor()| to set it). --- --- When a match has been found its line number is returned. --- If there is no match a 0 is returned and the cursor doesn't --- move. No error message is given. --- --- {flags} is a String, which can contain these character flags: --- 'b' search Backward instead of forward --- 'c' accept a match at the Cursor position --- 'e' move to the End of the match --- 'n' do Not move the cursor --- 'p' return number of matching sub-Pattern (see below) --- 's' Set the ' mark at the previous location of the cursor --- 'w' Wrap around the end of the file --- 'W' don't Wrap around the end of the file --- 'z' start searching at the cursor column instead of Zero --- If neither 'w' or 'W' is given, the 'wrapscan' option applies. --- --- If the 's' flag is supplied, the ' mark is set, only if the --- cursor is moved. The 's' flag cannot be combined with the 'n' --- flag. --- --- 'ignorecase', 'smartcase' and 'magic' are used. --- --- When the 'z' flag is not given, forward searching always --- starts in column zero and then matches before the cursor are --- skipped. When the 'c' flag is present in 'cpo' the next --- search starts after the match. Without the 'c' flag the next --- search starts one column after the start of the match. This --- matters for overlapping matches. See |cpo-c|. You can also --- insert "\ze" to change where the match ends, see |/\ze|. --- --- When searching backwards and the 'z' flag is given then the --- search starts in column zero, thus no match in the current --- line will be found (unless wrapping around the end of the --- file). --- --- When the {stopline} argument is given then the search stops --- after searching this line. This is useful to restrict the --- search to a range of lines. Examples: >vim --- let match = search('(', 'b', line("w0")) --- let end = search('END', '', line("w$")) --- <When {stopline} is used and it is not zero this also implies --- that the search does not wrap around the end of the file. --- A zero value is equal to not giving the argument. --- --- When the {timeout} argument is given the search stops when --- more than this many milliseconds have passed. Thus when --- {timeout} is 500 the search stops after half a second. --- The value must not be negative. A zero value is like not --- giving the argument. --- --- If the {skip} expression is given it is evaluated with the --- cursor positioned on the start of a match. If it evaluates to --- non-zero this match is skipped. This can be used, for --- example, to skip a match in a comment or a string. --- {skip} can be a string, which is evaluated as an expression, a --- function reference or a lambda. --- When {skip} is omitted or empty, every match is accepted. --- When evaluating {skip} causes an error the search is aborted --- and -1 returned. --- *search()-sub-match* --- With the 'p' flag the returned value is one more than the --- first sub-match in \(\). One if none of them matched but the --- whole pattern did match. --- To get the column number too use |searchpos()|. --- --- The cursor will be positioned at the match, unless the 'n' --- flag is used. --- --- Example (goes over all files in the argument list): >vim --- let n = 1 --- while n <= argc() " loop over all files in arglist --- exe "argument " .. n --- " start at the last char in the file and wrap for the --- " first search to find match at start of file --- normal G$ --- let flags = "w" --- while search("foo", flags) > 0 --- s/foo/bar/g --- let flags = "W" --- endwhile --- update " write the file if modified --- let n = n + 1 --- endwhile --- < --- Example for using some flags: >vim --- echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') --- <This will search for the keywords "if", "else", and "endif" --- under or after the cursor. Because of the 'p' flag, it --- returns 1, 2, or 3 depending on which keyword is found, or 0 --- if the search fails. With the cursor on the first word of the --- line: --- if (foo == 0) | let foo = foo + 1 | endif ~ --- the function returns 1. Without the 'c' flag, the function --- finds the "endif" and returns 3. The same thing happens --- without the 'e' flag if the cursor is on the "f" of "if". --- The 'n' flag tells the function not to move the cursor. --- --- @param pattern any --- @param flags? string --- @param stopline? any --- @param timeout? integer --- @param skip? any --- @return any function vim.fn.search(pattern, flags, stopline, timeout, skip) end --- Get or update the last search count, like what is displayed --- without the "S" flag in 'shortmess'. This works even if --- 'shortmess' does contain the "S" flag. --- --- This returns a |Dictionary|. The dictionary is empty if the --- previous pattern was not set and "pattern" was not specified. --- --- key type meaning ~ --- current |Number| current position of match; --- 0 if the cursor position is --- before the first match --- exact_match |Boolean| 1 if "current" is matched on --- "pos", otherwise 0 --- total |Number| total count of matches found --- incomplete |Number| 0: search was fully completed --- 1: recomputing was timed out --- 2: max count exceeded --- --- For {options} see further down. --- --- To get the last search count when |n| or |N| was pressed, call --- this function with `recompute: 0` . This sometimes returns --- wrong information because |n| and |N|'s maximum count is 99. --- If it exceeded 99 the result must be max count + 1 (100). If --- you want to get correct information, specify `recompute: 1`: >vim --- --- " result == maxcount + 1 (100) when many matches --- let result = searchcount(#{recompute: 0}) --- --- " Below returns correct result (recompute defaults --- " to 1) --- let result = searchcount() --- < --- The function is useful to add the count to 'statusline': >vim --- function! LastSearchCount() abort --- let result = searchcount(#{recompute: 0}) --- if empty(result) --- return '' --- endif --- if result.incomplete ==# 1 " timed out --- return printf(' /%s [?/??]', \@/) --- elseif result.incomplete ==# 2 " max count exceeded --- if result.total > result.maxcount && --- \ result.current > result.maxcount --- return printf(' /%s [>%d/>%d]', \@/, --- \ result.current, result.total) --- elseif result.total > result.maxcount --- return printf(' /%s [%d/>%d]', \@/, --- \ result.current, result.total) --- endif --- endif --- return printf(' /%s [%d/%d]', \@/, --- \ result.current, result.total) --- endfunction --- let &statusline ..= '%{LastSearchCount()}' --- --- " Or if you want to show the count only when --- " 'hlsearch' was on --- " let &statusline ..= --- " \ '%{v:hlsearch ? LastSearchCount() : ""}' --- < --- You can also update the search count, which can be useful in a --- |CursorMoved| or |CursorMovedI| autocommand: >vim --- --- autocmd CursorMoved,CursorMovedI * --- \ let s:searchcount_timer = timer_start( --- \ 200, function('s:update_searchcount')) --- function! s:update_searchcount(timer) abort --- if a:timer ==# s:searchcount_timer --- call searchcount(#{ --- \ recompute: 1, maxcount: 0, timeout: 100}) --- redrawstatus --- endif --- endfunction --- < --- This can also be used to count matched texts with specified --- pattern in the current buffer using "pattern": >vim --- --- " Count '\<foo\>' in this buffer --- " (Note that it also updates search count) --- let result = searchcount(#{pattern: '\<foo\>'}) --- --- " To restore old search count by old pattern, --- " search again --- call searchcount() --- < --- {options} must be a |Dictionary|. It can contain: --- key type meaning ~ --- recompute |Boolean| if |TRUE|, recompute the count --- like |n| or |N| was executed. --- otherwise returns the last --- computed result (when |n| or --- |N| was used when "S" is not --- in 'shortmess', or this --- function was called). --- (default: |TRUE|) --- pattern |String| recompute if this was given --- and different with |\@/|. --- this works as same as the --- below command is executed --- before calling this function >vim --- let \@/ = pattern --- < (default: |\@/|) --- timeout |Number| 0 or negative number is no --- timeout. timeout milliseconds --- for recomputing the result --- (default: 0) --- maxcount |Number| 0 or negative number is no --- limit. max count of matched --- text while recomputing the --- result. if search exceeded --- total count, "total" value --- becomes `maxcount + 1` --- (default: 0) --- pos |List| `[lnum, col, off]` value --- when recomputing the result. --- this changes "current" result --- value. see |cursor()|, |getpos()| --- (default: cursor's position) --- --- @param options? table --- @return any function vim.fn.searchcount(options) end --- Search for the declaration of {name}. --- --- With a non-zero {global} argument it works like |gD|, find --- first match in the file. Otherwise it works like |gd|, find --- first match in the function. --- --- With a non-zero {thisblock} argument matches in a {} block --- that ends before the cursor position are ignored. Avoids --- finding variable declarations only valid in another scope. --- --- Moves the cursor to the found match. --- Returns zero for success, non-zero for failure. --- Example: >vim --- if searchdecl('myvar') == 0 --- echo getline('.') --- endif --- < --- --- @param name string --- @param global? any --- @param thisblock? any --- @return any function vim.fn.searchdecl(name, global, thisblock) end --- Search for the match of a nested start-end pair. This can be --- used to find the "endif" that matches an "if", while other --- if/endif pairs in between are ignored. --- The search starts at the cursor. The default is to search --- forward, include 'b' in {flags} to search backward. --- If a match is found, the cursor is positioned at it and the --- line number is returned. If no match is found 0 or -1 is --- returned and the cursor doesn't move. No error message is --- given. --- --- {start}, {middle} and {end} are patterns, see |pattern|. They --- must not contain \( \) pairs. Use of \%( \) is allowed. When --- {middle} is not empty, it is found when searching from either --- direction, but only when not in a nested start-end pair. A --- typical use is: >vim --- echo searchpair('\<if\>', '\<else\>', '\<endif\>') --- <By leaving {middle} empty the "else" is skipped. --- --- {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with --- |search()|. Additionally: --- 'r' Repeat until no more matches found; will find the --- outer pair. Implies the 'W' flag. --- 'm' Return number of matches instead of line number with --- the match; will be > 1 when 'r' is used. --- Note: it's nearly always a good idea to use the 'W' flag, to --- avoid wrapping around the end of the file. --- --- When a match for {start}, {middle} or {end} is found, the --- {skip} expression is evaluated with the cursor positioned on --- the start of the match. It should return non-zero if this --- match is to be skipped. E.g., because it is inside a comment --- or a string. --- When {skip} is omitted or empty, every match is accepted. --- When evaluating {skip} causes an error the search is aborted --- and -1 returned. --- {skip} can be a string, a lambda, a funcref or a partial. --- Anything else makes the function fail. --- --- For {stopline} and {timeout} see |search()|. --- --- The value of 'ignorecase' is used. 'magic' is ignored, the --- patterns are used like it's on. --- --- The search starts exactly at the cursor. A match with --- {start}, {middle} or {end} at the next character, in the --- direction of searching, is the first one found. Example: >vim --- if 1 --- if 2 --- endif 2 --- endif 1 --- <When starting at the "if 2", with the cursor on the "i", and --- searching forwards, the "endif 2" is found. When starting on --- the character just before the "if 2", the "endif 1" will be --- found. That's because the "if 2" will be found first, and --- then this is considered to be a nested if/endif from "if 2" to --- "endif 2". --- When searching backwards and {end} is more than one character, --- it may be useful to put "\zs" at the end of the pattern, so --- that when the cursor is inside a match with the end it finds --- the matching start. --- --- Example, to find the "endif" command in a Vim script: >vim --- --- echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', --- \ 'getline(".") =~ "^\\s*\""') --- --- <The cursor must be at or after the "if" for which a match is --- to be found. Note that single-quote strings are used to avoid --- having to double the backslashes. The skip expression only --- catches comments at the start of a line, not after a command. --- Also, a word "en" or "if" halfway through a line is considered --- a match. --- Another example, to search for the matching "{" of a "}": >vim --- --- echo searchpair('{', '', '}', 'bW') --- --- <This works when the cursor is at or before the "}" for which a --- match is to be found. To reject matches that syntax --- highlighting recognized as strings: >vim --- --- echo searchpair('{', '', '}', 'bW', --- \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') --- < --- --- @return any function vim.fn.searchpair() end --- Same as |searchpair()|, but returns a |List| with the line and --- column position of the match. The first element of the |List| --- is the line number and the second element is the byte index of --- the column position of the match. If no match is found, --- returns [0, 0]. >vim --- --- let [lnum,col] = searchpairpos('{', '', '}', 'n') --- < --- See |match-parens| for a bigger and more useful example. --- --- @return any function vim.fn.searchpairpos() end --- Same as |search()|, but returns a |List| with the line and --- column position of the match. The first element of the |List| --- is the line number and the second element is the byte index of --- the column position of the match. If no match is found, --- returns [0, 0]. --- Example: >vim --- let [lnum, col] = searchpos('mypattern', 'n') --- --- <When the 'p' flag is given then there is an extra item with --- the sub-pattern match number |search()-sub-match|. Example: >vim --- let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') --- <In this example "submatch" is 2 when a lowercase letter is --- found |/\l|, 3 when an uppercase letter is found |/\u|. --- --- @param pattern any --- @param flags? string --- @param stopline? any --- @param timeout? integer --- @param skip? any --- @return any function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end --- Returns a list of server addresses, or empty if all servers --- were stopped. |serverstart()| |serverstop()| --- Example: >vim --- echo serverlist() --- < --- --- @return any function vim.fn.serverlist() end --- Opens a socket or named pipe at {address} and listens for --- |RPC| messages. Clients can send |API| commands to the --- returned address to control Nvim. --- --- Returns the address string (which may differ from the --- {address} argument, see below). --- --- - If {address} has a colon (":") it is a TCP/IPv4/IPv6 address --- where the last ":" separates host and port (empty or zero --- assigns a random port). --- - Else {address} is the path to a named pipe (except on Windows). --- - If {address} has no slashes ("/") it is treated as the --- "name" part of a generated path in this format: >vim --- stdpath("run").."/{name}.{pid}.{counter}" --- < - If {address} is omitted the name is "nvim". >vim --- echo serverstart() --- < > --- => /tmp/nvim.bram/oknANW/nvim.15430.5 --- < --- Example bash command to list all Nvim servers: >bash --- ls ${XDG_RUNTIME_DIR:-${TMPDIR}nvim.${USER}}/*/nvim.*.0 --- --- <Example named pipe: >vim --- if has('win32') --- echo serverstart('\\.\pipe\nvim-pipe-1234') --- else --- echo serverstart('nvim.sock') --- endif --- < --- Example TCP/IP address: >vim --- echo serverstart('::1:12345') --- < --- --- @param address? any --- @return any function vim.fn.serverstart(address) end --- Closes the pipe or socket at {address}. --- Returns TRUE if {address} is valid, else FALSE. --- If |v:servername| is stopped it is set to the next available --- address in |serverlist()|. --- --- @param address any --- @return any function vim.fn.serverstop(address) end --- Set line {lnum} to {text} in buffer {buf}. This works like --- |setline()| for the specified buffer. --- --- This function works only for loaded buffers. First call --- |bufload()| if needed. --- --- To insert lines use |appendbufline()|. --- --- {text} can be a string to set one line, or a List of strings --- to set multiple lines. If the List extends below the last --- line then those lines are added. If the List is empty then --- nothing is changed and zero is returned. --- --- For the use of {buf}, see |bufname()| above. --- --- {lnum} is used like with |setline()|. --- Use "$" to refer to the last line in buffer {buf}. --- When {lnum} is just below the last line the {text} will be --- added below the last line. --- 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. --- --- @param buf any --- @param lnum integer --- @param text any --- @return any function vim.fn.setbufline(buf, lnum, text) end --- Set option or local variable {varname} in buffer {buf} to --- {val}. --- This also works for a global or local window option, but it --- doesn't work for a global or local window variable. --- For a local window option the global value is unchanged. --- For the use of {buf}, see |bufname()| above. --- The {varname} argument is a string. --- Note that the variable name without "b:" must be used. --- Examples: >vim --- call setbufvar(1, "&mod", 1) --- call setbufvar("todo", "myvar", "foobar") --- <This function is not available in the |sandbox|. --- --- @param buf any --- @param varname string --- @param val any --- @return any function vim.fn.setbufvar(buf, varname, val) end --- Specify overrides for cell widths of character ranges. This --- tells Vim how wide characters are when displayed in the --- terminal, counted in screen cells. The values override --- 'ambiwidth'. Example: >vim --- call setcellwidths([ --- \ [0x111, 0x111, 1], --- \ [0x2194, 0x2199, 2], --- \ ]) --- --- <The {list} argument is a List of Lists with each three --- numbers: [{low}, {high}, {width}]. *E1109* *E1110* --- {low} and {high} can be the same, in which case this refers to --- one character. Otherwise it is the range of characters from --- {low} to {high} (inclusive). *E1111* *E1114* --- Only characters with value 0x80 and higher can be used. --- --- {width} must be either 1 or 2, indicating the character width --- in screen cells. *E1112* --- An error is given if the argument is invalid, also when a --- range overlaps with another. *E1113* --- --- If the new value causes 'fillchars' or 'listchars' to become --- invalid it is rejected and an error is given. --- --- To clear the overrides pass an empty {list}: >vim --- call setcellwidths([]) --- --- <You can use the script $VIMRUNTIME/tools/emoji_list.vim to see --- the effect for known emoji characters. Move the cursor --- through the text to check if the cell widths of your terminal --- match with what Vim knows about each emoji. If it doesn't --- look right you need to adjust the {list} argument. --- --- @param list any --- @return any function vim.fn.setcellwidths(list) end --- Same as |setpos()| but uses the specified column number as the --- character index instead of the byte index in the line. --- --- Example: --- With the text "μ¬λ³΄μΈμ" in line 8: >vim --- call setcharpos('.', [0, 8, 4, 0]) --- <positions the cursor on the fourth character 'μ'. >vim --- call setpos('.', [0, 8, 4, 0]) --- <positions the cursor on the second character '보'. --- --- @param expr any --- @param list any --- @return any function vim.fn.setcharpos(expr, list) end --- Set the current character search information to {dict}, --- which contains one or more of the following entries: --- --- char character which will be used for a subsequent --- |,| or |;| command; an empty string clears the --- character search --- forward direction of character search; 1 for forward, --- 0 for backward --- until type of character search; 1 for a |t| or |T| --- character search, 0 for an |f| or |F| --- character search --- --- This can be useful to save/restore a user's character search --- from a script: >vim --- let prevsearch = getcharsearch() --- " Perform a command which clobbers user's search --- call setcharsearch(prevsearch) --- <Also see |getcharsearch()|. --- --- @param dict any --- @return any function vim.fn.setcharsearch(dict) end --- Set the command line to {str} and set the cursor position to --- {pos}. --- If {pos} is omitted, the cursor is positioned after the text. --- Returns 0 when successful, 1 when not editing the command --- line. --- --- @param str any --- @param pos? any --- @return any function vim.fn.setcmdline(str, pos) end --- Set the cursor position in the command line to byte position --- {pos}. The first position is 1. --- Use |getcmdpos()| to obtain the current position. --- Only works while editing the command line, thus you must use --- |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For --- |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is --- set after the command line is set to the expression. For --- |c_CTRL-R_=| it is set after evaluating the expression but --- before inserting the resulting text. --- When the number is too big the cursor is put at the end of the --- line. A number smaller than one has undefined results. --- Returns 0 when successful, 1 when not editing the command --- line. --- --- @param pos any --- @return any function vim.fn.setcmdpos(pos) end --- @param lnum integer --- @param col? integer --- @param off? any --- @return any function vim.fn.setcursorcharpos(lnum, col, off) end --- Same as |cursor()| but uses the specified column number as the --- character index instead of the byte index in the line. --- --- Example: --- With the text "μ¬λ³΄μΈμ" in line 4: >vim --- call setcursorcharpos(4, 3) --- <positions the cursor on the third character 'μΈ'. >vim --- call cursor(4, 3) --- <positions the cursor on the first character 'μ¬'. --- --- @param list any --- @return any function vim.fn.setcursorcharpos(list) end --- Set environment variable {name} to {val}. Example: >vim --- call setenv('HOME', '/home/myhome') --- --- <When {val} is |v:null| the environment variable is deleted. --- See also |expr-env|. --- --- @param name string --- @param val any --- @return any function vim.fn.setenv(name, val) end --- Set the file permissions for {fname} to {mode}. --- {mode} must be a string with 9 characters. It is of the form --- "rwxrwxrwx", where each group of "rwx" flags represent, in --- turn, the permissions of the owner of the file, the group the --- file belongs to, and other users. A '-' character means the --- permission is off, any other character means on. Multi-byte --- characters are not supported. --- --- For example "rw-r-----" means read-write for the user, --- readable by the group, not accessible by others. "xx-x-----" --- would do the same thing. --- --- Returns non-zero for success, zero for failure. --- --- To read permissions see |getfperm()|. --- --- @param fname string --- @param mode string --- @return any function vim.fn.setfperm(fname, mode) end --- Set line {lnum} of the current buffer to {text}. To insert --- lines use |append()|. To set lines in another buffer use --- |setbufline()|. --- --- {lnum} is used like with |getline()|. --- When {lnum} is just below the last line the {text} will be --- added below the last line. --- {text} can be any type or a List of any type, each item is --- converted to a String. When {text} is an empty List then --- nothing is changed and FALSE is returned. --- --- If this succeeds, FALSE is returned. If this fails (most likely --- because {lnum} is invalid) TRUE is returned. --- --- Example: >vim --- call setline(5, strftime("%c")) --- --- <When {text} is a |List| then line {lnum} and following lines --- will be set to the items in the list. Example: >vim --- call setline(5, ['aaa', 'bbb', 'ccc']) --- <This is equivalent to: >vim --- for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] --- call setline(n, l) --- endfor --- --- <Note: The '[ and '] marks are not set. --- --- @param lnum integer --- @param text any --- @return any function vim.fn.setline(lnum, text) end --- Create or replace or add to the location list for window {nr}. --- {nr} can be the window number or the |window-ID|. --- When {nr} is zero the current window is used. --- --- For a location list window, the displayed location list is --- modified. For an invalid window number {nr}, -1 is returned. --- Otherwise, same as |setqflist()|. --- Also see |location-list|. --- --- For {action} see |setqflist-action|. --- --- If the optional {what} dictionary argument is supplied, then --- only the items listed in {what} are set. Refer to |setqflist()| --- for the list of supported keys in {what}. --- --- @param nr integer --- @param list any --- @param action? any --- @param what? any --- @return any function vim.fn.setloclist(nr, list, action, what) end --- Restores a list of matches saved by |getmatches()| for the --- current window. Returns 0 if successful, otherwise -1. All --- current matches are cleared before the list is restored. See --- example for |getmatches()|. --- If {win} is specified, use the window with this number or --- window ID instead of the current window. --- --- @param list any --- @param win? any --- @return any function vim.fn.setmatches(list, win) end --- Set the position for String {expr}. Possible values: --- . the cursor --- 'x mark x --- --- {list} must be a |List| with four or five numbers: --- [bufnum, lnum, col, off] --- [bufnum, lnum, col, off, curswant] --- --- "bufnum" is the buffer number. Zero can be used for the --- current buffer. When setting an uppercase mark "bufnum" is --- used for the mark position. For other marks it specifies the --- buffer to set the mark in. You can use the |bufnr()| function --- to turn a file name into a buffer number. --- For setting the cursor and the ' mark "bufnum" is ignored, --- since these are associated with a window, not a buffer. --- Does not change the jumplist. --- --- "lnum" and "col" are the position in the buffer. The first --- column is 1. Use a zero "lnum" to delete a mark. If "col" is --- smaller than 1 then 1 is used. To use the character count --- instead of the byte count, use |setcharpos()|. --- --- The "off" number is only used when 'virtualedit' is set. Then --- it is the offset in screen columns from the start of the --- character. E.g., a position within a <Tab> or after the last --- character. --- --- The "curswant" number is only used when setting the cursor --- position. It sets the preferred column for when moving the --- cursor vertically. When the "curswant" number is missing the --- preferred column is not set. When it is present and setting a --- mark position it is not used. --- --- Note that for '< and '> changing the line number may result in --- the marks to be effectively be swapped, so that '< is always --- before '>. --- --- Returns 0 when the position could be set, -1 otherwise. --- An error message is given if {expr} is invalid. --- --- Also see |setcharpos()|, |getpos()| and |getcurpos()|. --- --- This does not restore the preferred column for moving --- vertically; if you set the cursor position with this, |j| and --- |k| motions will jump to previous columns! Use |cursor()| to --- also set the preferred column. Also see the "curswant" key in --- |winrestview()|. --- --- @param expr any --- @param list any --- @return any function vim.fn.setpos(expr, list) end --- Create or replace or add to the quickfix list. --- --- If the optional {what} dictionary argument is supplied, then --- only the items listed in {what} are set. The first {list} --- argument is ignored. See below for the supported items in --- {what}. --- *setqflist-what* --- When {what} is not present, the items in {list} are used. Each --- item must be a dictionary. Non-dictionary items in {list} are --- ignored. Each dictionary item can contain the following --- entries: --- --- bufnr buffer number; must be the number of a valid --- buffer --- filename name of a file; only used when "bufnr" is not --- present or it is invalid. --- module name of a module; if given it will be used in --- quickfix error window instead of the filename. --- lnum line number in the file --- end_lnum end of lines, if the item spans multiple lines --- pattern search pattern used to locate the error --- col column number --- vcol when non-zero: "col" is visual column --- when zero: "col" is byte index --- end_col end column, if the item spans multiple columns --- nr error number --- text description of the error --- type single-character error type, 'E', 'W', etc. --- valid recognized error message --- user_data --- custom data associated with the item, can be --- any type. --- --- The "col", "vcol", "nr", "type" and "text" entries are --- optional. Either "lnum" or "pattern" entry can be used to --- locate a matching error line. --- If the "filename" and "bufnr" entries are not present or --- neither the "lnum" or "pattern" entries are present, then the --- item will not be handled as an error line. --- If both "pattern" and "lnum" are present then "pattern" will --- be used. --- If the "valid" entry is not supplied, then the valid flag is --- set when "bufnr" is a valid buffer or "filename" exists. --- If you supply an empty {list}, the quickfix list will be --- cleared. --- Note that the list is not exactly the same as what --- |getqflist()| returns. --- --- {action} values: *setqflist-action* *E927* --- 'a' The items from {list} are added to the existing --- quickfix list. If there is no existing list, then a --- new list is created. --- --- 'r' The items from the current quickfix list are replaced --- with the items from {list}. This can also be used to --- clear the list: >vim --- call setqflist([], 'r') --- < --- 'f' All the quickfix lists in the quickfix stack are --- freed. --- --- If {action} is not present or is set to ' ', then a new list --- is created. The new quickfix list is added after the current --- quickfix list in the stack and all the following lists are --- freed. To add a new quickfix list at the end of the stack, --- set "nr" in {what} to "$". --- --- The following items can be specified in dictionary {what}: --- context quickfix list context. See |quickfix-context| --- efm errorformat to use when parsing text from --- "lines". If this is not present, then the --- 'errorformat' option value is used. --- See |quickfix-parse| --- id quickfix list identifier |quickfix-ID| --- idx index of the current entry in the quickfix --- list specified by "id" or "nr". If set to '$', --- then the last entry in the list is set as the --- current entry. See |quickfix-index| --- items list of quickfix entries. Same as the {list} --- argument. --- lines use 'errorformat' to parse a list of lines and --- add the resulting entries to the quickfix list --- {nr} or {id}. Only a |List| value is supported. --- See |quickfix-parse| --- nr list number in the quickfix stack; zero --- means the current quickfix list and "$" means --- the last quickfix list. --- quickfixtextfunc --- function to get the text to display in the --- quickfix window. The value can be the name of --- a function or a funcref or a lambda. Refer to --- |quickfix-window-function| for an explanation --- of how to write the function and an example. --- title quickfix list title text. See |quickfix-title| --- Unsupported keys in {what} are ignored. --- If the "nr" item is not present, then the current quickfix list --- is modified. When creating a new quickfix list, "nr" can be --- set to a value one greater than the quickfix stack size. --- When modifying a quickfix list, to guarantee that the correct --- list is modified, "id" should be used instead of "nr" to --- specify the list. --- --- Examples (See also |setqflist-examples|): >vim --- call setqflist([], 'r', {'title': 'My search'}) --- call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) --- call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) --- < --- Returns zero for success, -1 for failure. --- --- This function can be used to create a quickfix list --- independent of the 'errorformat' setting. Use a command like --- `:cc 1` to jump to the first position. --- --- @param list any --- @param action? any --- @param what? any --- @return any function vim.fn.setqflist(list, action, what) end --- Set the register {regname} to {value}. --- If {regname} is "" or "\@", the unnamed register '"' is used. --- The {regname} argument is a string. --- --- {value} may be any value returned by |getreg()| or --- |getreginfo()|, including a |List| or |Dict|. --- If {options} contains "a" or {regname} is upper case, --- then the value is appended. --- --- {options} can also contain a register type specification: --- "c" or "v" |charwise| mode --- "l" or "V" |linewise| mode --- "b" or "<CTRL-V>" |blockwise-visual| mode --- If a number immediately follows "b" or "<CTRL-V>" then this is --- used as the width of the selection - if it is not specified --- then the width of the block is set to the number of characters --- in the longest line (counting a <Tab> as 1 character). --- If {options} contains "u" or '"', then the unnamed register is --- set to point to register {regname}. --- --- If {options} contains no register settings, then the default --- is to use character mode unless {value} ends in a <NL> for --- string {value} and linewise mode for list {value}. Blockwise --- mode is never selected automatically. --- Returns zero for success, non-zero for failure. --- --- *E883* --- Note: you may not use |List| containing more than one item to --- set search and expression registers. Lists containing no --- items act like empty strings. --- --- Examples: >vim --- call setreg(v:register, \@*) --- call setreg('*', \@%, 'ac') --- call setreg('a', "1\n2\n3", 'b5') --- call setreg('"', { 'points_to': 'a'}) --- --- <This example shows using the functions to save and restore a --- register: >vim --- let var_a = getreginfo() --- call setreg('a', var_a) --- <or: >vim --- let var_a = getreg('a', 1, 1) --- let var_amode = getregtype('a') --- " .... --- call setreg('a', var_a, var_amode) --- <Note: you may not reliably restore register value --- without using the third argument to |getreg()| as without it --- newlines are represented as newlines AND Nul bytes are --- represented as newlines as well, see |NL-used-for-Nul|. --- --- You can also change the type of a register by appending --- nothing: >vim --- call setreg('a', '', 'al') --- --- @param regname string --- @param value any --- @param options? table --- @return any function vim.fn.setreg(regname, value, options) end --- Set tab-local variable {varname} to {val} in tab page {tabnr}. --- |t:var| --- The {varname} argument is a string. --- Note that the variable name without "t:" must be used. --- Tabs are numbered starting with one. --- This function is not available in the |sandbox|. --- --- @param tabnr integer --- @param varname string --- @param val any --- @return any function vim.fn.settabvar(tabnr, varname, val) end --- Set option or local variable {varname} in window {winnr} to --- {val}. --- Tabs are numbered starting with one. For the current tabpage --- use |setwinvar()|. --- {winnr} can be the window number or the |window-ID|. --- When {winnr} is zero the current window is used. --- This also works for a global or local buffer option, but it --- doesn't work for a global or local buffer variable. --- For a local buffer option the global value is unchanged. --- Note that the variable name without "w:" must be used. --- Examples: >vim --- call settabwinvar(1, 1, "&list", 0) --- call settabwinvar(3, 2, "myvar", "foobar") --- <This function is not available in the |sandbox|. --- --- @param tabnr integer --- @param winnr integer --- @param varname string --- @param val any --- @return any function vim.fn.settabwinvar(tabnr, winnr, varname, val) end --- Modify the tag stack of the window {nr} using {dict}. --- {nr} can be the window number or the |window-ID|. --- --- For a list of supported items in {dict}, refer to --- |gettagstack()|. "curidx" takes effect before changing the tag --- stack. --- *E962* --- How the tag stack is modified depends on the {action} --- argument: --- - If {action} is not present or is set to 'r', then the tag --- stack is replaced. --- - If {action} is set to 'a', then new entries from {dict} are --- pushed (added) onto the tag stack. --- - If {action} is set to 't', then all the entries from the --- current entry in the tag stack or "curidx" in {dict} are --- removed and then new entries are pushed to the stack. --- --- The current index is set to one after the length of the tag --- stack after the modification. --- --- Returns zero for success, -1 for failure. --- --- Examples (for more examples see |tagstack-examples|): --- Empty the tag stack of window 3: >vim --- call settagstack(3, {'items' : []}) --- --- < Save and restore the tag stack: >vim --- let stack = gettagstack(1003) --- " do something else --- call settagstack(1003, stack) --- unlet stack --- < --- --- @param nr integer --- @param dict any --- @param action? any --- @return any function vim.fn.settagstack(nr, dict, action) end --- Like |settabwinvar()| for the current tab page. --- Examples: >vim --- call setwinvar(1, "&list", 0) --- call setwinvar(2, "myvar", "foobar") --- --- @param nr integer --- @param varname string --- @param val any --- @return any function vim.fn.setwinvar(nr, varname, val) end --- Returns a String with 64 hex characters, which is the SHA256 --- checksum of {string}. --- --- @param string string --- @return any function vim.fn.sha256(string) end --- Escape {string} for use as a shell command argument. --- --- On Windows when 'shellslash' is not set, encloses {string} in --- double-quotes and doubles all double-quotes within {string}. --- Otherwise encloses {string} in single-quotes and replaces all --- "'" with "'\''". --- --- If {special} is a |non-zero-arg|: --- - Special items such as "!", "%", "#" and "<cword>" will be --- preceded by a backslash. The backslash will be removed again --- by the |:!| command. --- - The <NL> character is escaped. --- --- If 'shell' contains "csh" in the tail: --- - The "!" character will be escaped. This is because csh and --- tcsh use "!" for history replacement even in single-quotes. --- - The <NL> character is escaped (twice if {special} is --- a |non-zero-arg|). --- --- If 'shell' contains "fish" in the tail, the "\" character will --- be escaped because in fish it is used as an escape character --- inside single quotes. --- --- Example of use with a |:!| command: >vim --- exe '!dir ' .. shellescape(expand('<cfile>'), 1) --- <This results in a directory listing for the file under the --- cursor. Example of use with |system()|: >vim --- call system("chmod +w -- " .. shellescape(expand("%"))) --- <See also |::S|. --- --- @param string string --- @param special? any --- @return any function vim.fn.shellescape(string, special) end --- Returns the effective value of 'shiftwidth'. This is the --- 'shiftwidth' value unless it is zero, in which case it is the --- 'tabstop' value. To be backwards compatible in indent --- plugins, use this: >vim --- if exists('*shiftwidth') --- func s:sw() --- return shiftwidth() --- endfunc --- else --- func s:sw() --- return &sw --- endfunc --- endif --- <And then use s:sw() instead of &sw. --- --- When there is one argument {col} this is used as column number --- for which to return the 'shiftwidth' value. This matters for the --- 'vartabstop' feature. If no {col} argument is given, column 1 --- will be assumed. --- --- @param col? integer --- @return integer function vim.fn.shiftwidth(col) end --- @param name string --- @param dict? vim.fn.sign_define.dict --- @return 0|-1 function vim.fn.sign_define(name, dict) end --- Define a new sign named {name} or modify the attributes of an --- existing sign. This is similar to the |:sign-define| command. --- --- Prefix {name} with a unique text to avoid name collisions. --- There is no {group} like with placing signs. --- --- The {name} can be a String or a Number. The optional {dict} --- argument specifies the sign attributes. The following values --- are supported: --- icon full path to the bitmap file for the sign. --- linehl highlight group used for the whole line the --- sign is placed in. --- numhl highlight group used for the line number where --- the sign is placed. --- text text that is displayed when there is no icon --- or the GUI is not being used. --- texthl highlight group used for the text item --- culhl highlight group used for the text item when --- the cursor is on the same line as the sign and --- 'cursorline' is enabled. --- --- If the sign named {name} already exists, then the attributes --- of the sign are updated. --- --- The one argument {list} can be used to define a list of signs. --- Each list item is a dictionary with the above items in {dict} --- and a "name" item for the sign name. --- --- Returns 0 on success and -1 on failure. When the one argument --- {list} is used, then returns a List of values one for each --- defined sign. --- --- Examples: >vim --- call sign_define("mySign", { --- \ "text" : "=>", --- \ "texthl" : "Error", --- \ "linehl" : "Search"}) --- call sign_define([ --- \ {'name' : 'sign1', --- \ 'text' : '=>'}, --- \ {'name' : 'sign2', --- \ 'text' : '!!'} --- \ ]) --- < --- --- @param list vim.fn.sign_define.dict[] --- @return (0|-1)[] function vim.fn.sign_define(list) end --- Get a list of defined signs and their attributes. --- This is similar to the |:sign-list| command. --- --- If the {name} is not supplied, then a list of all the defined --- signs is returned. Otherwise the attribute of the specified --- sign is returned. --- --- Each list item in the returned value is a dictionary with the --- following entries: --- icon full path to the bitmap file of the sign --- linehl highlight group used for the whole line the --- sign is placed in; not present if not set. --- name name of the sign --- numhl highlight group used for the line number where --- the sign is placed; not present if not set. --- text text that is displayed when there is no icon --- or the GUI is not being used. --- texthl highlight group used for the text item; not --- present if not set. --- culhl highlight group used for the text item when --- the cursor is on the same line as the sign and --- 'cursorline' is enabled; not present if not --- set. --- --- Returns an empty List if there are no signs and when {name} is --- not found. --- --- Examples: >vim --- " Get a list of all the defined signs --- echo sign_getdefined() --- --- " Get the attribute of the sign named mySign --- echo sign_getdefined("mySign") --- < --- --- @param name? string --- @return vim.fn.sign_getdefined.ret.item[] function vim.fn.sign_getdefined(name) end --- Return a list of signs placed in a buffer or all the buffers. --- This is similar to the |:sign-place-list| command. --- --- If the optional buffer name {buf} is specified, then only the --- list of signs placed in that buffer is returned. For the use --- of {buf}, see |bufname()|. The optional {dict} can contain --- the following entries: --- group select only signs in this group --- id select sign with this identifier --- lnum select signs placed in this line. For the use --- of {lnum}, see |line()|. --- If {group} is "*", then signs in all the groups including the --- global group are returned. If {group} is not supplied or is an --- empty string, then only signs in the global group are --- returned. If no arguments are supplied, then signs in the --- global group placed in all the buffers are returned. --- See |sign-group|. --- --- Each list item in the returned value is a dictionary with the --- following entries: --- bufnr number of the buffer with the sign --- signs list of signs placed in {bufnr}. Each list --- item is a dictionary with the below listed --- entries --- --- The dictionary for each sign contains the following entries: --- group sign group. Set to '' for the global group. --- id identifier of the sign --- lnum line number where the sign is placed --- name name of the defined sign --- priority sign priority --- --- The returned signs in a buffer are ordered by their line --- number and priority. --- --- Returns an empty list on failure or if there are no placed --- signs. --- --- Examples: >vim --- " Get a List of signs placed in eval.c in the --- " global group --- echo sign_getplaced("eval.c") --- --- " Get a List of signs in group 'g1' placed in eval.c --- echo sign_getplaced("eval.c", {'group' : 'g1'}) --- --- " Get a List of signs placed at line 10 in eval.c --- echo sign_getplaced("eval.c", {'lnum' : 10}) --- --- " Get sign with identifier 10 placed in a.py --- echo sign_getplaced("a.py", {'id' : 10}) --- --- " Get sign with id 20 in group 'g1' placed in a.py --- echo sign_getplaced("a.py", {'group' : 'g1', --- \ 'id' : 20}) --- --- " Get a List of all the placed signs --- echo sign_getplaced() --- < --- --- @param buf? any --- @param dict? vim.fn.sign_getplaced.dict --- @return vim.fn.sign_getplaced.ret.item[] function vim.fn.sign_getplaced(buf, dict) end --- Open the buffer {buf} or jump to the window that contains --- {buf} and position the cursor at sign {id} in group {group}. --- This is similar to the |:sign-jump| command. --- --- If {group} is an empty string, then the global group is used. --- For the use of {buf}, see |bufname()|. --- --- Returns the line number of the sign. Returns -1 if the --- arguments are invalid. --- --- Example: >vim --- " Jump to sign 10 in the current buffer --- call sign_jump(10, '', '') --- < --- --- @param id integer --- @param group string --- @param buf integer|string --- @return integer function vim.fn.sign_jump(id, group, buf) end --- Place the sign defined as {name} at line {lnum} in file or --- buffer {buf} and assign {id} and {group} to sign. This is --- similar to the |:sign-place| command. --- --- If the sign identifier {id} is zero, then a new identifier is --- allocated. Otherwise the specified number is used. {group} is --- the sign group name. To use the global sign group, use an --- empty string. {group} functions as a namespace for {id}, thus --- two groups can use the same IDs. Refer to |sign-identifier| --- and |sign-group| for more information. --- --- {name} refers to a defined sign. --- {buf} refers to a buffer name or number. For the accepted --- values, see |bufname()|. --- --- The optional {dict} argument supports the following entries: --- lnum line number in the file or buffer --- {buf} where the sign is to be placed. --- For the accepted values, see |line()|. --- priority priority of the sign. See --- |sign-priority| for more information. --- --- If the optional {dict} is not specified, then it modifies the --- placed sign {id} in group {group} to use the defined sign --- {name}. --- --- Returns the sign identifier on success and -1 on failure. --- --- Examples: >vim --- " Place a sign named sign1 with id 5 at line 20 in --- " buffer json.c --- call sign_place(5, '', 'sign1', 'json.c', --- \ {'lnum' : 20}) --- --- " Updates sign 5 in buffer json.c to use sign2 --- call sign_place(5, '', 'sign2', 'json.c') --- --- " Place a sign named sign3 at line 30 in --- " buffer json.c with a new identifier --- let id = sign_place(0, '', 'sign3', 'json.c', --- \ {'lnum' : 30}) --- --- " Place a sign named sign4 with id 10 in group 'g3' --- " at line 40 in buffer json.c with priority 90 --- call sign_place(10, 'g3', 'sign4', 'json.c', --- \ {'lnum' : 40, 'priority' : 90}) --- < --- --- @param id any --- @param group any --- @param name string --- @param buf any --- @param dict? vim.fn.sign_place.dict --- @return integer function vim.fn.sign_place(id, group, name, buf, dict) end --- Place one or more signs. This is similar to the --- |sign_place()| function. The {list} argument specifies the --- List of signs to place. Each list item is a dict with the --- following sign attributes: --- buffer Buffer name or number. For the accepted --- values, see |bufname()|. --- group Sign group. {group} functions as a namespace --- for {id}, thus two groups can use the same --- IDs. If not specified or set to an empty --- string, then the global group is used. See --- |sign-group| for more information. --- id Sign identifier. If not specified or zero, --- then a new unique identifier is allocated. --- Otherwise the specified number is used. See --- |sign-identifier| for more information. --- lnum Line number in the buffer where the sign is to --- be placed. For the accepted values, see --- |line()|. --- name Name of the sign to place. See |sign_define()| --- for more information. --- priority Priority of the sign. When multiple signs are --- placed on a line, the sign with the highest --- priority is used. If not specified, the --- default value of 10 is used. See --- |sign-priority| for more information. --- --- If {id} refers to an existing sign, then the existing sign is --- modified to use the specified {name} and/or {priority}. --- --- Returns a List of sign identifiers. If failed to place a --- sign, the corresponding list item is set to -1. --- --- Examples: >vim --- " Place sign s1 with id 5 at line 20 and id 10 at line --- " 30 in buffer a.c --- let [n1, n2] = sign_placelist([ --- \ {'id' : 5, --- \ 'name' : 's1', --- \ 'buffer' : 'a.c', --- \ 'lnum' : 20}, --- \ {'id' : 10, --- \ 'name' : 's1', --- \ 'buffer' : 'a.c', --- \ 'lnum' : 30} --- \ ]) --- --- " Place sign s1 in buffer a.c at line 40 and 50 --- " with auto-generated identifiers --- let [n1, n2] = sign_placelist([ --- \ {'name' : 's1', --- \ 'buffer' : 'a.c', --- \ 'lnum' : 40}, --- \ {'name' : 's1', --- \ 'buffer' : 'a.c', --- \ 'lnum' : 50} --- \ ]) --- < --- --- @param list vim.fn.sign_placelist.list.item[] --- @return integer[] function vim.fn.sign_placelist(list) end --- @param name? string --- @return 0|-1 function vim.fn.sign_undefine(name) end --- Deletes a previously defined sign {name}. This is similar to --- the |:sign-undefine| command. If {name} is not supplied, then --- deletes all the defined signs. --- --- The one argument {list} can be used to undefine a list of --- signs. Each list item is the name of a sign. --- --- Returns 0 on success and -1 on failure. For the one argument --- {list} call, returns a list of values one for each undefined --- sign. --- --- Examples: >vim --- " Delete a sign named mySign --- call sign_undefine("mySign") --- --- " Delete signs 'sign1' and 'sign2' --- call sign_undefine(["sign1", "sign2"]) --- --- " Delete all the signs --- call sign_undefine() --- < --- --- @param list? string[] --- @return integer[] function vim.fn.sign_undefine(list) end --- Remove a previously placed sign in one or more buffers. This --- is similar to the |:sign-unplace| command. --- --- {group} is the sign group name. To use the global sign group, --- use an empty string. If {group} is set to "*", then all the --- groups including the global group are used. --- The signs in {group} are selected based on the entries in --- {dict}. The following optional entries in {dict} are --- supported: --- buffer buffer name or number. See |bufname()|. --- id sign identifier --- If {dict} is not supplied, then all the signs in {group} are --- removed. --- --- Returns 0 on success and -1 on failure. --- --- Examples: >vim --- " Remove sign 10 from buffer a.vim --- call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) --- --- " Remove sign 20 in group 'g1' from buffer 3 --- call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) --- --- " Remove all the signs in group 'g2' from buffer 10 --- call sign_unplace('g2', {'buffer' : 10}) --- --- " Remove sign 30 in group 'g3' from all the buffers --- call sign_unplace('g3', {'id' : 30}) --- --- " Remove all the signs placed in buffer 5 --- call sign_unplace('*', {'buffer' : 5}) --- --- " Remove the signs in group 'g4' from all the buffers --- call sign_unplace('g4') --- --- " Remove sign 40 from all the buffers --- call sign_unplace('*', {'id' : 40}) --- --- " Remove all the placed signs from all the buffers --- call sign_unplace('*') --- --- @param group string --- @param dict? vim.fn.sign_unplace.dict --- @return 0|-1 function vim.fn.sign_unplace(group, dict) end --- Remove previously placed signs from one or more buffers. This --- is similar to the |sign_unplace()| function. --- --- The {list} argument specifies the List of signs to remove. --- Each list item is a dict with the following sign attributes: --- buffer buffer name or number. For the accepted --- values, see |bufname()|. If not specified, --- then the specified sign is removed from all --- the buffers. --- group sign group name. If not specified or set to an --- empty string, then the global sign group is --- used. If set to "*", then all the groups --- including the global group are used. --- id sign identifier. If not specified, then all --- the signs in the specified group are removed. --- --- Returns a List where an entry is set to 0 if the corresponding --- sign was successfully removed or -1 on failure. --- --- Example: >vim --- " Remove sign with id 10 from buffer a.vim and sign --- " with id 20 from buffer b.vim --- call sign_unplacelist([ --- \ {'id' : 10, 'buffer' : "a.vim"}, --- \ {'id' : 20, 'buffer' : 'b.vim'}, --- \ ]) --- < --- --- @param list vim.fn.sign_unplacelist.list.item --- @return (0|-1)[] function vim.fn.sign_unplacelist(list) end --- Simplify the file name as much as possible without changing --- the meaning. Shortcuts (on MS-Windows) or symbolic links (on --- Unix) are not resolved. If the first path component in --- {filename} designates the current directory, this will be --- valid for the result as well. A trailing path separator is --- not removed either. On Unix "//path" is unchanged, but --- "///path" is simplified to "/path" (this follows the Posix --- standard). --- Example: >vim --- simplify("./dir/.././/file/") == "./file/" --- <Note: The combination "dir/.." is only removed if "dir" is --- a searchable directory or does not exist. On Unix, it is also --- removed when "dir" is a symbolic link within the same --- directory. In order to resolve all the involved symbolic --- links before simplifying the path name, use |resolve()|. --- --- @param filename any --- @return any function vim.fn.simplify(filename) end --- Return the sine of {expr}, measured in radians, as a |Float|. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo sin(100) --- < -0.506366 >vim --- echo sin(-4.01) --- < 0.763301 --- --- @param expr any --- @return any function vim.fn.sin(expr) end --- Return the hyperbolic sine of {expr} as a |Float| in the range --- [-inf, inf]. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo sinh(0.5) --- < 0.521095 >vim --- echo sinh(-0.9) --- < -1.026517 --- --- @param expr any --- @return any function vim.fn.sinh(expr) end --- Similar to using a |slice| "expr[start : end]", but "end" is --- used exclusive. And for a string the indexes are used as --- character indexes instead of byte indexes. --- Also, composing characters are not counted. --- When {end} is omitted the slice continues to the last item. --- When {end} is -1 the last item is omitted. --- Returns an empty value if {start} or {end} are invalid. --- --- @param expr any --- @param start any --- @param end_? any --- @return any function vim.fn.slice(expr, start, end_) end --- Connect a socket to an address. If {mode} is "pipe" then --- {address} should be the path of a local domain socket (on --- unix) or named pipe (on Windows). If {mode} is "tcp" then --- {address} should be of the form "host:port" where the host --- should be an ip adderess or host name, and port the port --- number. --- --- For "pipe" mode, see |luv-pipe-handle|. For "tcp" mode, see --- |luv-tcp-handle|. --- --- Returns a |channel| ID. Close the socket with |chanclose()|. --- Use |chansend()| to send data over a bytes socket, and --- |rpcrequest()| and |rpcnotify()| to communicate with a RPC --- socket. --- --- {opts} is an optional dictionary with these keys: --- |on_data| : callback invoked when data was read from socket --- data_buffered : read socket data in |channel-buffered| mode. --- rpc : If set, |msgpack-rpc| will be used to communicate --- over the socket. --- Returns: --- - The channel ID on success (greater than zero) --- - 0 on invalid arguments or connection failure. --- --- @param mode string --- @param address any --- @param opts? table --- @return any function vim.fn.sockconnect(mode, address, opts) end --- Sort the items in {list} in-place. Returns {list}. --- --- If you want a list to remain unmodified make a copy first: >vim --- let sortedlist = sort(copy(mylist)) --- --- <When {how} is omitted or is a string, then sort() uses the --- string representation of each item to sort on. Numbers sort --- after Strings, |Lists| after Numbers. For sorting text in the --- current buffer use |:sort|. --- --- When {how} is given and it is 'i' then case is ignored. --- For backwards compatibility, the value one can be used to --- ignore case. Zero means to not ignore case. --- --- When {how} is given and it is 'l' then the current collation --- locale is used for ordering. Implementation details: strcoll() --- is used to compare strings. See |:language| check or set the --- collation locale. |v:collate| can also be used to check the --- current locale. Sorting using the locale typically ignores --- case. Example: >vim --- " ΓΆ is sorted similarly to o with English locale. --- language collate en_US.UTF8 --- echo sort(['n', 'o', 'O', 'ΓΆ', 'p', 'z'], 'l') --- < ['n', 'o', 'O', 'ΓΆ', 'p', 'z'] ~ --- >vim --- " ΓΆ is sorted after z with Swedish locale. --- language collate sv_SE.UTF8 --- echo sort(['n', 'o', 'O', 'ΓΆ', 'p', 'z'], 'l') --- < ['n', 'o', 'O', 'p', 'z', 'ΓΆ'] ~ --- This does not work properly on Mac. --- --- When {how} is given and it is 'n' then all items will be --- sorted numerical (Implementation detail: this uses the --- strtod() function to parse numbers, Strings, Lists, Dicts and --- Funcrefs will be considered as being 0). --- --- When {how} is given and it is 'N' then all items will be --- sorted numerical. This is like 'n' but a string containing --- digits will be used as the number they represent. --- --- When {how} is given and it is 'f' then all items will be --- sorted numerical. All values must be a Number or a Float. --- --- When {how} is a |Funcref| or a function name, this function --- is called to compare items. The function is invoked with two --- items as argument and must return zero if they are equal, 1 or --- bigger if the first one sorts after the second one, -1 or --- smaller if the first one sorts before the second one. --- --- {dict} is for functions with the "dict" attribute. It will be --- used to set the local variable "self". |Dictionary-function| --- --- The sort is stable, items which compare equal (as number or as --- string) will keep their relative position. E.g., when sorting --- on numbers, text strings will sort next to each other, in the --- same order as they were originally. --- --- --- Example: >vim --- func MyCompare(i1, i2) --- return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 --- endfunc --- eval mylist->sort("MyCompare") --- <A shorter compare version for this specific simple case, which --- ignores overflow: >vim --- func MyCompare(i1, i2) --- return a:i1 - a:i2 --- endfunc --- <For a simple expression you can use a lambda: >vim --- eval mylist->sort({i1, i2 -> i1 - i2}) --- < --- --- @param list any --- @param how? any --- @param dict? any --- @return any function vim.fn.sort(list, how, dict) end --- Return the sound-folded equivalent of {word}. Uses the first --- language in 'spelllang' for the current window that supports --- soundfolding. 'spell' must be set. When no sound folding is --- possible the {word} is returned unmodified. --- This can be used for making spelling suggestions. Note that --- the method can be quite slow. --- --- @param word any --- @return any function vim.fn.soundfold(word) end --- Without argument: The result is the badly spelled word under --- or after the cursor. The cursor is moved to the start of the --- bad word. When no bad word is found in the cursor line the --- result is an empty string and the cursor doesn't move. --- --- With argument: The result is the first word in {sentence} that --- is badly spelled. If there are no spelling mistakes the --- result is an empty string. --- --- The return value is a list with two items: --- - The badly spelled word or an empty string. --- - The type of the spelling error: --- "bad" spelling mistake --- "rare" rare word --- "local" word only valid in another region --- "caps" word should start with Capital --- Example: >vim --- echo spellbadword("the quik brown fox") --- < ['quik', 'bad'] ~ --- --- The spelling information for the current window and the value --- of 'spelllang' are used. --- --- @param sentence? any --- @return any function vim.fn.spellbadword(sentence) end --- Return a |List| with spelling suggestions to replace {word}. --- When {max} is given up to this number of suggestions are --- returned. Otherwise up to 25 suggestions are returned. --- --- When the {capital} argument is given and it's non-zero only --- suggestions with a leading capital will be given. Use this --- after a match with 'spellcapcheck'. --- --- {word} can be a badly spelled word followed by other text. --- This allows for joining two words that were split. The --- suggestions also include the following text, thus you can --- replace a line. --- --- {word} may also be a good word. Similar words will then be --- returned. {word} itself is not included in the suggestions, --- although it may appear capitalized. --- --- The spelling information for the current window is used. The --- values of 'spelllang' and 'spellsuggest' are used. --- --- @param word any --- @param max? any --- @param capital? any --- @return any function vim.fn.spellsuggest(word, max, capital) end --- Make a |List| out of {string}. When {pattern} is omitted or --- empty each white-separated sequence of characters becomes an --- item. --- Otherwise the string is split where {pattern} matches, --- removing the matched characters. 'ignorecase' is not used --- here, add \c to ignore case. |/\c| --- When the first or last item is empty it is omitted, unless the --- {keepempty} argument is given and it's non-zero. --- Other empty items are kept when {pattern} matches at least one --- character or when {keepempty} is non-zero. --- Example: >vim --- let words = split(getline('.'), '\W\+') --- <To split a string in individual characters: >vim --- for c in split(mystring, '\zs') | endfor --- <If you want to keep the separator you can also use '\zs' at --- the end of the pattern: >vim --- echo split('abc:def:ghi', ':\zs') --- < > --- ['abc:', 'def:', 'ghi'] --- < --- Splitting a table where the first element can be empty: >vim --- let items = split(line, ':', 1) --- <The opposite function is |join()|. --- --- @param string string --- @param pattern? any --- @param keepempty? any --- @return any function vim.fn.split(string, pattern, keepempty) end --- Return the non-negative square root of Float {expr} as a --- |Float|. --- {expr} must evaluate to a |Float| or a |Number|. When {expr} --- is negative the result is NaN (Not a Number). Returns 0.0 if --- {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo sqrt(100) --- < 10.0 >vim --- echo sqrt(-4.01) --- < str2float("nan") --- NaN may be different, it depends on system libraries. --- --- @param expr any --- @return any function vim.fn.sqrt(expr) end --- Initialize seed used by |rand()|: --- - If {expr} is not given, seed values are initialized by --- reading from /dev/urandom, if possible, or using time(NULL) --- a.k.a. epoch time otherwise; this only has second accuracy. --- - If {expr} is given it must be a Number. It is used to --- initialize the seed values. This is useful for testing or --- when a predictable sequence is intended. --- --- Examples: >vim --- let seed = srand() --- let seed = srand(userinput) --- echo rand(seed) --- < --- --- @param expr? any --- @return any function vim.fn.srand(expr) end --- Return a string which contains characters indicating the --- current state. Mostly useful in callbacks that want to do --- work that may not always be safe. Roughly this works like: --- - callback uses state() to check if work is safe to do. --- Yes: then do it right away. --- No: add to work queue and add a |SafeState| autocommand. --- - When SafeState is triggered and executes your autocommand, --- check with `state()` if the work can be done now, and if yes --- remove it from the queue and execute. --- Remove the autocommand if the queue is now empty. --- Also see |mode()|. --- --- When {what} is given only characters in this string will be --- added. E.g, this checks if the screen has scrolled: >vim --- if state('s') == '' --- " screen has not scrolled --- < --- These characters indicate the state, generally indicating that --- something is busy: --- m halfway a mapping, :normal command, feedkeys() or --- stuffed command --- o operator pending, e.g. after |d| --- a Insert mode autocomplete active --- x executing an autocommand --- S not triggering SafeState, e.g. after |f| or a count --- c callback invoked, including timer (repeats for --- recursiveness up to "ccc") --- s screen has scrolled for messages --- --- @param what? string --- @return any function vim.fn.state(what) end --- With |--headless| this opens stdin and stdout as a |channel|. --- May be called only once. See |channel-stdio|. stderr is not --- handled by this function, see |v:stderr|. --- --- Close the stdio handles with |chanclose()|. Use |chansend()| --- to send data to stdout, and |rpcrequest()| and |rpcnotify()| --- to communicate over RPC. --- --- {opts} is a dictionary with these keys: --- |on_stdin| : callback invoked when stdin is written to. --- on_print : callback invoked when Nvim needs to print a --- message, with the message (whose type is string) --- as sole argument. --- stdin_buffered : read stdin in |channel-buffered| mode. --- rpc : If set, |msgpack-rpc| will be used to communicate --- over stdio --- Returns: --- - |channel-id| on success (value is always 1) --- - 0 on invalid arguments --- --- @param opts table --- @return any function vim.fn.stdioopen(opts) end --- Returns |standard-path| locations of various default files and --- directories. --- --- {what} Type Description ~ --- cache String Cache directory: arbitrary temporary --- storage for plugins, etc. --- config String User configuration directory. |init.vim| --- is stored here. --- config_dirs List Other configuration directories. --- data String User data directory. --- data_dirs List Other data directories. --- log String Logs directory (for use by plugins too). --- run String Run directory: temporary, local storage --- for sockets, named pipes, etc. --- state String Session state directory: storage for file --- drafts, swap, undo, |shada|. --- --- Example: >vim --- echo stdpath("config") --- < --- --- @param what 'cache'|'config'|'config_dirs'|'data'|'data_dirs'|'log'|'run'|'state' --- @return string|string[] function vim.fn.stdpath(what) end --- Convert String {string} to a Float. This mostly works the --- same as when using a floating point number in an expression, --- see |floating-point-format|. But it's a bit more permissive. --- E.g., "1e40" is accepted, while in an expression you need to --- write "1.0e40". The hexadecimal form "0x123" is also --- accepted, but not others, like binary or octal. --- When {quoted} is present and non-zero then embedded single --- quotes before the dot are ignored, thus "1'000.0" is a --- thousand. --- Text after the number is silently ignored. --- The decimal point is always '.', no matter what the locale is --- set to. A comma ends the number: "12,345.67" is converted to --- 12.0. You can strip out thousands separators with --- |substitute()|: >vim --- let f = str2float(substitute(text, ',', '', 'g')) --- < --- Returns 0.0 if the conversion fails. --- --- @param string string --- @param quoted? any --- @return any function vim.fn.str2float(string, quoted) end --- Return a list containing the number values which represent --- each character in String {string}. Examples: >vim --- echo str2list(" ") " returns [32] --- echo str2list("ABC") " returns [65, 66, 67] --- <|list2str()| does the opposite. --- --- UTF-8 encoding is always used, {utf8} option has no effect, --- and exists only for backwards-compatibility. --- With UTF-8 composing characters are handled properly: >vim --- echo str2list("aΜ") " returns [97, 769] --- --- @param string string --- @param utf8? any --- @return any function vim.fn.str2list(string, utf8) end --- Convert string {string} to a number. --- {base} is the conversion base, it can be 2, 8, 10 or 16. --- When {quoted} is present and non-zero then embedded single --- quotes are ignored, thus "1'000'000" is a million. --- --- When {base} is omitted base 10 is used. This also means that --- a leading zero doesn't cause octal conversion to be used, as --- with the default String to Number conversion. Example: >vim --- let nr = str2nr('0123') --- < --- When {base} is 16 a leading "0x" or "0X" is ignored. With a --- different base the result will be zero. Similarly, when --- {base} is 8 a leading "0", "0o" or "0O" is ignored, and when --- {base} is 2 a leading "0b" or "0B" is ignored. --- Text after the number is silently ignored. --- --- Returns 0 if {string} is empty or on error. --- --- @param string string --- @param base? any --- @return any function vim.fn.str2nr(string, base) end --- The result is a Number, which is the number of characters --- in String {string}. Composing characters are ignored. --- |strchars()| can count the number of characters, counting --- composing characters separately. --- --- Returns 0 if {string} is empty or on error. --- --- Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. --- --- @param string string --- @return any function vim.fn.strcharlen(string) end --- Like |strpart()| but using character index and length instead --- of byte index and length. --- When {skipcc} is omitted or zero, composing characters are --- counted separately. --- When {skipcc} set to 1, Composing characters are ignored, --- similar to |slice()|. --- When a character index is used where a character does not --- exist it is omitted and counted as one character. For --- example: >vim --- echo strcharpart('abc', -1, 2) --- <results in 'a'. --- --- Returns an empty string on error. --- --- @param src any --- @param start any --- @param len? any --- @param skipcc? any --- @return any function vim.fn.strcharpart(src, start, len, skipcc) end --- The result is a Number, which is the number of characters --- in String {string}. --- When {skipcc} is omitted or zero, composing characters are --- counted separately. --- When {skipcc} set to 1, Composing characters are ignored. --- |strcharlen()| always does this. --- --- Returns zero on error. --- --- Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. --- --- {skipcc} is only available after 7.4.755. For backward --- compatibility, you can define a wrapper function: >vim --- if has("patch-7.4.755") --- function s:strchars(str, skipcc) --- return strchars(a:str, a:skipcc) --- endfunction --- else --- function s:strchars(str, skipcc) --- if a:skipcc --- return strlen(substitute(a:str, ".", "x", "g")) --- else --- return strchars(a:str) --- endif --- endfunction --- endif --- < --- --- @param string string --- @param skipcc? any --- @return integer function vim.fn.strchars(string, skipcc) end --- The result is a Number, which is the number of display cells --- String {string} occupies on the screen when it starts at {col} --- (first column is zero). When {col} is omitted zero is used. --- Otherwise it is the screen column where to start. This --- matters for Tab characters. --- The option settings of the current window are used. This --- matters for anything that's displayed differently, such as --- 'tabstop' and 'display'. --- When {string} contains characters with East Asian Width Class --- Ambiguous, this function's return value depends on 'ambiwidth'. --- Returns zero on error. --- Also see |strlen()|, |strwidth()| and |strchars()|. --- --- @param string string --- @param col? integer --- @return integer function vim.fn.strdisplaywidth(string, col) end --- The result is a String, which is a formatted date and time, as --- specified by the {format} string. The given {time} is used, --- or the current time if no time is given. The accepted --- {format} depends on your system, thus this is not portable! --- See the manual page of the C function strftime() for the --- format. The maximum length of the result is 80 characters. --- See also |localtime()|, |getftime()| and |strptime()|. --- The language can be changed with the |:language| command. --- Examples: >vim --- echo strftime("%c") " Sun Apr 27 11:49:23 1997 --- echo strftime("%Y %b %d %X") " 1997 Apr 27 11:53:25 --- echo strftime("%y%m%d %T") " 970427 11:53:55 --- echo strftime("%H:%M") " 11:55 --- echo strftime("%c", getftime("file.c")) --- " Show mod time of file.c. --- --- @param format any --- @param time? any --- @return string function vim.fn.strftime(format, time) end --- Get a Number corresponding to the character at {index} in --- {str}. This uses a zero-based character index, not a byte --- index. Composing characters are considered separate --- characters here. Use |nr2char()| to convert the Number to a --- String. --- Returns -1 if {index} is invalid. --- Also see |strcharpart()| and |strchars()|. --- --- @param str string --- @param index integer --- @return integer function vim.fn.strgetchar(str, index) end --- The result is a Number, which gives the byte index in --- {haystack} of the first occurrence of the String {needle}. --- If {start} is specified, the search starts at index {start}. --- This can be used to find a second match: >vim --- let colon1 = stridx(line, ":") --- let colon2 = stridx(line, ":", colon1 + 1) --- <The search is done case-sensitive. --- For pattern searches use |match()|. --- -1 is returned if the {needle} does not occur in {haystack}. --- See also |strridx()|. --- Examples: >vim --- echo stridx("An Example", "Example") " 3 --- echo stridx("Starting point", "Start") " 0 --- echo stridx("Starting point", "start") " -1 --- < *strstr()* *strchr()* --- stridx() works similar to the C function strstr(). When used --- with a single character it works similar to strchr(). --- --- @param haystack string --- @param needle string --- @param start? integer --- @return integer function vim.fn.stridx(haystack, needle, start) end --- Return {expr} converted to a String. If {expr} is a Number, --- Float, String, Blob or a composition of them, then the result --- can be parsed back with |eval()|. --- {expr} type result ~ --- String 'string' --- Number 123 --- Float 123.123456 or 1.123456e8 or --- `str2float('inf')` --- Funcref `function('name')` --- Blob 0z00112233.44556677.8899 --- List [item, item] --- Dictionary `{key: value, key: value}` --- Note that in String values the ' character is doubled. --- Also see |strtrans()|. --- Note 2: Output format is mostly compatible with YAML, except --- for infinite and NaN floating-point values representations --- which use |str2float()|. Strings are also dumped literally, --- only single quote is escaped, which does not allow using YAML --- for parsing back binary strings. |eval()| should always work for --- strings and floats though and this is the only official --- method, use |msgpackdump()| or |json_encode()| if you need to --- share data with other application. --- --- @param expr any --- @return string function vim.fn.string(expr) end --- The result is a Number, which is the length of the String --- {string} in bytes. --- If the argument is a Number it is first converted to a String. --- For other types an error is given and zero is returned. --- If you want to count the number of multibyte characters use --- |strchars()|. --- Also see |len()|, |strdisplaywidth()| and |strwidth()|. --- --- @param string string --- @return integer function vim.fn.strlen(string) end --- The result is a String, which is part of {src}, starting from --- byte {start}, with the byte length {len}. --- When {chars} is present and TRUE then {len} is the number of --- characters positions (composing characters are not counted --- separately, thus "1" means one base character and any --- following composing characters). --- To count {start} as characters instead of bytes use --- |strcharpart()|. --- --- When bytes are selected which do not exist, this doesn't --- result in an error, the bytes are simply omitted. --- If {len} is missing, the copy continues from {start} till the --- end of the {src}. >vim --- echo strpart("abcdefg", 3, 2) " returns 'de' --- echo strpart("abcdefg", -2, 4) " returns 'ab' --- echo strpart("abcdefg", 5, 4) " returns 'fg' --- echo strpart("abcdefg", 3) " returns 'defg' --- --- <Note: To get the first character, {start} must be 0. For --- example, to get the character under the cursor: >vim --- strpart(getline("."), col(".") - 1, 1, v:true) --- < --- Returns an empty string on error. --- --- @param src string --- @param start integer --- @param len? integer --- @param chars? 0|1 --- @return string function vim.fn.strpart(src, start, len, chars) end --- The result is a Number, which is a unix timestamp representing --- the date and time in {timestring}, which is expected to match --- the format specified in {format}. --- --- The accepted {format} depends on your system, thus this is not --- portable! See the manual page of the C function strptime() --- for the format. Especially avoid "%c". The value of $TZ also --- matters. --- --- If the {timestring} cannot be parsed with {format} zero is --- returned. If you do not know the format of {timestring} you --- can try different {format} values until you get a non-zero --- result. --- --- See also |strftime()|. --- Examples: >vim --- echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") --- < 862156163 >vim --- echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) --- < Sun Apr 27 11:53:55 1997 >vim --- echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) --- < Sun Apr 27 12:53:55 1997 --- --- @param format string --- @param timestring string --- @return integer function vim.fn.strptime(format, timestring) end --- The result is a Number, which gives the byte index in --- {haystack} of the last occurrence of the String {needle}. --- When {start} is specified, matches beyond this index are --- ignored. This can be used to find a match before a previous --- match: >vim --- let lastcomma = strridx(line, ",") --- let comma2 = strridx(line, ",", lastcomma - 1) --- <The search is done case-sensitive. --- For pattern searches use |match()|. --- -1 is returned if the {needle} does not occur in {haystack}. --- If the {needle} is empty the length of {haystack} is returned. --- See also |stridx()|. Examples: >vim --- echo strridx("an angry armadillo", "an") 3 --- < *strrchr()* --- When used with a single character it works similar to the C --- function strrchr(). --- --- @param haystack string --- @param needle string --- @param start? integer --- @return integer function vim.fn.strridx(haystack, needle, start) end --- The result is a String, which is {string} with all unprintable --- characters translated into printable characters |'isprint'|. --- Like they are shown in a window. Example: >vim --- echo strtrans(\@a) --- <This displays a newline in register a as "^\@" instead of --- starting a new line. --- --- Returns an empty string on error. --- --- @param string string --- @return string function vim.fn.strtrans(string) end --- The result is a Number, which is the number of UTF-16 code --- units in String {string} (after converting it to UTF-16). --- --- When {countcc} is TRUE, composing characters are counted --- separately. --- When {countcc} is omitted or FALSE, composing characters are --- ignored. --- --- Returns zero on error. --- --- Also see |strlen()| and |strcharlen()|. --- Examples: >vim --- echo strutf16len('a') " returns 1 --- echo strutf16len('Β©') " returns 1 --- echo strutf16len('π') " returns 2 --- echo strutf16len('aΜ¨Μ') " returns 1 --- echo strutf16len('aΜ¨Μ', v:true) " returns 3 --- < --- --- @param string string --- @param countcc? 0|1 --- @return integer function vim.fn.strutf16len(string, countcc) end --- The result is a Number, which is the number of display cells --- String {string} occupies. A Tab character is counted as one --- cell, alternatively use |strdisplaywidth()|. --- When {string} contains characters with East Asian Width Class --- Ambiguous, this function's return value depends on 'ambiwidth'. --- Returns zero on error. --- Also see |strlen()|, |strdisplaywidth()| and |strchars()|. --- --- @param string string --- @return integer function vim.fn.strwidth(string) end --- Only for an expression in a |:substitute| command or --- substitute() function. --- Returns the {nr}th submatch of the matched text. When {nr} --- is 0 the whole matched text is returned. --- Note that a NL in the string can stand for a line break of a --- multi-line match or a NUL character in the text. --- Also see |sub-replace-expression|. --- --- If {list} is present and non-zero then submatch() returns --- a list of strings, similar to |getline()| with two arguments. --- NL characters in the text represent NUL characters in the --- text. --- Only returns more than one item for |:substitute|, inside --- |substitute()| this list will always contain one or zero --- items, since there are no real line breaks. --- --- When substitute() is used recursively only the submatches in --- the current (deepest) call can be obtained. --- --- Returns an empty string or list on error. --- --- Examples: >vim --- s/\d\+/\=submatch(0) + 1/ --- echo substitute(text, '\d\+', '\=submatch(0) + 1', '') --- <This finds the first number in the line and adds one to it. --- A line break is included as a newline character. --- --- @param nr integer --- @param list? integer --- @return string|string[] function vim.fn.submatch(nr, list) end --- The result is a String, which is a copy of {string}, in which --- the first match of {pat} is replaced with {sub}. --- When {flags} is "g", all matches of {pat} in {string} are --- replaced. Otherwise {flags} should be "". --- --- This works like the ":substitute" command (without any flags). --- But the matching with {pat} is always done like the 'magic' --- option is set and 'cpoptions' is empty (to make scripts --- portable). 'ignorecase' is still relevant, use |/\c| or |/\C| --- if you want to ignore or match case and ignore 'ignorecase'. --- 'smartcase' is not used. See |string-match| for how {pat} is --- used. --- --- A "~" in {sub} is not replaced with the previous {sub}. --- Note that some codes in {sub} have a special meaning --- |sub-replace-special|. For example, to replace something with --- "\n" (two characters), use "\\\\n" or '\\n'. --- --- When {pat} does not match in {string}, {string} is returned --- unmodified. --- --- Example: >vim --- let &path = substitute(&path, ",\\=[^,]*$", "", "") --- <This removes the last component of the 'path' option. >vim --- echo substitute("testing", ".*", "\\U\\0", "") --- <results in "TESTING". --- --- When {sub} starts with "\=", the remainder is interpreted as --- an expression. See |sub-replace-expression|. Example: >vim --- echo substitute(s, '%\(\x\x\)', --- \ '\=nr2char("0x" .. submatch(1))', 'g') --- --- <When {sub} is a Funcref that function is called, with one --- optional argument. Example: >vim --- echo substitute(s, '%\(\x\x\)', SubNr, 'g') --- <The optional argument is a list which contains the whole --- matched string and up to nine submatches, like what --- |submatch()| returns. Example: >vim --- echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g') --- --- <Returns an empty string on error. --- --- @param string string --- @param pat string --- @param sub string --- @param flags string --- @return string function vim.fn.substitute(string, pat, sub, flags) end --- Returns a list of swap file names, like what "vim -r" shows. --- See the |-r| command argument. The 'directory' option is used --- for the directories to inspect. If you only want to get a --- list of swap files in the current directory then temporarily --- set 'directory' to a dot: >vim --- let save_dir = &directory --- let &directory = '.' --- let swapfiles = swapfilelist() --- let &directory = save_dir --- --- @return string[] function vim.fn.swapfilelist() end --- The result is a dictionary, which holds information about the --- swapfile {fname}. The available fields are: --- version Vim version --- user user name --- host host name --- fname original file name --- pid PID of the Nvim process that created the swap --- file, or zero if not running. --- mtime last modification time in seconds --- inode Optional: INODE number of the file --- dirty 1 if file was modified, 0 if not --- In case of failure an "error" item is added with the reason: --- Cannot open file: file not found or in accessible --- Cannot read file: cannot read first block --- Not a swap file: does not contain correct block ID --- Magic number mismatch: Info in first block is invalid --- --- @param fname string --- @return any function vim.fn.swapinfo(fname) end --- The result is the swap file path of the buffer {buf}. --- For the use of {buf}, see |bufname()| above. --- If buffer {buf} is the current buffer, the result is equal to --- |:swapname| (unless there is no swap file). --- If buffer {buf} has no swap file, returns an empty string. --- --- @param buf integer|string --- @return string function vim.fn.swapname(buf) end --- The result is a Number, which is the syntax ID at the position --- {lnum} and {col} in the current window. --- The syntax ID can be used with |synIDattr()| and --- |synIDtrans()| to obtain syntax information about text. --- --- {col} is 1 for the leftmost column, {lnum} is 1 for the first --- line. 'synmaxcol' applies, in a longer line zero is returned. --- Note that when the position is after the last character, --- that's where the cursor can be in Insert mode, synID() returns --- zero. {lnum} is used like with |getline()|. --- --- When {trans} is |TRUE|, transparent items are reduced to the --- item that they reveal. This is useful when wanting to know --- the effective color. When {trans} is |FALSE|, the transparent --- item is returned. This is useful when wanting to know which --- syntax item is effective (e.g. inside parens). --- Warning: This function can be very slow. Best speed is --- obtained by going through the file in forward direction. --- --- Returns zero on error. --- --- Example (echoes the name of the syntax item under the cursor): >vim --- echo synIDattr(synID(line("."), col("."), 1), "name") --- < --- --- @param lnum integer --- @param col integer --- @param trans 0|1 --- @return integer function vim.fn.synID(lnum, col, trans) end --- The result is a String, which is the {what} attribute of --- syntax ID {synID}. This can be used to obtain information --- about a syntax item. --- {mode} can be "gui" or "cterm", to get the attributes --- for that mode. When {mode} is omitted, or an invalid value is --- used, the attributes for the currently active highlighting are --- used (GUI or cterm). --- Use synIDtrans() to follow linked highlight groups. --- {what} result --- "name" the name of the syntax item --- "fg" foreground color (GUI: color name used to set --- the color, cterm: color number as a string, --- term: empty string) --- "bg" background color (as with "fg") --- "font" font name (only available in the GUI) --- |highlight-font| --- "sp" special color (as with "fg") |guisp| --- "fg#" like "fg", but for the GUI and the GUI is --- running the name in "#RRGGBB" form --- "bg#" like "fg#" for "bg" --- "sp#" like "fg#" for "sp" --- "bold" "1" if bold --- "italic" "1" if italic --- "reverse" "1" if reverse --- "inverse" "1" if inverse (= reverse) --- "standout" "1" if standout --- "underline" "1" if underlined --- "undercurl" "1" if undercurled --- "underdouble" "1" if double underlined --- "underdotted" "1" if dotted underlined --- "underdashed" "1" if dashed underlined --- "strikethrough" "1" if struckthrough --- "altfont" "1" if alternative font --- "nocombine" "1" if nocombine --- --- Returns an empty string on error. --- --- Example (echoes the color of the syntax item under the --- cursor): >vim --- echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") --- < --- Can also be used as a |method|: >vim --- echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") --- < --- --- @param synID integer --- @param what string --- @param mode? string --- @return string function vim.fn.synIDattr(synID, what, mode) end --- The result is a Number, which is the translated syntax ID of --- {synID}. This is the syntax group ID of what is being used to --- highlight the character. Highlight links given with --- ":highlight link" are followed. --- --- Returns zero on error. --- --- @param synID integer --- @return integer function vim.fn.synIDtrans(synID) end --- The result is a |List| with currently three items: --- 1. The first item in the list is 0 if the character at the --- position {lnum} and {col} is not part of a concealable --- region, 1 if it is. {lnum} is used like with |getline()|. --- 2. The second item in the list is a string. If the first item --- is 1, the second item contains the text which will be --- displayed in place of the concealed text, depending on the --- current setting of 'conceallevel' and 'listchars'. --- 3. The third and final item in the list is a number --- representing the specific syntax region matched in the --- line. When the character is not concealed the value is --- zero. This allows detection of the beginning of a new --- concealable region if there are two consecutive regions --- with the same replacement character. For an example, if --- the text is "123456" and both "23" and "45" are concealed --- and replaced by the character "X", then: --- call returns ~ --- synconcealed(lnum, 1) [0, '', 0] --- synconcealed(lnum, 2) [1, 'X', 1] --- synconcealed(lnum, 3) [1, 'X', 1] --- synconcealed(lnum, 4) [1, 'X', 2] --- synconcealed(lnum, 5) [1, 'X', 2] --- synconcealed(lnum, 6) [0, '', 0] --- --- @param lnum integer --- @param col integer --- @return {[1]: integer, [2]: string, [3]: integer}[] function vim.fn.synconcealed(lnum, col) end --- Return a |List|, which is the stack of syntax items at the --- position {lnum} and {col} in the current window. {lnum} is --- used like with |getline()|. Each item in the List is an ID --- like what |synID()| returns. --- The first item in the List is the outer region, following are --- items contained in that one. The last one is what |synID()| --- returns, unless not the whole item is highlighted or it is a --- transparent item. --- This function is useful for debugging a syntax file. --- Example that shows the syntax stack under the cursor: >vim --- for id in synstack(line("."), col(".")) --- echo synIDattr(id, "name") --- endfor --- <When the position specified with {lnum} and {col} is invalid --- an empty list is returned. The position just after the last --- character in a line and the first column in an empty line are --- valid positions. --- --- @param lnum integer --- @param col integer --- @return integer[] function vim.fn.synstack(lnum, col) end --- Note: Prefer |vim.system()| in Lua. --- --- Gets the output of {cmd} as a |string| (|systemlist()| returns --- a |List|) and sets |v:shell_error| to the error code. --- {cmd} is treated as in |jobstart()|: --- If {cmd} is a List it runs directly (no 'shell'). --- If {cmd} is a String it runs in the 'shell', like this: >vim --- call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) --- --- <Not to be used for interactive commands. --- --- Result is a String, filtered to avoid platform-specific quirks: --- - <CR><NL> is replaced with <NL> --- - NUL characters are replaced with SOH (0x01) --- --- Example: >vim --- echo system(['ls', expand('%:h')]) --- --- <If {input} is a string it is written to a pipe and passed as --- stdin to the command. The string is written as-is, line --- separators are not changed. --- If {input} is a |List| it is written to the pipe as --- |writefile()| does with {binary} set to "b" (i.e. with --- a newline between each list item, and newlines inside list --- items converted to NULs). --- When {input} is given and is a valid buffer id, the content of --- the buffer is written to the file line by line, each line --- terminated by NL (and NUL where the text has NL). --- *E5677* --- Note: system() cannot write to or read from backgrounded ("&") --- shell commands, e.g.: >vim --- echo system("cat - &", "foo") --- <which is equivalent to: > --- $ echo foo | bash -c 'cat - &' --- <The pipes are disconnected (unless overridden by shell --- redirection syntax) before input can reach it. Use --- |jobstart()| instead. --- --- Note: Use |shellescape()| or |::S| with |expand()| or --- |fnamemodify()| to escape special characters in a command --- argument. 'shellquote' and 'shellxquote' must be properly --- configured. Example: >vim --- echo system('ls '..shellescape(expand('%:h'))) --- echo system('ls '..expand('%:h:S')) --- --- <Unlike ":!cmd" there is no automatic check for changed files. --- Use |:checktime| to force a check. --- --- @param cmd string|string[] --- @param input? string|string[]|integer --- @return string function vim.fn.system(cmd, input) end --- Same as |system()|, but returns a |List| with lines (parts of --- output separated by NL) with NULs transformed into NLs. Output --- is the same as |readfile()| will output with {binary} argument --- set to "b", except that a final newline is not preserved, --- unless {keepempty} is non-zero. --- Note that on MS-Windows you may get trailing CR characters. --- --- To see the difference between "echo hello" and "echo -n hello" --- use |system()| and |split()|: >vim --- echo split(system('echo hello'), '\n', 1) --- < --- Returns an empty string on error. --- --- @param cmd string|string[] --- @param input? string|string[]|integer --- @param keepempty? integer --- @return string[] function vim.fn.systemlist(cmd, input, keepempty) end --- The result is a |List|, where each item is the number of the --- buffer associated with each window in the current tab page. --- {arg} specifies the number of the tab page to be used. When --- omitted the current tab page is used. --- When {arg} is invalid the number zero is returned. --- To get a list of all buffers in all tabs use this: >vim --- let buflist = [] --- for i in range(tabpagenr('$')) --- call extend(buflist, tabpagebuflist(i + 1)) --- endfor --- <Note that a buffer may appear in more than one window. --- --- @param arg? any --- @return any function vim.fn.tabpagebuflist(arg) end --- The result is a Number, which is the number of the current --- tab page. The first tab page has number 1. --- --- The optional argument {arg} supports the following values: --- $ the number of the last tab page (the tab page --- count). --- # the number of the last accessed tab page --- (where |g<Tab>| goes to). If there is no --- previous tab page, 0 is returned. --- The number can be used with the |:tab| command. --- --- Returns zero on error. --- --- @param arg? '$'|'#' --- @return integer function vim.fn.tabpagenr(arg) end --- Like |winnr()| but for tab page {tabarg}. --- {tabarg} specifies the number of tab page to be used. --- {arg} is used like with |winnr()|: --- - When omitted the current window number is returned. This is --- the window which will be used when going to this tab page. --- - When "$" the number of windows is returned. --- - When "#" the previous window nr is returned. --- Useful examples: >vim --- tabpagewinnr(1) " current window of tab page 1 --- tabpagewinnr(4, '$') " number of windows in tab page 4 --- <When {tabarg} is invalid zero is returned. --- --- @param tabarg integer --- @param arg? '$'|'#' --- @return integer function vim.fn.tabpagewinnr(tabarg, arg) end --- Returns a |List| with the file names used to search for tags --- for the current buffer. This is the 'tags' option expanded. --- --- @return string[] function vim.fn.tagfiles() end --- Returns a |List| of tags matching the regular expression {expr}. --- --- If {filename} is passed it is used to prioritize the results --- in the same way that |:tselect| does. See |tag-priority|. --- {filename} should be the full path of the file. --- --- Each list item is a dictionary with at least the following --- entries: --- name Name of the tag. --- filename Name of the file where the tag is --- defined. It is either relative to the --- current directory or a full path. --- cmd Ex command used to locate the tag in --- the file. --- kind Type of the tag. The value for this --- entry depends on the language specific --- kind values. Only available when --- using a tags file generated by --- Universal/Exuberant ctags or hdrtag. --- static A file specific tag. Refer to --- |static-tag| for more information. --- More entries may be present, depending on the content of the --- tags file: access, implementation, inherits and signature. --- Refer to the ctags documentation for information about these --- fields. For C code the fields "struct", "class" and "enum" --- may appear, they give the name of the entity the tag is --- contained in. --- --- The ex-command "cmd" can be either an ex search pattern, a --- line number or a line number followed by a byte number. --- --- If there are no matching tags, then an empty list is returned. --- --- To get an exact tag match, the anchors '^' and '$' should be --- used in {expr}. This also make the function work faster. --- Refer to |tag-regexp| for more information about the tag --- search regular expression pattern. --- --- Refer to |'tags'| for information about how the tags file is --- located by Vim. Refer to |tags-file-format| for the format of --- the tags file generated by the different ctags tools. --- --- @param expr any --- @param filename? string --- @return any function vim.fn.taglist(expr, filename) end --- Return the tangent of {expr}, measured in radians, as a |Float| --- in the range [-inf, inf]. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo tan(10) --- < 0.648361 >vim --- echo tan(-4.01) --- < -1.181502 --- --- @param expr number --- @return number function vim.fn.tan(expr) end --- Return the hyperbolic tangent of {expr} as a |Float| in the --- range [-1, 1]. --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo tanh(0.5) --- < 0.462117 >vim --- echo tanh(-1) --- < -0.761594 --- --- @param expr number --- @return number function vim.fn.tanh(expr) end --- Generates a (non-existent) filename located in the Nvim root --- |tempdir|. Scripts can use the filename as a temporary file. --- Example: >vim --- let tmpfile = tempname() --- exe "redir > " .. tmpfile --- < --- --- @return string function vim.fn.tempname() end --- Spawns {cmd} in a new pseudo-terminal session connected --- to the current (unmodified) buffer. Parameters and behavior --- are the same as |jobstart()| except "pty", "width", "height", --- and "TERM" are ignored: "height" and "width" are taken from --- the current window. Note that termopen() implies a "pty" arg --- to jobstart(), and thus has the implications documented at --- |jobstart()|. --- --- Returns the same values as jobstart(). --- --- Terminal environment is initialized as in |jobstart-env|, --- except $TERM is set to "xterm-256color". Full behavior is --- described in |terminal|. --- --- @param cmd any --- @param opts? table --- @return any function vim.fn.termopen(cmd, opts) end --- Return a list with information about timers. --- When {id} is given only information about this timer is --- returned. When timer {id} does not exist an empty list is --- returned. --- When {id} is omitted information about all timers is returned. --- --- For each timer the information is stored in a |Dictionary| with --- these items: --- "id" the timer ID --- "time" time the timer was started with --- "repeat" number of times the timer will still fire; --- -1 means forever --- "callback" the callback --- --- @param id? any --- @return any function vim.fn.timer_info(id) end --- Pause or unpause a timer. A paused timer does not invoke its --- callback when its time expires. Unpausing a timer may cause --- the callback to be invoked almost immediately if enough time --- has passed. --- --- Pausing a timer is useful to avoid the callback to be called --- for a short time. --- --- If {paused} evaluates to a non-zero Number or a non-empty --- String, then the timer is paused, otherwise it is unpaused. --- See |non-zero-arg|. --- --- @param timer any --- @param paused any --- @return any function vim.fn.timer_pause(timer, paused) end --- Create a timer and return the timer ID. --- --- {time} is the waiting time in milliseconds. This is the --- minimum time before invoking the callback. When the system is --- busy or Vim is not waiting for input the time will be longer. --- Zero can be used to execute the callback when Vim is back in --- the main loop. --- --- {callback} is the function to call. It can be the name of a --- function or a |Funcref|. It is called with one argument, which --- is the timer ID. The callback is only invoked when Vim is --- waiting for input. --- --- {options} is a dictionary. Supported entries: --- "repeat" Number of times to repeat the callback. --- -1 means forever. Default is 1. --- If the timer causes an error three times in a --- row the repeat is cancelled. --- --- Returns -1 on error. --- --- Example: >vim --- func MyHandler(timer) --- echo 'Handler called' --- endfunc --- let timer = timer_start(500, 'MyHandler', --- \ {'repeat': 3}) --- <This invokes MyHandler() three times at 500 msec intervals. --- --- @param time any --- @param callback any --- @param options? table --- @return any function vim.fn.timer_start(time, callback, options) end --- Stop a timer. The timer callback will no longer be invoked. --- {timer} is an ID returned by timer_start(), thus it must be a --- Number. If {timer} does not exist there is no error. --- --- @param timer any --- @return any function vim.fn.timer_stop(timer) end --- Stop all timers. The timer callbacks will no longer be --- invoked. Useful if some timers is misbehaving. If there are --- no timers there is no error. --- --- @return any function vim.fn.timer_stopall() end --- The result is a copy of the String given, with all uppercase --- characters turned into lowercase (just like applying |gu| to --- the string). Returns an empty string on error. --- --- @param expr any --- @return string function vim.fn.tolower(expr) end --- The result is a copy of the String given, with all lowercase --- characters turned into uppercase (just like applying |gU| to --- the string). Returns an empty string on error. --- --- @param expr any --- @return string function vim.fn.toupper(expr) end --- The result is a copy of the {src} string with all characters --- which appear in {fromstr} replaced by the character in that --- position in the {tostr} string. Thus the first character in --- {fromstr} is translated into the first character in {tostr} --- and so on. Exactly like the unix "tr" command. --- This code also deals with multibyte characters properly. --- --- Returns an empty string on error. --- --- Examples: >vim --- echo tr("hello there", "ht", "HT") --- <returns "Hello THere" >vim --- echo tr("<blob>", "<>", "{}") --- <returns "{blob}" --- --- @param src string --- @param fromstr string --- @param tostr string --- @return string function vim.fn.tr(src, fromstr, tostr) end --- Return {text} as a String where any character in {mask} is --- removed from the beginning and/or end of {text}. --- If {mask} is not given, {mask} is all characters up to 0x20, --- which includes Tab, space, NL and CR, plus the non-breaking --- space character 0xa0. --- The optional {dir} argument specifies where to remove the --- characters: --- 0 remove from the beginning and end of {text} --- 1 remove only at the beginning of {text} --- 2 remove only at the end of {text} --- When omitted both ends are trimmed. --- This function deals with multibyte characters properly. --- Returns an empty string on error. --- --- Examples: >vim --- echo trim(" some text ") --- <returns "some text" >vim --- echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL" --- <returns "RESERVE_TAIL" >vim --- echo trim("rm<Xrm<>X>rrm", "rm<>") --- <returns "Xrm<>X" (characters in the middle are not removed) >vim --- echo trim(" vim ", " ", 2) --- <returns " vim" --- --- @param text any --- @param mask? string --- @param dir? 0|1|2 --- @return string function vim.fn.trim(text, mask, dir) end --- Return the largest integral value with magnitude less than or --- equal to {expr} as a |Float| (truncate towards zero). --- {expr} must evaluate to a |Float| or a |Number|. --- Returns 0.0 if {expr} is not a |Float| or a |Number|. --- Examples: >vim --- echo trunc(1.456) --- < 1.0 >vim --- echo trunc(-5.456) --- < -5.0 >vim --- echo trunc(4.0) --- < 4.0 --- --- @param expr any --- @return integer function vim.fn.trunc(expr) end --- The result is a Number representing the type of {expr}. --- Instead of using the number directly, it is better to use the --- v:t_ variable that has the value: --- Number: 0 |v:t_number| --- String: 1 |v:t_string| --- Funcref: 2 |v:t_func| --- List: 3 |v:t_list| --- Dictionary: 4 |v:t_dict| --- Float: 5 |v:t_float| --- Boolean: 6 |v:t_bool| (|v:false| and |v:true|) --- Null: 7 (|v:null|) --- Blob: 10 |v:t_blob| --- For backward compatibility, this method can be used: >vim --- if type(myvar) == type(0) | endif --- if type(myvar) == type("") | endif --- if type(myvar) == type(function("tr")) | endif --- if type(myvar) == type([]) | endif --- if type(myvar) == type({}) | endif --- if type(myvar) == type(0.0) | endif --- if type(myvar) == type(v:true) | endif --- <In place of checking for |v:null| type it is better to check --- for |v:null| directly as it is the only value of this type: >vim --- if myvar is v:null | endif --- <To check if the v:t_ variables exist use this: >vim --- if exists('v:t_number') | endif --- --- @param expr any --- @return integer function vim.fn.type(expr) end --- Return the name of the undo file that would be used for a file --- with name {name} when writing. This uses the 'undodir' --- option, finding directories that exist. It does not check if --- the undo file exists. --- {name} is always expanded to the full path, since that is what --- is used internally. --- If {name} is empty undofile() returns an empty string, since a --- buffer without a file name will not write an undo file. --- Useful in combination with |:wundo| and |:rundo|. --- --- @param name string --- @return string function vim.fn.undofile(name) end --- Return the current state of the undo tree for the current --- buffer, or for a specific buffer if {buf} is given. The --- result is a dictionary with the following items: --- "seq_last" The highest undo sequence number used. --- "seq_cur" The sequence number of the current position in --- the undo tree. This differs from "seq_last" --- when some changes were undone. --- "time_cur" Time last used for |:earlier| and related --- commands. Use |strftime()| to convert to --- something readable. --- "save_last" Number of the last file write. Zero when no --- write yet. --- "save_cur" Number of the current position in the undo --- tree. --- "synced" Non-zero when the last undo block was synced. --- This happens when waiting from input from the --- user. See |undo-blocks|. --- "entries" A list of dictionaries with information about --- undo blocks. --- --- The first item in the "entries" list is the oldest undo item. --- Each List item is a |Dictionary| with these items: --- "seq" Undo sequence number. Same as what appears in --- |:undolist|. --- "time" Timestamp when the change happened. Use --- |strftime()| to convert to something readable. --- "newhead" Only appears in the item that is the last one --- that was added. This marks the last change --- and where further changes will be added. --- "curhead" Only appears in the item that is the last one --- that was undone. This marks the current --- position in the undo tree, the block that will --- be used by a redo command. When nothing was --- undone after the last change this item will --- not appear anywhere. --- "save" Only appears on the last block before a file --- write. The number is the write count. The --- first write has number 1, the last one the --- "save_last" mentioned above. --- "alt" Alternate entry. This is again a List of undo --- blocks. Each item may again have an "alt" --- item. --- --- @param buf? integer|string --- @return any function vim.fn.undotree(buf) end --- Remove second and succeeding copies of repeated adjacent --- {list} items in-place. Returns {list}. If you want a list --- to remain unmodified make a copy first: >vim --- let newlist = uniq(copy(mylist)) --- <The default compare function uses the string representation of --- each item. For the use of {func} and {dict} see |sort()|. --- --- Returns zero if {list} is not a |List|. --- --- @param list any --- @param func? any --- @param dict? any --- @return any[]|0 function vim.fn.uniq(list, func, dict) end --- Same as |charidx()| but returns the UTF-16 code unit index of --- the byte at {idx} in {string} (after converting it to UTF-16). --- --- When {charidx} is present and TRUE, {idx} is used as the --- character index in the String {string} instead of as the byte --- index. --- An {idx} in the middle of a UTF-8 sequence is rounded --- downwards to the beginning of that sequence. --- --- Returns -1 if the arguments are invalid or if there are less --- than {idx} bytes in {string}. If there are exactly {idx} bytes --- the length of the string in UTF-16 code units is returned. --- --- See |byteidx()| and |byteidxcomp()| for getting the byte index --- from the UTF-16 index and |charidx()| for getting the --- character index from the UTF-16 index. --- Refer to |string-offset-encoding| for more information. --- Examples: >vim --- echo utf16idx('aππ', 3) " returns 2 --- echo utf16idx('aππ', 7) " returns 4 --- echo utf16idx('aππ', 1, 0, 1) " returns 2 --- echo utf16idx('aππ', 2, 0, 1) " returns 4 --- echo utf16idx('aaΜ¨Μc', 6) " returns 2 --- echo utf16idx('aaΜ¨Μc', 6, 1) " returns 4 --- echo utf16idx('aππ', 9) " returns -1 --- < --- --- @param string string --- @param idx integer --- @param countcc? any --- @param charidx? any --- @return integer function vim.fn.utf16idx(string, idx, countcc, charidx) end --- Return a |List| with all the values of {dict}. The |List| is --- in arbitrary order. Also see |items()| and |keys()|. --- Returns zero if {dict} is not a |Dict|. --- --- @param dict any --- @return any function vim.fn.values(dict) end --- The result is a Number, which is the screen column of the file --- position given with {expr}. That is, the last screen position --- occupied by the character at that position, when the screen --- would be of unlimited width. When there is a <Tab> at the --- position, the returned Number will be the column at the end of --- the <Tab>. For example, for a <Tab> in column 1, with 'ts' --- set to 8, it returns 8. |conceal| is ignored. --- For the byte position use |col()|. --- --- For the use of {expr} see |col()|. --- --- When 'virtualedit' is used {expr} can be [lnum, col, off], --- where "off" is the offset in screen columns from the start of --- the character. E.g., a position within a <Tab> or after the --- last character. When "off" is omitted zero is used. When --- Virtual editing is active in the current mode, a position --- beyond the end of the line can be returned. Also see --- |'virtualedit'| --- --- The accepted positions are: --- . the cursor position --- $ the end of the cursor line (the result is the --- number of displayed characters 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. --- --- If {list} is present and non-zero then virtcol() returns a --- List with the first and last screen position occupied by the --- character. --- --- With the optional {winid} argument the values are obtained for --- that window instead of the current window. --- --- Note that only marks in the current file can be used. --- Examples: >vim --- " With text "foo^Lbar" and cursor on the "^L": --- --- echo virtcol(".") " returns 5 --- echo virtcol(".", 1) " returns [4, 5] --- echo virtcol("$") " returns 9 --- --- " With text " there", with 't at 'h': --- --- echo virtcol("'t") " returns 6 --- <The first column is 1. 0 or [0, 0] is returned for an error. --- A more advanced example that echoes the maximum length of --- all lines: >vim --- echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) --- --- @param expr any --- @param list? any --- @param winid? integer --- @return any function vim.fn.virtcol(expr, list, winid) end --- The result is a Number, which is the byte index of the --- character in window {winid} at buffer line {lnum} and virtual --- column {col}. --- --- If buffer line {lnum} is an empty line, 0 is returned. --- --- If {col} is greater than the last virtual column in line --- {lnum}, then the byte index of the character at the last --- virtual column is returned. --- --- For a multi-byte character, the column number of the first --- byte in the character is returned. --- --- The {winid} argument can be the window number or the --- |window-ID|. If this is zero, then the current window is used. --- --- Returns -1 if the window {winid} doesn't exist or the buffer --- line {lnum} or virtual column {col} is invalid. --- --- See also |screenpos()|, |virtcol()| and |col()|. --- --- @param winid integer --- @param lnum integer --- @param col integer --- @return any function vim.fn.virtcol2col(winid, lnum, col) end --- The result is a String, which describes the last Visual mode --- used in the current buffer. Initially it returns an empty --- string, but once Visual mode has been used, it returns "v", --- "V", or "<CTRL-V>" (a single CTRL-V character) for --- character-wise, line-wise, or block-wise Visual mode --- respectively. --- Example: >vim --- exe "normal " .. visualmode() --- <This enters the same Visual mode as before. It is also useful --- in scripts if you wish to act differently depending on the --- Visual mode that was used. --- If Visual mode is active, use |mode()| to get the Visual mode --- (e.g., in a |:vmap|). --- If {expr} is supplied and it evaluates to a non-zero Number or --- a non-empty String, then the Visual mode will be cleared and --- the old value is returned. See |non-zero-arg|. --- --- @param expr? any --- @return any function vim.fn.visualmode(expr) end --- Waits until {condition} evaluates to |TRUE|, where {condition} --- is a |Funcref| or |string| containing an expression. --- --- {timeout} is the maximum waiting time in milliseconds, -1 --- means forever. --- --- Condition is evaluated on user events, internal events, and --- every {interval} milliseconds (default: 200). --- --- Returns a status integer: --- 0 if the condition was satisfied before timeout --- -1 if the timeout was exceeded --- -2 if the function was interrupted (by |CTRL-C|) --- -3 if an error occurred --- --- @param timeout integer --- @param condition any --- @param interval? any --- @return any function vim.fn.wait(timeout, condition, interval) end --- Returns |TRUE| when the wildmenu is active and |FALSE| --- otherwise. See 'wildmenu' and 'wildmode'. --- This can be used in mappings to handle the 'wildcharm' option --- gracefully. (Makes only sense with |mapmode-c| mappings). --- --- For example to make <c-j> work like <down> in wildmode, use: >vim --- cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" --- < --- (Note, this needs the 'wildcharm' option set appropriately). --- --- @return any function vim.fn.wildmenumode() end --- Like `execute()` but in the context of window {id}. --- The window will temporarily be made the current window, --- without triggering autocommands or changing directory. When --- executing {command} autocommands will be triggered, this may --- have unexpected side effects. Use `:noautocmd` if needed. --- Example: >vim --- call win_execute(winid, 'syntax enable') --- <Doing the same with `setwinvar()` would not trigger --- autocommands and not actually show syntax highlighting. --- --- When window {id} does not exist then no error is given and --- an empty string is returned. --- --- @param id any --- @param command any --- @param silent? boolean --- @return any function vim.fn.win_execute(id, command, silent) end --- Returns a |List| with |window-ID|s for windows that contain --- buffer {bufnr}. When there is none the list is empty. --- --- @param bufnr any --- @return integer[] function vim.fn.win_findbuf(bufnr) end --- Get the |window-ID| for the specified window. --- When {win} is missing use the current window. --- With {win} this is the window number. The top window has --- number 1. --- Without {tab} use the current tab, otherwise the tab with --- number {tab}. The first tab has number one. --- Return zero if the window cannot be found. --- --- @param win? any --- @param tab? any --- @return integer function vim.fn.win_getid(win, tab) end --- Return the type of the window: --- "autocmd" autocommand window. Temporary window --- used to execute autocommands. --- "command" command-line window |cmdwin| --- (empty) normal window --- "loclist" |location-list-window| --- "popup" floating window |api-floatwin| --- "preview" preview window |preview-window| --- "quickfix" |quickfix-window| --- "unknown" window {nr} not found --- --- When {nr} is omitted return the type of the current window. --- When {nr} is given return the type of this window by number or --- |window-ID|. --- --- Also see the 'buftype' option. --- --- @param nr? integer --- @return 'autocmd'|'command'|''|'loclist'|'popup'|'preview'|'quickfix'|'unknown' function vim.fn.win_gettype(nr) end --- Go to window with ID {expr}. This may also change the current --- tabpage. --- Return TRUE if successful, FALSE if the window cannot be found. --- --- @param expr any --- @return 0|1 function vim.fn.win_gotoid(expr) end --- Return a list with the tab number and window number of window --- with ID {expr}: [tabnr, winnr]. --- Return [0, 0] if the window cannot be found. --- --- @param expr any --- @return any function vim.fn.win_id2tabwin(expr) end --- Return the window number of window with ID {expr}. --- Return 0 if the window cannot be found in the current tabpage. --- --- @param expr any --- @return any function vim.fn.win_id2win(expr) end --- Move window {nr}'s vertical separator (i.e., the right border) --- by {offset} columns, as if being dragged by the mouse. {nr} --- can be a window number or |window-ID|. A positive {offset} --- moves right and a negative {offset} moves left. Moving a --- window's vertical separator will change the width of the --- window and the width of other windows adjacent to the vertical --- separator. The magnitude of movement may be smaller than --- specified (e.g., as a consequence of maintaining --- 'winminwidth'). Returns TRUE if the window can be found and --- FALSE otherwise. --- This will fail for the rightmost window and a full-width --- window, since it has no separator on the right. --- Only works for the current tab page. *E1308* --- --- @param nr integer --- @param offset any --- @return any function vim.fn.win_move_separator(nr, offset) end --- Move window {nr}'s status line (i.e., the bottom border) by --- {offset} rows, as if being dragged by the mouse. {nr} can be a --- window number or |window-ID|. A positive {offset} moves down --- and a negative {offset} moves up. Moving a window's status --- line will change the height of the window and the height of --- other windows adjacent to the status line. The magnitude of --- movement may be smaller than specified (e.g., as a consequence --- of maintaining 'winminheight'). Returns TRUE if the window can --- be found and FALSE otherwise. --- Only works for the current tab page. --- --- @param nr integer --- @param offset any --- @return any function vim.fn.win_move_statusline(nr, offset) end --- Return the screen position of window {nr} as a list with two --- numbers: [row, col]. The first window always has position --- [1, 1], unless there is a tabline, then it is [2, 1]. --- {nr} can be the window number or the |window-ID|. Use zero --- for the current window. --- Returns [0, 0] if the window cannot be found in the current --- tabpage. --- --- @param nr integer --- @return any function vim.fn.win_screenpos(nr) end --- Move the window {nr} to a new split of the window {target}. --- This is similar to moving to {target}, creating a new window --- using |:split| but having the same contents as window {nr}, and --- then closing {nr}. --- --- Both {nr} and {target} can be window numbers or |window-ID|s. --- Both must be in the current tab page. --- --- Returns zero for success, non-zero for failure. --- --- {options} is a |Dictionary| with the following optional entries: --- "vertical" When TRUE, the split is created vertically, --- like with |:vsplit|. --- "rightbelow" When TRUE, the split is made below or to the --- right (if vertical). When FALSE, it is done --- above or to the left (if vertical). When not --- present, the values of 'splitbelow' and --- 'splitright' are used. --- --- @param nr integer --- @param target any --- @param options? table --- @return any function vim.fn.win_splitmove(nr, target, options) end --- The result is a Number, which is the number of the buffer --- associated with window {nr}. {nr} can be the window number or --- the |window-ID|. --- When {nr} is zero, the number of the buffer in the current --- window is returned. --- When window {nr} doesn't exist, -1 is returned. --- Example: >vim --- echo "The file in the current window is " .. bufname(winbufnr(0)) --- < --- --- @param nr integer --- @return integer function vim.fn.winbufnr(nr) end --- The result is a Number, which is the virtual column of the --- cursor in the window. This is counting screen cells from the --- left side of the window. The leftmost column is one. --- --- @return integer function vim.fn.wincol() end --- The result is a String. For MS-Windows it indicates the OS --- version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", --- Windows XP is "5.1". For non-MS-Windows systems the result is --- an empty string. --- --- @return string function vim.fn.windowsversion() end --- The result is a Number, which is the height of window {nr}. --- {nr} can be the window number or the |window-ID|. --- When {nr} is zero, the height of the current window is --- returned. When window {nr} doesn't exist, -1 is returned. --- An existing window always has a height of zero or more. --- This excludes any window toolbar line. --- Examples: >vim --- echo "The current window has " .. winheight(0) .. " lines." --- --- @param nr integer --- @return integer function vim.fn.winheight(nr) end --- The result is a nested List containing the layout of windows --- in a tabpage. --- --- Without {tabnr} use the current tabpage, otherwise the tabpage --- with number {tabnr}. If the tabpage {tabnr} is not found, --- returns an empty list. --- --- For a leaf window, it returns: > --- ["leaf", {winid}] --- < --- For horizontally split windows, which form a column, it --- returns: > --- ["col", [{nested list of windows}]] --- <For vertically split windows, which form a row, it returns: > --- ["row", [{nested list of windows}]] --- < --- Example: >vim --- " Only one window in the tab page --- echo winlayout() --- < > --- ['leaf', 1000] --- < >vim --- " Two horizontally split windows --- echo winlayout() --- < > --- ['col', [['leaf', 1000], ['leaf', 1001]]] --- < >vim --- " The second tab page, with three horizontally split --- " windows, with two vertically split windows in the --- " middle window --- echo winlayout(2) --- < > --- ['col', [['leaf', 1002], ['row', [['leaf', 1003], --- ['leaf', 1001]]], ['leaf', 1000]]] --- < --- --- @param tabnr? integer --- @return any function vim.fn.winlayout(tabnr) end --- The result is a Number, which is the screen line of the cursor --- in the window. This is counting screen lines from the top of --- the window. The first line is one. --- If the cursor was moved the view on the file will be updated --- first, this may cause a scroll. --- --- @return integer function vim.fn.winline() end --- The result is a Number, which is the number of the current --- window. The top window has number 1. --- Returns zero for a popup window. --- --- The optional argument {arg} supports the following values: --- $ the number of the last window (the window --- count). --- # the number of the last accessed window (where --- |CTRL-W_p| goes to). If there is no previous --- window or it is in another tab page 0 is --- returned. --- {N}j the number of the Nth window below the --- current window (where |CTRL-W_j| goes to). --- {N}k the number of the Nth window above the current --- window (where |CTRL-W_k| goes to). --- {N}h the number of the Nth window left of the --- current window (where |CTRL-W_h| goes to). --- {N}l the number of the Nth window right of the --- current window (where |CTRL-W_l| goes to). --- The number can be used with |CTRL-W_w| and ":wincmd w" --- |:wincmd|. --- When {arg} is invalid an error is given and zero is returned. --- Also see |tabpagewinnr()| and |win_getid()|. --- Examples: >vim --- let window_count = winnr('$') --- let prev_window = winnr('#') --- let wnum = winnr('3k') --- --- @param arg? any --- @return any function vim.fn.winnr(arg) end --- Returns a sequence of |:resize| commands that should restore --- the current window sizes. Only works properly when no windows --- are opened or closed and the current window and tab page is --- unchanged. --- Example: >vim --- let cmd = winrestcmd() --- call MessWithWindowSizes() --- exe cmd --- < --- --- @return any function vim.fn.winrestcmd() end --- Uses the |Dictionary| returned by |winsaveview()| to restore --- the view of the current window. --- Note: The {dict} does not have to contain all values, that are --- returned by |winsaveview()|. If values are missing, those --- settings won't be restored. So you can use: >vim --- call winrestview({'curswant': 4}) --- < --- This will only set the curswant value (the column the cursor --- wants to move on vertical movements) of the cursor to column 5 --- (yes, that is 5), while all other settings will remain the --- same. This is useful, if you set the cursor position manually. --- --- If you have changed the values the result is unpredictable. --- If the window size changed the result won't be the same. --- --- @param dict vim.fn.winrestview.dict --- @return any function vim.fn.winrestview(dict) end --- Returns a |Dictionary| that contains information to restore --- the view of the current window. Use |winrestview()| to --- restore the view. --- This is useful if you have a mapping that jumps around in the --- buffer and you want to go back to the original view. --- This does not save fold information. Use the 'foldenable' --- option to temporarily switch off folding, so that folds are --- not opened when moving around. This may have side effects. --- The return value includes: --- lnum cursor line number --- col cursor column (Note: the first column --- zero, as opposed to what |getcurpos()| --- returns) --- coladd cursor column offset for 'virtualedit' --- curswant column for vertical movement (Note: --- the first column is zero, as opposed --- to what |getcurpos()| returns). After --- |$| command it will be a very large --- number equal to |v:maxcol|. --- topline first line in the window --- topfill filler lines, only in diff mode --- leftcol first column displayed; only used when --- 'wrap' is off --- skipcol columns skipped --- Note that no option values are saved. --- --- @return vim.fn.winsaveview.ret function vim.fn.winsaveview() end --- The result is a Number, which is the width of window {nr}. --- {nr} can be the window number or the |window-ID|. --- When {nr} is zero, the width of the current window is --- returned. When window {nr} doesn't exist, -1 is returned. --- An existing window always has a width of zero or more. --- Examples: >vim --- echo "The current window has " .. winwidth(0) .. " columns." --- if winwidth(0) <= 50 --- 50 wincmd | --- endif --- <For getting the terminal or screen size, see the 'columns' --- option. --- --- @param nr integer --- @return any function vim.fn.winwidth(nr) end --- The result is a dictionary of byte/chars/word statistics for --- the current buffer. This is the same info as provided by --- |g_CTRL-G| --- The return value includes: --- bytes Number of bytes in the buffer --- chars Number of chars in the buffer --- words Number of words in the buffer --- cursor_bytes Number of bytes before cursor position --- (not in Visual mode) --- cursor_chars Number of chars before cursor position --- (not in Visual mode) --- cursor_words Number of words before cursor position --- (not in Visual mode) --- visual_bytes Number of bytes visually selected --- (only in Visual mode) --- visual_chars Number of chars visually selected --- (only in Visual mode) --- visual_words Number of words visually selected --- (only in Visual mode) --- --- @return any function vim.fn.wordcount() end --- When {object} is a |List| write it to file {fname}. Each list --- item is separated with a NL. Each list item must be a String --- or Number. --- All NL characters are replaced with a NUL character. --- Inserting CR characters needs to be done before passing {list} --- to writefile(). --- --- When {object} is a |Blob| write the bytes to file {fname} --- unmodified, also when binary mode is not specified. --- --- {flags} must be a String. These characters are recognized: --- --- 'b' Binary mode is used: There will not be a NL after the --- last list item. An empty item at the end does cause the --- last line in the file to end in a NL. --- --- 'a' Append mode is used, lines are appended to the file: >vim --- call writefile(["foo"], "event.log", "a") --- call writefile(["bar"], "event.log", "a") --- < --- 'D' Delete the file when the current function ends. This --- works like: >vim --- defer delete({fname}) --- < Fails when not in a function. Also see |:defer|. --- --- 's' fsync() is called after writing the file. This flushes --- the file to disk, if possible. This takes more time but --- avoids losing the file if the system crashes. --- --- 'S' fsync() is not called, even when 'fsync' is set. --- --- When {flags} does not contain "S" or "s" then fsync() is --- called if the 'fsync' option is set. --- --- An existing file is overwritten, if possible. --- --- When the write fails -1 is returned, otherwise 0. There is an --- error message if the file can't be created or when writing --- fails. --- --- Also see |readfile()|. --- To copy a file byte for byte: >vim --- let fl = readfile("foo", "b") --- call writefile(fl, "foocopy", "b") --- --- @param object any --- @param fname string --- @param flags? string --- @return any function vim.fn.writefile(object, fname, flags) end --- Bitwise XOR on the two arguments. The arguments are converted --- to a number. A List, Dict or Float argument causes an error. --- Also see `and()` and `or()`. --- Example: >vim --- let bits = xor(bits, 0x80) --- < --- --- @param expr any --- @param expr1 any --- @return any function vim.fn.xor(expr, expr1) end