diff options
Diffstat (limited to 'runtime/doc/builtin.txt')
| -rw-r--r-- | runtime/doc/builtin.txt | 266 |
1 files changed, 229 insertions, 37 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 9ac79c6..ec70220 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 9.1. Last change: 2024 Jan 05 +*builtin.txt* For Vim version 9.1. Last change: 2024 Mar 23 VIM REFERENCE MANUAL by Bram Moolenaar @@ -147,6 +147,8 @@ delete({fname} [, {flags}]) Number delete the file or directory {fname} deletebufline({buf}, {first} [, {last}]) Number delete lines from buffer {buf} did_filetype() Number |TRUE| if FileType autocmd event used +diff({fromlist}, {tolist} [, {options}]) + List diff two Lists of strings diff_filler({lnum}) Number diff filler lines about {lnum} diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} digraph_get({chars}) String get the |digraph| of {chars} @@ -198,6 +200,8 @@ foldclosedend({lnum}) Number last line of fold at {lnum} if closed foldlevel({lnum}) Number fold level at {lnum} foldtext() String line displayed for closed fold foldtextresult({lnum}) String text for closed fold at {lnum} +foreach({expr1}, {expr2}) List/Dict/Blob/String + for each item in {expr1} call {expr2} foreground() Number bring the Vim window to the foreground fullcommand({name} [, {vim9}]) String get full command from {name} funcref({name} [, {arglist}] [, {dict}]) @@ -259,6 +263,8 @@ getqflist({what}) Dict get specific quickfix list properties getreg([{regname} [, 1 [, {list}]]]) String or List contents of a register getreginfo([{regname}]) Dict information about a register +getregion({pos1}, {pos2} [, {opts}]) + List get the text from {pos1} to {pos2} getregtype([{regname}]) String type of a register getscriptinfo([{opts}]) List list of sourced scripts gettabinfo([{expr}]) List list of tab pages @@ -2044,6 +2050,72 @@ did_filetype() Returns |TRUE| when autocommands are being executed and the editing another buffer to set 'filetype' and load a syntax file. +diff({fromlist}, {tolist} [, {options}]) *diff()* + Returns a String or a List containing the diff between the + strings in {fromlist} and {tolist}. Uses the Vim internal + diff library to compute the diff. + + *E106* + The optional "output" item in {options} specifies the returned + diff format. The following values are supported: + indices Return a List of the starting and ending + indices and a count of the strings in each + diff hunk. + unified Return the unified diff output as a String. + This is the default. + + If the "output" item in {options} is "indices", then a List is + returned. Each List item contains a Dict with the following + items for each diff hunk: + from_idx start index in {fromlist} for this diff hunk. + from_count number of strings in {fromlist} that are + added/removed/modified in this diff hunk. + to_idx start index in {tolist} for this diff hunk. + to_count number of strings in {tolist} that are + added/removed/modified in this diff hunk. + + The {options} Dict argument also specifies diff options + (similar to 'diffopt') and supports the following items: + algorithm Dict specifying the diff algorithm to + use. Supported boolean items are + "myers", "minimal", "patience" and + "histogram". + context diff context length. Default is 0. + iblank ignore changes where lines are all + blank. + icase ignore changes in case of text. + indent-heuristic use the indent heuristic for the + internal diff library. + iwhite ignore changes in amount of white + space. + iwhiteall ignore all white space changes. + iwhiteeol ignore white space changes at end of + line. + For more information about these options, refer to 'diffopt'. + + To compute the unified diff, all the items in {fromlist} are + concatenated into a string using a newline separator and the + same for {tolist}. The unified diff output uses line numbers. + + Returns an empty List or String if {fromlist} and {tolist} are + identical. + + Examples: > + :echo diff(['abc'], ['xxx']) + @@ -1 +1 @@ + -abc + +xxx + + :echo diff(['abc'], ['xxx'], {'output': 'indices'}) + [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}] + :echo diff(readfile('oldfile'), readfile('newfile')) + :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$')) +< + For more examples, refer to |diff-func-examples| + + Can also be used as a |method|: > + GetFromList->diff(to_list) +< 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 @@ -2193,6 +2265,8 @@ empty({expr}) *empty()* - A |Job| is empty when it failed to start. - A |Channel| is empty when it is closed. - A |Blob| is empty when its length is zero. + - An |Object| is empty, when the |empty()| builtin method in + the object (if present) returns true. For a long |List| this is much faster than comparing the length with zero. @@ -2333,11 +2407,11 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, varname internal variable (see dict.key |internal-variables|). Also works list[i] for |curly-braces-names|, |Dictionary| - import.Func entries, |List| items, imported - items, etc. - Does not work for local variables in a - compiled `:def` function. - Also works for a function in |Vim9| + import.Func entries, |List| items, class and + class.Func object methods, imported items, etc. + object.Func Does not work for local variables in a + class.varname compiled `:def` function. + object.varname Also works for a function in |Vim9| script, since it can be used as a function reference. Beware that evaluating an index may @@ -2468,6 +2542,9 @@ expand({string} [, {nosuf} [, {list}]]) *expand()* for a non-existing file is not included, unless {string} does not start with '%', '#' or '<', see below. + For a |:terminal| window '%' expands to a '!' followed by + the command or shell that is run |terminal-bufname| + When {string} starts with '%', '#' or '<', the expansion is done like for the |cmdline-special| variables with their associated modifiers. Here is a short overview: @@ -2995,6 +3072,45 @@ foldtextresult({lnum}) *foldtextresult()* Can also be used as a |method|: > GetLnum()->foldtextresult() + +foreach({expr1}, {expr2}) *foreach()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + For each item in {expr1} execute {expr2}. {expr1} is not + modified; its values may be, as with |:lockvar| 1. |E741| + See |map()| and |filter()| to modify {expr1}. + + {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: > + call foreach(mylist, 'used[v:val] = true') +< This records the items that are in the {expr1} list. + + Note that {expr2} is the result of expression and is then used + as a command. 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. + With a legacy script lambda you don't get an error if it only + accepts one argument, but with a Vim9 lambda you get "E1106: + One argument too many", the number of arguments must match. + If the function returns a value, it is ignored. + + Returns {expr1} in all cases. + When an error is encountered while executing {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. + + Can also be used as a |method|: > + mylist->foreach(expr2) < *foreground()* foreground() Move the Vim window to the foreground. Useful when sent from @@ -3203,6 +3319,8 @@ getbufinfo([{dict}]) bufnr Buffer number. changed TRUE if the buffer is modified. changedtick Number of changes made to the buffer. + command TRUE if the buffer belongs to the + command-line window |cmdwin|. hidden TRUE if the buffer is hidden. lastused Timestamp in seconds, like |localtime()|, when the buffer was @@ -3427,7 +3545,7 @@ getcharmod() *getcharmod()* 32 mouse double click 64 mouse triple click 96 mouse quadruple click (== 32 + 64) - 128 command (Macintosh only) + 128 command (Mac) or super (GTK) 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. @@ -4155,6 +4273,59 @@ getreginfo([{regname}]) *getreginfo()* Can also be used as a |method|: > GetRegname()->getreginfo() +getregion({pos1}, {pos2} [, {opts}]) *getregion()* + Returns the list of strings from {pos1} to {pos2} from a + buffer. + + {pos1} and {pos2} must both be |List|s with four numbers. + See |getpos()| for the format of the list. It's possible + to specify positions from a different buffer, but please + note the limitations at |getregion-notes|. + + The optional argument {opts} is a Dict and supports the + following items: + + type Specify the region's selection type + (default: "v"): + "v" for |characterwise| mode + "V" for |linewise| mode + "<CTRL-V>" for |blockwise-visual| mode + + exclusive If |TRUE|, use exclusive selection + for the end position + (default: follow 'selection') + + You can get the last selection type by |visualmode()|. + If Visual mode is active, use |mode()| to get the Visual mode + (e.g., in a |:vmap|). + This function is useful to get text starting and ending in + different columns, such as a |characterwise-visual| selection. + + *getregion-notes* + Note that: + - Order of {pos1} and {pos2} doesn't matter, it will always + return content from the upper left position to the lower + right position. + - If 'virtualedit' is enabled and the region is past the end + of the lines, resulting lines are padded with spaces. + - If the region is blockwise and it starts or ends in the + middle of a multi-cell character, it is not included but + its selected part is substituted with spaces. + - If {pos1} and {pos2} are not in the same buffer, an empty + list is returned. + - {pos1} and {pos2} must belong to a |bufloaded()| buffer. + - It is evaluated in current window context, which makes a + difference if the buffer is displayed in a window with + different 'virtualedit' or 'list' values. + + Examples: > + :xnoremap <CR> + \ <Cmd>echow getregion( + \ getpos('v'), getpos('.'), #{ type: mode() })<CR> +< + Can also be used as a |method|: > + getpos('.')->getregion(getpos("'a")) +< getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. The value will be one of: @@ -4381,14 +4552,16 @@ getwinpos([{timeout}]) *getwinpos()* getwinposx() The result is a Number, which is the X coordinate in pixels of the left hand side of the GUI Vim window. Also works for an xterm (uses a timeout of 100 msec). - The result will be -1 if the information is not available. + The result will be -1 if the information is not available + (e.g. on the Wayland backend). The value can be used with `:winpos`. *getwinposy()* getwinposy() The result is a Number, which is the Y coordinate in pixels of the top of the GUI Vim window. Also works for an xterm (uses a timeout of 100 msec). - The result will be -1 if the information is not available. + The result will be -1 if the information is not available + (e.g. on the Wayland backend). The value can be used with `:winpos`. getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* @@ -5312,7 +5485,9 @@ len({expr}) The result is a Number, which is the length of the argument. 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. + When {expr} is an |Object|, invokes the |len()| method in the + object (if present) to get the length. Otherwise returns + zero. Can also be used as a |method|: > mylist->len() @@ -5933,6 +6108,7 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* Note that when {count} is added the way {start} works changes, see above. + *match-pattern* 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 @@ -6073,31 +6249,34 @@ matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) For each match, a |Dict| with the following items is returned: byteidx starting byte index of the match - lnum line number where there is a match - text matched string + lnum line number where there is a match + text matched string Note that there can be multiple matches in a single line. This function works only for loaded buffers. First call |bufload()| if needed. + See |match-pattern| for information about the effect of some + option settings on the pattern. + When {buf} is not a valid buffer, the buffer is not loaded or {lnum} or {end} is not valid then an error is given and an empty |List| is returned. Examples: > - " Assuming line 3 in buffer 5 contains "a" - :echo matchbufline(5, '\<\k\+\>', 3, 3) - [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] - " Assuming line 4 in buffer 10 contains "tik tok" - :echo matchbufline(10, '\<\k\+\>', 1, 4) - [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] + " Assuming line 3 in buffer 5 contains "a" + :echo matchbufline(5, '\<\k\+\>', 3, 3) + [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] + " Assuming line 4 in buffer 10 contains "tik tok" + :echo matchbufline(10, '\<\k\+\>', 1, 4) + [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] < If {submatch} is present and is v:true, then submatches like - "\1", "\2", etc. are also returned. Example: > - " Assuming line 2 in buffer 2 contains "acd" - :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 + "\1", "\2", etc. are also returned. Example: > + " Assuming line 2 in buffer 2 contains "acd" + :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 \ {'submatches': v:true}) - [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] + [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] < The "submatches" List always contains 9 items. If a submatch is not found, then an empty string is returned for that submatch. @@ -6254,11 +6433,14 @@ matchstrlist({list}, {pat} [, {dict}]) submatches a List of submatches. Present only if "submatches" is set to v:true in {dict}. + See |match-pattern| for information about the effect of some + option settings on the pattern. + Example: > - :echo matchstrlist(['tik tok'], '\<\k\+\>') - [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] - :echo matchstrlist(['a', 'b'], '\<\k\+\>') - [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] + :echo matchstrlist(['tik tok'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] + :echo matchstrlist(['a', 'b'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] < If "submatches" is present and is v:true, then submatches like "\1", "\2", etc. are also returned. Example: > @@ -6923,6 +7105,9 @@ printf({fmt}, {expr1} ...) *printf()* echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) < 1.41 + You will get an overflow error |E1510|, when the field-width + or precision will result in a string longer than 6400 chars. + *E1500* You cannot mix positional and non-positional arguments: > echo printf("%s%1$s", "One", "Two") @@ -7798,6 +7983,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) 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. + To get the matched string, use |matchbufline()|. {flags} is a String, which can contain these character flags: 'b' search Backward instead of forward @@ -8882,7 +9068,8 @@ slice({expr}, {start} [, {end}]) *slice()* 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, like in - |vim9script|. Also, composing characters are not counted. + |vim9script|. Also, composing characters are treated as a + part of the preceding base character. 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. @@ -9279,8 +9466,8 @@ strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* 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 {skipcc} set to 1, composing characters are treated as a + part of the preceding base character, 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: > @@ -9298,7 +9485,7 @@ strchars({string} [, {skipcc}]) *strchars()* in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. - When {skipcc} set to 1, Composing characters are ignored. + When {skipcc} set to 1, composing characters are ignored. |strcharlen()| always does this. Returns zero on error. @@ -9416,6 +9603,10 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, replaced by "[...]" or "{...}". Using eval() on the result will then fail. + For an object, invokes the |string()| method to get a textual + representation of the object. If the method is not present, + then the default representation is used. + Can also be used as a |method|: > mylist->string() @@ -10642,17 +10833,16 @@ win_screenpos({nr}) *win_screenpos()* [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. + Returns [0, 0] if the window cannot be found. Can also be used as a |method|: > GetWinid()->win_screenpos() < win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* - 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}. + Temporarily switch to window {target}, then move window {nr} + to a new split adjacent to {target}. + Unlike commands such as |:split|, no new windows are created + (the |window-ID| of window {nr} is unchanged after the move). Both {nr} and {target} can be window numbers or |window-ID|s. Both must be in the current tab page. @@ -10761,7 +10951,9 @@ winnr([{arg}]) The result is a Number, which is the number of the current # 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. + returned. May refer to the current window in + some cases (e.g. when evaluating 'statusline' + expressions). {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 |