Mercurial > vim
comparison runtime/doc/builtin.txt @ 26777:629e7046ef63 v8.2.3917
patch 8.2.3917: the eval.txt help file is way too big
Commit: https://github.com/vim/vim/commit/1cae5a0a034d0545360387407a7a409310f1efe2
Author: Bram Moolenaar <Bram@vim.org>
Date: Mon Dec 27 21:28:34 2021 +0000
patch 8.2.3917: the eval.txt help file is way too big
Problem: The eval.txt help file is way too big.
Solution: Move the builtin function details to a separate file.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Mon, 27 Dec 2021 22:30:02 +0100 |
parents | |
children | b7b82279426f |
comparison
equal
deleted
inserted
replaced
26776:7560ecdb2a6e | 26777:629e7046ef63 |
---|---|
1 *builtin.txt* For Vim version 8.2. Last change: 2021 Dec 27 | |
2 | |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 Builtin functions *builtin-functions* | |
8 | |
9 Note: Expression evaluation can be disabled at compile time. If this has been | |
10 done, the builtin functions are not available. See |+eval| and | |
11 |no-eval-feature|. | |
12 | |
13 1. Overview |builtin-function-list| | |
14 2. Details |builtin-function-details| | |
15 3. Feature list |feature-list| | |
16 4. Matching a pattern in a String |string-match| | |
17 | |
18 ============================================================================== | |
19 1. Overview *builtin-function-list* | |
20 | |
21 Use CTRL-] on the function name to jump to the full explanation. | |
22 | |
23 USAGE RESULT DESCRIPTION ~ | |
24 | |
25 abs({expr}) Float or Number absolute value of {expr} | |
26 acos({expr}) Float arc cosine of {expr} | |
27 add({object}, {item}) List/Blob append {item} to {object} | |
28 and({expr}, {expr}) Number bitwise AND | |
29 append({lnum}, {text}) Number append {text} below line {lnum} | |
30 appendbufline({expr}, {lnum}, {text}) | |
31 Number append {text} below line {lnum} | |
32 in buffer {expr} | |
33 argc([{winid}]) Number number of files in the argument list | |
34 argidx() Number current index in the argument list | |
35 arglistid([{winnr} [, {tabnr}]]) Number argument list id | |
36 argv({nr} [, {winid}]) String {nr} entry of the argument list | |
37 argv([-1, {winid}]) List the argument list | |
38 asin({expr}) Float arc sine of {expr} | |
39 assert_beeps({cmd}) Number assert {cmd} causes a beep | |
40 assert_equal({exp}, {act} [, {msg}]) | |
41 Number assert {exp} is equal to {act} | |
42 assert_equalfile({fname-one}, {fname-two} [, {msg}]) | |
43 Number assert file contents are equal | |
44 assert_exception({error} [, {msg}]) | |
45 Number assert {error} is in v:exception | |
46 assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) | |
47 Number assert {cmd} fails | |
48 assert_false({actual} [, {msg}]) | |
49 Number assert {actual} is false | |
50 assert_inrange({lower}, {upper}, {actual} [, {msg}]) | |
51 Number assert {actual} is inside the range | |
52 assert_match({pat}, {text} [, {msg}]) | |
53 Number assert {pat} matches {text} | |
54 assert_nobeep({cmd}) Number assert {cmd} does not cause a beep | |
55 assert_notequal({exp}, {act} [, {msg}]) | |
56 Number assert {exp} is not equal {act} | |
57 assert_notmatch({pat}, {text} [, {msg}]) | |
58 Number assert {pat} not matches {text} | |
59 assert_report({msg}) Number report a test failure | |
60 assert_true({actual} [, {msg}]) Number assert {actual} is true | |
61 atan({expr}) Float arc tangent of {expr} | |
62 atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} | |
63 balloon_gettext() String current text in the balloon | |
64 balloon_show({expr}) none show {expr} inside the balloon | |
65 balloon_split({msg}) List split {msg} as used for a balloon | |
66 blob2list({blob}) List convert {blob} into a list of numbers | |
67 browse({save}, {title}, {initdir}, {default}) | |
68 String put up a file requester | |
69 browsedir({title}, {initdir}) String put up a directory requester | |
70 bufadd({name}) Number add a buffer to the buffer list | |
71 bufexists({buf}) Number |TRUE| if buffer {buf} exists | |
72 buflisted({buf}) Number |TRUE| if buffer {buf} is listed | |
73 bufload({buf}) Number load buffer {buf} if not loaded yet | |
74 bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded | |
75 bufname([{buf}]) String Name of the buffer {buf} | |
76 bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} | |
77 bufwinid({buf}) Number window ID of buffer {buf} | |
78 bufwinnr({buf}) Number window number of buffer {buf} | |
79 byte2line({byte}) Number line number at byte count {byte} | |
80 byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr} | |
81 byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr} | |
82 call({func}, {arglist} [, {dict}]) | |
83 any call {func} with arguments {arglist} | |
84 ceil({expr}) Float round {expr} up | |
85 ch_canread({handle}) Number check if there is something to read | |
86 ch_close({handle}) none close {handle} | |
87 ch_close_in({handle}) none close in part of {handle} | |
88 ch_evalexpr({handle}, {expr} [, {options}]) | |
89 any evaluate {expr} on JSON {handle} | |
90 ch_evalraw({handle}, {string} [, {options}]) | |
91 any evaluate {string} on raw {handle} | |
92 ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what} | |
93 ch_getjob({channel}) Job get the Job of {channel} | |
94 ch_info({handle}) String info about channel {handle} | |
95 ch_log({msg} [, {handle}]) none write {msg} in the channel log file | |
96 ch_logfile({fname} [, {mode}]) none start logging channel activity | |
97 ch_open({address} [, {options}]) | |
98 Channel open a channel to {address} | |
99 ch_read({handle} [, {options}]) String read from {handle} | |
100 ch_readblob({handle} [, {options}]) | |
101 Blob read Blob from {handle} | |
102 ch_readraw({handle} [, {options}]) | |
103 String read raw from {handle} | |
104 ch_sendexpr({handle}, {expr} [, {options}]) | |
105 any send {expr} over JSON {handle} | |
106 ch_sendraw({handle}, {expr} [, {options}]) | |
107 any send {expr} over raw {handle} | |
108 ch_setoptions({handle}, {options}) | |
109 none set options for {handle} | |
110 ch_status({handle} [, {options}]) | |
111 String status of channel {handle} | |
112 changenr() Number current change number | |
113 char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} | |
114 charclass({string}) Number character class of {string} | |
115 charcol({expr}) Number column number of cursor or mark | |
116 charidx({string}, {idx} [, {countcc}]) | |
117 Number char index of byte {idx} in {string} | |
118 chdir({dir}) String change current working directory | |
119 cindent({lnum}) Number C indent for line {lnum} | |
120 clearmatches([{win}]) none clear all matches | |
121 col({expr}) Number column byte index of cursor or mark | |
122 complete({startcol}, {matches}) none set Insert mode completion | |
123 complete_add({expr}) Number add completion match | |
124 complete_check() Number check for key typed during completion | |
125 complete_info([{what}]) Dict get current completion information | |
126 confirm({msg} [, {choices} [, {default} [, {type}]]]) | |
127 Number number of choice picked by user | |
128 copy({expr}) any make a shallow copy of {expr} | |
129 cos({expr}) Float cosine of {expr} | |
130 cosh({expr}) Float hyperbolic cosine of {expr} | |
131 count({comp}, {expr} [, {ic} [, {start}]]) | |
132 Number count how many {expr} are in {comp} | |
133 cscope_connection([{num}, {dbpath} [, {prepend}]]) | |
134 Number checks existence of cscope connection | |
135 cursor({lnum}, {col} [, {off}]) | |
136 Number move cursor to {lnum}, {col}, {off} | |
137 cursor({list}) Number move cursor to position in {list} | |
138 debugbreak({pid}) Number interrupt process being debugged | |
139 deepcopy({expr} [, {noref}]) any make a full copy of {expr} | |
140 delete({fname} [, {flags}]) Number delete the file or directory {fname} | |
141 deletebufline({buf}, {first} [, {last}]) | |
142 Number delete lines from buffer {buf} | |
143 did_filetype() Number |TRUE| if FileType autocmd event used | |
144 diff_filler({lnum}) Number diff filler lines about {lnum} | |
145 diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} | |
146 digraph_get({chars}) String get the |digraph| of {chars} | |
147 digraph_getlist([{listall}]) List get all |digraph|s | |
148 digraph_set({chars}, {digraph}) Boolean register |digraph| | |
149 digraph_setlist({digraphlist}) Boolean register multiple |digraph|s | |
150 echoraw({expr}) none output {expr} as-is | |
151 empty({expr}) Number |TRUE| if {expr} is empty | |
152 environ() Dict return environment variables | |
153 escape({string}, {chars}) String escape {chars} in {string} with '\' | |
154 eval({string}) any evaluate {string} into its value | |
155 eventhandler() Number |TRUE| if inside an event handler | |
156 executable({expr}) Number 1 if executable {expr} exists | |
157 execute({command}) String execute {command} and get the output | |
158 exepath({expr}) String full path of the command {expr} | |
159 exists({expr}) Number |TRUE| if {expr} exists | |
160 exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time | |
161 exp({expr}) Float exponential of {expr} | |
162 expand({expr} [, {nosuf} [, {list}]]) | |
163 any expand special keywords in {expr} | |
164 expandcmd({expr}) String expand {expr} like with `:edit` | |
165 extend({expr1}, {expr2} [, {expr3}]) | |
166 List/Dict insert items of {expr2} into {expr1} | |
167 extendnew({expr1}, {expr2} [, {expr3}]) | |
168 List/Dict like |extend()| but creates a new | |
169 List or Dictionary | |
170 feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer | |
171 filereadable({file}) Number |TRUE| if {file} is a readable file | |
172 filewritable({file}) Number |TRUE| if {file} is a writable file | |
173 filter({expr1}, {expr2}) List/Dict/Blob/String | |
174 remove items from {expr1} where | |
175 {expr2} is 0 | |
176 finddir({name} [, {path} [, {count}]]) | |
177 String find directory {name} in {path} | |
178 findfile({name} [, {path} [, {count}]]) | |
179 String find file {name} in {path} | |
180 flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels | |
181 flattennew({list} [, {maxdepth}]) | |
182 List flatten a copy of {list} | |
183 float2nr({expr}) Number convert Float {expr} to a Number | |
184 floor({expr}) Float round {expr} down | |
185 fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} | |
186 fnameescape({fname}) String escape special characters in {fname} | |
187 fnamemodify({fname}, {mods}) String modify file name | |
188 foldclosed({lnum}) Number first line of fold at {lnum} if closed | |
189 foldclosedend({lnum}) Number last line of fold at {lnum} if closed | |
190 foldlevel({lnum}) Number fold level at {lnum} | |
191 foldtext() String line displayed for closed fold | |
192 foldtextresult({lnum}) String text for closed fold at {lnum} | |
193 foreground() Number bring the Vim window to the foreground | |
194 fullcommand({name}) String get full command from {name} | |
195 funcref({name} [, {arglist}] [, {dict}]) | |
196 Funcref reference to function {name} | |
197 function({name} [, {arglist}] [, {dict}]) | |
198 Funcref named reference to function {name} | |
199 garbagecollect([{atexit}]) none free memory, breaking cyclic references | |
200 get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} | |
201 get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} | |
202 get({func}, {what}) any get property of funcref/partial {func} | |
203 getbufinfo([{buf}]) List information about buffers | |
204 getbufline({buf}, {lnum} [, {end}]) | |
205 List lines {lnum} to {end} of buffer {buf} | |
206 getbufvar({buf}, {varname} [, {def}]) | |
207 any variable {varname} in buffer {buf} | |
208 getchangelist([{buf}]) List list of change list items | |
209 getchar([expr]) Number or String | |
210 get one character from the user | |
211 getcharmod() Number modifiers for the last typed character | |
212 getcharpos({expr}) List position of cursor, mark, etc. | |
213 getcharsearch() Dict last character search | |
214 getcharstr([expr]) String get one character from the user | |
215 getcmdline() String return the current command-line | |
216 getcmdpos() Number return cursor position in command-line | |
217 getcmdtype() String return current command-line type | |
218 getcmdwintype() String return current command-line window type | |
219 getcompletion({pat}, {type} [, {filtered}]) | |
220 List list of cmdline completion matches | |
221 getcurpos([{winnr}]) List position of the cursor | |
222 getcursorcharpos([{winnr}]) List character position of the cursor | |
223 getcwd([{winnr} [, {tabnr}]]) String get the current working directory | |
224 getenv({name}) String return environment variable | |
225 getfontname([{name}]) String name of font being used | |
226 getfperm({fname}) String file permissions of file {fname} | |
227 getfsize({fname}) Number size in bytes of file {fname} | |
228 getftime({fname}) Number last modification time of file | |
229 getftype({fname}) String description of type of file {fname} | |
230 getimstatus() Number |TRUE| if the IME status is active | |
231 getjumplist([{winnr} [, {tabnr}]]) | |
232 List list of jump list items | |
233 getline({lnum}) String line {lnum} of current buffer | |
234 getline({lnum}, {end}) List lines {lnum} to {end} of current buffer | |
235 getloclist({nr}) List list of location list items | |
236 getloclist({nr}, {what}) Dict get specific location list properties | |
237 getmarklist([{buf}]) List list of global/local marks | |
238 getmatches([{win}]) List list of current matches | |
239 getmousepos() Dict last known mouse position | |
240 getpid() Number process ID of Vim | |
241 getpos({expr}) List position of cursor, mark, etc. | |
242 getqflist() List list of quickfix items | |
243 getqflist({what}) Dict get specific quickfix list properties | |
244 getreg([{regname} [, 1 [, {list}]]]) | |
245 String or List contents of a register | |
246 getreginfo([{regname}]) Dict information about a register | |
247 getregtype([{regname}]) String type of a register | |
248 gettabinfo([{expr}]) List list of tab pages | |
249 gettabvar({nr}, {varname} [, {def}]) | |
250 any variable {varname} in tab {nr} or {def} | |
251 gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) | |
252 any {name} in {winnr} in tab page {tabnr} | |
253 gettagstack([{nr}]) Dict get the tag stack of window {nr} | |
254 gettext({text}) String lookup translation of {text} | |
255 getwininfo([{winid}]) List list of info about each window | |
256 getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window | |
257 getwinposx() Number X coord in pixels of the Vim window | |
258 getwinposy() Number Y coord in pixels of the Vim window | |
259 getwinvar({nr}, {varname} [, {def}]) | |
260 any variable {varname} in window {nr} | |
261 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
262 any expand file wildcards in {expr} | |
263 glob2regpat({expr}) String convert a glob pat into a search pat | |
264 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
265 String do glob({expr}) for all dirs in {path} | |
266 has({feature} [, {check}]) Number |TRUE| if feature {feature} supported | |
267 has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} | |
268 haslocaldir([{winnr} [, {tabnr}]]) | |
269 Number |TRUE| if the window executed |:lcd| | |
270 or |:tcd| | |
271 hasmapto({what} [, {mode} [, {abbr}]]) | |
272 Number |TRUE| if mapping to {what} exists | |
273 histadd({history}, {item}) Number add an item to a history | |
274 histdel({history} [, {item}]) Number remove an item from a history | |
275 histget({history} [, {index}]) String get the item {index} from a history | |
276 histnr({history}) Number highest index of a history | |
277 hlID({name}) Number syntax ID of highlight group {name} | |
278 hlexists({name}) Number |TRUE| if highlight group {name} exists | |
279 hlget([{name} [, {resolve}]]) List get highlight group attributes | |
280 hlset({list}) Number set highlight group attributes | |
281 hostname() String name of the machine Vim is running on | |
282 iconv({expr}, {from}, {to}) String convert encoding of {expr} | |
283 indent({lnum}) Number indent of line {lnum} | |
284 index({object}, {expr} [, {start} [, {ic}]]) | |
285 Number index in {object} where {expr} appears | |
286 input({prompt} [, {text} [, {completion}]]) | |
287 String get input from the user | |
288 inputdialog({prompt} [, {text} [, {completion}]]) | |
289 String like input() but in a GUI dialog | |
290 inputlist({textlist}) Number let the user pick from a choice list | |
291 inputrestore() Number restore typeahead | |
292 inputsave() Number save and clear typeahead | |
293 inputsecret({prompt} [, {text}]) String like input() but hiding the text | |
294 insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}] | |
295 interrupt() none interrupt script execution | |
296 invert({expr}) Number bitwise invert | |
297 isdirectory({directory}) Number |TRUE| if {directory} is a directory | |
298 isinf({expr}) Number determine if {expr} is infinity value | |
299 (positive or negative) | |
300 islocked({expr}) Number |TRUE| if {expr} is locked | |
301 isnan({expr}) Number |TRUE| if {expr} is NaN | |
302 items({dict}) List key-value pairs in {dict} | |
303 job_getchannel({job}) Channel get the channel handle for {job} | |
304 job_info([{job}]) Dict get information about {job} | |
305 job_setoptions({job}, {options}) none set options for {job} | |
306 job_start({command} [, {options}]) | |
307 Job start a job | |
308 job_status({job}) String get the status of {job} | |
309 job_stop({job} [, {how}]) Number stop {job} | |
310 join({list} [, {sep}]) String join {list} items into one String | |
311 js_decode({string}) any decode JS style JSON | |
312 js_encode({expr}) String encode JS style JSON | |
313 json_decode({string}) any decode JSON | |
314 json_encode({expr}) String encode JSON | |
315 keys({dict}) List keys in {dict} | |
316 len({expr}) Number the length of {expr} | |
317 libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg} | |
318 libcallnr({lib}, {func}, {arg}) Number idem, but return a Number | |
319 line({expr} [, {winid}]) Number line nr of cursor, last line or mark | |
320 line2byte({lnum}) Number byte count of line {lnum} | |
321 lispindent({lnum}) Number Lisp indent for line {lnum} | |
322 list2blob({list}) Blob turn {list} of numbers into a Blob | |
323 list2str({list} [, {utf8}]) String turn {list} of numbers into a String | |
324 listener_add({callback} [, {buf}]) | |
325 Number add a callback to listen to changes | |
326 listener_flush([{buf}]) none invoke listener callbacks | |
327 listener_remove({id}) none remove a listener callback | |
328 localtime() Number current time | |
329 log({expr}) Float natural logarithm (base e) of {expr} | |
330 log10({expr}) Float logarithm of Float {expr} to base 10 | |
331 luaeval({expr} [, {expr}]) any evaluate |Lua| expression | |
332 map({expr1}, {expr2}) List/Dict/Blob/String | |
333 change each item in {expr1} to {expr2} | |
334 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) | |
335 String or Dict | |
336 rhs of mapping {name} in mode {mode} | |
337 mapcheck({name} [, {mode} [, {abbr}]]) | |
338 String check for mappings matching {name} | |
339 mapnew({expr1}, {expr2}) List/Dict/Blob/String | |
340 like |map()| but creates a new List or | |
341 Dictionary | |
342 mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result | |
343 match({expr}, {pat} [, {start} [, {count}]]) | |
344 Number position where {pat} matches in {expr} | |
345 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) | |
346 Number highlight {pattern} with {group} | |
347 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) | |
348 Number highlight positions with {group} | |
349 matcharg({nr}) List arguments of |:match| | |
350 matchdelete({id} [, {win}]) Number delete match identified by {id} | |
351 matchend({expr}, {pat} [, {start} [, {count}]]) | |
352 Number position where {pat} ends in {expr} | |
353 matchfuzzy({list}, {str} [, {dict}]) | |
354 List fuzzy match {str} in {list} | |
355 matchfuzzypos({list}, {str} [, {dict}]) | |
356 List fuzzy match {str} in {list} | |
357 matchlist({expr}, {pat} [, {start} [, {count}]]) | |
358 List match and submatches of {pat} in {expr} | |
359 matchstr({expr}, {pat} [, {start} [, {count}]]) | |
360 String {count}'th match of {pat} in {expr} | |
361 matchstrpos({expr}, {pat} [, {start} [, {count}]]) | |
362 List {count}'th match of {pat} in {expr} | |
363 max({expr}) Number maximum value of items in {expr} | |
364 menu_info({name} [, {mode}]) Dict get menu item information | |
365 min({expr}) Number minimum value of items in {expr} | |
366 mkdir({name} [, {path} [, {prot}]]) | |
367 Number create directory {name} | |
368 mode([expr]) String current editing mode | |
369 mzeval({expr}) any evaluate |MzScheme| expression | |
370 nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} | |
371 nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr} | |
372 or({expr}, {expr}) Number bitwise OR | |
373 pathshorten({expr} [, {len}]) String shorten directory names in a path | |
374 perleval({expr}) any evaluate |Perl| expression | |
375 popup_atcursor({what}, {options}) Number create popup window near the cursor | |
376 popup_beval({what}, {options}) Number create popup window for 'ballooneval' | |
377 popup_clear() none close all popup windows | |
378 popup_close({id} [, {result}]) none close popup window {id} | |
379 popup_create({what}, {options}) Number create a popup window | |
380 popup_dialog({what}, {options}) Number create a popup window used as a dialog | |
381 popup_filter_menu({id}, {key}) Number filter for a menu popup window | |
382 popup_filter_yesno({id}, {key}) Number filter for a dialog popup window | |
383 popup_findinfo() Number get window ID of info popup window | |
384 popup_findpreview() Number get window ID of preview popup window | |
385 popup_getoptions({id}) Dict get options of popup window {id} | |
386 popup_getpos({id}) Dict get position of popup window {id} | |
387 popup_hide({id}) none hide popup menu {id} | |
388 popup_list() List get a list of window IDs of all popups | |
389 popup_locate({row}, {col}) Number get window ID of popup at position | |
390 popup_menu({what}, {options}) Number create a popup window used as a menu | |
391 popup_move({id}, {options}) none set position of popup window {id} | |
392 popup_notification({what}, {options}) | |
393 Number create a notification popup window | |
394 popup_setoptions({id}, {options}) | |
395 none set options for popup window {id} | |
396 popup_settext({id}, {text}) none set the text of popup window {id} | |
397 popup_show({id}) none unhide popup window {id} | |
398 pow({x}, {y}) Float {x} to the power of {y} | |
399 prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} | |
400 printf({fmt}, {expr1}...) String format text | |
401 prompt_getprompt({buf}) String get prompt text | |
402 prompt_setcallback({buf}, {expr}) none set prompt callback function | |
403 prompt_setinterrupt({buf}, {text}) none set prompt interrupt function | |
404 prompt_setprompt({buf}, {text}) none set prompt text | |
405 prop_add({lnum}, {col}, {props}) none add one text property | |
406 prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) | |
407 none add multiple text properties | |
408 prop_clear({lnum} [, {lnum-end} [, {props}]]) | |
409 none remove all text properties | |
410 prop_find({props} [, {direction}]) | |
411 Dict search for a text property | |
412 prop_list({lnum} [, {props}]) List text properties in {lnum} | |
413 prop_remove({props} [, {lnum} [, {lnum-end}]]) | |
414 Number remove a text property | |
415 prop_type_add({name}, {props}) none define a new property type | |
416 prop_type_change({name}, {props}) | |
417 none change an existing property type | |
418 prop_type_delete({name} [, {props}]) | |
419 none delete a property type | |
420 prop_type_get({name} [, {props}]) | |
421 Dict get property type values | |
422 prop_type_list([{props}]) List get list of property types | |
423 pum_getpos() Dict position and size of pum if visible | |
424 pumvisible() Number whether popup menu is visible | |
425 py3eval({expr}) any evaluate |python3| expression | |
426 pyeval({expr}) any evaluate |Python| expression | |
427 pyxeval({expr}) any evaluate |python_x| expression | |
428 rand([{expr}]) Number get pseudo-random number | |
429 range({expr} [, {max} [, {stride}]]) | |
430 List items from {expr} to {max} | |
431 readblob({fname}) Blob read a |Blob| from {fname} | |
432 readdir({dir} [, {expr} [, {dict}]]) | |
433 List file names in {dir} selected by {expr} | |
434 readdirex({dir} [, {expr} [, {dict}]]) | |
435 List file info in {dir} selected by {expr} | |
436 readfile({fname} [, {type} [, {max}]]) | |
437 List get list of lines from file {fname} | |
438 reduce({object}, {func} [, {initial}]) | |
439 any reduce {object} using {func} | |
440 reg_executing() String get the executing register name | |
441 reg_recording() String get the recording register name | |
442 reltime([{start} [, {end}]]) List get time value | |
443 reltimefloat({time}) Float turn the time value into a Float | |
444 reltimestr({time}) String turn time value into a String | |
445 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) | |
446 String send expression | |
447 remote_foreground({server}) Number bring Vim server to the foreground | |
448 remote_peek({serverid} [, {retvar}]) | |
449 Number check for reply string | |
450 remote_read({serverid} [, {timeout}]) | |
451 String read reply string | |
452 remote_send({server}, {string} [, {idvar}]) | |
453 String send key sequence | |
454 remote_startserver({name}) none become server {name} | |
455 remove({list}, {idx} [, {end}]) any/List | |
456 remove items {idx}-{end} from {list} | |
457 remove({blob}, {idx} [, {end}]) Number/Blob | |
458 remove bytes {idx}-{end} from {blob} | |
459 remove({dict}, {key}) any remove entry {key} from {dict} | |
460 rename({from}, {to}) Number rename (move) file from {from} to {to} | |
461 repeat({expr}, {count}) String repeat {expr} {count} times | |
462 resolve({filename}) String get filename a shortcut points to | |
463 reverse({list}) List reverse {list} in-place | |
464 round({expr}) Float round off {expr} | |
465 rubyeval({expr}) any evaluate |Ruby| expression | |
466 screenattr({row}, {col}) Number attribute at screen position | |
467 screenchar({row}, {col}) Number character at screen position | |
468 screenchars({row}, {col}) List List of characters at screen position | |
469 screencol() Number current cursor column | |
470 screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character | |
471 screenrow() Number current cursor row | |
472 screenstring({row}, {col}) String characters at screen position | |
473 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
474 Number search for {pattern} | |
475 searchcount([{options}]) Dict get or update search stats | |
476 searchdecl({name} [, {global} [, {thisblock}]]) | |
477 Number search for variable declaration | |
478 searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) | |
479 Number search for other end of start/end pair | |
480 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) | |
481 List search for other end of start/end pair | |
482 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
483 List search for {pattern} | |
484 server2client({clientid}, {string}) | |
485 Number send reply string | |
486 serverlist() String get a list of available servers | |
487 setbufline({expr}, {lnum}, {text}) | |
488 Number set line {lnum} to {text} in buffer | |
489 {expr} | |
490 setbufvar({buf}, {varname}, {val}) | |
491 none set {varname} in buffer {buf} to {val} | |
492 setcellwidths({list}) none set character cell width overrides | |
493 setcharpos({expr}, {list}) Number set the {expr} position to {list} | |
494 setcharsearch({dict}) Dict set character search from {dict} | |
495 setcmdpos({pos}) Number set cursor position in command-line | |
496 setcursorcharpos({list}) Number move cursor to position in {list} | |
497 setenv({name}, {val}) none set environment variable | |
498 setfperm({fname}, {mode}) Number set {fname} file permissions to {mode} | |
499 setline({lnum}, {line}) Number set line {lnum} to {line} | |
500 setloclist({nr}, {list} [, {action}]) | |
501 Number modify location list using {list} | |
502 setloclist({nr}, {list}, {action}, {what}) | |
503 Number modify specific location list props | |
504 setmatches({list} [, {win}]) Number restore a list of matches | |
505 setpos({expr}, {list}) Number set the {expr} position to {list} | |
506 setqflist({list} [, {action}]) Number modify quickfix list using {list} | |
507 setqflist({list}, {action}, {what}) | |
508 Number modify specific quickfix list props | |
509 setreg({n}, {v} [, {opt}]) Number set register to value and type | |
510 settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val} | |
511 settabwinvar({tabnr}, {winnr}, {varname}, {val}) | |
512 none set {varname} in window {winnr} in tab | |
513 page {tabnr} to {val} | |
514 settagstack({nr}, {dict} [, {action}]) | |
515 Number modify tag stack using {dict} | |
516 setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val} | |
517 sha256({string}) String SHA256 checksum of {string} | |
518 shellescape({string} [, {special}]) | |
519 String escape {string} for use as shell | |
520 command argument | |
521 shiftwidth([{col}]) Number effective value of 'shiftwidth' | |
522 sign_define({name} [, {dict}]) Number define or update a sign | |
523 sign_define({list}) List define or update a list of signs | |
524 sign_getdefined([{name}]) List get a list of defined signs | |
525 sign_getplaced([{buf} [, {dict}]]) | |
526 List get a list of placed signs | |
527 sign_jump({id}, {group}, {buf}) | |
528 Number jump to a sign | |
529 sign_place({id}, {group}, {name}, {buf} [, {dict}]) | |
530 Number place a sign | |
531 sign_placelist({list}) List place a list of signs | |
532 sign_undefine([{name}]) Number undefine a sign | |
533 sign_undefine({list}) List undefine a list of signs | |
534 sign_unplace({group} [, {dict}]) | |
535 Number unplace a sign | |
536 sign_unplacelist({list}) List unplace a list of signs | |
537 simplify({filename}) String simplify filename as much as possible | |
538 sin({expr}) Float sine of {expr} | |
539 sinh({expr}) Float hyperbolic sine of {expr} | |
540 slice({expr}, {start} [, {end}]) String, List or Blob | |
541 slice of a String, List or Blob | |
542 sort({list} [, {func} [, {dict}]]) | |
543 List sort {list}, using {func} to compare | |
544 sound_clear() none stop playing all sounds | |
545 sound_playevent({name} [, {callback}]) | |
546 Number play an event sound | |
547 sound_playfile({path} [, {callback}]) | |
548 Number play sound file {path} | |
549 sound_stop({id}) none stop playing sound {id} | |
550 soundfold({word}) String sound-fold {word} | |
551 spellbadword() String badly spelled word at cursor | |
552 spellsuggest({word} [, {max} [, {capital}]]) | |
553 List spelling suggestions | |
554 split({expr} [, {pat} [, {keepempty}]]) | |
555 List make |List| from {pat} separated {expr} | |
556 sqrt({expr}) Float square root of {expr} | |
557 srand([{expr}]) List get seed for |rand()| | |
558 state([{what}]) String current state of Vim | |
559 str2float({expr} [, {quoted}]) Float convert String to Float | |
560 str2list({expr} [, {utf8}]) List convert each character of {expr} to | |
561 ASCII/UTF-8 value | |
562 str2nr({expr} [, {base} [, {quoted}]]) | |
563 Number convert String to Number | |
564 strcharlen({expr}) Number character length of the String {expr} | |
565 strcharpart({str}, {start} [, {len} [, {skipcc}]]) | |
566 String {len} characters of {str} at | |
567 character {start} | |
568 strchars({expr} [, {skipcc}]) Number character count of the String {expr} | |
569 strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} | |
570 strftime({format} [, {time}]) String format time with a specified format | |
571 strgetchar({str}, {index}) Number get char {index} from {str} | |
572 stridx({haystack}, {needle} [, {start}]) | |
573 Number index of {needle} in {haystack} | |
574 string({expr}) String String representation of {expr} value | |
575 strlen({expr}) Number length of the String {expr} | |
576 strpart({str}, {start} [, {len} [, {chars}]]) | |
577 String {len} bytes/chars of {str} at | |
578 byte {start} | |
579 strptime({format}, {timestring}) | |
580 Number Convert {timestring} to unix timestamp | |
581 strridx({haystack}, {needle} [, {start}]) | |
582 Number last index of {needle} in {haystack} | |
583 strtrans({expr}) String translate string to make it printable | |
584 strwidth({expr}) Number display cell length of the String {expr} | |
585 submatch({nr} [, {list}]) String or List | |
586 specific match in ":s" or substitute() | |
587 substitute({expr}, {pat}, {sub}, {flags}) | |
588 String all {pat} in {expr} replaced with {sub} | |
589 swapinfo({fname}) Dict information about swap file {fname} | |
590 swapname({buf}) String swap file of buffer {buf} | |
591 synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} | |
592 synIDattr({synID}, {what} [, {mode}]) | |
593 String attribute {what} of syntax ID {synID} | |
594 synIDtrans({synID}) Number translated syntax ID of {synID} | |
595 synconcealed({lnum}, {col}) List info about concealing | |
596 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} | |
597 system({expr} [, {input}]) String output of shell command/filter {expr} | |
598 systemlist({expr} [, {input}]) List output of shell command/filter {expr} | |
599 tabpagebuflist([{arg}]) List list of buffer numbers in tab page | |
600 tabpagenr([{arg}]) Number number of current or last tab page | |
601 tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page | |
602 tagfiles() List tags files used | |
603 taglist({expr} [, {filename}]) List list of tags matching {expr} | |
604 tan({expr}) Float tangent of {expr} | |
605 tanh({expr}) Float hyperbolic tangent of {expr} | |
606 tempname() String name for a temporary file | |
607 term_dumpdiff({filename}, {filename} [, {options}]) | |
608 Number display difference between two dumps | |
609 term_dumpload({filename} [, {options}]) | |
610 Number displaying a screen dump | |
611 term_dumpwrite({buf}, {filename} [, {options}]) | |
612 none dump terminal window contents | |
613 term_getaltscreen({buf}) Number get the alternate screen flag | |
614 term_getansicolors({buf}) List get ANSI palette in GUI color mode | |
615 term_getattr({attr}, {what}) Number get the value of attribute {what} | |
616 term_getcursor({buf}) List get the cursor position of a terminal | |
617 term_getjob({buf}) Job get the job associated with a terminal | |
618 term_getline({buf}, {row}) String get a line of text from a terminal | |
619 term_getscrolled({buf}) Number get the scroll count of a terminal | |
620 term_getsize({buf}) List get the size of a terminal | |
621 term_getstatus({buf}) String get the status of a terminal | |
622 term_gettitle({buf}) String get the title of a terminal | |
623 term_gettty({buf}, [{input}]) String get the tty name of a terminal | |
624 term_list() List get the list of terminal buffers | |
625 term_scrape({buf}, {row}) List get row of a terminal screen | |
626 term_sendkeys({buf}, {keys}) none send keystrokes to a terminal | |
627 term_setansicolors({buf}, {colors}) | |
628 none set ANSI palette in GUI color mode | |
629 term_setapi({buf}, {expr}) none set |terminal-api| function name prefix | |
630 term_setkill({buf}, {how}) none set signal to stop job in terminal | |
631 term_setrestore({buf}, {command}) none set command to restore terminal | |
632 term_setsize({buf}, {rows}, {cols}) | |
633 none set the size of a terminal | |
634 term_start({cmd} [, {options}]) Number open a terminal window and run a job | |
635 term_wait({buf} [, {time}]) Number wait for screen to be updated | |
636 terminalprops() Dict properties of the terminal | |
637 test_alloc_fail({id}, {countdown}, {repeat}) | |
638 none make memory allocation fail | |
639 test_autochdir() none enable 'autochdir' during startup | |
640 test_feedinput({string}) none add key sequence to input buffer | |
641 test_garbagecollect_now() none free memory right now for testing | |
642 test_garbagecollect_soon() none free memory soon for testing | |
643 test_getvalue({string}) any get value of an internal variable | |
644 test_gui_drop_files({list}, {row}, {col}, {mods}) | |
645 none drop a list of files in a window | |
646 test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods}) | |
647 none add a mouse event to the input buffer | |
648 test_ignore_error({expr}) none ignore a specific error | |
649 test_null_blob() Blob null value for testing | |
650 test_null_channel() Channel null value for testing | |
651 test_null_dict() Dict null value for testing | |
652 test_null_function() Funcref null value for testing | |
653 test_null_job() Job null value for testing | |
654 test_null_list() List null value for testing | |
655 test_null_partial() Funcref null value for testing | |
656 test_null_string() String null value for testing | |
657 test_option_not_set({name}) none reset flag indicating option was set | |
658 test_override({expr}, {val}) none test with Vim internal overrides | |
659 test_refcount({expr}) Number get the reference count of {expr} | |
660 test_scrollbar({which}, {value}, {dragging}) | |
661 none scroll in the GUI for testing | |
662 test_setmouse({row}, {col}) none set the mouse position for testing | |
663 test_settime({expr}) none set current time for testing | |
664 test_srand_seed([seed]) none set seed for testing srand() | |
665 test_unknown() any unknown value for testing | |
666 test_void() any void value for testing | |
667 timer_info([{id}]) List information about timers | |
668 timer_pause({id}, {pause}) none pause or unpause a timer | |
669 timer_start({time}, {callback} [, {options}]) | |
670 Number create a timer | |
671 timer_stop({timer}) none stop a timer | |
672 timer_stopall() none stop all timers | |
673 tolower({expr}) String the String {expr} switched to lowercase | |
674 toupper({expr}) String the String {expr} switched to uppercase | |
675 tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} | |
676 to chars in {tostr} | |
677 trim({text} [, {mask} [, {dir}]]) | |
678 String trim characters in {mask} from {text} | |
679 trunc({expr}) Float truncate Float {expr} | |
680 type({expr}) Number type of value {expr} | |
681 typename({expr}) String representation of the type of {expr} | |
682 undofile({name}) String undo file name for {name} | |
683 undotree() List undo file tree | |
684 uniq({list} [, {func} [, {dict}]]) | |
685 List remove adjacent duplicates from a list | |
686 values({dict}) List values in {dict} | |
687 virtcol({expr}) Number screen column of cursor or mark | |
688 visualmode([expr]) String last visual mode used | |
689 wildmenumode() Number whether 'wildmenu' mode is active | |
690 win_execute({id}, {command} [, {silent}]) | |
691 String execute {command} in window {id} | |
692 win_findbuf({bufnr}) List find windows containing {bufnr} | |
693 win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} | |
694 win_gettype([{nr}]) String type of window {nr} | |
695 win_gotoid({expr}) Number go to window with ID {expr} | |
696 win_id2tabwin({expr}) List get tab and window nr from window ID | |
697 win_id2win({expr}) Number get window nr from window ID | |
698 win_screenpos({nr}) List get screen position of window {nr} | |
699 win_splitmove({nr}, {target} [, {options}]) | |
700 Number move window {nr} to split of {target} | |
701 winbufnr({nr}) Number buffer number of window {nr} | |
702 wincol() Number window column of the cursor | |
703 windowsversion() String MS-Windows OS version | |
704 winheight({nr}) Number height of window {nr} | |
705 winlayout([{tabnr}]) List layout of windows in tab {tabnr} | |
706 winline() Number window line of the cursor | |
707 winnr([{expr}]) Number number of current window | |
708 winrestcmd() String returns command to restore window sizes | |
709 winrestview({dict}) none restore view of current window | |
710 winsaveview() Dict save view of current window | |
711 winwidth({nr}) Number width of window {nr} | |
712 wordcount() Dict get byte/char/word statistics | |
713 writefile({object}, {fname} [, {flags}]) | |
714 Number write |Blob| or |List| of lines to file | |
715 xor({expr}, {expr}) Number bitwise XOR | |
716 | |
717 ============================================================================== | |
718 2. Details *builtin-function-details* | |
719 | |
720 Not all functions are here, some have been moved to a help file covering the | |
721 specific functionality. | |
722 | |
723 abs({expr}) *abs()* | |
724 Return the absolute value of {expr}. When {expr} evaluates to | |
725 a |Float| abs() returns a |Float|. When {expr} can be | |
726 converted to a |Number| abs() returns a |Number|. Otherwise | |
727 abs() gives an error message and returns -1. | |
728 Examples: > | |
729 echo abs(1.456) | |
730 < 1.456 > | |
731 echo abs(-5.456) | |
732 < 5.456 > | |
733 echo abs(-4) | |
734 < 4 | |
735 | |
736 Can also be used as a |method|: > | |
737 Compute()->abs() | |
738 | |
739 < {only available when compiled with the |+float| feature} | |
740 | |
741 | |
742 acos({expr}) *acos()* | |
743 Return the arc cosine of {expr} measured in radians, as a | |
744 |Float| in the range of [0, pi]. | |
745 {expr} must evaluate to a |Float| or a |Number| in the range | |
746 [-1, 1]. | |
747 Examples: > | |
748 :echo acos(0) | |
749 < 1.570796 > | |
750 :echo acos(-0.5) | |
751 < 2.094395 | |
752 | |
753 Can also be used as a |method|: > | |
754 Compute()->acos() | |
755 | |
756 < {only available when compiled with the |+float| feature} | |
757 | |
758 | |
759 add({object}, {expr}) *add()* | |
760 Append the item {expr} to |List| or |Blob| {object}. Returns | |
761 the resulting |List| or |Blob|. Examples: > | |
762 :let alist = add([1, 2, 3], item) | |
763 :call add(mylist, "woodstock") | |
764 < Note that when {expr} is a |List| it is appended as a single | |
765 item. Use |extend()| to concatenate |Lists|. | |
766 When {object} is a |Blob| then {expr} must be a number. | |
767 Use |insert()| to add an item at another position. | |
768 | |
769 Can also be used as a |method|: > | |
770 mylist->add(val1)->add(val2) | |
771 | |
772 | |
773 and({expr}, {expr}) *and()* | |
774 Bitwise AND on the two arguments. The arguments are converted | |
775 to a number. A List, Dict or Float argument causes an error. | |
776 Example: > | |
777 :let flag = and(bits, 0x80) | |
778 < Can also be used as a |method|: > | |
779 :let flag = bits->and(0x80) | |
780 | |
781 | |
782 append({lnum}, {text}) *append()* | |
783 When {text} is a |List|: Append each item of the |List| as a | |
784 text line below line {lnum} in the current buffer. | |
785 Otherwise append {text} as one text line below line {lnum} in | |
786 the current buffer. | |
787 Any type of item is accepted and converted to a String. | |
788 {lnum} can be zero to insert a line before the first one. | |
789 {lnum} is used like with |getline()|. | |
790 Returns 1 for failure ({lnum} out of range or out of memory), | |
791 0 for success. In |Vim9| script an invalid argument or | |
792 negative number results in an error. Example: > | |
793 :let failed = append(line('$'), "# THE END") | |
794 :let failed = append(0, ["Chapter 1", "the beginning"]) | |
795 | |
796 < Can also be used as a |method| after a List, the base is | |
797 passed as the second argument: > | |
798 mylist->append(lnum) | |
799 | |
800 | |
801 appendbufline({buf}, {lnum}, {text}) *appendbufline()* | |
802 Like |append()| but append the text in buffer {buf}. | |
803 | |
804 This function works only for loaded buffers. First call | |
805 |bufload()| if needed. | |
806 | |
807 For the use of {buf}, see |bufname()|. | |
808 | |
809 {lnum} is used like with |append()|. Note that using |line()| | |
810 would use the current buffer, not the one appending to. | |
811 Use "$" to append at the end of the buffer. | |
812 | |
813 On success 0 is returned, on failure 1 is returned. | |
814 In |Vim9| script an error is given for an invalid {lnum}. | |
815 | |
816 If {buf} is not a valid buffer or {lnum} is not valid, an | |
817 error message is given. Example: > | |
818 :let failed = appendbufline(13, 0, "# THE START") | |
819 < | |
820 Can also be used as a |method| after a List, the base is | |
821 passed as the second argument: > | |
822 mylist->appendbufline(buf, lnum) | |
823 | |
824 | |
825 argc([{winid}]) *argc()* | |
826 The result is the number of files in the argument list. See | |
827 |arglist|. | |
828 If {winid} is not supplied, the argument list of the current | |
829 window is used. | |
830 If {winid} is -1, the global argument list is used. | |
831 Otherwise {winid} specifies the window of which the argument | |
832 list is used: either the window number or the window ID. | |
833 Returns -1 if the {winid} argument is invalid. | |
834 | |
835 *argidx()* | |
836 argidx() The result is the current index in the argument list. 0 is | |
837 the first file. argc() - 1 is the last one. See |arglist|. | |
838 | |
839 *arglistid()* | |
840 arglistid([{winnr} [, {tabnr}]]) | |
841 Return the argument list ID. This is a number which | |
842 identifies the argument list being used. Zero is used for the | |
843 global argument list. See |arglist|. | |
844 Returns -1 if the arguments are invalid. | |
845 | |
846 Without arguments use the current window. | |
847 With {winnr} only use this window in the current tab page. | |
848 With {winnr} and {tabnr} use the window in the specified tab | |
849 page. | |
850 {winnr} can be the window number or the |window-ID|. | |
851 | |
852 *argv()* | |
853 argv([{nr} [, {winid}]]) | |
854 The result is the {nr}th file in the argument list. See | |
855 |arglist|. "argv(0)" is the first one. Example: > | |
856 :let i = 0 | |
857 :while i < argc() | |
858 : let f = escape(fnameescape(argv(i)), '.') | |
859 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>' | |
860 : let i = i + 1 | |
861 :endwhile | |
862 < Without the {nr} argument, or when {nr} is -1, a |List| with | |
863 the whole |arglist| is returned. | |
864 | |
865 The {winid} argument specifies the window ID, see |argc()|. | |
866 For the Vim command line arguments see |v:argv|. | |
867 | |
868 asin({expr}) *asin()* | |
869 Return the arc sine of {expr} measured in radians, as a |Float| | |
870 in the range of [-pi/2, pi/2]. | |
871 {expr} must evaluate to a |Float| or a |Number| in the range | |
872 [-1, 1]. | |
873 Examples: > | |
874 :echo asin(0.8) | |
875 < 0.927295 > | |
876 :echo asin(-0.5) | |
877 < -0.523599 | |
878 | |
879 Can also be used as a |method|: > | |
880 Compute()->asin() | |
881 < | |
882 {only available when compiled with the |+float| feature} | |
883 | |
884 | |
885 assert_ functions are documented here: |assert-functions-details| | |
886 | |
887 | |
888 | |
889 atan({expr}) *atan()* | |
890 Return the principal value of the arc tangent of {expr}, in | |
891 the range [-pi/2, +pi/2] radians, as a |Float|. | |
892 {expr} must evaluate to a |Float| or a |Number|. | |
893 Examples: > | |
894 :echo atan(100) | |
895 < 1.560797 > | |
896 :echo atan(-4.01) | |
897 < -1.326405 | |
898 | |
899 Can also be used as a |method|: > | |
900 Compute()->atan() | |
901 < | |
902 {only available when compiled with the |+float| feature} | |
903 | |
904 | |
905 atan2({expr1}, {expr2}) *atan2()* | |
906 Return the arc tangent of {expr1} / {expr2}, measured in | |
907 radians, as a |Float| in the range [-pi, pi]. | |
908 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. | |
909 Examples: > | |
910 :echo atan2(-1, 1) | |
911 < -0.785398 > | |
912 :echo atan2(1, -1) | |
913 < 2.356194 | |
914 | |
915 Can also be used as a |method|: > | |
916 Compute()->atan2(1) | |
917 < | |
918 {only available when compiled with the |+float| feature} | |
919 | |
920 balloon_gettext() *balloon_gettext()* | |
921 Return the current text in the balloon. Only for the string, | |
922 not used for the List. | |
923 | |
924 balloon_show({expr}) *balloon_show()* | |
925 Show {expr} inside the balloon. For the GUI {expr} is used as | |
926 a string. For a terminal {expr} can be a list, which contains | |
927 the lines of the balloon. If {expr} is not a list it will be | |
928 split with |balloon_split()|. | |
929 If {expr} is an empty string any existing balloon is removed. | |
930 | |
931 Example: > | |
932 func GetBalloonContent() | |
933 " ... initiate getting the content | |
934 return '' | |
935 endfunc | |
936 set balloonexpr=GetBalloonContent() | |
937 | |
938 func BalloonCallback(result) | |
939 call balloon_show(a:result) | |
940 endfunc | |
941 < Can also be used as a |method|: > | |
942 GetText()->balloon_show() | |
943 < | |
944 The intended use is that fetching the content of the balloon | |
945 is initiated from 'balloonexpr'. It will invoke an | |
946 asynchronous method, in which a callback invokes | |
947 balloon_show(). The 'balloonexpr' itself can return an | |
948 empty string or a placeholder. | |
949 | |
950 When showing a balloon is not possible nothing happens, no | |
951 error message. | |
952 {only available when compiled with the |+balloon_eval| or | |
953 |+balloon_eval_term| feature} | |
954 | |
955 balloon_split({msg}) *balloon_split()* | |
956 Split String {msg} into lines to be displayed in a balloon. | |
957 The splits are made for the current window size and optimize | |
958 to show debugger output. | |
959 Returns a |List| with the split lines. | |
960 Can also be used as a |method|: > | |
961 GetText()->balloon_split()->balloon_show() | |
962 | |
963 < {only available when compiled with the |+balloon_eval_term| | |
964 feature} | |
965 | |
966 blob2list({blob}) *blob2list()* | |
967 Return a List containing the number value of each byte in Blob | |
968 {blob}. Examples: > | |
969 blob2list(0z0102.0304) returns [1, 2, 3, 4] | |
970 blob2list(0z) returns [] | |
971 < Returns an empty List on error. |list2blob()| does the | |
972 opposite. | |
973 | |
974 Can also be used as a |method|: > | |
975 GetBlob()->blob2list() | |
976 | |
977 *browse()* | |
978 browse({save}, {title}, {initdir}, {default}) | |
979 Put up a file requester. This only works when "has("browse")" | |
980 returns |TRUE| (only in some GUI versions). | |
981 The input fields are: | |
982 {save} when |TRUE|, select file to write | |
983 {title} title for the requester | |
984 {initdir} directory to start browsing in | |
985 {default} default file name | |
986 An empty string is returned when the "Cancel" button is hit, | |
987 something went wrong, or browsing is not possible. | |
988 | |
989 *browsedir()* | |
990 browsedir({title}, {initdir}) | |
991 Put up a directory requester. This only works when | |
992 "has("browse")" returns |TRUE| (only in some GUI versions). | |
993 On systems where a directory browser is not supported a file | |
994 browser is used. In that case: select a file in the directory | |
995 to be used. | |
996 The input fields are: | |
997 {title} title for the requester | |
998 {initdir} directory to start browsing in | |
999 When the "Cancel" button is hit, something went wrong, or | |
1000 browsing is not possible, an empty string is returned. | |
1001 | |
1002 bufadd({name}) *bufadd()* | |
1003 Add a buffer to the buffer list with String {name}. | |
1004 If a buffer for file {name} already exists, return that buffer | |
1005 number. Otherwise return the buffer number of the newly | |
1006 created buffer. When {name} is an empty string then a new | |
1007 buffer is always created. | |
1008 The buffer will not have 'buflisted' set and not be loaded | |
1009 yet. To add some text to the buffer use this: > | |
1010 let bufnr = bufadd('someName') | |
1011 call bufload(bufnr) | |
1012 call setbufline(bufnr, 1, ['some', 'text']) | |
1013 < Can also be used as a |method|: > | |
1014 let bufnr = 'somename'->bufadd() | |
1015 | |
1016 bufexists({buf}) *bufexists()* | |
1017 The result is a Number, which is |TRUE| if a buffer called | |
1018 {buf} exists. | |
1019 If the {buf} argument is a number, buffer numbers are used. | |
1020 Number zero is the alternate buffer for the current window. | |
1021 | |
1022 If the {buf} argument is a string it must match a buffer name | |
1023 exactly. The name can be: | |
1024 - Relative to the current directory. | |
1025 - A full path. | |
1026 - The name of a buffer with 'buftype' set to "nofile". | |
1027 - A URL name. | |
1028 Unlisted buffers will be found. | |
1029 Note that help files are listed by their short name in the | |
1030 output of |:buffers|, but bufexists() requires using their | |
1031 long name to be able to find them. | |
1032 bufexists() may report a buffer exists, but to use the name | |
1033 with a |:buffer| command you may need to use |expand()|. Esp | |
1034 for MS-Windows 8.3 names in the form "c:\DOCUME~1" | |
1035 Use "bufexists(0)" to test for the existence of an alternate | |
1036 file name. | |
1037 | |
1038 Can also be used as a |method|: > | |
1039 let exists = 'somename'->bufexists() | |
1040 < | |
1041 Obsolete name: buffer_exists(). *buffer_exists()* | |
1042 | |
1043 buflisted({buf}) *buflisted()* | |
1044 The result is a Number, which is |TRUE| if a buffer called | |
1045 {buf} exists and is listed (has the 'buflisted' option set). | |
1046 The {buf} argument is used like with |bufexists()|. | |
1047 | |
1048 Can also be used as a |method|: > | |
1049 let listed = 'somename'->buflisted() | |
1050 | |
1051 bufload({buf}) *bufload()* | |
1052 Ensure the buffer {buf} is loaded. When the buffer name | |
1053 refers to an existing file then the file is read. Otherwise | |
1054 the buffer will be empty. If the buffer was already loaded | |
1055 then there is no change. | |
1056 If there is an existing swap file for the file of the buffer, | |
1057 there will be no dialog, the buffer will be loaded anyway. | |
1058 The {buf} argument is used like with |bufexists()|. | |
1059 | |
1060 Can also be used as a |method|: > | |
1061 eval 'somename'->bufload() | |
1062 | |
1063 bufloaded({buf}) *bufloaded()* | |
1064 The result is a Number, which is |TRUE| if a buffer called | |
1065 {buf} exists and is loaded (shown in a window or hidden). | |
1066 The {buf} argument is used like with |bufexists()|. | |
1067 | |
1068 Can also be used as a |method|: > | |
1069 let loaded = 'somename'->bufloaded() | |
1070 | |
1071 bufname([{buf}]) *bufname()* | |
1072 The result is the name of a buffer. Mostly as it is displayed | |
1073 by the `:ls` command, but not using special names such as | |
1074 "[No Name]". | |
1075 If {buf} is omitted the current buffer is used. | |
1076 If {buf} is a Number, that buffer number's name is given. | |
1077 Number zero is the alternate buffer for the current window. | |
1078 If {buf} is a String, it is used as a |file-pattern| to match | |
1079 with the buffer names. This is always done like 'magic' is | |
1080 set and 'cpoptions' is empty. When there is more than one | |
1081 match an empty string is returned. | |
1082 "" or "%" can be used for the current buffer, "#" for the | |
1083 alternate buffer. | |
1084 A full match is preferred, otherwise a match at the start, end | |
1085 or middle of the buffer name is accepted. If you only want a | |
1086 full match then put "^" at the start and "$" at the end of the | |
1087 pattern. | |
1088 Listed buffers are found first. If there is a single match | |
1089 with a listed buffer, that one is returned. Next unlisted | |
1090 buffers are searched for. | |
1091 If the {buf} is a String, but you want to use it as a buffer | |
1092 number, force it to be a Number by adding zero to it: > | |
1093 :echo bufname("3" + 0) | |
1094 < Can also be used as a |method|: > | |
1095 echo bufnr->bufname() | |
1096 | |
1097 < If the buffer doesn't exist, or doesn't have a name, an empty | |
1098 string is returned. > | |
1099 bufname("#") alternate buffer name | |
1100 bufname(3) name of buffer 3 | |
1101 bufname("%") name of current buffer | |
1102 bufname("file2") name of buffer where "file2" matches. | |
1103 < *buffer_name()* | |
1104 Obsolete name: buffer_name(). | |
1105 | |
1106 *bufnr()* | |
1107 bufnr([{buf} [, {create}]]) | |
1108 The result is the number of a buffer, as it is displayed by | |
1109 the `:ls` command. For the use of {buf}, see |bufname()| | |
1110 above. | |
1111 | |
1112 If the buffer doesn't exist, -1 is returned. Or, if the | |
1113 {create} argument is present and TRUE, a new, unlisted, | |
1114 buffer is created and its number is returned. Example: > | |
1115 let newbuf = bufnr('Scratch001', 1) | |
1116 < Using an empty name uses the current buffer. To create a new | |
1117 buffer with an empty name use |bufadd()|. | |
1118 | |
1119 bufnr("$") is the last buffer: > | |
1120 :let last_buffer = bufnr("$") | |
1121 < The result is a Number, which is the highest buffer number | |
1122 of existing buffers. Note that not all buffers with a smaller | |
1123 number necessarily exist, because ":bwipeout" may have removed | |
1124 them. Use bufexists() to test for the existence of a buffer. | |
1125 | |
1126 Can also be used as a |method|: > | |
1127 echo bufref->bufnr() | |
1128 < | |
1129 Obsolete name: buffer_number(). *buffer_number()* | |
1130 *last_buffer_nr()* | |
1131 Obsolete name for bufnr("$"): last_buffer_nr(). | |
1132 | |
1133 bufwinid({buf}) *bufwinid()* | |
1134 The result is a Number, which is the |window-ID| of the first | |
1135 window associated with buffer {buf}. For the use of {buf}, | |
1136 see |bufname()| above. If buffer {buf} doesn't exist or | |
1137 there is no such window, -1 is returned. Example: > | |
1138 | |
1139 echo "A window containing buffer 1 is " . (bufwinid(1)) | |
1140 < | |
1141 Only deals with the current tab page. | |
1142 | |
1143 Can also be used as a |method|: > | |
1144 FindBuffer()->bufwinid() | |
1145 | |
1146 bufwinnr({buf}) *bufwinnr()* | |
1147 Like |bufwinid()| but return the window number instead of the | |
1148 |window-ID|. | |
1149 If buffer {buf} doesn't exist or there is no such window, -1 | |
1150 is returned. Example: > | |
1151 | |
1152 echo "A window containing buffer 1 is " . (bufwinnr(1)) | |
1153 | |
1154 < The number can be used with |CTRL-W_w| and ":wincmd w" | |
1155 |:wincmd|. | |
1156 | |
1157 Can also be used as a |method|: > | |
1158 FindBuffer()->bufwinnr() | |
1159 | |
1160 byte2line({byte}) *byte2line()* | |
1161 Return the line number that contains the character at byte | |
1162 count {byte} in the current buffer. This includes the | |
1163 end-of-line character, depending on the 'fileformat' option | |
1164 for the current buffer. The first character has byte count | |
1165 one. | |
1166 Also see |line2byte()|, |go| and |:goto|. | |
1167 | |
1168 Can also be used as a |method|: > | |
1169 GetOffset()->byte2line() | |
1170 | |
1171 < {not available when compiled without the |+byte_offset| | |
1172 feature} | |
1173 | |
1174 byteidx({expr}, {nr}) *byteidx()* | |
1175 Return byte index of the {nr}'th character in the String | |
1176 {expr}. Use zero for the first character, it then returns | |
1177 zero. | |
1178 If there are no multibyte characters the returned value is | |
1179 equal to {nr}. | |
1180 Composing characters are not counted separately, their byte | |
1181 length is added to the preceding base character. See | |
1182 |byteidxcomp()| below for counting composing characters | |
1183 separately. | |
1184 Example : > | |
1185 echo matchstr(str, ".", byteidx(str, 3)) | |
1186 < will display the fourth character. Another way to do the | |
1187 same: > | |
1188 let s = strpart(str, byteidx(str, 3)) | |
1189 echo strpart(s, 0, byteidx(s, 1)) | |
1190 < Also see |strgetchar()| and |strcharpart()|. | |
1191 | |
1192 If there are less than {nr} characters -1 is returned. | |
1193 If there are exactly {nr} characters the length of the string | |
1194 in bytes is returned. | |
1195 | |
1196 Can also be used as a |method|: > | |
1197 GetName()->byteidx(idx) | |
1198 | |
1199 byteidxcomp({expr}, {nr}) *byteidxcomp()* | |
1200 Like byteidx(), except that a composing character is counted | |
1201 as a separate character. Example: > | |
1202 let s = 'e' . nr2char(0x301) | |
1203 echo byteidx(s, 1) | |
1204 echo byteidxcomp(s, 1) | |
1205 echo byteidxcomp(s, 2) | |
1206 < The first and third echo result in 3 ('e' plus composing | |
1207 character is 3 bytes), the second echo results in 1 ('e' is | |
1208 one byte). | |
1209 Only works differently from byteidx() when 'encoding' is set | |
1210 to a Unicode encoding. | |
1211 | |
1212 Can also be used as a |method|: > | |
1213 GetName()->byteidxcomp(idx) | |
1214 | |
1215 call({func}, {arglist} [, {dict}]) *call()* *E699* | |
1216 Call function {func} with the items in |List| {arglist} as | |
1217 arguments. | |
1218 {func} can either be a |Funcref| or the name of a function. | |
1219 a:firstline and a:lastline are set to the cursor line. | |
1220 Returns the return value of the called function. | |
1221 {dict} is for functions with the "dict" attribute. It will be | |
1222 used to set the local variable "self". |Dictionary-function| | |
1223 | |
1224 Can also be used as a |method|: > | |
1225 GetFunc()->call([arg, arg], dict) | |
1226 | |
1227 ceil({expr}) *ceil()* | |
1228 Return the smallest integral value greater than or equal to | |
1229 {expr} as a |Float| (round up). | |
1230 {expr} must evaluate to a |Float| or a |Number|. | |
1231 Examples: > | |
1232 echo ceil(1.456) | |
1233 < 2.0 > | |
1234 echo ceil(-5.456) | |
1235 < -5.0 > | |
1236 echo ceil(4.0) | |
1237 < 4.0 | |
1238 | |
1239 Can also be used as a |method|: > | |
1240 Compute()->ceil() | |
1241 < | |
1242 {only available when compiled with the |+float| feature} | |
1243 | |
1244 | |
1245 ch_ functions are documented here: |channel-functions-details| | |
1246 | |
1247 | |
1248 changenr() *changenr()* | |
1249 Return the number of the most recent change. This is the same | |
1250 number as what is displayed with |:undolist| and can be used | |
1251 with the |:undo| command. | |
1252 When a change was made it is the number of that change. After | |
1253 redo it is the number of the redone change. After undo it is | |
1254 one less than the number of the undone change. | |
1255 | |
1256 char2nr({string} [, {utf8}]) *char2nr()* | |
1257 Return number value of the first char in {string}. | |
1258 Examples: > | |
1259 char2nr(" ") returns 32 | |
1260 char2nr("ABC") returns 65 | |
1261 < When {utf8} is omitted or zero, the current 'encoding' is used. | |
1262 Example for "utf-8": > | |
1263 char2nr("á") returns 225 | |
1264 char2nr("á"[0]) returns 195 | |
1265 < When {utf8} is TRUE, always treat as UTF-8 characters. | |
1266 A combining character is a separate character. | |
1267 |nr2char()| does the opposite. | |
1268 To turn a string into a list of character numbers: > | |
1269 let str = "ABC" | |
1270 let list = map(split(str, '\zs'), {_, val -> char2nr(val)}) | |
1271 < Result: [65, 66, 67] | |
1272 | |
1273 Can also be used as a |method|: > | |
1274 GetChar()->char2nr() | |
1275 | |
1276 | |
1277 charclass({string}) *charclass()* | |
1278 Return the character class of the first character in {string}. | |
1279 The character class is one of: | |
1280 0 blank | |
1281 1 punctuation | |
1282 2 word character | |
1283 3 emoji | |
1284 other specific Unicode class | |
1285 The class is used in patterns and word motions. | |
1286 | |
1287 | |
1288 charcol({expr}) *charcol()* | |
1289 Same as |col()| but returns the character index of the column | |
1290 position given with {expr} instead of the byte position. | |
1291 | |
1292 Example: | |
1293 With the cursor on '세' in line 5 with text "여보세요": > | |
1294 charcol('.') returns 3 | |
1295 col('.') returns 7 | |
1296 | |
1297 < Can also be used as a |method|: > | |
1298 GetPos()->col() | |
1299 < | |
1300 *charidx()* | |
1301 charidx({string}, {idx} [, {countcc}]) | |
1302 Return the character index of the byte at {idx} in {string}. | |
1303 The index of the first character is zero. | |
1304 If there are no multibyte characters the returned value is | |
1305 equal to {idx}. | |
1306 When {countcc} is omitted or |FALSE|, then composing characters | |
1307 are not counted separately, their byte length is | |
1308 added to the preceding base character. | |
1309 When {countcc} is |TRUE|, then composing characters are | |
1310 counted as separate characters. | |
1311 Returns -1 if the arguments are invalid or if {idx} is greater | |
1312 than the index of the last byte in {string}. An error is | |
1313 given if the first argument is not a string, the second | |
1314 argument is not a number or when the third argument is present | |
1315 and is not zero or one. | |
1316 See |byteidx()| and |byteidxcomp()| for getting the byte index | |
1317 from the character index. | |
1318 Examples: > | |
1319 echo charidx('áb́ć', 3) returns 1 | |
1320 echo charidx('áb́ć', 6, 1) returns 4 | |
1321 echo charidx('áb́ć', 16) returns -1 | |
1322 < | |
1323 Can also be used as a |method|: > | |
1324 GetName()->charidx(idx) | |
1325 | |
1326 chdir({dir}) *chdir()* | |
1327 Change the current working directory to {dir}. The scope of | |
1328 the directory change depends on the directory of the current | |
1329 window: | |
1330 - If the current window has a window-local directory | |
1331 (|:lcd|), then changes the window local directory. | |
1332 - Otherwise, if the current tabpage has a local | |
1333 directory (|:tcd|) then changes the tabpage local | |
1334 directory. | |
1335 - Otherwise, changes the global directory. | |
1336 {dir} must be a String. | |
1337 If successful, returns the previous working directory. Pass | |
1338 this to another chdir() to restore the directory. | |
1339 On failure, returns an empty string. | |
1340 | |
1341 Example: > | |
1342 let save_dir = chdir(newdir) | |
1343 if save_dir != "" | |
1344 " ... do some work | |
1345 call chdir(save_dir) | |
1346 endif | |
1347 | |
1348 < Can also be used as a |method|: > | |
1349 GetDir()->chdir() | |
1350 < | |
1351 cindent({lnum}) *cindent()* | |
1352 Get the amount of indent for line {lnum} according the C | |
1353 indenting rules, as with 'cindent'. | |
1354 The indent is counted in spaces, the value of 'tabstop' is | |
1355 relevant. {lnum} is used just like in |getline()|. | |
1356 When {lnum} is invalid or Vim was not compiled the |+cindent| | |
1357 feature, -1 is returned. | |
1358 See |C-indenting|. | |
1359 | |
1360 Can also be used as a |method|: > | |
1361 GetLnum()->cindent() | |
1362 | |
1363 clearmatches([{win}]) *clearmatches()* | |
1364 Clears all matches previously defined for the current window | |
1365 by |matchadd()| and the |:match| commands. | |
1366 If {win} is specified, use the window with this number or | |
1367 window ID instead of the current window. | |
1368 | |
1369 Can also be used as a |method|: > | |
1370 GetWin()->clearmatches() | |
1371 < | |
1372 *col()* | |
1373 col({expr}) The result is a Number, which is the byte index of the column | |
1374 position given with {expr}. The accepted positions are: | |
1375 . the cursor position | |
1376 $ the end of the cursor line (the result is the | |
1377 number of bytes in the cursor line plus one) | |
1378 'x position of mark x (if the mark is not set, 0 is | |
1379 returned) | |
1380 v In Visual mode: the start of the Visual area (the | |
1381 cursor is the end). When not in Visual mode | |
1382 returns the cursor position. Differs from |'<| in | |
1383 that it's updated right away. | |
1384 Additionally {expr} can be [lnum, col]: a |List| with the line | |
1385 and column number. Most useful when the column is "$", to get | |
1386 the last column of a specific line. When "lnum" or "col" is | |
1387 out of range then col() returns zero. | |
1388 To get the line number use |line()|. To get both use | |
1389 |getpos()|. | |
1390 For the screen column position use |virtcol()|. For the | |
1391 character position use |charcol()|. | |
1392 Note that only marks in the current file can be used. | |
1393 Examples: > | |
1394 col(".") column of cursor | |
1395 col("$") length of cursor line plus one | |
1396 col("'t") column of mark t | |
1397 col("'" . markname) column of mark markname | |
1398 < The first column is 1. 0 is returned for an error. | |
1399 For an uppercase mark the column may actually be in another | |
1400 buffer. | |
1401 For the cursor position, when 'virtualedit' is active, the | |
1402 column is one higher if the cursor is after the end of the | |
1403 line. This can be used to obtain the column in Insert mode: > | |
1404 :imap <F2> <C-O>:let save_ve = &ve<CR> | |
1405 \<C-O>:set ve=all<CR> | |
1406 \<C-O>:echo col(".") . "\n" <Bar> | |
1407 \let &ve = save_ve<CR> | |
1408 | |
1409 < Can also be used as a |method|: > | |
1410 GetPos()->col() | |
1411 < | |
1412 | |
1413 complete({startcol}, {matches}) *complete()* *E785* | |
1414 Set the matches for Insert mode completion. | |
1415 Can only be used in Insert mode. You need to use a mapping | |
1416 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O | |
1417 or with an expression mapping. | |
1418 {startcol} is the byte offset in the line where the completed | |
1419 text start. The text up to the cursor is the original text | |
1420 that will be replaced by the matches. Use col('.') for an | |
1421 empty string. "col('.') - 1" will replace one character by a | |
1422 match. | |
1423 {matches} must be a |List|. Each |List| item is one match. | |
1424 See |complete-items| for the kind of items that are possible. | |
1425 "longest" in 'completeopt' is ignored. | |
1426 Note that the after calling this function you need to avoid | |
1427 inserting anything that would cause completion to stop. | |
1428 The match can be selected with CTRL-N and CTRL-P as usual with | |
1429 Insert mode completion. The popup menu will appear if | |
1430 specified, see |ins-completion-menu|. | |
1431 Example: > | |
1432 inoremap <F5> <C-R>=ListMonths()<CR> | |
1433 | |
1434 func! ListMonths() | |
1435 call complete(col('.'), ['January', 'February', 'March', | |
1436 \ 'April', 'May', 'June', 'July', 'August', 'September', | |
1437 \ 'October', 'November', 'December']) | |
1438 return '' | |
1439 endfunc | |
1440 < This isn't very useful, but it shows how it works. Note that | |
1441 an empty string is returned to avoid a zero being inserted. | |
1442 | |
1443 Can also be used as a |method|, the base is passed as the | |
1444 second argument: > | |
1445 GetMatches()->complete(col('.')) | |
1446 | |
1447 complete_add({expr}) *complete_add()* | |
1448 Add {expr} to the list of matches. Only to be used by the | |
1449 function specified with the 'completefunc' option. | |
1450 Returns 0 for failure (empty string or out of memory), | |
1451 1 when the match was added, 2 when the match was already in | |
1452 the list. | |
1453 See |complete-functions| for an explanation of {expr}. It is | |
1454 the same as one item in the list that 'omnifunc' would return. | |
1455 | |
1456 Can also be used as a |method|: > | |
1457 GetMoreMatches()->complete_add() | |
1458 | |
1459 complete_check() *complete_check()* | |
1460 Check for a key typed while looking for completion matches. | |
1461 This is to be used when looking for matches takes some time. | |
1462 Returns |TRUE| when searching for matches is to be aborted, | |
1463 zero otherwise. | |
1464 Only to be used by the function specified with the | |
1465 'completefunc' option. | |
1466 | |
1467 | |
1468 complete_info([{what}]) *complete_info()* | |
1469 Returns a |Dictionary| with information about Insert mode | |
1470 completion. See |ins-completion|. | |
1471 The items are: | |
1472 mode Current completion mode name string. | |
1473 See |complete_info_mode| for the values. | |
1474 pum_visible |TRUE| if popup menu is visible. | |
1475 See |pumvisible()|. | |
1476 items List of completion matches. Each item is a | |
1477 dictionary containing the entries "word", | |
1478 "abbr", "menu", "kind", "info" and "user_data". | |
1479 See |complete-items|. | |
1480 selected Selected item index. First index is zero. | |
1481 Index is -1 if no item is selected (showing | |
1482 typed text only, or the last completion after | |
1483 no item is selected when using the <Up> or | |
1484 <Down> keys) | |
1485 inserted Inserted string. [NOT IMPLEMENT YET] | |
1486 | |
1487 *complete_info_mode* | |
1488 mode values are: | |
1489 "" Not in completion mode | |
1490 "keyword" Keyword completion |i_CTRL-X_CTRL-N| | |
1491 "ctrl_x" Just pressed CTRL-X |i_CTRL-X| | |
1492 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or | |
1493 |i_CTRL-X_CTRL-Y| | |
1494 "whole_line" Whole lines |i_CTRL-X_CTRL-L| | |
1495 "files" File names |i_CTRL-X_CTRL-F| | |
1496 "tags" Tags |i_CTRL-X_CTRL-]| | |
1497 "path_defines" Definition completion |i_CTRL-X_CTRL-D| | |
1498 "path_patterns" Include completion |i_CTRL-X_CTRL-I| | |
1499 "dictionary" Dictionary |i_CTRL-X_CTRL-K| | |
1500 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| | |
1501 "cmdline" Vim Command line |i_CTRL-X_CTRL-V| | |
1502 "function" User defined completion |i_CTRL-X_CTRL-U| | |
1503 "omni" Omni completion |i_CTRL-X_CTRL-O| | |
1504 "spell" Spelling suggestions |i_CTRL-X_s| | |
1505 "eval" |complete()| completion | |
1506 "unknown" Other internal modes | |
1507 | |
1508 If the optional {what} list argument is supplied, then only | |
1509 the items listed in {what} are returned. Unsupported items in | |
1510 {what} are silently ignored. | |
1511 | |
1512 To get the position and size of the popup menu, see | |
1513 |pum_getpos()|. It's also available in |v:event| during the | |
1514 |CompleteChanged| event. | |
1515 | |
1516 Examples: > | |
1517 " Get all items | |
1518 call complete_info() | |
1519 " Get only 'mode' | |
1520 call complete_info(['mode']) | |
1521 " Get only 'mode' and 'pum_visible' | |
1522 call complete_info(['mode', 'pum_visible']) | |
1523 | |
1524 < Can also be used as a |method|: > | |
1525 GetItems()->complete_info() | |
1526 < | |
1527 *confirm()* | |
1528 confirm({msg} [, {choices} [, {default} [, {type}]]]) | |
1529 confirm() offers the user a dialog, from which a choice can be | |
1530 made. It returns the number of the choice. For the first | |
1531 choice this is 1. | |
1532 Note: confirm() is only supported when compiled with dialog | |
1533 support, see |+dialog_con| and |+dialog_gui|. | |
1534 | |
1535 {msg} is displayed in a |dialog| with {choices} as the | |
1536 alternatives. When {choices} is missing or empty, "&OK" is | |
1537 used (and translated). | |
1538 {msg} is a String, use '\n' to include a newline. Only on | |
1539 some systems the string is wrapped when it doesn't fit. | |
1540 | |
1541 {choices} is a String, with the individual choices separated | |
1542 by '\n', e.g. > | |
1543 confirm("Save changes?", "&Yes\n&No\n&Cancel") | |
1544 < The letter after the '&' is the shortcut key for that choice. | |
1545 Thus you can type 'c' to select "Cancel". The shortcut does | |
1546 not need to be the first letter: > | |
1547 confirm("file has been modified", "&Save\nSave &All") | |
1548 < For the console, the first letter of each choice is used as | |
1549 the default shortcut key. Case is ignored. | |
1550 | |
1551 The optional {default} argument is the number of the choice | |
1552 that is made if the user hits <CR>. Use 1 to make the first | |
1553 choice the default one. Use 0 to not set a default. If | |
1554 {default} is omitted, 1 is used. | |
1555 | |
1556 The optional {type} String argument gives the type of dialog. | |
1557 This is only used for the icon of the GTK, Mac, Motif and | |
1558 Win32 GUI. It can be one of these values: "Error", | |
1559 "Question", "Info", "Warning" or "Generic". Only the first | |
1560 character is relevant. When {type} is omitted, "Generic" is | |
1561 used. | |
1562 | |
1563 If the user aborts the dialog by pressing <Esc>, CTRL-C, | |
1564 or another valid interrupt key, confirm() returns 0. | |
1565 | |
1566 An example: > | |
1567 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2) | |
1568 :if choice == 0 | |
1569 : echo "make up your mind!" | |
1570 :elseif choice == 3 | |
1571 : echo "tasteful" | |
1572 :else | |
1573 : echo "I prefer bananas myself." | |
1574 :endif | |
1575 < In a GUI dialog, buttons are used. The layout of the buttons | |
1576 depends on the 'v' flag in 'guioptions'. If it is included, | |
1577 the buttons are always put vertically. Otherwise, confirm() | |
1578 tries to put the buttons in one horizontal line. If they | |
1579 don't fit, a vertical layout is used anyway. For some systems | |
1580 the horizontal layout is always used. | |
1581 | |
1582 Can also be used as a |method|in: > | |
1583 BuildMessage()->confirm("&Yes\n&No") | |
1584 < | |
1585 *copy()* | |
1586 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't | |
1587 different from using {expr} directly. | |
1588 When {expr} is a |List| a shallow copy is created. This means | |
1589 that the original |List| can be changed without changing the | |
1590 copy, and vice versa. But the items are identical, thus | |
1591 changing an item changes the contents of both |Lists|. | |
1592 A |Dictionary| is copied in a similar way as a |List|. | |
1593 Also see |deepcopy()|. | |
1594 Can also be used as a |method|: > | |
1595 mylist->copy() | |
1596 | |
1597 cos({expr}) *cos()* | |
1598 Return the cosine of {expr}, measured in radians, as a |Float|. | |
1599 {expr} must evaluate to a |Float| or a |Number|. | |
1600 Examples: > | |
1601 :echo cos(100) | |
1602 < 0.862319 > | |
1603 :echo cos(-4.01) | |
1604 < -0.646043 | |
1605 | |
1606 Can also be used as a |method|: > | |
1607 Compute()->cos() | |
1608 < | |
1609 {only available when compiled with the |+float| feature} | |
1610 | |
1611 | |
1612 cosh({expr}) *cosh()* | |
1613 Return the hyperbolic cosine of {expr} as a |Float| in the range | |
1614 [1, inf]. | |
1615 {expr} must evaluate to a |Float| or a |Number|. | |
1616 Examples: > | |
1617 :echo cosh(0.5) | |
1618 < 1.127626 > | |
1619 :echo cosh(-0.5) | |
1620 < -1.127626 | |
1621 | |
1622 Can also be used as a |method|: > | |
1623 Compute()->cosh() | |
1624 < | |
1625 {only available when compiled with the |+float| feature} | |
1626 | |
1627 | |
1628 count({comp}, {expr} [, {ic} [, {start}]]) *count()* | |
1629 Return the number of times an item with value {expr} appears | |
1630 in |String|, |List| or |Dictionary| {comp}. | |
1631 | |
1632 If {start} is given then start with the item with this index. | |
1633 {start} can only be used with a |List|. | |
1634 | |
1635 When {ic} is given and it's |TRUE| then case is ignored. | |
1636 | |
1637 When {comp} is a string then the number of not overlapping | |
1638 occurrences of {expr} is returned. Zero is returned when | |
1639 {expr} is an empty string. | |
1640 | |
1641 Can also be used as a |method|: > | |
1642 mylist->count(val) | |
1643 < | |
1644 *cscope_connection()* | |
1645 cscope_connection([{num} , {dbpath} [, {prepend}]]) | |
1646 Checks for the existence of a |cscope| connection. If no | |
1647 parameters are specified, then the function returns: | |
1648 0, if cscope was not available (not compiled in), or | |
1649 if there are no cscope connections; | |
1650 1, if there is at least one cscope connection. | |
1651 | |
1652 If parameters are specified, then the value of {num} | |
1653 determines how existence of a cscope connection is checked: | |
1654 | |
1655 {num} Description of existence check | |
1656 ----- ------------------------------ | |
1657 0 Same as no parameters (e.g., "cscope_connection()"). | |
1658 1 Ignore {prepend}, and use partial string matches for | |
1659 {dbpath}. | |
1660 2 Ignore {prepend}, and use exact string matches for | |
1661 {dbpath}. | |
1662 3 Use {prepend}, use partial string matches for both | |
1663 {dbpath} and {prepend}. | |
1664 4 Use {prepend}, use exact string matches for both | |
1665 {dbpath} and {prepend}. | |
1666 | |
1667 Note: All string comparisons are case sensitive! | |
1668 | |
1669 Examples. Suppose we had the following (from ":cs show"): > | |
1670 | |
1671 # pid database name prepend path | |
1672 0 27664 cscope.out /usr/local | |
1673 < | |
1674 Invocation Return Val ~ | |
1675 ---------- ---------- > | |
1676 cscope_connection() 1 | |
1677 cscope_connection(1, "out") 1 | |
1678 cscope_connection(2, "out") 0 | |
1679 cscope_connection(3, "out") 0 | |
1680 cscope_connection(3, "out", "local") 1 | |
1681 cscope_connection(4, "out") 0 | |
1682 cscope_connection(4, "out", "local") 0 | |
1683 cscope_connection(4, "cscope.out", "/usr/local") 1 | |
1684 < | |
1685 cursor({lnum}, {col} [, {off}]) *cursor()* | |
1686 cursor({list}) | |
1687 Positions the cursor at the column (byte count) {col} in the | |
1688 line {lnum}. The first column is one. | |
1689 | |
1690 When there is one argument {list} this is used as a |List| | |
1691 with two, three or four item: | |
1692 [{lnum}, {col}] | |
1693 [{lnum}, {col}, {off}] | |
1694 [{lnum}, {col}, {off}, {curswant}] | |
1695 This is like the return value of |getpos()| or |getcurpos()|, | |
1696 but without the first item. | |
1697 | |
1698 To position the cursor using the character count, use | |
1699 |setcursorcharpos()|. | |
1700 | |
1701 Does not change the jumplist. | |
1702 {lnum} is used like with |getline()|. | |
1703 If {lnum} is greater than the number of lines in the buffer, | |
1704 the cursor will be positioned at the last line in the buffer. | |
1705 If {lnum} is zero, the cursor will stay in the current line. | |
1706 If {col} is greater than the number of bytes in the line, | |
1707 the cursor will be positioned at the last character in the | |
1708 line. | |
1709 If {col} is zero, the cursor will stay in the current column. | |
1710 If {curswant} is given it is used to set the preferred column | |
1711 for vertical movement. Otherwise {col} is used. | |
1712 | |
1713 When 'virtualedit' is used {off} specifies the offset in | |
1714 screen columns from the start of the character. E.g., a | |
1715 position within a <Tab> or after the last character. | |
1716 Returns 0 when the position could be set, -1 otherwise. | |
1717 | |
1718 Can also be used as a |method|: > | |
1719 GetCursorPos()->cursor() | |
1720 | |
1721 debugbreak({pid}) *debugbreak()* | |
1722 Specifically used to interrupt a program being debugged. It | |
1723 will cause process {pid} to get a SIGTRAP. Behavior for other | |
1724 processes is undefined. See |terminal-debugger|. | |
1725 {only available on MS-Windows} | |
1726 | |
1727 Can also be used as a |method|: > | |
1728 GetPid()->debugbreak() | |
1729 | |
1730 deepcopy({expr} [, {noref}]) *deepcopy()* *E698* | |
1731 Make a copy of {expr}. For Numbers and Strings this isn't | |
1732 different from using {expr} directly. | |
1733 When {expr} is a |List| a full copy is created. This means | |
1734 that the original |List| can be changed without changing the | |
1735 copy, and vice versa. When an item is a |List| or | |
1736 |Dictionary|, a copy for it is made, recursively. Thus | |
1737 changing an item in the copy does not change the contents of | |
1738 the original |List|. | |
1739 A |Dictionary| is copied in a similar way as a |List|. | |
1740 | |
1741 When {noref} is omitted or zero a contained |List| or | |
1742 |Dictionary| is only copied once. All references point to | |
1743 this single copy. With {noref} set to 1 every occurrence of a | |
1744 |List| or |Dictionary| results in a new copy. This also means | |
1745 that a cyclic reference causes deepcopy() to fail. | |
1746 *E724* | |
1747 Nesting is possible up to 100 levels. When there is an item | |
1748 that refers back to a higher level making a deep copy with | |
1749 {noref} set to 1 will fail. | |
1750 Also see |copy()|. | |
1751 | |
1752 Can also be used as a |method|: > | |
1753 GetObject()->deepcopy() | |
1754 | |
1755 delete({fname} [, {flags}]) *delete()* | |
1756 Without {flags} or with {flags} empty: Deletes the file by the | |
1757 name {fname}. This also works when {fname} is a symbolic link. | |
1758 | |
1759 When {flags} is "d": Deletes the directory by the name | |
1760 {fname}. This fails when directory {fname} is not empty. | |
1761 | |
1762 When {flags} is "rf": Deletes the directory by the name | |
1763 {fname} and everything in it, recursively. BE CAREFUL! | |
1764 Note: on MS-Windows it is not possible to delete a directory | |
1765 that is being used. | |
1766 | |
1767 A symbolic link itself is deleted, not what it points to. | |
1768 | |
1769 The result is a Number, which is 0/false if the delete | |
1770 operation was successful and -1/true when the deletion failed | |
1771 or partly failed. | |
1772 | |
1773 Use |remove()| to delete an item from a |List|. | |
1774 To delete a line from the buffer use |:delete| or | |
1775 |deletebufline()|. | |
1776 | |
1777 Can also be used as a |method|: > | |
1778 GetName()->delete() | |
1779 | |
1780 deletebufline({buf}, {first} [, {last}]) *deletebufline()* | |
1781 Delete lines {first} to {last} (inclusive) from buffer {buf}. | |
1782 If {last} is omitted then delete line {first} only. | |
1783 On success 0 is returned, on failure 1 is returned. | |
1784 | |
1785 This function works only for loaded buffers. First call | |
1786 |bufload()| if needed. | |
1787 | |
1788 For the use of {buf}, see |bufname()| above. | |
1789 | |
1790 {first} and {last} are used like with |getline()|. Note that | |
1791 when using |line()| this refers to the current buffer. Use "$" | |
1792 to refer to the last line in buffer {buf}. | |
1793 | |
1794 Can also be used as a |method|: > | |
1795 GetBuffer()->deletebufline(1) | |
1796 < | |
1797 *did_filetype()* | |
1798 did_filetype() Returns |TRUE| when autocommands are being executed and the | |
1799 FileType event has been triggered at least once. Can be used | |
1800 to avoid triggering the FileType event again in the scripts | |
1801 that detect the file type. |FileType| | |
1802 Returns |FALSE| when `:setf FALLBACK` was used. | |
1803 When editing another file, the counter is reset, thus this | |
1804 really checks if the FileType event has been triggered for the | |
1805 current buffer. This allows an autocommand that starts | |
1806 editing another buffer to set 'filetype' and load a syntax | |
1807 file. | |
1808 | |
1809 diff_filler({lnum}) *diff_filler()* | |
1810 Returns the number of filler lines above line {lnum}. | |
1811 These are the lines that were inserted at this point in | |
1812 another diff'ed window. These filler lines are shown in the | |
1813 display but don't exist in the buffer. | |
1814 {lnum} is used like with |getline()|. Thus "." is the current | |
1815 line, "'m" mark m, etc. | |
1816 Returns 0 if the current window is not in diff mode. | |
1817 | |
1818 Can also be used as a |method|: > | |
1819 GetLnum()->diff_filler() | |
1820 | |
1821 diff_hlID({lnum}, {col}) *diff_hlID()* | |
1822 Returns the highlight ID for diff mode at line {lnum} column | |
1823 {col} (byte index). When the current line does not have a | |
1824 diff change zero is returned. | |
1825 {lnum} is used like with |getline()|. Thus "." is the current | |
1826 line, "'m" mark m, etc. | |
1827 {col} is 1 for the leftmost column, {lnum} is 1 for the first | |
1828 line. | |
1829 The highlight ID can be used with |synIDattr()| to obtain | |
1830 syntax information about the highlighting. | |
1831 | |
1832 Can also be used as a |method|: > | |
1833 GetLnum()->diff_hlID(col) | |
1834 < | |
1835 | |
1836 digraph_get({chars}) *digraph_get()* *E1214* | |
1837 Return the digraph of {chars}. This should be a string with | |
1838 exactly two characters. If {chars} are not just two | |
1839 characters, or the digraph of {chars} does not exist, an error | |
1840 is given and an empty string is returned. | |
1841 | |
1842 The character will be converted from Unicode to 'encoding' | |
1843 when needed. This does require the conversion to be | |
1844 available, it might fail. | |
1845 | |
1846 Also see |digraph_getlist()|. | |
1847 | |
1848 Examples: > | |
1849 " Get a built-in digraph | |
1850 :echo digraph_get('00') " Returns '∞' | |
1851 | |
1852 " Get a user-defined digraph | |
1853 :call digraph_set('aa', 'あ') | |
1854 :echo digraph_get('aa') " Returns 'あ' | |
1855 < | |
1856 Can also be used as a |method|: > | |
1857 GetChars()->digraph_get() | |
1858 < | |
1859 This function works only when compiled with the |+digraphs| | |
1860 feature. If this feature is disabled, this function will | |
1861 display an error message. | |
1862 | |
1863 | |
1864 digraph_getlist([{listall}]) *digraph_getlist()* | |
1865 Return a list of digraphs. If the {listall} argument is given | |
1866 and it is TRUE, return all digraphs, including the default | |
1867 digraphs. Otherwise, return only user-defined digraphs. | |
1868 | |
1869 The characters will be converted from Unicode to 'encoding' | |
1870 when needed. This does require the conservation to be | |
1871 available, it might fail. | |
1872 | |
1873 Also see |digraph_get()|. | |
1874 | |
1875 Examples: > | |
1876 " Get user-defined digraphs | |
1877 :echo digraph_getlist() | |
1878 | |
1879 " Get all the digraphs, including default digraphs | |
1880 :echo digraph_getlist(1) | |
1881 < | |
1882 Can also be used as a |method|: > | |
1883 GetNumber()->digraph_getlist() | |
1884 < | |
1885 This function works only when compiled with the |+digraphs| | |
1886 feature. If this feature is disabled, this function will | |
1887 display an error message. | |
1888 | |
1889 | |
1890 digraph_set({chars}, {digraph}) *digraph_set()* *E1205* | |
1891 Add digraph {chars} to the list. {chars} must be a string | |
1892 with two characters. {digraph} is a string with one UTF-8 | |
1893 encoded character. Be careful, composing characters are NOT | |
1894 ignored. This function is similar to |:digraphs| command, but | |
1895 useful to add digraphs start with a white space. | |
1896 | |
1897 The function result is v:true if |digraph| is registered. If | |
1898 this fails an error message is given and v:false is returned. | |
1899 | |
1900 If you want to define multiple digraphs at once, you can use | |
1901 |digraph_setlist()|. | |
1902 | |
1903 Example: > | |
1904 call digraph_set(' ', 'あ') | |
1905 < | |
1906 Can be used as a |method|: > | |
1907 GetString()->digraph_set('あ') | |
1908 < | |
1909 This function works only when compiled with the |+digraphs| | |
1910 feature. If this feature is disabled, this function will | |
1911 display an error message. | |
1912 | |
1913 | |
1914 digraph_setlist({digraphlist}) *digraph_setlist()* | |
1915 Similar to |digraph_set()| but this function can add multiple | |
1916 digraphs at once. {digraphlist} is a list composed of lists, | |
1917 where each list contains two strings with {chars} and | |
1918 {digraph} as in |digraph_set()|. | |
1919 Example: > | |
1920 call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) | |
1921 < | |
1922 It is similar to the following: > | |
1923 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] | |
1924 call digraph_set(chars, digraph) | |
1925 endfor | |
1926 < Except that the function returns after the first error, | |
1927 following digraphs will not be added. | |
1928 | |
1929 Can be used as a |method|: > | |
1930 GetList()->digraph_setlist() | |
1931 < | |
1932 This function works only when compiled with the |+digraphs| | |
1933 feature. If this feature is disabled, this function will | |
1934 display an error message. | |
1935 | |
1936 | |
1937 echoraw({string}) *echoraw()* | |
1938 Output {string} as-is, including unprintable characters. | |
1939 This can be used to output a terminal code. For example, to | |
1940 disable modifyOtherKeys: > | |
1941 call echoraw(&t_TE) | |
1942 < and to enable it again: > | |
1943 call echoraw(&t_TI) | |
1944 < Use with care, you can mess up the terminal this way. | |
1945 | |
1946 | |
1947 empty({expr}) *empty()* | |
1948 Return the Number 1 if {expr} is empty, zero otherwise. | |
1949 - A |List| or |Dictionary| is empty when it does not have any | |
1950 items. | |
1951 - A |String| is empty when its length is zero. | |
1952 - A |Number| and |Float| are empty when their value is zero. | |
1953 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. | |
1954 - A |Job| is empty when it failed to start. | |
1955 - A |Channel| is empty when it is closed. | |
1956 - A |Blob| is empty when its length is zero. | |
1957 | |
1958 For a long |List| this is much faster than comparing the | |
1959 length with zero. | |
1960 | |
1961 Can also be used as a |method|: > | |
1962 mylist->empty() | |
1963 | |
1964 environ() *environ()* | |
1965 Return all of environment variables as dictionary. You can | |
1966 check if an environment variable exists like this: > | |
1967 :echo has_key(environ(), 'HOME') | |
1968 < Note that the variable name may be CamelCase; to ignore case | |
1969 use this: > | |
1970 :echo index(keys(environ()), 'HOME', 0, 1) != -1 | |
1971 | |
1972 escape({string}, {chars}) *escape()* | |
1973 Escape the characters in {chars} that occur in {string} with a | |
1974 backslash. Example: > | |
1975 :echo escape('c:\program files\vim', ' \') | |
1976 < results in: > | |
1977 c:\\program\ files\\vim | |
1978 < Also see |shellescape()| and |fnameescape()|. | |
1979 | |
1980 Can also be used as a |method|: > | |
1981 GetText()->escape(' \') | |
1982 < | |
1983 *eval()* | |
1984 eval({string}) Evaluate {string} and return the result. Especially useful to | |
1985 turn the result of |string()| back into the original value. | |
1986 This works for Numbers, Floats, Strings, Blobs and composites | |
1987 of them. Also works for |Funcref|s that refer to existing | |
1988 functions. | |
1989 | |
1990 Can also be used as a |method|: > | |
1991 argv->join()->eval() | |
1992 | |
1993 eventhandler() *eventhandler()* | |
1994 Returns 1 when inside an event handler. That is that Vim got | |
1995 interrupted while waiting for the user to type a character, | |
1996 e.g., when dropping a file on Vim. This means interactive | |
1997 commands cannot be used. Otherwise zero is returned. | |
1998 | |
1999 executable({expr}) *executable()* | |
2000 This function checks if an executable with the name {expr} | |
2001 exists. {expr} must be the name of the program without any | |
2002 arguments. | |
2003 executable() uses the value of $PATH and/or the normal | |
2004 searchpath for programs. *PATHEXT* | |
2005 On MS-Windows the ".exe", ".bat", etc. can optionally be | |
2006 included. Then the extensions in $PATHEXT are tried. Thus if | |
2007 "foo.exe" does not exist, "foo.exe.bat" can be found. If | |
2008 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot | |
2009 by itself can be used in $PATHEXT to try using the name | |
2010 without an extension. When 'shell' looks like a Unix shell, | |
2011 then the name is also tried without adding an extension. | |
2012 On MS-Windows it only checks if the file exists and is not a | |
2013 directory, not if it's really executable. | |
2014 On MS-Windows an executable in the same directory as Vim is | |
2015 always found. Since this directory is added to $PATH it | |
2016 should also work to execute it |win32-PATH|. | |
2017 The result is a Number: | |
2018 1 exists | |
2019 0 does not exist | |
2020 -1 not implemented on this system | |
2021 |exepath()| can be used to get the full path of an executable. | |
2022 | |
2023 Can also be used as a |method|: > | |
2024 GetCommand()->executable() | |
2025 | |
2026 execute({command} [, {silent}]) *execute()* | |
2027 Execute an Ex command or commands and return the output as a | |
2028 string. | |
2029 {command} can be a string or a List. In case of a List the | |
2030 lines are executed one by one. | |
2031 This is equivalent to: > | |
2032 redir => var | |
2033 {command} | |
2034 redir END | |
2035 < | |
2036 The optional {silent} argument can have these values: | |
2037 "" no `:silent` used | |
2038 "silent" `:silent` used | |
2039 "silent!" `:silent!` used | |
2040 The default is "silent". Note that with "silent!", unlike | |
2041 `:redir`, error messages are dropped. When using an external | |
2042 command the screen may be messed up, use `system()` instead. | |
2043 *E930* | |
2044 It is not possible to use `:redir` anywhere in {command}. | |
2045 | |
2046 To get a list of lines use |split()| on the result: > | |
2047 split(execute('args'), "\n") | |
2048 | |
2049 < To execute a command in another window than the current one | |
2050 use `win_execute()`. | |
2051 | |
2052 When used recursively the output of the recursive call is not | |
2053 included in the output of the higher level call. | |
2054 | |
2055 Can also be used as a |method|: > | |
2056 GetCommand()->execute() | |
2057 | |
2058 exepath({expr}) *exepath()* | |
2059 If {expr} is an executable and is either an absolute path, a | |
2060 relative path or found in $PATH, return the full path. | |
2061 Note that the current directory is used when {expr} starts | |
2062 with "./", which may be a problem for Vim: > | |
2063 echo exepath(v:progpath) | |
2064 < If {expr} cannot be found in $PATH or is not executable then | |
2065 an empty string is returned. | |
2066 | |
2067 Can also be used as a |method|: > | |
2068 GetCommand()->exepath() | |
2069 < | |
2070 *exists()* | |
2071 exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, | |
2072 zero otherwise. | |
2073 | |
2074 Note: In a compiled |:def| function the evaluation is done at | |
2075 runtime. Use `exists_compiled()` to evaluate the expression | |
2076 at compile time. | |
2077 | |
2078 For checking for a supported feature use |has()|. | |
2079 For checking if a file exists use |filereadable()|. | |
2080 | |
2081 The {expr} argument is a string, which contains one of these: | |
2082 &option-name Vim option (only checks if it exists, | |
2083 not if it really works) | |
2084 +option-name Vim option that works. | |
2085 $ENVNAME environment variable (could also be | |
2086 done by comparing with an empty | |
2087 string) | |
2088 *funcname built-in function (see |functions|) | |
2089 or user defined function (see | |
2090 |user-functions|) that is implemented. | |
2091 Also works for a variable that is a | |
2092 Funcref. | |
2093 ?funcname built-in function that could be | |
2094 implemented; to be used to check if | |
2095 "funcname" is valid | |
2096 varname internal variable (see | |
2097 |internal-variables|). Also works | |
2098 for |curly-braces-names|, |Dictionary| | |
2099 entries, |List| items, etc. | |
2100 Does not work for local variables in a | |
2101 compiled `:def` function. | |
2102 Beware that evaluating an index may | |
2103 cause an error message for an invalid | |
2104 expression. E.g.: > | |
2105 :let l = [1, 2, 3] | |
2106 :echo exists("l[5]") | |
2107 < 0 > | |
2108 :echo exists("l[xx]") | |
2109 < E121: Undefined variable: xx | |
2110 0 | |
2111 :cmdname Ex command: built-in command, user | |
2112 command or command modifier |:command|. | |
2113 Returns: | |
2114 1 for match with start of a command | |
2115 2 full match with a command | |
2116 3 matches several user commands | |
2117 To check for a supported command | |
2118 always check the return value to be 2. | |
2119 :2match The |:2match| command. | |
2120 :3match The |:3match| command. | |
2121 #event autocommand defined for this event | |
2122 #event#pattern autocommand defined for this event and | |
2123 pattern (the pattern is taken | |
2124 literally and compared to the | |
2125 autocommand patterns character by | |
2126 character) | |
2127 #group autocommand group exists | |
2128 #group#event autocommand defined for this group and | |
2129 event. | |
2130 #group#event#pattern | |
2131 autocommand defined for this group, | |
2132 event and pattern. | |
2133 ##event autocommand for this event is | |
2134 supported. | |
2135 | |
2136 Examples: > | |
2137 exists("&shortname") | |
2138 exists("$HOSTNAME") | |
2139 exists("*strftime") | |
2140 exists("*s:MyFunc") | |
2141 exists("bufcount") | |
2142 exists(":Make") | |
2143 exists("#CursorHold") | |
2144 exists("#BufReadPre#*.gz") | |
2145 exists("#filetypeindent") | |
2146 exists("#filetypeindent#FileType") | |
2147 exists("#filetypeindent#FileType#*") | |
2148 exists("##ColorScheme") | |
2149 < There must be no space between the symbol (&/$/*/#) and the | |
2150 name. | |
2151 There must be no extra characters after the name, although in | |
2152 a few cases this is ignored. That may become more strict in | |
2153 the future, thus don't count on it! | |
2154 Working example: > | |
2155 exists(":make") | |
2156 < NOT working example: > | |
2157 exists(":make install") | |
2158 | |
2159 < Note that the argument must be a string, not the name of the | |
2160 variable itself. For example: > | |
2161 exists(bufcount) | |
2162 < This doesn't check for existence of the "bufcount" variable, | |
2163 but gets the value of "bufcount", and checks if that exists. | |
2164 | |
2165 Can also be used as a |method|: > | |
2166 Varname()->exists() | |
2167 < | |
2168 | |
2169 exists_compiled({expr}) *exists_compiled()* | |
2170 Like `exists()` but evaluated at compile time. This is useful | |
2171 to skip a block where a function is used that would otherwise | |
2172 give an error: > | |
2173 if exists_compiled('*ThatFunction') | |
2174 ThatFunction('works') | |
2175 endif | |
2176 < If `exists()` were used then a compilation error would be | |
2177 given if ThatFunction() is not defined. | |
2178 | |
2179 {expr} must be a literal string. *E1232* | |
2180 Can only be used in a |:def| function. *E1233* | |
2181 This does not work to check for arguments or local variables. | |
2182 | |
2183 | |
2184 exp({expr}) *exp()* | |
2185 Return the exponential of {expr} as a |Float| in the range | |
2186 [0, inf]. | |
2187 {expr} must evaluate to a |Float| or a |Number|. | |
2188 Examples: > | |
2189 :echo exp(2) | |
2190 < 7.389056 > | |
2191 :echo exp(-1) | |
2192 < 0.367879 | |
2193 | |
2194 Can also be used as a |method|: > | |
2195 Compute()->exp() | |
2196 < | |
2197 {only available when compiled with the |+float| feature} | |
2198 | |
2199 | |
2200 expand({string} [, {nosuf} [, {list}]]) *expand()* | |
2201 Expand wildcards and the following special keywords in | |
2202 {string}. 'wildignorecase' applies. | |
2203 | |
2204 If {list} is given and it is |TRUE|, a List will be returned. | |
2205 Otherwise the result is a String and when there are several | |
2206 matches, they are separated by <NL> characters. [Note: in | |
2207 version 5.0 a space was used, which caused problems when a | |
2208 file name contains a space] | |
2209 | |
2210 If the expansion fails, the result is an empty string. A name | |
2211 for a non-existing file is not included, unless {string} does | |
2212 not start with '%', '#' or '<', see below. | |
2213 | |
2214 When {string} starts with '%', '#' or '<', the expansion is | |
2215 done like for the |cmdline-special| variables with their | |
2216 associated modifiers. Here is a short overview: | |
2217 | |
2218 % current file name | |
2219 # alternate file name | |
2220 #n alternate file name n | |
2221 <cfile> file name under the cursor | |
2222 <afile> autocmd file name | |
2223 <abuf> autocmd buffer number (as a String!) | |
2224 <amatch> autocmd matched name | |
2225 <cexpr> C expression under the cursor | |
2226 <sfile> sourced script file or function name | |
2227 <slnum> sourced script line number or function | |
2228 line number | |
2229 <sflnum> script file line number, also when in | |
2230 a function | |
2231 <SID> "<SNR>123_" where "123" is the | |
2232 current script ID |<SID>| | |
2233 <stack> call stack | |
2234 <cword> word under the cursor | |
2235 <cWORD> WORD under the cursor | |
2236 <client> the {clientid} of the last received | |
2237 message |server2client()| | |
2238 Modifiers: | |
2239 :p expand to full path | |
2240 :h head (last path component removed) | |
2241 :t tail (last path component only) | |
2242 :r root (one extension removed) | |
2243 :e extension only | |
2244 | |
2245 Example: > | |
2246 :let &tags = expand("%:p:h") . "/tags" | |
2247 < Note that when expanding a string that starts with '%', '#' or | |
2248 '<', any following text is ignored. This does NOT work: > | |
2249 :let doesntwork = expand("%:h.bak") | |
2250 < Use this: > | |
2251 :let doeswork = expand("%:h") . ".bak" | |
2252 < Also note that expanding "<cfile>" and others only returns the | |
2253 referenced file name without further expansion. If "<cfile>" | |
2254 is "~/.cshrc", you need to do another expand() to have the | |
2255 "~/" expanded into the path of the home directory: > | |
2256 :echo expand(expand("<cfile>")) | |
2257 < | |
2258 There cannot be white space between the variables and the | |
2259 following modifier. The |fnamemodify()| function can be used | |
2260 to modify normal file names. | |
2261 | |
2262 When using '%' or '#', and the current or alternate file name | |
2263 is not defined, an empty string is used. Using "%:p" in a | |
2264 buffer with no name, results in the current directory, with a | |
2265 '/' added. | |
2266 | |
2267 When {string} does not start with '%', '#' or '<', it is | |
2268 expanded like a file name is expanded on the command line. | |
2269 'suffixes' and 'wildignore' are used, unless the optional | |
2270 {nosuf} argument is given and it is |TRUE|. | |
2271 Names for non-existing files are included. The "**" item can | |
2272 be used to search in a directory tree. For example, to find | |
2273 all "README" files in the current directory and below: > | |
2274 :echo expand("**/README") | |
2275 < | |
2276 expand() can also be used to expand variables and environment | |
2277 variables that are only known in a shell. But this can be | |
2278 slow, because a shell may be used to do the expansion. See | |
2279 |expr-env-expand|. | |
2280 The expanded variable is still handled like a list of file | |
2281 names. When an environment variable cannot be expanded, it is | |
2282 left unchanged. Thus ":echo expand('$FOOBAR')" results in | |
2283 "$FOOBAR". | |
2284 | |
2285 See |glob()| for finding existing files. See |system()| for | |
2286 getting the raw output of an external command. | |
2287 | |
2288 Can also be used as a |method|: > | |
2289 Getpattern()->expand() | |
2290 | |
2291 expandcmd({string}) *expandcmd()* | |
2292 Expand special items in String {string} like what is done for | |
2293 an Ex command such as `:edit`. This expands special keywords, | |
2294 like with |expand()|, and environment variables, anywhere in | |
2295 {string}. "~user" and "~/path" are only expanded at the | |
2296 start. | |
2297 Returns the expanded string. Example: > | |
2298 :echo expandcmd('make %<.o') | |
2299 | |
2300 < Can also be used as a |method|: > | |
2301 GetCommand()->expandcmd() | |
2302 < | |
2303 extend({expr1}, {expr2} [, {expr3}]) *extend()* | |
2304 {expr1} and {expr2} must be both |Lists| or both | |
2305 |Dictionaries|. | |
2306 | |
2307 If they are |Lists|: Append {expr2} to {expr1}. | |
2308 If {expr3} is given insert the items of {expr2} before the | |
2309 item with index {expr3} in {expr1}. When {expr3} is zero | |
2310 insert before the first item. When {expr3} is equal to | |
2311 len({expr1}) then {expr2} is appended. | |
2312 Examples: > | |
2313 :echo sort(extend(mylist, [7, 5])) | |
2314 :call extend(mylist, [2, 3], 1) | |
2315 < When {expr1} is the same List as {expr2} then the number of | |
2316 items copied is equal to the original length of the List. | |
2317 E.g., when {expr3} is 1 you get N new copies of the first item | |
2318 (where N is the original length of the List). | |
2319 Use |add()| to concatenate one item to a list. To concatenate | |
2320 two lists into a new list use the + operator: > | |
2321 :let newlist = [1, 2, 3] + [4, 5] | |
2322 < | |
2323 If they are |Dictionaries|: | |
2324 Add all entries from {expr2} to {expr1}. | |
2325 If a key exists in both {expr1} and {expr2} then {expr3} is | |
2326 used to decide what to do: | |
2327 {expr3} = "keep": keep the value of {expr1} | |
2328 {expr3} = "force": use the value of {expr2} | |
2329 {expr3} = "error": give an error message *E737* | |
2330 When {expr3} is omitted then "force" is assumed. | |
2331 | |
2332 {expr1} is changed when {expr2} is not empty. If necessary | |
2333 make a copy of {expr1} first. | |
2334 {expr2} remains unchanged. | |
2335 When {expr1} is locked and {expr2} is not empty the operation | |
2336 fails. | |
2337 Returns {expr1}. | |
2338 | |
2339 Can also be used as a |method|: > | |
2340 mylist->extend(otherlist) | |
2341 | |
2342 | |
2343 extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* | |
2344 Like |extend()| but instead of adding items to {expr1} a new | |
2345 List or Dictionary is created and returned. {expr1} remains | |
2346 unchanged. Items can still be changed by {expr2}, if you | |
2347 don't want that use |deepcopy()| first. | |
2348 | |
2349 | |
2350 feedkeys({string} [, {mode}]) *feedkeys()* | |
2351 Characters in {string} are queued for processing as if they | |
2352 come from a mapping or were typed by the user. | |
2353 | |
2354 By default the string is added to the end of the typeahead | |
2355 buffer, thus if a mapping is still being executed the | |
2356 characters come after them. Use the 'i' flag to insert before | |
2357 other characters, they will be executed next, before any | |
2358 characters from a mapping. | |
2359 | |
2360 The function does not wait for processing of keys contained in | |
2361 {string}. | |
2362 | |
2363 To include special keys into {string}, use double-quotes | |
2364 and "\..." notation |expr-quote|. For example, | |
2365 feedkeys("\<CR>") simulates pressing of the <Enter> key. But | |
2366 feedkeys('\<CR>') pushes 5 characters. | |
2367 A special code that might be useful is <Ignore>, it exits the | |
2368 wait for a character without doing anything. *<Ignore>* | |
2369 | |
2370 {mode} is a String, which can contain these character flags: | |
2371 'm' Remap keys. This is default. If {mode} is absent, | |
2372 keys are remapped. | |
2373 'n' Do not remap keys. | |
2374 't' Handle keys as if typed; otherwise they are handled as | |
2375 if coming from a mapping. This matters for undo, | |
2376 opening folds, etc. | |
2377 'L' Lowlevel input. Only works for Unix or when using the | |
2378 GUI. Keys are used as if they were coming from the | |
2379 terminal. Other flags are not used. *E980* | |
2380 When a CTRL-C interrupts and 't' is included it sets | |
2381 the internal "got_int" flag. | |
2382 'i' Insert the string instead of appending (see above). | |
2383 'x' Execute commands until typeahead is empty. This is | |
2384 similar to using ":normal!". You can call feedkeys() | |
2385 several times without 'x' and then one time with 'x' | |
2386 (possibly with an empty {string}) to execute all the | |
2387 typeahead. Note that when Vim ends in Insert mode it | |
2388 will behave as if <Esc> is typed, to avoid getting | |
2389 stuck, waiting for a character to be typed before the | |
2390 script continues. | |
2391 Note that if you manage to call feedkeys() while | |
2392 executing commands, thus calling it recursively, then | |
2393 all typeahead will be consumed by the last call. | |
2394 '!' When used with 'x' will not end Insert mode. Can be | |
2395 used in a test when a timer is set to exit Insert mode | |
2396 a little later. Useful for testing CursorHoldI. | |
2397 | |
2398 Return value is always 0. | |
2399 | |
2400 Can also be used as a |method|: > | |
2401 GetInput()->feedkeys() | |
2402 | |
2403 filereadable({file}) *filereadable()* | |
2404 The result is a Number, which is |TRUE| when a file with the | |
2405 name {file} exists, and can be read. If {file} doesn't exist, | |
2406 or is a directory, the result is |FALSE|. {file} is any | |
2407 expression, which is used as a String. | |
2408 If you don't care about the file being readable you can use | |
2409 |glob()|. | |
2410 {file} is used as-is, you may want to expand wildcards first: > | |
2411 echo filereadable('~/.vimrc') | |
2412 0 | |
2413 echo filereadable(expand('~/.vimrc')) | |
2414 1 | |
2415 | |
2416 < Can also be used as a |method|: > | |
2417 GetName()->filereadable() | |
2418 < *file_readable()* | |
2419 Obsolete name: file_readable(). | |
2420 | |
2421 | |
2422 filewritable({file}) *filewritable()* | |
2423 The result is a Number, which is 1 when a file with the | |
2424 name {file} exists, and can be written. If {file} doesn't | |
2425 exist, or is not writable, the result is 0. If {file} is a | |
2426 directory, and we can write to it, the result is 2. | |
2427 | |
2428 Can also be used as a |method|: > | |
2429 GetName()->filewritable() | |
2430 | |
2431 | |
2432 filter({expr1}, {expr2}) *filter()* | |
2433 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. | |
2434 For each item in {expr1} evaluate {expr2} and when the result | |
2435 is zero or false remove the item from the |List| or | |
2436 |Dictionary|. Similarly for each byte in a |Blob| and each | |
2437 charactor in a |String|. | |
2438 | |
2439 {expr2} must be a |string| or |Funcref|. | |
2440 | |
2441 If {expr2} is a |string|, inside {expr2} |v:val| has the value | |
2442 of the current item. For a |Dictionary| |v:key| has the key | |
2443 of the current item and for a |List| |v:key| has the index of | |
2444 the current item. For a |Blob| |v:key| has the index of the | |
2445 current byte. For a |String| |v:key| has the index of the | |
2446 current character. | |
2447 Examples: > | |
2448 call filter(mylist, 'v:val !~ "OLD"') | |
2449 < Removes the items where "OLD" appears. > | |
2450 call filter(mydict, 'v:key >= 8') | |
2451 < Removes the items with a key below 8. > | |
2452 call filter(var, 0) | |
2453 < Removes all the items, thus clears the |List| or |Dictionary|. | |
2454 | |
2455 Note that {expr2} is the result of expression and is then | |
2456 used as an expression again. Often it is good to use a | |
2457 |literal-string| to avoid having to double backslashes. | |
2458 | |
2459 If {expr2} is a |Funcref| it must take two arguments: | |
2460 1. the key or the index of the current item. | |
2461 2. the value of the current item. | |
2462 The function must return |TRUE| if the item should be kept. | |
2463 Example that keeps the odd items of a list: > | |
2464 func Odd(idx, val) | |
2465 return a:idx % 2 == 1 | |
2466 endfunc | |
2467 call filter(mylist, function('Odd')) | |
2468 < It is shorter when using a |lambda|: > | |
2469 call filter(myList, {idx, val -> idx * val <= 42}) | |
2470 < If you do not use "val" you can leave it out: > | |
2471 call filter(myList, {idx -> idx % 2 == 1}) | |
2472 < | |
2473 In |Vim9| script the result must be true, false, zero or one. | |
2474 Other values will result in a type error. | |
2475 | |
2476 For a |List| and a |Dictionary| the operation is done | |
2477 in-place. If you want it to remain unmodified make a copy | |
2478 first: > | |
2479 :let l = filter(copy(mylist), 'v:val =~ "KEEP"') | |
2480 | |
2481 < Returns {expr1}, the |List| or |Dictionary| that was filtered, | |
2482 or a new |Blob| or |String|. | |
2483 When an error is encountered while evaluating {expr2} no | |
2484 further items in {expr1} are processed. | |
2485 When {expr2} is a Funcref errors inside a function are ignored, | |
2486 unless it was defined with the "abort" flag. | |
2487 | |
2488 Can also be used as a |method|: > | |
2489 mylist->filter(expr2) | |
2490 | |
2491 finddir({name} [, {path} [, {count}]]) *finddir()* | |
2492 Find directory {name} in {path}. Supports both downwards and | |
2493 upwards recursive directory searches. See |file-searching| | |
2494 for the syntax of {path}. | |
2495 | |
2496 Returns the path of the first found match. When the found | |
2497 directory is below the current directory a relative path is | |
2498 returned. Otherwise a full path is returned. | |
2499 If {path} is omitted or empty then 'path' is used. | |
2500 | |
2501 If the optional {count} is given, find {count}'s occurrence of | |
2502 {name} in {path} instead of the first one. | |
2503 When {count} is negative return all the matches in a |List|. | |
2504 | |
2505 This is quite similar to the ex-command `:find`. | |
2506 {only available when compiled with the |+file_in_path| | |
2507 feature} | |
2508 | |
2509 Can also be used as a |method|: > | |
2510 GetName()->finddir() | |
2511 | |
2512 findfile({name} [, {path} [, {count}]]) *findfile()* | |
2513 Just like |finddir()|, but find a file instead of a directory. | |
2514 Uses 'suffixesadd'. | |
2515 Example: > | |
2516 :echo findfile("tags.vim", ".;") | |
2517 < Searches from the directory of the current file upwards until | |
2518 it finds the file "tags.vim". | |
2519 | |
2520 Can also be used as a |method|: > | |
2521 GetName()->findfile() | |
2522 | |
2523 flatten({list} [, {maxdepth}]) *flatten()* | |
2524 Flatten {list} up to {maxdepth} levels. Without {maxdepth} | |
2525 the result is a |List| without nesting, as if {maxdepth} is | |
2526 a very large number. | |
2527 The {list} is changed in place, use |flattennew()| if you do | |
2528 not want that. | |
2529 In Vim9 script flatten() cannot be used, you must always use | |
2530 |flattennew()|. | |
2531 *E900* | |
2532 {maxdepth} means how deep in nested lists changes are made. | |
2533 {list} is not modified when {maxdepth} is 0. | |
2534 {maxdepth} must be positive number. | |
2535 | |
2536 If there is an error the number zero is returned. | |
2537 | |
2538 Example: > | |
2539 :echo flatten([1, [2, [3, 4]], 5]) | |
2540 < [1, 2, 3, 4, 5] > | |
2541 :echo flatten([1, [2, [3, 4]], 5], 1) | |
2542 < [1, 2, [3, 4], 5] | |
2543 | |
2544 Can also be used as a |method|: > | |
2545 mylist->flatten() | |
2546 < | |
2547 flattennew({list} [, {maxdepth}]) *flattennew()* | |
2548 Like |flatten()| but first make a copy of {list}. | |
2549 | |
2550 | |
2551 float2nr({expr}) *float2nr()* | |
2552 Convert {expr} to a Number by omitting the part after the | |
2553 decimal point. | |
2554 {expr} must evaluate to a |Float| or a Number. | |
2555 When the value of {expr} is out of range for a |Number| the | |
2556 result is truncated to 0x7fffffff or -0x7fffffff (or when | |
2557 64-bit Number support is enabled, 0x7fffffffffffffff or | |
2558 -0x7fffffffffffffff). NaN results in -0x80000000 (or when | |
2559 64-bit Number support is enabled, -0x8000000000000000). | |
2560 Examples: > | |
2561 echo float2nr(3.95) | |
2562 < 3 > | |
2563 echo float2nr(-23.45) | |
2564 < -23 > | |
2565 echo float2nr(1.0e100) | |
2566 < 2147483647 (or 9223372036854775807) > | |
2567 echo float2nr(-1.0e150) | |
2568 < -2147483647 (or -9223372036854775807) > | |
2569 echo float2nr(1.0e-100) | |
2570 < 0 | |
2571 | |
2572 Can also be used as a |method|: > | |
2573 Compute()->float2nr() | |
2574 < | |
2575 {only available when compiled with the |+float| feature} | |
2576 | |
2577 | |
2578 floor({expr}) *floor()* | |
2579 Return the largest integral value less than or equal to | |
2580 {expr} as a |Float| (round down). | |
2581 {expr} must evaluate to a |Float| or a |Number|. | |
2582 Examples: > | |
2583 echo floor(1.856) | |
2584 < 1.0 > | |
2585 echo floor(-5.456) | |
2586 < -6.0 > | |
2587 echo floor(4.0) | |
2588 < 4.0 | |
2589 | |
2590 Can also be used as a |method|: > | |
2591 Compute()->floor() | |
2592 < | |
2593 {only available when compiled with the |+float| feature} | |
2594 | |
2595 | |
2596 fmod({expr1}, {expr2}) *fmod()* | |
2597 Return the remainder of {expr1} / {expr2}, even if the | |
2598 division is not representable. Returns {expr1} - i * {expr2} | |
2599 for some integer i such that if {expr2} is non-zero, the | |
2600 result has the same sign as {expr1} and magnitude less than | |
2601 the magnitude of {expr2}. If {expr2} is zero, the value | |
2602 returned is zero. The value returned is a |Float|. | |
2603 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. | |
2604 Examples: > | |
2605 :echo fmod(12.33, 1.22) | |
2606 < 0.13 > | |
2607 :echo fmod(-12.33, 1.22) | |
2608 < -0.13 | |
2609 | |
2610 Can also be used as a |method|: > | |
2611 Compute()->fmod(1.22) | |
2612 < | |
2613 {only available when compiled with |+float| feature} | |
2614 | |
2615 | |
2616 fnameescape({string}) *fnameescape()* | |
2617 Escape {string} for use as file name command argument. All | |
2618 characters that have a special meaning, such as '%' and '|' | |
2619 are escaped with a backslash. | |
2620 For most systems the characters escaped are | |
2621 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash | |
2622 appears in a filename, it depends on the value of 'isfname'. | |
2623 A leading '+' and '>' is also escaped (special after |:edit| | |
2624 and |:write|). And a "-" by itself (special after |:cd|). | |
2625 Example: > | |
2626 :let fname = '+some str%nge|name' | |
2627 :exe "edit " . fnameescape(fname) | |
2628 < results in executing: > | |
2629 edit \+some\ str\%nge\|name | |
2630 < | |
2631 Can also be used as a |method|: > | |
2632 GetName()->fnameescape() | |
2633 | |
2634 fnamemodify({fname}, {mods}) *fnamemodify()* | |
2635 Modify file name {fname} according to {mods}. {mods} is a | |
2636 string of characters like it is used for file names on the | |
2637 command line. See |filename-modifiers|. | |
2638 Example: > | |
2639 :echo fnamemodify("main.c", ":p:h") | |
2640 < results in: > | |
2641 /home/mool/vim/vim/src | |
2642 < If {mods} is empty then {fname} is returned. | |
2643 Note: Environment variables don't work in {fname}, use | |
2644 |expand()| first then. | |
2645 | |
2646 Can also be used as a |method|: > | |
2647 GetName()->fnamemodify(':p:h') | |
2648 | |
2649 foldclosed({lnum}) *foldclosed()* | |
2650 The result is a Number. If the line {lnum} is in a closed | |
2651 fold, the result is the number of the first line in that fold. | |
2652 If the line {lnum} is not in a closed fold, -1 is returned. | |
2653 {lnum} is used like with |getline()|. Thus "." is the current | |
2654 line, "'m" mark m, etc. | |
2655 | |
2656 Can also be used as a |method|: > | |
2657 GetLnum()->foldclosed() | |
2658 | |
2659 foldclosedend({lnum}) *foldclosedend()* | |
2660 The result is a Number. If the line {lnum} is in a closed | |
2661 fold, the result is the number of the last line in that fold. | |
2662 If the line {lnum} is not in a closed fold, -1 is returned. | |
2663 {lnum} is used like with |getline()|. Thus "." is the current | |
2664 line, "'m" mark m, etc. | |
2665 | |
2666 Can also be used as a |method|: > | |
2667 GetLnum()->foldclosedend() | |
2668 | |
2669 foldlevel({lnum}) *foldlevel()* | |
2670 The result is a Number, which is the foldlevel of line {lnum} | |
2671 in the current buffer. For nested folds the deepest level is | |
2672 returned. If there is no fold at line {lnum}, zero is | |
2673 returned. It doesn't matter if the folds are open or closed. | |
2674 When used while updating folds (from 'foldexpr') -1 is | |
2675 returned for lines where folds are still to be updated and the | |
2676 foldlevel is unknown. As a special case the level of the | |
2677 previous line is usually available. | |
2678 {lnum} is used like with |getline()|. Thus "." is the current | |
2679 line, "'m" mark m, etc. | |
2680 | |
2681 Can also be used as a |method|: > | |
2682 GetLnum()->foldlevel() | |
2683 < | |
2684 *foldtext()* | |
2685 foldtext() Returns a String, to be displayed for a closed fold. This is | |
2686 the default function used for the 'foldtext' option and should | |
2687 only be called from evaluating 'foldtext'. It uses the | |
2688 |v:foldstart|, |v:foldend| and |v:folddashes| variables. | |
2689 The returned string looks like this: > | |
2690 +-- 45 lines: abcdef | |
2691 < The number of leading dashes depends on the foldlevel. The | |
2692 "45" is the number of lines in the fold. "abcdef" is the text | |
2693 in the first non-blank line of the fold. Leading white space, | |
2694 "//" or "/*" and the text from the 'foldmarker' and | |
2695 'commentstring' options is removed. | |
2696 When used to draw the actual foldtext, the rest of the line | |
2697 will be filled with the fold char from the 'fillchars' | |
2698 setting. | |
2699 {not available when compiled without the |+folding| feature} | |
2700 | |
2701 foldtextresult({lnum}) *foldtextresult()* | |
2702 Returns the text that is displayed for the closed fold at line | |
2703 {lnum}. Evaluates 'foldtext' in the appropriate context. | |
2704 When there is no closed fold at {lnum} an empty string is | |
2705 returned. | |
2706 {lnum} is used like with |getline()|. Thus "." is the current | |
2707 line, "'m" mark m, etc. | |
2708 Useful when exporting folded text, e.g., to HTML. | |
2709 {not available when compiled without the |+folding| feature} | |
2710 | |
2711 | |
2712 Can also be used as a |method|: > | |
2713 GetLnum()->foldtextresult() | |
2714 < | |
2715 *foreground()* | |
2716 foreground() Move the Vim window to the foreground. Useful when sent from | |
2717 a client to a Vim server. |remote_send()| | |
2718 On Win32 systems this might not work, the OS does not always | |
2719 allow a window to bring itself to the foreground. Use | |
2720 |remote_foreground()| instead. | |
2721 {only in the Win32, Athena, Motif and GTK GUI versions and the | |
2722 Win32 console version} | |
2723 | |
2724 fullcommand({name}) *fullcommand()* | |
2725 Get the full command name from a short abbreviated command | |
2726 name; see |20.2| for details on command abbreviations. | |
2727 | |
2728 The string argument {name} may start with a `:` and can | |
2729 include a [range], these are skipped and not returned. | |
2730 Returns an empty string if a command doesn't exist or if it's | |
2731 ambiguous (for user-defined commands). | |
2732 | |
2733 For example `fullcommand('s')`, `fullcommand('sub')`, | |
2734 `fullcommand(':%substitute')` all return "substitute". | |
2735 | |
2736 Can also be used as a |method|: > | |
2737 GetName()->fullcommand() | |
2738 < | |
2739 *funcref()* | |
2740 funcref({name} [, {arglist}] [, {dict}]) | |
2741 Just like |function()|, but the returned Funcref will lookup | |
2742 the function by reference, not by name. This matters when the | |
2743 function {name} is redefined later. | |
2744 | |
2745 Unlike |function()|, {name} must be an existing user function. | |
2746 Also for autoloaded functions. {name} cannot be a builtin | |
2747 function. | |
2748 | |
2749 Can also be used as a |method|: > | |
2750 GetFuncname()->funcref([arg]) | |
2751 < | |
2752 *function()* *partial* *E700* *E922* *E923* | |
2753 function({name} [, {arglist}] [, {dict}]) | |
2754 Return a |Funcref| variable that refers to function {name}. | |
2755 {name} can be the name of a user defined function or an | |
2756 internal function. | |
2757 | |
2758 {name} can also be a Funcref or a partial. When it is a | |
2759 partial the dict stored in it will be used and the {dict} | |
2760 argument is not allowed. E.g.: > | |
2761 let FuncWithArg = function(dict.Func, [arg]) | |
2762 let Broken = function(dict.Func, [arg], dict) | |
2763 < | |
2764 When using the Funcref the function will be found by {name}, | |
2765 also when it was redefined later. Use |funcref()| to keep the | |
2766 same function. | |
2767 | |
2768 When {arglist} or {dict} is present this creates a partial. | |
2769 That means the argument list and/or the dictionary is stored in | |
2770 the Funcref and will be used when the Funcref is called. | |
2771 | |
2772 The arguments are passed to the function in front of other | |
2773 arguments, but after any argument from |method|. Example: > | |
2774 func Callback(arg1, arg2, name) | |
2775 ... | |
2776 let Partial = function('Callback', ['one', 'two']) | |
2777 ... | |
2778 call Partial('name') | |
2779 < Invokes the function as with: > | |
2780 call Callback('one', 'two', 'name') | |
2781 | |
2782 < With a |method|: > | |
2783 func Callback(one, two, three) | |
2784 ... | |
2785 let Partial = function('Callback', ['two']) | |
2786 ... | |
2787 eval 'one'->Partial('three') | |
2788 < Invokes the function as with: > | |
2789 call Callback('one', 'two', 'three') | |
2790 | |
2791 < The function() call can be nested to add more arguments to the | |
2792 Funcref. The extra arguments are appended to the list of | |
2793 arguments. Example: > | |
2794 func Callback(arg1, arg2, name) | |
2795 ... | |
2796 let Func = function('Callback', ['one']) | |
2797 let Func2 = function(Func, ['two']) | |
2798 ... | |
2799 call Func2('name') | |
2800 < Invokes the function as with: > | |
2801 call Callback('one', 'two', 'name') | |
2802 | |
2803 < The Dictionary is only useful when calling a "dict" function. | |
2804 In that case the {dict} is passed in as "self". Example: > | |
2805 function Callback() dict | |
2806 echo "called for " . self.name | |
2807 endfunction | |
2808 ... | |
2809 let context = {"name": "example"} | |
2810 let Func = function('Callback', context) | |
2811 ... | |
2812 call Func() " will echo: called for example | |
2813 < The use of function() is not needed when there are no extra | |
2814 arguments, these two are equivalent: > | |
2815 let Func = function('Callback', context) | |
2816 let Func = context.Callback | |
2817 | |
2818 < The argument list and the Dictionary can be combined: > | |
2819 function Callback(arg1, count) dict | |
2820 ... | |
2821 let context = {"name": "example"} | |
2822 let Func = function('Callback', ['one'], context) | |
2823 ... | |
2824 call Func(500) | |
2825 < Invokes the function as with: > | |
2826 call context.Callback('one', 500) | |
2827 < | |
2828 Can also be used as a |method|: > | |
2829 GetFuncname()->function([arg]) | |
2830 | |
2831 | |
2832 garbagecollect([{atexit}]) *garbagecollect()* | |
2833 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs| | |
2834 that have circular references. | |
2835 | |
2836 There is hardly ever a need to invoke this function, as it is | |
2837 automatically done when Vim runs out of memory or is waiting | |
2838 for the user to press a key after 'updatetime'. Items without | |
2839 circular references are always freed when they become unused. | |
2840 This is useful if you have deleted a very big |List| and/or | |
2841 |Dictionary| with circular references in a script that runs | |
2842 for a long time. | |
2843 | |
2844 When the optional {atexit} argument is one, garbage | |
2845 collection will also be done when exiting Vim, if it wasn't | |
2846 done before. This is useful when checking for memory leaks. | |
2847 | |
2848 The garbage collection is not done immediately but only when | |
2849 it's safe to perform. This is when waiting for the user to | |
2850 type a character. To force garbage collection immediately use | |
2851 |test_garbagecollect_now()|. | |
2852 | |
2853 get({list}, {idx} [, {default}]) *get()* | |
2854 Get item {idx} from |List| {list}. When this item is not | |
2855 available return {default}. Return zero when {default} is | |
2856 omitted. | |
2857 Preferably used as a |method|: > | |
2858 mylist->get(idx) | |
2859 get({blob}, {idx} [, {default}]) | |
2860 Get byte {idx} from |Blob| {blob}. When this byte is not | |
2861 available return {default}. Return -1 when {default} is | |
2862 omitted. | |
2863 Preferably used as a |method|: > | |
2864 myblob->get(idx) | |
2865 get({dict}, {key} [, {default}]) | |
2866 Get item with key {key} from |Dictionary| {dict}. When this | |
2867 item is not available return {default}. Return zero when | |
2868 {default} is omitted. Useful example: > | |
2869 let val = get(g:, 'var_name', 'default') | |
2870 < This gets the value of g:var_name if it exists, and uses | |
2871 'default' when it does not exist. | |
2872 Preferably used as a |method|: > | |
2873 mydict->get(key) | |
2874 get({func}, {what}) | |
2875 Get an item with from Funcref {func}. Possible values for | |
2876 {what} are: | |
2877 "name" The function name | |
2878 "func" The function | |
2879 "dict" The dictionary | |
2880 "args" The list with arguments | |
2881 Preferably used as a |method|: > | |
2882 myfunc->get(what) | |
2883 < | |
2884 *getbufinfo()* | |
2885 getbufinfo([{buf}]) | |
2886 getbufinfo([{dict}]) | |
2887 Get information about buffers as a List of Dictionaries. | |
2888 | |
2889 Without an argument information about all the buffers is | |
2890 returned. | |
2891 | |
2892 When the argument is a |Dictionary| only the buffers matching | |
2893 the specified criteria are returned. The following keys can | |
2894 be specified in {dict}: | |
2895 buflisted include only listed buffers. | |
2896 bufloaded include only loaded buffers. | |
2897 bufmodified include only modified buffers. | |
2898 | |
2899 Otherwise, {buf} specifies a particular buffer to return | |
2900 information for. For the use of {buf}, see |bufname()| | |
2901 above. If the buffer is found the returned List has one item. | |
2902 Otherwise the result is an empty list. | |
2903 | |
2904 Each returned List item is a dictionary with the following | |
2905 entries: | |
2906 bufnr Buffer number. | |
2907 changed TRUE if the buffer is modified. | |
2908 changedtick Number of changes made to the buffer. | |
2909 hidden TRUE if the buffer is hidden. | |
2910 lastused Timestamp in seconds, like | |
2911 |localtime()|, when the buffer was | |
2912 last used. | |
2913 {only with the |+viminfo| feature} | |
2914 listed TRUE if the buffer is listed. | |
2915 lnum Line number used for the buffer when | |
2916 opened in the current window. | |
2917 Only valid if the buffer has been | |
2918 displayed in the window in the past. | |
2919 If you want the line number of the | |
2920 last known cursor position in a given | |
2921 window, use |line()|: > | |
2922 :echo line('.', {winid}) | |
2923 < | |
2924 linecount Number of lines in the buffer (only | |
2925 valid when loaded) | |
2926 loaded TRUE if the buffer is loaded. | |
2927 name Full path to the file in the buffer. | |
2928 signs List of signs placed in the buffer. | |
2929 Each list item is a dictionary with | |
2930 the following fields: | |
2931 id sign identifier | |
2932 lnum line number | |
2933 name sign name | |
2934 variables A reference to the dictionary with | |
2935 buffer-local variables. | |
2936 windows List of |window-ID|s that display this | |
2937 buffer | |
2938 popups List of popup |window-ID|s that | |
2939 display this buffer | |
2940 | |
2941 Examples: > | |
2942 for buf in getbufinfo() | |
2943 echo buf.name | |
2944 endfor | |
2945 for buf in getbufinfo({'buflisted':1}) | |
2946 if buf.changed | |
2947 .... | |
2948 endif | |
2949 endfor | |
2950 < | |
2951 To get buffer-local options use: > | |
2952 getbufvar({bufnr}, '&option_name') | |
2953 < | |
2954 Can also be used as a |method|: > | |
2955 GetBufnr()->getbufinfo() | |
2956 < | |
2957 | |
2958 *getbufline()* | |
2959 getbufline({buf}, {lnum} [, {end}]) | |
2960 Return a |List| with the lines starting from {lnum} to {end} | |
2961 (inclusive) in the buffer {buf}. If {end} is omitted, a | |
2962 |List| with only the line {lnum} is returned. | |
2963 | |
2964 For the use of {buf}, see |bufname()| above. | |
2965 | |
2966 For {lnum} and {end} "$" can be used for the last line of the | |
2967 buffer. Otherwise a number must be used. | |
2968 | |
2969 When {lnum} is smaller than 1 or bigger than the number of | |
2970 lines in the buffer, an empty |List| is returned. | |
2971 | |
2972 When {end} is greater than the number of lines in the buffer, | |
2973 it is treated as {end} is set to the number of lines in the | |
2974 buffer. When {end} is before {lnum} an empty |List| is | |
2975 returned. | |
2976 | |
2977 This function works only for loaded buffers. For unloaded and | |
2978 non-existing buffers, an empty |List| is returned. | |
2979 | |
2980 Example: > | |
2981 :let lines = getbufline(bufnr("myfile"), 1, "$") | |
2982 | |
2983 < Can also be used as a |method|: > | |
2984 GetBufnr()->getbufline(lnum) | |
2985 | |
2986 getbufvar({buf}, {varname} [, {def}]) *getbufvar()* | |
2987 The result is the value of option or local buffer variable | |
2988 {varname} in buffer {buf}. Note that the name without "b:" | |
2989 must be used. | |
2990 The {varname} argument is a string. | |
2991 When {varname} is empty returns a |Dictionary| with all the | |
2992 buffer-local variables. | |
2993 When {varname} is equal to "&" returns a |Dictionary| with all | |
2994 the buffer-local options. | |
2995 Otherwise, when {varname} starts with "&" returns the value of | |
2996 a buffer-local option. | |
2997 This also works for a global or buffer-local option, but it | |
2998 doesn't work for a global variable, window-local variable or | |
2999 window-local option. | |
3000 For the use of {buf}, see |bufname()| above. | |
3001 When the buffer or variable doesn't exist {def} or an empty | |
3002 string is returned, there is no error message. | |
3003 Examples: > | |
3004 :let bufmodified = getbufvar(1, "&mod") | |
3005 :echo "todo myvar = " . getbufvar("todo", "myvar") | |
3006 | |
3007 < Can also be used as a |method|: > | |
3008 GetBufnr()->getbufvar(varname) | |
3009 < | |
3010 getchangelist([{buf}]) *getchangelist()* | |
3011 Returns the |changelist| for the buffer {buf}. For the use | |
3012 of {buf}, see |bufname()| above. If buffer {buf} doesn't | |
3013 exist, an empty list is returned. | |
3014 | |
3015 The returned list contains two entries: a list with the change | |
3016 locations and the current position in the list. Each | |
3017 entry in the change list is a dictionary with the following | |
3018 entries: | |
3019 col column number | |
3020 coladd column offset for 'virtualedit' | |
3021 lnum line number | |
3022 If buffer {buf} is the current buffer, then the current | |
3023 position refers to the position in the list. For other | |
3024 buffers, it is set to the length of the list. | |
3025 | |
3026 Can also be used as a |method|: > | |
3027 GetBufnr()->getchangelist() | |
3028 | |
3029 getchar([expr]) *getchar()* | |
3030 Get a single character from the user or input stream. | |
3031 If [expr] is omitted, wait until a character is available. | |
3032 If [expr] is 0, only get a character when one is available. | |
3033 Return zero otherwise. | |
3034 If [expr] is 1, only check if a character is available, it is | |
3035 not consumed. Return zero if no character available. | |
3036 If you prefer always getting a string use |getcharstr()|. | |
3037 | |
3038 Without [expr] and when [expr] is 0 a whole character or | |
3039 special key is returned. If it is a single character, the | |
3040 result is a number. Use nr2char() to convert it to a String. | |
3041 Otherwise a String is returned with the encoded character. | |
3042 For a special key it's a String with a sequence of bytes | |
3043 starting with 0x80 (decimal: 128). This is the same value as | |
3044 the String "\<Key>", e.g., "\<Left>". The returned value is | |
3045 also a String when a modifier (shift, control, alt) was used | |
3046 that is not included in the character. | |
3047 | |
3048 When [expr] is 0 and Esc is typed, there will be a short delay | |
3049 while Vim waits to see if this is the start of an escape | |
3050 sequence. | |
3051 | |
3052 When [expr] is 1 only the first byte is returned. For a | |
3053 one-byte character it is the character itself as a number. | |
3054 Use nr2char() to convert it to a String. | |
3055 | |
3056 Use getcharmod() to obtain any additional modifiers. | |
3057 | |
3058 When the user clicks a mouse button, the mouse event will be | |
3059 returned. The position can then be found in |v:mouse_col|, | |
3060 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. | |
3061 |getmousepos()| can also be used. Mouse move events will be | |
3062 ignored. | |
3063 This example positions the mouse as it would normally happen: > | |
3064 let c = getchar() | |
3065 if c == "\<LeftMouse>" && v:mouse_win > 0 | |
3066 exe v:mouse_win . "wincmd w" | |
3067 exe v:mouse_lnum | |
3068 exe "normal " . v:mouse_col . "|" | |
3069 endif | |
3070 < | |
3071 When using bracketed paste only the first character is | |
3072 returned, the rest of the pasted text is dropped. | |
3073 |xterm-bracketed-paste|. | |
3074 | |
3075 There is no prompt, you will somehow have to make clear to the | |
3076 user that a character has to be typed. The screen is not | |
3077 redrawn, e.g. when resizing the window. When using a popup | |
3078 window it should work better with a |popup-filter|. | |
3079 | |
3080 There is no mapping for the character. | |
3081 Key codes are replaced, thus when the user presses the <Del> | |
3082 key you get the code for the <Del> key, not the raw character | |
3083 sequence. Examples: > | |
3084 getchar() == "\<Del>" | |
3085 getchar() == "\<S-Left>" | |
3086 < This example redefines "f" to ignore case: > | |
3087 :nmap f :call FindChar()<CR> | |
3088 :function FindChar() | |
3089 : let c = nr2char(getchar()) | |
3090 : while col('.') < col('$') - 1 | |
3091 : normal l | |
3092 : if getline('.')[col('.') - 1] ==? c | |
3093 : break | |
3094 : endif | |
3095 : endwhile | |
3096 :endfunction | |
3097 < | |
3098 You may also receive synthetic characters, such as | |
3099 |<CursorHold>|. Often you will want to ignore this and get | |
3100 another character: > | |
3101 :function GetKey() | |
3102 : let c = getchar() | |
3103 : while c == "\<CursorHold>" | |
3104 : let c = getchar() | |
3105 : endwhile | |
3106 : return c | |
3107 :endfunction | |
3108 | |
3109 getcharmod() *getcharmod()* | |
3110 The result is a Number which is the state of the modifiers for | |
3111 the last obtained character with getchar() or in another way. | |
3112 These values are added together: | |
3113 2 shift | |
3114 4 control | |
3115 8 alt (meta) | |
3116 16 meta (when it's different from ALT) | |
3117 32 mouse double click | |
3118 64 mouse triple click | |
3119 96 mouse quadruple click (== 32 + 64) | |
3120 128 command (Macintosh only) | |
3121 Only the modifiers that have not been included in the | |
3122 character itself are obtained. Thus Shift-a results in "A" | |
3123 without a modifier. | |
3124 | |
3125 *getcharpos()* | |
3126 getcharpos({expr}) | |
3127 Get the position for String {expr}. Same as |getpos()| but the | |
3128 column number in the returned List is a character index | |
3129 instead of a byte index. | |
3130 If |getpos()| returns a very large column number, such as | |
3131 2147483647, then getcharpos() will return the character index | |
3132 of the last character. | |
3133 | |
3134 Example: | |
3135 With the cursor on '세' in line 5 with text "여보세요": > | |
3136 getcharpos('.') returns [0, 5, 3, 0] | |
3137 getpos('.') returns [0, 5, 7, 0] | |
3138 < | |
3139 Can also be used as a |method|: > | |
3140 GetMark()->getcharpos() | |
3141 | |
3142 getcharsearch() *getcharsearch()* | |
3143 Return the current character search information as a {dict} | |
3144 with the following entries: | |
3145 | |
3146 char character previously used for a character | |
3147 search (|t|, |f|, |T|, or |F|); empty string | |
3148 if no character search has been performed | |
3149 forward direction of character search; 1 for forward, | |
3150 0 for backward | |
3151 until type of character search; 1 for a |t| or |T| | |
3152 character search, 0 for an |f| or |F| | |
3153 character search | |
3154 | |
3155 This can be useful to always have |;| and |,| search | |
3156 forward/backward regardless of the direction of the previous | |
3157 character search: > | |
3158 :nnoremap <expr> ; getcharsearch().forward ? ';' : ',' | |
3159 :nnoremap <expr> , getcharsearch().forward ? ',' : ';' | |
3160 < Also see |setcharsearch()|. | |
3161 | |
3162 | |
3163 getcharstr([expr]) *getcharstr()* | |
3164 Get a single character from the user or input stream as a | |
3165 string. | |
3166 If [expr] is omitted, wait until a character is available. | |
3167 If [expr] is 0 or false, only get a character when one is | |
3168 available. Return an empty string otherwise. | |
3169 If [expr] is 1 or true, only check if a character is | |
3170 available, it is not consumed. Return an empty string | |
3171 if no character is available. | |
3172 Otherwise this works like |getchar()|, except that a number | |
3173 result is converted to a string. | |
3174 | |
3175 | |
3176 getcmdline() *getcmdline()* | |
3177 Return the current command-line. Only works when the command | |
3178 line is being edited, thus requires use of |c_CTRL-\_e| or | |
3179 |c_CTRL-R_=|. | |
3180 Example: > | |
3181 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> | |
3182 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|. | |
3183 Returns an empty string when entering a password or using | |
3184 |inputsecret()|. | |
3185 | |
3186 getcmdpos() *getcmdpos()* | |
3187 Return the position of the cursor in the command line as a | |
3188 byte count. The first column is 1. | |
3189 Only works when editing the command line, thus requires use of | |
3190 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. | |
3191 Returns 0 otherwise. | |
3192 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|. | |
3193 | |
3194 getcmdtype() *getcmdtype()* | |
3195 Return the current command-line type. Possible return values | |
3196 are: | |
3197 : normal Ex command | |
3198 > debug mode command |debug-mode| | |
3199 / forward search command | |
3200 ? backward search command | |
3201 @ |input()| command | |
3202 - |:insert| or |:append| command | |
3203 = |i_CTRL-R_=| | |
3204 Only works when editing the command line, thus requires use of | |
3205 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. | |
3206 Returns an empty string otherwise. | |
3207 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. | |
3208 | |
3209 getcmdwintype() *getcmdwintype()* | |
3210 Return the current |command-line-window| type. Possible return | |
3211 values are the same as |getcmdtype()|. Returns an empty string | |
3212 when not in the command-line window. | |
3213 | |
3214 getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* | |
3215 Return a list of command-line completion matches. The String | |
3216 {type} argument specifies what for. The following completion | |
3217 types are supported: | |
3218 | |
3219 arglist file names in argument list | |
3220 augroup autocmd groups | |
3221 buffer buffer names | |
3222 behave :behave suboptions | |
3223 color color schemes | |
3224 command Ex command | |
3225 cmdline |cmdline-completion| result | |
3226 compiler compilers | |
3227 cscope |:cscope| suboptions | |
3228 diff_buffer |:diffget| and |:diffput| completion | |
3229 dir directory names | |
3230 environment environment variable names | |
3231 event autocommand events | |
3232 expression Vim expression | |
3233 file file and directory names | |
3234 file_in_path file and directory names in |'path'| | |
3235 filetype filetype names |'filetype'| | |
3236 function function name | |
3237 help help subjects | |
3238 highlight highlight groups | |
3239 history :history suboptions | |
3240 locale locale names (as output of locale -a) | |
3241 mapclear buffer argument | |
3242 mapping mapping name | |
3243 menu menus | |
3244 messages |:messages| suboptions | |
3245 option options | |
3246 packadd optional package |pack-add| names | |
3247 shellcmd Shell command | |
3248 sign |:sign| suboptions | |
3249 syntax syntax file names |'syntax'| | |
3250 syntime |:syntime| suboptions | |
3251 tag tags | |
3252 tag_listfiles tags, file names | |
3253 user user names | |
3254 var user variables | |
3255 | |
3256 If {pat} is an empty string, then all the matches are | |
3257 returned. Otherwise only items matching {pat} are returned. | |
3258 See |wildcards| for the use of special characters in {pat}. | |
3259 | |
3260 If the optional {filtered} flag is set to 1, then 'wildignore' | |
3261 is applied to filter the results. Otherwise all the matches | |
3262 are returned. The 'wildignorecase' option always applies. | |
3263 | |
3264 If {type} is "cmdline", then the |cmdline-completion| result is | |
3265 returned. For example, to complete the possible values after | |
3266 a ":call" command: > | |
3267 echo getcompletion('call ', 'cmdline') | |
3268 < | |
3269 If there are no matches, an empty list is returned. An | |
3270 invalid value for {type} produces an error. | |
3271 | |
3272 Can also be used as a |method|: > | |
3273 GetPattern()->getcompletion('color') | |
3274 < | |
3275 *getcurpos()* | |
3276 getcurpos([{winid}]) | |
3277 Get the position of the cursor. This is like getpos('.'), but | |
3278 includes an extra "curswant" item in the list: | |
3279 [0, lnum, col, off, curswant] ~ | |
3280 The "curswant" number is the preferred column when moving the | |
3281 cursor vertically. Also see |getcursorcharpos()| and | |
3282 |getpos()|. | |
3283 The first "bufnum" item is always zero. The byte position of | |
3284 the cursor is returned in 'col'. To get the character | |
3285 position, use |getcursorcharpos()|. | |
3286 | |
3287 The optional {winid} argument can specify the window. It can | |
3288 be the window number or the |window-ID|. The last known | |
3289 cursor position is returned, this may be invalid for the | |
3290 current value of the buffer if it is not the current window. | |
3291 If {winid} is invalid a list with zeroes is returned. | |
3292 | |
3293 This can be used to save and restore the cursor position: > | |
3294 let save_cursor = getcurpos() | |
3295 MoveTheCursorAround | |
3296 call setpos('.', save_cursor) | |
3297 < Note that this only works within the window. See | |
3298 |winrestview()| for restoring more state. | |
3299 | |
3300 Can also be used as a |method|: > | |
3301 GetWinid()->getcurpos() | |
3302 < | |
3303 *getcursorcharpos()* | |
3304 getcursorcharpos([{winid}]) | |
3305 Same as |getcurpos()| but the column number in the returned | |
3306 List is a character index instead of a byte index. | |
3307 | |
3308 Example: | |
3309 With the cursor on '보' in line 3 with text "여보세요": > | |
3310 getcursorcharpos() returns [0, 3, 2, 0, 3] | |
3311 getcurpos() returns [0, 3, 4, 0, 3] | |
3312 < | |
3313 Can also be used as a |method|: > | |
3314 GetWinid()->getcursorcharpos() | |
3315 | |
3316 < *getcwd()* | |
3317 getcwd([{winnr} [, {tabnr}]]) | |
3318 The result is a String, which is the name of the current | |
3319 working directory. 'autochdir' is ignored. | |
3320 | |
3321 With {winnr} return the local current directory of this window | |
3322 in the current tab page. {winnr} can be the window number or | |
3323 the |window-ID|. | |
3324 If {winnr} is -1 return the name of the global working | |
3325 directory. See also |haslocaldir()|. | |
3326 | |
3327 With {winnr} and {tabnr} return the local current directory of | |
3328 the window in the specified tab page. If {winnr} is -1 return | |
3329 the working directory of the tabpage. | |
3330 If {winnr} is zero use the current window, if {tabnr} is zero | |
3331 use the current tabpage. | |
3332 Without any arguments, return the actual working directory of | |
3333 the current window. | |
3334 Return an empty string if the arguments are invalid. | |
3335 | |
3336 Examples: > | |
3337 " Get the working directory of the current window | |
3338 :echo getcwd() | |
3339 :echo getcwd(0) | |
3340 :echo getcwd(0, 0) | |
3341 " Get the working directory of window 3 in tabpage 2 | |
3342 :echo getcwd(3, 2) | |
3343 " Get the global working directory | |
3344 :echo getcwd(-1) | |
3345 " Get the working directory of tabpage 3 | |
3346 :echo getcwd(-1, 3) | |
3347 " Get the working directory of current tabpage | |
3348 :echo getcwd(-1, 0) | |
3349 | |
3350 < Can also be used as a |method|: > | |
3351 GetWinnr()->getcwd() | |
3352 | |
3353 getenv({name}) *getenv()* | |
3354 Return the value of environment variable {name}. The {name} | |
3355 argument is a string, without a leading '$'. Example: > | |
3356 myHome = getenv('HOME') | |
3357 | |
3358 < When the variable does not exist |v:null| is returned. That | |
3359 is different from a variable set to an empty string, although | |
3360 some systems interpret the empty value as the variable being | |
3361 deleted. See also |expr-env|. | |
3362 | |
3363 Can also be used as a |method|: > | |
3364 GetVarname()->getenv() | |
3365 | |
3366 getfontname([{name}]) *getfontname()* | |
3367 Without an argument returns the name of the normal font being | |
3368 used. Like what is used for the Normal highlight group | |
3369 |hl-Normal|. | |
3370 With an argument a check is done whether String {name} is a | |
3371 valid font name. If not then an empty string is returned. | |
3372 Otherwise the actual font name is returned, or {name} if the | |
3373 GUI does not support obtaining the real name. | |
3374 Only works when the GUI is running, thus not in your vimrc or | |
3375 gvimrc file. Use the |GUIEnter| autocommand to use this | |
3376 function just after the GUI has started. | |
3377 Note that the GTK GUI accepts any font name, thus checking for | |
3378 a valid name does not work. | |
3379 | |
3380 getfperm({fname}) *getfperm()* | |
3381 The result is a String, which is the read, write, and execute | |
3382 permissions of the given file {fname}. | |
3383 If {fname} does not exist or its directory cannot be read, an | |
3384 empty string is returned. | |
3385 The result is of the form "rwxrwxrwx", where each group of | |
3386 "rwx" flags represent, in turn, the permissions of the owner | |
3387 of the file, the group the file belongs to, and other users. | |
3388 If a user does not have a given permission the flag for this | |
3389 is replaced with the string "-". Examples: > | |
3390 :echo getfperm("/etc/passwd") | |
3391 :echo getfperm(expand("~/.vimrc")) | |
3392 < This will hopefully (from a security point of view) display | |
3393 the string "rw-r--r--" or even "rw-------". | |
3394 | |
3395 Can also be used as a |method|: > | |
3396 GetFilename()->getfperm() | |
3397 < | |
3398 For setting permissions use |setfperm()|. | |
3399 | |
3400 getfsize({fname}) *getfsize()* | |
3401 The result is a Number, which is the size in bytes of the | |
3402 given file {fname}. | |
3403 If {fname} is a directory, 0 is returned. | |
3404 If the file {fname} can't be found, -1 is returned. | |
3405 If the size of {fname} is too big to fit in a Number then -2 | |
3406 is returned. | |
3407 | |
3408 Can also be used as a |method|: > | |
3409 GetFilename()->getfsize() | |
3410 | |
3411 getftime({fname}) *getftime()* | |
3412 The result is a Number, which is the last modification time of | |
3413 the given file {fname}. The value is measured as seconds | |
3414 since 1st Jan 1970, and may be passed to strftime(). See also | |
3415 |localtime()| and |strftime()|. | |
3416 If the file {fname} can't be found -1 is returned. | |
3417 | |
3418 Can also be used as a |method|: > | |
3419 GetFilename()->getftime() | |
3420 | |
3421 getftype({fname}) *getftype()* | |
3422 The result is a String, which is a description of the kind of | |
3423 file of the given file {fname}. | |
3424 If {fname} does not exist an empty string is returned. | |
3425 Here is a table over different kinds of files and their | |
3426 results: | |
3427 Normal file "file" | |
3428 Directory "dir" | |
3429 Symbolic link "link" | |
3430 Block device "bdev" | |
3431 Character device "cdev" | |
3432 Socket "socket" | |
3433 FIFO "fifo" | |
3434 All other "other" | |
3435 Example: > | |
3436 getftype("/home") | |
3437 < Note that a type such as "link" will only be returned on | |
3438 systems that support it. On some systems only "dir" and | |
3439 "file" are returned. On MS-Windows a symbolic link to a | |
3440 directory returns "dir" instead of "link". | |
3441 | |
3442 Can also be used as a |method|: > | |
3443 GetFilename()->getftype() | |
3444 | |
3445 getimstatus() *getimstatus()* | |
3446 The result is a Number, which is |TRUE| when the IME status is | |
3447 active. | |
3448 See 'imstatusfunc'. | |
3449 | |
3450 getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* | |
3451 Returns the |jumplist| for the specified window. | |
3452 | |
3453 Without arguments use the current window. | |
3454 With {winnr} only use this window in the current tab page. | |
3455 {winnr} can also be a |window-ID|. | |
3456 With {winnr} and {tabnr} use the window in the specified tab | |
3457 page. | |
3458 | |
3459 The returned list contains two entries: a list with the jump | |
3460 locations and the last used jump position number in the list. | |
3461 Each entry in the jump location list is a dictionary with | |
3462 the following entries: | |
3463 bufnr buffer number | |
3464 col column number | |
3465 coladd column offset for 'virtualedit' | |
3466 filename filename if available | |
3467 lnum line number | |
3468 | |
3469 Can also be used as a |method|: > | |
3470 GetWinnr()->getjumplist() | |
3471 | |
3472 < *getline()* | |
3473 getline({lnum} [, {end}]) | |
3474 Without {end} the result is a String, which is line {lnum} | |
3475 from the current buffer. Example: > | |
3476 getline(1) | |
3477 < When {lnum} is a String that doesn't start with a | |
3478 digit, |line()| is called to translate the String into a Number. | |
3479 To get the line under the cursor: > | |
3480 getline(".") | |
3481 < When {lnum} is a number smaller than 1 or bigger than the | |
3482 number of lines in the buffer, an empty string is returned. | |
3483 | |
3484 When {end} is given the result is a |List| where each item is | |
3485 a line from the current buffer in the range {lnum} to {end}, | |
3486 including line {end}. | |
3487 {end} is used in the same way as {lnum}. | |
3488 Non-existing lines are silently omitted. | |
3489 When {end} is before {lnum} an empty |List| is returned. | |
3490 Example: > | |
3491 :let start = line('.') | |
3492 :let end = search("^$") - 1 | |
3493 :let lines = getline(start, end) | |
3494 | |
3495 < Can also be used as a |method|: > | |
3496 ComputeLnum()->getline() | |
3497 | |
3498 < To get lines from another buffer see |getbufline()| | |
3499 | |
3500 getloclist({nr} [, {what}]) *getloclist()* | |
3501 Returns a |List| with all the entries in the location list for | |
3502 window {nr}. {nr} can be the window number or the |window-ID|. | |
3503 When {nr} is zero the current window is used. | |
3504 | |
3505 For a location list window, the displayed location list is | |
3506 returned. For an invalid window number {nr}, an empty list is | |
3507 returned. Otherwise, same as |getqflist()|. | |
3508 | |
3509 If the optional {what} dictionary argument is supplied, then | |
3510 returns the items listed in {what} as a dictionary. Refer to | |
3511 |getqflist()| for the supported items in {what}. | |
3512 | |
3513 In addition to the items supported by |getqflist()| in {what}, | |
3514 the following item is supported by |getloclist()|: | |
3515 | |
3516 filewinid id of the window used to display files | |
3517 from the location list. This field is | |
3518 applicable only when called from a | |
3519 location list window. See | |
3520 |location-list-file-window| for more | |
3521 details. | |
3522 | |
3523 Returns a |Dictionary| with default values if there is no | |
3524 location list for the window {nr}. | |
3525 Returns an empty Dictionary if window {nr} does not exist. | |
3526 | |
3527 Examples (See also |getqflist-examples|): > | |
3528 :echo getloclist(3, {'all': 0}) | |
3529 :echo getloclist(5, {'filewinid': 0}) | |
3530 | |
3531 | |
3532 getmarklist([{buf}]) *getmarklist()* | |
3533 Without the {buf} argument returns a |List| with information | |
3534 about all the global marks. |mark| | |
3535 | |
3536 If the optional {buf} argument is specified, returns the | |
3537 local marks defined in buffer {buf}. For the use of {buf}, | |
3538 see |bufname()|. | |
3539 | |
3540 Each item in the returned List is a |Dict| with the following: | |
3541 mark name of the mark prefixed by "'" | |
3542 pos a |List| with the position of the mark: | |
3543 [bufnum, lnum, col, off] | |
3544 Refer to |getpos()| for more information. | |
3545 file file name | |
3546 | |
3547 Refer to |getpos()| for getting information about a specific | |
3548 mark. | |
3549 | |
3550 Can also be used as a |method|: > | |
3551 GetBufnr()->getmarklist() | |
3552 | |
3553 getmatches([{win}]) *getmatches()* | |
3554 Returns a |List| with all matches previously defined for the | |
3555 current window by |matchadd()| and the |:match| commands. | |
3556 |getmatches()| is useful in combination with |setmatches()|, | |
3557 as |setmatches()| can restore a list of matches saved by | |
3558 |getmatches()|. | |
3559 If {win} is specified, use the window with this number or | |
3560 window ID instead of the current window. | |
3561 Example: > | |
3562 :echo getmatches() | |
3563 < [{'group': 'MyGroup1', 'pattern': 'TODO', | |
3564 'priority': 10, 'id': 1}, {'group': 'MyGroup2', | |
3565 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > | |
3566 :let m = getmatches() | |
3567 :call clearmatches() | |
3568 :echo getmatches() | |
3569 < [] > | |
3570 :call setmatches(m) | |
3571 :echo getmatches() | |
3572 < [{'group': 'MyGroup1', 'pattern': 'TODO', | |
3573 'priority': 10, 'id': 1}, {'group': 'MyGroup2', | |
3574 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > | |
3575 :unlet m | |
3576 < | |
3577 getmousepos() *getmousepos()* | |
3578 Returns a |Dictionary| with the last known position of the | |
3579 mouse. This can be used in a mapping for a mouse click or in | |
3580 a filter of a popup window. The items are: | |
3581 screenrow screen row | |
3582 screencol screen column | |
3583 winid Window ID of the click | |
3584 winrow row inside "winid" | |
3585 wincol column inside "winid" | |
3586 line text line inside "winid" | |
3587 column text column inside "winid" | |
3588 All numbers are 1-based. | |
3589 | |
3590 If not over a window, e.g. when in the command line, then only | |
3591 "screenrow" and "screencol" are valid, the others are zero. | |
3592 | |
3593 When on the status line below a window or the vertical | |
3594 separator right of a window, the "line" and "column" values | |
3595 are zero. | |
3596 | |
3597 When the position is after the text then "column" is the | |
3598 length of the text in bytes plus one. | |
3599 | |
3600 If the mouse is over a popup window then that window is used. | |
3601 | |
3602 When using |getchar()| the Vim variables |v:mouse_lnum|, | |
3603 |v:mouse_col| and |v:mouse_winid| also provide these values. | |
3604 | |
3605 *getpid()* | |
3606 getpid() Return a Number which is the process ID of the Vim process. | |
3607 On Unix and MS-Windows this is a unique number, until Vim | |
3608 exits. | |
3609 | |
3610 *getpos()* | |
3611 getpos({expr}) Get the position for String {expr}. For possible values of | |
3612 {expr} see |line()|. For getting the cursor position see | |
3613 |getcurpos()|. | |
3614 The result is a |List| with four numbers: | |
3615 [bufnum, lnum, col, off] | |
3616 "bufnum" is zero, unless a mark like '0 or 'A is used, then it | |
3617 is the buffer number of the mark. | |
3618 "lnum" and "col" are the position in the buffer. The first | |
3619 column is 1. | |
3620 The "off" number is zero, unless 'virtualedit' is used. Then | |
3621 it is the offset in screen columns from the start of the | |
3622 character. E.g., a position within a <Tab> or after the last | |
3623 character. | |
3624 Note that for '< and '> Visual mode matters: when it is "V" | |
3625 (visual line mode) the column of '< is zero and the column of | |
3626 '> is a large number. | |
3627 The column number in the returned List is the byte position | |
3628 within the line. To get the character position in the line, | |
3629 use |getcharpos()|. | |
3630 The column number can be very large, e.g. 2147483647, in which | |
3631 case it means "after the end of the line". | |
3632 This can be used to save and restore the position of a mark: > | |
3633 let save_a_mark = getpos("'a") | |
3634 ... | |
3635 call setpos("'a", save_a_mark) | |
3636 < Also see |getcharpos()|, |getcurpos()| and |setpos()|. | |
3637 | |
3638 Can also be used as a |method|: > | |
3639 GetMark()->getpos() | |
3640 | |
3641 getqflist([{what}]) *getqflist()* | |
3642 Returns a |List| with all the current quickfix errors. Each | |
3643 list item is a dictionary with these entries: | |
3644 bufnr number of buffer that has the file name, use | |
3645 bufname() to get the name | |
3646 module module name | |
3647 lnum line number in the buffer (first line is 1) | |
3648 end_lnum | |
3649 end of line number if the item is multiline | |
3650 col column number (first column is 1) | |
3651 end_col end of column number if the item has range | |
3652 vcol |TRUE|: "col" is visual column | |
3653 |FALSE|: "col" is byte index | |
3654 nr error number | |
3655 pattern search pattern used to locate the error | |
3656 text description of the error | |
3657 type type of the error, 'E', '1', etc. | |
3658 valid |TRUE|: recognized error message | |
3659 | |
3660 When there is no error list or it's empty, an empty list is | |
3661 returned. Quickfix list entries with a non-existing buffer | |
3662 number are returned with "bufnr" set to zero (Note: some | |
3663 functions accept buffer number zero for the alternate buffer, | |
3664 you may need to explicitly check for zero). | |
3665 | |
3666 Useful application: Find pattern matches in multiple files and | |
3667 do something with them: > | |
3668 :vimgrep /theword/jg *.c | |
3669 :for d in getqflist() | |
3670 : echo bufname(d.bufnr) ':' d.lnum '=' d.text | |
3671 :endfor | |
3672 < | |
3673 If the optional {what} dictionary argument is supplied, then | |
3674 returns only the items listed in {what} as a dictionary. The | |
3675 following string items are supported in {what}: | |
3676 changedtick get the total number of changes made | |
3677 to the list |quickfix-changedtick| | |
3678 context get the |quickfix-context| | |
3679 efm errorformat to use when parsing "lines". If | |
3680 not present, then the 'errorformat' option | |
3681 value is used. | |
3682 id get information for the quickfix list with | |
3683 |quickfix-ID|; zero means the id for the | |
3684 current list or the list specified by "nr" | |
3685 idx get information for the quickfix entry at this | |
3686 index in the list specified by 'id' or 'nr'. | |
3687 If set to zero, then uses the current entry. | |
3688 See |quickfix-index| | |
3689 items quickfix list entries | |
3690 lines parse a list of lines using 'efm' and return | |
3691 the resulting entries. Only a |List| type is | |
3692 accepted. The current quickfix list is not | |
3693 modified. See |quickfix-parse|. | |
3694 nr get information for this quickfix list; zero | |
3695 means the current quickfix list and "$" means | |
3696 the last quickfix list | |
3697 qfbufnr number of the buffer displayed in the quickfix | |
3698 window. Returns 0 if the quickfix buffer is | |
3699 not present. See |quickfix-buffer|. | |
3700 size number of entries in the quickfix list | |
3701 title get the list title |quickfix-title| | |
3702 winid get the quickfix |window-ID| | |
3703 all all of the above quickfix properties | |
3704 Non-string items in {what} are ignored. To get the value of a | |
3705 particular item, set it to zero. | |
3706 If "nr" is not present then the current quickfix list is used. | |
3707 If both "nr" and a non-zero "id" are specified, then the list | |
3708 specified by "id" is used. | |
3709 To get the number of lists in the quickfix stack, set "nr" to | |
3710 "$" in {what}. The "nr" value in the returned dictionary | |
3711 contains the quickfix stack size. | |
3712 When "lines" is specified, all the other items except "efm" | |
3713 are ignored. The returned dictionary contains the entry | |
3714 "items" with the list of entries. | |
3715 | |
3716 The returned dictionary contains the following entries: | |
3717 changedtick total number of changes made to the | |
3718 list |quickfix-changedtick| | |
3719 context quickfix list context. See |quickfix-context| | |
3720 If not present, set to "". | |
3721 id quickfix list ID |quickfix-ID|. If not | |
3722 present, set to 0. | |
3723 idx index of the quickfix entry in the list. If not | |
3724 present, set to 0. | |
3725 items quickfix list entries. If not present, set to | |
3726 an empty list. | |
3727 nr quickfix list number. If not present, set to 0 | |
3728 qfbufnr number of the buffer displayed in the quickfix | |
3729 window. If not present, set to 0. | |
3730 size number of entries in the quickfix list. If not | |
3731 present, set to 0. | |
3732 title quickfix list title text. If not present, set | |
3733 to "". | |
3734 winid quickfix |window-ID|. If not present, set to 0 | |
3735 | |
3736 Examples (See also |getqflist-examples|): > | |
3737 :echo getqflist({'all': 1}) | |
3738 :echo getqflist({'nr': 2, 'title': 1}) | |
3739 :echo getqflist({'lines' : ["F1:10:L10"]}) | |
3740 < | |
3741 getreg([{regname} [, 1 [, {list}]]]) *getreg()* | |
3742 The result is a String, which is the contents of register | |
3743 {regname}. Example: > | |
3744 :let cliptext = getreg('*') | |
3745 < When register {regname} was not set the result is an empty | |
3746 string. | |
3747 The {regname} argument must be a string. | |
3748 | |
3749 getreg('=') returns the last evaluated value of the expression | |
3750 register. (For use in maps.) | |
3751 getreg('=', 1) returns the expression itself, so that it can | |
3752 be restored with |setreg()|. For other registers the extra | |
3753 argument is ignored, thus you can always give it. | |
3754 | |
3755 If {list} is present and |TRUE|, the result type is changed | |
3756 to |List|. Each list item is one text line. Use it if you care | |
3757 about zero bytes possibly present inside register: without | |
3758 third argument both NLs and zero bytes are represented as NLs | |
3759 (see |NL-used-for-Nul|). | |
3760 When the register was not set an empty list is returned. | |
3761 | |
3762 If {regname} is "", the unnamed register '"' is used. | |
3763 If {regname} is not specified, |v:register| is used. | |
3764 In |Vim9-script| {regname} must be one character. | |
3765 | |
3766 Can also be used as a |method|: > | |
3767 GetRegname()->getreg() | |
3768 | |
3769 getreginfo([{regname}]) *getreginfo()* | |
3770 Returns detailed information about register {regname} as a | |
3771 Dictionary with the following entries: | |
3772 regcontents List of lines contained in register | |
3773 {regname}, like | |
3774 |getreg|({regname}, 1, 1). | |
3775 regtype the type of register {regname}, as in | |
3776 |getregtype()|. | |
3777 isunnamed Boolean flag, v:true if this register | |
3778 is currently pointed to by the unnamed | |
3779 register. | |
3780 points_to for the unnamed register, gives the | |
3781 single letter name of the register | |
3782 currently pointed to (see |quotequote|). | |
3783 For example, after deleting a line | |
3784 with `dd`, this field will be "1", | |
3785 which is the register that got the | |
3786 deleted text. | |
3787 | |
3788 The {regname} argument is a string. If {regname} is invalid | |
3789 or not set, an empty Dictionary will be returned. | |
3790 If {regname} is "" or "@", the unnamed register '"' is used. | |
3791 If {regname} is not specified, |v:register| is used. | |
3792 The returned Dictionary can be passed to |setreg()|. | |
3793 In |Vim9-script| {regname} must be one character. | |
3794 | |
3795 Can also be used as a |method|: > | |
3796 GetRegname()->getreginfo() | |
3797 | |
3798 getregtype([{regname}]) *getregtype()* | |
3799 The result is a String, which is type of register {regname}. | |
3800 The value will be one of: | |
3801 "v" for |characterwise| text | |
3802 "V" for |linewise| text | |
3803 "<CTRL-V>{width}" for |blockwise-visual| text | |
3804 "" for an empty or unknown register | |
3805 <CTRL-V> is one character with value 0x16. | |
3806 The {regname} argument is a string. If {regname} is "", the | |
3807 unnamed register '"' is used. If {regname} is not specified, | |
3808 |v:register| is used. | |
3809 In |Vim9-script| {regname} must be one character. | |
3810 | |
3811 Can also be used as a |method|: > | |
3812 GetRegname()->getregtype() | |
3813 | |
3814 gettabinfo([{tabnr}]) *gettabinfo()* | |
3815 If {tabnr} is not specified, then information about all the | |
3816 tab pages is returned as a |List|. Each List item is a | |
3817 |Dictionary|. Otherwise, {tabnr} specifies the tab page | |
3818 number and information about that one is returned. If the tab | |
3819 page does not exist an empty List is returned. | |
3820 | |
3821 Each List item is a |Dictionary| with the following entries: | |
3822 tabnr tab page number. | |
3823 variables a reference to the dictionary with | |
3824 tabpage-local variables | |
3825 windows List of |window-ID|s in the tab page. | |
3826 | |
3827 Can also be used as a |method|: > | |
3828 GetTabnr()->gettabinfo() | |
3829 | |
3830 gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* | |
3831 Get the value of a tab-local variable {varname} in tab page | |
3832 {tabnr}. |t:var| | |
3833 Tabs are numbered starting with one. | |
3834 The {varname} argument is a string. When {varname} is empty a | |
3835 dictionary with all tab-local variables is returned. | |
3836 Note that the name without "t:" must be used. | |
3837 When the tab or variable doesn't exist {def} or an empty | |
3838 string is returned, there is no error message. | |
3839 | |
3840 Can also be used as a |method|: > | |
3841 GetTabnr()->gettabvar(varname) | |
3842 | |
3843 gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* | |
3844 Get the value of window-local variable {varname} in window | |
3845 {winnr} in tab page {tabnr}. | |
3846 The {varname} argument is a string. When {varname} is empty a | |
3847 dictionary with all window-local variables is returned. | |
3848 When {varname} is equal to "&" get the values of all | |
3849 window-local options in a |Dictionary|. | |
3850 Otherwise, when {varname} starts with "&" get the value of a | |
3851 window-local option. | |
3852 Note that {varname} must be the name without "w:". | |
3853 Tabs are numbered starting with one. For the current tabpage | |
3854 use |getwinvar()|. | |
3855 {winnr} can be the window number or the |window-ID|. | |
3856 When {winnr} is zero the current window is used. | |
3857 This also works for a global option, buffer-local option and | |
3858 window-local option, but it doesn't work for a global variable | |
3859 or buffer-local variable. | |
3860 When the tab, window or variable doesn't exist {def} or an | |
3861 empty string is returned, there is no error message. | |
3862 Examples: > | |
3863 :let list_is_on = gettabwinvar(1, 2, '&list') | |
3864 :echo "myvar = " . gettabwinvar(3, 1, 'myvar') | |
3865 < | |
3866 To obtain all window-local variables use: > | |
3867 gettabwinvar({tabnr}, {winnr}, '&') | |
3868 | |
3869 < Can also be used as a |method|: > | |
3870 GetTabnr()->gettabwinvar(winnr, varname) | |
3871 | |
3872 gettagstack([{winnr}]) *gettagstack()* | |
3873 The result is a Dict, which is the tag stack of window {winnr}. | |
3874 {winnr} can be the window number or the |window-ID|. | |
3875 When {winnr} is not specified, the current window is used. | |
3876 When window {winnr} doesn't exist, an empty Dict is returned. | |
3877 | |
3878 The returned dictionary contains the following entries: | |
3879 curidx Current index in the stack. When at | |
3880 top of the stack, set to (length + 1). | |
3881 Index of bottom of the stack is 1. | |
3882 items List of items in the stack. Each item | |
3883 is a dictionary containing the | |
3884 entries described below. | |
3885 length Number of entries in the stack. | |
3886 | |
3887 Each item in the stack is a dictionary with the following | |
3888 entries: | |
3889 bufnr buffer number of the current jump | |
3890 from cursor position before the tag jump. | |
3891 See |getpos()| for the format of the | |
3892 returned list. | |
3893 matchnr current matching tag number. Used when | |
3894 multiple matching tags are found for a | |
3895 name. | |
3896 tagname name of the tag | |
3897 | |
3898 See |tagstack| for more information about the tag stack. | |
3899 | |
3900 Can also be used as a |method|: > | |
3901 GetWinnr()->gettagstack() | |
3902 | |
3903 | |
3904 gettext({text}) *gettext()* | |
3905 Translate String {text} if possible. | |
3906 This is mainly for use in the distributed Vim scripts. When | |
3907 generating message translations the {text} is extracted by | |
3908 xgettext, the translator can add the translated message in the | |
3909 .po file and Vim will lookup the translation when gettext() is | |
3910 called. | |
3911 For {text} double quoted strings are preferred, because | |
3912 xgettext does not understand escaping in single quoted | |
3913 strings. | |
3914 | |
3915 | |
3916 getwininfo([{winid}]) *getwininfo()* | |
3917 Returns information about windows as a |List| with Dictionaries. | |
3918 | |
3919 If {winid} is given Information about the window with that ID | |
3920 is returned, as a |List| with one item. If the window does not | |
3921 exist the result is an empty list. | |
3922 | |
3923 Without {winid} information about all the windows in all the | |
3924 tab pages is returned. | |
3925 | |
3926 Each List item is a |Dictionary| with the following entries: | |
3927 botline last complete displayed buffer line | |
3928 bufnr number of buffer in the window | |
3929 height window height (excluding winbar) | |
3930 loclist 1 if showing a location list | |
3931 {only with the +quickfix feature} | |
3932 quickfix 1 if quickfix or location list window | |
3933 {only with the +quickfix feature} | |
3934 terminal 1 if a terminal window | |
3935 {only with the +terminal feature} | |
3936 tabnr tab page number | |
3937 topline first displayed buffer line | |
3938 variables a reference to the dictionary with | |
3939 window-local variables | |
3940 width window width | |
3941 winbar 1 if the window has a toolbar, 0 | |
3942 otherwise | |
3943 wincol leftmost screen column of the window; | |
3944 "col" from |win_screenpos()| | |
3945 textoff number of columns occupied by any | |
3946 'foldcolumn', 'signcolumn' and line | |
3947 number in front of the text | |
3948 winid |window-ID| | |
3949 winnr window number | |
3950 winrow topmost screen line of the window; | |
3951 "row" from |win_screenpos()| | |
3952 | |
3953 Can also be used as a |method|: > | |
3954 GetWinnr()->getwininfo() | |
3955 | |
3956 getwinpos([{timeout}]) *getwinpos()* | |
3957 The result is a |List| with two numbers, the result of | |
3958 |getwinposx()| and |getwinposy()| combined: | |
3959 [x-pos, y-pos] | |
3960 {timeout} can be used to specify how long to wait in msec for | |
3961 a response from the terminal. When omitted 100 msec is used. | |
3962 Use a longer time for a remote terminal. | |
3963 When using a value less than 10 and no response is received | |
3964 within that time, a previously reported position is returned, | |
3965 if available. This can be used to poll for the position and | |
3966 do some work in the meantime: > | |
3967 while 1 | |
3968 let res = getwinpos(1) | |
3969 if res[0] >= 0 | |
3970 break | |
3971 endif | |
3972 " Do some work here | |
3973 endwhile | |
3974 < | |
3975 | |
3976 Can also be used as a |method|: > | |
3977 GetTimeout()->getwinpos() | |
3978 < | |
3979 *getwinposx()* | |
3980 getwinposx() The result is a Number, which is the X coordinate in pixels of | |
3981 the left hand side of the GUI Vim window. Also works for an | |
3982 xterm (uses a timeout of 100 msec). | |
3983 The result will be -1 if the information is not available. | |
3984 The value can be used with `:winpos`. | |
3985 | |
3986 *getwinposy()* | |
3987 getwinposy() The result is a Number, which is the Y coordinate in pixels of | |
3988 the top of the GUI Vim window. Also works for an xterm (uses | |
3989 a timeout of 100 msec). | |
3990 The result will be -1 if the information is not available. | |
3991 The value can be used with `:winpos`. | |
3992 | |
3993 getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* | |
3994 Like |gettabwinvar()| for the current tabpage. | |
3995 Examples: > | |
3996 :let list_is_on = getwinvar(2, '&list') | |
3997 :echo "myvar = " . getwinvar(1, 'myvar') | |
3998 | |
3999 < Can also be used as a |method|: > | |
4000 GetWinnr()->getwinvar(varname) | |
4001 < | |
4002 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* | |
4003 Expand the file wildcards in {expr}. See |wildcards| for the | |
4004 use of special characters. | |
4005 | |
4006 Unless the optional {nosuf} argument is given and is |TRUE|, | |
4007 the 'suffixes' and 'wildignore' options apply: Names matching | |
4008 one of the patterns in 'wildignore' will be skipped and | |
4009 'suffixes' affect the ordering of matches. | |
4010 'wildignorecase' always applies. | |
4011 | |
4012 When {list} is present and it is |TRUE| the result is a |List| | |
4013 with all matching files. The advantage of using a List is, | |
4014 you also get filenames containing newlines correctly. | |
4015 Otherwise the result is a String and when there are several | |
4016 matches, they are separated by <NL> characters. | |
4017 | |
4018 If the expansion fails, the result is an empty String or List. | |
4019 | |
4020 You can also use |readdir()| if you need to do complicated | |
4021 things, such as limiting the number of matches. | |
4022 | |
4023 A name for a non-existing file is not included. A symbolic | |
4024 link is only included if it points to an existing file. | |
4025 However, when the {alllinks} argument is present and it is | |
4026 |TRUE| then all symbolic links are included. | |
4027 | |
4028 For most systems backticks can be used to get files names from | |
4029 any external command. Example: > | |
4030 :let tagfiles = glob("`find . -name tags -print`") | |
4031 :let &tags = substitute(tagfiles, "\n", ",", "g") | |
4032 < The result of the program inside the backticks should be one | |
4033 item per line. Spaces inside an item are allowed. | |
4034 | |
4035 See |expand()| for expanding special Vim variables. See | |
4036 |system()| for getting the raw output of an external command. | |
4037 | |
4038 Can also be used as a |method|: > | |
4039 GetExpr()->glob() | |
4040 | |
4041 glob2regpat({string}) *glob2regpat()* | |
4042 Convert a file pattern, as used by glob(), into a search | |
4043 pattern. The result can be used to match with a string that | |
4044 is a file name. E.g. > | |
4045 if filename =~ glob2regpat('Make*.mak') | |
4046 < This is equivalent to: > | |
4047 if filename =~ '^Make.*\.mak$' | |
4048 < When {string} is an empty string the result is "^$", match an | |
4049 empty string. | |
4050 Note that the result depends on the system. On MS-Windows | |
4051 a backslash usually means a path separator. | |
4052 | |
4053 Can also be used as a |method|: > | |
4054 GetExpr()->glob2regpat() | |
4055 < *globpath()* | |
4056 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
4057 Perform glob() for String {expr} on all directories in {path} | |
4058 and concatenate the results. Example: > | |
4059 :echo globpath(&rtp, "syntax/c.vim") | |
4060 < | |
4061 {path} is a comma-separated list of directory names. Each | |
4062 directory name is prepended to {expr} and expanded like with | |
4063 |glob()|. A path separator is inserted when needed. | |
4064 To add a comma inside a directory name escape it with a | |
4065 backslash. Note that on MS-Windows a directory may have a | |
4066 trailing backslash, remove it if you put a comma after it. | |
4067 If the expansion fails for one of the directories, there is no | |
4068 error message. | |
4069 | |
4070 Unless the optional {nosuf} argument is given and is |TRUE|, | |
4071 the 'suffixes' and 'wildignore' options apply: Names matching | |
4072 one of the patterns in 'wildignore' will be skipped and | |
4073 'suffixes' affect the ordering of matches. | |
4074 | |
4075 When {list} is present and it is |TRUE| the result is a |List| | |
4076 with all matching files. The advantage of using a List is, you | |
4077 also get filenames containing newlines correctly. Otherwise | |
4078 the result is a String and when there are several matches, | |
4079 they are separated by <NL> characters. Example: > | |
4080 :echo globpath(&rtp, "syntax/c.vim", 0, 1) | |
4081 < | |
4082 {alllinks} is used as with |glob()|. | |
4083 | |
4084 The "**" item can be used to search in a directory tree. | |
4085 For example, to find all "README.txt" files in the directories | |
4086 in 'runtimepath' and below: > | |
4087 :echo globpath(&rtp, "**/README.txt") | |
4088 < Upwards search and limiting the depth of "**" is not | |
4089 supported, thus using 'path' will not always work properly. | |
4090 | |
4091 Can also be used as a |method|, the base is passed as the | |
4092 second argument: > | |
4093 GetExpr()->globpath(&rtp) | |
4094 < | |
4095 *has()* | |
4096 has({feature} [, {check}]) | |
4097 When {check} is omitted or is zero: The result is a Number, | |
4098 which is 1 if the feature {feature} is supported, zero | |
4099 otherwise. The {feature} argument is a string, case is | |
4100 ignored. See |feature-list| below. | |
4101 | |
4102 When {check} is present and not zero: The result is a Number, | |
4103 which is 1 if the feature {feature} could ever be supported, | |
4104 zero otherwise. This is useful to check for a typo in | |
4105 {feature} and to detect dead code. Keep in mind that an older | |
4106 Vim version will not know about a feature added later and | |
4107 features that have been abandoned will not be known by the | |
4108 current Vim version. | |
4109 | |
4110 Also see |exists()| and |exists_compiled()|. | |
4111 | |
4112 Note that to skip code that has a syntax error when the | |
4113 feature is not available, Vim may skip the rest of the line | |
4114 and miss a following `endif`. Therefore put the `endif` on a | |
4115 separate line: > | |
4116 if has('feature') | |
4117 let x = this->breaks->without->the->feature | |
4118 endif | |
4119 < If the `endif` would be moved to the second line as "| endif" it | |
4120 would not be found. | |
4121 | |
4122 | |
4123 has_key({dict}, {key}) *has_key()* | |
4124 The result is a Number, which is TRUE if |Dictionary| {dict} | |
4125 has an entry with key {key}. FALSE otherwise. The {key} | |
4126 argument is a string. | |
4127 | |
4128 Can also be used as a |method|: > | |
4129 mydict->has_key(key) | |
4130 | |
4131 haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* | |
4132 The result is a Number: | |
4133 1 when the window has set a local directory via |:lcd| | |
4134 2 when the tab-page has set a local directory via |:tcd| | |
4135 0 otherwise. | |
4136 | |
4137 Without arguments use the current window. | |
4138 With {winnr} use this window in the current tab page. | |
4139 With {winnr} and {tabnr} use the window in the specified tab | |
4140 page. | |
4141 {winnr} can be the window number or the |window-ID|. | |
4142 If {winnr} is -1 it is ignored and only the tabpage is used. | |
4143 Return 0 if the arguments are invalid. | |
4144 Examples: > | |
4145 if haslocaldir() == 1 | |
4146 " window local directory case | |
4147 elseif haslocaldir() == 2 | |
4148 " tab-local directory case | |
4149 else | |
4150 " global directory case | |
4151 endif | |
4152 | |
4153 " current window | |
4154 :echo haslocaldir() | |
4155 :echo haslocaldir(0) | |
4156 :echo haslocaldir(0, 0) | |
4157 " window n in current tab page | |
4158 :echo haslocaldir(n) | |
4159 :echo haslocaldir(n, 0) | |
4160 " window n in tab page m | |
4161 :echo haslocaldir(n, m) | |
4162 " tab page m | |
4163 :echo haslocaldir(-1, m) | |
4164 < | |
4165 Can also be used as a |method|: > | |
4166 GetWinnr()->haslocaldir() | |
4167 | |
4168 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* | |
4169 The result is a Number, which is TRUE if there is a mapping | |
4170 that contains {what} in somewhere in the rhs (what it is | |
4171 mapped to) and this mapping exists in one of the modes | |
4172 indicated by {mode}. | |
4173 The arguments {what} and {mode} are strings. | |
4174 When {abbr} is there and it is |TRUE| use abbreviations | |
4175 instead of mappings. Don't forget to specify Insert and/or | |
4176 Command-line mode. | |
4177 Both the global mappings and the mappings local to the current | |
4178 buffer are checked for a match. | |
4179 If no matching mapping is found FALSE is returned. | |
4180 The following characters are recognized in {mode}: | |
4181 n Normal mode | |
4182 v Visual and Select mode | |
4183 x Visual mode | |
4184 s Select mode | |
4185 o Operator-pending mode | |
4186 i Insert mode | |
4187 l Language-Argument ("r", "f", "t", etc.) | |
4188 c Command-line mode | |
4189 When {mode} is omitted, "nvo" is used. | |
4190 | |
4191 This function is useful to check if a mapping already exists | |
4192 to a function in a Vim script. Example: > | |
4193 :if !hasmapto('\ABCdoit') | |
4194 : map <Leader>d \ABCdoit | |
4195 :endif | |
4196 < This installs the mapping to "\ABCdoit" only if there isn't | |
4197 already a mapping to "\ABCdoit". | |
4198 | |
4199 Can also be used as a |method|: > | |
4200 GetRHS()->hasmapto() | |
4201 | |
4202 histadd({history}, {item}) *histadd()* | |
4203 Add the String {item} to the history {history} which can be | |
4204 one of: *hist-names* | |
4205 "cmd" or ":" command line history | |
4206 "search" or "/" search pattern history | |
4207 "expr" or "=" typed expression history | |
4208 "input" or "@" input line history | |
4209 "debug" or ">" debug command history | |
4210 empty the current or last used history | |
4211 The {history} string does not need to be the whole name, one | |
4212 character is sufficient. | |
4213 If {item} does already exist in the history, it will be | |
4214 shifted to become the newest entry. | |
4215 The result is a Number: TRUE if the operation was successful, | |
4216 otherwise FALSE is returned. | |
4217 | |
4218 Example: > | |
4219 :call histadd("input", strftime("%Y %b %d")) | |
4220 :let date=input("Enter date: ") | |
4221 < This function is not available in the |sandbox|. | |
4222 | |
4223 Can also be used as a |method|, the base is passed as the | |
4224 second argument: > | |
4225 GetHistory()->histadd('search') | |
4226 | |
4227 histdel({history} [, {item}]) *histdel()* | |
4228 Clear {history}, i.e. delete all its entries. See |hist-names| | |
4229 for the possible values of {history}. | |
4230 | |
4231 If the parameter {item} evaluates to a String, it is used as a | |
4232 regular expression. All entries matching that expression will | |
4233 be removed from the history (if there are any). | |
4234 Upper/lowercase must match, unless "\c" is used |/\c|. | |
4235 If {item} evaluates to a Number, it will be interpreted as | |
4236 an index, see |:history-indexing|. The respective entry will | |
4237 be removed if it exists. | |
4238 | |
4239 The result is TRUE for a successful operation, otherwise FALSE | |
4240 is returned. | |
4241 | |
4242 Examples: | |
4243 Clear expression register history: > | |
4244 :call histdel("expr") | |
4245 < | |
4246 Remove all entries starting with "*" from the search history: > | |
4247 :call histdel("/", '^\*') | |
4248 < | |
4249 The following three are equivalent: > | |
4250 :call histdel("search", histnr("search")) | |
4251 :call histdel("search", -1) | |
4252 :call histdel("search", '^'.histget("search", -1).'$') | |
4253 < | |
4254 To delete the last search pattern and use the last-but-one for | |
4255 the "n" command and 'hlsearch': > | |
4256 :call histdel("search", -1) | |
4257 :let @/ = histget("search", -1) | |
4258 < | |
4259 Can also be used as a |method|: > | |
4260 GetHistory()->histdel() | |
4261 | |
4262 histget({history} [, {index}]) *histget()* | |
4263 The result is a String, the entry with Number {index} from | |
4264 {history}. See |hist-names| for the possible values of | |
4265 {history}, and |:history-indexing| for {index}. If there is | |
4266 no such entry, an empty String is returned. When {index} is | |
4267 omitted, the most recent item from the history is used. | |
4268 | |
4269 Examples: | |
4270 Redo the second last search from history. > | |
4271 :execute '/' . histget("search", -2) | |
4272 | |
4273 < Define an Ex command ":H {num}" that supports re-execution of | |
4274 the {num}th entry from the output of |:history|. > | |
4275 :command -nargs=1 H execute histget("cmd", 0+<args>) | |
4276 < | |
4277 Can also be used as a |method|: > | |
4278 GetHistory()->histget() | |
4279 | |
4280 histnr({history}) *histnr()* | |
4281 The result is the Number of the current entry in {history}. | |
4282 See |hist-names| for the possible values of {history}. | |
4283 If an error occurred, -1 is returned. | |
4284 | |
4285 Example: > | |
4286 :let inp_index = histnr("expr") | |
4287 | |
4288 < Can also be used as a |method|: > | |
4289 GetHistory()->histnr() | |
4290 < | |
4291 hlexists({name}) *hlexists()* | |
4292 The result is a Number, which is TRUE if a highlight group | |
4293 called {name} exists. This is when the group has been | |
4294 defined in some way. Not necessarily when highlighting has | |
4295 been defined for it, it may also have been used for a syntax | |
4296 item. | |
4297 *highlight_exists()* | |
4298 Obsolete name: highlight_exists(). | |
4299 | |
4300 Can also be used as a |method|: > | |
4301 GetName()->hlexists() | |
4302 < | |
4303 hlget([{name} [, {resolve}]]) *hlget()* | |
4304 Returns a List of all the highlight group attributes. If the | |
4305 optional {name} is specified, then returns a List with only | |
4306 the attributes of the specified highlight group. Returns an | |
4307 empty List if the highlight group {name} is not present. | |
4308 | |
4309 If the optional {resolve} argument is set to v:true and the | |
4310 highlight group {name} is linked to another group, then the | |
4311 link is resolved recursively and the attributes of the | |
4312 resolved highlight group are returned. | |
4313 | |
4314 Each entry in the returned List is a Dictionary with the | |
4315 following items: | |
4316 cleared boolean flag, set to v:true if the highlight | |
4317 group attributes are cleared or not yet | |
4318 specified. See |highlight-clear|. | |
4319 cterm cterm attributes. See |highlight-cterm|. | |
4320 ctermbg cterm background color. | |
4321 See |highlight-ctermbg|. | |
4322 ctermfg cterm foreground color. | |
4323 See |highlight-ctermfg|. | |
4324 ctermul cterm underline color. See |highlight-ctermul|. | |
4325 default boolean flag, set to v:true if the highlight | |
4326 group link is a default link. See | |
4327 |highlight-default|. | |
4328 font highlight group font. See |highlight-font|. | |
4329 gui gui attributes. See |highlight-gui|. | |
4330 guibg gui background color. See |highlight-guibg|. | |
4331 guifg gui foreground color. See |highlight-guifg|. | |
4332 guisp gui special color. See |highlight-guisp|. | |
4333 id highlight group ID. | |
4334 linksto linked highlight group name. | |
4335 See |:highlight-link|. | |
4336 name highlight group name. See |group-name|. | |
4337 start start terminal keycode. See |highlight-start|. | |
4338 stop stop terminal keycode. See |highlight-stop|. | |
4339 term term attributes. See |highlight-term|. | |
4340 | |
4341 The 'term', 'cterm' and 'gui' items in the above Dictionary | |
4342 have a dictionary value with the following optional boolean | |
4343 items: 'bold', 'standout', 'underline', 'undercurl', 'italic', | |
4344 'reverse', 'inverse' and 'strikethrough'. | |
4345 | |
4346 Example(s): > | |
4347 :echo hlget() | |
4348 :echo hlget('ModeMsg') | |
4349 :echo hlget('Number', v:true) | |
4350 < | |
4351 Can also be used as a |method|: > | |
4352 GetName()->hlget() | |
4353 < | |
4354 hlset({list}) *hlset()* | |
4355 Creates or modifies the attributes of a List of highlight | |
4356 groups. Each item in {list} is a dictionary containing the | |
4357 attributes of a highlight group. See |hlget()| for the list of | |
4358 supported items in this dictionary. | |
4359 | |
4360 In addition to the items described in |hlget()|, the following | |
4361 additional items are supported in the dictionary: | |
4362 | |
4363 force boolean flag to force the creation of | |
4364 a link for an existing highlight group | |
4365 with attributes. | |
4366 | |
4367 The highlight group is identified using the 'name' item and | |
4368 the 'id' item (if supplied) is ignored. If a highlight group | |
4369 with a specified name doesn't exist, then it is created. | |
4370 Otherwise the attributes of an existing highlight group are | |
4371 modified. | |
4372 | |
4373 If an empty dictionary value is used for the 'term' or 'cterm' | |
4374 or 'gui' entries, then the corresponding attributes are | |
4375 cleared. If the 'cleared' item is set to v:true, then all the | |
4376 attributes of the highlight group are cleared. | |
4377 | |
4378 The 'linksto' item can be used to link a highlight group to | |
4379 another highlight group. See |:highlight-link|. | |
4380 | |
4381 Returns zero for success, -1 for failure. | |
4382 | |
4383 Example(s): > | |
4384 " add bold attribute to the Visual highlight group | |
4385 :call hlset([#{name: 'Visual', | |
4386 \ term: #{reverse: 1 , bold: 1}}]) | |
4387 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) | |
4388 :let l = hlget() | |
4389 :call hlset(l) | |
4390 " clear the Search highlight group | |
4391 :call hlset([#{name: 'Search', cleared: v:true}]) | |
4392 " clear the 'term' attributes for a highlight group | |
4393 :call hlset([#{name: 'Title', term: {}}]) | |
4394 " create the MyHlg group linking it to DiffAdd | |
4395 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) | |
4396 " remove the MyHlg group link | |
4397 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}]) | |
4398 " clear the attributes and a link | |
4399 :call hlset([#{name: 'MyHlg', cleared: v:true, | |
4400 \ linksto: 'NONE'}]) | |
4401 < | |
4402 Can also be used as a |method|: > | |
4403 GetAttrList()->hlset() | |
4404 < | |
4405 *hlID()* | |
4406 hlID({name}) The result is a Number, which is the ID of the highlight group | |
4407 with name {name}. When the highlight group doesn't exist, | |
4408 zero is returned. | |
4409 This can be used to retrieve information about the highlight | |
4410 group. For example, to get the background color of the | |
4411 "Comment" group: > | |
4412 :echo synIDattr(synIDtrans(hlID("Comment")), "bg") | |
4413 < *highlightID()* | |
4414 Obsolete name: highlightID(). | |
4415 | |
4416 Can also be used as a |method|: > | |
4417 GetName()->hlID() | |
4418 | |
4419 hostname() *hostname()* | |
4420 The result is a String, which is the name of the machine on | |
4421 which Vim is currently running. Machine names greater than | |
4422 256 characters long are truncated. | |
4423 | |
4424 iconv({string}, {from}, {to}) *iconv()* | |
4425 The result is a String, which is the text {string} converted | |
4426 from encoding {from} to encoding {to}. | |
4427 When the conversion completely fails an empty string is | |
4428 returned. When some characters could not be converted they | |
4429 are replaced with "?". | |
4430 The encoding names are whatever the iconv() library function | |
4431 can accept, see ":!man 3 iconv". | |
4432 Most conversions require Vim to be compiled with the |+iconv| | |
4433 feature. Otherwise only UTF-8 to latin1 conversion and back | |
4434 can be done. | |
4435 This can be used to display messages with special characters, | |
4436 no matter what 'encoding' is set to. Write the message in | |
4437 UTF-8 and use: > | |
4438 echo iconv(utf8_str, "utf-8", &enc) | |
4439 < Note that Vim uses UTF-8 for all Unicode encodings, conversion | |
4440 from/to UCS-2 is automatically changed to use UTF-8. You | |
4441 cannot use UCS-2 in a string anyway, because of the NUL bytes. | |
4442 | |
4443 Can also be used as a |method|: > | |
4444 GetText()->iconv('latin1', 'utf-8') | |
4445 < | |
4446 *indent()* | |
4447 indent({lnum}) The result is a Number, which is indent of line {lnum} in the | |
4448 current buffer. The indent is counted in spaces, the value | |
4449 of 'tabstop' is relevant. {lnum} is used just like in | |
4450 |getline()|. | |
4451 When {lnum} is invalid -1 is returned. In |Vim9| script an | |
4452 error is given. | |
4453 | |
4454 Can also be used as a |method|: > | |
4455 GetLnum()->indent() | |
4456 | |
4457 index({object}, {expr} [, {start} [, {ic}]]) *index()* | |
4458 If {object} is a |List| return the lowest index where the item | |
4459 has a value equal to {expr}. There is no automatic | |
4460 conversion, so the String "4" is different from the Number 4. | |
4461 And the number 4 is different from the Float 4.0. The value | |
4462 of 'ignorecase' is not used here, case always matters. | |
4463 | |
4464 If {object} is |Blob| return the lowest index where the byte | |
4465 value is equal to {expr}. | |
4466 | |
4467 If {start} is given then start looking at the item with index | |
4468 {start} (may be negative for an item relative to the end). | |
4469 When {ic} is given and it is |TRUE|, ignore case. Otherwise | |
4470 case must match. | |
4471 -1 is returned when {expr} is not found in {object}. | |
4472 Example: > | |
4473 :let idx = index(words, "the") | |
4474 :if index(numbers, 123) >= 0 | |
4475 | |
4476 < Can also be used as a |method|: > | |
4477 GetObject()->index(what) | |
4478 | |
4479 input({prompt} [, {text} [, {completion}]]) *input()* | |
4480 The result is a String, which is whatever the user typed on | |
4481 the command-line. The {prompt} argument is either a prompt | |
4482 string, or a blank string (for no prompt). A '\n' can be used | |
4483 in the prompt to start a new line. | |
4484 The highlighting set with |:echohl| is used for the prompt. | |
4485 The input is entered just like a command-line, with the same | |
4486 editing commands and mappings. There is a separate history | |
4487 for lines typed for input(). | |
4488 Example: > | |
4489 :if input("Coffee or beer? ") == "beer" | |
4490 : echo "Cheers!" | |
4491 :endif | |
4492 < | |
4493 If the optional {text} argument is present and not empty, this | |
4494 is used for the default reply, as if the user typed this. | |
4495 Example: > | |
4496 :let color = input("Color? ", "white") | |
4497 | |
4498 < The optional {completion} argument specifies the type of | |
4499 completion supported for the input. Without it completion is | |
4500 not performed. The supported completion types are the same as | |
4501 that can be supplied to a user-defined command using the | |
4502 "-complete=" argument. Refer to |:command-completion| for | |
4503 more information. Example: > | |
4504 let fname = input("File: ", "", "file") | |
4505 < | |
4506 NOTE: This function must not be used in a startup file, for | |
4507 the versions that only run in GUI mode (e.g., the Win32 GUI). | |
4508 Note: When input() is called from within a mapping it will | |
4509 consume remaining characters from that mapping, because a | |
4510 mapping is handled like the characters were typed. | |
4511 Use |inputsave()| before input() and |inputrestore()| | |
4512 after input() to avoid that. Another solution is to avoid | |
4513 that further characters follow in the mapping, e.g., by using | |
4514 |:execute| or |:normal|. | |
4515 | |
4516 Example with a mapping: > | |
4517 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR> | |
4518 :function GetFoo() | |
4519 : call inputsave() | |
4520 : let g:Foo = input("enter search pattern: ") | |
4521 : call inputrestore() | |
4522 :endfunction | |
4523 | |
4524 < Can also be used as a |method|: > | |
4525 GetPrompt()->input() | |
4526 | |
4527 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* | |
4528 Like |input()|, but when the GUI is running and text dialogs | |
4529 are supported, a dialog window pops up to input the text. | |
4530 Example: > | |
4531 :let n = inputdialog("value for shiftwidth", shiftwidth()) | |
4532 :if n != "" | |
4533 : let &sw = n | |
4534 :endif | |
4535 < When the dialog is cancelled {cancelreturn} is returned. When | |
4536 omitted an empty string is returned. | |
4537 Hitting <Enter> works like pressing the OK button. Hitting | |
4538 <Esc> works like pressing the Cancel button. | |
4539 NOTE: Command-line completion is not supported. | |
4540 | |
4541 Can also be used as a |method|: > | |
4542 GetPrompt()->inputdialog() | |
4543 | |
4544 inputlist({textlist}) *inputlist()* | |
4545 {textlist} must be a |List| of strings. This |List| is | |
4546 displayed, one string per line. The user will be prompted to | |
4547 enter a number, which is returned. | |
4548 The user can also select an item by clicking on it with the | |
4549 mouse, if the mouse is enabled in the command line ('mouse' is | |
4550 "a" or includes "c"). For the first string 0 is returned. | |
4551 When clicking above the first item a negative number is | |
4552 returned. When clicking on the prompt one more than the | |
4553 length of {textlist} is returned. | |
4554 Make sure {textlist} has less than 'lines' entries, otherwise | |
4555 it won't work. It's a good idea to put the entry number at | |
4556 the start of the string. And put a prompt in the first item. | |
4557 Example: > | |
4558 let color = inputlist(['Select color:', '1. red', | |
4559 \ '2. green', '3. blue']) | |
4560 | |
4561 < Can also be used as a |method|: > | |
4562 GetChoices()->inputlist() | |
4563 | |
4564 inputrestore() *inputrestore()* | |
4565 Restore typeahead that was saved with a previous |inputsave()|. | |
4566 Should be called the same number of times inputsave() is | |
4567 called. Calling it more often is harmless though. | |
4568 Returns TRUE when there is nothing to restore, FALSE otherwise. | |
4569 | |
4570 inputsave() *inputsave()* | |
4571 Preserve typeahead (also from mappings) and clear it, so that | |
4572 a following prompt gets input from the user. Should be | |
4573 followed by a matching inputrestore() after the prompt. Can | |
4574 be used several times, in which case there must be just as | |
4575 many inputrestore() calls. | |
4576 Returns TRUE when out of memory, FALSE otherwise. | |
4577 | |
4578 inputsecret({prompt} [, {text}]) *inputsecret()* | |
4579 This function acts much like the |input()| function with but | |
4580 two exceptions: | |
4581 a) the user's response will be displayed as a sequence of | |
4582 asterisks ("*") thereby keeping the entry secret, and | |
4583 b) the user's response will not be recorded on the input | |
4584 |history| stack. | |
4585 The result is a String, which is whatever the user actually | |
4586 typed on the command-line in response to the issued prompt. | |
4587 NOTE: Command-line completion is not supported. | |
4588 | |
4589 Can also be used as a |method|: > | |
4590 GetPrompt()->inputsecret() | |
4591 | |
4592 insert({object}, {item} [, {idx}]) *insert()* | |
4593 When {object} is a |List| or a |Blob| insert {item} at the start | |
4594 of it. | |
4595 | |
4596 If {idx} is specified insert {item} before the item with index | |
4597 {idx}. If {idx} is zero it goes before the first item, just | |
4598 like omitting {idx}. A negative {idx} is also possible, see | |
4599 |list-index|. -1 inserts just before the last item. | |
4600 | |
4601 Returns the resulting |List| or |Blob|. Examples: > | |
4602 :let mylist = insert([2, 3, 5], 1) | |
4603 :call insert(mylist, 4, -1) | |
4604 :call insert(mylist, 6, len(mylist)) | |
4605 < The last example can be done simpler with |add()|. | |
4606 Note that when {item} is a |List| it is inserted as a single | |
4607 item. Use |extend()| to concatenate |Lists|. | |
4608 | |
4609 Can also be used as a |method|: > | |
4610 mylist->insert(item) | |
4611 | |
4612 interrupt() *interrupt()* | |
4613 Interrupt script execution. It works more or less like the | |
4614 user typing CTRL-C, most commands won't execute and control | |
4615 returns to the user. This is useful to abort execution | |
4616 from lower down, e.g. in an autocommand. Example: > | |
4617 :function s:check_typoname(file) | |
4618 : if fnamemodify(a:file, ':t') == '[' | |
4619 : echomsg 'Maybe typo' | |
4620 : call interrupt() | |
4621 : endif | |
4622 :endfunction | |
4623 :au BufWritePre * call s:check_typoname(expand('<amatch>')) | |
4624 | |
4625 invert({expr}) *invert()* | |
4626 Bitwise invert. The argument is converted to a number. A | |
4627 List, Dict or Float argument causes an error. Example: > | |
4628 :let bits = invert(bits) | |
4629 < Can also be used as a |method|: > | |
4630 :let bits = bits->invert() | |
4631 | |
4632 isdirectory({directory}) *isdirectory()* | |
4633 The result is a Number, which is |TRUE| when a directory | |
4634 with the name {directory} exists. If {directory} doesn't | |
4635 exist, or isn't a directory, the result is |FALSE|. {directory} | |
4636 is any expression, which is used as a String. | |
4637 | |
4638 Can also be used as a |method|: > | |
4639 GetName()->isdirectory() | |
4640 | |
4641 isinf({expr}) *isinf()* | |
4642 Return 1 if {expr} is a positive infinity, or -1 a negative | |
4643 infinity, otherwise 0. > | |
4644 :echo isinf(1.0 / 0.0) | |
4645 < 1 > | |
4646 :echo isinf(-1.0 / 0.0) | |
4647 < -1 | |
4648 | |
4649 Can also be used as a |method|: > | |
4650 Compute()->isinf() | |
4651 < | |
4652 {only available when compiled with the |+float| feature} | |
4653 | |
4654 islocked({expr}) *islocked()* *E786* | |
4655 The result is a Number, which is |TRUE| when {expr} is the | |
4656 name of a locked variable. | |
4657 The string argument {expr} must be the name of a variable, | |
4658 |List| item or |Dictionary| entry, not the variable itself! | |
4659 Example: > | |
4660 :let alist = [0, ['a', 'b'], 2, 3] | |
4661 :lockvar 1 alist | |
4662 :echo islocked('alist') " 1 | |
4663 :echo islocked('alist[1]') " 0 | |
4664 | |
4665 < When {expr} is a variable that does not exist you get an error | |
4666 message. Use |exists()| to check for existence. | |
4667 In Vim9 script it does not work for local variables. | |
4668 | |
4669 Can also be used as a |method|: > | |
4670 GetName()->islocked() | |
4671 | |
4672 isnan({expr}) *isnan()* | |
4673 Return |TRUE| if {expr} is a float with value NaN. > | |
4674 echo isnan(0.0 / 0.0) | |
4675 < 1 | |
4676 | |
4677 Can also be used as a |method|: > | |
4678 Compute()->isnan() | |
4679 < | |
4680 {only available when compiled with the |+float| feature} | |
4681 | |
4682 items({dict}) *items()* | |
4683 Return a |List| with all the key-value pairs of {dict}. Each | |
4684 |List| item is a list with two items: the key of a {dict} | |
4685 entry and the value of this entry. The |List| is in arbitrary | |
4686 order. Also see |keys()| and |values()|. | |
4687 Example: > | |
4688 for [key, value] in items(mydict) | |
4689 echo key . ': ' . value | |
4690 endfor | |
4691 | |
4692 < Can also be used as a |method|: > | |
4693 mydict->items() | |
4694 | |
4695 job_ functions are documented here: |job-functions-details| | |
4696 | |
4697 | |
4698 join({list} [, {sep}]) *join()* | |
4699 Join the items in {list} together into one String. | |
4700 When {sep} is specified it is put in between the items. If | |
4701 {sep} is omitted a single space is used. | |
4702 Note that {sep} is not added at the end. You might want to | |
4703 add it there too: > | |
4704 let lines = join(mylist, "\n") . "\n" | |
4705 < String items are used as-is. |Lists| and |Dictionaries| are | |
4706 converted into a string like with |string()|. | |
4707 The opposite function is |split()|. | |
4708 | |
4709 Can also be used as a |method|: > | |
4710 mylist->join() | |
4711 | |
4712 js_decode({string}) *js_decode()* | |
4713 This is similar to |json_decode()| with these differences: | |
4714 - Object key names do not have to be in quotes. | |
4715 - Strings can be in single quotes. | |
4716 - Empty items in an array (between two commas) are allowed and | |
4717 result in v:none items. | |
4718 | |
4719 Can also be used as a |method|: > | |
4720 ReadObject()->js_decode() | |
4721 | |
4722 js_encode({expr}) *js_encode()* | |
4723 This is similar to |json_encode()| with these differences: | |
4724 - Object key names are not in quotes. | |
4725 - v:none items in an array result in an empty item between | |
4726 commas. | |
4727 For example, the Vim object: | |
4728 [1,v:none,{"one":1},v:none] ~ | |
4729 Will be encoded as: | |
4730 [1,,{one:1},,] ~ | |
4731 While json_encode() would produce: | |
4732 [1,null,{"one":1},null] ~ | |
4733 This encoding is valid for JavaScript. It is more efficient | |
4734 than JSON, especially when using an array with optional items. | |
4735 | |
4736 Can also be used as a |method|: > | |
4737 GetObject()->js_encode() | |
4738 | |
4739 json_decode({string}) *json_decode()* | |
4740 This parses a JSON formatted string and returns the equivalent | |
4741 in Vim values. See |json_encode()| for the relation between | |
4742 JSON and Vim values. | |
4743 The decoding is permissive: | |
4744 - A trailing comma in an array and object is ignored, e.g. | |
4745 "[1, 2, ]" is the same as "[1, 2]". | |
4746 - Integer keys are accepted in objects, e.g. {1:2} is the | |
4747 same as {"1":2}. | |
4748 - More floating point numbers are recognized, e.g. "1." for | |
4749 "1.0", or "001.2" for "1.2". Special floating point values | |
4750 "Infinity", "-Infinity" and "NaN" (capitalization ignored) | |
4751 are accepted. | |
4752 - Leading zeroes in integer numbers are ignored, e.g. "012" | |
4753 for "12" or "-012" for "-12". | |
4754 - Capitalization is ignored in literal names null, true or | |
4755 false, e.g. "NULL" for "null", "True" for "true". | |
4756 - Control characters U+0000 through U+001F which are not | |
4757 escaped in strings are accepted, e.g. " " (tab | |
4758 character in string) for "\t". | |
4759 - An empty JSON expression or made of only spaces is accepted | |
4760 and results in v:none. | |
4761 - Backslash in an invalid 2-character sequence escape is | |
4762 ignored, e.g. "\a" is decoded as "a". | |
4763 - A correct surrogate pair in JSON strings should normally be | |
4764 a 12 character sequence such as "\uD834\uDD1E", but | |
4765 json_decode() silently accepts truncated surrogate pairs | |
4766 such as "\uD834" or "\uD834\u" | |
4767 *E938* | |
4768 A duplicate key in an object, valid in rfc7159, is not | |
4769 accepted by json_decode() as the result must be a valid Vim | |
4770 type, e.g. this fails: {"a":"b", "a":"c"} | |
4771 | |
4772 Can also be used as a |method|: > | |
4773 ReadObject()->json_decode() | |
4774 | |
4775 json_encode({expr}) *json_encode()* | |
4776 Encode {expr} as JSON and return this as a string. | |
4777 The encoding is specified in: | |
4778 https://tools.ietf.org/html/rfc7159.html | |
4779 Vim values are converted as follows: | |
4780 |Number| decimal number | |
4781 |Float| floating point number | |
4782 Float nan "NaN" | |
4783 Float inf "Infinity" | |
4784 Float -inf "-Infinity" | |
4785 |String| in double quotes (possibly null) | |
4786 |Funcref| not possible, error | |
4787 |List| as an array (possibly null); when | |
4788 used recursively: [] | |
4789 |Dict| as an object (possibly null); when | |
4790 used recursively: {} | |
4791 |Blob| as an array of the individual bytes | |
4792 v:false "false" | |
4793 v:true "true" | |
4794 v:none "null" | |
4795 v:null "null" | |
4796 Note that NaN and Infinity are passed on as values. This is | |
4797 missing in the JSON standard, but several implementations do | |
4798 allow it. If not then you will get an error. | |
4799 | |
4800 Can also be used as a |method|: > | |
4801 GetObject()->json_encode() | |
4802 | |
4803 keys({dict}) *keys()* | |
4804 Return a |List| with all the keys of {dict}. The |List| is in | |
4805 arbitrary order. Also see |items()| and |values()|. | |
4806 | |
4807 Can also be used as a |method|: > | |
4808 mydict->keys() | |
4809 | |
4810 < *len()* *E701* | |
4811 len({expr}) The result is a Number, which is the length of the argument. | |
4812 When {expr} is a String or a Number the length in bytes is | |
4813 used, as with |strlen()|. | |
4814 When {expr} is a |List| the number of items in the |List| is | |
4815 returned. | |
4816 When {expr} is a |Blob| the number of bytes is returned. | |
4817 When {expr} is a |Dictionary| the number of entries in the | |
4818 |Dictionary| is returned. | |
4819 Otherwise an error is given. | |
4820 | |
4821 Can also be used as a |method|: > | |
4822 mylist->len() | |
4823 | |
4824 < *libcall()* *E364* *E368* | |
4825 libcall({libname}, {funcname}, {argument}) | |
4826 Call function {funcname} in the run-time library {libname} | |
4827 with single argument {argument}. | |
4828 This is useful to call functions in a library that you | |
4829 especially made to be used with Vim. Since only one argument | |
4830 is possible, calling standard library functions is rather | |
4831 limited. | |
4832 The result is the String returned by the function. If the | |
4833 function returns NULL, this will appear as an empty string "" | |
4834 to Vim. | |
4835 If the function returns a number, use libcallnr()! | |
4836 If {argument} is a number, it is passed to the function as an | |
4837 int; if {argument} is a string, it is passed as a | |
4838 null-terminated string. | |
4839 This function will fail in |restricted-mode|. | |
4840 | |
4841 libcall() allows you to write your own 'plug-in' extensions to | |
4842 Vim without having to recompile the program. It is NOT a | |
4843 means to call system functions! If you try to do so Vim will | |
4844 very probably crash. | |
4845 | |
4846 For Win32, the functions you write must be placed in a DLL | |
4847 and use the normal C calling convention (NOT Pascal which is | |
4848 used in Windows System DLLs). The function must take exactly | |
4849 one parameter, either a character pointer or a long integer, | |
4850 and must return a character pointer or NULL. The character | |
4851 pointer returned must point to memory that will remain valid | |
4852 after the function has returned (e.g. in static data in the | |
4853 DLL). If it points to allocated memory, that memory will | |
4854 leak away. Using a static buffer in the function should work, | |
4855 it's then freed when the DLL is unloaded. | |
4856 | |
4857 WARNING: If the function returns a non-valid pointer, Vim may | |
4858 crash! This also happens if the function returns a number, | |
4859 because Vim thinks it's a pointer. | |
4860 For Win32 systems, {libname} should be the filename of the DLL | |
4861 without the ".DLL" suffix. A full path is only required if | |
4862 the DLL is not in the usual places. | |
4863 For Unix: When compiling your own plugins, remember that the | |
4864 object code must be compiled as position-independent ('PIC'). | |
4865 {only in Win32 and some Unix versions, when the |+libcall| | |
4866 feature is present} | |
4867 Examples: > | |
4868 :echo libcall("libc.so", "getenv", "HOME") | |
4869 | |
4870 < Can also be used as a |method|, the base is passed as the | |
4871 third argument: > | |
4872 GetValue()->libcall("libc.so", "getenv") | |
4873 < | |
4874 *libcallnr()* | |
4875 libcallnr({libname}, {funcname}, {argument}) | |
4876 Just like |libcall()|, but used for a function that returns an | |
4877 int instead of a string. | |
4878 {only in Win32 on some Unix versions, when the |+libcall| | |
4879 feature is present} | |
4880 Examples: > | |
4881 :echo libcallnr("/usr/lib/libc.so", "getpid", "") | |
4882 :call libcallnr("libc.so", "printf", "Hello World!\n") | |
4883 :call libcallnr("libc.so", "sleep", 10) | |
4884 < | |
4885 Can also be used as a |method|, the base is passed as the | |
4886 third argument: > | |
4887 GetValue()->libcallnr("libc.so", "printf") | |
4888 < | |
4889 | |
4890 line({expr} [, {winid}]) *line()* | |
4891 The result is a Number, which is the line number of the file | |
4892 position given with {expr}. The {expr} argument is a string. | |
4893 The accepted positions are: | |
4894 . the cursor position | |
4895 $ the last line in the current buffer | |
4896 'x position of mark x (if the mark is not set, 0 is | |
4897 returned) | |
4898 w0 first line visible in current window (one if the | |
4899 display isn't updated, e.g. in silent Ex mode) | |
4900 w$ last line visible in current window (this is one | |
4901 less than "w0" if no lines are visible) | |
4902 v In Visual mode: the start of the Visual area (the | |
4903 cursor is the end). When not in Visual mode | |
4904 returns the cursor position. Differs from |'<| in | |
4905 that it's updated right away. | |
4906 Note that a mark in another file can be used. The line number | |
4907 then applies to another buffer. | |
4908 To get the column number use |col()|. To get both use | |
4909 |getpos()|. | |
4910 With the optional {winid} argument the values are obtained for | |
4911 that window instead of the current window. | |
4912 Examples: > | |
4913 line(".") line number of the cursor | |
4914 line(".", winid) idem, in window "winid" | |
4915 line("'t") line number of mark t | |
4916 line("'" . marker) line number of mark marker | |
4917 < | |
4918 To jump to the last known position when opening a file see | |
4919 |last-position-jump|. | |
4920 | |
4921 Can also be used as a |method|: > | |
4922 GetValue()->line() | |
4923 | |
4924 line2byte({lnum}) *line2byte()* | |
4925 Return the byte count from the start of the buffer for line | |
4926 {lnum}. This includes the end-of-line character, depending on | |
4927 the 'fileformat' option for the current buffer. The first | |
4928 line returns 1. 'encoding' matters, 'fileencoding' is ignored. | |
4929 This can also be used to get the byte count for the line just | |
4930 below the last line: > | |
4931 line2byte(line("$") + 1) | |
4932 < This is the buffer size plus one. If 'fileencoding' is empty | |
4933 it is the file size plus one. {lnum} is used like with | |
4934 |getline()|. When {lnum} is invalid, or the |+byte_offset| | |
4935 feature has been disabled at compile time, -1 is returned. | |
4936 Also see |byte2line()|, |go| and |:goto|. | |
4937 | |
4938 Can also be used as a |method|: > | |
4939 GetLnum()->line2byte() | |
4940 | |
4941 lispindent({lnum}) *lispindent()* | |
4942 Get the amount of indent for line {lnum} according the lisp | |
4943 indenting rules, as with 'lisp'. | |
4944 The indent is counted in spaces, the value of 'tabstop' is | |
4945 relevant. {lnum} is used just like in |getline()|. | |
4946 When {lnum} is invalid or Vim was not compiled the | |
4947 |+lispindent| feature, -1 is returned. In |Vim9| script an | |
4948 error is given. | |
4949 | |
4950 Can also be used as a |method|: > | |
4951 GetLnum()->lispindent() | |
4952 | |
4953 list2blob({list}) *list2blob()* | |
4954 Return a Blob concatenating all the number values in {list}. | |
4955 Examples: > | |
4956 list2blob([1, 2, 3, 4]) returns 0z01020304 | |
4957 list2blob([]) returns 0z | |
4958 < Returns an empty Blob on error. If one of the numbers is | |
4959 negative or more than 255 error *E1239* is given. | |
4960 | |
4961 |blob2list()| does the opposite. | |
4962 | |
4963 Can also be used as a |method|: > | |
4964 GetList()->list2blob() | |
4965 | |
4966 list2str({list} [, {utf8}]) *list2str()* | |
4967 Convert each number in {list} to a character string can | |
4968 concatenate them all. Examples: > | |
4969 list2str([32]) returns " " | |
4970 list2str([65, 66, 67]) returns "ABC" | |
4971 < The same can be done (slowly) with: > | |
4972 join(map(list, {nr, val -> nr2char(val)}), '') | |
4973 < |str2list()| does the opposite. | |
4974 | |
4975 When {utf8} is omitted or zero, the current 'encoding' is used. | |
4976 When {utf8} is TRUE, always return UTF-8 characters. | |
4977 With UTF-8 composing characters work as expected: > | |
4978 list2str([97, 769]) returns "á" | |
4979 < | |
4980 Can also be used as a |method|: > | |
4981 GetList()->list2str() | |
4982 | |
4983 listener_add({callback} [, {buf}]) *listener_add()* | |
4984 Add a callback function that will be invoked when changes have | |
4985 been made to buffer {buf}. | |
4986 {buf} refers to a buffer name or number. For the accepted | |
4987 values, see |bufname()|. When {buf} is omitted the current | |
4988 buffer is used. | |
4989 Returns a unique ID that can be passed to |listener_remove()|. | |
4990 | |
4991 The {callback} is invoked with five arguments: | |
4992 a:bufnr the buffer that was changed | |
4993 a:start first changed line number | |
4994 a:end first line number below the change | |
4995 a:added number of lines added, negative if lines were | |
4996 deleted | |
4997 a:changes a List of items with details about the changes | |
4998 | |
4999 Example: > | |
5000 func Listener(bufnr, start, end, added, changes) | |
5001 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed' | |
5002 endfunc | |
5003 call listener_add('Listener', bufnr) | |
5004 | |
5005 < The List cannot be changed. Each item in a:changes is a | |
5006 dictionary with these entries: | |
5007 lnum the first line number of the change | |
5008 end the first line below the change | |
5009 added number of lines added; negative if lines were | |
5010 deleted | |
5011 col first column in "lnum" that was affected by | |
5012 the change; one if unknown or the whole line | |
5013 was affected; this is a byte index, first | |
5014 character has a value of one. | |
5015 When lines are inserted the values are: | |
5016 lnum line above which the new line is added | |
5017 end equal to "lnum" | |
5018 added number of lines inserted | |
5019 col 1 | |
5020 When lines are deleted the values are: | |
5021 lnum the first deleted line | |
5022 end the line below the first deleted line, before | |
5023 the deletion was done | |
5024 added negative, number of lines deleted | |
5025 col 1 | |
5026 When lines are changed: | |
5027 lnum the first changed line | |
5028 end the line below the last changed line | |
5029 added 0 | |
5030 col first column with a change or 1 | |
5031 | |
5032 The entries are in the order the changes were made, thus the | |
5033 most recent change is at the end. The line numbers are valid | |
5034 when the callback is invoked, but later changes may make them | |
5035 invalid, thus keeping a copy for later might not work. | |
5036 | |
5037 The {callback} is invoked just before the screen is updated, | |
5038 when |listener_flush()| is called or when a change is being | |
5039 made that changes the line count in a way it causes a line | |
5040 number in the list of changes to become invalid. | |
5041 | |
5042 The {callback} is invoked with the text locked, see | |
5043 |textlock|. If you do need to make changes to the buffer, use | |
5044 a timer to do this later |timer_start()|. | |
5045 | |
5046 The {callback} is not invoked when the buffer is first loaded. | |
5047 Use the |BufReadPost| autocmd event to handle the initial text | |
5048 of a buffer. | |
5049 The {callback} is also not invoked when the buffer is | |
5050 unloaded, use the |BufUnload| autocmd event for that. | |
5051 | |
5052 Can also be used as a |method|, the base is passed as the | |
5053 second argument: > | |
5054 GetBuffer()->listener_add(callback) | |
5055 | |
5056 listener_flush([{buf}]) *listener_flush()* | |
5057 Invoke listener callbacks for buffer {buf}. If there are no | |
5058 pending changes then no callbacks are invoked. | |
5059 | |
5060 {buf} refers to a buffer name or number. For the accepted | |
5061 values, see |bufname()|. When {buf} is omitted the current | |
5062 buffer is used. | |
5063 | |
5064 Can also be used as a |method|: > | |
5065 GetBuffer()->listener_flush() | |
5066 | |
5067 listener_remove({id}) *listener_remove()* | |
5068 Remove a listener previously added with listener_add(). | |
5069 Returns FALSE when {id} could not be found, TRUE when {id} was | |
5070 removed. | |
5071 | |
5072 Can also be used as a |method|: > | |
5073 GetListenerId()->listener_remove() | |
5074 | |
5075 localtime() *localtime()* | |
5076 Return the current time, measured as seconds since 1st Jan | |
5077 1970. See also |strftime()|, |strptime()| and |getftime()|. | |
5078 | |
5079 | |
5080 log({expr}) *log()* | |
5081 Return the natural logarithm (base e) of {expr} as a |Float|. | |
5082 {expr} must evaluate to a |Float| or a |Number| in the range | |
5083 (0, inf]. | |
5084 Examples: > | |
5085 :echo log(10) | |
5086 < 2.302585 > | |
5087 :echo log(exp(5)) | |
5088 < 5.0 | |
5089 | |
5090 Can also be used as a |method|: > | |
5091 Compute()->log() | |
5092 < | |
5093 {only available when compiled with the |+float| feature} | |
5094 | |
5095 | |
5096 log10({expr}) *log10()* | |
5097 Return the logarithm of Float {expr} to base 10 as a |Float|. | |
5098 {expr} must evaluate to a |Float| or a |Number|. | |
5099 Examples: > | |
5100 :echo log10(1000) | |
5101 < 3.0 > | |
5102 :echo log10(0.01) | |
5103 < -2.0 | |
5104 | |
5105 Can also be used as a |method|: > | |
5106 Compute()->log10() | |
5107 < | |
5108 {only available when compiled with the |+float| feature} | |
5109 | |
5110 luaeval({expr} [, {expr}]) *luaeval()* | |
5111 Evaluate Lua expression {expr} and return its result converted | |
5112 to Vim data structures. Second {expr} may hold additional | |
5113 argument accessible as _A inside first {expr}. | |
5114 Strings are returned as they are. | |
5115 Boolean objects are converted to numbers. | |
5116 Numbers are converted to |Float| values if vim was compiled | |
5117 with |+float| and to numbers otherwise. | |
5118 Dictionaries and lists obtained by vim.eval() are returned | |
5119 as-is. | |
5120 Other objects are returned as zero without any errors. | |
5121 See |lua-luaeval| for more details. | |
5122 Note that in a `:def` function local variables are not visible | |
5123 to {expr}. | |
5124 | |
5125 Can also be used as a |method|: > | |
5126 GetExpr()->luaeval() | |
5127 | |
5128 < {only available when compiled with the |+lua| feature} | |
5129 | |
5130 map({expr1}, {expr2}) *map()* | |
5131 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. | |
5132 When {expr1} is a |List|| or |Dictionary|, replace each | |
5133 item in {expr1} with the result of evaluating {expr2}. | |
5134 For a |Blob| each byte is replaced. | |
5135 For a |String|, each character, including composing | |
5136 characters, is replaced. | |
5137 If the item type changes you may want to use |mapnew()| to | |
5138 create a new List or Dictionary. This is required when using | |
5139 Vim9 script. | |
5140 | |
5141 {expr2} must be a |String| or |Funcref|. | |
5142 | |
5143 If {expr2} is a |String|, inside {expr2} |v:val| has the value | |
5144 of the current item. For a |Dictionary| |v:key| has the key | |
5145 of the current item and for a |List| |v:key| has the index of | |
5146 the current item. For a |Blob| |v:key| has the index of the | |
5147 current byte. For a |String| |v:key| has the index of the | |
5148 current character. | |
5149 Example: > | |
5150 :call map(mylist, '"> " . v:val . " <"') | |
5151 < This puts "> " before and " <" after each item in "mylist". | |
5152 | |
5153 Note that {expr2} is the result of an expression and is then | |
5154 used as an expression again. Often it is good to use a | |
5155 |literal-string| to avoid having to double backslashes. You | |
5156 still have to double ' quotes | |
5157 | |
5158 If {expr2} is a |Funcref| it is called with two arguments: | |
5159 1. The key or the index of the current item. | |
5160 2. the value of the current item. | |
5161 The function must return the new value of the item. Example | |
5162 that changes each value by "key-value": > | |
5163 func KeyValue(key, val) | |
5164 return a:key . '-' . a:val | |
5165 endfunc | |
5166 call map(myDict, function('KeyValue')) | |
5167 < It is shorter when using a |lambda|: > | |
5168 call map(myDict, {key, val -> key . '-' . val}) | |
5169 < If you do not use "val" you can leave it out: > | |
5170 call map(myDict, {key -> 'item: ' . key}) | |
5171 < If you do not use "key" you can use a short name: > | |
5172 call map(myDict, {_, val -> 'item: ' . val}) | |
5173 < | |
5174 The operation is done in-place for a |List| and |Dictionary|. | |
5175 If you want it to remain unmodified make a copy first: > | |
5176 :let tlist = map(copy(mylist), ' v:val . "\t"') | |
5177 | |
5178 < Returns {expr1}, the |List| or |Dictionary| that was filtered, | |
5179 or a new |Blob| or |String|. | |
5180 When an error is encountered while evaluating {expr2} no | |
5181 further items in {expr1} are processed. | |
5182 When {expr2} is a Funcref errors inside a function are ignored, | |
5183 unless it was defined with the "abort" flag. | |
5184 | |
5185 Can also be used as a |method|: > | |
5186 mylist->map(expr2) | |
5187 | |
5188 | |
5189 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* | |
5190 When {dict} is omitted or zero: Return the rhs of mapping | |
5191 {name} in mode {mode}. The returned String has special | |
5192 characters translated like in the output of the ":map" command | |
5193 listing. | |
5194 | |
5195 When there is no mapping for {name}, an empty String is | |
5196 returned. When the mapping for {name} is empty, then "<Nop>" | |
5197 is returned. | |
5198 | |
5199 The {name} can have special key names, like in the ":map" | |
5200 command. | |
5201 | |
5202 {mode} can be one of these strings: | |
5203 "n" Normal | |
5204 "v" Visual (including Select) | |
5205 "o" Operator-pending | |
5206 "i" Insert | |
5207 "c" Cmd-line | |
5208 "s" Select | |
5209 "x" Visual | |
5210 "l" langmap |language-mapping| | |
5211 "t" Terminal-Job | |
5212 "" Normal, Visual and Operator-pending | |
5213 When {mode} is omitted, the modes for "" are used. | |
5214 | |
5215 When {abbr} is there and it is |TRUE| use abbreviations | |
5216 instead of mappings. | |
5217 | |
5218 When {dict} is there and it is |TRUE| return a dictionary | |
5219 containing all the information of the mapping with the | |
5220 following items: | |
5221 "lhs" The {lhs} of the mapping as it would be typed | |
5222 "lhsraw" The {lhs} of the mapping as raw bytes | |
5223 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate | |
5224 form, only present when it differs from "lhsraw" | |
5225 "rhs" The {rhs} of the mapping as typed. | |
5226 "silent" 1 for a |:map-silent| mapping, else 0. | |
5227 "noremap" 1 if the {rhs} of the mapping is not remappable. | |
5228 "script" 1 if mapping was defined with <script>. | |
5229 "expr" 1 for an expression mapping (|:map-<expr>|). | |
5230 "buffer" 1 for a buffer local mapping (|:map-local|). | |
5231 "mode" Modes for which the mapping is defined. In | |
5232 addition to the modes mentioned above, these | |
5233 characters will be used: | |
5234 " " Normal, Visual and Operator-pending | |
5235 "!" Insert and Commandline mode | |
5236 (|mapmode-ic|) | |
5237 "sid" The script local ID, used for <sid> mappings | |
5238 (|<SID>|). | |
5239 "lnum" The line number in "sid", zero if unknown. | |
5240 "nowait" Do not wait for other, longer mappings. | |
5241 (|:map-<nowait>|). | |
5242 | |
5243 The dictionary can be used to restore a mapping with | |
5244 |mapset()|. | |
5245 | |
5246 The mappings local to the current buffer are checked first, | |
5247 then the global mappings. | |
5248 This function can be used to map a key even when it's already | |
5249 mapped, and have it do the original mapping too. Sketch: > | |
5250 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n') | |
5251 | |
5252 < Can also be used as a |method|: > | |
5253 GetKey()->maparg('n') | |
5254 | |
5255 mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* | |
5256 Check if there is a mapping that matches with {name} in mode | |
5257 {mode}. See |maparg()| for {mode} and special names in | |
5258 {name}. | |
5259 When {abbr} is there and it is |TRUE| use abbreviations | |
5260 instead of mappings. | |
5261 A match happens with a mapping that starts with {name} and | |
5262 with a mapping which is equal to the start of {name}. | |
5263 | |
5264 matches mapping "a" "ab" "abc" ~ | |
5265 mapcheck("a") yes yes yes | |
5266 mapcheck("abc") yes yes yes | |
5267 mapcheck("ax") yes no no | |
5268 mapcheck("b") no no no | |
5269 | |
5270 The difference with maparg() is that mapcheck() finds a | |
5271 mapping that matches with {name}, while maparg() only finds a | |
5272 mapping for {name} exactly. | |
5273 When there is no mapping that starts with {name}, an empty | |
5274 String is returned. If there is one, the RHS of that mapping | |
5275 is returned. If there are several mappings that start with | |
5276 {name}, the RHS of one of them is returned. This will be | |
5277 "<Nop>" if the RHS is empty. | |
5278 The mappings local to the current buffer are checked first, | |
5279 then the global mappings. | |
5280 This function can be used to check if a mapping can be added | |
5281 without being ambiguous. Example: > | |
5282 :if mapcheck("_vv") == "" | |
5283 : map _vv :set guifont=7x13<CR> | |
5284 :endif | |
5285 < This avoids adding the "_vv" mapping when there already is a | |
5286 mapping for "_v" or for "_vvv". | |
5287 | |
5288 Can also be used as a |method|: > | |
5289 GetKey()->mapcheck('n') | |
5290 | |
5291 | |
5292 mapnew({expr1}, {expr2}) *mapnew()* | |
5293 Like |map()| but instead of replacing items in {expr1} a new | |
5294 List or Dictionary is created and returned. {expr1} remains | |
5295 unchanged. Items can still be changed by {expr2}, if you | |
5296 don't want that use |deepcopy()| first. | |
5297 | |
5298 | |
5299 mapset({mode}, {abbr}, {dict}) *mapset()* | |
5300 Restore a mapping from a dictionary returned by |maparg()|. | |
5301 {mode} and {abbr} should be the same as for the call to | |
5302 |maparg()|. *E460* | |
5303 {mode} is used to define the mode in which the mapping is set, | |
5304 not the "mode" entry in {dict}. | |
5305 Example for saving and restoring a mapping: > | |
5306 let save_map = maparg('K', 'n', 0, 1) | |
5307 nnoremap K somethingelse | |
5308 ... | |
5309 call mapset('n', 0, save_map) | |
5310 < Note that if you are going to replace a map in several modes, | |
5311 e.g. with `:map!`, you need to save the mapping for all of | |
5312 them, since they can differ. | |
5313 | |
5314 | |
5315 match({expr}, {pat} [, {start} [, {count}]]) *match()* | |
5316 When {expr} is a |List| then this returns the index of the | |
5317 first item where {pat} matches. Each item is used as a | |
5318 String, |Lists| and |Dictionaries| are used as echoed. | |
5319 | |
5320 Otherwise, {expr} is used as a String. The result is a | |
5321 Number, which gives the index (byte offset) in {expr} where | |
5322 {pat} matches. | |
5323 | |
5324 A match at the first character or |List| item returns zero. | |
5325 If there is no match -1 is returned. | |
5326 | |
5327 For getting submatches see |matchlist()|. | |
5328 Example: > | |
5329 :echo match("testing", "ing") " results in 4 | |
5330 :echo match([1, 'x'], '\a') " results in 1 | |
5331 < See |string-match| for how {pat} is used. | |
5332 *strpbrk()* | |
5333 Vim doesn't have a strpbrk() function. But you can do: > | |
5334 :let sepidx = match(line, '[.,;: \t]') | |
5335 < *strcasestr()* | |
5336 Vim doesn't have a strcasestr() function. But you can add | |
5337 "\c" to the pattern to ignore case: > | |
5338 :let idx = match(haystack, '\cneedle') | |
5339 < | |
5340 If {start} is given, the search starts from byte index | |
5341 {start} in a String or item {start} in a |List|. | |
5342 The result, however, is still the index counted from the | |
5343 first character/item. Example: > | |
5344 :echo match("testing", "ing", 2) | |
5345 < result is again "4". > | |
5346 :echo match("testing", "ing", 4) | |
5347 < result is again "4". > | |
5348 :echo match("testing", "t", 2) | |
5349 < result is "3". | |
5350 For a String, if {start} > 0 then it is like the string starts | |
5351 {start} bytes later, thus "^" will match at {start}. Except | |
5352 when {count} is given, then it's like matches before the | |
5353 {start} byte are ignored (this is a bit complicated to keep it | |
5354 backwards compatible). | |
5355 For a String, if {start} < 0, it will be set to 0. For a list | |
5356 the index is counted from the end. | |
5357 If {start} is out of range ({start} > strlen({expr}) for a | |
5358 String or {start} > len({expr}) for a |List|) -1 is returned. | |
5359 | |
5360 When {count} is given use the {count}'th match. When a match | |
5361 is found in a String the search for the next one starts one | |
5362 character further. Thus this example results in 1: > | |
5363 echo match("testing", "..", 0, 2) | |
5364 < In a |List| the search continues in the next item. | |
5365 Note that when {count} is added the way {start} works changes, | |
5366 see above. | |
5367 | |
5368 See |pattern| for the patterns that are accepted. | |
5369 The 'ignorecase' option is used to set the ignore-caseness of | |
5370 the pattern. 'smartcase' is NOT used. The matching is always | |
5371 done like 'magic' is set and 'cpoptions' is empty. | |
5372 Note that a match at the start is preferred, thus when the | |
5373 pattern is using "*" (any number of matches) it tends to find | |
5374 zero matches at the start instead of a number of matches | |
5375 further down in the text. | |
5376 | |
5377 Can also be used as a |method|: > | |
5378 GetText()->match('word') | |
5379 GetList()->match('word') | |
5380 < | |
5381 *matchadd()* *E798* *E799* *E801* *E957* | |
5382 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) | |
5383 Defines a pattern to be highlighted in the current window (a | |
5384 "match"). It will be highlighted with {group}. Returns an | |
5385 identification number (ID), which can be used to delete the | |
5386 match using |matchdelete()|. The ID is bound to the window. | |
5387 Matching is case sensitive and magic, unless case sensitivity | |
5388 or magicness are explicitly overridden in {pattern}. The | |
5389 'magic', 'smartcase' and 'ignorecase' options are not used. | |
5390 The "Conceal" value is special, it causes the match to be | |
5391 concealed. | |
5392 | |
5393 The optional {priority} argument assigns a priority to the | |
5394 match. A match with a high priority will have its | |
5395 highlighting overrule that of a match with a lower priority. | |
5396 A priority is specified as an integer (negative numbers are no | |
5397 exception). If the {priority} argument is not specified, the | |
5398 default priority is 10. The priority of 'hlsearch' is zero, | |
5399 hence all matches with a priority greater than zero will | |
5400 overrule it. Syntax highlighting (see 'syntax') is a separate | |
5401 mechanism, and regardless of the chosen priority a match will | |
5402 always overrule syntax highlighting. | |
5403 | |
5404 The optional {id} argument allows the request for a specific | |
5405 match ID. If a specified ID is already taken, an error | |
5406 message will appear and the match will not be added. An ID | |
5407 is specified as a positive integer (zero excluded). IDs 1, 2 | |
5408 and 3 are reserved for |:match|, |:2match| and |:3match|, | |
5409 respectively. If the {id} argument is not specified or -1, | |
5410 |matchadd()| automatically chooses a free ID. | |
5411 | |
5412 The optional {dict} argument allows for further custom | |
5413 values. Currently this is used to specify a match specific | |
5414 conceal character that will be shown for |hl-Conceal| | |
5415 highlighted matches. The dict can have the following members: | |
5416 | |
5417 conceal Special character to show instead of the | |
5418 match (only for |hl-Conceal| highlighted | |
5419 matches, see |:syn-cchar|) | |
5420 window Instead of the current window use the | |
5421 window with this number or window ID. | |
5422 | |
5423 The number of matches is not limited, as it is the case with | |
5424 the |:match| commands. | |
5425 | |
5426 Example: > | |
5427 :highlight MyGroup ctermbg=green guibg=green | |
5428 :let m = matchadd("MyGroup", "TODO") | |
5429 < Deletion of the pattern: > | |
5430 :call matchdelete(m) | |
5431 | |
5432 < A list of matches defined by |matchadd()| and |:match| are | |
5433 available from |getmatches()|. All matches can be deleted in | |
5434 one operation by |clearmatches()|. | |
5435 | |
5436 Can also be used as a |method|: > | |
5437 GetGroup()->matchadd('TODO') | |
5438 < | |
5439 *matchaddpos()* | |
5440 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) | |
5441 Same as |matchadd()|, but requires a list of positions {pos} | |
5442 instead of a pattern. This command is faster than |matchadd()| | |
5443 because it does not require to handle regular expressions and | |
5444 sets buffer line boundaries to redraw screen. It is supposed | |
5445 to be used when fast match additions and deletions are | |
5446 required, for example to highlight matching parentheses. | |
5447 | |
5448 {pos} is a list of positions. Each position can be one of | |
5449 these: | |
5450 - A number. This whole line will be highlighted. The first | |
5451 line has number 1. | |
5452 - A list with one number, e.g., [23]. The whole line with this | |
5453 number will be highlighted. | |
5454 - A list with two numbers, e.g., [23, 11]. The first number is | |
5455 the line number, the second one is the column number (first | |
5456 column is 1, the value must correspond to the byte index as | |
5457 |col()| would return). The character at this position will | |
5458 be highlighted. | |
5459 - A list with three numbers, e.g., [23, 11, 3]. As above, but | |
5460 the third number gives the length of the highlight in bytes. | |
5461 | |
5462 The maximum number of positions in {pos} is 8. | |
5463 | |
5464 Example: > | |
5465 :highlight MyGroup ctermbg=green guibg=green | |
5466 :let m = matchaddpos("MyGroup", [[23, 24], 34]) | |
5467 < Deletion of the pattern: > | |
5468 :call matchdelete(m) | |
5469 | |
5470 < Matches added by |matchaddpos()| are returned by | |
5471 |getmatches()|. | |
5472 | |
5473 Can also be used as a |method|: > | |
5474 GetGroup()->matchaddpos([23, 11]) | |
5475 | |
5476 matcharg({nr}) *matcharg()* | |
5477 Selects the {nr} match item, as set with a |:match|, | |
5478 |:2match| or |:3match| command. | |
5479 Return a |List| with two elements: | |
5480 The name of the highlight group used | |
5481 The pattern used. | |
5482 When {nr} is not 1, 2 or 3 returns an empty |List|. | |
5483 When there is no match item set returns ['', '']. | |
5484 This is useful to save and restore a |:match|. | |
5485 Highlighting matches using the |:match| commands are limited | |
5486 to three matches. |matchadd()| does not have this limitation. | |
5487 | |
5488 Can also be used as a |method|: > | |
5489 GetMatch()->matcharg() | |
5490 | |
5491 matchdelete({id} [, {win}) *matchdelete()* *E802* *E803* | |
5492 Deletes a match with ID {id} previously defined by |matchadd()| | |
5493 or one of the |:match| commands. Returns 0 if successful, | |
5494 otherwise -1. See example for |matchadd()|. All matches can | |
5495 be deleted in one operation by |clearmatches()|. | |
5496 If {win} is specified, use the window with this number or | |
5497 window ID instead of the current window. | |
5498 | |
5499 Can also be used as a |method|: > | |
5500 GetMatch()->matchdelete() | |
5501 | |
5502 matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* | |
5503 Same as |match()|, but return the index of first character | |
5504 after the match. Example: > | |
5505 :echo matchend("testing", "ing") | |
5506 < results in "7". | |
5507 *strspn()* *strcspn()* | |
5508 Vim doesn't have a strspn() or strcspn() function, but you can | |
5509 do it with matchend(): > | |
5510 :let span = matchend(line, '[a-zA-Z]') | |
5511 :let span = matchend(line, '[^a-zA-Z]') | |
5512 < Except that -1 is returned when there are no matches. | |
5513 | |
5514 The {start}, if given, has the same meaning as for |match()|. > | |
5515 :echo matchend("testing", "ing", 2) | |
5516 < results in "7". > | |
5517 :echo matchend("testing", "ing", 5) | |
5518 < result is "-1". | |
5519 When {expr} is a |List| the result is equal to |match()|. | |
5520 | |
5521 Can also be used as a |method|: > | |
5522 GetText()->matchend('word') | |
5523 | |
5524 | |
5525 matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* | |
5526 If {list} is a list of strings, then returns a |List| with all | |
5527 the strings in {list} that fuzzy match {str}. The strings in | |
5528 the returned list are sorted based on the matching score. | |
5529 | |
5530 The optional {dict} argument always supports the following | |
5531 items: | |
5532 matchseq When this item is present and {str} contains | |
5533 multiple words separated by white space, then | |
5534 returns only matches that contain the words in | |
5535 the given sequence. | |
5536 | |
5537 If {list} is a list of dictionaries, then the optional {dict} | |
5538 argument supports the following additional items: | |
5539 key key of the item which is fuzzy matched against | |
5540 {str}. The value of this item should be a | |
5541 string. | |
5542 text_cb |Funcref| that will be called for every item | |
5543 in {list} to get the text for fuzzy matching. | |
5544 This should accept a dictionary item as the | |
5545 argument and return the text for that item to | |
5546 use for fuzzy matching. | |
5547 | |
5548 {str} is treated as a literal string and regular expression | |
5549 matching is NOT supported. The maximum supported {str} length | |
5550 is 256. | |
5551 | |
5552 When {str} has multiple words each separated by white space, | |
5553 then the list of strings that have all the words is returned. | |
5554 | |
5555 If there are no matching strings or there is an error, then an | |
5556 empty list is returned. If length of {str} is greater than | |
5557 256, then returns an empty list. | |
5558 | |
5559 Refer to |fuzzy-match| for more information about fuzzy | |
5560 matching strings. | |
5561 | |
5562 Example: > | |
5563 :echo matchfuzzy(["clay", "crow"], "cay") | |
5564 < results in ["clay"]. > | |
5565 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") | |
5566 < results in a list of buffer names fuzzy matching "ndl". > | |
5567 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) | |
5568 < results in a list of buffer information dicts with buffer | |
5569 names fuzzy matching "ndl". > | |
5570 :echo getbufinfo()->matchfuzzy("spl", | |
5571 \ {'text_cb' : {v -> v.name}}) | |
5572 < results in a list of buffer information dicts with buffer | |
5573 names fuzzy matching "spl". > | |
5574 :echo v:oldfiles->matchfuzzy("test") | |
5575 < results in a list of file names fuzzy matching "test". > | |
5576 :let l = readfile("buffer.c")->matchfuzzy("str") | |
5577 < results in a list of lines in "buffer.c" fuzzy matching "str". > | |
5578 :echo ['one two', 'two one']->matchfuzzy('two one') | |
5579 < results in ['two one', 'one two']. > | |
5580 :echo ['one two', 'two one']->matchfuzzy('two one', | |
5581 \ {'matchseq': 1}) | |
5582 < results in ['two one']. | |
5583 | |
5584 matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* | |
5585 Same as |matchfuzzy()|, but returns the list of matched | |
5586 strings, the list of character positions where characters | |
5587 in {str} matches and a list of matching scores. You can | |
5588 use |byteidx()| to convert a character position to a byte | |
5589 position. | |
5590 | |
5591 If {str} matches multiple times in a string, then only the | |
5592 positions for the best match is returned. | |
5593 | |
5594 If there are no matching strings or there is an error, then a | |
5595 list with three empty list items is returned. | |
5596 | |
5597 Example: > | |
5598 :echo matchfuzzypos(['testing'], 'tsg') | |
5599 < results in [['testing'], [[0, 2, 6]], [99]] > | |
5600 :echo matchfuzzypos(['clay', 'lacy'], 'la') | |
5601 < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] > | |
5602 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'}) | |
5603 < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]] | |
5604 | |
5605 matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* | |
5606 Same as |match()|, but return a |List|. The first item in the | |
5607 list is the matched string, same as what matchstr() would | |
5608 return. Following items are submatches, like "\1", "\2", etc. | |
5609 in |:substitute|. When an optional submatch didn't match an | |
5610 empty string is used. Example: > | |
5611 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') | |
5612 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] | |
5613 When there is no match an empty list is returned. | |
5614 | |
5615 You can pass in a List, but that is not very useful. | |
5616 | |
5617 Can also be used as a |method|: > | |
5618 GetText()->matchlist('word') | |
5619 | |
5620 matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* | |
5621 Same as |match()|, but return the matched string. Example: > | |
5622 :echo matchstr("testing", "ing") | |
5623 < results in "ing". | |
5624 When there is no match "" is returned. | |
5625 The {start}, if given, has the same meaning as for |match()|. > | |
5626 :echo matchstr("testing", "ing", 2) | |
5627 < results in "ing". > | |
5628 :echo matchstr("testing", "ing", 5) | |
5629 < result is "". | |
5630 When {expr} is a |List| then the matching item is returned. | |
5631 The type isn't changed, it's not necessarily a String. | |
5632 | |
5633 Can also be used as a |method|: > | |
5634 GetText()->matchstr('word') | |
5635 | |
5636 matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* | |
5637 Same as |matchstr()|, but return the matched string, the start | |
5638 position and the end position of the match. Example: > | |
5639 :echo matchstrpos("testing", "ing") | |
5640 < results in ["ing", 4, 7]. | |
5641 When there is no match ["", -1, -1] is returned. | |
5642 The {start}, if given, has the same meaning as for |match()|. > | |
5643 :echo matchstrpos("testing", "ing", 2) | |
5644 < results in ["ing", 4, 7]. > | |
5645 :echo matchstrpos("testing", "ing", 5) | |
5646 < result is ["", -1, -1]. | |
5647 When {expr} is a |List| then the matching item, the index | |
5648 of first item where {pat} matches, the start position and the | |
5649 end position of the match are returned. > | |
5650 :echo matchstrpos([1, '__x'], '\a') | |
5651 < result is ["x", 1, 2, 3]. | |
5652 The type isn't changed, it's not necessarily a String. | |
5653 | |
5654 Can also be used as a |method|: > | |
5655 GetText()->matchstrpos('word') | |
5656 < | |
5657 | |
5658 *max()* | |
5659 max({expr}) Return the maximum value of all items in {expr}. Example: > | |
5660 echo max([apples, pears, oranges]) | |
5661 | |
5662 < {expr} can be a |List| or a |Dictionary|. For a Dictionary, | |
5663 it returns the maximum of all values in the Dictionary. | |
5664 If {expr} is neither a List nor a Dictionary, or one of the | |
5665 items in {expr} cannot be used as a Number this results in | |
5666 an error. An empty |List| or |Dictionary| results in zero. | |
5667 | |
5668 Can also be used as a |method|: > | |
5669 mylist->max() | |
5670 | |
5671 | |
5672 menu_info({name} [, {mode}]) *menu_info()* | |
5673 Return information about the specified menu {name} in | |
5674 mode {mode}. The menu name should be specified without the | |
5675 shortcut character ('&'). If {name} is "", then the top-level | |
5676 menu names are returned. | |
5677 | |
5678 {mode} can be one of these strings: | |
5679 "n" Normal | |
5680 "v" Visual (including Select) | |
5681 "o" Operator-pending | |
5682 "i" Insert | |
5683 "c" Cmd-line | |
5684 "s" Select | |
5685 "x" Visual | |
5686 "t" Terminal-Job | |
5687 "" Normal, Visual and Operator-pending | |
5688 "!" Insert and Cmd-line | |
5689 When {mode} is omitted, the modes for "" are used. | |
5690 | |
5691 Returns a |Dictionary| containing the following items: | |
5692 accel menu item accelerator text |menu-text| | |
5693 display display name (name without '&') | |
5694 enabled v:true if this menu item is enabled | |
5695 Refer to |:menu-enable| | |
5696 icon name of the icon file (for toolbar) | |
5697 |toolbar-icon| | |
5698 iconidx index of a built-in icon | |
5699 modes modes for which the menu is defined. In | |
5700 addition to the modes mentioned above, these | |
5701 characters will be used: | |
5702 " " Normal, Visual and Operator-pending | |
5703 name menu item name. | |
5704 noremenu v:true if the {rhs} of the menu item is not | |
5705 remappable else v:false. | |
5706 priority menu order priority |menu-priority| | |
5707 rhs right-hand-side of the menu item. The returned | |
5708 string has special characters translated like | |
5709 in the output of the ":menu" command listing. | |
5710 When the {rhs} of a menu item is empty, then | |
5711 "<Nop>" is returned. | |
5712 script v:true if script-local remapping of {rhs} is | |
5713 allowed else v:false. See |:menu-script|. | |
5714 shortcut shortcut key (character after '&' in | |
5715 the menu name) |menu-shortcut| | |
5716 silent v:true if the menu item is created | |
5717 with <silent> argument |:menu-silent| | |
5718 submenus |List| containing the names of | |
5719 all the submenus. Present only if the menu | |
5720 item has submenus. | |
5721 | |
5722 Returns an empty dictionary if the menu item is not found. | |
5723 | |
5724 Examples: > | |
5725 :echo menu_info('Edit.Cut') | |
5726 :echo menu_info('File.Save', 'n') | |
5727 | |
5728 " Display the entire menu hierarchy in a buffer | |
5729 func ShowMenu(name, pfx) | |
5730 let m = menu_info(a:name) | |
5731 call append(line('$'), a:pfx .. m.display) | |
5732 for child in m->get('submenus', []) | |
5733 call ShowMenu(a:name .. '.' .. escape(child, '.'), | |
5734 \ a:pfx .. ' ') | |
5735 endfor | |
5736 endfunc | |
5737 new | |
5738 for topmenu in menu_info('').submenus | |
5739 call ShowMenu(topmenu, '') | |
5740 endfor | |
5741 < | |
5742 Can also be used as a |method|: > | |
5743 GetMenuName()->menu_info('v') | |
5744 | |
5745 | |
5746 < *min()* | |
5747 min({expr}) Return the minimum value of all items in {expr}. Example: > | |
5748 echo min([apples, pears, oranges]) | |
5749 | |
5750 < {expr} can be a |List| or a |Dictionary|. For a Dictionary, | |
5751 it returns the minimum of all values in the Dictionary. | |
5752 If {expr} is neither a List nor a Dictionary, or one of the | |
5753 items in {expr} cannot be used as a Number this results in | |
5754 an error. An empty |List| or |Dictionary| results in zero. | |
5755 | |
5756 Can also be used as a |method|: > | |
5757 mylist->min() | |
5758 | |
5759 < *mkdir()* *E739* | |
5760 mkdir({name} [, {path} [, {prot}]]) | |
5761 Create directory {name}. | |
5762 | |
5763 If {path} is "p" then intermediate directories are created as | |
5764 necessary. Otherwise it must be "". | |
5765 | |
5766 If {prot} is given it is used to set the protection bits of | |
5767 the new directory. The default is 0o755 (rwxr-xr-x: r/w for | |
5768 the user, readable for others). Use 0o700 to make it | |
5769 unreadable for others. This is only used for the last part of | |
5770 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be | |
5771 created with 0o755. | |
5772 Example: > | |
5773 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700) | |
5774 | |
5775 < This function is not available in the |sandbox|. | |
5776 | |
5777 There is no error if the directory already exists and the "p" | |
5778 flag is passed (since patch 8.0.1708). However, without the | |
5779 "p" option the call will fail. | |
5780 | |
5781 The function result is a Number, which is TRUE if the call was | |
5782 successful or FALSE if the directory creation failed or partly | |
5783 failed. | |
5784 | |
5785 Not available on all systems. To check use: > | |
5786 :if exists("*mkdir") | |
5787 | |
5788 < Can also be used as a |method|: > | |
5789 GetName()->mkdir() | |
5790 < | |
5791 *mode()* | |
5792 mode([expr]) Return a string that indicates the current mode. | |
5793 If [expr] is supplied and it evaluates to a non-zero Number or | |
5794 a non-empty String (|non-zero-arg|), then the full mode is | |
5795 returned, otherwise only the first letter is returned. | |
5796 Also see |state()|. | |
5797 | |
5798 n Normal | |
5799 no Operator-pending | |
5800 nov Operator-pending (forced characterwise |o_v|) | |
5801 noV Operator-pending (forced linewise |o_V|) | |
5802 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|); | |
5803 CTRL-V is one character | |
5804 niI Normal using |i_CTRL-O| in |Insert-mode| | |
5805 niR Normal using |i_CTRL-O| in |Replace-mode| | |
5806 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| | |
5807 nt Terminal-Normal (insert goes to Terminal-Job mode) | |
5808 v Visual by character | |
5809 vs Visual by character using |v_CTRL-O| in Select mode | |
5810 V Visual by line | |
5811 Vs Visual by line using |v_CTRL-O| in Select mode | |
5812 CTRL-V Visual blockwise | |
5813 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode | |
5814 s Select by character | |
5815 S Select by line | |
5816 CTRL-S Select blockwise | |
5817 i Insert | |
5818 ic Insert mode completion |compl-generic| | |
5819 ix Insert mode |i_CTRL-X| completion | |
5820 R Replace |R| | |
5821 Rc Replace mode completion |compl-generic| | |
5822 Rx Replace mode |i_CTRL-X| completion | |
5823 Rv Virtual Replace |gR| | |
5824 Rvc Virtual Replace mode completion |compl-generic| | |
5825 Rvx Virtual Replace mode |i_CTRL-X| completion | |
5826 c Command-line editing | |
5827 cv Vim Ex mode |gQ| | |
5828 ce Normal Ex mode |Q| | |
5829 r Hit-enter prompt | |
5830 rm The -- more -- prompt | |
5831 r? A |:confirm| query of some sort | |
5832 ! Shell or external command is executing | |
5833 t Terminal-Job mode: keys go to the job | |
5834 | |
5835 This is useful in the 'statusline' option or when used | |
5836 with |remote_expr()| In most other places it always returns | |
5837 "c" or "n". | |
5838 Note that in the future more modes and more specific modes may | |
5839 be added. It's better not to compare the whole string but only | |
5840 the leading character(s). | |
5841 Also see |visualmode()|. | |
5842 | |
5843 Can also be used as a |method|: > | |
5844 DoFull()->mode() | |
5845 | |
5846 mzeval({expr}) *mzeval()* | |
5847 Evaluate MzScheme expression {expr} and return its result | |
5848 converted to Vim data structures. | |
5849 Numbers and strings are returned as they are. | |
5850 Pairs (including lists and improper lists) and vectors are | |
5851 returned as Vim |Lists|. | |
5852 Hash tables are represented as Vim |Dictionary| type with keys | |
5853 converted to strings. | |
5854 All other types are converted to string with display function. | |
5855 Examples: > | |
5856 :mz (define l (list 1 2 3)) | |
5857 :mz (define h (make-hash)) (hash-set! h "list" l) | |
5858 :echo mzeval("l") | |
5859 :echo mzeval("h") | |
5860 < | |
5861 Note that in a `:def` function local variables are not visible | |
5862 to {expr}. | |
5863 | |
5864 Can also be used as a |method|: > | |
5865 GetExpr()->mzeval() | |
5866 < | |
5867 {only available when compiled with the |+mzscheme| feature} | |
5868 | |
5869 nextnonblank({lnum}) *nextnonblank()* | |
5870 Return the line number of the first line at or below {lnum} | |
5871 that is not blank. Example: > | |
5872 if getline(nextnonblank(1)) =~ "Java" | |
5873 < When {lnum} is invalid or there is no non-blank line at or | |
5874 below it, zero is returned. | |
5875 {lnum} is used like with |getline()|. | |
5876 See also |prevnonblank()|. | |
5877 | |
5878 Can also be used as a |method|: > | |
5879 GetLnum()->nextnonblank() | |
5880 | |
5881 nr2char({expr} [, {utf8}]) *nr2char()* | |
5882 Return a string with a single character, which has the number | |
5883 value {expr}. Examples: > | |
5884 nr2char(64) returns "@" | |
5885 nr2char(32) returns " " | |
5886 < When {utf8} is omitted or zero, the current 'encoding' is used. | |
5887 Example for "utf-8": > | |
5888 nr2char(300) returns I with bow character | |
5889 < When {utf8} is TRUE, always return UTF-8 characters. | |
5890 Note that a NUL character in the file is specified with | |
5891 nr2char(10), because NULs are represented with newline | |
5892 characters. nr2char(0) is a real NUL and terminates the | |
5893 string, thus results in an empty string. | |
5894 To turn a list of character numbers into a string: > | |
5895 let list = [65, 66, 67] | |
5896 let str = join(map(list, {_, val -> nr2char(val)}), '') | |
5897 < Result: "ABC" | |
5898 | |
5899 Can also be used as a |method|: > | |
5900 GetNumber()->nr2char() | |
5901 | |
5902 or({expr}, {expr}) *or()* | |
5903 Bitwise OR on the two arguments. The arguments are converted | |
5904 to a number. A List, Dict or Float argument causes an error. | |
5905 Example: > | |
5906 :let bits = or(bits, 0x80) | |
5907 < Can also be used as a |method|: > | |
5908 :let bits = bits->or(0x80) | |
5909 | |
5910 | |
5911 pathshorten({path} [, {len}]) *pathshorten()* | |
5912 Shorten directory names in the path {path} and return the | |
5913 result. The tail, the file name, is kept as-is. The other | |
5914 components in the path are reduced to {len} letters in length. | |
5915 If {len} is omitted or smaller than 1 then 1 is used (single | |
5916 letters). Leading '~' and '.' characters are kept. Examples: > | |
5917 :echo pathshorten('~/.vim/autoload/myfile.vim') | |
5918 < ~/.v/a/myfile.vim ~ | |
5919 > | |
5920 :echo pathshorten('~/.vim/autoload/myfile.vim', 2) | |
5921 < ~/.vi/au/myfile.vim ~ | |
5922 It doesn't matter if the path exists or not. | |
5923 | |
5924 Can also be used as a |method|: > | |
5925 GetDirectories()->pathshorten() | |
5926 | |
5927 perleval({expr}) *perleval()* | |
5928 Evaluate Perl expression {expr} in scalar context and return | |
5929 its result converted to Vim data structures. If value can't be | |
5930 converted, it is returned as a string Perl representation. | |
5931 Note: If you want an array or hash, {expr} must return a | |
5932 reference to it. | |
5933 Example: > | |
5934 :echo perleval('[1 .. 4]') | |
5935 < [1, 2, 3, 4] | |
5936 | |
5937 Note that in a `:def` function local variables are not visible | |
5938 to {expr}. | |
5939 | |
5940 Can also be used as a |method|: > | |
5941 GetExpr()->perleval() | |
5942 | |
5943 < {only available when compiled with the |+perl| feature} | |
5944 | |
5945 | |
5946 popup_ functions are documented here: |popup-functions| | |
5947 | |
5948 | |
5949 pow({x}, {y}) *pow()* | |
5950 Return the power of {x} to the exponent {y} as a |Float|. | |
5951 {x} and {y} must evaluate to a |Float| or a |Number|. | |
5952 Examples: > | |
5953 :echo pow(3, 3) | |
5954 < 27.0 > | |
5955 :echo pow(2, 16) | |
5956 < 65536.0 > | |
5957 :echo pow(32, 0.20) | |
5958 < 2.0 | |
5959 | |
5960 Can also be used as a |method|: > | |
5961 Compute()->pow(3) | |
5962 < | |
5963 {only available when compiled with the |+float| feature} | |
5964 | |
5965 prevnonblank({lnum}) *prevnonblank()* | |
5966 Return the line number of the first line at or above {lnum} | |
5967 that is not blank. Example: > | |
5968 let ind = indent(prevnonblank(v:lnum - 1)) | |
5969 < When {lnum} is invalid or there is no non-blank line at or | |
5970 above it, zero is returned. | |
5971 {lnum} is used like with |getline()|. | |
5972 Also see |nextnonblank()|. | |
5973 | |
5974 Can also be used as a |method|: > | |
5975 GetLnum()->prevnonblank() | |
5976 | |
5977 printf({fmt}, {expr1} ...) *printf()* | |
5978 Return a String with {fmt}, where "%" items are replaced by | |
5979 the formatted form of their respective arguments. Example: > | |
5980 printf("%4d: E%d %.30s", lnum, errno, msg) | |
5981 < May result in: | |
5982 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ | |
5983 | |
5984 When used as a |method| the base is passed as the second | |
5985 argument: > | |
5986 Compute()->printf("result: %d") | |
5987 | |
5988 < Often used items are: | |
5989 %s string | |
5990 %6S string right-aligned in 6 display cells | |
5991 %6s string right-aligned in 6 bytes | |
5992 %.9s string truncated to 9 bytes | |
5993 %c single byte | |
5994 %d decimal number | |
5995 %5d decimal number padded with spaces to 5 characters | |
5996 %x hex number | |
5997 %04x hex number padded with zeros to at least 4 characters | |
5998 %X hex number using upper case letters | |
5999 %o octal number | |
6000 %08b binary number padded with zeros to at least 8 chars | |
6001 %f floating point number as 12.23, inf, -inf or nan | |
6002 %F floating point number as 12.23, INF, -INF or NAN | |
6003 %e floating point number as 1.23e3, inf, -inf or nan | |
6004 %E floating point number as 1.23E3, INF, -INF or NAN | |
6005 %g floating point number, as %f or %e depending on value | |
6006 %G floating point number, as %F or %E depending on value | |
6007 %% the % character itself | |
6008 | |
6009 Conversion specifications start with '%' and end with the | |
6010 conversion type. All other characters are copied unchanged to | |
6011 the result. | |
6012 | |
6013 The "%" starts a conversion specification. The following | |
6014 arguments appear in sequence: | |
6015 | |
6016 % [flags] [field-width] [.precision] type | |
6017 | |
6018 flags | |
6019 Zero or more of the following flags: | |
6020 | |
6021 # The value should be converted to an "alternate | |
6022 form". For c, d, and s conversions, this option | |
6023 has no effect. For o conversions, the precision | |
6024 of the number is increased to force the first | |
6025 character of the output string to a zero (except | |
6026 if a zero value is printed with an explicit | |
6027 precision of zero). | |
6028 For b and B conversions, a non-zero result has | |
6029 the string "0b" (or "0B" for B conversions) | |
6030 prepended to it. | |
6031 For x and X conversions, a non-zero result has | |
6032 the string "0x" (or "0X" for X conversions) | |
6033 prepended to it. | |
6034 | |
6035 0 (zero) Zero padding. For all conversions the converted | |
6036 value is padded on the left with zeros rather | |
6037 than blanks. If a precision is given with a | |
6038 numeric conversion (d, b, B, o, x, and X), the 0 | |
6039 flag is ignored. | |
6040 | |
6041 - A negative field width flag; the converted value | |
6042 is to be left adjusted on the field boundary. | |
6043 The converted value is padded on the right with | |
6044 blanks, rather than on the left with blanks or | |
6045 zeros. A - overrides a 0 if both are given. | |
6046 | |
6047 ' ' (space) A blank should be left before a positive | |
6048 number produced by a signed conversion (d). | |
6049 | |
6050 + A sign must always be placed before a number | |
6051 produced by a signed conversion. A + overrides | |
6052 a space if both are used. | |
6053 | |
6054 field-width | |
6055 An optional decimal digit string specifying a minimum | |
6056 field width. If the converted value has fewer bytes | |
6057 than the field width, it will be padded with spaces on | |
6058 the left (or right, if the left-adjustment flag has | |
6059 been given) to fill out the field width. For the S | |
6060 conversion the count is in cells. | |
6061 | |
6062 .precision | |
6063 An optional precision, in the form of a period '.' | |
6064 followed by an optional digit string. If the digit | |
6065 string is omitted, the precision is taken as zero. | |
6066 This gives the minimum number of digits to appear for | |
6067 d, o, x, and X conversions, the maximum number of | |
6068 bytes to be printed from a string for s conversions, | |
6069 or the maximum number of cells to be printed from a | |
6070 string for S conversions. | |
6071 For floating point it is the number of digits after | |
6072 the decimal point. | |
6073 | |
6074 type | |
6075 A character that specifies the type of conversion to | |
6076 be applied, see below. | |
6077 | |
6078 A field width or precision, or both, may be indicated by an | |
6079 asterisk '*' instead of a digit string. In this case, a | |
6080 Number argument supplies the field width or precision. A | |
6081 negative field width is treated as a left adjustment flag | |
6082 followed by a positive field width; a negative precision is | |
6083 treated as though it were missing. Example: > | |
6084 :echo printf("%d: %.*s", nr, width, line) | |
6085 < This limits the length of the text used from "line" to | |
6086 "width" bytes. | |
6087 | |
6088 The conversion specifiers and their meanings are: | |
6089 | |
6090 *printf-d* *printf-b* *printf-B* *printf-o* | |
6091 *printf-x* *printf-X* | |
6092 dbBoxX The Number argument is converted to signed decimal | |
6093 (d), unsigned binary (b and B), unsigned octal (o), or | |
6094 unsigned hexadecimal (x and X) notation. The letters | |
6095 "abcdef" are used for x conversions; the letters | |
6096 "ABCDEF" are used for X conversions. | |
6097 The precision, if any, gives the minimum number of | |
6098 digits that must appear; if the converted value | |
6099 requires fewer digits, it is padded on the left with | |
6100 zeros. | |
6101 In no case does a non-existent or small field width | |
6102 cause truncation of a numeric field; if the result of | |
6103 a conversion is wider than the field width, the field | |
6104 is expanded to contain the conversion result. | |
6105 The 'h' modifier indicates the argument is 16 bits. | |
6106 The 'l' modifier indicates the argument is 32 bits. | |
6107 The 'L' modifier indicates the argument is 64 bits. | |
6108 Generally, these modifiers are not useful. They are | |
6109 ignored when type is known from the argument. | |
6110 | |
6111 i alias for d | |
6112 D alias for ld | |
6113 U alias for lu | |
6114 O alias for lo | |
6115 | |
6116 *printf-c* | |
6117 c The Number argument is converted to a byte, and the | |
6118 resulting character is written. | |
6119 | |
6120 *printf-s* | |
6121 s The text of the String argument is used. If a | |
6122 precision is specified, no more bytes than the number | |
6123 specified are used. | |
6124 If the argument is not a String type, it is | |
6125 automatically converted to text with the same format | |
6126 as ":echo". | |
6127 *printf-S* | |
6128 S The text of the String argument is used. If a | |
6129 precision is specified, no more display cells than the | |
6130 number specified are used. | |
6131 | |
6132 *printf-f* *E807* | |
6133 f F The Float argument is converted into a string of the | |
6134 form 123.456. The precision specifies the number of | |
6135 digits after the decimal point. When the precision is | |
6136 zero the decimal point is omitted. When the precision | |
6137 is not specified 6 is used. A really big number | |
6138 (out of range or dividing by zero) results in "inf" | |
6139 or "-inf" with %f (INF or -INF with %F). | |
6140 "0.0 / 0.0" results in "nan" with %f (NAN with %F). | |
6141 Example: > | |
6142 echo printf("%.2f", 12.115) | |
6143 < 12.12 | |
6144 Note that roundoff depends on the system libraries. | |
6145 Use |round()| when in doubt. | |
6146 | |
6147 *printf-e* *printf-E* | |
6148 e E The Float argument is converted into a string of the | |
6149 form 1.234e+03 or 1.234E+03 when using 'E'. The | |
6150 precision specifies the number of digits after the | |
6151 decimal point, like with 'f'. | |
6152 | |
6153 *printf-g* *printf-G* | |
6154 g G The Float argument is converted like with 'f' if the | |
6155 value is between 0.001 (inclusive) and 10000000.0 | |
6156 (exclusive). Otherwise 'e' is used for 'g' and 'E' | |
6157 for 'G'. When no precision is specified superfluous | |
6158 zeroes and '+' signs are removed, except for the zero | |
6159 immediately after the decimal point. Thus 10000000.0 | |
6160 results in 1.0e7. | |
6161 | |
6162 *printf-%* | |
6163 % A '%' is written. No argument is converted. The | |
6164 complete conversion specification is "%%". | |
6165 | |
6166 When a Number argument is expected a String argument is also | |
6167 accepted and automatically converted. | |
6168 When a Float or String argument is expected a Number argument | |
6169 is also accepted and automatically converted. | |
6170 Any other argument type results in an error message. | |
6171 | |
6172 *E766* *E767* | |
6173 The number of {exprN} arguments must exactly match the number | |
6174 of "%" items. If there are not sufficient or too many | |
6175 arguments an error is given. Up to 18 arguments can be used. | |
6176 | |
6177 | |
6178 prompt_getprompt({buf}) *prompt_getprompt()* | |
6179 Returns the effective prompt text for buffer {buf}. {buf} can | |
6180 be a buffer name or number. See |prompt-buffer|. | |
6181 | |
6182 If the buffer doesn't exist or isn't a prompt buffer, an empty | |
6183 string is returned. | |
6184 | |
6185 Can also be used as a |method|: > | |
6186 GetBuffer()->prompt_getprompt() | |
6187 | |
6188 < {only available when compiled with the |+channel| feature} | |
6189 | |
6190 | |
6191 prompt_setcallback({buf}, {expr}) *prompt_setcallback()* | |
6192 Set prompt callback for buffer {buf} to {expr}. When {expr} | |
6193 is an empty string the callback is removed. This has only | |
6194 effect if {buf} has 'buftype' set to "prompt". | |
6195 | |
6196 The callback is invoked when pressing Enter. The current | |
6197 buffer will always be the prompt buffer. A new line for a | |
6198 prompt is added before invoking the callback, thus the prompt | |
6199 for which the callback was invoked will be in the last but one | |
6200 line. | |
6201 If the callback wants to add text to the buffer, it must | |
6202 insert it above the last line, since that is where the current | |
6203 prompt is. This can also be done asynchronously. | |
6204 The callback is invoked with one argument, which is the text | |
6205 that was entered at the prompt. This can be an empty string | |
6206 if the user only typed Enter. | |
6207 Example: > | |
6208 call prompt_setcallback(bufnr(), function('s:TextEntered')) | |
6209 func s:TextEntered(text) | |
6210 if a:text == 'exit' || a:text == 'quit' | |
6211 stopinsert | |
6212 close | |
6213 else | |
6214 call append(line('$') - 1, 'Entered: "' . a:text . '"') | |
6215 " Reset 'modified' to allow the buffer to be closed. | |
6216 set nomodified | |
6217 endif | |
6218 endfunc | |
6219 | |
6220 < Can also be used as a |method|: > | |
6221 GetBuffer()->prompt_setcallback(callback) | |
6222 | |
6223 < {only available when compiled with the |+channel| feature} | |
6224 | |
6225 prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* | |
6226 Set a callback for buffer {buf} to {expr}. When {expr} is an | |
6227 empty string the callback is removed. This has only effect if | |
6228 {buf} has 'buftype' set to "prompt". | |
6229 | |
6230 This callback will be invoked when pressing CTRL-C in Insert | |
6231 mode. Without setting a callback Vim will exit Insert mode, | |
6232 as in any buffer. | |
6233 | |
6234 Can also be used as a |method|: > | |
6235 GetBuffer()->prompt_setinterrupt(callback) | |
6236 | |
6237 < {only available when compiled with the |+channel| feature} | |
6238 | |
6239 prompt_setprompt({buf}, {text}) *prompt_setprompt()* | |
6240 Set prompt for buffer {buf} to {text}. You most likely want | |
6241 {text} to end in a space. | |
6242 The result is only visible if {buf} has 'buftype' set to | |
6243 "prompt". Example: > | |
6244 call prompt_setprompt(bufnr(), 'command: ') | |
6245 < | |
6246 Can also be used as a |method|: > | |
6247 GetBuffer()->prompt_setprompt('command: ') | |
6248 | |
6249 < {only available when compiled with the |+channel| feature} | |
6250 | |
6251 prop_ functions are documented here: |text-prop-functions| | |
6252 | |
6253 pum_getpos() *pum_getpos()* | |
6254 If the popup menu (see |ins-completion-menu|) is not visible, | |
6255 returns an empty |Dictionary|, otherwise, returns a | |
6256 |Dictionary| with the following keys: | |
6257 height nr of items visible | |
6258 width screen cells | |
6259 row top screen row (0 first row) | |
6260 col leftmost screen column (0 first col) | |
6261 size total nr of items | |
6262 scrollbar |TRUE| if scrollbar is visible | |
6263 | |
6264 The values are the same as in |v:event| during | |
6265 |CompleteChanged|. | |
6266 | |
6267 pumvisible() *pumvisible()* | |
6268 Returns non-zero when the popup menu is visible, zero | |
6269 otherwise. See |ins-completion-menu|. | |
6270 This can be used to avoid some things that would remove the | |
6271 popup menu. | |
6272 | |
6273 py3eval({expr}) *py3eval()* | |
6274 Evaluate Python expression {expr} and return its result | |
6275 converted to Vim data structures. | |
6276 Numbers and strings are returned as they are (strings are | |
6277 copied though, Unicode strings are additionally converted to | |
6278 'encoding'). | |
6279 Lists are represented as Vim |List| type. | |
6280 Dictionaries are represented as Vim |Dictionary| type with | |
6281 keys converted to strings. | |
6282 Note that in a `:def` function local variables are not visible | |
6283 to {expr}. | |
6284 | |
6285 Can also be used as a |method|: > | |
6286 GetExpr()->py3eval() | |
6287 | |
6288 < {only available when compiled with the |+python3| feature} | |
6289 | |
6290 *E858* *E859* | |
6291 pyeval({expr}) *pyeval()* | |
6292 Evaluate Python expression {expr} and return its result | |
6293 converted to Vim data structures. | |
6294 Numbers and strings are returned as they are (strings are | |
6295 copied though). | |
6296 Lists are represented as Vim |List| type. | |
6297 Dictionaries are represented as Vim |Dictionary| type, | |
6298 non-string keys result in error. | |
6299 Note that in a `:def` function local variables are not visible | |
6300 to {expr}. | |
6301 | |
6302 Can also be used as a |method|: > | |
6303 GetExpr()->pyeval() | |
6304 | |
6305 < {only available when compiled with the |+python| feature} | |
6306 | |
6307 pyxeval({expr}) *pyxeval()* | |
6308 Evaluate Python expression {expr} and return its result | |
6309 converted to Vim data structures. | |
6310 Uses Python 2 or 3, see |python_x| and 'pyxversion'. | |
6311 See also: |pyeval()|, |py3eval()| | |
6312 | |
6313 Can also be used as a |method|: > | |
6314 GetExpr()->pyxeval() | |
6315 | |
6316 < {only available when compiled with the |+python| or the | |
6317 |+python3| feature} | |
6318 | |
6319 rand([{expr}]) *rand()* *random* | |
6320 Return a pseudo-random Number generated with an xoshiro128** | |
6321 algorithm using seed {expr}. The returned number is 32 bits, | |
6322 also on 64 bits systems, for consistency. | |
6323 {expr} can be initialized by |srand()| and will be updated by | |
6324 rand(). If {expr} is omitted, an internal seed value is used | |
6325 and updated. | |
6326 | |
6327 Examples: > | |
6328 :echo rand() | |
6329 :let seed = srand() | |
6330 :echo rand(seed) | |
6331 :echo rand(seed) % 16 " random number 0 - 15 | |
6332 < | |
6333 | |
6334 *E726* *E727* | |
6335 range({expr} [, {max} [, {stride}]]) *range()* | |
6336 Returns a |List| with Numbers: | |
6337 - If only {expr} is specified: [0, 1, ..., {expr} - 1] | |
6338 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] | |
6339 - If {stride} is specified: [{expr}, {expr} + {stride}, ..., | |
6340 {max}] (increasing {expr} with {stride} each time, not | |
6341 producing a value past {max}). | |
6342 When the maximum is one before the start the result is an | |
6343 empty list. When the maximum is more than one before the | |
6344 start this is an error. | |
6345 Examples: > | |
6346 range(4) " [0, 1, 2, 3] | |
6347 range(2, 4) " [2, 3, 4] | |
6348 range(2, 9, 3) " [2, 5, 8] | |
6349 range(2, -2, -1) " [2, 1, 0, -1, -2] | |
6350 range(0) " [] | |
6351 range(2, 0) " error! | |
6352 < | |
6353 Can also be used as a |method|: > | |
6354 GetExpr()->range() | |
6355 < | |
6356 | |
6357 readblob({fname}) *readblob()* | |
6358 Read file {fname} in binary mode and return a |Blob|. | |
6359 When the file can't be opened an error message is given and | |
6360 the result is an empty |Blob|. | |
6361 Also see |readfile()| and |writefile()|. | |
6362 | |
6363 | |
6364 readdir({directory} [, {expr} [, {dict}]]) *readdir()* | |
6365 Return a list with file and directory names in {directory}. | |
6366 You can also use |glob()| if you don't need to do complicated | |
6367 things, such as limiting the number of matches. | |
6368 The list will be sorted (case sensitive), see the {dict} | |
6369 argument below for changing the sort order. | |
6370 | |
6371 When {expr} is omitted all entries are included. | |
6372 When {expr} is given, it is evaluated to check what to do: | |
6373 If {expr} results in -1 then no further entries will | |
6374 be handled. | |
6375 If {expr} results in 0 then this entry will not be | |
6376 added to the list. | |
6377 If {expr} results in 1 then this entry will be added | |
6378 to the list. | |
6379 The entries "." and ".." are always excluded. | |
6380 Each time {expr} is evaluated |v:val| is set to the entry name. | |
6381 When {expr} is a function the name is passed as the argument. | |
6382 For example, to get a list of files ending in ".txt": > | |
6383 readdir(dirname, {n -> n =~ '.txt$'}) | |
6384 < To skip hidden and backup files: > | |
6385 readdir(dirname, {n -> n !~ '^\.\|\~$'}) | |
6386 | |
6387 < The optional {dict} argument allows for further custom | |
6388 values. Currently this is used to specify if and how sorting | |
6389 should be performed. The dict can have the following members: | |
6390 | |
6391 sort How to sort the result returned from the system. | |
6392 Valid values are: | |
6393 "none" do not sort (fastest method) | |
6394 "case" sort case sensitive (byte value of | |
6395 each character, technically, using | |
6396 strcmp()) (default) | |
6397 "icase" sort case insensitive (technically | |
6398 using strcasecmp()) | |
6399 "collate" sort using the collation order | |
6400 of the "POSIX" or "C" |locale| | |
6401 (technically using strcoll()) | |
6402 Other values are silently ignored. | |
6403 | |
6404 For example, to get a list of all files in the current | |
6405 directory without sorting the individual entries: > | |
6406 readdir('.', '1', #{sort: 'none'}) | |
6407 < If you want to get a directory tree: > | |
6408 function! s:tree(dir) | |
6409 return {a:dir : map(readdir(a:dir), | |
6410 \ {_, x -> isdirectory(x) ? | |
6411 \ {x : s:tree(a:dir . '/' . x)} : x})} | |
6412 endfunction | |
6413 echo s:tree(".") | |
6414 < | |
6415 Can also be used as a |method|: > | |
6416 GetDirName()->readdir() | |
6417 < | |
6418 readdirex({directory} [, {expr} [, {dict}]]) *readdirex()* | |
6419 Extended version of |readdir()|. | |
6420 Return a list of Dictionaries with file and directory | |
6421 information in {directory}. | |
6422 This is useful if you want to get the attributes of file and | |
6423 directory at the same time as getting a list of a directory. | |
6424 This is much faster than calling |readdir()| then calling | |
6425 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for | |
6426 each file and directory especially on MS-Windows. | |
6427 The list will by default be sorted by name (case sensitive), | |
6428 the sorting can be changed by using the optional {dict} | |
6429 argument, see |readdir()|. | |
6430 | |
6431 The Dictionary for file and directory information has the | |
6432 following items: | |
6433 group Group name of the entry. (Only on Unix) | |
6434 name Name of the entry. | |
6435 perm Permissions of the entry. See |getfperm()|. | |
6436 size Size of the entry. See |getfsize()|. | |
6437 time Timestamp of the entry. See |getftime()|. | |
6438 type Type of the entry. | |
6439 On Unix, almost same as |getftype()| except: | |
6440 Symlink to a dir "linkd" | |
6441 Other symlink "link" | |
6442 On MS-Windows: | |
6443 Normal file "file" | |
6444 Directory "dir" | |
6445 Junction "junction" | |
6446 Symlink to a dir "linkd" | |
6447 Other symlink "link" | |
6448 Other reparse point "reparse" | |
6449 user User name of the entry's owner. (Only on Unix) | |
6450 On Unix, if the entry is a symlink, the Dictionary includes | |
6451 the information of the target (except the "type" item). | |
6452 On MS-Windows, it includes the information of the symlink | |
6453 itself because of performance reasons. | |
6454 | |
6455 When {expr} is omitted all entries are included. | |
6456 When {expr} is given, it is evaluated to check what to do: | |
6457 If {expr} results in -1 then no further entries will | |
6458 be handled. | |
6459 If {expr} results in 0 then this entry will not be | |
6460 added to the list. | |
6461 If {expr} results in 1 then this entry will be added | |
6462 to the list. | |
6463 The entries "." and ".." are always excluded. | |
6464 Each time {expr} is evaluated |v:val| is set to a |Dictionary| | |
6465 of the entry. | |
6466 When {expr} is a function the entry is passed as the argument. | |
6467 For example, to get a list of files ending in ".txt": > | |
6468 readdirex(dirname, {e -> e.name =~ '.txt$'}) | |
6469 < | |
6470 For example, to get a list of all files in the current | |
6471 directory without sorting the individual entries: > | |
6472 readdirex(dirname, '1', #{sort: 'none'}) | |
6473 | |
6474 < | |
6475 Can also be used as a |method|: > | |
6476 GetDirName()->readdirex() | |
6477 < | |
6478 | |
6479 *readfile()* | |
6480 readfile({fname} [, {type} [, {max}]]) | |
6481 Read file {fname} and return a |List|, each line of the file | |
6482 as an item. Lines are broken at NL characters. Macintosh | |
6483 files separated with CR will result in a single long line | |
6484 (unless a NL appears somewhere). | |
6485 All NUL characters are replaced with a NL character. | |
6486 When {type} contains "b" binary mode is used: | |
6487 - When the last line ends in a NL an extra empty list item is | |
6488 added. | |
6489 - No CR characters are removed. | |
6490 Otherwise: | |
6491 - CR characters that appear before a NL are removed. | |
6492 - Whether the last line ends in a NL or not does not matter. | |
6493 - When 'encoding' is Unicode any UTF-8 byte order mark is | |
6494 removed from the text. | |
6495 When {max} is given this specifies the maximum number of lines | |
6496 to be read. Useful if you only want to check the first ten | |
6497 lines of a file: > | |
6498 :for line in readfile(fname, '', 10) | |
6499 : if line =~ 'Date' | echo line | endif | |
6500 :endfor | |
6501 < When {max} is negative -{max} lines from the end of the file | |
6502 are returned, or as many as there are. | |
6503 When {max} is zero the result is an empty list. | |
6504 Note that without {max} the whole file is read into memory. | |
6505 Also note that there is no recognition of encoding. Read a | |
6506 file into a buffer if you need to. | |
6507 Deprecated (use |readblob()| instead): When {type} contains | |
6508 "B" a |Blob| is returned with the binary data of the file | |
6509 unmodified. | |
6510 When the file can't be opened an error message is given and | |
6511 the result is an empty list. | |
6512 Also see |writefile()|. | |
6513 | |
6514 Can also be used as a |method|: > | |
6515 GetFileName()->readfile() | |
6516 | |
6517 reduce({object}, {func} [, {initial}]) *reduce()* *E998* | |
6518 {func} is called for every item in {object}, which can be a | |
6519 |String|, |List| or a |Blob|. {func} is called with two | |
6520 arguments: the result so far and current item. After | |
6521 processing all items the result is returned. | |
6522 | |
6523 {initial} is the initial result. When omitted, the first item | |
6524 in {object} is used and {func} is first called for the second | |
6525 item. If {initial} is not given and {object} is empty no | |
6526 result can be computed, an E998 error is given. | |
6527 | |
6528 Examples: > | |
6529 echo reduce([1, 3, 5], { acc, val -> acc + val }) | |
6530 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') | |
6531 echo reduce(0z1122, { acc, val -> 2 * acc + val }) | |
6532 echo reduce('xyz', { acc, val -> acc .. ',' .. val }) | |
6533 < | |
6534 Can also be used as a |method|: > | |
6535 echo mylist->reduce({ acc, val -> acc + val }, 0) | |
6536 | |
6537 | |
6538 reg_executing() *reg_executing()* | |
6539 Returns the single letter name of the register being executed. | |
6540 Returns an empty string when no register is being executed. | |
6541 See |@|. | |
6542 | |
6543 reg_recording() *reg_recording()* | |
6544 Returns the single letter name of the register being recorded. | |
6545 Returns an empty string when not recording. See |q|. | |
6546 | |
6547 reltime([{start} [, {end}]]) *reltime()* | |
6548 Return an item that represents a time value. The item is a | |
6549 list with items that depend on the system. In Vim 9 script | |
6550 list<any> can be used. | |
6551 The item can be passed to |reltimestr()| to convert it to a | |
6552 string or |reltimefloat()| to convert to a Float. | |
6553 | |
6554 Without an argument reltime() returns the current time. | |
6555 With one argument is returns the time passed since the time | |
6556 specified in the argument. | |
6557 With two arguments it returns the time passed between {start} | |
6558 and {end}. | |
6559 | |
6560 The {start} and {end} arguments must be values returned by | |
6561 reltime(). If there is an error zero is returned in legacy | |
6562 script, in Vim9 script an error is given. | |
6563 | |
6564 Can also be used as a |method|: > | |
6565 GetStart()->reltime() | |
6566 < | |
6567 {only available when compiled with the |+reltime| feature} | |
6568 | |
6569 reltimefloat({time}) *reltimefloat()* | |
6570 Return a Float that represents the time value of {time}. | |
6571 Example: > | |
6572 let start = reltime() | |
6573 call MyFunction() | |
6574 let seconds = reltimefloat(reltime(start)) | |
6575 < See the note of reltimestr() about overhead. | |
6576 Also see |profiling|. | |
6577 If there is an error 0.0 is returned in legacy script, in Vim9 | |
6578 script an error is given. | |
6579 | |
6580 Can also be used as a |method|: > | |
6581 reltime(start)->reltimefloat() | |
6582 | |
6583 < {only available when compiled with the |+reltime| feature} | |
6584 | |
6585 reltimestr({time}) *reltimestr()* | |
6586 Return a String that represents the time value of {time}. | |
6587 This is the number of seconds, a dot and the number of | |
6588 microseconds. Example: > | |
6589 let start = reltime() | |
6590 call MyFunction() | |
6591 echo reltimestr(reltime(start)) | |
6592 < Note that overhead for the commands will be added to the time. | |
6593 The accuracy depends on the system. | |
6594 Leading spaces are used to make the string align nicely. You | |
6595 can use split() to remove it. > | |
6596 echo split(reltimestr(reltime(start)))[0] | |
6597 < Also see |profiling|. | |
6598 If there is an error an empty string is returned in legacy | |
6599 script, in Vim9 script an error is given. | |
6600 | |
6601 Can also be used as a |method|: > | |
6602 reltime(start)->reltimestr() | |
6603 | |
6604 < {only available when compiled with the |+reltime| feature} | |
6605 | |
6606 *remote_expr()* *E449* | |
6607 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) | |
6608 Send the {string} to {server}. The string is sent as an | |
6609 expression and the result is returned after evaluation. | |
6610 The result must be a String or a |List|. A |List| is turned | |
6611 into a String by joining the items with a line break in | |
6612 between (not at the end), like with join(expr, "\n"). | |
6613 If {idvar} is present and not empty, it is taken as the name | |
6614 of a variable and a {serverid} for later use with | |
6615 |remote_read()| is stored there. | |
6616 If {timeout} is given the read times out after this many | |
6617 seconds. Otherwise a timeout of 600 seconds is used. | |
6618 See also |clientserver| |RemoteReply|. | |
6619 This function is not available in the |sandbox|. | |
6620 {only available when compiled with the |+clientserver| feature} | |
6621 Note: Any errors will cause a local error message to be issued | |
6622 and the result will be the empty string. | |
6623 | |
6624 Variables will be evaluated in the global namespace, | |
6625 independent of a function currently being active. Except | |
6626 when in debug mode, then local function variables and | |
6627 arguments can be evaluated. | |
6628 | |
6629 Examples: > | |
6630 :echo remote_expr("gvim", "2+2") | |
6631 :echo remote_expr("gvim1", "b:current_syntax") | |
6632 < | |
6633 Can also be used as a |method|: > | |
6634 ServerName()->remote_expr(expr) | |
6635 | |
6636 remote_foreground({server}) *remote_foreground()* | |
6637 Move the Vim server with the name {server} to the foreground. | |
6638 The {server} argument is a string. | |
6639 This works like: > | |
6640 remote_expr({server}, "foreground()") | |
6641 < Except that on Win32 systems the client does the work, to work | |
6642 around the problem that the OS doesn't always allow the server | |
6643 to bring itself to the foreground. | |
6644 Note: This does not restore the window if it was minimized, | |
6645 like foreground() does. | |
6646 This function is not available in the |sandbox|. | |
6647 | |
6648 Can also be used as a |method|: > | |
6649 ServerName()->remote_foreground() | |
6650 | |
6651 < {only in the Win32, Athena, Motif and GTK GUI versions and the | |
6652 Win32 console version} | |
6653 | |
6654 | |
6655 remote_peek({serverid} [, {retvar}]) *remote_peek()* | |
6656 Returns a positive number if there are available strings | |
6657 from {serverid}. Copies any reply string into the variable | |
6658 {retvar} if specified. {retvar} must be a string with the | |
6659 name of a variable. | |
6660 Returns zero if none are available. | |
6661 Returns -1 if something is wrong. | |
6662 See also |clientserver|. | |
6663 This function is not available in the |sandbox|. | |
6664 {only available when compiled with the |+clientserver| feature} | |
6665 Examples: > | |
6666 :let repl = "" | |
6667 :echo "PEEK: ".remote_peek(id, "repl").": ".repl | |
6668 | |
6669 < Can also be used as a |method|: > | |
6670 ServerId()->remote_peek() | |
6671 | |
6672 remote_read({serverid}, [{timeout}]) *remote_read()* | |
6673 Return the oldest available reply from {serverid} and consume | |
6674 it. Unless a {timeout} in seconds is given, it blocks until a | |
6675 reply is available. | |
6676 See also |clientserver|. | |
6677 This function is not available in the |sandbox|. | |
6678 {only available when compiled with the |+clientserver| feature} | |
6679 Example: > | |
6680 :echo remote_read(id) | |
6681 | |
6682 < Can also be used as a |method|: > | |
6683 ServerId()->remote_read() | |
6684 < | |
6685 *remote_send()* *E241* | |
6686 remote_send({server}, {string} [, {idvar}]) | |
6687 Send the {string} to {server}. The string is sent as input | |
6688 keys and the function returns immediately. At the Vim server | |
6689 the keys are not mapped |:map|. | |
6690 If {idvar} is present, it is taken as the name of a variable | |
6691 and a {serverid} for later use with remote_read() is stored | |
6692 there. | |
6693 See also |clientserver| |RemoteReply|. | |
6694 This function is not available in the |sandbox|. | |
6695 {only available when compiled with the |+clientserver| feature} | |
6696 | |
6697 Note: Any errors will be reported in the server and may mess | |
6698 up the display. | |
6699 Examples: > | |
6700 :echo remote_send("gvim", ":DropAndReply ".file, "serverid"). | |
6701 \ remote_read(serverid) | |
6702 | |
6703 :autocmd NONE RemoteReply * | |
6704 \ echo remote_read(expand("<amatch>")) | |
6705 :echo remote_send("gvim", ":sleep 10 | echo ". | |
6706 \ 'server2client(expand("<client>"), "HELLO")<CR>') | |
6707 < | |
6708 Can also be used as a |method|: > | |
6709 ServerName()->remote_send(keys) | |
6710 < | |
6711 *remote_startserver()* *E941* *E942* | |
6712 remote_startserver({name}) | |
6713 Become the server {name}. This fails if already running as a | |
6714 server, when |v:servername| is not empty. | |
6715 | |
6716 Can also be used as a |method|: > | |
6717 ServerName()->remote_startserver() | |
6718 | |
6719 < {only available when compiled with the |+clientserver| feature} | |
6720 | |
6721 remove({list}, {idx} [, {end}]) *remove()* | |
6722 Without {end}: Remove the item at {idx} from |List| {list} and | |
6723 return the item. | |
6724 With {end}: Remove items from {idx} to {end} (inclusive) and | |
6725 return a |List| with these items. When {idx} points to the same | |
6726 item as {end} a list with one item is returned. When {end} | |
6727 points to an item before {idx} this is an error. | |
6728 See |list-index| for possible values of {idx} and {end}. | |
6729 Example: > | |
6730 :echo "last item: " . remove(mylist, -1) | |
6731 :call remove(mylist, 0, 9) | |
6732 < | |
6733 Use |delete()| to remove a file. | |
6734 | |
6735 Can also be used as a |method|: > | |
6736 mylist->remove(idx) | |
6737 | |
6738 remove({blob}, {idx} [, {end}]) | |
6739 Without {end}: Remove the byte at {idx} from |Blob| {blob} and | |
6740 return the byte. | |
6741 With {end}: Remove bytes from {idx} to {end} (inclusive) and | |
6742 return a |Blob| with these bytes. When {idx} points to the same | |
6743 byte as {end} a |Blob| with one byte is returned. When {end} | |
6744 points to a byte before {idx} this is an error. | |
6745 Example: > | |
6746 :echo "last byte: " . remove(myblob, -1) | |
6747 :call remove(mylist, 0, 9) | |
6748 | |
6749 remove({dict}, {key}) | |
6750 Remove the entry from {dict} with key {key} and return it. | |
6751 Example: > | |
6752 :echo "removed " . remove(dict, "one") | |
6753 < If there is no {key} in {dict} this is an error. | |
6754 | |
6755 rename({from}, {to}) *rename()* | |
6756 Rename the file by the name {from} to the name {to}. This | |
6757 should also work to move files across file systems. The | |
6758 result is a Number, which is 0 if the file was renamed | |
6759 successfully, and non-zero when the renaming failed. | |
6760 NOTE: If {to} exists it is overwritten without warning. | |
6761 This function is not available in the |sandbox|. | |
6762 | |
6763 Can also be used as a |method|: > | |
6764 GetOldName()->rename(newname) | |
6765 | |
6766 repeat({expr}, {count}) *repeat()* | |
6767 Repeat {expr} {count} times and return the concatenated | |
6768 result. Example: > | |
6769 :let separator = repeat('-', 80) | |
6770 < When {count} is zero or negative the result is empty. | |
6771 When {expr} is a |List| the result is {expr} concatenated | |
6772 {count} times. Example: > | |
6773 :let longlist = repeat(['a', 'b'], 3) | |
6774 < Results in ['a', 'b', 'a', 'b', 'a', 'b']. | |
6775 | |
6776 Can also be used as a |method|: > | |
6777 mylist->repeat(count) | |
6778 | |
6779 resolve({filename}) *resolve()* *E655* | |
6780 On MS-Windows, when {filename} is a shortcut (a .lnk file), | |
6781 returns the path the shortcut points to in a simplified form. | |
6782 When {filename} is a symbolic link or junction point, return | |
6783 the full path to the target. If the target of junction is | |
6784 removed, return {filename}. | |
6785 On Unix, repeat resolving symbolic links in all path | |
6786 components of {filename} and return the simplified result. | |
6787 To cope with link cycles, resolving of symbolic links is | |
6788 stopped after 100 iterations. | |
6789 On other systems, return the simplified {filename}. | |
6790 The simplification step is done as by |simplify()|. | |
6791 resolve() keeps a leading path component specifying the | |
6792 current directory (provided the result is still a relative | |
6793 path name) and also keeps a trailing path separator. | |
6794 | |
6795 Can also be used as a |method|: > | |
6796 GetName()->resolve() | |
6797 | |
6798 reverse({object}) *reverse()* | |
6799 Reverse the order of items in {object} in-place. | |
6800 {object} can be a |List| or a |Blob|. | |
6801 Returns {object}. | |
6802 If you want an object to remain unmodified make a copy first: > | |
6803 :let revlist = reverse(copy(mylist)) | |
6804 < Can also be used as a |method|: > | |
6805 mylist->reverse() | |
6806 | |
6807 round({expr}) *round()* | |
6808 Round off {expr} to the nearest integral value and return it | |
6809 as a |Float|. If {expr} lies halfway between two integral | |
6810 values, then use the larger one (away from zero). | |
6811 {expr} must evaluate to a |Float| or a |Number|. | |
6812 Examples: > | |
6813 echo round(0.456) | |
6814 < 0.0 > | |
6815 echo round(4.5) | |
6816 < 5.0 > | |
6817 echo round(-4.5) | |
6818 < -5.0 | |
6819 | |
6820 Can also be used as a |method|: > | |
6821 Compute()->round() | |
6822 < | |
6823 {only available when compiled with the |+float| feature} | |
6824 | |
6825 rubyeval({expr}) *rubyeval()* | |
6826 Evaluate Ruby expression {expr} and return its result | |
6827 converted to Vim data structures. | |
6828 Numbers, floats and strings are returned as they are (strings | |
6829 are copied though). | |
6830 Arrays are represented as Vim |List| type. | |
6831 Hashes are represented as Vim |Dictionary| type. | |
6832 Other objects are represented as strings resulted from their | |
6833 "Object#to_s" method. | |
6834 Note that in a `:def` function local variables are not visible | |
6835 to {expr}. | |
6836 | |
6837 Can also be used as a |method|: > | |
6838 GetRubyExpr()->rubyeval() | |
6839 | |
6840 < {only available when compiled with the |+ruby| feature} | |
6841 | |
6842 screenattr({row}, {col}) *screenattr()* | |
6843 Like |screenchar()|, but return the attribute. This is a rather | |
6844 arbitrary number that can only be used to compare to the | |
6845 attribute at other positions. | |
6846 | |
6847 Can also be used as a |method|: > | |
6848 GetRow()->screenattr(col) | |
6849 | |
6850 screenchar({row}, {col}) *screenchar()* | |
6851 The result is a Number, which is the character at position | |
6852 [row, col] on the screen. This works for every possible | |
6853 screen position, also status lines, window separators and the | |
6854 command line. The top left position is row one, column one | |
6855 The character excludes composing characters. For double-byte | |
6856 encodings it may only be the first byte. | |
6857 This is mainly to be used for testing. | |
6858 Returns -1 when row or col is out of range. | |
6859 | |
6860 Can also be used as a |method|: > | |
6861 GetRow()->screenchar(col) | |
6862 | |
6863 screenchars({row}, {col}) *screenchars()* | |
6864 The result is a |List| of Numbers. The first number is the same | |
6865 as what |screenchar()| returns. Further numbers are | |
6866 composing characters on top of the base character. | |
6867 This is mainly to be used for testing. | |
6868 Returns an empty List when row or col is out of range. | |
6869 | |
6870 Can also be used as a |method|: > | |
6871 GetRow()->screenchars(col) | |
6872 | |
6873 screencol() *screencol()* | |
6874 The result is a Number, which is the current screen column of | |
6875 the cursor. The leftmost column has number 1. | |
6876 This function is mainly used for testing. | |
6877 | |
6878 Note: Always returns the current screen column, thus if used | |
6879 in a command (e.g. ":echo screencol()") it will return the | |
6880 column inside the command line, which is 1 when the command is | |
6881 executed. To get the cursor position in the file use one of | |
6882 the following mappings: > | |
6883 nnoremap <expr> GG ":echom ".screencol()."\n" | |
6884 nnoremap <silent> GG :echom screencol()<CR> | |
6885 nnoremap GG <Cmd>echom screencol()<CR> | |
6886 < | |
6887 screenpos({winid}, {lnum}, {col}) *screenpos()* | |
6888 The result is a Dict with the screen position of the text | |
6889 character in window {winid} at buffer line {lnum} and column | |
6890 {col}. {col} is a one-based byte index. | |
6891 The Dict has these members: | |
6892 row screen row | |
6893 col first screen column | |
6894 endcol last screen column | |
6895 curscol cursor screen column | |
6896 If the specified position is not visible, all values are zero. | |
6897 The "endcol" value differs from "col" when the character | |
6898 occupies more than one screen cell. E.g. for a Tab "col" can | |
6899 be 1 and "endcol" can be 8. | |
6900 The "curscol" value is where the cursor would be placed. For | |
6901 a Tab it would be the same as "endcol", while for a double | |
6902 width character it would be the same as "col". | |
6903 The |conceal| feature is ignored here, the column numbers are | |
6904 as if 'conceallevel' is zero. You can set the cursor to the | |
6905 right position and use |screencol()| to get the value with | |
6906 |conceal| taken into account. | |
6907 | |
6908 Can also be used as a |method|: > | |
6909 GetWinid()->screenpos(lnum, col) | |
6910 | |
6911 screenrow() *screenrow()* | |
6912 The result is a Number, which is the current screen row of the | |
6913 cursor. The top line has number one. | |
6914 This function is mainly used for testing. | |
6915 Alternatively you can use |winline()|. | |
6916 | |
6917 Note: Same restrictions as with |screencol()|. | |
6918 | |
6919 screenstring({row}, {col}) *screenstring()* | |
6920 The result is a String that contains the base character and | |
6921 any composing characters at position [row, col] on the screen. | |
6922 This is like |screenchars()| but returning a String with the | |
6923 characters. | |
6924 This is mainly to be used for testing. | |
6925 Returns an empty String when row or col is out of range. | |
6926 | |
6927 Can also be used as a |method|: > | |
6928 GetRow()->screenstring(col) | |
6929 < | |
6930 *search()* | |
6931 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
6932 Search for regexp pattern {pattern}. The search starts at the | |
6933 cursor position (you can use |cursor()| to set it). | |
6934 | |
6935 When a match has been found its line number is returned. | |
6936 If there is no match a 0 is returned and the cursor doesn't | |
6937 move. No error message is given. | |
6938 | |
6939 {flags} is a String, which can contain these character flags: | |
6940 'b' search Backward instead of forward | |
6941 'c' accept a match at the Cursor position | |
6942 'e' move to the End of the match | |
6943 'n' do Not move the cursor | |
6944 'p' return number of matching sub-Pattern (see below) | |
6945 's' Set the ' mark at the previous location of the cursor | |
6946 'w' Wrap around the end of the file | |
6947 'W' don't Wrap around the end of the file | |
6948 'z' start searching at the cursor column instead of zero | |
6949 If neither 'w' or 'W' is given, the 'wrapscan' option applies. | |
6950 | |
6951 If the 's' flag is supplied, the ' mark is set, only if the | |
6952 cursor is moved. The 's' flag cannot be combined with the 'n' | |
6953 flag. | |
6954 | |
6955 'ignorecase', 'smartcase' and 'magic' are used. | |
6956 | |
6957 When the 'z' flag is not given, forward searching always | |
6958 starts in column zero and then matches before the cursor are | |
6959 skipped. When the 'c' flag is present in 'cpo' the next | |
6960 search starts after the match. Without the 'c' flag the next | |
6961 search starts one column further. This matters for | |
6962 overlapping matches. | |
6963 When searching backwards and the 'z' flag is given then the | |
6964 search starts in column zero, thus no match in the current | |
6965 line will be found (unless wrapping around the end of the | |
6966 file). | |
6967 | |
6968 When the {stopline} argument is given then the search stops | |
6969 after searching this line. This is useful to restrict the | |
6970 search to a range of lines. Examples: > | |
6971 let match = search('(', 'b', line("w0")) | |
6972 let end = search('END', '', line("w$")) | |
6973 < When {stopline} is used and it is not zero this also implies | |
6974 that the search does not wrap around the end of the file. | |
6975 A zero value is equal to not giving the argument. | |
6976 | |
6977 When the {timeout} argument is given the search stops when | |
6978 more than this many milliseconds have passed. Thus when | |
6979 {timeout} is 500 the search stops after half a second. | |
6980 The value must not be negative. A zero value is like not | |
6981 giving the argument. | |
6982 {only available when compiled with the |+reltime| feature} | |
6983 | |
6984 If the {skip} expression is given it is evaluated with the | |
6985 cursor positioned on the start of a match. If it evaluates to | |
6986 non-zero this match is skipped. This can be used, for | |
6987 example, to skip a match in a comment or a string. | |
6988 {skip} can be a string, which is evaluated as an expression, a | |
6989 function reference or a lambda. | |
6990 When {skip} is omitted or empty, every match is accepted. | |
6991 When evaluating {skip} causes an error the search is aborted | |
6992 and -1 returned. | |
6993 *search()-sub-match* | |
6994 With the 'p' flag the returned value is one more than the | |
6995 first sub-match in \(\). One if none of them matched but the | |
6996 whole pattern did match. | |
6997 To get the column number too use |searchpos()|. | |
6998 | |
6999 The cursor will be positioned at the match, unless the 'n' | |
7000 flag is used. | |
7001 | |
7002 Example (goes over all files in the argument list): > | |
7003 :let n = 1 | |
7004 :while n <= argc() " loop over all files in arglist | |
7005 : exe "argument " . n | |
7006 : " start at the last char in the file and wrap for the | |
7007 : " first search to find match at start of file | |
7008 : normal G$ | |
7009 : let flags = "w" | |
7010 : while search("foo", flags) > 0 | |
7011 : s/foo/bar/g | |
7012 : let flags = "W" | |
7013 : endwhile | |
7014 : update " write the file if modified | |
7015 : let n = n + 1 | |
7016 :endwhile | |
7017 < | |
7018 Example for using some flags: > | |
7019 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') | |
7020 < This will search for the keywords "if", "else", and "endif" | |
7021 under or after the cursor. Because of the 'p' flag, it | |
7022 returns 1, 2, or 3 depending on which keyword is found, or 0 | |
7023 if the search fails. With the cursor on the first word of the | |
7024 line: | |
7025 if (foo == 0) | let foo = foo + 1 | endif ~ | |
7026 the function returns 1. Without the 'c' flag, the function | |
7027 finds the "endif" and returns 3. The same thing happens | |
7028 without the 'e' flag if the cursor is on the "f" of "if". | |
7029 The 'n' flag tells the function not to move the cursor. | |
7030 | |
7031 Can also be used as a |method|: > | |
7032 GetPattern()->search() | |
7033 | |
7034 searchcount([{options}]) *searchcount()* | |
7035 Get or update the last search count, like what is displayed | |
7036 without the "S" flag in 'shortmess'. This works even if | |
7037 'shortmess' does contain the "S" flag. | |
7038 | |
7039 This returns a |Dictionary|. The dictionary is empty if the | |
7040 previous pattern was not set and "pattern" was not specified. | |
7041 | |
7042 key type meaning ~ | |
7043 current |Number| current position of match; | |
7044 0 if the cursor position is | |
7045 before the first match | |
7046 exact_match |Boolean| 1 if "current" is matched on | |
7047 "pos", otherwise 0 | |
7048 total |Number| total count of matches found | |
7049 incomplete |Number| 0: search was fully completed | |
7050 1: recomputing was timed out | |
7051 2: max count exceeded | |
7052 | |
7053 For {options} see further down. | |
7054 | |
7055 To get the last search count when |n| or |N| was pressed, call | |
7056 this function with `recompute: 0` . This sometimes returns | |
7057 wrong information because |n| and |N|'s maximum count is 99. | |
7058 If it exceeded 99 the result must be max count + 1 (100). If | |
7059 you want to get correct information, specify `recompute: 1`: > | |
7060 | |
7061 " result == maxcount + 1 (100) when many matches | |
7062 let result = searchcount(#{recompute: 0}) | |
7063 | |
7064 " Below returns correct result (recompute defaults | |
7065 " to 1) | |
7066 let result = searchcount() | |
7067 < | |
7068 The function is useful to add the count to |statusline|: > | |
7069 function! LastSearchCount() abort | |
7070 let result = searchcount(#{recompute: 0}) | |
7071 if empty(result) | |
7072 return '' | |
7073 endif | |
7074 if result.incomplete ==# 1 " timed out | |
7075 return printf(' /%s [?/??]', @/) | |
7076 elseif result.incomplete ==# 2 " max count exceeded | |
7077 if result.total > result.maxcount && | |
7078 \ result.current > result.maxcount | |
7079 return printf(' /%s [>%d/>%d]', @/, | |
7080 \ result.current, result.total) | |
7081 elseif result.total > result.maxcount | |
7082 return printf(' /%s [%d/>%d]', @/, | |
7083 \ result.current, result.total) | |
7084 endif | |
7085 endif | |
7086 return printf(' /%s [%d/%d]', @/, | |
7087 \ result.current, result.total) | |
7088 endfunction | |
7089 let &statusline .= '%{LastSearchCount()}' | |
7090 | |
7091 " Or if you want to show the count only when | |
7092 " 'hlsearch' was on | |
7093 " let &statusline .= | |
7094 " \ '%{v:hlsearch ? LastSearchCount() : ""}' | |
7095 < | |
7096 You can also update the search count, which can be useful in a | |
7097 |CursorMoved| or |CursorMovedI| autocommand: > | |
7098 | |
7099 autocmd CursorMoved,CursorMovedI * | |
7100 \ let s:searchcount_timer = timer_start( | |
7101 \ 200, function('s:update_searchcount')) | |
7102 function! s:update_searchcount(timer) abort | |
7103 if a:timer ==# s:searchcount_timer | |
7104 call searchcount(#{ | |
7105 \ recompute: 1, maxcount: 0, timeout: 100}) | |
7106 redrawstatus | |
7107 endif | |
7108 endfunction | |
7109 < | |
7110 This can also be used to count matched texts with specified | |
7111 pattern in the current buffer using "pattern": > | |
7112 | |
7113 " Count '\<foo\>' in this buffer | |
7114 " (Note that it also updates search count) | |
7115 let result = searchcount(#{pattern: '\<foo\>'}) | |
7116 | |
7117 " To restore old search count by old pattern, | |
7118 " search again | |
7119 call searchcount() | |
7120 < | |
7121 {options} must be a |Dictionary|. It can contain: | |
7122 key type meaning ~ | |
7123 recompute |Boolean| if |TRUE|, recompute the count | |
7124 like |n| or |N| was executed. | |
7125 otherwise returns the last | |
7126 computed result (when |n| or | |
7127 |N| was used when "S" is not | |
7128 in 'shortmess', or this | |
7129 function was called). | |
7130 (default: |TRUE|) | |
7131 pattern |String| recompute if this was given | |
7132 and different with |@/|. | |
7133 this works as same as the | |
7134 below command is executed | |
7135 before calling this function > | |
7136 let @/ = pattern | |
7137 < (default: |@/|) | |
7138 timeout |Number| 0 or negative number is no | |
7139 timeout. timeout milliseconds | |
7140 for recomputing the result | |
7141 (default: 0) | |
7142 maxcount |Number| 0 or negative number is no | |
7143 limit. max count of matched | |
7144 text while recomputing the | |
7145 result. if search exceeded | |
7146 total count, "total" value | |
7147 becomes `maxcount + 1` | |
7148 (default: 99) | |
7149 pos |List| `[lnum, col, off]` value | |
7150 when recomputing the result. | |
7151 this changes "current" result | |
7152 value. see |cursor()|, | |
7153 |getpos()| | |
7154 (default: cursor's position) | |
7155 | |
7156 Can also be used as a |method|: > | |
7157 GetSearchOpts()->searchcount() | |
7158 < | |
7159 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* | |
7160 Search for the declaration of {name}. | |
7161 | |
7162 With a non-zero {global} argument it works like |gD|, find | |
7163 first match in the file. Otherwise it works like |gd|, find | |
7164 first match in the function. | |
7165 | |
7166 With a non-zero {thisblock} argument matches in a {} block | |
7167 that ends before the cursor position are ignored. Avoids | |
7168 finding variable declarations only valid in another scope. | |
7169 | |
7170 Moves the cursor to the found match. | |
7171 Returns zero for success, non-zero for failure. | |
7172 Example: > | |
7173 if searchdecl('myvar') == 0 | |
7174 echo getline('.') | |
7175 endif | |
7176 < | |
7177 Can also be used as a |method|: > | |
7178 GetName()->searchdecl() | |
7179 < | |
7180 *searchpair()* | |
7181 searchpair({start}, {middle}, {end} [, {flags} [, {skip} | |
7182 [, {stopline} [, {timeout}]]]]) | |
7183 Search for the match of a nested start-end pair. This can be | |
7184 used to find the "endif" that matches an "if", while other | |
7185 if/endif pairs in between are ignored. | |
7186 The search starts at the cursor. The default is to search | |
7187 forward, include 'b' in {flags} to search backward. | |
7188 If a match is found, the cursor is positioned at it and the | |
7189 line number is returned. If no match is found 0 or -1 is | |
7190 returned and the cursor doesn't move. No error message is | |
7191 given. | |
7192 | |
7193 {start}, {middle} and {end} are patterns, see |pattern|. They | |
7194 must not contain \( \) pairs. Use of \%( \) is allowed. When | |
7195 {middle} is not empty, it is found when searching from either | |
7196 direction, but only when not in a nested start-end pair. A | |
7197 typical use is: > | |
7198 searchpair('\<if\>', '\<else\>', '\<endif\>') | |
7199 < By leaving {middle} empty the "else" is skipped. | |
7200 | |
7201 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with | |
7202 |search()|. Additionally: | |
7203 'r' Repeat until no more matches found; will find the | |
7204 outer pair. Implies the 'W' flag. | |
7205 'm' Return number of matches instead of line number with | |
7206 the match; will be > 1 when 'r' is used. | |
7207 Note: it's nearly always a good idea to use the 'W' flag, to | |
7208 avoid wrapping around the end of the file. | |
7209 | |
7210 When a match for {start}, {middle} or {end} is found, the | |
7211 {skip} expression is evaluated with the cursor positioned on | |
7212 the start of the match. It should return non-zero if this | |
7213 match is to be skipped. E.g., because it is inside a comment | |
7214 or a string. | |
7215 When {skip} is omitted or empty, every match is accepted. | |
7216 When evaluating {skip} causes an error the search is aborted | |
7217 and -1 returned. | |
7218 {skip} can be a string, a lambda, a funcref or a partial. | |
7219 Anything else makes the function fail. | |
7220 In a `:def` function when the {skip} argument is a string | |
7221 constant it is compiled into instructions. | |
7222 | |
7223 For {stopline} and {timeout} see |search()|. | |
7224 | |
7225 The value of 'ignorecase' is used. 'magic' is ignored, the | |
7226 patterns are used like it's on. | |
7227 | |
7228 The search starts exactly at the cursor. A match with | |
7229 {start}, {middle} or {end} at the next character, in the | |
7230 direction of searching, is the first one found. Example: > | |
7231 if 1 | |
7232 if 2 | |
7233 endif 2 | |
7234 endif 1 | |
7235 < When starting at the "if 2", with the cursor on the "i", and | |
7236 searching forwards, the "endif 2" is found. When starting on | |
7237 the character just before the "if 2", the "endif 1" will be | |
7238 found. That's because the "if 2" will be found first, and | |
7239 then this is considered to be a nested if/endif from "if 2" to | |
7240 "endif 2". | |
7241 When searching backwards and {end} is more than one character, | |
7242 it may be useful to put "\zs" at the end of the pattern, so | |
7243 that when the cursor is inside a match with the end it finds | |
7244 the matching start. | |
7245 | |
7246 Example, to find the "endif" command in a Vim script: > | |
7247 | |
7248 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', | |
7249 \ 'getline(".") =~ "^\\s*\""') | |
7250 | |
7251 < The cursor must be at or after the "if" for which a match is | |
7252 to be found. Note that single-quote strings are used to avoid | |
7253 having to double the backslashes. The skip expression only | |
7254 catches comments at the start of a line, not after a command. | |
7255 Also, a word "en" or "if" halfway a line is considered a | |
7256 match. | |
7257 Another example, to search for the matching "{" of a "}": > | |
7258 | |
7259 :echo searchpair('{', '', '}', 'bW') | |
7260 | |
7261 < This works when the cursor is at or before the "}" for which a | |
7262 match is to be found. To reject matches that syntax | |
7263 highlighting recognized as strings: > | |
7264 | |
7265 :echo searchpair('{', '', '}', 'bW', | |
7266 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') | |
7267 < | |
7268 *searchpairpos()* | |
7269 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} | |
7270 [, {stopline} [, {timeout}]]]]) | |
7271 Same as |searchpair()|, but returns a |List| with the line and | |
7272 column position of the match. The first element of the |List| | |
7273 is the line number and the second element is the byte index of | |
7274 the column position of the match. If no match is found, | |
7275 returns [0, 0]. > | |
7276 | |
7277 :let [lnum,col] = searchpairpos('{', '', '}', 'n') | |
7278 < | |
7279 See |match-parens| for a bigger and more useful example. | |
7280 | |
7281 *searchpos()* | |
7282 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
7283 Same as |search()|, but returns a |List| with the line and | |
7284 column position of the match. The first element of the |List| | |
7285 is the line number and the second element is the byte index of | |
7286 the column position of the match. If no match is found, | |
7287 returns [0, 0]. | |
7288 Example: > | |
7289 :let [lnum, col] = searchpos('mypattern', 'n') | |
7290 | |
7291 < When the 'p' flag is given then there is an extra item with | |
7292 the sub-pattern match number |search()-sub-match|. Example: > | |
7293 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') | |
7294 < In this example "submatch" is 2 when a lowercase letter is | |
7295 found |/\l|, 3 when an uppercase letter is found |/\u|. | |
7296 | |
7297 Can also be used as a |method|: > | |
7298 GetPattern()->searchpos() | |
7299 | |
7300 server2client({clientid}, {string}) *server2client()* | |
7301 Send a reply string to {clientid}. The most recent {clientid} | |
7302 that sent a string can be retrieved with expand("<client>"). | |
7303 {only available when compiled with the |+clientserver| feature} | |
7304 Returns zero for success, -1 for failure. | |
7305 Note: | |
7306 This id has to be stored before the next command can be | |
7307 received. I.e. before returning from the received command and | |
7308 before calling any commands that waits for input. | |
7309 See also |clientserver|. | |
7310 Example: > | |
7311 :echo server2client(expand("<client>"), "HELLO") | |
7312 | |
7313 < Can also be used as a |method|: > | |
7314 GetClientId()->server2client(string) | |
7315 < | |
7316 serverlist() *serverlist()* | |
7317 Return a list of available server names, one per line. | |
7318 When there are no servers or the information is not available | |
7319 an empty string is returned. See also |clientserver|. | |
7320 {only available when compiled with the |+clientserver| feature} | |
7321 Example: > | |
7322 :echo serverlist() | |
7323 < | |
7324 setbufline({buf}, {lnum}, {text}) *setbufline()* | |
7325 Set line {lnum} to {text} in buffer {buf}. This works like | |
7326 |setline()| for the specified buffer. | |
7327 | |
7328 This function works only for loaded buffers. First call | |
7329 |bufload()| if needed. | |
7330 | |
7331 To insert lines use |appendbufline()|. | |
7332 Any text properties in {lnum} are cleared. | |
7333 | |
7334 {text} can be a string to set one line, or a list of strings | |
7335 to set multiple lines. If the list extends below the last | |
7336 line then those lines are added. | |
7337 | |
7338 For the use of {buf}, see |bufname()| above. | |
7339 | |
7340 {lnum} is used like with |setline()|. | |
7341 Use "$" to refer to the last line in buffer {buf}. | |
7342 When {lnum} is just below the last line the {text} will be | |
7343 added below the last line. | |
7344 | |
7345 When {buf} is not a valid buffer, the buffer is not loaded or | |
7346 {lnum} is not valid then 1 is returned. In |Vim9| script an | |
7347 error is given. | |
7348 On success 0 is returned. | |
7349 | |
7350 Can also be used as a |method|, the base is passed as the | |
7351 third argument: > | |
7352 GetText()->setbufline(buf, lnum) | |
7353 | |
7354 setbufvar({buf}, {varname}, {val}) *setbufvar()* | |
7355 Set option or local variable {varname} in buffer {buf} to | |
7356 {val}. | |
7357 This also works for a global or local window option, but it | |
7358 doesn't work for a global or local window variable. | |
7359 For a local window option the global value is unchanged. | |
7360 For the use of {buf}, see |bufname()| above. | |
7361 The {varname} argument is a string. | |
7362 Note that the variable name without "b:" must be used. | |
7363 Examples: > | |
7364 :call setbufvar(1, "&mod", 1) | |
7365 :call setbufvar("todo", "myvar", "foobar") | |
7366 < This function is not available in the |sandbox|. | |
7367 | |
7368 Can also be used as a |method|, the base is passed as the | |
7369 third argument: > | |
7370 GetValue()->setbufvar(buf, varname) | |
7371 | |
7372 | |
7373 setcellwidths({list}) *setcellwidths()* | |
7374 Specify overrides for cell widths of character ranges. This | |
7375 tells Vim how wide characters are, counted in screen cells. | |
7376 This overrides 'ambiwidth'. Example: > | |
7377 setcellwidths([[0xad, 0xad, 1], | |
7378 \ [0x2194, 0x2199, 2]]) | |
7379 | |
7380 < *E1109* *E1110* *E1111* *E1112* *E1113* | |
7381 The {list} argument is a list of lists with each three | |
7382 numbers. These three numbers are [low, high, width]. "low" | |
7383 and "high" can be the same, in which case this refers to one | |
7384 character. Otherwise it is the range of characters from "low" | |
7385 to "high" (inclusive). "width" is either 1 or 2, indicating | |
7386 the character width in screen cells. | |
7387 An error is given if the argument is invalid, also when a | |
7388 range overlaps with another. | |
7389 Only characters with value 0x100 and higher can be used. | |
7390 | |
7391 If the new value causes 'fillchars' or 'listchars' to become | |
7392 invalid it is rejected and an error is given. | |
7393 | |
7394 To clear the overrides pass an empty list: > | |
7395 setcellwidths([]); | |
7396 < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see | |
7397 the effect for known emoji characters. | |
7398 | |
7399 setcharpos({expr}, {list}) *setcharpos()* | |
7400 Same as |setpos()| but uses the specified column number as the | |
7401 character index instead of the byte index in the line. | |
7402 | |
7403 Example: | |
7404 With the text "여보세요" in line 8: > | |
7405 call setcharpos('.', [0, 8, 4, 0]) | |
7406 < positions the cursor on the fourth character '요'. > | |
7407 call setpos('.', [0, 8, 4, 0]) | |
7408 < positions the cursor on the second character '보'. | |
7409 | |
7410 Can also be used as a |method|: > | |
7411 GetPosition()->setcharpos('.') | |
7412 | |
7413 setcharsearch({dict}) *setcharsearch()* | |
7414 Set the current character search information to {dict}, | |
7415 which contains one or more of the following entries: | |
7416 | |
7417 char character which will be used for a subsequent | |
7418 |,| or |;| command; an empty string clears the | |
7419 character search | |
7420 forward direction of character search; 1 for forward, | |
7421 0 for backward | |
7422 until type of character search; 1 for a |t| or |T| | |
7423 character search, 0 for an |f| or |F| | |
7424 character search | |
7425 | |
7426 This can be useful to save/restore a user's character search | |
7427 from a script: > | |
7428 :let prevsearch = getcharsearch() | |
7429 :" Perform a command which clobbers user's search | |
7430 :call setcharsearch(prevsearch) | |
7431 < Also see |getcharsearch()|. | |
7432 | |
7433 Can also be used as a |method|: > | |
7434 SavedSearch()->setcharsearch() | |
7435 | |
7436 setcmdpos({pos}) *setcmdpos()* | |
7437 Set the cursor position in the command line to byte position | |
7438 {pos}. The first position is 1. | |
7439 Use |getcmdpos()| to obtain the current position. | |
7440 Only works while editing the command line, thus you must use | |
7441 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For | |
7442 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is | |
7443 set after the command line is set to the expression. For | |
7444 |c_CTRL-R_=| it is set after evaluating the expression but | |
7445 before inserting the resulting text. | |
7446 When the number is too big the cursor is put at the end of the | |
7447 line. A number smaller than one has undefined results. | |
7448 Returns FALSE when successful, TRUE when not editing the | |
7449 command line. | |
7450 | |
7451 Can also be used as a |method|: > | |
7452 GetPos()->setcmdpos() | |
7453 | |
7454 setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* | |
7455 setcursorcharpos({list}) | |
7456 Same as |cursor()| but uses the specified column number as the | |
7457 character index instead of the byte index in the line. | |
7458 | |
7459 Example: | |
7460 With the text "여보세요" in line 4: > | |
7461 call setcursorcharpos(4, 3) | |
7462 < positions the cursor on the third character '세'. > | |
7463 call cursor(4, 3) | |
7464 < positions the cursor on the first character '여'. | |
7465 | |
7466 Can also be used as a |method|: > | |
7467 GetCursorPos()->setcursorcharpos() | |
7468 | |
7469 | |
7470 setenv({name}, {val}) *setenv()* | |
7471 Set environment variable {name} to {val}. Example: > | |
7472 call setenv('HOME', '/home/myhome') | |
7473 | |
7474 < When {val} is |v:null| the environment variable is deleted. | |
7475 See also |expr-env|. | |
7476 | |
7477 Can also be used as a |method|, the base is passed as the | |
7478 second argument: > | |
7479 GetPath()->setenv('PATH') | |
7480 | |
7481 setfperm({fname}, {mode}) *setfperm()* *chmod* | |
7482 Set the file permissions for {fname} to {mode}. | |
7483 {mode} must be a string with 9 characters. It is of the form | |
7484 "rwxrwxrwx", where each group of "rwx" flags represent, in | |
7485 turn, the permissions of the owner of the file, the group the | |
7486 file belongs to, and other users. A '-' character means the | |
7487 permission is off, any other character means on. Multi-byte | |
7488 characters are not supported. | |
7489 | |
7490 For example "rw-r-----" means read-write for the user, | |
7491 readable by the group, not accessible by others. "xx-x-----" | |
7492 would do the same thing. | |
7493 | |
7494 Returns non-zero for success, zero for failure. | |
7495 | |
7496 Can also be used as a |method|: > | |
7497 GetFilename()->setfperm(mode) | |
7498 < | |
7499 To read permissions see |getfperm()|. | |
7500 | |
7501 | |
7502 setline({lnum}, {text}) *setline()* | |
7503 Set line {lnum} of the current buffer to {text}. To insert | |
7504 lines use |append()|. To set lines in another buffer use | |
7505 |setbufline()|. Any text properties in {lnum} are cleared. | |
7506 | |
7507 {lnum} is used like with |getline()|. | |
7508 When {lnum} is just below the last line the {text} will be | |
7509 added below the last line. | |
7510 {text} can be any type or a List of any type, each item is | |
7511 converted to a String. | |
7512 | |
7513 If this succeeds, FALSE is returned. If this fails (most likely | |
7514 because {lnum} is invalid) TRUE is returned. | |
7515 In |Vim9| script an error is given if {lnum} is invalid. | |
7516 | |
7517 Example: > | |
7518 :call setline(5, strftime("%c")) | |
7519 | |
7520 < When {text} is a |List| then line {lnum} and following lines | |
7521 will be set to the items in the list. Example: > | |
7522 :call setline(5, ['aaa', 'bbb', 'ccc']) | |
7523 < This is equivalent to: > | |
7524 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] | |
7525 : call setline(n, l) | |
7526 :endfor | |
7527 | |
7528 < Note: The '[ and '] marks are not set. | |
7529 | |
7530 Can also be used as a |method|, the base is passed as the | |
7531 second argument: > | |
7532 GetText()->setline(lnum) | |
7533 | |
7534 setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* | |
7535 Create or replace or add to the location list for window {nr}. | |
7536 {nr} can be the window number or the |window-ID|. | |
7537 When {nr} is zero the current window is used. | |
7538 | |
7539 For a location list window, the displayed location list is | |
7540 modified. For an invalid window number {nr}, -1 is returned. | |
7541 Otherwise, same as |setqflist()|. | |
7542 Also see |location-list|. | |
7543 | |
7544 For {action} see |setqflist-action|. | |
7545 | |
7546 If the optional {what} dictionary argument is supplied, then | |
7547 only the items listed in {what} are set. Refer to |setqflist()| | |
7548 for the list of supported keys in {what}. | |
7549 | |
7550 Can also be used as a |method|, the base is passed as the | |
7551 second argument: > | |
7552 GetLoclist()->setloclist(winnr) | |
7553 | |
7554 setmatches({list} [, {win}]) *setmatches()* | |
7555 Restores a list of matches saved by |getmatches()| for the | |
7556 current window. Returns 0 if successful, otherwise -1. All | |
7557 current matches are cleared before the list is restored. See | |
7558 example for |getmatches()|. | |
7559 If {win} is specified, use the window with this number or | |
7560 window ID instead of the current window. | |
7561 | |
7562 Can also be used as a |method|: > | |
7563 GetMatches()->setmatches() | |
7564 < | |
7565 *setpos()* | |
7566 setpos({expr}, {list}) | |
7567 Set the position for String {expr}. Possible values: | |
7568 . the cursor | |
7569 'x mark x | |
7570 | |
7571 {list} must be a |List| with four or five numbers: | |
7572 [bufnum, lnum, col, off] | |
7573 [bufnum, lnum, col, off, curswant] | |
7574 | |
7575 "bufnum" is the buffer number. Zero can be used for the | |
7576 current buffer. When setting an uppercase mark "bufnum" is | |
7577 used for the mark position. For other marks it specifies the | |
7578 buffer to set the mark in. You can use the |bufnr()| function | |
7579 to turn a file name into a buffer number. | |
7580 For setting the cursor and the ' mark "bufnum" is ignored, | |
7581 since these are associated with a window, not a buffer. | |
7582 Does not change the jumplist. | |
7583 | |
7584 "lnum" and "col" are the position in the buffer. The first | |
7585 column is 1. Use a zero "lnum" to delete a mark. If "col" is | |
7586 smaller than 1 then 1 is used. To use the character count | |
7587 instead of the byte count, use |setcharpos()|. | |
7588 | |
7589 The "off" number is only used when 'virtualedit' is set. Then | |
7590 it is the offset in screen columns from the start of the | |
7591 character. E.g., a position within a <Tab> or after the last | |
7592 character. | |
7593 | |
7594 The "curswant" number is only used when setting the cursor | |
7595 position. It sets the preferred column for when moving the | |
7596 cursor vertically. When the "curswant" number is missing the | |
7597 preferred column is not set. When it is present and setting a | |
7598 mark position it is not used. | |
7599 | |
7600 Note that for '< and '> changing the line number may result in | |
7601 the marks to be effectively be swapped, so that '< is always | |
7602 before '>. | |
7603 | |
7604 Returns 0 when the position could be set, -1 otherwise. | |
7605 An error message is given if {expr} is invalid. | |
7606 | |
7607 Also see |setcharpos()|, |getpos()| and |getcurpos()|. | |
7608 | |
7609 This does not restore the preferred column for moving | |
7610 vertically; if you set the cursor position with this, |j| and | |
7611 |k| motions will jump to previous columns! Use |cursor()| to | |
7612 also set the preferred column. Also see the "curswant" key in | |
7613 |winrestview()|. | |
7614 | |
7615 Can also be used as a |method|: > | |
7616 GetPosition()->setpos('.') | |
7617 | |
7618 setqflist({list} [, {action} [, {what}]]) *setqflist()* | |
7619 Create or replace or add to the quickfix list. | |
7620 | |
7621 If the optional {what} dictionary argument is supplied, then | |
7622 only the items listed in {what} are set. The first {list} | |
7623 argument is ignored. See below for the supported items in | |
7624 {what}. | |
7625 *setqflist-what* | |
7626 When {what} is not present, the items in {list} are used. Each | |
7627 item must be a dictionary. Non-dictionary items in {list} are | |
7628 ignored. Each dictionary item can contain the following | |
7629 entries: | |
7630 | |
7631 bufnr buffer number; must be the number of a valid | |
7632 buffer | |
7633 filename name of a file; only used when "bufnr" is not | |
7634 present or it is invalid. | |
7635 module name of a module; if given it will be used in | |
7636 quickfix error window instead of the filename. | |
7637 lnum line number in the file | |
7638 pattern search pattern used to locate the error | |
7639 col column number | |
7640 vcol when non-zero: "col" is visual column | |
7641 when zero: "col" is byte index | |
7642 nr error number | |
7643 text description of the error | |
7644 type single-character error type, 'E', 'W', etc. | |
7645 valid recognized error message | |
7646 | |
7647 The "col", "vcol", "nr", "type" and "text" entries are | |
7648 optional. Either "lnum" or "pattern" entry can be used to | |
7649 locate a matching error line. | |
7650 If the "filename" and "bufnr" entries are not present or | |
7651 neither the "lnum" or "pattern" entries are present, then the | |
7652 item will not be handled as an error line. | |
7653 If both "pattern" and "lnum" are present then "pattern" will | |
7654 be used. | |
7655 If the "valid" entry is not supplied, then the valid flag is | |
7656 set when "bufnr" is a valid buffer or "filename" exists. | |
7657 If you supply an empty {list}, the quickfix list will be | |
7658 cleared. | |
7659 Note that the list is not exactly the same as what | |
7660 |getqflist()| returns. | |
7661 | |
7662 {action} values: *setqflist-action* *E927* | |
7663 'a' The items from {list} are added to the existing | |
7664 quickfix list. If there is no existing list, then a | |
7665 new list is created. | |
7666 | |
7667 'r' The items from the current quickfix list are replaced | |
7668 with the items from {list}. This can also be used to | |
7669 clear the list: > | |
7670 :call setqflist([], 'r') | |
7671 < | |
7672 'f' All the quickfix lists in the quickfix stack are | |
7673 freed. | |
7674 | |
7675 If {action} is not present or is set to ' ', then a new list | |
7676 is created. The new quickfix list is added after the current | |
7677 quickfix list in the stack and all the following lists are | |
7678 freed. To add a new quickfix list at the end of the stack, | |
7679 set "nr" in {what} to "$". | |
7680 | |
7681 The following items can be specified in dictionary {what}: | |
7682 context quickfix list context. See |quickfix-context| | |
7683 efm errorformat to use when parsing text from | |
7684 "lines". If this is not present, then the | |
7685 'errorformat' option value is used. | |
7686 See |quickfix-parse| | |
7687 id quickfix list identifier |quickfix-ID| | |
7688 idx index of the current entry in the quickfix | |
7689 list specified by 'id' or 'nr'. If set to '$', | |
7690 then the last entry in the list is set as the | |
7691 current entry. See |quickfix-index| | |
7692 items list of quickfix entries. Same as the {list} | |
7693 argument. | |
7694 lines use 'errorformat' to parse a list of lines and | |
7695 add the resulting entries to the quickfix list | |
7696 {nr} or {id}. Only a |List| value is supported. | |
7697 See |quickfix-parse| | |
7698 nr list number in the quickfix stack; zero | |
7699 means the current quickfix list and "$" means | |
7700 the last quickfix list. | |
7701 quickfixtextfunc | |
7702 function to get the text to display in the | |
7703 quickfix window. The value can be the name of | |
7704 a function or a funcref or a lambda. Refer to | |
7705 |quickfix-window-function| for an explanation | |
7706 of how to write the function and an example. | |
7707 title quickfix list title text. See |quickfix-title| | |
7708 Unsupported keys in {what} are ignored. | |
7709 If the "nr" item is not present, then the current quickfix list | |
7710 is modified. When creating a new quickfix list, "nr" can be | |
7711 set to a value one greater than the quickfix stack size. | |
7712 When modifying a quickfix list, to guarantee that the correct | |
7713 list is modified, "id" should be used instead of "nr" to | |
7714 specify the list. | |
7715 | |
7716 Examples (See also |setqflist-examples|): > | |
7717 :call setqflist([], 'r', {'title': 'My search'}) | |
7718 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) | |
7719 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) | |
7720 < | |
7721 Returns zero for success, -1 for failure. | |
7722 | |
7723 This function can be used to create a quickfix list | |
7724 independent of the 'errorformat' setting. Use a command like | |
7725 `:cc 1` to jump to the first position. | |
7726 | |
7727 Can also be used as a |method|, the base is passed as the | |
7728 second argument: > | |
7729 GetErrorlist()->setqflist() | |
7730 < | |
7731 *setreg()* | |
7732 setreg({regname}, {value} [, {options}]) | |
7733 Set the register {regname} to {value}. | |
7734 If {regname} is "" or "@", the unnamed register '"' is used. | |
7735 The {regname} argument is a string. In |Vim9-script| | |
7736 {regname} must be one character. | |
7737 | |
7738 {value} may be any value returned by |getreg()| or | |
7739 |getreginfo()|, including a |List| or |Dict|. | |
7740 If {options} contains "a" or {regname} is upper case, | |
7741 then the value is appended. | |
7742 | |
7743 {options} can also contain a register type specification: | |
7744 "c" or "v" |characterwise| mode | |
7745 "l" or "V" |linewise| mode | |
7746 "b" or "<CTRL-V>" |blockwise-visual| mode | |
7747 If a number immediately follows "b" or "<CTRL-V>" then this is | |
7748 used as the width of the selection - if it is not specified | |
7749 then the width of the block is set to the number of characters | |
7750 in the longest line (counting a <Tab> as 1 character). | |
7751 | |
7752 If {options} contains no register settings, then the default | |
7753 is to use character mode unless {value} ends in a <NL> for | |
7754 string {value} and linewise mode for list {value}. Blockwise | |
7755 mode is never selected automatically. | |
7756 Returns zero for success, non-zero for failure. | |
7757 | |
7758 *E883* | |
7759 Note: you may not use |List| containing more than one item to | |
7760 set search and expression registers. Lists containing no | |
7761 items act like empty strings. | |
7762 | |
7763 Examples: > | |
7764 :call setreg(v:register, @*) | |
7765 :call setreg('*', @%, 'ac') | |
7766 :call setreg('a', "1\n2\n3", 'b5') | |
7767 :call setreg('"', { 'points_to': 'a'}) | |
7768 | |
7769 < This example shows using the functions to save and restore a | |
7770 register: > | |
7771 :let var_a = getreginfo() | |
7772 :call setreg('a', var_a) | |
7773 < or: > | |
7774 :let var_a = getreg('a', 1, 1) | |
7775 :let var_amode = getregtype('a') | |
7776 .... | |
7777 :call setreg('a', var_a, var_amode) | |
7778 < Note: you may not reliably restore register value | |
7779 without using the third argument to |getreg()| as without it | |
7780 newlines are represented as newlines AND Nul bytes are | |
7781 represented as newlines as well, see |NL-used-for-Nul|. | |
7782 | |
7783 You can also change the type of a register by appending | |
7784 nothing: > | |
7785 :call setreg('a', '', 'al') | |
7786 | |
7787 < Can also be used as a |method|, the base is passed as the | |
7788 second argument: > | |
7789 GetText()->setreg('a') | |
7790 | |
7791 settabvar({tabnr}, {varname}, {val}) *settabvar()* | |
7792 Set tab-local variable {varname} to {val} in tab page {tabnr}. | |
7793 |t:var| | |
7794 The {varname} argument is a string. | |
7795 Note that autocommands are blocked, side effects may not be | |
7796 triggered, e.g. when setting 'filetype'. | |
7797 Note that the variable name without "t:" must be used. | |
7798 Tabs are numbered starting with one. | |
7799 This function is not available in the |sandbox|. | |
7800 | |
7801 Can also be used as a |method|, the base is passed as the | |
7802 third argument: > | |
7803 GetValue()->settabvar(tab, name) | |
7804 | |
7805 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* | |
7806 Set option or local variable {varname} in window {winnr} to | |
7807 {val}. | |
7808 Tabs are numbered starting with one. For the current tabpage | |
7809 use |setwinvar()|. | |
7810 {winnr} can be the window number or the |window-ID|. | |
7811 When {winnr} is zero the current window is used. | |
7812 Note that autocommands are blocked, side effects may not be | |
7813 triggered, e.g. when setting 'filetype' or 'syntax'. | |
7814 This also works for a global or local buffer option, but it | |
7815 doesn't work for a global or local buffer variable. | |
7816 For a local buffer option the global value is unchanged. | |
7817 Note that the variable name without "w:" must be used. | |
7818 Examples: > | |
7819 :call settabwinvar(1, 1, "&list", 0) | |
7820 :call settabwinvar(3, 2, "myvar", "foobar") | |
7821 < This function is not available in the |sandbox|. | |
7822 | |
7823 Can also be used as a |method|, the base is passed as the | |
7824 fourth argument: > | |
7825 GetValue()->settabwinvar(tab, winnr, name) | |
7826 | |
7827 settagstack({nr}, {dict} [, {action}]) *settagstack()* | |
7828 Modify the tag stack of the window {nr} using {dict}. | |
7829 {nr} can be the window number or the |window-ID|. | |
7830 | |
7831 For a list of supported items in {dict}, refer to | |
7832 |gettagstack()|. "curidx" takes effect before changing the tag | |
7833 stack. | |
7834 *E962* | |
7835 How the tag stack is modified depends on the {action} | |
7836 argument: | |
7837 - If {action} is not present or is set to 'r', then the tag | |
7838 stack is replaced. | |
7839 - If {action} is set to 'a', then new entries from {dict} are | |
7840 pushed (added) onto the tag stack. | |
7841 - If {action} is set to 't', then all the entries from the | |
7842 current entry in the tag stack or "curidx" in {dict} are | |
7843 removed and then new entries are pushed to the stack. | |
7844 | |
7845 The current index is set to one after the length of the tag | |
7846 stack after the modification. | |
7847 | |
7848 Returns zero for success, -1 for failure. | |
7849 | |
7850 Examples (for more examples see |tagstack-examples|): | |
7851 Empty the tag stack of window 3: > | |
7852 call settagstack(3, {'items' : []}) | |
7853 | |
7854 < Save and restore the tag stack: > | |
7855 let stack = gettagstack(1003) | |
7856 " do something else | |
7857 call settagstack(1003, stack) | |
7858 unlet stack | |
7859 < | |
7860 Can also be used as a |method|, the base is passed as the | |
7861 second argument: > | |
7862 GetStack()->settagstack(winnr) | |
7863 | |
7864 setwinvar({winnr}, {varname}, {val}) *setwinvar()* | |
7865 Like |settabwinvar()| for the current tab page. | |
7866 Examples: > | |
7867 :call setwinvar(1, "&list", 0) | |
7868 :call setwinvar(2, "myvar", "foobar") | |
7869 | |
7870 < Can also be used as a |method|, the base is passed as the | |
7871 third argument: > | |
7872 GetValue()->setwinvar(winnr, name) | |
7873 | |
7874 sha256({string}) *sha256()* | |
7875 Returns a String with 64 hex characters, which is the SHA256 | |
7876 checksum of {string}. | |
7877 | |
7878 Can also be used as a |method|: > | |
7879 GetText()->sha256() | |
7880 | |
7881 < {only available when compiled with the |+cryptv| feature} | |
7882 | |
7883 shellescape({string} [, {special}]) *shellescape()* | |
7884 Escape {string} for use as a shell command argument. | |
7885 When the 'shell' contains powershell (MS-Windows) or pwsh | |
7886 (MS-Windows, Linux, and MacOS) then it will enclose {string} | |
7887 in single quotes and will double up all internal single | |
7888 quotes. | |
7889 On MS-Windows, when 'shellslash' is not set, it will enclose | |
7890 {string} in double quotes and double all double quotes within | |
7891 {string}. | |
7892 Otherwise it will enclose {string} in single quotes and | |
7893 replace all "'" with "'\''". | |
7894 | |
7895 When the {special} argument is present and it's a non-zero | |
7896 Number or a non-empty String (|non-zero-arg|), then special | |
7897 items such as "!", "%", "#" and "<cword>" will be preceded by | |
7898 a backslash. This backslash will be removed again by the |:!| | |
7899 command. | |
7900 | |
7901 The "!" character will be escaped (again with a |non-zero-arg| | |
7902 {special}) when 'shell' contains "csh" in the tail. That is | |
7903 because for csh and tcsh "!" is used for history replacement | |
7904 even when inside single quotes. | |
7905 | |
7906 With a |non-zero-arg| {special} the <NL> character is also | |
7907 escaped. When 'shell' containing "csh" in the tail it's | |
7908 escaped a second time. | |
7909 | |
7910 The "\" character will be escaped when 'shell' contains "fish" | |
7911 in the tail. That is because for fish "\" is used as an escape | |
7912 character inside single quotes. | |
7913 | |
7914 Example of use with a |:!| command: > | |
7915 :exe '!dir ' . shellescape(expand('<cfile>'), 1) | |
7916 < This results in a directory listing for the file under the | |
7917 cursor. Example of use with |system()|: > | |
7918 :call system("chmod +w -- " . shellescape(expand("%"))) | |
7919 < See also |::S|. | |
7920 | |
7921 Can also be used as a |method|: > | |
7922 GetCommand()->shellescape() | |
7923 | |
7924 shiftwidth([{col}]) *shiftwidth()* | |
7925 Returns the effective value of 'shiftwidth'. This is the | |
7926 'shiftwidth' value unless it is zero, in which case it is the | |
7927 'tabstop' value. This function was introduced with patch | |
7928 7.3.694 in 2012, everybody should have it by now (however it | |
7929 did not allow for the optional {col} argument until 8.1.542). | |
7930 | |
7931 When there is one argument {col} this is used as column number | |
7932 for which to return the 'shiftwidth' value. This matters for the | |
7933 'vartabstop' feature. If the 'vartabstop' setting is enabled and | |
7934 no {col} argument is given, column 1 will be assumed. | |
7935 | |
7936 Can also be used as a |method|: > | |
7937 GetColumn()->shiftwidth() | |
7938 | |
7939 sign_ functions are documented here: |sign-functions-details| | |
7940 | |
7941 | |
7942 simplify({filename}) *simplify()* | |
7943 Simplify the file name as much as possible without changing | |
7944 the meaning. Shortcuts (on MS-Windows) or symbolic links (on | |
7945 Unix) are not resolved. If the first path component in | |
7946 {filename} designates the current directory, this will be | |
7947 valid for the result as well. A trailing path separator is | |
7948 not removed either. On Unix "//path" is unchanged, but | |
7949 "///path" is simplified to "/path" (this follows the Posix | |
7950 standard). | |
7951 Example: > | |
7952 simplify("./dir/.././/file/") == "./file/" | |
7953 < Note: The combination "dir/.." is only removed if "dir" is | |
7954 a searchable directory or does not exist. On Unix, it is also | |
7955 removed when "dir" is a symbolic link within the same | |
7956 directory. In order to resolve all the involved symbolic | |
7957 links before simplifying the path name, use |resolve()|. | |
7958 | |
7959 Can also be used as a |method|: > | |
7960 GetName()->simplify() | |
7961 | |
7962 sin({expr}) *sin()* | |
7963 Return the sine of {expr}, measured in radians, as a |Float|. | |
7964 {expr} must evaluate to a |Float| or a |Number|. | |
7965 Examples: > | |
7966 :echo sin(100) | |
7967 < -0.506366 > | |
7968 :echo sin(-4.01) | |
7969 < 0.763301 | |
7970 | |
7971 Can also be used as a |method|: > | |
7972 Compute()->sin() | |
7973 < | |
7974 {only available when compiled with the |+float| feature} | |
7975 | |
7976 | |
7977 sinh({expr}) *sinh()* | |
7978 Return the hyperbolic sine of {expr} as a |Float| in the range | |
7979 [-inf, inf]. | |
7980 {expr} must evaluate to a |Float| or a |Number|. | |
7981 Examples: > | |
7982 :echo sinh(0.5) | |
7983 < 0.521095 > | |
7984 :echo sinh(-0.9) | |
7985 < -1.026517 | |
7986 | |
7987 Can also be used as a |method|: > | |
7988 Compute()->sinh() | |
7989 < | |
7990 {only available when compiled with the |+float| feature} | |
7991 | |
7992 | |
7993 slice({expr}, {start} [, {end}]) *slice()* | |
7994 Similar to using a |slice| "expr[start : end]", but "end" is | |
7995 used exclusive. And for a string the indexes are used as | |
7996 character indexes instead of byte indexes, like in | |
7997 |vim9script|. Also, composing characters are not counted. | |
7998 When {end} is omitted the slice continues to the last item. | |
7999 When {end} is -1 the last item is omitted. | |
8000 | |
8001 Can also be used as a |method|: > | |
8002 GetList()->slice(offset) | |
8003 | |
8004 | |
8005 sort({list} [, {func} [, {dict}]]) *sort()* *E702* | |
8006 Sort the items in {list} in-place. Returns {list}. | |
8007 | |
8008 If you want a list to remain unmodified make a copy first: > | |
8009 :let sortedlist = sort(copy(mylist)) | |
8010 | |
8011 < When {func} is omitted, is empty or zero, then sort() uses the | |
8012 string representation of each item to sort on. Numbers sort | |
8013 after Strings, |Lists| after Numbers. For sorting text in the | |
8014 current buffer use |:sort|. | |
8015 | |
8016 When {func} is given and it is '1' or 'i' then case is | |
8017 ignored. | |
8018 | |
8019 When {func} is given and it is 'l' then the current collation | |
8020 locale is used for ordering. Implementation details: strcoll() | |
8021 is used to compare strings. See |:language| check or set the | |
8022 collation locale. |v:collate| can also be used to check the | |
8023 current locale. Sorting using the locale typically ignores | |
8024 case. Example: > | |
8025 " ö is sorted similarly to o with English locale. | |
8026 :language collate en_US.UTF8 | |
8027 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') | |
8028 < ['n', 'o', 'O', 'ö', 'p', 'z'] ~ | |
8029 > | |
8030 " ö is sorted after z with Swedish locale. | |
8031 :language collate sv_SE.UTF8 | |
8032 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') | |
8033 < ['n', 'o', 'O', 'p', 'z', 'ö'] ~ | |
8034 This does not work properly on Mac. | |
8035 | |
8036 When {func} is given and it is 'n' then all items will be | |
8037 sorted numerical (Implementation detail: this uses the | |
8038 strtod() function to parse numbers, Strings, Lists, Dicts and | |
8039 Funcrefs will be considered as being 0). | |
8040 | |
8041 When {func} is given and it is 'N' then all items will be | |
8042 sorted numerical. This is like 'n' but a string containing | |
8043 digits will be used as the number they represent. | |
8044 | |
8045 When {func} is given and it is 'f' then all items will be | |
8046 sorted numerical. All values must be a Number or a Float. | |
8047 | |
8048 When {func} is a |Funcref| or a function name, this function | |
8049 is called to compare items. The function is invoked with two | |
8050 items as argument and must return zero if they are equal, 1 or | |
8051 bigger if the first one sorts after the second one, -1 or | |
8052 smaller if the first one sorts before the second one. | |
8053 | |
8054 {dict} is for functions with the "dict" attribute. It will be | |
8055 used to set the local variable "self". |Dictionary-function| | |
8056 | |
8057 The sort is stable, items which compare equal (as number or as | |
8058 string) will keep their relative position. E.g., when sorting | |
8059 on numbers, text strings will sort next to each other, in the | |
8060 same order as they were originally. | |
8061 | |
8062 Can also be used as a |method|: > | |
8063 mylist->sort() | |
8064 | |
8065 < Also see |uniq()|. | |
8066 | |
8067 Example: > | |
8068 func MyCompare(i1, i2) | |
8069 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 | |
8070 endfunc | |
8071 eval mylist->sort("MyCompare") | |
8072 < A shorter compare version for this specific simple case, which | |
8073 ignores overflow: > | |
8074 func MyCompare(i1, i2) | |
8075 return a:i1 - a:i2 | |
8076 endfunc | |
8077 < For a simple expression you can use a lambda: > | |
8078 eval mylist->sort({i1, i2 -> i1 - i2}) | |
8079 < | |
8080 sound_clear() *sound_clear()* | |
8081 Stop playing all sounds. | |
8082 | |
8083 On some Linux systems you may need the libcanberra-pulse | |
8084 package, otherwise sound may not stop. | |
8085 | |
8086 {only available when compiled with the |+sound| feature} | |
8087 | |
8088 *sound_playevent()* | |
8089 sound_playevent({name} [, {callback}]) | |
8090 Play a sound identified by {name}. Which event names are | |
8091 supported depends on the system. Often the XDG sound names | |
8092 are used. On Ubuntu they may be found in | |
8093 /usr/share/sounds/freedesktop/stereo. Example: > | |
8094 call sound_playevent('bell') | |
8095 < On MS-Windows, {name} can be SystemAsterisk, SystemDefault, | |
8096 SystemExclamation, SystemExit, SystemHand, SystemQuestion, | |
8097 SystemStart, SystemWelcome, etc. | |
8098 | |
8099 When {callback} is specified it is invoked when the sound is | |
8100 finished. The first argument is the sound ID, the second | |
8101 argument is the status: | |
8102 0 sound was played to the end | |
8103 1 sound was interrupted | |
8104 2 error occurred after sound started | |
8105 Example: > | |
8106 func Callback(id, status) | |
8107 echomsg "sound " .. a:id .. " finished with " .. a:status | |
8108 endfunc | |
8109 call sound_playevent('bell', 'Callback') | |
8110 | |
8111 < MS-Windows: {callback} doesn't work for this function. | |
8112 | |
8113 Returns the sound ID, which can be passed to `sound_stop()`. | |
8114 Returns zero if the sound could not be played. | |
8115 | |
8116 Can also be used as a |method|: > | |
8117 GetSoundName()->sound_playevent() | |
8118 | |
8119 < {only available when compiled with the |+sound| feature} | |
8120 | |
8121 *sound_playfile()* | |
8122 sound_playfile({path} [, {callback}]) | |
8123 Like `sound_playevent()` but play sound file {path}. {path} | |
8124 must be a full path. On Ubuntu you may find files to play | |
8125 with this command: > | |
8126 :!find /usr/share/sounds -type f | grep -v index.theme | |
8127 | |
8128 < Can also be used as a |method|: > | |
8129 GetSoundPath()->sound_playfile() | |
8130 | |
8131 < {only available when compiled with the |+sound| feature} | |
8132 | |
8133 | |
8134 sound_stop({id}) *sound_stop()* | |
8135 Stop playing sound {id}. {id} must be previously returned by | |
8136 `sound_playevent()` or `sound_playfile()`. | |
8137 | |
8138 On some Linux systems you may need the libcanberra-pulse | |
8139 package, otherwise sound may not stop. | |
8140 | |
8141 On MS-Windows, this does not work for event sound started by | |
8142 `sound_playevent()`. To stop event sounds, use `sound_clear()`. | |
8143 | |
8144 Can also be used as a |method|: > | |
8145 soundid->sound_stop() | |
8146 | |
8147 < {only available when compiled with the |+sound| feature} | |
8148 | |
8149 *soundfold()* | |
8150 soundfold({word}) | |
8151 Return the sound-folded equivalent of {word}. Uses the first | |
8152 language in 'spelllang' for the current window that supports | |
8153 soundfolding. 'spell' must be set. When no sound folding is | |
8154 possible the {word} is returned unmodified. | |
8155 This can be used for making spelling suggestions. Note that | |
8156 the method can be quite slow. | |
8157 | |
8158 Can also be used as a |method|: > | |
8159 GetWord()->soundfold() | |
8160 < | |
8161 *spellbadword()* | |
8162 spellbadword([{sentence}]) | |
8163 Without argument: The result is the badly spelled word under | |
8164 or after the cursor. The cursor is moved to the start of the | |
8165 bad word. When no bad word is found in the cursor line the | |
8166 result is an empty string and the cursor doesn't move. | |
8167 | |
8168 With argument: The result is the first word in {sentence} that | |
8169 is badly spelled. If there are no spelling mistakes the | |
8170 result is an empty string. | |
8171 | |
8172 The return value is a list with two items: | |
8173 - The badly spelled word or an empty string. | |
8174 - The type of the spelling error: | |
8175 "bad" spelling mistake | |
8176 "rare" rare word | |
8177 "local" word only valid in another region | |
8178 "caps" word should start with Capital | |
8179 Example: > | |
8180 echo spellbadword("the quik brown fox") | |
8181 < ['quik', 'bad'] ~ | |
8182 | |
8183 The spelling information for the current window and the value | |
8184 of 'spelllang' are used. | |
8185 | |
8186 Can also be used as a |method|: > | |
8187 GetText()->spellbadword() | |
8188 < | |
8189 *spellsuggest()* | |
8190 spellsuggest({word} [, {max} [, {capital}]]) | |
8191 Return a |List| with spelling suggestions to replace {word}. | |
8192 When {max} is given up to this number of suggestions are | |
8193 returned. Otherwise up to 25 suggestions are returned. | |
8194 | |
8195 When the {capital} argument is given and it's non-zero only | |
8196 suggestions with a leading capital will be given. Use this | |
8197 after a match with 'spellcapcheck'. | |
8198 | |
8199 {word} can be a badly spelled word followed by other text. | |
8200 This allows for joining two words that were split. The | |
8201 suggestions also include the following text, thus you can | |
8202 replace a line. | |
8203 | |
8204 {word} may also be a good word. Similar words will then be | |
8205 returned. {word} itself is not included in the suggestions, | |
8206 although it may appear capitalized. | |
8207 | |
8208 The spelling information for the current window is used. The | |
8209 values of 'spelllang' and 'spellsuggest' are used. | |
8210 | |
8211 Can also be used as a |method|: > | |
8212 GetWord()->spellsuggest() | |
8213 | |
8214 split({string} [, {pattern} [, {keepempty}]]) *split()* | |
8215 Make a |List| out of {string}. When {pattern} is omitted or | |
8216 empty each white-separated sequence of characters becomes an | |
8217 item. | |
8218 Otherwise the string is split where {pattern} matches, | |
8219 removing the matched characters. 'ignorecase' is not used | |
8220 here, add \c to ignore case. |/\c| | |
8221 When the first or last item is empty it is omitted, unless the | |
8222 {keepempty} argument is given and it's non-zero. | |
8223 Other empty items are kept when {pattern} matches at least one | |
8224 character or when {keepempty} is non-zero. | |
8225 Example: > | |
8226 :let words = split(getline('.'), '\W\+') | |
8227 < To split a string in individual characters: > | |
8228 :for c in split(mystring, '\zs') | |
8229 < If you want to keep the separator you can also use '\zs' at | |
8230 the end of the pattern: > | |
8231 :echo split('abc:def:ghi', ':\zs') | |
8232 < ['abc:', 'def:', 'ghi'] ~ | |
8233 Splitting a table where the first element can be empty: > | |
8234 :let items = split(line, ':', 1) | |
8235 < The opposite function is |join()|. | |
8236 | |
8237 Can also be used as a |method|: > | |
8238 GetString()->split() | |
8239 | |
8240 sqrt({expr}) *sqrt()* | |
8241 Return the non-negative square root of Float {expr} as a | |
8242 |Float|. | |
8243 {expr} must evaluate to a |Float| or a |Number|. When {expr} | |
8244 is negative the result is NaN (Not a Number). | |
8245 Examples: > | |
8246 :echo sqrt(100) | |
8247 < 10.0 > | |
8248 :echo sqrt(-4.01) | |
8249 < nan | |
8250 "nan" may be different, it depends on system libraries. | |
8251 | |
8252 Can also be used as a |method|: > | |
8253 Compute()->sqrt() | |
8254 < | |
8255 {only available when compiled with the |+float| feature} | |
8256 | |
8257 | |
8258 srand([{expr}]) *srand()* | |
8259 Initialize seed used by |rand()|: | |
8260 - If {expr} is not given, seed values are initialized by | |
8261 reading from /dev/urandom, if possible, or using time(NULL) | |
8262 a.k.a. epoch time otherwise; this only has second accuracy. | |
8263 - If {expr} is given it must be a Number. It is used to | |
8264 initialize the seed values. This is useful for testing or | |
8265 when a predictable sequence is intended. | |
8266 | |
8267 Examples: > | |
8268 :let seed = srand() | |
8269 :let seed = srand(userinput) | |
8270 :echo rand(seed) | |
8271 | |
8272 state([{what}]) *state()* | |
8273 Return a string which contains characters indicating the | |
8274 current state. Mostly useful in callbacks that want to do | |
8275 work that may not always be safe. Roughly this works like: | |
8276 - callback uses state() to check if work is safe to do. | |
8277 Yes: then do it right away. | |
8278 No: add to work queue and add a |SafeState| and/or | |
8279 |SafeStateAgain| autocommand (|SafeState| triggers at | |
8280 toplevel, |SafeStateAgain| triggers after handling | |
8281 messages and callbacks). | |
8282 - When SafeState or SafeStateAgain is triggered and executes | |
8283 your autocommand, check with `state()` if the work can be | |
8284 done now, and if yes remove it from the queue and execute. | |
8285 Remove the autocommand if the queue is now empty. | |
8286 Also see |mode()|. | |
8287 | |
8288 When {what} is given only characters in this string will be | |
8289 added. E.g, this checks if the screen has scrolled: > | |
8290 if state('s') == '' | |
8291 " screen has not scrolled | |
8292 < | |
8293 These characters indicate the state, generally indicating that | |
8294 something is busy: | |
8295 m halfway a mapping, :normal command, feedkeys() or | |
8296 stuffed command | |
8297 o operator pending, e.g. after |d| | |
8298 a Insert mode autocomplete active | |
8299 x executing an autocommand | |
8300 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and | |
8301 ch_readraw() when reading json | |
8302 S not triggering SafeState or SafeStateAgain, e.g. after | |
8303 |f| or a count | |
8304 c callback invoked, including timer (repeats for | |
8305 recursiveness up to "ccc") | |
8306 s screen has scrolled for messages | |
8307 | |
8308 str2float({string} [, {quoted}]) *str2float()* | |
8309 Convert String {string} to a Float. This mostly works the | |
8310 same as when using a floating point number in an expression, | |
8311 see |floating-point-format|. But it's a bit more permissive. | |
8312 E.g., "1e40" is accepted, while in an expression you need to | |
8313 write "1.0e40". The hexadecimal form "0x123" is also | |
8314 accepted, but not others, like binary or octal. | |
8315 When {quoted} is present and non-zero then embedded single | |
8316 quotes before the dot are ignored, thus "1'000.0" is a | |
8317 thousand. | |
8318 Text after the number is silently ignored. | |
8319 The decimal point is always '.', no matter what the locale is | |
8320 set to. A comma ends the number: "12,345.67" is converted to | |
8321 12.0. You can strip out thousands separators with | |
8322 |substitute()|: > | |
8323 let f = str2float(substitute(text, ',', '', 'g')) | |
8324 < | |
8325 Can also be used as a |method|: > | |
8326 let f = text->substitute(',', '', 'g')->str2float() | |
8327 < | |
8328 {only available when compiled with the |+float| feature} | |
8329 | |
8330 str2list({string} [, {utf8}]) *str2list()* | |
8331 Return a list containing the number values which represent | |
8332 each character in String {string}. Examples: > | |
8333 str2list(" ") returns [32] | |
8334 str2list("ABC") returns [65, 66, 67] | |
8335 < |list2str()| does the opposite. | |
8336 | |
8337 When {utf8} is omitted or zero, the current 'encoding' is used. | |
8338 When {utf8} is TRUE, always treat the String as UTF-8 | |
8339 characters. With UTF-8 composing characters are handled | |
8340 properly: > | |
8341 str2list("á") returns [97, 769] | |
8342 | |
8343 < Can also be used as a |method|: > | |
8344 GetString()->str2list() | |
8345 | |
8346 | |
8347 str2nr({string} [, {base} [, {quoted}]]) *str2nr()* | |
8348 Convert string {string} to a number. | |
8349 {base} is the conversion base, it can be 2, 8, 10 or 16. | |
8350 When {quoted} is present and non-zero then embedded single | |
8351 quotes are ignored, thus "1'000'000" is a million. | |
8352 | |
8353 When {base} is omitted base 10 is used. This also means that | |
8354 a leading zero doesn't cause octal conversion to be used, as | |
8355 with the default String to Number conversion. Example: > | |
8356 let nr = str2nr('0123') | |
8357 < | |
8358 When {base} is 16 a leading "0x" or "0X" is ignored. With a | |
8359 different base the result will be zero. Similarly, when | |
8360 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when | |
8361 {base} is 2 a leading "0b" or "0B" is ignored. | |
8362 Text after the number is silently ignored. | |
8363 | |
8364 Can also be used as a |method|: > | |
8365 GetText()->str2nr() | |
8366 | |
8367 | |
8368 strcharlen({string}) *strcharlen()* | |
8369 The result is a Number, which is the number of characters | |
8370 in String {string}. Composing characters are ignored. | |
8371 |strchars()| can count the number of characters, counting | |
8372 composing characters separately. | |
8373 | |
8374 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. | |
8375 | |
8376 Can also be used as a |method|: > | |
8377 GetText()->strcharlen() | |
8378 | |
8379 | |
8380 strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* | |
8381 Like |strpart()| but using character index and length instead | |
8382 of byte index and length. | |
8383 When {skipcc} is omitted or zero, composing characters are | |
8384 counted separately. | |
8385 When {skipcc} set to 1, Composing characters are ignored, | |
8386 similar to |slice()|. | |
8387 When a character index is used where a character does not | |
8388 exist it is omitted and counted as one character. For | |
8389 example: > | |
8390 strcharpart('abc', -1, 2) | |
8391 < results in 'a'. | |
8392 | |
8393 Can also be used as a |method|: > | |
8394 GetText()->strcharpart(5) | |
8395 | |
8396 | |
8397 strchars({string} [, {skipcc}]) *strchars()* | |
8398 The result is a Number, which is the number of characters | |
8399 in String {string}. | |
8400 When {skipcc} is omitted or zero, composing characters are | |
8401 counted separately. | |
8402 When {skipcc} set to 1, Composing characters are ignored. | |
8403 |strcharlen()| always does this. | |
8404 | |
8405 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. | |
8406 | |
8407 {skipcc} is only available after 7.4.755. For backward | |
8408 compatibility, you can define a wrapper function: > | |
8409 if has("patch-7.4.755") | |
8410 function s:strchars(str, skipcc) | |
8411 return strchars(a:str, a:skipcc) | |
8412 endfunction | |
8413 else | |
8414 function s:strchars(str, skipcc) | |
8415 if a:skipcc | |
8416 return strlen(substitute(a:str, ".", "x", "g")) | |
8417 else | |
8418 return strchars(a:str) | |
8419 endif | |
8420 endfunction | |
8421 endif | |
8422 < | |
8423 Can also be used as a |method|: > | |
8424 GetText()->strchars() | |
8425 | |
8426 strdisplaywidth({string} [, {col}]) *strdisplaywidth()* | |
8427 The result is a Number, which is the number of display cells | |
8428 String {string} occupies on the screen when it starts at {col} | |
8429 (first column is zero). When {col} is omitted zero is used. | |
8430 Otherwise it is the screen column where to start. This | |
8431 matters for Tab characters. | |
8432 The option settings of the current window are used. This | |
8433 matters for anything that's displayed differently, such as | |
8434 'tabstop' and 'display'. | |
8435 When {string} contains characters with East Asian Width Class | |
8436 Ambiguous, this function's return value depends on 'ambiwidth'. | |
8437 Also see |strlen()|, |strwidth()| and |strchars()|. | |
8438 | |
8439 Can also be used as a |method|: > | |
8440 GetText()->strdisplaywidth() | |
8441 | |
8442 strftime({format} [, {time}]) *strftime()* | |
8443 The result is a String, which is a formatted date and time, as | |
8444 specified by the {format} string. The given {time} is used, | |
8445 or the current time if no time is given. The accepted | |
8446 {format} depends on your system, thus this is not portable! | |
8447 See the manual page of the C function strftime() for the | |
8448 format. The maximum length of the result is 80 characters. | |
8449 See also |localtime()|, |getftime()| and |strptime()|. | |
8450 The language can be changed with the |:language| command. | |
8451 Examples: > | |
8452 :echo strftime("%c") Sun Apr 27 11:49:23 1997 | |
8453 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25 | |
8454 :echo strftime("%y%m%d %T") 970427 11:53:55 | |
8455 :echo strftime("%H:%M") 11:55 | |
8456 :echo strftime("%c", getftime("file.c")) | |
8457 Show mod time of file.c. | |
8458 < Not available on all systems. To check use: > | |
8459 :if exists("*strftime") | |
8460 | |
8461 < Can also be used as a |method|: > | |
8462 GetFormat()->strftime() | |
8463 | |
8464 strgetchar({str}, {index}) *strgetchar()* | |
8465 Get character {index} from {str}. This uses a character | |
8466 index, not a byte index. Composing characters are considered | |
8467 separate characters here. | |
8468 Also see |strcharpart()| and |strchars()|. | |
8469 | |
8470 Can also be used as a |method|: > | |
8471 GetText()->strgetchar(5) | |
8472 | |
8473 stridx({haystack}, {needle} [, {start}]) *stridx()* | |
8474 The result is a Number, which gives the byte index in | |
8475 {haystack} of the first occurrence of the String {needle}. | |
8476 If {start} is specified, the search starts at index {start}. | |
8477 This can be used to find a second match: > | |
8478 :let colon1 = stridx(line, ":") | |
8479 :let colon2 = stridx(line, ":", colon1 + 1) | |
8480 < The search is done case-sensitive. | |
8481 For pattern searches use |match()|. | |
8482 -1 is returned if the {needle} does not occur in {haystack}. | |
8483 See also |strridx()|. | |
8484 Examples: > | |
8485 :echo stridx("An Example", "Example") 3 | |
8486 :echo stridx("Starting point", "Start") 0 | |
8487 :echo stridx("Starting point", "start") -1 | |
8488 < *strstr()* *strchr()* | |
8489 stridx() works similar to the C function strstr(). When used | |
8490 with a single character it works similar to strchr(). | |
8491 | |
8492 Can also be used as a |method|: > | |
8493 GetHaystack()->stridx(needle) | |
8494 < | |
8495 *string()* | |
8496 string({expr}) Return {expr} converted to a String. If {expr} is a Number, | |
8497 Float, String, Blob or a composition of them, then the result | |
8498 can be parsed back with |eval()|. | |
8499 {expr} type result ~ | |
8500 String 'string' (single quotes are doubled) | |
8501 Number 123 | |
8502 Float 123.123456 or 1.123456e8 | |
8503 Funcref function('name') | |
8504 Blob 0z00112233.44556677.8899 | |
8505 List [item, item] | |
8506 Dictionary {key: value, key: value} | |
8507 | |
8508 When a |List| or |Dictionary| has a recursive reference it is | |
8509 replaced by "[...]" or "{...}". Using eval() on the result | |
8510 will then fail. | |
8511 | |
8512 Can also be used as a |method|: > | |
8513 mylist->string() | |
8514 | |
8515 < Also see |strtrans()|. | |
8516 | |
8517 | |
8518 strlen({string}) *strlen()* | |
8519 The result is a Number, which is the length of the String | |
8520 {string} in bytes. | |
8521 If the argument is a Number it is first converted to a String. | |
8522 For other types an error is given. | |
8523 If you want to count the number of multibyte characters use | |
8524 |strchars()|. | |
8525 Also see |len()|, |strdisplaywidth()| and |strwidth()|. | |
8526 | |
8527 Can also be used as a |method|: > | |
8528 GetString()->strlen() | |
8529 | |
8530 strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* | |
8531 The result is a String, which is part of {src}, starting from | |
8532 byte {start}, with the byte length {len}. | |
8533 When {chars} is present and TRUE then {len} is the number of | |
8534 characters positions (composing characters are not counted | |
8535 separately, thus "1" means one base character and any | |
8536 following composing characters). | |
8537 To count {start} as characters instead of bytes use | |
8538 |strcharpart()|. | |
8539 | |
8540 When bytes are selected which do not exist, this doesn't | |
8541 result in an error, the bytes are simply omitted. | |
8542 If {len} is missing, the copy continues from {start} till the | |
8543 end of the {src}. > | |
8544 strpart("abcdefg", 3, 2) == "de" | |
8545 strpart("abcdefg", -2, 4) == "ab" | |
8546 strpart("abcdefg", 5, 4) == "fg" | |
8547 strpart("abcdefg", 3) == "defg" | |
8548 | |
8549 < Note: To get the first character, {start} must be 0. For | |
8550 example, to get the character under the cursor: > | |
8551 strpart(getline("."), col(".") - 1, 1, v:true) | |
8552 < | |
8553 Can also be used as a |method|: > | |
8554 GetText()->strpart(5) | |
8555 | |
8556 strptime({format}, {timestring}) *strptime()* | |
8557 The result is a Number, which is a unix timestamp representing | |
8558 the date and time in {timestring}, which is expected to match | |
8559 the format specified in {format}. | |
8560 | |
8561 The accepted {format} depends on your system, thus this is not | |
8562 portable! See the manual page of the C function strptime() | |
8563 for the format. Especially avoid "%c". The value of $TZ also | |
8564 matters. | |
8565 | |
8566 If the {timestring} cannot be parsed with {format} zero is | |
8567 returned. If you do not know the format of {timestring} you | |
8568 can try different {format} values until you get a non-zero | |
8569 result. | |
8570 | |
8571 See also |strftime()|. | |
8572 Examples: > | |
8573 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") | |
8574 < 862156163 > | |
8575 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) | |
8576 < Sun Apr 27 11:53:55 1997 > | |
8577 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) | |
8578 < Sun Apr 27 12:53:55 1997 | |
8579 | |
8580 Can also be used as a |method|: > | |
8581 GetFormat()->strptime(timestring) | |
8582 < | |
8583 Not available on all systems. To check use: > | |
8584 :if exists("*strptime") | |
8585 | |
8586 strridx({haystack}, {needle} [, {start}]) *strridx()* | |
8587 The result is a Number, which gives the byte index in | |
8588 {haystack} of the last occurrence of the String {needle}. | |
8589 When {start} is specified, matches beyond this index are | |
8590 ignored. This can be used to find a match before a previous | |
8591 match: > | |
8592 :let lastcomma = strridx(line, ",") | |
8593 :let comma2 = strridx(line, ",", lastcomma - 1) | |
8594 < The search is done case-sensitive. | |
8595 For pattern searches use |match()|. | |
8596 -1 is returned if the {needle} does not occur in {haystack}. | |
8597 If the {needle} is empty the length of {haystack} is returned. | |
8598 See also |stridx()|. Examples: > | |
8599 :echo strridx("an angry armadillo", "an") 3 | |
8600 < *strrchr()* | |
8601 When used with a single character it works similar to the C | |
8602 function strrchr(). | |
8603 | |
8604 Can also be used as a |method|: > | |
8605 GetHaystack()->strridx(needle) | |
8606 | |
8607 strtrans({string}) *strtrans()* | |
8608 The result is a String, which is {string} with all unprintable | |
8609 characters translated into printable characters |'isprint'|. | |
8610 Like they are shown in a window. Example: > | |
8611 echo strtrans(@a) | |
8612 < This displays a newline in register a as "^@" instead of | |
8613 starting a new line. | |
8614 | |
8615 Can also be used as a |method|: > | |
8616 GetString()->strtrans() | |
8617 | |
8618 strwidth({string}) *strwidth()* | |
8619 The result is a Number, which is the number of display cells | |
8620 String {string} occupies. A Tab character is counted as one | |
8621 cell, alternatively use |strdisplaywidth()|. | |
8622 When {string} contains characters with East Asian Width Class | |
8623 Ambiguous, this function's return value depends on 'ambiwidth'. | |
8624 Also see |strlen()|, |strdisplaywidth()| and |strchars()|. | |
8625 | |
8626 Can also be used as a |method|: > | |
8627 GetString()->strwidth() | |
8628 | |
8629 submatch({nr} [, {list}]) *submatch()* *E935* | |
8630 Only for an expression in a |:substitute| command or | |
8631 substitute() function. | |
8632 Returns the {nr}'th submatch of the matched text. When {nr} | |
8633 is 0 the whole matched text is returned. | |
8634 Note that a NL in the string can stand for a line break of a | |
8635 multi-line match or a NUL character in the text. | |
8636 Also see |sub-replace-expression|. | |
8637 | |
8638 If {list} is present and non-zero then submatch() returns | |
8639 a list of strings, similar to |getline()| with two arguments. | |
8640 NL characters in the text represent NUL characters in the | |
8641 text. | |
8642 Only returns more than one item for |:substitute|, inside | |
8643 |substitute()| this list will always contain one or zero | |
8644 items, since there are no real line breaks. | |
8645 | |
8646 When substitute() is used recursively only the submatches in | |
8647 the current (deepest) call can be obtained. | |
8648 | |
8649 Examples: > | |
8650 :s/\d\+/\=submatch(0) + 1/ | |
8651 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '') | |
8652 < This finds the first number in the line and adds one to it. | |
8653 A line break is included as a newline character. | |
8654 | |
8655 Can also be used as a |method|: > | |
8656 GetNr()->submatch() | |
8657 | |
8658 substitute({string}, {pat}, {sub}, {flags}) *substitute()* | |
8659 The result is a String, which is a copy of {string}, in which | |
8660 the first match of {pat} is replaced with {sub}. | |
8661 When {flags} is "g", all matches of {pat} in {string} are | |
8662 replaced. Otherwise {flags} should be "". | |
8663 | |
8664 This works like the ":substitute" command (without any flags). | |
8665 But the matching with {pat} is always done like the 'magic' | |
8666 option is set and 'cpoptions' is empty (to make scripts | |
8667 portable). 'ignorecase' is still relevant, use |/\c| or |/\C| | |
8668 if you want to ignore or match case and ignore 'ignorecase'. | |
8669 'smartcase' is not used. See |string-match| for how {pat} is | |
8670 used. | |
8671 | |
8672 A "~" in {sub} is not replaced with the previous {sub}. | |
8673 Note that some codes in {sub} have a special meaning | |
8674 |sub-replace-special|. For example, to replace something with | |
8675 "\n" (two characters), use "\\\\n" or '\\n'. | |
8676 | |
8677 When {pat} does not match in {string}, {string} is returned | |
8678 unmodified. | |
8679 | |
8680 Example: > | |
8681 :let &path = substitute(&path, ",\\=[^,]*$", "", "") | |
8682 < This removes the last component of the 'path' option. > | |
8683 :echo substitute("testing", ".*", "\\U\\0", "") | |
8684 < results in "TESTING". | |
8685 | |
8686 When {sub} starts with "\=", the remainder is interpreted as | |
8687 an expression. See |sub-replace-expression|. Example: > | |
8688 :echo substitute(s, '%\(\x\x\)', | |
8689 \ '\=nr2char("0x" . submatch(1))', 'g') | |
8690 | |
8691 < When {sub} is a Funcref that function is called, with one | |
8692 optional argument. Example: > | |
8693 :echo substitute(s, '%\(\x\x\)', SubNr, 'g') | |
8694 < The optional argument is a list which contains the whole | |
8695 matched string and up to nine submatches, like what | |
8696 |submatch()| returns. Example: > | |
8697 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g') | |
8698 | |
8699 < Can also be used as a |method|: > | |
8700 GetString()->substitute(pat, sub, flags) | |
8701 | |
8702 swapinfo({fname}) *swapinfo()* | |
8703 The result is a dictionary, which holds information about the | |
8704 swapfile {fname}. The available fields are: | |
8705 version Vim version | |
8706 user user name | |
8707 host host name | |
8708 fname original file name | |
8709 pid PID of the Vim process that created the swap | |
8710 file | |
8711 mtime last modification time in seconds | |
8712 inode Optional: INODE number of the file | |
8713 dirty 1 if file was modified, 0 if not | |
8714 Note that "user" and "host" are truncated to at most 39 bytes. | |
8715 In case of failure an "error" item is added with the reason: | |
8716 Cannot open file: file not found or in accessible | |
8717 Cannot read file: cannot read first block | |
8718 Not a swap file: does not contain correct block ID | |
8719 Magic number mismatch: Info in first block is invalid | |
8720 | |
8721 Can also be used as a |method|: > | |
8722 GetFilename()->swapinfo() | |
8723 | |
8724 swapname({buf}) *swapname()* | |
8725 The result is the swap file path of the buffer {expr}. | |
8726 For the use of {buf}, see |bufname()| above. | |
8727 If buffer {buf} is the current buffer, the result is equal to | |
8728 |:swapname| (unless there is no swap file). | |
8729 If buffer {buf} has no swap file, returns an empty string. | |
8730 | |
8731 Can also be used as a |method|: > | |
8732 GetBufname()->swapname() | |
8733 | |
8734 synID({lnum}, {col}, {trans}) *synID()* | |
8735 The result is a Number, which is the syntax ID at the position | |
8736 {lnum} and {col} in the current window. | |
8737 The syntax ID can be used with |synIDattr()| and | |
8738 |synIDtrans()| to obtain syntax information about text. | |
8739 | |
8740 {col} is 1 for the leftmost column, {lnum} is 1 for the first | |
8741 line. 'synmaxcol' applies, in a longer line zero is returned. | |
8742 Note that when the position is after the last character, | |
8743 that's where the cursor can be in Insert mode, synID() returns | |
8744 zero. {lnum} is used like with |getline()|. | |
8745 | |
8746 When {trans} is |TRUE|, transparent items are reduced to the | |
8747 item that they reveal. This is useful when wanting to know | |
8748 the effective color. When {trans} is |FALSE|, the transparent | |
8749 item is returned. This is useful when wanting to know which | |
8750 syntax item is effective (e.g. inside parens). | |
8751 Warning: This function can be very slow. Best speed is | |
8752 obtained by going through the file in forward direction. | |
8753 | |
8754 Example (echoes the name of the syntax item under the cursor): > | |
8755 :echo synIDattr(synID(line("."), col("."), 1), "name") | |
8756 < | |
8757 | |
8758 synIDattr({synID}, {what} [, {mode}]) *synIDattr()* | |
8759 The result is a String, which is the {what} attribute of | |
8760 syntax ID {synID}. This can be used to obtain information | |
8761 about a syntax item. | |
8762 {mode} can be "gui", "cterm" or "term", to get the attributes | |
8763 for that mode. When {mode} is omitted, or an invalid value is | |
8764 used, the attributes for the currently active highlighting are | |
8765 used (GUI, cterm or term). | |
8766 Use synIDtrans() to follow linked highlight groups. | |
8767 {what} result | |
8768 "name" the name of the syntax item | |
8769 "fg" foreground color (GUI: color name used to set | |
8770 the color, cterm: color number as a string, | |
8771 term: empty string) | |
8772 "bg" background color (as with "fg") | |
8773 "font" font name (only available in the GUI) | |
8774 |highlight-font| | |
8775 "sp" special color for the GUI (as with "fg") | |
8776 |highlight-guisp| | |
8777 "ul" underline color for cterm: number as a string | |
8778 "fg#" like "fg", but for the GUI and the GUI is | |
8779 running the name in "#RRGGBB" form | |
8780 "bg#" like "fg#" for "bg" | |
8781 "sp#" like "fg#" for "sp" | |
8782 "bold" "1" if bold | |
8783 "italic" "1" if italic | |
8784 "reverse" "1" if reverse | |
8785 "inverse" "1" if inverse (= reverse) | |
8786 "standout" "1" if standout | |
8787 "underline" "1" if underlined | |
8788 "undercurl" "1" if undercurled | |
8789 "strike" "1" if strikethrough | |
8790 | |
8791 Example (echoes the color of the syntax item under the | |
8792 cursor): > | |
8793 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") | |
8794 < | |
8795 Can also be used as a |method|: > | |
8796 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") | |
8797 | |
8798 | |
8799 synIDtrans({synID}) *synIDtrans()* | |
8800 The result is a Number, which is the translated syntax ID of | |
8801 {synID}. This is the syntax group ID of what is being used to | |
8802 highlight the character. Highlight links given with | |
8803 ":highlight link" are followed. | |
8804 | |
8805 Can also be used as a |method|: > | |
8806 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") | |
8807 | |
8808 synconcealed({lnum}, {col}) *synconcealed()* | |
8809 The result is a |List| with currently three items: | |
8810 1. The first item in the list is 0 if the character at the | |
8811 position {lnum} and {col} is not part of a concealable | |
8812 region, 1 if it is. {lnum} is used like with |getline()|. | |
8813 2. The second item in the list is a string. If the first item | |
8814 is 1, the second item contains the text which will be | |
8815 displayed in place of the concealed text, depending on the | |
8816 current setting of 'conceallevel' and 'listchars'. | |
8817 3. The third and final item in the list is a number | |
8818 representing the specific syntax region matched in the | |
8819 line. When the character is not concealed the value is | |
8820 zero. This allows detection of the beginning of a new | |
8821 concealable region if there are two consecutive regions | |
8822 with the same replacement character. For an example, if | |
8823 the text is "123456" and both "23" and "45" are concealed | |
8824 and replaced by the character "X", then: | |
8825 call returns ~ | |
8826 synconcealed(lnum, 1) [0, '', 0] | |
8827 synconcealed(lnum, 2) [1, 'X', 1] | |
8828 synconcealed(lnum, 3) [1, 'X', 1] | |
8829 synconcealed(lnum, 4) [1, 'X', 2] | |
8830 synconcealed(lnum, 5) [1, 'X', 2] | |
8831 synconcealed(lnum, 6) [0, '', 0] | |
8832 | |
8833 | |
8834 synstack({lnum}, {col}) *synstack()* | |
8835 Return a |List|, which is the stack of syntax items at the | |
8836 position {lnum} and {col} in the current window. {lnum} is | |
8837 used like with |getline()|. Each item in the List is an ID | |
8838 like what |synID()| returns. | |
8839 The first item in the List is the outer region, following are | |
8840 items contained in that one. The last one is what |synID()| | |
8841 returns, unless not the whole item is highlighted or it is a | |
8842 transparent item. | |
8843 This function is useful for debugging a syntax file. | |
8844 Example that shows the syntax stack under the cursor: > | |
8845 for id in synstack(line("."), col(".")) | |
8846 echo synIDattr(id, "name") | |
8847 endfor | |
8848 < When the position specified with {lnum} and {col} is invalid | |
8849 nothing is returned. The position just after the last | |
8850 character in a line and the first column in an empty line are | |
8851 valid positions. | |
8852 | |
8853 system({expr} [, {input}]) *system()* *E677* | |
8854 Get the output of the shell command {expr} as a |String|. See | |
8855 |systemlist()| to get the output as a |List|. | |
8856 | |
8857 When {input} is given and is a |String| this string is written | |
8858 to a file and passed as stdin to the command. The string is | |
8859 written as-is, you need to take care of using the correct line | |
8860 separators yourself. | |
8861 If {input} is given and is a |List| it is written to the file | |
8862 in a way |writefile()| does with {binary} set to "b" (i.e. | |
8863 with a newline between each list item with newlines inside | |
8864 list items converted to NULs). | |
8865 When {input} is given and is a number that is a valid id for | |
8866 an existing buffer then the content of the buffer is written | |
8867 to the file line by line, each line terminated by a NL and | |
8868 NULs characters where the text has a NL. | |
8869 | |
8870 Pipes are not used, the 'shelltemp' option is not used. | |
8871 | |
8872 When prepended by |:silent| the terminal will not be set to | |
8873 cooked mode. This is meant to be used for commands that do | |
8874 not need the user to type. It avoids stray characters showing | |
8875 up on the screen which require |CTRL-L| to remove. > | |
8876 :silent let f = system('ls *.vim') | |
8877 < | |
8878 Note: Use |shellescape()| or |::S| with |expand()| or | |
8879 |fnamemodify()| to escape special characters in a command | |
8880 argument. Newlines in {expr} may cause the command to fail. | |
8881 The characters in 'shellquote' and 'shellxquote' may also | |
8882 cause trouble. | |
8883 This is not to be used for interactive commands. | |
8884 | |
8885 The result is a String. Example: > | |
8886 :let files = system("ls " . shellescape(expand('%:h'))) | |
8887 :let files = system('ls ' . expand('%:h:S')) | |
8888 | |
8889 < To make the result more system-independent, the shell output | |
8890 is filtered to replace <CR> with <NL> for Macintosh, and | |
8891 <CR><NL> with <NL> for DOS-like systems. | |
8892 To avoid the string being truncated at a NUL, all NUL | |
8893 characters are replaced with SOH (0x01). | |
8894 | |
8895 The command executed is constructed using several options: | |
8896 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote' | |
8897 ({tmp} is an automatically generated file name). | |
8898 For Unix, braces are put around {expr} to allow for | |
8899 concatenated commands. | |
8900 | |
8901 The command will be executed in "cooked" mode, so that a | |
8902 CTRL-C will interrupt the command (on Unix at least). | |
8903 | |
8904 The resulting error code can be found in |v:shell_error|. | |
8905 This function will fail in |restricted-mode|. | |
8906 | |
8907 Note that any wrong value in the options mentioned above may | |
8908 make the function fail. It has also been reported to fail | |
8909 when using a security agent application. | |
8910 Unlike ":!cmd" there is no automatic check for changed files. | |
8911 Use |:checktime| to force a check. | |
8912 | |
8913 Can also be used as a |method|: > | |
8914 :echo GetCmd()->system() | |
8915 | |
8916 | |
8917 systemlist({expr} [, {input}]) *systemlist()* | |
8918 Same as |system()|, but returns a |List| with lines (parts of | |
8919 output separated by NL) with NULs transformed into NLs. Output | |
8920 is the same as |readfile()| will output with {binary} argument | |
8921 set to "b", except that there is no extra empty item when the | |
8922 result ends in a NL. | |
8923 Note that on MS-Windows you may get trailing CR characters. | |
8924 | |
8925 To see the difference between "echo hello" and "echo -n hello" | |
8926 use |system()| and |split()|: > | |
8927 echo system('echo hello')->split('\n', 1) | |
8928 < | |
8929 Returns an empty string on error. | |
8930 | |
8931 Can also be used as a |method|: > | |
8932 :echo GetCmd()->systemlist() | |
8933 | |
8934 | |
8935 tabpagebuflist([{arg}]) *tabpagebuflist()* | |
8936 The result is a |List|, where each item is the number of the | |
8937 buffer associated with each window in the current tab page. | |
8938 {arg} specifies the number of the tab page to be used. When | |
8939 omitted the current tab page is used. | |
8940 When {arg} is invalid the number zero is returned. | |
8941 To get a list of all buffers in all tabs use this: > | |
8942 let buflist = [] | |
8943 for i in range(tabpagenr('$')) | |
8944 call extend(buflist, tabpagebuflist(i + 1)) | |
8945 endfor | |
8946 < Note that a buffer may appear in more than one window. | |
8947 | |
8948 Can also be used as a |method|: > | |
8949 GetTabpage()->tabpagebuflist() | |
8950 | |
8951 tabpagenr([{arg}]) *tabpagenr()* | |
8952 The result is a Number, which is the number of the current | |
8953 tab page. The first tab page has number 1. | |
8954 | |
8955 The optional argument {arg} supports the following values: | |
8956 $ the number of the last tab page (the tab page | |
8957 count). | |
8958 # the number of the last accessed tab page | |
8959 (where |g<Tab>| goes to). if there is no | |
8960 previous tab page 0 is returned. | |
8961 The number can be used with the |:tab| command. | |
8962 | |
8963 | |
8964 tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* | |
8965 Like |winnr()| but for tab page {tabarg}. | |
8966 {tabarg} specifies the number of tab page to be used. | |
8967 {arg} is used like with |winnr()|: | |
8968 - When omitted the current window number is returned. This is | |
8969 the window which will be used when going to this tab page. | |
8970 - When "$" the number of windows is returned. | |
8971 - When "#" the previous window nr is returned. | |
8972 Useful examples: > | |
8973 tabpagewinnr(1) " current window of tab page 1 | |
8974 tabpagewinnr(4, '$') " number of windows in tab page 4 | |
8975 < When {tabarg} is invalid zero is returned. | |
8976 | |
8977 Can also be used as a |method|: > | |
8978 GetTabpage()->tabpagewinnr() | |
8979 < | |
8980 *tagfiles()* | |
8981 tagfiles() Returns a |List| with the file names used to search for tags | |
8982 for the current buffer. This is the 'tags' option expanded. | |
8983 | |
8984 | |
8985 taglist({expr} [, {filename}]) *taglist()* | |
8986 Returns a |List| of tags matching the regular expression {expr}. | |
8987 | |
8988 If {filename} is passed it is used to prioritize the results | |
8989 in the same way that |:tselect| does. See |tag-priority|. | |
8990 {filename} should be the full path of the file. | |
8991 | |
8992 Each list item is a dictionary with at least the following | |
8993 entries: | |
8994 name Name of the tag. | |
8995 filename Name of the file where the tag is | |
8996 defined. It is either relative to the | |
8997 current directory or a full path. | |
8998 cmd Ex command used to locate the tag in | |
8999 the file. | |
9000 kind Type of the tag. The value for this | |
9001 entry depends on the language specific | |
9002 kind values. Only available when | |
9003 using a tags file generated by | |
9004 Exuberant ctags or hdrtag. | |
9005 static A file specific tag. Refer to | |
9006 |static-tag| for more information. | |
9007 More entries may be present, depending on the content of the | |
9008 tags file: access, implementation, inherits and signature. | |
9009 Refer to the ctags documentation for information about these | |
9010 fields. For C code the fields "struct", "class" and "enum" | |
9011 may appear, they give the name of the entity the tag is | |
9012 contained in. | |
9013 | |
9014 The ex-command "cmd" can be either an ex search pattern, a | |
9015 line number or a line number followed by a byte number. | |
9016 | |
9017 If there are no matching tags, then an empty list is returned. | |
9018 | |
9019 To get an exact tag match, the anchors '^' and '$' should be | |
9020 used in {expr}. This also make the function work faster. | |
9021 Refer to |tag-regexp| for more information about the tag | |
9022 search regular expression pattern. | |
9023 | |
9024 Refer to |'tags'| for information about how the tags file is | |
9025 located by Vim. Refer to |tags-file-format| for the format of | |
9026 the tags file generated by the different ctags tools. | |
9027 | |
9028 Can also be used as a |method|: > | |
9029 GetTagpattern()->taglist() | |
9030 | |
9031 tan({expr}) *tan()* | |
9032 Return the tangent of {expr}, measured in radians, as a |Float| | |
9033 in the range [-inf, inf]. | |
9034 {expr} must evaluate to a |Float| or a |Number|. | |
9035 Examples: > | |
9036 :echo tan(10) | |
9037 < 0.648361 > | |
9038 :echo tan(-4.01) | |
9039 < -1.181502 | |
9040 | |
9041 Can also be used as a |method|: > | |
9042 Compute()->tan() | |
9043 < | |
9044 {only available when compiled with the |+float| feature} | |
9045 | |
9046 | |
9047 tanh({expr}) *tanh()* | |
9048 Return the hyperbolic tangent of {expr} as a |Float| in the | |
9049 range [-1, 1]. | |
9050 {expr} must evaluate to a |Float| or a |Number|. | |
9051 Examples: > | |
9052 :echo tanh(0.5) | |
9053 < 0.462117 > | |
9054 :echo tanh(-1) | |
9055 < -0.761594 | |
9056 | |
9057 Can also be used as a |method|: > | |
9058 Compute()->tanh() | |
9059 < | |
9060 {only available when compiled with the |+float| feature} | |
9061 | |
9062 | |
9063 tempname() *tempname()* *temp-file-name* | |
9064 The result is a String, which is the name of a file that | |
9065 doesn't exist. It can be used for a temporary file. The name | |
9066 is different for at least 26 consecutive calls. Example: > | |
9067 :let tmpfile = tempname() | |
9068 :exe "redir > " . tmpfile | |
9069 < For Unix, the file will be in a private directory |tempfile|. | |
9070 For MS-Windows forward slashes are used when the 'shellslash' | |
9071 option is set, or when 'shellcmdflag' starts with '-' and | |
9072 'shell' does not contain powershell or pwsh. | |
9073 | |
9074 | |
9075 term_ functions are documented here: |terminal-function-details| | |
9076 | |
9077 | |
9078 terminalprops() *terminalprops()* | |
9079 Returns a |Dictionary| with properties of the terminal that Vim | |
9080 detected from the response to |t_RV| request. See | |
9081 |v:termresponse| for the response itself. If |v:termresponse| | |
9082 is empty most values here will be 'u' for unknown. | |
9083 cursor_style whether sending |t_RS| works ** | |
9084 cursor_blink_mode whether sending |t_RC| works ** | |
9085 underline_rgb whether |t_8u| works ** | |
9086 mouse mouse type supported | |
9087 | |
9088 ** value 'u' for unknown, 'y' for yes, 'n' for no | |
9089 | |
9090 If the |+termresponse| feature is missing then the result is | |
9091 an empty dictionary. | |
9092 | |
9093 If "cursor_style" is 'y' then |t_RS| will be sent to request the | |
9094 current cursor style. | |
9095 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to | |
9096 request the cursor blink status. | |
9097 "cursor_style" and "cursor_blink_mode" are also set if |t_u7| | |
9098 is not empty, Vim will detect the working of sending |t_RS| | |
9099 and |t_RC| on startup. | |
9100 | |
9101 When "underline_rgb" is not 'y', then |t_8u| will be made empty. | |
9102 This avoids sending it to xterm, which would clear the colors. | |
9103 | |
9104 For "mouse" the value 'u' is unknown | |
9105 | |
9106 Also see: | |
9107 - 'ambiwidth' - detected by using |t_u7|. | |
9108 - |v:termstyleresp| and |v:termblinkresp| for the response to | |
9109 |t_RS| and |t_RC|. | |
9110 | |
9111 | |
9112 test_ functions are documented here: |test-functions-details| | |
9113 | |
9114 | |
9115 *timer_info()* | |
9116 timer_info([{id}]) | |
9117 Return a list with information about timers. | |
9118 When {id} is given only information about this timer is | |
9119 returned. When timer {id} does not exist an empty list is | |
9120 returned. | |
9121 When {id} is omitted information about all timers is returned. | |
9122 | |
9123 For each timer the information is stored in a |Dictionary| with | |
9124 these items: | |
9125 "id" the timer ID | |
9126 "time" time the timer was started with | |
9127 "remaining" time until the timer fires | |
9128 "repeat" number of times the timer will still fire; | |
9129 -1 means forever | |
9130 "callback" the callback | |
9131 "paused" 1 if the timer is paused, 0 otherwise | |
9132 | |
9133 Can also be used as a |method|: > | |
9134 GetTimer()->timer_info() | |
9135 | |
9136 < {only available when compiled with the |+timers| feature} | |
9137 | |
9138 timer_pause({timer}, {paused}) *timer_pause()* | |
9139 Pause or unpause a timer. A paused timer does not invoke its | |
9140 callback when its time expires. Unpausing a timer may cause | |
9141 the callback to be invoked almost immediately if enough time | |
9142 has passed. | |
9143 | |
9144 Pausing a timer is useful to avoid the callback to be called | |
9145 for a short time. | |
9146 | |
9147 If {paused} evaluates to a non-zero Number or a non-empty | |
9148 String, then the timer is paused, otherwise it is unpaused. | |
9149 See |non-zero-arg|. | |
9150 | |
9151 Can also be used as a |method|: > | |
9152 GetTimer()->timer_pause(1) | |
9153 | |
9154 < {only available when compiled with the |+timers| feature} | |
9155 | |
9156 *timer_start()* *timer* *timers* | |
9157 timer_start({time}, {callback} [, {options}]) | |
9158 Create a timer and return the timer ID. | |
9159 | |
9160 {time} is the waiting time in milliseconds. This is the | |
9161 minimum time before invoking the callback. When the system is | |
9162 busy or Vim is not waiting for input the time will be longer. | |
9163 | |
9164 {callback} is the function to call. It can be the name of a | |
9165 function or a |Funcref|. It is called with one argument, which | |
9166 is the timer ID. The callback is only invoked when Vim is | |
9167 waiting for input. | |
9168 If you want to show a message look at |popup_notification()| | |
9169 to avoid interfering with what the user is doing. | |
9170 | |
9171 {options} is a dictionary. Supported entries: | |
9172 "repeat" Number of times to repeat calling the | |
9173 callback. -1 means forever. When not present | |
9174 the callback will be called once. | |
9175 If the timer causes an error three times in a | |
9176 row the repeat is cancelled. This avoids that | |
9177 Vim becomes unusable because of all the error | |
9178 messages. | |
9179 | |
9180 Example: > | |
9181 func MyHandler(timer) | |
9182 echo 'Handler called' | |
9183 endfunc | |
9184 let timer = timer_start(500, 'MyHandler', | |
9185 \ {'repeat': 3}) | |
9186 < This will invoke MyHandler() three times at 500 msec | |
9187 intervals. | |
9188 | |
9189 Can also be used as a |method|: > | |
9190 GetMsec()->timer_start(callback) | |
9191 | |
9192 < Not available in the |sandbox|. | |
9193 {only available when compiled with the |+timers| feature} | |
9194 | |
9195 timer_stop({timer}) *timer_stop()* | |
9196 Stop a timer. The timer callback will no longer be invoked. | |
9197 {timer} is an ID returned by timer_start(), thus it must be a | |
9198 Number. If {timer} does not exist there is no error. | |
9199 | |
9200 Can also be used as a |method|: > | |
9201 GetTimer()->timer_stop() | |
9202 | |
9203 < {only available when compiled with the |+timers| feature} | |
9204 | |
9205 timer_stopall() *timer_stopall()* | |
9206 Stop all timers. The timer callbacks will no longer be | |
9207 invoked. Useful if a timer is misbehaving. If there are no | |
9208 timers there is no error. | |
9209 | |
9210 {only available when compiled with the |+timers| feature} | |
9211 | |
9212 tolower({expr}) *tolower()* | |
9213 The result is a copy of the String given, with all uppercase | |
9214 characters turned into lowercase (just like applying |gu| to | |
9215 the string). | |
9216 | |
9217 Can also be used as a |method|: > | |
9218 GetText()->tolower() | |
9219 | |
9220 toupper({expr}) *toupper()* | |
9221 The result is a copy of the String given, with all lowercase | |
9222 characters turned into uppercase (just like applying |gU| to | |
9223 the string). | |
9224 | |
9225 Can also be used as a |method|: > | |
9226 GetText()->toupper() | |
9227 | |
9228 tr({src}, {fromstr}, {tostr}) *tr()* | |
9229 The result is a copy of the {src} string with all characters | |
9230 which appear in {fromstr} replaced by the character in that | |
9231 position in the {tostr} string. Thus the first character in | |
9232 {fromstr} is translated into the first character in {tostr} | |
9233 and so on. Exactly like the unix "tr" command. | |
9234 This code also deals with multibyte characters properly. | |
9235 | |
9236 Examples: > | |
9237 echo tr("hello there", "ht", "HT") | |
9238 < returns "Hello THere" > | |
9239 echo tr("<blob>", "<>", "{}") | |
9240 < returns "{blob}" | |
9241 | |
9242 Can also be used as a |method|: > | |
9243 GetText()->tr(from, to) | |
9244 | |
9245 trim({text} [, {mask} [, {dir}]]) *trim()* | |
9246 Return {text} as a String where any character in {mask} is | |
9247 removed from the beginning and/or end of {text}. | |
9248 | |
9249 If {mask} is not given, {mask} is all characters up to 0x20, | |
9250 which includes Tab, space, NL and CR, plus the non-breaking | |
9251 space character 0xa0. | |
9252 | |
9253 The optional {dir} argument specifies where to remove the | |
9254 characters: | |
9255 0 remove from the beginning and end of {text} | |
9256 1 remove only at the beginning of {text} | |
9257 2 remove only at the end of {text} | |
9258 When omitted both ends are trimmed. | |
9259 | |
9260 This function deals with multibyte characters properly. | |
9261 | |
9262 Examples: > | |
9263 echo trim(" some text ") | |
9264 < returns "some text" > | |
9265 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL" | |
9266 < returns "RESERVE_TAIL" > | |
9267 echo trim("rm<Xrm<>X>rrm", "rm<>") | |
9268 < returns "Xrm<>X" (characters in the middle are not removed) > | |
9269 echo trim(" vim ", " ", 2) | |
9270 < returns " vim" | |
9271 | |
9272 Can also be used as a |method|: > | |
9273 GetText()->trim() | |
9274 | |
9275 trunc({expr}) *trunc()* | |
9276 Return the largest integral value with magnitude less than or | |
9277 equal to {expr} as a |Float| (truncate towards zero). | |
9278 {expr} must evaluate to a |Float| or a |Number|. | |
9279 Examples: > | |
9280 echo trunc(1.456) | |
9281 < 1.0 > | |
9282 echo trunc(-5.456) | |
9283 < -5.0 > | |
9284 echo trunc(4.0) | |
9285 < 4.0 | |
9286 | |
9287 Can also be used as a |method|: > | |
9288 Compute()->trunc() | |
9289 < | |
9290 {only available when compiled with the |+float| feature} | |
9291 | |
9292 *type()* | |
9293 type({expr}) The result is a Number representing the type of {expr}. | |
9294 Instead of using the number directly, it is better to use the | |
9295 v:t_ variable that has the value: | |
9296 Number: 0 |v:t_number| | |
9297 String: 1 |v:t_string| | |
9298 Funcref: 2 |v:t_func| | |
9299 List: 3 |v:t_list| | |
9300 Dictionary: 4 |v:t_dict| | |
9301 Float: 5 |v:t_float| | |
9302 Boolean: 6 |v:t_bool| (v:false and v:true) | |
9303 None: 7 |v:t_none| (v:null and v:none) | |
9304 Job: 8 |v:t_job| | |
9305 Channel: 9 |v:t_channel| | |
9306 Blob: 10 |v:t_blob| | |
9307 For backward compatibility, this method can be used: > | |
9308 :if type(myvar) == type(0) | |
9309 :if type(myvar) == type("") | |
9310 :if type(myvar) == type(function("tr")) | |
9311 :if type(myvar) == type([]) | |
9312 :if type(myvar) == type({}) | |
9313 :if type(myvar) == type(0.0) | |
9314 :if type(myvar) == type(v:false) | |
9315 :if type(myvar) == type(v:none) | |
9316 < To check if the v:t_ variables exist use this: > | |
9317 :if exists('v:t_number') | |
9318 | |
9319 < Can also be used as a |method|: > | |
9320 mylist->type() | |
9321 | |
9322 | |
9323 typename({expr}) *typename()* | |
9324 Return a string representation of the type of {expr}. | |
9325 Example: > | |
9326 echo typename([1, 2, 3]) | |
9327 list<number> | |
9328 | |
9329 | |
9330 undofile({name}) *undofile()* | |
9331 Return the name of the undo file that would be used for a file | |
9332 with name {name} when writing. This uses the 'undodir' | |
9333 option, finding directories that exist. It does not check if | |
9334 the undo file exists. | |
9335 {name} is always expanded to the full path, since that is what | |
9336 is used internally. | |
9337 If {name} is empty undofile() returns an empty string, since a | |
9338 buffer without a file name will not write an undo file. | |
9339 Useful in combination with |:wundo| and |:rundo|. | |
9340 When compiled without the |+persistent_undo| option this always | |
9341 returns an empty string. | |
9342 | |
9343 Can also be used as a |method|: > | |
9344 GetFilename()->undofile() | |
9345 | |
9346 undotree() *undotree()* | |
9347 Return the current state of the undo tree in a dictionary with | |
9348 the following items: | |
9349 "seq_last" The highest undo sequence number used. | |
9350 "seq_cur" The sequence number of the current position in | |
9351 the undo tree. This differs from "seq_last" | |
9352 when some changes were undone. | |
9353 "time_cur" Time last used for |:earlier| and related | |
9354 commands. Use |strftime()| to convert to | |
9355 something readable. | |
9356 "save_last" Number of the last file write. Zero when no | |
9357 write yet. | |
9358 "save_cur" Number of the current position in the undo | |
9359 tree. | |
9360 "synced" Non-zero when the last undo block was synced. | |
9361 This happens when waiting from input from the | |
9362 user. See |undo-blocks|. | |
9363 "entries" A list of dictionaries with information about | |
9364 undo blocks. | |
9365 | |
9366 The first item in the "entries" list is the oldest undo item. | |
9367 Each List item is a |Dictionary| with these items: | |
9368 "seq" Undo sequence number. Same as what appears in | |
9369 |:undolist|. | |
9370 "time" Timestamp when the change happened. Use | |
9371 |strftime()| to convert to something readable. | |
9372 "newhead" Only appears in the item that is the last one | |
9373 that was added. This marks the last change | |
9374 and where further changes will be added. | |
9375 "curhead" Only appears in the item that is the last one | |
9376 that was undone. This marks the current | |
9377 position in the undo tree, the block that will | |
9378 be used by a redo command. When nothing was | |
9379 undone after the last change this item will | |
9380 not appear anywhere. | |
9381 "save" Only appears on the last block before a file | |
9382 write. The number is the write count. The | |
9383 first write has number 1, the last one the | |
9384 "save_last" mentioned above. | |
9385 "alt" Alternate entry. This is again a List of undo | |
9386 blocks. Each item may again have an "alt" | |
9387 item. | |
9388 | |
9389 uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* | |
9390 Remove second and succeeding copies of repeated adjacent | |
9391 {list} items in-place. Returns {list}. If you want a list | |
9392 to remain unmodified make a copy first: > | |
9393 :let newlist = uniq(copy(mylist)) | |
9394 < The default compare function uses the string representation of | |
9395 each item. For the use of {func} and {dict} see |sort()|. | |
9396 | |
9397 Can also be used as a |method|: > | |
9398 mylist->uniq() | |
9399 | |
9400 values({dict}) *values()* | |
9401 Return a |List| with all the values of {dict}. The |List| is | |
9402 in arbitrary order. Also see |items()| and |keys()|. | |
9403 | |
9404 Can also be used as a |method|: > | |
9405 mydict->values() | |
9406 | |
9407 virtcol({expr}) *virtcol()* | |
9408 The result is a Number, which is the screen column of the file | |
9409 position given with {expr}. That is, the last screen position | |
9410 occupied by the character at that position, when the screen | |
9411 would be of unlimited width. When there is a <Tab> at the | |
9412 position, the returned Number will be the column at the end of | |
9413 the <Tab>. For example, for a <Tab> in column 1, with 'ts' | |
9414 set to 8, it returns 8. |conceal| is ignored. | |
9415 For the byte position use |col()|. | |
9416 For the use of {expr} see |col()|. | |
9417 When 'virtualedit' is used {expr} can be [lnum, col, off], where | |
9418 "off" is the offset in screen columns from the start of the | |
9419 character. E.g., a position within a <Tab> or after the last | |
9420 character. When "off" is omitted zero is used. | |
9421 When Virtual editing is active in the current mode, a position | |
9422 beyond the end of the line can be returned. |'virtualedit'| | |
9423 The accepted positions are: | |
9424 . the cursor position | |
9425 $ the end of the cursor line (the result is the | |
9426 number of displayed characters in the cursor line | |
9427 plus one) | |
9428 'x position of mark x (if the mark is not set, 0 is | |
9429 returned) | |
9430 v In Visual mode: the start of the Visual area (the | |
9431 cursor is the end). When not in Visual mode | |
9432 returns the cursor position. Differs from |'<| in | |
9433 that it's updated right away. | |
9434 Note that only marks in the current file can be used. | |
9435 Examples: > | |
9436 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5 | |
9437 virtcol("$") with text "foo^Lbar", returns 9 | |
9438 virtcol("'t") with text " there", with 't at 'h', returns 6 | |
9439 < The first column is 1. 0 is returned for an error. | |
9440 A more advanced example that echoes the maximum length of | |
9441 all lines: > | |
9442 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) | |
9443 | |
9444 < Can also be used as a |method|: > | |
9445 GetPos()->virtcol() | |
9446 | |
9447 | |
9448 visualmode([{expr}]) *visualmode()* | |
9449 The result is a String, which describes the last Visual mode | |
9450 used in the current buffer. Initially it returns an empty | |
9451 string, but once Visual mode has been used, it returns "v", | |
9452 "V", or "<CTRL-V>" (a single CTRL-V character) for | |
9453 character-wise, line-wise, or block-wise Visual mode | |
9454 respectively. | |
9455 Example: > | |
9456 :exe "normal " . visualmode() | |
9457 < This enters the same Visual mode as before. It is also useful | |
9458 in scripts if you wish to act differently depending on the | |
9459 Visual mode that was used. | |
9460 If Visual mode is active, use |mode()| to get the Visual mode | |
9461 (e.g., in a |:vmap|). | |
9462 If {expr} is supplied and it evaluates to a non-zero Number or | |
9463 a non-empty String, then the Visual mode will be cleared and | |
9464 the old value is returned. See |non-zero-arg|. | |
9465 | |
9466 wildmenumode() *wildmenumode()* | |
9467 Returns |TRUE| when the wildmenu is active and |FALSE| | |
9468 otherwise. See 'wildmenu' and 'wildmode'. | |
9469 This can be used in mappings to handle the 'wildcharm' option | |
9470 gracefully. (Makes only sense with |mapmode-c| mappings). | |
9471 | |
9472 For example to make <c-j> work like <down> in wildmode, use: > | |
9473 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" | |
9474 < | |
9475 (Note, this needs the 'wildcharm' option set appropriately). | |
9476 | |
9477 win_execute({id}, {command} [, {silent}]) *win_execute()* | |
9478 Like `execute()` but in the context of window {id}. | |
9479 The window will temporarily be made the current window, | |
9480 without triggering autocommands or changing directory. When | |
9481 executing {command} autocommands will be triggered, this may | |
9482 have unexpected side effects. Use |:noautocmd| if needed. | |
9483 Example: > | |
9484 call win_execute(winid, 'set syntax=python') | |
9485 < Doing the same with `setwinvar()` would not trigger | |
9486 autocommands and not actually show syntax highlighting. | |
9487 | |
9488 *E994* | |
9489 Not all commands are allowed in popup windows. | |
9490 When window {id} does not exist then no error is given and | |
9491 an empty string is returned. | |
9492 | |
9493 Can also be used as a |method|, the base is passed as the | |
9494 second argument: > | |
9495 GetCommand()->win_execute(winid) | |
9496 | |
9497 win_findbuf({bufnr}) *win_findbuf()* | |
9498 Returns a |List| with |window-ID|s for windows that contain | |
9499 buffer {bufnr}. When there is none the list is empty. | |
9500 | |
9501 Can also be used as a |method|: > | |
9502 GetBufnr()->win_findbuf() | |
9503 | |
9504 win_getid([{win} [, {tab}]]) *win_getid()* | |
9505 Get the |window-ID| for the specified window. | |
9506 When {win} is missing use the current window. | |
9507 With {win} this is the window number. The top window has | |
9508 number 1. | |
9509 Without {tab} use the current tab, otherwise the tab with | |
9510 number {tab}. The first tab has number one. | |
9511 Return zero if the window cannot be found. | |
9512 | |
9513 Can also be used as a |method|: > | |
9514 GetWinnr()->win_getid() | |
9515 | |
9516 | |
9517 win_gettype([{nr}]) *win_gettype()* | |
9518 Return the type of the window: | |
9519 "autocmd" autocommand window. Temporary window | |
9520 used to execute autocommands. | |
9521 "command" command-line window |cmdwin| | |
9522 (empty) normal window | |
9523 "loclist" |location-list-window| | |
9524 "popup" popup window |popup| | |
9525 "preview" preview window |preview-window| | |
9526 "quickfix" |quickfix-window| | |
9527 "unknown" window {nr} not found | |
9528 | |
9529 When {nr} is omitted return the type of the current window. | |
9530 When {nr} is given return the type of this window by number or | |
9531 |window-ID|. | |
9532 | |
9533 Also see the 'buftype' option. When running a terminal in a | |
9534 popup window then 'buftype' is "terminal" and win_gettype() | |
9535 returns "popup". | |
9536 | |
9537 Can also be used as a |method|: > | |
9538 GetWinid()->win_gettype() | |
9539 < | |
9540 win_gotoid({expr}) *win_gotoid()* | |
9541 Go to window with ID {expr}. This may also change the current | |
9542 tabpage. | |
9543 Return TRUE if successful, FALSE if the window cannot be found. | |
9544 | |
9545 Can also be used as a |method|: > | |
9546 GetWinid()->win_gotoid() | |
9547 | |
9548 win_id2tabwin({expr}) *win_id2tabwin()* | |
9549 Return a list with the tab number and window number of window | |
9550 with ID {expr}: [tabnr, winnr]. | |
9551 Return [0, 0] if the window cannot be found. | |
9552 | |
9553 Can also be used as a |method|: > | |
9554 GetWinid()->win_id2tabwin() | |
9555 | |
9556 win_id2win({expr}) *win_id2win()* | |
9557 Return the window number of window with ID {expr}. | |
9558 Return 0 if the window cannot be found in the current tabpage. | |
9559 | |
9560 Can also be used as a |method|: > | |
9561 GetWinid()->win_id2win() | |
9562 | |
9563 win_screenpos({nr}) *win_screenpos()* | |
9564 Return the screen position of window {nr} as a list with two | |
9565 numbers: [row, col]. The first window always has position | |
9566 [1, 1], unless there is a tabline, then it is [2, 1]. | |
9567 {nr} can be the window number or the |window-ID|. Use zero | |
9568 for the current window. | |
9569 Returns [0, 0] if the window cannot be found in the current | |
9570 tabpage. | |
9571 | |
9572 Can also be used as a |method|: > | |
9573 GetWinid()->win_screenpos() | |
9574 < | |
9575 win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* | |
9576 Move the window {nr} to a new split of the window {target}. | |
9577 This is similar to moving to {target}, creating a new window | |
9578 using |:split| but having the same contents as window {nr}, and | |
9579 then closing {nr}. | |
9580 | |
9581 Both {nr} and {target} can be window numbers or |window-ID|s. | |
9582 Both must be in the current tab page. | |
9583 | |
9584 Returns zero for success, non-zero for failure. | |
9585 | |
9586 {options} is a |Dictionary| with the following optional entries: | |
9587 "vertical" When TRUE, the split is created vertically, | |
9588 like with |:vsplit|. | |
9589 "rightbelow" When TRUE, the split is made below or to the | |
9590 right (if vertical). When FALSE, it is done | |
9591 above or to the left (if vertical). When not | |
9592 present, the values of 'splitbelow' and | |
9593 'splitright' are used. | |
9594 | |
9595 Can also be used as a |method|: > | |
9596 GetWinid()->win_splitmove(target) | |
9597 < | |
9598 | |
9599 *winbufnr()* | |
9600 winbufnr({nr}) The result is a Number, which is the number of the buffer | |
9601 associated with window {nr}. {nr} can be the window number or | |
9602 the |window-ID|. | |
9603 When {nr} is zero, the number of the buffer in the current | |
9604 window is returned. | |
9605 When window {nr} doesn't exist, -1 is returned. | |
9606 Example: > | |
9607 :echo "The file in the current window is " . bufname(winbufnr(0)) | |
9608 < | |
9609 Can also be used as a |method|: > | |
9610 FindWindow()->winbufnr()->bufname() | |
9611 < | |
9612 *wincol()* | |
9613 wincol() The result is a Number, which is the virtual column of the | |
9614 cursor in the window. This is counting screen cells from the | |
9615 left side of the window. The leftmost column is one. | |
9616 | |
9617 *windowsversion()* | |
9618 windowsversion() | |
9619 The result is a String. For MS-Windows it indicates the OS | |
9620 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", | |
9621 Windows XP is "5.1". For non-MS-Windows systems the result is | |
9622 an empty string. | |
9623 | |
9624 winheight({nr}) *winheight()* | |
9625 The result is a Number, which is the height of window {nr}. | |
9626 {nr} can be the window number or the |window-ID|. | |
9627 When {nr} is zero, the height of the current window is | |
9628 returned. When window {nr} doesn't exist, -1 is returned. | |
9629 An existing window always has a height of zero or more. | |
9630 This excludes any window toolbar line. | |
9631 Examples: > | |
9632 :echo "The current window has " . winheight(0) . " lines." | |
9633 | |
9634 < Can also be used as a |method|: > | |
9635 GetWinid()->winheight() | |
9636 < | |
9637 winlayout([{tabnr}]) *winlayout()* | |
9638 The result is a nested List containing the layout of windows | |
9639 in a tabpage. | |
9640 | |
9641 Without {tabnr} use the current tabpage, otherwise the tabpage | |
9642 with number {tabnr}. If the tabpage {tabnr} is not found, | |
9643 returns an empty list. | |
9644 | |
9645 For a leaf window, it returns: | |
9646 ['leaf', {winid}] | |
9647 For horizontally split windows, which form a column, it | |
9648 returns: | |
9649 ['col', [{nested list of windows}]] | |
9650 For vertically split windows, which form a row, it returns: | |
9651 ['row', [{nested list of windows}]] | |
9652 | |
9653 Example: > | |
9654 " Only one window in the tab page | |
9655 :echo winlayout() | |
9656 ['leaf', 1000] | |
9657 " Two horizontally split windows | |
9658 :echo winlayout() | |
9659 ['col', [['leaf', 1000], ['leaf', 1001]]] | |
9660 " The second tab page, with three horizontally split | |
9661 " windows, with two vertically split windows in the | |
9662 " middle window | |
9663 :echo winlayout(2) | |
9664 ['col', [['leaf', 1002], ['row', [['leaf', 1003], | |
9665 ['leaf', 1001]]], ['leaf', 1000]]] | |
9666 < | |
9667 Can also be used as a |method|: > | |
9668 GetTabnr()->winlayout() | |
9669 < | |
9670 *winline()* | |
9671 winline() The result is a Number, which is the screen line of the cursor | |
9672 in the window. This is counting screen lines from the top of | |
9673 the window. The first line is one. | |
9674 If the cursor was moved the view on the file will be updated | |
9675 first, this may cause a scroll. | |
9676 | |
9677 *winnr()* | |
9678 winnr([{arg}]) The result is a Number, which is the number of the current | |
9679 window. The top window has number 1. | |
9680 Returns zero for a popup window. | |
9681 | |
9682 The optional argument {arg} supports the following values: | |
9683 $ the number of the last window (the window | |
9684 count). | |
9685 # the number of the last accessed window (where | |
9686 |CTRL-W_p| goes to). If there is no previous | |
9687 window or it is in another tab page 0 is | |
9688 returned. | |
9689 {N}j the number of the Nth window below the | |
9690 current window (where |CTRL-W_j| goes to). | |
9691 {N}k the number of the Nth window above the current | |
9692 window (where |CTRL-W_k| goes to). | |
9693 {N}h the number of the Nth window left of the | |
9694 current window (where |CTRL-W_h| goes to). | |
9695 {N}l the number of the Nth window right of the | |
9696 current window (where |CTRL-W_l| goes to). | |
9697 The number can be used with |CTRL-W_w| and ":wincmd w" | |
9698 |:wincmd|. | |
9699 Also see |tabpagewinnr()| and |win_getid()|. | |
9700 Examples: > | |
9701 let window_count = winnr('$') | |
9702 let prev_window = winnr('#') | |
9703 let wnum = winnr('3k') | |
9704 | |
9705 < Can also be used as a |method|: > | |
9706 GetWinval()->winnr() | |
9707 < | |
9708 *winrestcmd()* | |
9709 winrestcmd() Returns a sequence of |:resize| commands that should restore | |
9710 the current window sizes. Only works properly when no windows | |
9711 are opened or closed and the current window and tab page is | |
9712 unchanged. | |
9713 Example: > | |
9714 :let cmd = winrestcmd() | |
9715 :call MessWithWindowSizes() | |
9716 :exe cmd | |
9717 < | |
9718 *winrestview()* | |
9719 winrestview({dict}) | |
9720 Uses the |Dictionary| returned by |winsaveview()| to restore | |
9721 the view of the current window. | |
9722 Note: The {dict} does not have to contain all values, that are | |
9723 returned by |winsaveview()|. If values are missing, those | |
9724 settings won't be restored. So you can use: > | |
9725 :call winrestview({'curswant': 4}) | |
9726 < | |
9727 This will only set the curswant value (the column the cursor | |
9728 wants to move on vertical movements) of the cursor to column 5 | |
9729 (yes, that is 5), while all other settings will remain the | |
9730 same. This is useful, if you set the cursor position manually. | |
9731 | |
9732 If you have changed the values the result is unpredictable. | |
9733 If the window size changed the result won't be the same. | |
9734 | |
9735 Can also be used as a |method|: > | |
9736 GetView()->winrestview() | |
9737 < | |
9738 *winsaveview()* | |
9739 winsaveview() Returns a |Dictionary| that contains information to restore | |
9740 the view of the current window. Use |winrestview()| to | |
9741 restore the view. | |
9742 This is useful if you have a mapping that jumps around in the | |
9743 buffer and you want to go back to the original view. | |
9744 This does not save fold information. Use the 'foldenable' | |
9745 option to temporarily switch off folding, so that folds are | |
9746 not opened when moving around. This may have side effects. | |
9747 The return value includes: | |
9748 lnum cursor line number | |
9749 col cursor column (Note: the first column | |
9750 zero, as opposed to what getpos() | |
9751 returns) | |
9752 coladd cursor column offset for 'virtualedit' | |
9753 curswant column for vertical movement | |
9754 topline first line in the window | |
9755 topfill filler lines, only in diff mode | |
9756 leftcol first column displayed; only used when | |
9757 'wrap' is off | |
9758 skipcol columns skipped | |
9759 Note that no option values are saved. | |
9760 | |
9761 | |
9762 winwidth({nr}) *winwidth()* | |
9763 The result is a Number, which is the width of window {nr}. | |
9764 {nr} can be the window number or the |window-ID|. | |
9765 When {nr} is zero, the width of the current window is | |
9766 returned. When window {nr} doesn't exist, -1 is returned. | |
9767 An existing window always has a width of zero or more. | |
9768 Examples: > | |
9769 :echo "The current window has " . winwidth(0) . " columns." | |
9770 :if winwidth(0) <= 50 | |
9771 : 50 wincmd | | |
9772 :endif | |
9773 < For getting the terminal or screen size, see the 'columns' | |
9774 option. | |
9775 | |
9776 Can also be used as a |method|: > | |
9777 GetWinid()->winwidth() | |
9778 | |
9779 | |
9780 wordcount() *wordcount()* | |
9781 The result is a dictionary of byte/chars/word statistics for | |
9782 the current buffer. This is the same info as provided by | |
9783 |g_CTRL-G| | |
9784 The return value includes: | |
9785 bytes Number of bytes in the buffer | |
9786 chars Number of chars in the buffer | |
9787 words Number of words in the buffer | |
9788 cursor_bytes Number of bytes before cursor position | |
9789 (not in Visual mode) | |
9790 cursor_chars Number of chars before cursor position | |
9791 (not in Visual mode) | |
9792 cursor_words Number of words before cursor position | |
9793 (not in Visual mode) | |
9794 visual_bytes Number of bytes visually selected | |
9795 (only in Visual mode) | |
9796 visual_chars Number of chars visually selected | |
9797 (only in Visual mode) | |
9798 visual_words Number of words visually selected | |
9799 (only in Visual mode) | |
9800 | |
9801 | |
9802 *writefile()* | |
9803 writefile({object}, {fname} [, {flags}]) | |
9804 When {object} is a |List| write it to file {fname}. Each list | |
9805 item is separated with a NL. Each list item must be a String | |
9806 or Number. | |
9807 When {flags} contains "b" then binary mode is used: There will | |
9808 not be a NL after the last list item. An empty item at the | |
9809 end does cause the last line in the file to end in a NL. | |
9810 | |
9811 When {object} is a |Blob| write the bytes to file {fname} | |
9812 unmodified. | |
9813 | |
9814 When {flags} contains "a" then append mode is used, lines are | |
9815 appended to the file: > | |
9816 :call writefile(["foo"], "event.log", "a") | |
9817 :call writefile(["bar"], "event.log", "a") | |
9818 < | |
9819 When {flags} contains "s" then fsync() is called after writing | |
9820 the file. This flushes the file to disk, if possible. This | |
9821 takes more time but avoids losing the file if the system | |
9822 crashes. | |
9823 When {flags} does not contain "S" or "s" then fsync() is | |
9824 called if the 'fsync' option is set. | |
9825 When {flags} contains "S" then fsync() is not called, even | |
9826 when 'fsync' is set. | |
9827 | |
9828 All NL characters are replaced with a NUL character. | |
9829 Inserting CR characters needs to be done before passing {list} | |
9830 to writefile(). | |
9831 An existing file is overwritten, if possible. | |
9832 When the write fails -1 is returned, otherwise 0. There is an | |
9833 error message if the file can't be created or when writing | |
9834 fails. | |
9835 Also see |readfile()|. | |
9836 To copy a file byte for byte: > | |
9837 :let fl = readfile("foo", "b") | |
9838 :call writefile(fl, "foocopy", "b") | |
9839 | |
9840 < Can also be used as a |method|: > | |
9841 GetText()->writefile("thefile") | |
9842 | |
9843 | |
9844 xor({expr}, {expr}) *xor()* | |
9845 Bitwise XOR on the two arguments. The arguments are converted | |
9846 to a number. A List, Dict or Float argument causes an error. | |
9847 Example: > | |
9848 :let bits = xor(bits, 0x80) | |
9849 < | |
9850 Can also be used as a |method|: > | |
9851 :let bits = bits->xor(0x80) | |
9852 < | |
9853 | |
9854 ============================================================================== | |
9855 3. Feature list *feature-list* | |
9856 | |
9857 There are three types of features: | |
9858 1. Features that are only supported when they have been enabled when Vim | |
9859 was compiled |+feature-list|. Example: > | |
9860 :if has("cindent") | |
9861 < *gui_running* | |
9862 2. Features that are only supported when certain conditions have been met. | |
9863 Example: > | |
9864 :if has("gui_running") | |
9865 < *has-patch* | |
9866 3. Beyond a certain version or at a certain version and including a specific | |
9867 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or | |
9868 later, or it is version 7.4 and patch 248 was included. Example: > | |
9869 :if has("patch-7.4.248") | |
9870 < Note that it's possible for patch 248 to be omitted even though 249 is | |
9871 included. Only happens when cherry-picking patches. | |
9872 Note that this form only works for patch 7.4.237 and later, before that | |
9873 you need to check for the patch and the v:version. Example (checking | |
9874 version 6.2.148 or later): > | |
9875 :if v:version > 602 || (v:version == 602 && has("patch148")) | |
9876 | |
9877 Hint: To find out if Vim supports backslashes in a file name (MS-Windows), | |
9878 use: `if exists('+shellslash')` | |
9879 | |
9880 | |
9881 acl Compiled with |ACL| support. | |
9882 all_builtin_terms Compiled with all builtin terminals enabled. | |
9883 amiga Amiga version of Vim. | |
9884 arabic Compiled with Arabic support |Arabic|. | |
9885 arp Compiled with ARP support (Amiga). | |
9886 autocmd Compiled with autocommand support. (always true) | |
9887 autochdir Compiled with support for 'autochdir' | |
9888 autoservername Automatically enable |clientserver| | |
9889 balloon_eval Compiled with |balloon-eval| support. | |
9890 balloon_multiline GUI supports multiline balloons. | |
9891 beos BeOS version of Vim. | |
9892 browse Compiled with |:browse| support, and browse() will | |
9893 work. | |
9894 browsefilter Compiled with support for |browsefilter|. | |
9895 bsd Compiled on an OS in the BSD family (excluding macOS). | |
9896 builtin_terms Compiled with some builtin terminals. | |
9897 byte_offset Compiled with support for 'o' in 'statusline' | |
9898 channel Compiled with support for |channel| and |job| | |
9899 cindent Compiled with 'cindent' support. | |
9900 clientserver Compiled with remote invocation support |clientserver|. | |
9901 clipboard Compiled with 'clipboard' support. | |
9902 clipboard_working Compiled with 'clipboard' support and it can be used. | |
9903 cmdline_compl Compiled with |cmdline-completion| support. | |
9904 cmdline_hist Compiled with |cmdline-history| support. | |
9905 cmdline_info Compiled with 'showcmd' and 'ruler' support. | |
9906 comments Compiled with |'comments'| support. | |
9907 compatible Compiled to be very Vi compatible. | |
9908 conpty Platform where |ConPTY| can be used. | |
9909 cryptv Compiled with encryption support |encryption|. | |
9910 cscope Compiled with |cscope| support. | |
9911 cursorbind Compiled with |'cursorbind'| (always true) | |
9912 debug Compiled with "DEBUG" defined. | |
9913 dialog_con Compiled with console dialog support. | |
9914 dialog_gui Compiled with GUI dialog support. | |
9915 diff Compiled with |vimdiff| and 'diff' support. | |
9916 digraphs Compiled with support for digraphs. | |
9917 directx Compiled with support for DirectX and 'renderoptions'. | |
9918 dnd Compiled with support for the "~ register |quote_~|. | |
9919 drop_file Compiled with |drop_file| support. | |
9920 ebcdic Compiled on a machine with ebcdic character set. | |
9921 emacs_tags Compiled with support for Emacs tags. | |
9922 eval Compiled with expression evaluation support. Always | |
9923 true, of course! | |
9924 ex_extra |+ex_extra| (always true) | |
9925 extra_search Compiled with support for |'incsearch'| and | |
9926 |'hlsearch'| | |
9927 farsi Support for Farsi was removed |farsi|. | |
9928 file_in_path Compiled with support for |gf| and |<cfile>| | |
9929 filterpipe When 'shelltemp' is off pipes are used for shell | |
9930 read/write/filter commands | |
9931 find_in_path Compiled with support for include file searches | |
9932 |+find_in_path|. | |
9933 float Compiled with support for |Float|. | |
9934 fname_case Case in file names matters (for Amiga and MS-Windows | |
9935 this is not present). | |
9936 folding Compiled with |folding| support. | |
9937 footer Compiled with GUI footer support. |gui-footer| | |
9938 fork Compiled to use fork()/exec() instead of system(). | |
9939 gettext Compiled with message translation |multi-lang| | |
9940 gui Compiled with GUI enabled. | |
9941 gui_athena Compiled with Athena GUI. | |
9942 gui_gnome Compiled with Gnome support (gui_gtk is also defined). | |
9943 gui_gtk Compiled with GTK+ GUI (any version). | |
9944 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). | |
9945 gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined). | |
9946 gui_haiku Compiled with Haiku GUI. | |
9947 gui_mac Compiled with Macintosh GUI. | |
9948 gui_motif Compiled with Motif GUI. | |
9949 gui_photon Compiled with Photon GUI. | |
9950 gui_running Vim is running in the GUI, or it will start soon. | |
9951 gui_win32 Compiled with MS-Windows Win32 GUI. | |
9952 gui_win32s idem, and Win32s system being used (Windows 3.1) | |
9953 haiku Haiku version of Vim. | |
9954 hangul_input Compiled with Hangul input support. |hangul| | |
9955 hpux HP-UX version of Vim. | |
9956 iconv Can use iconv() for conversion. | |
9957 insert_expand Compiled with support for CTRL-X expansion commands in | |
9958 Insert mode. (always true) | |
9959 job Compiled with support for |channel| and |job| | |
9960 ipv6 Compiled with support for IPv6 networking in |channel|. | |
9961 jumplist Compiled with |jumplist| support. | |
9962 keymap Compiled with 'keymap' support. | |
9963 lambda Compiled with |lambda| support. | |
9964 langmap Compiled with 'langmap' support. | |
9965 libcall Compiled with |libcall()| support. | |
9966 linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and | |
9967 'breakindent' support. | |
9968 linux Linux version of Vim. | |
9969 lispindent Compiled with support for lisp indenting. | |
9970 listcmds Compiled with commands for the buffer list |:files| | |
9971 and the argument list |arglist|. | |
9972 localmap Compiled with local mappings and abbr. |:map-local| | |
9973 lua Compiled with Lua interface |Lua|. | |
9974 mac Any Macintosh version of Vim cf. osx | |
9975 macunix Synonym for osxdarwin | |
9976 menu Compiled with support for |:menu|. | |
9977 mksession Compiled with support for |:mksession|. | |
9978 modify_fname Compiled with file name modifiers. |filename-modifiers| | |
9979 (always true) | |
9980 mouse Compiled with support for mouse. | |
9981 mouse_dec Compiled with support for Dec terminal mouse. | |
9982 mouse_gpm Compiled with support for gpm (Linux console mouse) | |
9983 mouse_gpm_enabled GPM mouse is working | |
9984 mouse_netterm Compiled with support for netterm mouse. | |
9985 mouse_pterm Compiled with support for qnx pterm mouse. | |
9986 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse) | |
9987 mouse_sgr Compiled with support for sgr mouse. | |
9988 mouse_urxvt Compiled with support for urxvt mouse. | |
9989 mouse_xterm Compiled with support for xterm mouse. | |
9990 mouseshape Compiled with support for 'mouseshape'. | |
9991 multi_byte Compiled with support for 'encoding' (always true) | |
9992 multi_byte_encoding 'encoding' is set to a multibyte encoding. | |
9993 multi_byte_ime Compiled with support for IME input method. | |
9994 multi_lang Compiled with support for multiple languages. | |
9995 mzscheme Compiled with MzScheme interface |mzscheme|. | |
9996 nanotime Compiled with sub-second time stamp checks. | |
9997 netbeans_enabled Compiled with support for |netbeans| and connected. | |
9998 netbeans_intg Compiled with support for |netbeans|. | |
9999 num64 Compiled with 64-bit |Number| support. | |
10000 ole Compiled with OLE automation support for Win32. | |
10001 osx Compiled for macOS cf. mac | |
10002 osxdarwin Compiled for macOS, with |mac-darwin-feature| | |
10003 packages Compiled with |packages| support. | |
10004 path_extra Compiled with up/downwards search in 'path' and 'tags' | |
10005 perl Compiled with Perl interface. | |
10006 persistent_undo Compiled with support for persistent undo history. | |
10007 postscript Compiled with PostScript file printing. | |
10008 printer Compiled with |:hardcopy| support. | |
10009 profile Compiled with |:profile| support. | |
10010 python Python 2.x interface available. |has-python| | |
10011 python_compiled Compiled with Python 2.x interface. |has-python| | |
10012 python_dynamic Python 2.x interface is dynamically loaded. |has-python| | |
10013 python3 Python 3.x interface available. |has-python| | |
10014 python3_compiled Compiled with Python 3.x interface. |has-python| | |
10015 python3_dynamic Python 3.x interface is dynamically loaded. |has-python| | |
10016 pythonx Python 2.x and/or 3.x interface available. |python_x| | |
10017 qnx QNX version of Vim. | |
10018 quickfix Compiled with |quickfix| support. | |
10019 reltime Compiled with |reltime()| support. | |
10020 rightleft Compiled with 'rightleft' support. | |
10021 ruby Compiled with Ruby interface |ruby|. | |
10022 scrollbind Compiled with 'scrollbind' support. (always true) | |
10023 showcmd Compiled with 'showcmd' support. | |
10024 signs Compiled with |:sign| support. | |
10025 smartindent Compiled with 'smartindent' support. | |
10026 sodium Compiled with libsodium for better crypt support | |
10027 sound Compiled with sound support, e.g. `sound_playevent()` | |
10028 spell Compiled with spell checking support |spell|. | |
10029 startuptime Compiled with |--startuptime| support. | |
10030 statusline Compiled with support for 'statusline', 'rulerformat' | |
10031 and special formats of 'titlestring' and 'iconstring'. | |
10032 sun SunOS version of Vim. | |
10033 sun_workshop Support for Sun |workshop| has been removed. | |
10034 syntax Compiled with syntax highlighting support |syntax|. | |
10035 syntax_items There are active syntax highlighting items for the | |
10036 current buffer. | |
10037 system Compiled to use system() instead of fork()/exec(). | |
10038 tag_binary Compiled with binary searching in tags files | |
10039 |tag-binary-search|. | |
10040 tag_old_static Support for old static tags was removed, see | |
10041 |tag-old-static|. | |
10042 tcl Compiled with Tcl interface. | |
10043 termguicolors Compiled with true color in terminal support. | |
10044 terminal Compiled with |terminal| support. | |
10045 terminfo Compiled with terminfo instead of termcap. | |
10046 termresponse Compiled with support for |t_RV| and |v:termresponse|. | |
10047 textobjects Compiled with support for |text-objects|. | |
10048 textprop Compiled with support for |text-properties|. | |
10049 tgetent Compiled with tgetent support, able to use a termcap | |
10050 or terminfo file. | |
10051 timers Compiled with |timer_start()| support. | |
10052 title Compiled with window title support |'title'|. | |
10053 toolbar Compiled with support for |gui-toolbar|. | |
10054 ttyin input is a terminal (tty) | |
10055 ttyout output is a terminal (tty) | |
10056 unix Unix version of Vim. *+unix* | |
10057 unnamedplus Compiled with support for "unnamedplus" in 'clipboard' | |
10058 user_commands User-defined commands. (always true) | |
10059 vartabs Compiled with variable tabstop support |'vartabstop'|. | |
10060 vcon Win32: Virtual console support is working, can use | |
10061 'termguicolors'. Also see |+vtp|. | |
10062 vertsplit Compiled with vertically split windows |:vsplit|. | |
10063 (always true) | |
10064 vim_starting True while initial source'ing takes place. |startup| | |
10065 *vim_starting* | |
10066 viminfo Compiled with viminfo support. | |
10067 vimscript-1 Compiled Vim script version 1 support | |
10068 vimscript-2 Compiled Vim script version 2 support | |
10069 vimscript-3 Compiled Vim script version 3 support | |
10070 virtualedit Compiled with 'virtualedit' option. (always true) | |
10071 visual Compiled with Visual mode. (always true) | |
10072 visualextra Compiled with extra Visual mode commands. (always | |
10073 true) |blockwise-operators|. | |
10074 vms VMS version of Vim. | |
10075 vreplace Compiled with |gR| and |gr| commands. (always true) | |
10076 vtp Compiled for vcon support |+vtp| (check vcon to find | |
10077 out if it works in the current console). | |
10078 wildignore Compiled with 'wildignore' option. | |
10079 wildmenu Compiled with 'wildmenu' option. | |
10080 win16 old version for MS-Windows 3.1 (always false) | |
10081 win32 Win32 version of Vim (MS-Windows 95 and later, 32 or | |
10082 64 bits) | |
10083 win32unix Win32 version of Vim, using Unix files (Cygwin) | |
10084 win64 Win64 version of Vim (MS-Windows 64 bit). | |
10085 win95 Win32 version for MS-Windows 95/98/ME (always false) | |
10086 winaltkeys Compiled with 'winaltkeys' option. | |
10087 windows Compiled with support for more than one window. | |
10088 (always true) | |
10089 writebackup Compiled with 'writebackup' default on. | |
10090 xfontset Compiled with X fontset support |xfontset|. | |
10091 xim Compiled with X input method support |xim|. | |
10092 xpm Compiled with pixmap support. | |
10093 xpm_w32 Compiled with pixmap support for Win32. (Only for | |
10094 backward compatibility. Use "xpm" instead.) | |
10095 xsmp Compiled with X session management support. | |
10096 xsmp_interact Compiled with interactive X session management support. | |
10097 xterm_clipboard Compiled with support for xterm clipboard. | |
10098 xterm_save Compiled with support for saving and restoring the | |
10099 xterm screen. | |
10100 x11 Compiled with X11 support. | |
10101 | |
10102 | |
10103 ============================================================================== | |
10104 4. Matching a pattern in a String *string-match* | |
10105 | |
10106 This is common between several functions. A regexp pattern as explained at | |
10107 |pattern| is normally used to find a match in the buffer lines. When a | |
10108 pattern is used to find a match in a String, almost everything works in the | |
10109 same way. The difference is that a String is handled like it is one line. | |
10110 When it contains a "\n" character, this is not seen as a line break for the | |
10111 pattern. It can be matched with a "\n" in the pattern, or with ".". Example: | |
10112 > | |
10113 :let a = "aaaa\nxxxx" | |
10114 :echo matchstr(a, "..\n..") | |
10115 aa | |
10116 xx | |
10117 :echo matchstr(a, "a.x") | |
10118 a | |
10119 x | |
10120 | |
10121 Don't forget that "^" will only match at the first character of the String and | |
10122 "$" at the last character of the string. They don't match after or before a | |
10123 "\n". | |
10124 | |
10125 vim:tw=78:ts=8:noet:ft=help:norl: |