*builtin.txt* Nvim NVIM REFERENCE MANUAL Builtin functions *vimscript-functions* *builtin-functions* For functions grouped by what they are used for see |function-list|. Type |gO| to see the table of contents. ============================================================================== 1. Details *builtin-function-details* abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to a |Float| abs() returns a |Float|. When {expr} can be converted to a |Number| abs() returns a |Number|. Otherwise 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 acos({expr}) *acos()* Return the arc cosine of {expr} measured in radians, as a |Float| in the range of [0, pi]. {expr} must evaluate to a |Float| or a |Number| in the range [-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 add({object}, {expr}) *add()* 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|. and({expr}, {expr}) *and()* 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) < api_info() *api_info()* Returns Dictionary of |api-metadata|. View it in a nice human-readable format: >vim lua vim.print(vim.fn.api_info()) < append({lnum}, {text}) *append()* 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"]) < appendbufline({buf}, {lnum}, {text}) *appendbufline()* 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. argc([{winid}]) *argc()* The result is the number of files in the argument list. See |arglist|. If {winid} is not supplied, the argument list of the current window is used. If {winid} is -1, the global argument list is used. Otherwise {winid} specifies the window of which the argument list is used: either the window number or the window ID. Returns -1 if the {winid} argument is invalid. argidx() *argidx()* The result is the current index in the argument list. 0 is the first file. argc() - 1 is the last one. See |arglist|. arglistid([{winnr} [, {tabnr}]]) *arglistid()* Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. Returns -1 if the arguments are invalid. Without arguments use the current window. With {winnr} only use this window in the current tab page. With {winnr} and {tabnr} use the window in the specified tab page. {winnr} can be the window number or the |window-ID|. argv([{nr} [, {winid}]]) *argv()* 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 .. '' 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. asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| in the range of [-pi/2, pi/2]. {expr} must evaluate to a |Float| or a |Number| in the range [-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 assert_beeps({cmd}) *assert_beeps()* 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|. assert_equal({expected}, {actual} [, {msg}]) *assert_equal()* When {expected} and {actual} are not equal an error message is added to |v:errors| and 1 is returned. Otherwise zero is returned. |assert-return| 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' ~ assert_equalfile({fname-one}, {fname-two}) *assert_equalfile()* 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. assert_exception({error} [, {msg}]) *assert_exception()* 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 < *assert_fails()* assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) 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. assert_false({actual} [, {msg}]) *assert_false()* 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. assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* This asserts number and |Float| values. When {actual} is lower than {lower} or higher than {upper} an error message is added to |v:errors|. Also see |assert-return|. The error is in the form "Expected range {lower} - {upper}, but got {actual}". When {msg} is present it is prefixed to that. assert_match({pattern}, {actual} [, {msg}]) *assert_match()* 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' ~ assert_nobeep({cmd}) *assert_nobeep()* Run {cmd} and add an error message to |v:errors| if it produces a beep or visual bell. Also see |assert_beeps()|. assert_notequal({expected}, {actual} [, {msg}]) *assert_notequal()* The opposite of `assert_equal()`: add an error message to |v:errors| when {expected} and {actual} are equal. Also see |assert-return|. assert_notmatch({pattern}, {actual} [, {msg}]) *assert_notmatch()* The opposite of `assert_match()`: add an error message to |v:errors| when {pattern} matches {actual}. Also see |assert-return|. assert_report({msg}) *assert_report()* Report a test failure directly, using String {msg}. Always returns one. assert_true({actual} [, {msg}]) *assert_true()* 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. atan({expr}) *atan()* Return the principal value of the arc tangent of {expr}, in the range [-pi/2, +pi/2] radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. 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 atan2({expr1}, {expr2}) *atan2()* Return the arc tangent of {expr1} / {expr2}, measured in radians, as a |Float| in the range [-pi, pi]. {expr1} and {expr2} must evaluate to a |Float| or a |Number|. 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 blob2list({blob}) *blob2list()* 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. browse({save}, {title}, {initdir}, {default}) *browse()* Put up a file requester. This only works when "has("browse")" returns |TRUE| (only in some GUI versions). The input fields are: {save} when |TRUE|, select file to write {title} title for the requester {initdir} directory to start browsing in {default} default file name An empty string is returned when the "Cancel" button is hit, something went wrong, or browsing is not possible. browsedir({title}, {initdir}) *browsedir()* 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. bufadd({name}) *bufadd()* 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. bufexists({buf}) *bufexists()* 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. buflisted({buf}) *buflisted()* 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()|. bufload({buf}) *bufload()* 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()|. bufloaded({buf}) *bufloaded()* 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()|. bufname([{buf}]) *bufname()* 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. < bufnr([{buf} [, {create}]]) *bufnr()* 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. bufwinid({buf}) *bufwinid()* 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. bufwinnr({buf}) *bufwinnr()* 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|. byte2line({byte}) *byte2line()* 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. byteidx({expr}, {nr} [, {utf16}]) *byteidx()* 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 < byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* 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). call({func}, {arglist} [, {dict}]) *call()* *E699* 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| ceil({expr}) *ceil()* Return the smallest integral value greater than or equal to {expr} as a |Float| (round up). {expr} must evaluate to a |Float| or a |Number|. 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|. chanclose({id} [, {stream}]) *chanclose()* 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. changenr() *changenr()* 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. chansend({id}, {data}) *chansend()* 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 "abc123456". 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. char2nr({string} [, {utf8}]) *char2nr()* 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("\") " 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|. charclass({string}) *charclass()* 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|. charcol({expr} [, {winid}]) *charcol()* 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 charidx({string}, {idx} [, {countcc} [, {utf16}]]) *charidx()* 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('áb́ć', 3) " returns 1 echo charidx('áb́ć', 6, 1) " returns 4 echo charidx('áb́ć', 16) " returns -1 echo charidx('a😊😊', 4, 0, 1) " returns 2 < chdir({dir}) *chdir()* 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 cindent({lnum}) *cindent()* 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|. clearmatches([{win}]) *clearmatches()* 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. col({expr} [, {winid}]) *col()* 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 mapping the cursor isn't moved, this can be used to obtain the column in Insert mode: >vim imap echo col(".").."\n" complete({startcol}, {matches}) *complete()* *E785* 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 =ListMonths() 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. complete_add({expr}) *complete_add()* 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. complete_check() *complete_check()* 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. complete_info([{what}]) *complete_info()* Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: mode Current completion mode name string. See |complete_info_mode| for the values. pum_visible |TRUE| if popup menu is visible. See |pumvisible()|. items List of completion matches. Each item is a dictionary containing the entries "word", "abbr", "menu", "kind", "info" and "user_data". See |complete-items|. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing typed text only, or the last completion after no item is selected when using the or keys) inserted Inserted string. [NOT IMPLEMENTED YET] preview_winid Info floating preview window id. preview_bufnr Info floating preview buffer id. *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']) confirm({msg} [, {choices} [, {default} [, {type}]]]) *confirm()* 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 , 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. copy({expr}) *copy()* Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a shallow copy is created. This means 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()|. cos({expr}) *cos()* Return the cosine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. Examples: >vim echo cos(100) < 0.862319 >vim echo cos(-4.01) < -0.646043 cosh({expr}) *cosh()* 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 count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* 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. ctxget([{index}]) *ctxget()* 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). ctxpop() *ctxpop()* Pops and restores the |context| at the top of the |context-stack|. ctxpush([{types}]) *ctxpush()* 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. ctxset({context} [, {index}]) *ctxset()* 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). ctxsize() *ctxsize()* Returns the size of the |context-stack|. cursor({lnum}, {col} [, {off}]) cursor({list}) *cursor()* Positions the cursor at the column (byte count) {col} in the line {lnum}. The first column is one. When there is one argument {list} this is used as a |List| with two, three or four item: [{lnum}, {col}] [{lnum}, {col}, {off}] [{lnum}, {col}, {off}, {curswant}] This is like the return value of |getpos()| or |getcurpos()|, but without the first item. To position the cursor using {col} as the character count, use |setcursorcharpos()|. Does not change the jumplist. {lnum} is used like with |getline()|, except that if {lnum} is zero, the cursor will stay in the current line. If {lnum} is greater than the number of lines in the buffer, the cursor will be positioned at the last line in the buffer. If {col} is greater than the number of bytes in the line, the cursor will be positioned at the last character in the line. If {col} is zero, the cursor will stay in the current column. If {curswant} is given it is used to set the preferred column for vertical movement. Otherwise {col} is used. When 'virtualedit' is used {off} specifies the offset in screen columns from the start of the character. E.g., a position within a or after the last character. Returns 0 when the position could be set, -1 otherwise. debugbreak({pid}) *debugbreak()* 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|. deepcopy({expr} [, {noref}]) *deepcopy()* *E698* 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()|. delete({fname} [, {flags}]) *delete()* 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. deletebufline({buf}, {first} [, {last}]) *deletebufline()* 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}. dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* 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. dictwatcherdel({dict}, {pattern}, {callback}) *dictwatcherdel()* Removes a watcher added with |dictwatcheradd()|. All three arguments must match the ones passed to |dictwatcheradd()| in order for the watcher to be successfully deleted. did_filetype() *did_filetype()* 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. diff_filler({lnum}) *diff_filler()* 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. diff_hlID({lnum}, {col}) *diff_hlID()* 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. digraph_get({chars}) *digraph_get()* *E1214* 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 'あ' < digraph_getlist([{listall}]) *digraph_getlist()* 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) < digraph_set({chars}, {digraph}) *digraph_set()* 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('あ') < digraph_setlist({digraphlist}) *digraph_setlist()* 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() < empty({expr}) *empty()* 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. environ() *environ()* 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 < escape({string}, {chars}) *escape()* 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()|. eval({string}) *eval()* 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. eventhandler() *eventhandler()* 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. executable({expr}) *executable()* 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. execute({command} [, {silent}]) *execute()* 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()`. exepath({expr}) *exepath()* 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. exists({expr}) *exists()* 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("*v:lua.Func") 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. exp({expr}) *exp()* 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 expand({string} [, {nosuf} [, {list}]]) *expand()* Expand wildcards and the following special keywords in {string}. 'wildignorecase' applies. If {list} is given and it is |TRUE|, a List will be returned. Otherwise the result is a String and when there are several matches, they are separated by characters. If the expansion fails, the result is an empty string. A name for a non-existing file is not included, unless {string} does not start with '%', '#' or '<', see below. When {string} starts with '%', '#' or '<', the expansion is done like for the |cmdline-special| variables with their associated modifiers. Here is a short overview: % current file name # alternate file name #n alternate file name n file name under the cursor autocmd file name autocmd buffer number (as a String!) autocmd matched name C expression under the cursor sourced script file or function name sourced script line number or function line number script file line number, also when in a function "123_" where "123" is the current script ID ||