blob: 3448ed58551e906fc56fb29c5527fc0436e92b2f [file] [log] [blame]
Bram Moolenaar71b6d332022-09-10 13:13:14 +01001*builtin.txt* For Vim version 9.0. Last change: 2022 Sep 10
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Builtin functions *builtin-functions*
8
9Note: Expression evaluation can be disabled at compile time. If this has been
10done, the builtin functions are not available. See |+eval| and
11|no-eval-feature|.
12
131. Overview |builtin-function-list|
142. Details |builtin-function-details|
153. Feature list |feature-list|
164. Matching a pattern in a String |string-match|
17
18==============================================================================
191. Overview *builtin-function-list*
20
21Use CTRL-] on the function name to jump to the full explanation.
22
23USAGE RESULT DESCRIPTION ~
24
25abs({expr}) Float or Number absolute value of {expr}
26acos({expr}) Float arc cosine of {expr}
27add({object}, {item}) List/Blob append {item} to {object}
28and({expr}, {expr}) Number bitwise AND
29append({lnum}, {text}) Number append {text} below line {lnum}
30appendbufline({expr}, {lnum}, {text})
31 Number append {text} below line {lnum}
32 in buffer {expr}
33argc([{winid}]) Number number of files in the argument list
34argidx() Number current index in the argument list
35arglistid([{winnr} [, {tabnr}]]) Number argument list id
36argv({nr} [, {winid}]) String {nr} entry of the argument list
37argv([-1, {winid}]) List the argument list
38asin({expr}) Float arc sine of {expr}
39assert_beeps({cmd}) Number assert {cmd} causes a beep
40assert_equal({exp}, {act} [, {msg}])
41 Number assert {exp} is equal to {act}
42assert_equalfile({fname-one}, {fname-two} [, {msg}])
43 Number assert file contents are equal
44assert_exception({error} [, {msg}])
45 Number assert {error} is in v:exception
46assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
47 Number assert {cmd} fails
48assert_false({actual} [, {msg}])
49 Number assert {actual} is false
50assert_inrange({lower}, {upper}, {actual} [, {msg}])
51 Number assert {actual} is inside the range
52assert_match({pat}, {text} [, {msg}])
53 Number assert {pat} matches {text}
54assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
55assert_notequal({exp}, {act} [, {msg}])
56 Number assert {exp} is not equal {act}
57assert_notmatch({pat}, {text} [, {msg}])
58 Number assert {pat} not matches {text}
59assert_report({msg}) Number report a test failure
60assert_true({actual} [, {msg}]) Number assert {actual} is true
61atan({expr}) Float arc tangent of {expr}
62atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +010063autocmd_add({acmds}) Bool add a list of autocmds and groups
64autocmd_delete({acmds}) Bool delete a list of autocmds and groups
65autocmd_get([{opts}]) List return a list of autocmds
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000066balloon_gettext() String current text in the balloon
67balloon_show({expr}) none show {expr} inside the balloon
68balloon_split({msg}) List split {msg} as used for a balloon
69blob2list({blob}) List convert {blob} into a list of numbers
70browse({save}, {title}, {initdir}, {default})
71 String put up a file requester
72browsedir({title}, {initdir}) String put up a directory requester
73bufadd({name}) Number add a buffer to the buffer list
74bufexists({buf}) Number |TRUE| if buffer {buf} exists
75buflisted({buf}) Number |TRUE| if buffer {buf} is listed
76bufload({buf}) Number load buffer {buf} if not loaded yet
77bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
78bufname([{buf}]) String Name of the buffer {buf}
79bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
80bufwinid({buf}) Number window ID of buffer {buf}
81bufwinnr({buf}) Number window number of buffer {buf}
82byte2line({byte}) Number line number at byte count {byte}
83byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
84byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
85call({func}, {arglist} [, {dict}])
86 any call {func} with arguments {arglist}
87ceil({expr}) Float round {expr} up
88ch_canread({handle}) Number check if there is something to read
89ch_close({handle}) none close {handle}
90ch_close_in({handle}) none close in part of {handle}
91ch_evalexpr({handle}, {expr} [, {options}])
92 any evaluate {expr} on JSON {handle}
93ch_evalraw({handle}, {string} [, {options}])
94 any evaluate {string} on raw {handle}
95ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
96ch_getjob({channel}) Job get the Job of {channel}
97ch_info({handle}) String info about channel {handle}
98ch_log({msg} [, {handle}]) none write {msg} in the channel log file
99ch_logfile({fname} [, {mode}]) none start logging channel activity
100ch_open({address} [, {options}])
101 Channel open a channel to {address}
102ch_read({handle} [, {options}]) String read from {handle}
103ch_readblob({handle} [, {options}])
104 Blob read Blob from {handle}
105ch_readraw({handle} [, {options}])
106 String read raw from {handle}
107ch_sendexpr({handle}, {expr} [, {options}])
108 any send {expr} over JSON {handle}
109ch_sendraw({handle}, {expr} [, {options}])
110 any send {expr} over raw {handle}
111ch_setoptions({handle}, {options})
112 none set options for {handle}
113ch_status({handle} [, {options}])
114 String status of channel {handle}
115changenr() Number current change number
116char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
117charclass({string}) Number character class of {string}
118charcol({expr}) Number column number of cursor or mark
119charidx({string}, {idx} [, {countcc}])
120 Number char index of byte {idx} in {string}
121chdir({dir}) String change current working directory
122cindent({lnum}) Number C indent for line {lnum}
123clearmatches([{win}]) none clear all matches
124col({expr}) Number column byte index of cursor or mark
125complete({startcol}, {matches}) none set Insert mode completion
126complete_add({expr}) Number add completion match
127complete_check() Number check for key typed during completion
128complete_info([{what}]) Dict get current completion information
129confirm({msg} [, {choices} [, {default} [, {type}]]])
130 Number number of choice picked by user
131copy({expr}) any make a shallow copy of {expr}
132cos({expr}) Float cosine of {expr}
133cosh({expr}) Float hyperbolic cosine of {expr}
134count({comp}, {expr} [, {ic} [, {start}]])
135 Number count how many {expr} are in {comp}
136cscope_connection([{num}, {dbpath} [, {prepend}]])
137 Number checks existence of cscope connection
138cursor({lnum}, {col} [, {off}])
139 Number move cursor to {lnum}, {col}, {off}
140cursor({list}) Number move cursor to position in {list}
141debugbreak({pid}) Number interrupt process being debugged
142deepcopy({expr} [, {noref}]) any make a full copy of {expr}
143delete({fname} [, {flags}]) Number delete the file or directory {fname}
144deletebufline({buf}, {first} [, {last}])
145 Number delete lines from buffer {buf}
146did_filetype() Number |TRUE| if FileType autocmd event used
147diff_filler({lnum}) Number diff filler lines about {lnum}
148diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
149digraph_get({chars}) String get the |digraph| of {chars}
150digraph_getlist([{listall}]) List get all |digraph|s
151digraph_set({chars}, {digraph}) Boolean register |digraph|
152digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
153echoraw({expr}) none output {expr} as-is
154empty({expr}) Number |TRUE| if {expr} is empty
155environ() Dict return environment variables
156escape({string}, {chars}) String escape {chars} in {string} with '\'
157eval({string}) any evaluate {string} into its value
158eventhandler() Number |TRUE| if inside an event handler
159executable({expr}) Number 1 if executable {expr} exists
160execute({command}) String execute {command} and get the output
161exepath({expr}) String full path of the command {expr}
162exists({expr}) Number |TRUE| if {expr} exists
163exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
164exp({expr}) Float exponential of {expr}
165expand({expr} [, {nosuf} [, {list}]])
166 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100167expandcmd({string} [, {options}])
168 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000169extend({expr1}, {expr2} [, {expr3}])
170 List/Dict insert items of {expr2} into {expr1}
171extendnew({expr1}, {expr2} [, {expr3}])
172 List/Dict like |extend()| but creates a new
173 List or Dictionary
174feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
175filereadable({file}) Number |TRUE| if {file} is a readable file
176filewritable({file}) Number |TRUE| if {file} is a writable file
177filter({expr1}, {expr2}) List/Dict/Blob/String
178 remove items from {expr1} where
179 {expr2} is 0
180finddir({name} [, {path} [, {count}]])
181 String find directory {name} in {path}
182findfile({name} [, {path} [, {count}]])
183 String find file {name} in {path}
184flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
185flattennew({list} [, {maxdepth}])
186 List flatten a copy of {list}
187float2nr({expr}) Number convert Float {expr} to a Number
188floor({expr}) Float round {expr} down
189fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
190fnameescape({fname}) String escape special characters in {fname}
191fnamemodify({fname}, {mods}) String modify file name
192foldclosed({lnum}) Number first line of fold at {lnum} if closed
193foldclosedend({lnum}) Number last line of fold at {lnum} if closed
194foldlevel({lnum}) Number fold level at {lnum}
195foldtext() String line displayed for closed fold
196foldtextresult({lnum}) String text for closed fold at {lnum}
197foreground() Number bring the Vim window to the foreground
198fullcommand({name}) String get full command from {name}
199funcref({name} [, {arglist}] [, {dict}])
200 Funcref reference to function {name}
201function({name} [, {arglist}] [, {dict}])
202 Funcref named reference to function {name}
203garbagecollect([{atexit}]) none free memory, breaking cyclic references
204get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
205get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
206get({func}, {what}) any get property of funcref/partial {func}
207getbufinfo([{buf}]) List information about buffers
208getbufline({buf}, {lnum} [, {end}])
209 List lines {lnum} to {end} of buffer {buf}
210getbufvar({buf}, {varname} [, {def}])
211 any variable {varname} in buffer {buf}
212getchangelist([{buf}]) List list of change list items
213getchar([expr]) Number or String
214 get one character from the user
215getcharmod() Number modifiers for the last typed character
216getcharpos({expr}) List position of cursor, mark, etc.
217getcharsearch() Dict last character search
218getcharstr([expr]) String get one character from the user
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100219getcmdcompltype() String return the type of the current
220 command-line completion
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000221getcmdline() String return the current command-line
222getcmdpos() Number return cursor position in command-line
Shougo Matsushita79d599b2022-05-07 12:48:29 +0100223getcmdscreenpos() Number return cursor screen position in
224 command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000225getcmdtype() String return current command-line type
226getcmdwintype() String return current command-line window type
227getcompletion({pat}, {type} [, {filtered}])
228 List list of cmdline completion matches
229getcurpos([{winnr}]) List position of the cursor
230getcursorcharpos([{winnr}]) List character position of the cursor
231getcwd([{winnr} [, {tabnr}]]) String get the current working directory
232getenv({name}) String return environment variable
233getfontname([{name}]) String name of font being used
234getfperm({fname}) String file permissions of file {fname}
235getfsize({fname}) Number size in bytes of file {fname}
236getftime({fname}) Number last modification time of file
237getftype({fname}) String description of type of file {fname}
238getimstatus() Number |TRUE| if the IME status is active
239getjumplist([{winnr} [, {tabnr}]])
240 List list of jump list items
241getline({lnum}) String line {lnum} of current buffer
242getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
243getloclist({nr}) List list of location list items
244getloclist({nr}, {what}) Dict get specific location list properties
245getmarklist([{buf}]) List list of global/local marks
246getmatches([{win}]) List list of current matches
247getmousepos() Dict last known mouse position
248getpid() Number process ID of Vim
249getpos({expr}) List position of cursor, mark, etc.
250getqflist() List list of quickfix items
251getqflist({what}) Dict get specific quickfix list properties
252getreg([{regname} [, 1 [, {list}]]])
253 String or List contents of a register
254getreginfo([{regname}]) Dict information about a register
255getregtype([{regname}]) String type of a register
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +0100256getscriptinfo([{opts}]) List list of sourced scripts
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000257gettabinfo([{expr}]) List list of tab pages
258gettabvar({nr}, {varname} [, {def}])
259 any variable {varname} in tab {nr} or {def}
260gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
261 any {name} in {winnr} in tab page {tabnr}
262gettagstack([{nr}]) Dict get the tag stack of window {nr}
263gettext({text}) String lookup translation of {text}
264getwininfo([{winid}]) List list of info about each window
265getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
266getwinposx() Number X coord in pixels of the Vim window
267getwinposy() Number Y coord in pixels of the Vim window
268getwinvar({nr}, {varname} [, {def}])
269 any variable {varname} in window {nr}
270glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
271 any expand file wildcards in {expr}
272glob2regpat({expr}) String convert a glob pat into a search pat
273globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
274 String do glob({expr}) for all dirs in {path}
275has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
276has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
277haslocaldir([{winnr} [, {tabnr}]])
278 Number |TRUE| if the window executed |:lcd|
279 or |:tcd|
280hasmapto({what} [, {mode} [, {abbr}]])
281 Number |TRUE| if mapping to {what} exists
282histadd({history}, {item}) Number add an item to a history
283histdel({history} [, {item}]) Number remove an item from a history
284histget({history} [, {index}]) String get the item {index} from a history
285histnr({history}) Number highest index of a history
286hlID({name}) Number syntax ID of highlight group {name}
287hlexists({name}) Number |TRUE| if highlight group {name} exists
288hlget([{name} [, {resolve}]]) List get highlight group attributes
289hlset({list}) Number set highlight group attributes
290hostname() String name of the machine Vim is running on
291iconv({expr}, {from}, {to}) String convert encoding of {expr}
292indent({lnum}) Number indent of line {lnum}
293index({object}, {expr} [, {start} [, {ic}]])
294 Number index in {object} where {expr} appears
Yegappan Lakshmananb2186552022-08-13 13:09:20 +0100295indexof({object}, {expr} [, {opts}]])
296 Number index in {object} where {expr} is true
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000297input({prompt} [, {text} [, {completion}]])
298 String get input from the user
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100299inputdialog({prompt} [, {text} [, {cancelreturn}]])
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000300 String like input() but in a GUI dialog
301inputlist({textlist}) Number let the user pick from a choice list
302inputrestore() Number restore typeahead
303inputsave() Number save and clear typeahead
304inputsecret({prompt} [, {text}]) String like input() but hiding the text
305insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
306interrupt() none interrupt script execution
307invert({expr}) Number bitwise invert
LemonBoydca1d402022-04-28 15:26:33 +0100308isabsolutepath({path}) Number |TRUE| if {path} is an absolute path
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000309isdirectory({directory}) Number |TRUE| if {directory} is a directory
310isinf({expr}) Number determine if {expr} is infinity value
311 (positive or negative)
312islocked({expr}) Number |TRUE| if {expr} is locked
313isnan({expr}) Number |TRUE| if {expr} is NaN
314items({dict}) List key-value pairs in {dict}
315job_getchannel({job}) Channel get the channel handle for {job}
316job_info([{job}]) Dict get information about {job}
317job_setoptions({job}, {options}) none set options for {job}
318job_start({command} [, {options}])
319 Job start a job
320job_status({job}) String get the status of {job}
321job_stop({job} [, {how}]) Number stop {job}
322join({list} [, {sep}]) String join {list} items into one String
323js_decode({string}) any decode JS style JSON
324js_encode({expr}) String encode JS style JSON
325json_decode({string}) any decode JSON
326json_encode({expr}) String encode JSON
327keys({dict}) List keys in {dict}
328len({expr}) Number the length of {expr}
329libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
330libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
331line({expr} [, {winid}]) Number line nr of cursor, last line or mark
332line2byte({lnum}) Number byte count of line {lnum}
333lispindent({lnum}) Number Lisp indent for line {lnum}
334list2blob({list}) Blob turn {list} of numbers into a Blob
335list2str({list} [, {utf8}]) String turn {list} of numbers into a String
336listener_add({callback} [, {buf}])
337 Number add a callback to listen to changes
338listener_flush([{buf}]) none invoke listener callbacks
339listener_remove({id}) none remove a listener callback
340localtime() Number current time
341log({expr}) Float natural logarithm (base e) of {expr}
342log10({expr}) Float logarithm of Float {expr} to base 10
343luaeval({expr} [, {expr}]) any evaluate |Lua| expression
344map({expr1}, {expr2}) List/Dict/Blob/String
345 change each item in {expr1} to {expr2}
346maparg({name} [, {mode} [, {abbr} [, {dict}]]])
347 String or Dict
348 rhs of mapping {name} in mode {mode}
349mapcheck({name} [, {mode} [, {abbr}]])
350 String check for mappings matching {name}
Ernie Rael09661202022-04-25 14:40:44 +0100351maplist([{abbr}]) List list of all mappings, a dict for each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000352mapnew({expr1}, {expr2}) List/Dict/Blob/String
353 like |map()| but creates a new List or
354 Dictionary
355mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
356match({expr}, {pat} [, {start} [, {count}]])
357 Number position where {pat} matches in {expr}
358matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
359 Number highlight {pattern} with {group}
360matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
361 Number highlight positions with {group}
362matcharg({nr}) List arguments of |:match|
363matchdelete({id} [, {win}]) Number delete match identified by {id}
364matchend({expr}, {pat} [, {start} [, {count}]])
365 Number position where {pat} ends in {expr}
366matchfuzzy({list}, {str} [, {dict}])
367 List fuzzy match {str} in {list}
368matchfuzzypos({list}, {str} [, {dict}])
369 List fuzzy match {str} in {list}
370matchlist({expr}, {pat} [, {start} [, {count}]])
371 List match and submatches of {pat} in {expr}
372matchstr({expr}, {pat} [, {start} [, {count}]])
373 String {count}'th match of {pat} in {expr}
374matchstrpos({expr}, {pat} [, {start} [, {count}]])
375 List {count}'th match of {pat} in {expr}
376max({expr}) Number maximum value of items in {expr}
377menu_info({name} [, {mode}]) Dict get menu item information
378min({expr}) Number minimum value of items in {expr}
379mkdir({name} [, {path} [, {prot}]])
380 Number create directory {name}
381mode([expr]) String current editing mode
382mzeval({expr}) any evaluate |MzScheme| expression
383nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
384nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
385or({expr}, {expr}) Number bitwise OR
386pathshorten({expr} [, {len}]) String shorten directory names in a path
387perleval({expr}) any evaluate |Perl| expression
388popup_atcursor({what}, {options}) Number create popup window near the cursor
389popup_beval({what}, {options}) Number create popup window for 'ballooneval'
390popup_clear() none close all popup windows
391popup_close({id} [, {result}]) none close popup window {id}
392popup_create({what}, {options}) Number create a popup window
393popup_dialog({what}, {options}) Number create a popup window used as a dialog
394popup_filter_menu({id}, {key}) Number filter for a menu popup window
395popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
396popup_findinfo() Number get window ID of info popup window
397popup_findpreview() Number get window ID of preview popup window
398popup_getoptions({id}) Dict get options of popup window {id}
399popup_getpos({id}) Dict get position of popup window {id}
400popup_hide({id}) none hide popup menu {id}
401popup_list() List get a list of window IDs of all popups
402popup_locate({row}, {col}) Number get window ID of popup at position
403popup_menu({what}, {options}) Number create a popup window used as a menu
404popup_move({id}, {options}) none set position of popup window {id}
405popup_notification({what}, {options})
406 Number create a notification popup window
407popup_setoptions({id}, {options})
408 none set options for popup window {id}
409popup_settext({id}, {text}) none set the text of popup window {id}
410popup_show({id}) none unhide popup window {id}
411pow({x}, {y}) Float {x} to the power of {y}
412prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
413printf({fmt}, {expr1}...) String format text
414prompt_getprompt({buf}) String get prompt text
415prompt_setcallback({buf}, {expr}) none set prompt callback function
416prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
417prompt_setprompt({buf}, {text}) none set prompt text
418prop_add({lnum}, {col}, {props}) none add one text property
419prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
420 none add multiple text properties
421prop_clear({lnum} [, {lnum-end} [, {props}]])
422 none remove all text properties
423prop_find({props} [, {direction}])
424 Dict search for a text property
425prop_list({lnum} [, {props}]) List text properties in {lnum}
426prop_remove({props} [, {lnum} [, {lnum-end}]])
427 Number remove a text property
428prop_type_add({name}, {props}) none define a new property type
429prop_type_change({name}, {props})
430 none change an existing property type
431prop_type_delete({name} [, {props}])
432 none delete a property type
433prop_type_get({name} [, {props}])
434 Dict get property type values
435prop_type_list([{props}]) List get list of property types
436pum_getpos() Dict position and size of pum if visible
437pumvisible() Number whether popup menu is visible
438py3eval({expr}) any evaluate |python3| expression
439pyeval({expr}) any evaluate |Python| expression
440pyxeval({expr}) any evaluate |python_x| expression
441rand([{expr}]) Number get pseudo-random number
442range({expr} [, {max} [, {stride}]])
443 List items from {expr} to {max}
444readblob({fname}) Blob read a |Blob| from {fname}
445readdir({dir} [, {expr} [, {dict}]])
446 List file names in {dir} selected by {expr}
447readdirex({dir} [, {expr} [, {dict}]])
448 List file info in {dir} selected by {expr}
449readfile({fname} [, {type} [, {max}]])
450 List get list of lines from file {fname}
451reduce({object}, {func} [, {initial}])
452 any reduce {object} using {func}
453reg_executing() String get the executing register name
454reg_recording() String get the recording register name
455reltime([{start} [, {end}]]) List get time value
456reltimefloat({time}) Float turn the time value into a Float
457reltimestr({time}) String turn time value into a String
458remote_expr({server}, {string} [, {idvar} [, {timeout}]])
459 String send expression
460remote_foreground({server}) Number bring Vim server to the foreground
461remote_peek({serverid} [, {retvar}])
462 Number check for reply string
463remote_read({serverid} [, {timeout}])
464 String read reply string
465remote_send({server}, {string} [, {idvar}])
466 String send key sequence
467remote_startserver({name}) none become server {name}
468remove({list}, {idx} [, {end}]) any/List
469 remove items {idx}-{end} from {list}
470remove({blob}, {idx} [, {end}]) Number/Blob
471 remove bytes {idx}-{end} from {blob}
472remove({dict}, {key}) any remove entry {key} from {dict}
473rename({from}, {to}) Number rename (move) file from {from} to {to}
Bakudankun375141e2022-09-09 18:46:47 +0100474repeat({expr}, {count}) List/Blob/String
475 repeat {expr} {count} times
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000476resolve({filename}) String get filename a shortcut points to
477reverse({list}) List reverse {list} in-place
478round({expr}) Float round off {expr}
479rubyeval({expr}) any evaluate |Ruby| expression
480screenattr({row}, {col}) Number attribute at screen position
481screenchar({row}, {col}) Number character at screen position
482screenchars({row}, {col}) List List of characters at screen position
483screencol() Number current cursor column
484screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
485screenrow() Number current cursor row
486screenstring({row}, {col}) String characters at screen position
487search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
488 Number search for {pattern}
489searchcount([{options}]) Dict get or update search stats
490searchdecl({name} [, {global} [, {thisblock}]])
491 Number search for variable declaration
492searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
493 Number search for other end of start/end pair
494searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
495 List search for other end of start/end pair
496searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
497 List search for {pattern}
498server2client({clientid}, {string})
499 Number send reply string
500serverlist() String get a list of available servers
501setbufline({expr}, {lnum}, {text})
502 Number set line {lnum} to {text} in buffer
503 {expr}
504setbufvar({buf}, {varname}, {val})
505 none set {varname} in buffer {buf} to {val}
506setcellwidths({list}) none set character cell width overrides
507setcharpos({expr}, {list}) Number set the {expr} position to {list}
508setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100509setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000510setcmdpos({pos}) Number set cursor position in command-line
511setcursorcharpos({list}) Number move cursor to position in {list}
512setenv({name}, {val}) none set environment variable
513setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
514setline({lnum}, {line}) Number set line {lnum} to {line}
515setloclist({nr}, {list} [, {action}])
516 Number modify location list using {list}
517setloclist({nr}, {list}, {action}, {what})
518 Number modify specific location list props
519setmatches({list} [, {win}]) Number restore a list of matches
520setpos({expr}, {list}) Number set the {expr} position to {list}
521setqflist({list} [, {action}]) Number modify quickfix list using {list}
522setqflist({list}, {action}, {what})
523 Number modify specific quickfix list props
524setreg({n}, {v} [, {opt}]) Number set register to value and type
525settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
526settabwinvar({tabnr}, {winnr}, {varname}, {val})
527 none set {varname} in window {winnr} in tab
528 page {tabnr} to {val}
529settagstack({nr}, {dict} [, {action}])
530 Number modify tag stack using {dict}
531setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
532sha256({string}) String SHA256 checksum of {string}
533shellescape({string} [, {special}])
534 String escape {string} for use as shell
535 command argument
536shiftwidth([{col}]) Number effective value of 'shiftwidth'
537sign_define({name} [, {dict}]) Number define or update a sign
538sign_define({list}) List define or update a list of signs
539sign_getdefined([{name}]) List get a list of defined signs
540sign_getplaced([{buf} [, {dict}]])
541 List get a list of placed signs
542sign_jump({id}, {group}, {buf})
543 Number jump to a sign
544sign_place({id}, {group}, {name}, {buf} [, {dict}])
545 Number place a sign
546sign_placelist({list}) List place a list of signs
547sign_undefine([{name}]) Number undefine a sign
548sign_undefine({list}) List undefine a list of signs
549sign_unplace({group} [, {dict}])
550 Number unplace a sign
551sign_unplacelist({list}) List unplace a list of signs
552simplify({filename}) String simplify filename as much as possible
553sin({expr}) Float sine of {expr}
554sinh({expr}) Float hyperbolic sine of {expr}
555slice({expr}, {start} [, {end}]) String, List or Blob
556 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000557sort({list} [, {how} [, {dict}]])
558 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000559sound_clear() none stop playing all sounds
560sound_playevent({name} [, {callback}])
561 Number play an event sound
562sound_playfile({path} [, {callback}])
563 Number play sound file {path}
564sound_stop({id}) none stop playing sound {id}
565soundfold({word}) String sound-fold {word}
566spellbadword() String badly spelled word at cursor
567spellsuggest({word} [, {max} [, {capital}]])
568 List spelling suggestions
569split({expr} [, {pat} [, {keepempty}]])
570 List make |List| from {pat} separated {expr}
571sqrt({expr}) Float square root of {expr}
572srand([{expr}]) List get seed for |rand()|
573state([{what}]) String current state of Vim
574str2float({expr} [, {quoted}]) Float convert String to Float
575str2list({expr} [, {utf8}]) List convert each character of {expr} to
576 ASCII/UTF-8 value
577str2nr({expr} [, {base} [, {quoted}]])
578 Number convert String to Number
579strcharlen({expr}) Number character length of the String {expr}
580strcharpart({str}, {start} [, {len} [, {skipcc}]])
581 String {len} characters of {str} at
582 character {start}
583strchars({expr} [, {skipcc}]) Number character count of the String {expr}
584strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
585strftime({format} [, {time}]) String format time with a specified format
586strgetchar({str}, {index}) Number get char {index} from {str}
587stridx({haystack}, {needle} [, {start}])
588 Number index of {needle} in {haystack}
589string({expr}) String String representation of {expr} value
590strlen({expr}) Number length of the String {expr}
591strpart({str}, {start} [, {len} [, {chars}]])
592 String {len} bytes/chars of {str} at
593 byte {start}
594strptime({format}, {timestring})
595 Number Convert {timestring} to unix timestamp
596strridx({haystack}, {needle} [, {start}])
597 Number last index of {needle} in {haystack}
598strtrans({expr}) String translate string to make it printable
599strwidth({expr}) Number display cell length of the String {expr}
600submatch({nr} [, {list}]) String or List
601 specific match in ":s" or substitute()
602substitute({expr}, {pat}, {sub}, {flags})
603 String all {pat} in {expr} replaced with {sub}
604swapinfo({fname}) Dict information about swap file {fname}
605swapname({buf}) String swap file of buffer {buf}
606synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
607synIDattr({synID}, {what} [, {mode}])
608 String attribute {what} of syntax ID {synID}
609synIDtrans({synID}) Number translated syntax ID of {synID}
610synconcealed({lnum}, {col}) List info about concealing
611synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
612system({expr} [, {input}]) String output of shell command/filter {expr}
613systemlist({expr} [, {input}]) List output of shell command/filter {expr}
614tabpagebuflist([{arg}]) List list of buffer numbers in tab page
615tabpagenr([{arg}]) Number number of current or last tab page
616tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
617tagfiles() List tags files used
618taglist({expr} [, {filename}]) List list of tags matching {expr}
619tan({expr}) Float tangent of {expr}
620tanh({expr}) Float hyperbolic tangent of {expr}
621tempname() String name for a temporary file
622term_dumpdiff({filename}, {filename} [, {options}])
623 Number display difference between two dumps
624term_dumpload({filename} [, {options}])
625 Number displaying a screen dump
626term_dumpwrite({buf}, {filename} [, {options}])
627 none dump terminal window contents
628term_getaltscreen({buf}) Number get the alternate screen flag
629term_getansicolors({buf}) List get ANSI palette in GUI color mode
630term_getattr({attr}, {what}) Number get the value of attribute {what}
631term_getcursor({buf}) List get the cursor position of a terminal
632term_getjob({buf}) Job get the job associated with a terminal
633term_getline({buf}, {row}) String get a line of text from a terminal
634term_getscrolled({buf}) Number get the scroll count of a terminal
635term_getsize({buf}) List get the size of a terminal
636term_getstatus({buf}) String get the status of a terminal
637term_gettitle({buf}) String get the title of a terminal
638term_gettty({buf}, [{input}]) String get the tty name of a terminal
639term_list() List get the list of terminal buffers
640term_scrape({buf}, {row}) List get row of a terminal screen
641term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
642term_setansicolors({buf}, {colors})
643 none set ANSI palette in GUI color mode
644term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
645term_setkill({buf}, {how}) none set signal to stop job in terminal
646term_setrestore({buf}, {command}) none set command to restore terminal
647term_setsize({buf}, {rows}, {cols})
648 none set the size of a terminal
649term_start({cmd} [, {options}]) Number open a terminal window and run a job
650term_wait({buf} [, {time}]) Number wait for screen to be updated
651terminalprops() Dict properties of the terminal
652test_alloc_fail({id}, {countdown}, {repeat})
653 none make memory allocation fail
654test_autochdir() none enable 'autochdir' during startup
655test_feedinput({string}) none add key sequence to input buffer
656test_garbagecollect_now() none free memory right now for testing
657test_garbagecollect_soon() none free memory soon for testing
658test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000659test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000660test_ignore_error({expr}) none ignore a specific error
661test_null_blob() Blob null value for testing
662test_null_channel() Channel null value for testing
663test_null_dict() Dict null value for testing
664test_null_function() Funcref null value for testing
665test_null_job() Job null value for testing
666test_null_list() List null value for testing
667test_null_partial() Funcref null value for testing
668test_null_string() String null value for testing
669test_option_not_set({name}) none reset flag indicating option was set
670test_override({expr}, {val}) none test with Vim internal overrides
671test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000672test_setmouse({row}, {col}) none set the mouse position for testing
673test_settime({expr}) none set current time for testing
674test_srand_seed([seed]) none set seed for testing srand()
675test_unknown() any unknown value for testing
676test_void() any void value for testing
677timer_info([{id}]) List information about timers
678timer_pause({id}, {pause}) none pause or unpause a timer
679timer_start({time}, {callback} [, {options}])
680 Number create a timer
681timer_stop({timer}) none stop a timer
682timer_stopall() none stop all timers
683tolower({expr}) String the String {expr} switched to lowercase
684toupper({expr}) String the String {expr} switched to uppercase
685tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
686 to chars in {tostr}
687trim({text} [, {mask} [, {dir}]])
688 String trim characters in {mask} from {text}
689trunc({expr}) Float truncate Float {expr}
690type({expr}) Number type of value {expr}
691typename({expr}) String representation of the type of {expr}
692undofile({name}) String undo file name for {name}
693undotree() List undo file tree
694uniq({list} [, {func} [, {dict}]])
695 List remove adjacent duplicates from a list
696values({dict}) List values in {dict}
LemonBoy0f7a3e12022-05-26 12:10:37 +0100697virtcol({expr} [, {list}]) Number or List
698 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100699virtcol2col({winid}, {lnum}, {col})
700 Number byte index of a character on screen
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000701visualmode([expr]) String last visual mode used
702wildmenumode() Number whether 'wildmenu' mode is active
703win_execute({id}, {command} [, {silent}])
704 String execute {command} in window {id}
705win_findbuf({bufnr}) List find windows containing {bufnr}
706win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
707win_gettype([{nr}]) String type of window {nr}
708win_gotoid({expr}) Number go to window with ID {expr}
709win_id2tabwin({expr}) List get tab and window nr from window ID
710win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000711win_move_separator({nr}) Number move window vertical separator
712win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000713win_screenpos({nr}) List get screen position of window {nr}
714win_splitmove({nr}, {target} [, {options}])
715 Number move window {nr} to split of {target}
716winbufnr({nr}) Number buffer number of window {nr}
717wincol() Number window column of the cursor
718windowsversion() String MS-Windows OS version
719winheight({nr}) Number height of window {nr}
720winlayout([{tabnr}]) List layout of windows in tab {tabnr}
721winline() Number window line of the cursor
722winnr([{expr}]) Number number of current window
723winrestcmd() String returns command to restore window sizes
724winrestview({dict}) none restore view of current window
725winsaveview() Dict save view of current window
726winwidth({nr}) Number width of window {nr}
727wordcount() Dict get byte/char/word statistics
728writefile({object}, {fname} [, {flags}])
729 Number write |Blob| or |List| of lines to file
730xor({expr}, {expr}) Number bitwise XOR
731
732==============================================================================
7332. Details *builtin-function-details*
734
735Not all functions are here, some have been moved to a help file covering the
736specific functionality.
737
738abs({expr}) *abs()*
739 Return the absolute value of {expr}. When {expr} evaluates to
740 a |Float| abs() returns a |Float|. When {expr} can be
741 converted to a |Number| abs() returns a |Number|. Otherwise
742 abs() gives an error message and returns -1.
743 Examples: >
744 echo abs(1.456)
745< 1.456 >
746 echo abs(-5.456)
747< 5.456 >
748 echo abs(-4)
749< 4
750
751 Can also be used as a |method|: >
752 Compute()->abs()
753
754< {only available when compiled with the |+float| feature}
755
756
757acos({expr}) *acos()*
758 Return the arc cosine of {expr} measured in radians, as a
759 |Float| in the range of [0, pi].
760 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100761 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000762 Examples: >
763 :echo acos(0)
764< 1.570796 >
765 :echo acos(-0.5)
766< 2.094395
767
768 Can also be used as a |method|: >
769 Compute()->acos()
770
771< {only available when compiled with the |+float| feature}
772
773
774add({object}, {expr}) *add()*
775 Append the item {expr} to |List| or |Blob| {object}. Returns
776 the resulting |List| or |Blob|. Examples: >
777 :let alist = add([1, 2, 3], item)
778 :call add(mylist, "woodstock")
779< Note that when {expr} is a |List| it is appended as a single
780 item. Use |extend()| to concatenate |Lists|.
781 When {object} is a |Blob| then {expr} must be a number.
782 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100783 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000784
785 Can also be used as a |method|: >
786 mylist->add(val1)->add(val2)
787
788
789and({expr}, {expr}) *and()*
790 Bitwise AND on the two arguments. The arguments are converted
791 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100792 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000793 Example: >
794 :let flag = and(bits, 0x80)
795< Can also be used as a |method|: >
796 :let flag = bits->and(0x80)
797
798
799append({lnum}, {text}) *append()*
800 When {text} is a |List|: Append each item of the |List| as a
801 text line below line {lnum} in the current buffer.
802 Otherwise append {text} as one text line below line {lnum} in
803 the current buffer.
804 Any type of item is accepted and converted to a String.
805 {lnum} can be zero to insert a line before the first one.
806 {lnum} is used like with |getline()|.
807 Returns 1 for failure ({lnum} out of range or out of memory),
808 0 for success. In |Vim9| script an invalid argument or
809 negative number results in an error. Example: >
810 :let failed = append(line('$'), "# THE END")
811 :let failed = append(0, ["Chapter 1", "the beginning"])
812
813< Can also be used as a |method| after a List, the base is
814 passed as the second argument: >
815 mylist->append(lnum)
816
817
818appendbufline({buf}, {lnum}, {text}) *appendbufline()*
819 Like |append()| but append the text in buffer {buf}.
820
821 This function works only for loaded buffers. First call
822 |bufload()| if needed.
823
824 For the use of {buf}, see |bufname()|.
825
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000826 {lnum} is the line number to append below. Note that using
827 |line()| would use the current buffer, not the one appending
828 to. Use "$" to append at the end of the buffer. Other string
829 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000830
831 On success 0 is returned, on failure 1 is returned.
832 In |Vim9| script an error is given for an invalid {lnum}.
833
834 If {buf} is not a valid buffer or {lnum} is not valid, an
835 error message is given. Example: >
836 :let failed = appendbufline(13, 0, "# THE START")
837<
838 Can also be used as a |method| after a List, the base is
839 passed as the second argument: >
840 mylist->appendbufline(buf, lnum)
841
842
843argc([{winid}]) *argc()*
844 The result is the number of files in the argument list. See
845 |arglist|.
846 If {winid} is not supplied, the argument list of the current
847 window is used.
848 If {winid} is -1, the global argument list is used.
849 Otherwise {winid} specifies the window of which the argument
850 list is used: either the window number or the window ID.
851 Returns -1 if the {winid} argument is invalid.
852
853 *argidx()*
854argidx() The result is the current index in the argument list. 0 is
855 the first file. argc() - 1 is the last one. See |arglist|.
856
857 *arglistid()*
858arglistid([{winnr} [, {tabnr}]])
859 Return the argument list ID. This is a number which
860 identifies the argument list being used. Zero is used for the
861 global argument list. See |arglist|.
862 Returns -1 if the arguments are invalid.
863
864 Without arguments use the current window.
865 With {winnr} only use this window in the current tab page.
866 With {winnr} and {tabnr} use the window in the specified tab
867 page.
868 {winnr} can be the window number or the |window-ID|.
869
870 *argv()*
871argv([{nr} [, {winid}]])
872 The result is the {nr}th file in the argument list. See
873 |arglist|. "argv(0)" is the first one. Example: >
874 :let i = 0
875 :while i < argc()
876 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000877 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000878 : let i = i + 1
879 :endwhile
880< Without the {nr} argument, or when {nr} is -1, a |List| with
881 the whole |arglist| is returned.
882
883 The {winid} argument specifies the window ID, see |argc()|.
884 For the Vim command line arguments see |v:argv|.
885
Bram Moolenaar016188f2022-06-06 20:52:59 +0100886 Returns an empty string if {nr}th argument is not present in
887 the argument list. Returns an empty List if the {winid}
888 argument is invalid.
889
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000890asin({expr}) *asin()*
891 Return the arc sine of {expr} measured in radians, as a |Float|
892 in the range of [-pi/2, pi/2].
893 {expr} must evaluate to a |Float| or a |Number| in the range
894 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100895 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
896 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000897 Examples: >
898 :echo asin(0.8)
899< 0.927295 >
900 :echo asin(-0.5)
901< -0.523599
902
903 Can also be used as a |method|: >
904 Compute()->asin()
905<
906 {only available when compiled with the |+float| feature}
907
908
909assert_ functions are documented here: |assert-functions-details|
910
911
912
913atan({expr}) *atan()*
914 Return the principal value of the arc tangent of {expr}, in
915 the range [-pi/2, +pi/2] radians, as a |Float|.
916 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100917 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000918 Examples: >
919 :echo atan(100)
920< 1.560797 >
921 :echo atan(-4.01)
922< -1.326405
923
924 Can also be used as a |method|: >
925 Compute()->atan()
926<
927 {only available when compiled with the |+float| feature}
928
929
930atan2({expr1}, {expr2}) *atan2()*
931 Return the arc tangent of {expr1} / {expr2}, measured in
932 radians, as a |Float| in the range [-pi, pi].
933 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100934 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
935 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000936 Examples: >
937 :echo atan2(-1, 1)
938< -0.785398 >
939 :echo atan2(1, -1)
940< 2.356194
941
942 Can also be used as a |method|: >
943 Compute()->atan2(1)
944<
945 {only available when compiled with the |+float| feature}
946
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100947
948autocmd_add({acmds}) *autocmd_add()*
949 Adds a List of autocmds and autocmd groups.
950
951 The {acmds} argument is a List where each item is a Dict with
952 the following optional items:
953 bufnr buffer number to add a buffer-local autocmd.
954 If this item is specified, then the "pattern"
955 item is ignored.
956 cmd Ex command to execute for this autocmd event
957 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100958 This can be either a String with a single
959 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100960 group autocmd group name. Refer to |autocmd-groups|.
961 If this group doesn't exist then it is
962 created. If not specified or empty, then the
963 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100964 nested boolean flag, set to v:true to add a nested
965 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100966 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100967 which executes only once. Refer to
968 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100969 pattern autocmd pattern string. Refer to
970 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100971 present, then this item is ignored. This can
972 be a String with a single pattern or a List of
973 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100974 replace boolean flag, set to v:true to remove all the
975 commands associated with the specified autocmd
976 event and group and add the {cmd}. This is
977 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +0100978 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100979
980 Returns v:true on success and v:false on failure.
981 Examples: >
982 " Create a buffer-local autocmd for buffer 5
983 let acmd = {}
984 let acmd.group = 'MyGroup'
985 let acmd.event = 'BufEnter'
986 let acmd.bufnr = 5
987 let acmd.cmd = 'call BufEnterFunc()'
988 call autocmd_add([acmd])
989
990 Can also be used as a |method|: >
991 GetAutocmdList()->autocmd_add()
992<
993autocmd_delete({acmds}) *autocmd_delete()*
994 Deletes a List of autocmds and autocmd groups.
995
996 The {acmds} argument is a List where each item is a Dict with
997 the following optional items:
998 bufnr buffer number to delete a buffer-local autocmd.
999 If this item is specified, then the "pattern"
1000 item is ignored.
1001 cmd Ex command for this autocmd event
1002 event autocmd event name. Refer to |autocmd-events|.
1003 If '*' then all the autocmd events in this
1004 group are deleted.
1005 group autocmd group name. Refer to |autocmd-groups|.
1006 If not specified or empty, then the default
1007 group is used.
1008 nested set to v:true for a nested autocmd.
1009 Refer to |autocmd-nested|.
1010 once set to v:true for an autocmd which executes
1011 only once. Refer to |autocmd-once|.
1012 pattern autocmd pattern string. Refer to
1013 |autocmd-patterns|. If "bufnr" item is
1014 present, then this item is ignored.
1015
1016 If only {group} is specified in a {acmds} entry and {event},
1017 {pattern} and {cmd} are not specified, then that autocmd group
1018 is deleted.
1019
Bram Moolenaar016188f2022-06-06 20:52:59 +01001020 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001021 Examples: >
1022 " :autocmd! BufLeave *.vim
1023 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1024 call autocmd_delete([acmd]})
1025 " :autocmd! MyGroup1 BufLeave
1026 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1027 call autocmd_delete([acmd])
1028 " :autocmd! MyGroup2 BufEnter *.c
1029 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1030 \ pattern: '*.c'}
1031 " :autocmd! MyGroup2 * *.c
1032 let acmd = #{group: 'MyGroup2', event: '*',
1033 \ pattern: '*.c'}
1034 call autocmd_delete([acmd])
1035 " :autocmd! MyGroup3
1036 let acmd = #{group: 'MyGroup3'}
1037 call autocmd_delete([acmd])
1038<
1039 Can also be used as a |method|: >
1040 GetAutocmdList()->autocmd_delete()
1041
1042autocmd_get([{opts}]) *autocmd_get()*
1043 Returns a |List| of autocmds. If {opts} is not supplied, then
1044 returns the autocmds for all the events in all the groups.
1045
1046 The optional {opts} Dict argument supports the following
1047 items:
1048 group Autocmd group name. If specified, returns only
1049 the autocmds defined in this group. If the
1050 specified group doesn't exist, results in an
1051 error message. If set to an empty string,
1052 then the default autocmd group is used.
1053 event Autocmd event name. If specified, returns only
1054 the autocmds defined for this event. If set
1055 to "*", then returns autocmds for all the
1056 events. If the specified event doesn't exist,
1057 results in an error message.
1058 pattern Autocmd pattern. If specified, returns only
1059 the autocmds defined for this pattern.
1060 A combination of the above three times can be supplied in
1061 {opts}.
1062
1063 Each Dict in the returned List contains the following items:
1064 bufnr For buffer-local autocmds, buffer number where
1065 the autocmd is defined.
1066 cmd Command executed for this autocmd.
1067 event Autocmd event name.
1068 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001069 nested Boolean flag, set to v:true for a nested
1070 autocmd. See |autocmd-nested|.
1071 once Boolean flag, set to v:true, if the autocmd
1072 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001073 pattern Autocmd pattern. For a buffer-local
1074 autocmd, this will be of the form "<buffer=n>".
1075 If there are multiple commands for an autocmd event in a
1076 group, then separate items are returned for each command.
1077
Bram Moolenaar016188f2022-06-06 20:52:59 +01001078 Returns an empty List if an autocmd with the specified group
1079 or event or pattern is not found.
1080
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001081 Examples: >
1082 " :autocmd MyGroup
1083 echo autocmd_get(#{group: 'Mygroup'})
1084 " :autocmd G BufUnload
1085 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1086 " :autocmd G * *.ts
1087 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1088 echo autocmd_get(acmd)
1089 " :autocmd Syntax
1090 echo autocmd_get(#{event: 'Syntax'})
1091 " :autocmd G BufEnter *.ts
1092 let acmd = #{group: 'G', event: 'BufEnter',
1093 \ pattern: '*.ts'}
1094 echo autocmd_get(acmd)
1095<
1096 Can also be used as a |method|: >
1097 Getopts()->autocmd_get()
1098<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001099balloon_gettext() *balloon_gettext()*
1100 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001101 not used for the List. Returns an empty string if balloon
1102 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001103
1104balloon_show({expr}) *balloon_show()*
1105 Show {expr} inside the balloon. For the GUI {expr} is used as
1106 a string. For a terminal {expr} can be a list, which contains
1107 the lines of the balloon. If {expr} is not a list it will be
1108 split with |balloon_split()|.
1109 If {expr} is an empty string any existing balloon is removed.
1110
1111 Example: >
1112 func GetBalloonContent()
1113 " ... initiate getting the content
1114 return ''
1115 endfunc
1116 set balloonexpr=GetBalloonContent()
1117
1118 func BalloonCallback(result)
1119 call balloon_show(a:result)
1120 endfunc
1121< Can also be used as a |method|: >
1122 GetText()->balloon_show()
1123<
1124 The intended use is that fetching the content of the balloon
1125 is initiated from 'balloonexpr'. It will invoke an
1126 asynchronous method, in which a callback invokes
1127 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001128 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001129
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001130 When showing a balloon is not possible then nothing happens,
1131 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001132 {only available when compiled with the |+balloon_eval| or
1133 |+balloon_eval_term| feature}
1134
1135balloon_split({msg}) *balloon_split()*
1136 Split String {msg} into lines to be displayed in a balloon.
1137 The splits are made for the current window size and optimize
1138 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001139 Returns a |List| with the split lines. Returns an empty List
1140 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001141 Can also be used as a |method|: >
1142 GetText()->balloon_split()->balloon_show()
1143
1144< {only available when compiled with the |+balloon_eval_term|
1145 feature}
1146
1147blob2list({blob}) *blob2list()*
1148 Return a List containing the number value of each byte in Blob
1149 {blob}. Examples: >
1150 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1151 blob2list(0z) returns []
1152< Returns an empty List on error. |list2blob()| does the
1153 opposite.
1154
1155 Can also be used as a |method|: >
1156 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001157<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001158 *browse()*
1159browse({save}, {title}, {initdir}, {default})
1160 Put up a file requester. This only works when "has("browse")"
1161 returns |TRUE| (only in some GUI versions).
1162 The input fields are:
1163 {save} when |TRUE|, select file to write
1164 {title} title for the requester
1165 {initdir} directory to start browsing in
1166 {default} default file name
1167 An empty string is returned when the "Cancel" button is hit,
1168 something went wrong, or browsing is not possible.
1169
1170 *browsedir()*
1171browsedir({title}, {initdir})
1172 Put up a directory requester. This only works when
1173 "has("browse")" returns |TRUE| (only in some GUI versions).
1174 On systems where a directory browser is not supported a file
1175 browser is used. In that case: select a file in the directory
1176 to be used.
1177 The input fields are:
1178 {title} title for the requester
1179 {initdir} directory to start browsing in
1180 When the "Cancel" button is hit, something went wrong, or
1181 browsing is not possible, an empty string is returned.
1182
1183bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001184 Add a buffer to the buffer list with name {name} (must be a
1185 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001186 If a buffer for file {name} already exists, return that buffer
1187 number. Otherwise return the buffer number of the newly
1188 created buffer. When {name} is an empty string then a new
1189 buffer is always created.
1190 The buffer will not have 'buflisted' set and not be loaded
1191 yet. To add some text to the buffer use this: >
1192 let bufnr = bufadd('someName')
1193 call bufload(bufnr)
1194 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001195< Returns 0 on error.
1196 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001197 let bufnr = 'somename'->bufadd()
1198
1199bufexists({buf}) *bufexists()*
1200 The result is a Number, which is |TRUE| if a buffer called
1201 {buf} exists.
1202 If the {buf} argument is a number, buffer numbers are used.
1203 Number zero is the alternate buffer for the current window.
1204
1205 If the {buf} argument is a string it must match a buffer name
1206 exactly. The name can be:
1207 - Relative to the current directory.
1208 - A full path.
1209 - The name of a buffer with 'buftype' set to "nofile".
1210 - A URL name.
1211 Unlisted buffers will be found.
1212 Note that help files are listed by their short name in the
1213 output of |:buffers|, but bufexists() requires using their
1214 long name to be able to find them.
1215 bufexists() may report a buffer exists, but to use the name
1216 with a |:buffer| command you may need to use |expand()|. Esp
1217 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1218 Use "bufexists(0)" to test for the existence of an alternate
1219 file name.
1220
1221 Can also be used as a |method|: >
1222 let exists = 'somename'->bufexists()
1223<
1224 Obsolete name: buffer_exists(). *buffer_exists()*
1225
1226buflisted({buf}) *buflisted()*
1227 The result is a Number, which is |TRUE| if a buffer called
1228 {buf} exists and is listed (has the 'buflisted' option set).
1229 The {buf} argument is used like with |bufexists()|.
1230
1231 Can also be used as a |method|: >
1232 let listed = 'somename'->buflisted()
1233
1234bufload({buf}) *bufload()*
1235 Ensure the buffer {buf} is loaded. When the buffer name
1236 refers to an existing file then the file is read. Otherwise
1237 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001238 then there is no change. If the buffer is not related to a
1239 file the no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001240 If there is an existing swap file for the file of the buffer,
1241 there will be no dialog, the buffer will be loaded anyway.
1242 The {buf} argument is used like with |bufexists()|.
1243
1244 Can also be used as a |method|: >
1245 eval 'somename'->bufload()
1246
1247bufloaded({buf}) *bufloaded()*
1248 The result is a Number, which is |TRUE| if a buffer called
1249 {buf} exists and is loaded (shown in a window or hidden).
1250 The {buf} argument is used like with |bufexists()|.
1251
1252 Can also be used as a |method|: >
1253 let loaded = 'somename'->bufloaded()
1254
1255bufname([{buf}]) *bufname()*
1256 The result is the name of a buffer. Mostly as it is displayed
1257 by the `:ls` command, but not using special names such as
1258 "[No Name]".
1259 If {buf} is omitted the current buffer is used.
1260 If {buf} is a Number, that buffer number's name is given.
1261 Number zero is the alternate buffer for the current window.
1262 If {buf} is a String, it is used as a |file-pattern| to match
1263 with the buffer names. This is always done like 'magic' is
1264 set and 'cpoptions' is empty. When there is more than one
1265 match an empty string is returned.
1266 "" or "%" can be used for the current buffer, "#" for the
1267 alternate buffer.
1268 A full match is preferred, otherwise a match at the start, end
1269 or middle of the buffer name is accepted. If you only want a
1270 full match then put "^" at the start and "$" at the end of the
1271 pattern.
1272 Listed buffers are found first. If there is a single match
1273 with a listed buffer, that one is returned. Next unlisted
1274 buffers are searched for.
1275 If the {buf} is a String, but you want to use it as a buffer
1276 number, force it to be a Number by adding zero to it: >
1277 :echo bufname("3" + 0)
1278< Can also be used as a |method|: >
1279 echo bufnr->bufname()
1280
1281< If the buffer doesn't exist, or doesn't have a name, an empty
1282 string is returned. >
1283 bufname("#") alternate buffer name
1284 bufname(3) name of buffer 3
1285 bufname("%") name of current buffer
1286 bufname("file2") name of buffer where "file2" matches.
1287< *buffer_name()*
1288 Obsolete name: buffer_name().
1289
1290 *bufnr()*
1291bufnr([{buf} [, {create}]])
1292 The result is the number of a buffer, as it is displayed by
1293 the `:ls` command. For the use of {buf}, see |bufname()|
1294 above.
1295
1296 If the buffer doesn't exist, -1 is returned. Or, if the
1297 {create} argument is present and TRUE, a new, unlisted,
1298 buffer is created and its number is returned. Example: >
1299 let newbuf = bufnr('Scratch001', 1)
1300< Using an empty name uses the current buffer. To create a new
1301 buffer with an empty name use |bufadd()|.
1302
1303 bufnr("$") is the last buffer: >
1304 :let last_buffer = bufnr("$")
1305< The result is a Number, which is the highest buffer number
1306 of existing buffers. Note that not all buffers with a smaller
1307 number necessarily exist, because ":bwipeout" may have removed
1308 them. Use bufexists() to test for the existence of a buffer.
1309
1310 Can also be used as a |method|: >
1311 echo bufref->bufnr()
1312<
1313 Obsolete name: buffer_number(). *buffer_number()*
1314 *last_buffer_nr()*
1315 Obsolete name for bufnr("$"): last_buffer_nr().
1316
1317bufwinid({buf}) *bufwinid()*
1318 The result is a Number, which is the |window-ID| of the first
1319 window associated with buffer {buf}. For the use of {buf},
1320 see |bufname()| above. If buffer {buf} doesn't exist or
1321 there is no such window, -1 is returned. Example: >
1322
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001323 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001324<
1325 Only deals with the current tab page.
1326
1327 Can also be used as a |method|: >
1328 FindBuffer()->bufwinid()
1329
1330bufwinnr({buf}) *bufwinnr()*
1331 Like |bufwinid()| but return the window number instead of the
1332 |window-ID|.
1333 If buffer {buf} doesn't exist or there is no such window, -1
1334 is returned. Example: >
1335
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001336 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001337
1338< The number can be used with |CTRL-W_w| and ":wincmd w"
1339 |:wincmd|.
1340
1341 Can also be used as a |method|: >
1342 FindBuffer()->bufwinnr()
1343
1344byte2line({byte}) *byte2line()*
1345 Return the line number that contains the character at byte
1346 count {byte} in the current buffer. This includes the
1347 end-of-line character, depending on the 'fileformat' option
1348 for the current buffer. The first character has byte count
1349 one.
1350 Also see |line2byte()|, |go| and |:goto|.
1351
Bram Moolenaar016188f2022-06-06 20:52:59 +01001352 Returns -1 if the {byte} value is invalid.
1353
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001354 Can also be used as a |method|: >
1355 GetOffset()->byte2line()
1356
1357< {not available when compiled without the |+byte_offset|
1358 feature}
1359
1360byteidx({expr}, {nr}) *byteidx()*
1361 Return byte index of the {nr}'th character in the String
1362 {expr}. Use zero for the first character, it then returns
1363 zero.
1364 If there are no multibyte characters the returned value is
1365 equal to {nr}.
1366 Composing characters are not counted separately, their byte
1367 length is added to the preceding base character. See
1368 |byteidxcomp()| below for counting composing characters
1369 separately.
1370 Example : >
1371 echo matchstr(str, ".", byteidx(str, 3))
1372< will display the fourth character. Another way to do the
1373 same: >
1374 let s = strpart(str, byteidx(str, 3))
1375 echo strpart(s, 0, byteidx(s, 1))
1376< Also see |strgetchar()| and |strcharpart()|.
1377
1378 If there are less than {nr} characters -1 is returned.
1379 If there are exactly {nr} characters the length of the string
1380 in bytes is returned.
1381
1382 Can also be used as a |method|: >
1383 GetName()->byteidx(idx)
1384
1385byteidxcomp({expr}, {nr}) *byteidxcomp()*
1386 Like byteidx(), except that a composing character is counted
1387 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001388 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001389 echo byteidx(s, 1)
1390 echo byteidxcomp(s, 1)
1391 echo byteidxcomp(s, 2)
1392< The first and third echo result in 3 ('e' plus composing
1393 character is 3 bytes), the second echo results in 1 ('e' is
1394 one byte).
1395 Only works differently from byteidx() when 'encoding' is set
1396 to a Unicode encoding.
1397
1398 Can also be used as a |method|: >
1399 GetName()->byteidxcomp(idx)
1400
1401call({func}, {arglist} [, {dict}]) *call()* *E699*
1402 Call function {func} with the items in |List| {arglist} as
1403 arguments.
1404 {func} can either be a |Funcref| or the name of a function.
1405 a:firstline and a:lastline are set to the cursor line.
1406 Returns the return value of the called function.
1407 {dict} is for functions with the "dict" attribute. It will be
1408 used to set the local variable "self". |Dictionary-function|
1409
1410 Can also be used as a |method|: >
1411 GetFunc()->call([arg, arg], dict)
1412
1413ceil({expr}) *ceil()*
1414 Return the smallest integral value greater than or equal to
1415 {expr} as a |Float| (round up).
1416 {expr} must evaluate to a |Float| or a |Number|.
1417 Examples: >
1418 echo ceil(1.456)
1419< 2.0 >
1420 echo ceil(-5.456)
1421< -5.0 >
1422 echo ceil(4.0)
1423< 4.0
1424
Bram Moolenaar016188f2022-06-06 20:52:59 +01001425 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1426
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001427 Can also be used as a |method|: >
1428 Compute()->ceil()
1429<
1430 {only available when compiled with the |+float| feature}
1431
1432
1433ch_ functions are documented here: |channel-functions-details|
1434
1435
1436changenr() *changenr()*
1437 Return the number of the most recent change. This is the same
1438 number as what is displayed with |:undolist| and can be used
1439 with the |:undo| command.
1440 When a change was made it is the number of that change. After
1441 redo it is the number of the redone change. After undo it is
1442 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001443 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001444
1445char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001446 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001447 Examples: >
1448 char2nr(" ") returns 32
1449 char2nr("ABC") returns 65
1450< When {utf8} is omitted or zero, the current 'encoding' is used.
1451 Example for "utf-8": >
1452 char2nr("á") returns 225
1453 char2nr("á"[0]) returns 195
1454< When {utf8} is TRUE, always treat as UTF-8 characters.
1455 A combining character is a separate character.
1456 |nr2char()| does the opposite.
1457 To turn a string into a list of character numbers: >
1458 let str = "ABC"
1459 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1460< Result: [65, 66, 67]
1461
Bram Moolenaar016188f2022-06-06 20:52:59 +01001462 Returns 0 if {string} is not a |String|.
1463
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001464 Can also be used as a |method|: >
1465 GetChar()->char2nr()
1466
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001467charclass({string}) *charclass()*
1468 Return the character class of the first character in {string}.
1469 The character class is one of:
1470 0 blank
1471 1 punctuation
1472 2 word character
1473 3 emoji
1474 other specific Unicode class
1475 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001476 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001477
1478
1479charcol({expr}) *charcol()*
1480 Same as |col()| but returns the character index of the column
1481 position given with {expr} instead of the byte position.
1482
1483 Example:
1484 With the cursor on '세' in line 5 with text "여보세요": >
1485 charcol('.') returns 3
1486 col('.') returns 7
1487
1488< Can also be used as a |method|: >
1489 GetPos()->col()
1490<
1491 *charidx()*
1492charidx({string}, {idx} [, {countcc}])
1493 Return the character index of the byte at {idx} in {string}.
1494 The index of the first character is zero.
1495 If there are no multibyte characters the returned value is
1496 equal to {idx}.
1497 When {countcc} is omitted or |FALSE|, then composing characters
1498 are not counted separately, their byte length is
1499 added to the preceding base character.
1500 When {countcc} is |TRUE|, then composing characters are
1501 counted as separate characters.
1502 Returns -1 if the arguments are invalid or if {idx} is greater
1503 than the index of the last byte in {string}. An error is
1504 given if the first argument is not a string, the second
1505 argument is not a number or when the third argument is present
1506 and is not zero or one.
1507 See |byteidx()| and |byteidxcomp()| for getting the byte index
1508 from the character index.
1509 Examples: >
1510 echo charidx('áb́ć', 3) returns 1
1511 echo charidx('áb́ć', 6, 1) returns 4
1512 echo charidx('áb́ć', 16) returns -1
1513<
1514 Can also be used as a |method|: >
1515 GetName()->charidx(idx)
1516
1517chdir({dir}) *chdir()*
1518 Change the current working directory to {dir}. The scope of
1519 the directory change depends on the directory of the current
1520 window:
1521 - If the current window has a window-local directory
1522 (|:lcd|), then changes the window local directory.
1523 - Otherwise, if the current tabpage has a local
1524 directory (|:tcd|) then changes the tabpage local
1525 directory.
1526 - Otherwise, changes the global directory.
1527 {dir} must be a String.
1528 If successful, returns the previous working directory. Pass
1529 this to another chdir() to restore the directory.
1530 On failure, returns an empty string.
1531
1532 Example: >
1533 let save_dir = chdir(newdir)
1534 if save_dir != ""
1535 " ... do some work
1536 call chdir(save_dir)
1537 endif
1538
1539< Can also be used as a |method|: >
1540 GetDir()->chdir()
1541<
1542cindent({lnum}) *cindent()*
1543 Get the amount of indent for line {lnum} according the C
1544 indenting rules, as with 'cindent'.
1545 The indent is counted in spaces, the value of 'tabstop' is
1546 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001547 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001548 See |C-indenting|.
1549
1550 Can also be used as a |method|: >
1551 GetLnum()->cindent()
1552
1553clearmatches([{win}]) *clearmatches()*
1554 Clears all matches previously defined for the current window
1555 by |matchadd()| and the |:match| commands.
1556 If {win} is specified, use the window with this number or
1557 window ID instead of the current window.
1558
1559 Can also be used as a |method|: >
1560 GetWin()->clearmatches()
1561<
1562 *col()*
1563col({expr}) The result is a Number, which is the byte index of the column
1564 position given with {expr}. The accepted positions are:
1565 . the cursor position
1566 $ the end of the cursor line (the result is the
1567 number of bytes in the cursor line plus one)
1568 'x position of mark x (if the mark is not set, 0 is
1569 returned)
1570 v In Visual mode: the start of the Visual area (the
1571 cursor is the end). When not in Visual mode
1572 returns the cursor position. Differs from |'<| in
1573 that it's updated right away.
1574 Additionally {expr} can be [lnum, col]: a |List| with the line
1575 and column number. Most useful when the column is "$", to get
1576 the last column of a specific line. When "lnum" or "col" is
1577 out of range then col() returns zero.
1578 To get the line number use |line()|. To get both use
1579 |getpos()|.
1580 For the screen column position use |virtcol()|. For the
1581 character position use |charcol()|.
1582 Note that only marks in the current file can be used.
1583 Examples: >
1584 col(".") column of cursor
1585 col("$") length of cursor line plus one
1586 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001587 col("'" .. markname) column of mark markname
Bram Moolenaar016188f2022-06-06 20:52:59 +01001588< The first column is 1. Returns 0 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001589 For an uppercase mark the column may actually be in another
1590 buffer.
1591 For the cursor position, when 'virtualedit' is active, the
1592 column is one higher if the cursor is after the end of the
1593 line. This can be used to obtain the column in Insert mode: >
1594 :imap <F2> <C-O>:let save_ve = &ve<CR>
1595 \<C-O>:set ve=all<CR>
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001596 \<C-O>:echo col(".") .. "\n" <Bar>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001597 \let &ve = save_ve<CR>
1598
1599< Can also be used as a |method|: >
1600 GetPos()->col()
1601<
1602
1603complete({startcol}, {matches}) *complete()* *E785*
1604 Set the matches for Insert mode completion.
1605 Can only be used in Insert mode. You need to use a mapping
1606 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1607 or with an expression mapping.
1608 {startcol} is the byte offset in the line where the completed
1609 text start. The text up to the cursor is the original text
1610 that will be replaced by the matches. Use col('.') for an
1611 empty string. "col('.') - 1" will replace one character by a
1612 match.
1613 {matches} must be a |List|. Each |List| item is one match.
1614 See |complete-items| for the kind of items that are possible.
1615 "longest" in 'completeopt' is ignored.
1616 Note that the after calling this function you need to avoid
1617 inserting anything that would cause completion to stop.
1618 The match can be selected with CTRL-N and CTRL-P as usual with
1619 Insert mode completion. The popup menu will appear if
1620 specified, see |ins-completion-menu|.
1621 Example: >
1622 inoremap <F5> <C-R>=ListMonths()<CR>
1623
1624 func! ListMonths()
1625 call complete(col('.'), ['January', 'February', 'March',
1626 \ 'April', 'May', 'June', 'July', 'August', 'September',
1627 \ 'October', 'November', 'December'])
1628 return ''
1629 endfunc
1630< This isn't very useful, but it shows how it works. Note that
1631 an empty string is returned to avoid a zero being inserted.
1632
1633 Can also be used as a |method|, the base is passed as the
1634 second argument: >
1635 GetMatches()->complete(col('.'))
1636
1637complete_add({expr}) *complete_add()*
1638 Add {expr} to the list of matches. Only to be used by the
1639 function specified with the 'completefunc' option.
1640 Returns 0 for failure (empty string or out of memory),
1641 1 when the match was added, 2 when the match was already in
1642 the list.
1643 See |complete-functions| for an explanation of {expr}. It is
1644 the same as one item in the list that 'omnifunc' would return.
1645
1646 Can also be used as a |method|: >
1647 GetMoreMatches()->complete_add()
1648
1649complete_check() *complete_check()*
1650 Check for a key typed while looking for completion matches.
1651 This is to be used when looking for matches takes some time.
1652 Returns |TRUE| when searching for matches is to be aborted,
1653 zero otherwise.
1654 Only to be used by the function specified with the
1655 'completefunc' option.
1656
1657
1658complete_info([{what}]) *complete_info()*
1659 Returns a |Dictionary| with information about Insert mode
1660 completion. See |ins-completion|.
1661 The items are:
1662 mode Current completion mode name string.
1663 See |complete_info_mode| for the values.
1664 pum_visible |TRUE| if popup menu is visible.
1665 See |pumvisible()|.
1666 items List of completion matches. Each item is a
1667 dictionary containing the entries "word",
1668 "abbr", "menu", "kind", "info" and "user_data".
1669 See |complete-items|.
1670 selected Selected item index. First index is zero.
1671 Index is -1 if no item is selected (showing
1672 typed text only, or the last completion after
1673 no item is selected when using the <Up> or
1674 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001675 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001676
1677 *complete_info_mode*
1678 mode values are:
1679 "" Not in completion mode
1680 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1681 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1682 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1683 |i_CTRL-X_CTRL-Y|
1684 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1685 "files" File names |i_CTRL-X_CTRL-F|
1686 "tags" Tags |i_CTRL-X_CTRL-]|
1687 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1688 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1689 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1690 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1691 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1692 "function" User defined completion |i_CTRL-X_CTRL-U|
1693 "omni" Omni completion |i_CTRL-X_CTRL-O|
1694 "spell" Spelling suggestions |i_CTRL-X_s|
1695 "eval" |complete()| completion
1696 "unknown" Other internal modes
1697
1698 If the optional {what} list argument is supplied, then only
1699 the items listed in {what} are returned. Unsupported items in
1700 {what} are silently ignored.
1701
1702 To get the position and size of the popup menu, see
1703 |pum_getpos()|. It's also available in |v:event| during the
1704 |CompleteChanged| event.
1705
Bram Moolenaar016188f2022-06-06 20:52:59 +01001706 Returns an empty |Dictionary| on error.
1707
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001708 Examples: >
1709 " Get all items
1710 call complete_info()
1711 " Get only 'mode'
1712 call complete_info(['mode'])
1713 " Get only 'mode' and 'pum_visible'
1714 call complete_info(['mode', 'pum_visible'])
1715
1716< Can also be used as a |method|: >
1717 GetItems()->complete_info()
1718<
1719 *confirm()*
1720confirm({msg} [, {choices} [, {default} [, {type}]]])
1721 confirm() offers the user a dialog, from which a choice can be
1722 made. It returns the number of the choice. For the first
1723 choice this is 1.
1724 Note: confirm() is only supported when compiled with dialog
1725 support, see |+dialog_con| and |+dialog_gui|.
1726
1727 {msg} is displayed in a |dialog| with {choices} as the
1728 alternatives. When {choices} is missing or empty, "&OK" is
1729 used (and translated).
1730 {msg} is a String, use '\n' to include a newline. Only on
1731 some systems the string is wrapped when it doesn't fit.
1732
1733 {choices} is a String, with the individual choices separated
1734 by '\n', e.g. >
1735 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1736< The letter after the '&' is the shortcut key for that choice.
1737 Thus you can type 'c' to select "Cancel". The shortcut does
1738 not need to be the first letter: >
1739 confirm("file has been modified", "&Save\nSave &All")
1740< For the console, the first letter of each choice is used as
1741 the default shortcut key. Case is ignored.
1742
1743 The optional {default} argument is the number of the choice
1744 that is made if the user hits <CR>. Use 1 to make the first
1745 choice the default one. Use 0 to not set a default. If
1746 {default} is omitted, 1 is used.
1747
1748 The optional {type} String argument gives the type of dialog.
1749 This is only used for the icon of the GTK, Mac, Motif and
1750 Win32 GUI. It can be one of these values: "Error",
1751 "Question", "Info", "Warning" or "Generic". Only the first
1752 character is relevant. When {type} is omitted, "Generic" is
1753 used.
1754
1755 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1756 or another valid interrupt key, confirm() returns 0.
1757
1758 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001759 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001760 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001761 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001762 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001763 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001764 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001765 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001766 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001767 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001768< In a GUI dialog, buttons are used. The layout of the buttons
1769 depends on the 'v' flag in 'guioptions'. If it is included,
1770 the buttons are always put vertically. Otherwise, confirm()
1771 tries to put the buttons in one horizontal line. If they
1772 don't fit, a vertical layout is used anyway. For some systems
1773 the horizontal layout is always used.
1774
1775 Can also be used as a |method|in: >
1776 BuildMessage()->confirm("&Yes\n&No")
1777<
1778 *copy()*
1779copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1780 different from using {expr} directly.
1781 When {expr} is a |List| a shallow copy is created. This means
1782 that the original |List| can be changed without changing the
1783 copy, and vice versa. But the items are identical, thus
1784 changing an item changes the contents of both |Lists|.
1785 A |Dictionary| is copied in a similar way as a |List|.
1786 Also see |deepcopy()|.
1787 Can also be used as a |method|: >
1788 mylist->copy()
1789
1790cos({expr}) *cos()*
1791 Return the cosine of {expr}, measured in radians, as a |Float|.
1792 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001793 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001794 Examples: >
1795 :echo cos(100)
1796< 0.862319 >
1797 :echo cos(-4.01)
1798< -0.646043
1799
1800 Can also be used as a |method|: >
1801 Compute()->cos()
1802<
1803 {only available when compiled with the |+float| feature}
1804
1805
1806cosh({expr}) *cosh()*
1807 Return the hyperbolic cosine of {expr} as a |Float| in the range
1808 [1, inf].
1809 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001810 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001811 Examples: >
1812 :echo cosh(0.5)
1813< 1.127626 >
1814 :echo cosh(-0.5)
1815< -1.127626
1816
1817 Can also be used as a |method|: >
1818 Compute()->cosh()
1819<
1820 {only available when compiled with the |+float| feature}
1821
1822
1823count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1824 Return the number of times an item with value {expr} appears
1825 in |String|, |List| or |Dictionary| {comp}.
1826
1827 If {start} is given then start with the item with this index.
1828 {start} can only be used with a |List|.
1829
1830 When {ic} is given and it's |TRUE| then case is ignored.
1831
1832 When {comp} is a string then the number of not overlapping
1833 occurrences of {expr} is returned. Zero is returned when
1834 {expr} is an empty string.
1835
1836 Can also be used as a |method|: >
1837 mylist->count(val)
1838<
1839 *cscope_connection()*
1840cscope_connection([{num} , {dbpath} [, {prepend}]])
1841 Checks for the existence of a |cscope| connection. If no
1842 parameters are specified, then the function returns:
1843 0, if cscope was not available (not compiled in), or
1844 if there are no cscope connections;
1845 1, if there is at least one cscope connection.
1846
1847 If parameters are specified, then the value of {num}
1848 determines how existence of a cscope connection is checked:
1849
1850 {num} Description of existence check
1851 ----- ------------------------------
1852 0 Same as no parameters (e.g., "cscope_connection()").
1853 1 Ignore {prepend}, and use partial string matches for
1854 {dbpath}.
1855 2 Ignore {prepend}, and use exact string matches for
1856 {dbpath}.
1857 3 Use {prepend}, use partial string matches for both
1858 {dbpath} and {prepend}.
1859 4 Use {prepend}, use exact string matches for both
1860 {dbpath} and {prepend}.
1861
1862 Note: All string comparisons are case sensitive!
1863
1864 Examples. Suppose we had the following (from ":cs show"): >
1865
1866 # pid database name prepend path
1867 0 27664 cscope.out /usr/local
1868<
1869 Invocation Return Val ~
1870 ---------- ---------- >
1871 cscope_connection() 1
1872 cscope_connection(1, "out") 1
1873 cscope_connection(2, "out") 0
1874 cscope_connection(3, "out") 0
1875 cscope_connection(3, "out", "local") 1
1876 cscope_connection(4, "out") 0
1877 cscope_connection(4, "out", "local") 0
1878 cscope_connection(4, "cscope.out", "/usr/local") 1
1879<
1880cursor({lnum}, {col} [, {off}]) *cursor()*
1881cursor({list})
1882 Positions the cursor at the column (byte count) {col} in the
1883 line {lnum}. The first column is one.
1884
1885 When there is one argument {list} this is used as a |List|
1886 with two, three or four item:
1887 [{lnum}, {col}]
1888 [{lnum}, {col}, {off}]
1889 [{lnum}, {col}, {off}, {curswant}]
1890 This is like the return value of |getpos()| or |getcurpos()|,
1891 but without the first item.
1892
1893 To position the cursor using the character count, use
1894 |setcursorcharpos()|.
1895
1896 Does not change the jumplist.
1897 {lnum} is used like with |getline()|.
1898 If {lnum} is greater than the number of lines in the buffer,
1899 the cursor will be positioned at the last line in the buffer.
1900 If {lnum} is zero, the cursor will stay in the current line.
1901 If {col} is greater than the number of bytes in the line,
1902 the cursor will be positioned at the last character in the
1903 line.
1904 If {col} is zero, the cursor will stay in the current column.
1905 If {curswant} is given it is used to set the preferred column
1906 for vertical movement. Otherwise {col} is used.
1907
1908 When 'virtualedit' is used {off} specifies the offset in
1909 screen columns from the start of the character. E.g., a
1910 position within a <Tab> or after the last character.
1911 Returns 0 when the position could be set, -1 otherwise.
1912
1913 Can also be used as a |method|: >
1914 GetCursorPos()->cursor()
1915
1916debugbreak({pid}) *debugbreak()*
1917 Specifically used to interrupt a program being debugged. It
1918 will cause process {pid} to get a SIGTRAP. Behavior for other
1919 processes is undefined. See |terminal-debugger|.
1920 {only available on MS-Windows}
1921
Bram Moolenaar016188f2022-06-06 20:52:59 +01001922 Returns |TRUE| if successfully interrupted the program.
1923 Otherwise returns |FALSE|.
1924
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001925 Can also be used as a |method|: >
1926 GetPid()->debugbreak()
1927
1928deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1929 Make a copy of {expr}. For Numbers and Strings this isn't
1930 different from using {expr} directly.
1931 When {expr} is a |List| a full copy is created. This means
1932 that the original |List| can be changed without changing the
1933 copy, and vice versa. When an item is a |List| or
1934 |Dictionary|, a copy for it is made, recursively. Thus
1935 changing an item in the copy does not change the contents of
1936 the original |List|.
1937 A |Dictionary| is copied in a similar way as a |List|.
1938
1939 When {noref} is omitted or zero a contained |List| or
1940 |Dictionary| is only copied once. All references point to
1941 this single copy. With {noref} set to 1 every occurrence of a
1942 |List| or |Dictionary| results in a new copy. This also means
1943 that a cyclic reference causes deepcopy() to fail.
1944 *E724*
1945 Nesting is possible up to 100 levels. When there is an item
1946 that refers back to a higher level making a deep copy with
1947 {noref} set to 1 will fail.
1948 Also see |copy()|.
1949
1950 Can also be used as a |method|: >
1951 GetObject()->deepcopy()
1952
1953delete({fname} [, {flags}]) *delete()*
1954 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001955 name {fname}.
1956
1957 This also works when {fname} is a symbolic link. The symbolic
1958 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001959
1960 When {flags} is "d": Deletes the directory by the name
1961 {fname}. This fails when directory {fname} is not empty.
1962
1963 When {flags} is "rf": Deletes the directory by the name
1964 {fname} and everything in it, recursively. BE CAREFUL!
1965 Note: on MS-Windows it is not possible to delete a directory
1966 that is being used.
1967
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001968 The result is a Number, which is 0/false if the delete
1969 operation was successful and -1/true when the deletion failed
1970 or partly failed.
1971
1972 Use |remove()| to delete an item from a |List|.
1973 To delete a line from the buffer use |:delete| or
1974 |deletebufline()|.
1975
1976 Can also be used as a |method|: >
1977 GetName()->delete()
1978
1979deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1980 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1981 If {last} is omitted then delete line {first} only.
1982 On success 0 is returned, on failure 1 is returned.
1983
1984 This function works only for loaded buffers. First call
1985 |bufload()| if needed.
1986
1987 For the use of {buf}, see |bufname()| above.
1988
1989 {first} and {last} are used like with |getline()|. Note that
1990 when using |line()| this refers to the current buffer. Use "$"
1991 to refer to the last line in buffer {buf}.
1992
1993 Can also be used as a |method|: >
1994 GetBuffer()->deletebufline(1)
1995<
1996 *did_filetype()*
1997did_filetype() Returns |TRUE| when autocommands are being executed and the
1998 FileType event has been triggered at least once. Can be used
1999 to avoid triggering the FileType event again in the scripts
2000 that detect the file type. |FileType|
2001 Returns |FALSE| when `:setf FALLBACK` was used.
2002 When editing another file, the counter is reset, thus this
2003 really checks if the FileType event has been triggered for the
2004 current buffer. This allows an autocommand that starts
2005 editing another buffer to set 'filetype' and load a syntax
2006 file.
2007
2008diff_filler({lnum}) *diff_filler()*
2009 Returns the number of filler lines above line {lnum}.
2010 These are the lines that were inserted at this point in
2011 another diff'ed window. These filler lines are shown in the
2012 display but don't exist in the buffer.
2013 {lnum} is used like with |getline()|. Thus "." is the current
2014 line, "'m" mark m, etc.
2015 Returns 0 if the current window is not in diff mode.
2016
2017 Can also be used as a |method|: >
2018 GetLnum()->diff_filler()
2019
2020diff_hlID({lnum}, {col}) *diff_hlID()*
2021 Returns the highlight ID for diff mode at line {lnum} column
2022 {col} (byte index). When the current line does not have a
2023 diff change zero is returned.
2024 {lnum} is used like with |getline()|. Thus "." is the current
2025 line, "'m" mark m, etc.
2026 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2027 line.
2028 The highlight ID can be used with |synIDattr()| to obtain
2029 syntax information about the highlighting.
2030
2031 Can also be used as a |method|: >
2032 GetLnum()->diff_hlID(col)
2033<
2034
2035digraph_get({chars}) *digraph_get()* *E1214*
2036 Return the digraph of {chars}. This should be a string with
2037 exactly two characters. If {chars} are not just two
2038 characters, or the digraph of {chars} does not exist, an error
2039 is given and an empty string is returned.
2040
2041 The character will be converted from Unicode to 'encoding'
2042 when needed. This does require the conversion to be
2043 available, it might fail.
2044
2045 Also see |digraph_getlist()|.
2046
2047 Examples: >
2048 " Get a built-in digraph
2049 :echo digraph_get('00') " Returns '∞'
2050
2051 " Get a user-defined digraph
2052 :call digraph_set('aa', 'あ')
2053 :echo digraph_get('aa') " Returns 'あ'
2054<
2055 Can also be used as a |method|: >
2056 GetChars()->digraph_get()
2057<
2058 This function works only when compiled with the |+digraphs|
2059 feature. If this feature is disabled, this function will
2060 display an error message.
2061
2062
2063digraph_getlist([{listall}]) *digraph_getlist()*
2064 Return a list of digraphs. If the {listall} argument is given
2065 and it is TRUE, return all digraphs, including the default
2066 digraphs. Otherwise, return only user-defined digraphs.
2067
2068 The characters will be converted from Unicode to 'encoding'
2069 when needed. This does require the conservation to be
2070 available, it might fail.
2071
2072 Also see |digraph_get()|.
2073
2074 Examples: >
2075 " Get user-defined digraphs
2076 :echo digraph_getlist()
2077
2078 " Get all the digraphs, including default digraphs
2079 :echo digraph_getlist(1)
2080<
2081 Can also be used as a |method|: >
2082 GetNumber()->digraph_getlist()
2083<
2084 This function works only when compiled with the |+digraphs|
2085 feature. If this feature is disabled, this function will
2086 display an error message.
2087
2088
Bram Moolenaara2baa732022-02-04 16:09:54 +00002089digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002090 Add digraph {chars} to the list. {chars} must be a string
2091 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002092 encoded character. *E1215*
2093 Be careful, composing characters are NOT ignored. This
2094 function is similar to |:digraphs| command, but useful to add
2095 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002096
2097 The function result is v:true if |digraph| is registered. If
2098 this fails an error message is given and v:false is returned.
2099
2100 If you want to define multiple digraphs at once, you can use
2101 |digraph_setlist()|.
2102
2103 Example: >
2104 call digraph_set(' ', 'あ')
2105<
2106 Can be used as a |method|: >
2107 GetString()->digraph_set('あ')
2108<
2109 This function works only when compiled with the |+digraphs|
2110 feature. If this feature is disabled, this function will
2111 display an error message.
2112
2113
2114digraph_setlist({digraphlist}) *digraph_setlist()*
2115 Similar to |digraph_set()| but this function can add multiple
2116 digraphs at once. {digraphlist} is a list composed of lists,
2117 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002118 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002119 Example: >
2120 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2121<
2122 It is similar to the following: >
2123 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2124 call digraph_set(chars, digraph)
2125 endfor
2126< Except that the function returns after the first error,
2127 following digraphs will not be added.
2128
2129 Can be used as a |method|: >
2130 GetList()->digraph_setlist()
2131<
2132 This function works only when compiled with the |+digraphs|
2133 feature. If this feature is disabled, this function will
2134 display an error message.
2135
2136
2137echoraw({string}) *echoraw()*
2138 Output {string} as-is, including unprintable characters.
2139 This can be used to output a terminal code. For example, to
2140 disable modifyOtherKeys: >
2141 call echoraw(&t_TE)
2142< and to enable it again: >
2143 call echoraw(&t_TI)
2144< Use with care, you can mess up the terminal this way.
2145
2146
2147empty({expr}) *empty()*
2148 Return the Number 1 if {expr} is empty, zero otherwise.
2149 - A |List| or |Dictionary| is empty when it does not have any
2150 items.
2151 - A |String| is empty when its length is zero.
2152 - A |Number| and |Float| are empty when their value is zero.
2153 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2154 - A |Job| is empty when it failed to start.
2155 - A |Channel| is empty when it is closed.
2156 - A |Blob| is empty when its length is zero.
2157
2158 For a long |List| this is much faster than comparing the
2159 length with zero.
2160
2161 Can also be used as a |method|: >
2162 mylist->empty()
2163
2164environ() *environ()*
2165 Return all of environment variables as dictionary. You can
2166 check if an environment variable exists like this: >
2167 :echo has_key(environ(), 'HOME')
2168< Note that the variable name may be CamelCase; to ignore case
2169 use this: >
2170 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2171
2172escape({string}, {chars}) *escape()*
2173 Escape the characters in {chars} that occur in {string} with a
2174 backslash. Example: >
2175 :echo escape('c:\program files\vim', ' \')
2176< results in: >
2177 c:\\program\ files\\vim
2178< Also see |shellescape()| and |fnameescape()|.
2179
2180 Can also be used as a |method|: >
2181 GetText()->escape(' \')
2182<
2183 *eval()*
2184eval({string}) Evaluate {string} and return the result. Especially useful to
2185 turn the result of |string()| back into the original value.
2186 This works for Numbers, Floats, Strings, Blobs and composites
2187 of them. Also works for |Funcref|s that refer to existing
2188 functions.
2189
2190 Can also be used as a |method|: >
2191 argv->join()->eval()
2192
2193eventhandler() *eventhandler()*
2194 Returns 1 when inside an event handler. That is that Vim got
2195 interrupted while waiting for the user to type a character,
2196 e.g., when dropping a file on Vim. This means interactive
2197 commands cannot be used. Otherwise zero is returned.
2198
2199executable({expr}) *executable()*
2200 This function checks if an executable with the name {expr}
2201 exists. {expr} must be the name of the program without any
2202 arguments.
2203 executable() uses the value of $PATH and/or the normal
2204 searchpath for programs. *PATHEXT*
2205 On MS-Windows the ".exe", ".bat", etc. can optionally be
2206 included. Then the extensions in $PATHEXT are tried. Thus if
2207 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2208 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2209 by itself can be used in $PATHEXT to try using the name
2210 without an extension. When 'shell' looks like a Unix shell,
2211 then the name is also tried without adding an extension.
2212 On MS-Windows it only checks if the file exists and is not a
2213 directory, not if it's really executable.
2214 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002215 normally found. Since this directory is added to $PATH it
2216 should also work to execute it |win32-PATH|. This can be
2217 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2218 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002219 The result is a Number:
2220 1 exists
2221 0 does not exist
2222 -1 not implemented on this system
2223 |exepath()| can be used to get the full path of an executable.
2224
2225 Can also be used as a |method|: >
2226 GetCommand()->executable()
2227
2228execute({command} [, {silent}]) *execute()*
2229 Execute an Ex command or commands and return the output as a
2230 string.
2231 {command} can be a string or a List. In case of a List the
2232 lines are executed one by one.
2233 This is equivalent to: >
2234 redir => var
2235 {command}
2236 redir END
2237<
2238 The optional {silent} argument can have these values:
2239 "" no `:silent` used
2240 "silent" `:silent` used
2241 "silent!" `:silent!` used
2242 The default is "silent". Note that with "silent!", unlike
2243 `:redir`, error messages are dropped. When using an external
2244 command the screen may be messed up, use `system()` instead.
2245 *E930*
2246 It is not possible to use `:redir` anywhere in {command}.
2247
2248 To get a list of lines use |split()| on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002249 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002250
2251< To execute a command in another window than the current one
2252 use `win_execute()`.
2253
2254 When used recursively the output of the recursive call is not
2255 included in the output of the higher level call.
2256
2257 Can also be used as a |method|: >
2258 GetCommand()->execute()
2259
2260exepath({expr}) *exepath()*
2261 If {expr} is an executable and is either an absolute path, a
2262 relative path or found in $PATH, return the full path.
2263 Note that the current directory is used when {expr} starts
2264 with "./", which may be a problem for Vim: >
2265 echo exepath(v:progpath)
2266< If {expr} cannot be found in $PATH or is not executable then
2267 an empty string is returned.
2268
2269 Can also be used as a |method|: >
2270 GetCommand()->exepath()
2271<
2272 *exists()*
2273exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2274 zero otherwise.
2275
2276 Note: In a compiled |:def| function the evaluation is done at
2277 runtime. Use `exists_compiled()` to evaluate the expression
2278 at compile time.
2279
2280 For checking for a supported feature use |has()|.
2281 For checking if a file exists use |filereadable()|.
2282
2283 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002284 varname internal variable (see
2285 dict.key |internal-variables|). Also works
2286 list[i] for |curly-braces-names|, |Dictionary|
2287 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002288 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002289 Does not work for local variables in a
2290 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002291 Also works for a function in |Vim9|
2292 script, since it can be used as a
2293 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002294 Beware that evaluating an index may
2295 cause an error message for an invalid
2296 expression. E.g.: >
2297 :let l = [1, 2, 3]
2298 :echo exists("l[5]")
2299< 0 >
2300 :echo exists("l[xx]")
2301< E121: Undefined variable: xx
2302 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002303 &option-name Vim option (only checks if it exists,
2304 not if it really works)
2305 +option-name Vim option that works.
2306 $ENVNAME environment variable (could also be
2307 done by comparing with an empty
2308 string)
2309 *funcname built-in function (see |functions|)
2310 or user defined function (see
2311 |user-functions|) that is implemented.
2312 Also works for a variable that is a
2313 Funcref.
2314 ?funcname built-in function that could be
2315 implemented; to be used to check if
2316 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002317 :cmdname Ex command: built-in command, user
2318 command or command modifier |:command|.
2319 Returns:
2320 1 for match with start of a command
2321 2 full match with a command
2322 3 matches several user commands
2323 To check for a supported command
2324 always check the return value to be 2.
2325 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002326 :3match The |:3match| command (but you
2327 probably should not use it, it is
2328 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002329 #event autocommand defined for this event
2330 #event#pattern autocommand defined for this event and
2331 pattern (the pattern is taken
2332 literally and compared to the
2333 autocommand patterns character by
2334 character)
2335 #group autocommand group exists
2336 #group#event autocommand defined for this group and
2337 event.
2338 #group#event#pattern
2339 autocommand defined for this group,
2340 event and pattern.
2341 ##event autocommand for this event is
2342 supported.
2343
2344 Examples: >
2345 exists("&shortname")
2346 exists("$HOSTNAME")
2347 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002348 exists("*s:MyFunc") " only for legacy script
2349 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002350 exists("bufcount")
2351 exists(":Make")
2352 exists("#CursorHold")
2353 exists("#BufReadPre#*.gz")
2354 exists("#filetypeindent")
2355 exists("#filetypeindent#FileType")
2356 exists("#filetypeindent#FileType#*")
2357 exists("##ColorScheme")
2358< There must be no space between the symbol (&/$/*/#) and the
2359 name.
2360 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002361 a few cases this is ignored. That may become stricter in the
2362 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002363 Working example: >
2364 exists(":make")
2365< NOT working example: >
2366 exists(":make install")
2367
2368< Note that the argument must be a string, not the name of the
2369 variable itself. For example: >
2370 exists(bufcount)
2371< This doesn't check for existence of the "bufcount" variable,
2372 but gets the value of "bufcount", and checks if that exists.
2373
2374 Can also be used as a |method|: >
2375 Varname()->exists()
2376<
2377
2378exists_compiled({expr}) *exists_compiled()*
2379 Like `exists()` but evaluated at compile time. This is useful
2380 to skip a block where a function is used that would otherwise
2381 give an error: >
2382 if exists_compiled('*ThatFunction')
2383 ThatFunction('works')
2384 endif
2385< If `exists()` were used then a compilation error would be
2386 given if ThatFunction() is not defined.
2387
2388 {expr} must be a literal string. *E1232*
2389 Can only be used in a |:def| function. *E1233*
2390 This does not work to check for arguments or local variables.
2391
2392
2393exp({expr}) *exp()*
2394 Return the exponential of {expr} as a |Float| in the range
2395 [0, inf].
2396 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002397 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002398 Examples: >
2399 :echo exp(2)
2400< 7.389056 >
2401 :echo exp(-1)
2402< 0.367879
2403
2404 Can also be used as a |method|: >
2405 Compute()->exp()
2406<
2407 {only available when compiled with the |+float| feature}
2408
2409
2410expand({string} [, {nosuf} [, {list}]]) *expand()*
2411 Expand wildcards and the following special keywords in
2412 {string}. 'wildignorecase' applies.
2413
2414 If {list} is given and it is |TRUE|, a List will be returned.
2415 Otherwise the result is a String and when there are several
2416 matches, they are separated by <NL> characters. [Note: in
2417 version 5.0 a space was used, which caused problems when a
2418 file name contains a space]
2419
2420 If the expansion fails, the result is an empty string. A name
2421 for a non-existing file is not included, unless {string} does
2422 not start with '%', '#' or '<', see below.
2423
2424 When {string} starts with '%', '#' or '<', the expansion is
2425 done like for the |cmdline-special| variables with their
2426 associated modifiers. Here is a short overview:
2427
2428 % current file name
2429 # alternate file name
2430 #n alternate file name n
2431 <cfile> file name under the cursor
2432 <afile> autocmd file name
2433 <abuf> autocmd buffer number (as a String!)
2434 <amatch> autocmd matched name
2435 <cexpr> C expression under the cursor
2436 <sfile> sourced script file or function name
2437 <slnum> sourced script line number or function
2438 line number
2439 <sflnum> script file line number, also when in
2440 a function
2441 <SID> "<SNR>123_" where "123" is the
2442 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002443 <script> sourced script file, or script file
2444 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002445 <stack> call stack
2446 <cword> word under the cursor
2447 <cWORD> WORD under the cursor
2448 <client> the {clientid} of the last received
2449 message |server2client()|
2450 Modifiers:
2451 :p expand to full path
2452 :h head (last path component removed)
2453 :t tail (last path component only)
2454 :r root (one extension removed)
2455 :e extension only
2456
2457 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002458 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002459< Note that when expanding a string that starts with '%', '#' or
2460 '<', any following text is ignored. This does NOT work: >
2461 :let doesntwork = expand("%:h.bak")
2462< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002463 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002464< Also note that expanding "<cfile>" and others only returns the
2465 referenced file name without further expansion. If "<cfile>"
2466 is "~/.cshrc", you need to do another expand() to have the
2467 "~/" expanded into the path of the home directory: >
2468 :echo expand(expand("<cfile>"))
2469<
2470 There cannot be white space between the variables and the
2471 following modifier. The |fnamemodify()| function can be used
2472 to modify normal file names.
2473
2474 When using '%' or '#', and the current or alternate file name
2475 is not defined, an empty string is used. Using "%:p" in a
2476 buffer with no name, results in the current directory, with a
2477 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002478 When 'verbose' is set then expanding '%', '#' and <> items
2479 will result in an error message if the argument cannot be
2480 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002481
2482 When {string} does not start with '%', '#' or '<', it is
2483 expanded like a file name is expanded on the command line.
2484 'suffixes' and 'wildignore' are used, unless the optional
2485 {nosuf} argument is given and it is |TRUE|.
2486 Names for non-existing files are included. The "**" item can
2487 be used to search in a directory tree. For example, to find
2488 all "README" files in the current directory and below: >
2489 :echo expand("**/README")
2490<
2491 expand() can also be used to expand variables and environment
2492 variables that are only known in a shell. But this can be
2493 slow, because a shell may be used to do the expansion. See
2494 |expr-env-expand|.
2495 The expanded variable is still handled like a list of file
2496 names. When an environment variable cannot be expanded, it is
2497 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2498 "$FOOBAR".
2499
2500 See |glob()| for finding existing files. See |system()| for
2501 getting the raw output of an external command.
2502
2503 Can also be used as a |method|: >
2504 Getpattern()->expand()
2505
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002506expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002507 Expand special items in String {string} like what is done for
2508 an Ex command such as `:edit`. This expands special keywords,
2509 like with |expand()|, and environment variables, anywhere in
2510 {string}. "~user" and "~/path" are only expanded at the
2511 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002512
2513 The following items are supported in the {options} Dict
2514 argument:
2515 errmsg If set to TRUE, error messages are displayed
2516 if an error is encountered during expansion.
2517 By default, error messages are not displayed.
2518
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002519 Returns the expanded string. If an error is encountered
2520 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002521
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002522 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002523 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002524 make /path/runtime/doc/builtin.o
2525 :echo expandcmd('make %<.o', {'errmsg': v:true})
2526<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002527 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002528 GetCommand()->expandcmd()
2529<
2530extend({expr1}, {expr2} [, {expr3}]) *extend()*
2531 {expr1} and {expr2} must be both |Lists| or both
2532 |Dictionaries|.
2533
2534 If they are |Lists|: Append {expr2} to {expr1}.
2535 If {expr3} is given insert the items of {expr2} before the
2536 item with index {expr3} in {expr1}. When {expr3} is zero
2537 insert before the first item. When {expr3} is equal to
2538 len({expr1}) then {expr2} is appended.
2539 Examples: >
2540 :echo sort(extend(mylist, [7, 5]))
2541 :call extend(mylist, [2, 3], 1)
2542< When {expr1} is the same List as {expr2} then the number of
2543 items copied is equal to the original length of the List.
2544 E.g., when {expr3} is 1 you get N new copies of the first item
2545 (where N is the original length of the List).
2546 Use |add()| to concatenate one item to a list. To concatenate
2547 two lists into a new list use the + operator: >
2548 :let newlist = [1, 2, 3] + [4, 5]
2549<
2550 If they are |Dictionaries|:
2551 Add all entries from {expr2} to {expr1}.
2552 If a key exists in both {expr1} and {expr2} then {expr3} is
2553 used to decide what to do:
2554 {expr3} = "keep": keep the value of {expr1}
2555 {expr3} = "force": use the value of {expr2}
2556 {expr3} = "error": give an error message *E737*
2557 When {expr3} is omitted then "force" is assumed.
2558
2559 {expr1} is changed when {expr2} is not empty. If necessary
2560 make a copy of {expr1} first.
2561 {expr2} remains unchanged.
2562 When {expr1} is locked and {expr2} is not empty the operation
2563 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002564 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002565
2566 Can also be used as a |method|: >
2567 mylist->extend(otherlist)
2568
2569
2570extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2571 Like |extend()| but instead of adding items to {expr1} a new
2572 List or Dictionary is created and returned. {expr1} remains
2573 unchanged. Items can still be changed by {expr2}, if you
2574 don't want that use |deepcopy()| first.
2575
2576
2577feedkeys({string} [, {mode}]) *feedkeys()*
2578 Characters in {string} are queued for processing as if they
2579 come from a mapping or were typed by the user.
2580
2581 By default the string is added to the end of the typeahead
2582 buffer, thus if a mapping is still being executed the
2583 characters come after them. Use the 'i' flag to insert before
2584 other characters, they will be executed next, before any
2585 characters from a mapping.
2586
2587 The function does not wait for processing of keys contained in
2588 {string}.
2589
2590 To include special keys into {string}, use double-quotes
2591 and "\..." notation |expr-quote|. For example,
2592 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2593 feedkeys('\<CR>') pushes 5 characters.
2594 A special code that might be useful is <Ignore>, it exits the
2595 wait for a character without doing anything. *<Ignore>*
2596
2597 {mode} is a String, which can contain these character flags:
2598 'm' Remap keys. This is default. If {mode} is absent,
2599 keys are remapped.
2600 'n' Do not remap keys.
2601 't' Handle keys as if typed; otherwise they are handled as
2602 if coming from a mapping. This matters for undo,
2603 opening folds, etc.
2604 'L' Lowlevel input. Only works for Unix or when using the
2605 GUI. Keys are used as if they were coming from the
2606 terminal. Other flags are not used. *E980*
2607 When a CTRL-C interrupts and 't' is included it sets
2608 the internal "got_int" flag.
2609 'i' Insert the string instead of appending (see above).
2610 'x' Execute commands until typeahead is empty. This is
2611 similar to using ":normal!". You can call feedkeys()
2612 several times without 'x' and then one time with 'x'
2613 (possibly with an empty {string}) to execute all the
2614 typeahead. Note that when Vim ends in Insert mode it
2615 will behave as if <Esc> is typed, to avoid getting
2616 stuck, waiting for a character to be typed before the
2617 script continues.
2618 Note that if you manage to call feedkeys() while
2619 executing commands, thus calling it recursively, then
2620 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002621 'c' Remove any script context when executing, so that
2622 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002623 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002624 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002625 '!' When used with 'x' will not end Insert mode. Can be
2626 used in a test when a timer is set to exit Insert mode
2627 a little later. Useful for testing CursorHoldI.
2628
2629 Return value is always 0.
2630
2631 Can also be used as a |method|: >
2632 GetInput()->feedkeys()
2633
2634filereadable({file}) *filereadable()*
2635 The result is a Number, which is |TRUE| when a file with the
2636 name {file} exists, and can be read. If {file} doesn't exist,
2637 or is a directory, the result is |FALSE|. {file} is any
2638 expression, which is used as a String.
2639 If you don't care about the file being readable you can use
2640 |glob()|.
2641 {file} is used as-is, you may want to expand wildcards first: >
2642 echo filereadable('~/.vimrc')
2643 0
2644 echo filereadable(expand('~/.vimrc'))
2645 1
2646
2647< Can also be used as a |method|: >
2648 GetName()->filereadable()
2649< *file_readable()*
2650 Obsolete name: file_readable().
2651
2652
2653filewritable({file}) *filewritable()*
2654 The result is a Number, which is 1 when a file with the
2655 name {file} exists, and can be written. If {file} doesn't
2656 exist, or is not writable, the result is 0. If {file} is a
2657 directory, and we can write to it, the result is 2.
2658
2659 Can also be used as a |method|: >
2660 GetName()->filewritable()
2661
2662
2663filter({expr1}, {expr2}) *filter()*
2664 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2665 For each item in {expr1} evaluate {expr2} and when the result
2666 is zero or false remove the item from the |List| or
2667 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002668 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002669
2670 {expr2} must be a |string| or |Funcref|.
2671
2672 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2673 of the current item. For a |Dictionary| |v:key| has the key
2674 of the current item and for a |List| |v:key| has the index of
2675 the current item. For a |Blob| |v:key| has the index of the
2676 current byte. For a |String| |v:key| has the index of the
2677 current character.
2678 Examples: >
2679 call filter(mylist, 'v:val !~ "OLD"')
2680< Removes the items where "OLD" appears. >
2681 call filter(mydict, 'v:key >= 8')
2682< Removes the items with a key below 8. >
2683 call filter(var, 0)
2684< Removes all the items, thus clears the |List| or |Dictionary|.
2685
2686 Note that {expr2} is the result of expression and is then
2687 used as an expression again. Often it is good to use a
2688 |literal-string| to avoid having to double backslashes.
2689
2690 If {expr2} is a |Funcref| it must take two arguments:
2691 1. the key or the index of the current item.
2692 2. the value of the current item.
2693 The function must return |TRUE| if the item should be kept.
2694 Example that keeps the odd items of a list: >
2695 func Odd(idx, val)
2696 return a:idx % 2 == 1
2697 endfunc
2698 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002699< It is shorter when using a |lambda|. In |Vim9| syntax: >
2700 call filter(myList, (idx, val) => idx * val <= 42)
2701< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002702 call filter(myList, {idx, val -> idx * val <= 42})
2703< If you do not use "val" you can leave it out: >
2704 call filter(myList, {idx -> idx % 2 == 1})
2705<
2706 In |Vim9| script the result must be true, false, zero or one.
2707 Other values will result in a type error.
2708
2709 For a |List| and a |Dictionary| the operation is done
2710 in-place. If you want it to remain unmodified make a copy
2711 first: >
2712 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2713
2714< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002715 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002716 When an error is encountered while evaluating {expr2} no
2717 further items in {expr1} are processed.
2718 When {expr2} is a Funcref errors inside a function are ignored,
2719 unless it was defined with the "abort" flag.
2720
2721 Can also be used as a |method|: >
2722 mylist->filter(expr2)
2723
2724finddir({name} [, {path} [, {count}]]) *finddir()*
2725 Find directory {name} in {path}. Supports both downwards and
2726 upwards recursive directory searches. See |file-searching|
2727 for the syntax of {path}.
2728
2729 Returns the path of the first found match. When the found
2730 directory is below the current directory a relative path is
2731 returned. Otherwise a full path is returned.
2732 If {path} is omitted or empty then 'path' is used.
2733
2734 If the optional {count} is given, find {count}'s occurrence of
2735 {name} in {path} instead of the first one.
2736 When {count} is negative return all the matches in a |List|.
2737
Bram Moolenaar016188f2022-06-06 20:52:59 +01002738 Returns an empty string if the directory is not found.
2739
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002740 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002741
2742 Can also be used as a |method|: >
2743 GetName()->finddir()
2744
2745findfile({name} [, {path} [, {count}]]) *findfile()*
2746 Just like |finddir()|, but find a file instead of a directory.
2747 Uses 'suffixesadd'.
2748 Example: >
2749 :echo findfile("tags.vim", ".;")
2750< Searches from the directory of the current file upwards until
2751 it finds the file "tags.vim".
2752
2753 Can also be used as a |method|: >
2754 GetName()->findfile()
2755
2756flatten({list} [, {maxdepth}]) *flatten()*
2757 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2758 the result is a |List| without nesting, as if {maxdepth} is
2759 a very large number.
2760 The {list} is changed in place, use |flattennew()| if you do
2761 not want that.
2762 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002763 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002764 *E900*
2765 {maxdepth} means how deep in nested lists changes are made.
2766 {list} is not modified when {maxdepth} is 0.
2767 {maxdepth} must be positive number.
2768
2769 If there is an error the number zero is returned.
2770
2771 Example: >
2772 :echo flatten([1, [2, [3, 4]], 5])
2773< [1, 2, 3, 4, 5] >
2774 :echo flatten([1, [2, [3, 4]], 5], 1)
2775< [1, 2, [3, 4], 5]
2776
2777 Can also be used as a |method|: >
2778 mylist->flatten()
2779<
2780flattennew({list} [, {maxdepth}]) *flattennew()*
2781 Like |flatten()| but first make a copy of {list}.
2782
2783
2784float2nr({expr}) *float2nr()*
2785 Convert {expr} to a Number by omitting the part after the
2786 decimal point.
2787 {expr} must evaluate to a |Float| or a Number.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002788 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002789 When the value of {expr} is out of range for a |Number| the
2790 result is truncated to 0x7fffffff or -0x7fffffff (or when
2791 64-bit Number support is enabled, 0x7fffffffffffffff or
2792 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2793 64-bit Number support is enabled, -0x8000000000000000).
2794 Examples: >
2795 echo float2nr(3.95)
2796< 3 >
2797 echo float2nr(-23.45)
2798< -23 >
2799 echo float2nr(1.0e100)
2800< 2147483647 (or 9223372036854775807) >
2801 echo float2nr(-1.0e150)
2802< -2147483647 (or -9223372036854775807) >
2803 echo float2nr(1.0e-100)
2804< 0
2805
2806 Can also be used as a |method|: >
2807 Compute()->float2nr()
2808<
2809 {only available when compiled with the |+float| feature}
2810
2811
2812floor({expr}) *floor()*
2813 Return the largest integral value less than or equal to
2814 {expr} as a |Float| (round down).
2815 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002816 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002817 Examples: >
2818 echo floor(1.856)
2819< 1.0 >
2820 echo floor(-5.456)
2821< -6.0 >
2822 echo floor(4.0)
2823< 4.0
2824
2825 Can also be used as a |method|: >
2826 Compute()->floor()
2827<
2828 {only available when compiled with the |+float| feature}
2829
2830
2831fmod({expr1}, {expr2}) *fmod()*
2832 Return the remainder of {expr1} / {expr2}, even if the
2833 division is not representable. Returns {expr1} - i * {expr2}
2834 for some integer i such that if {expr2} is non-zero, the
2835 result has the same sign as {expr1} and magnitude less than
2836 the magnitude of {expr2}. If {expr2} is zero, the value
2837 returned is zero. The value returned is a |Float|.
2838 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002839 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2840 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002841 Examples: >
2842 :echo fmod(12.33, 1.22)
2843< 0.13 >
2844 :echo fmod(-12.33, 1.22)
2845< -0.13
2846
2847 Can also be used as a |method|: >
2848 Compute()->fmod(1.22)
2849<
2850 {only available when compiled with |+float| feature}
2851
2852
2853fnameescape({string}) *fnameescape()*
2854 Escape {string} for use as file name command argument. All
2855 characters that have a special meaning, such as '%' and '|'
2856 are escaped with a backslash.
2857 For most systems the characters escaped are
2858 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2859 appears in a filename, it depends on the value of 'isfname'.
2860 A leading '+' and '>' is also escaped (special after |:edit|
2861 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002862 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002863 Example: >
2864 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002865 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002866< results in executing: >
2867 edit \+some\ str\%nge\|name
2868<
2869 Can also be used as a |method|: >
2870 GetName()->fnameescape()
2871
2872fnamemodify({fname}, {mods}) *fnamemodify()*
2873 Modify file name {fname} according to {mods}. {mods} is a
2874 string of characters like it is used for file names on the
2875 command line. See |filename-modifiers|.
2876 Example: >
2877 :echo fnamemodify("main.c", ":p:h")
2878< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002879 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01002880< If {mods} is empty or an unsupported modifier is used then
2881 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01002882 When {fname} is empty then with {mods} ":h" returns ".", so
2883 that `:cd` can be used with it. This is different from
2884 expand('%:h') without a buffer name, which returns an empty
2885 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002886 Note: Environment variables don't work in {fname}, use
2887 |expand()| first then.
2888
2889 Can also be used as a |method|: >
2890 GetName()->fnamemodify(':p:h')
2891
2892foldclosed({lnum}) *foldclosed()*
2893 The result is a Number. If the line {lnum} is in a closed
2894 fold, the result is the number of the first line in that fold.
2895 If the line {lnum} is not in a closed fold, -1 is returned.
2896 {lnum} is used like with |getline()|. Thus "." is the current
2897 line, "'m" mark m, etc.
2898
2899 Can also be used as a |method|: >
2900 GetLnum()->foldclosed()
2901
2902foldclosedend({lnum}) *foldclosedend()*
2903 The result is a Number. If the line {lnum} is in a closed
2904 fold, the result is the number of the last line in that fold.
2905 If the line {lnum} is not in a closed fold, -1 is returned.
2906 {lnum} is used like with |getline()|. Thus "." is the current
2907 line, "'m" mark m, etc.
2908
2909 Can also be used as a |method|: >
2910 GetLnum()->foldclosedend()
2911
2912foldlevel({lnum}) *foldlevel()*
2913 The result is a Number, which is the foldlevel of line {lnum}
2914 in the current buffer. For nested folds the deepest level is
2915 returned. If there is no fold at line {lnum}, zero is
2916 returned. It doesn't matter if the folds are open or closed.
2917 When used while updating folds (from 'foldexpr') -1 is
2918 returned for lines where folds are still to be updated and the
2919 foldlevel is unknown. As a special case the level of the
2920 previous line is usually available.
2921 {lnum} is used like with |getline()|. Thus "." is the current
2922 line, "'m" mark m, etc.
2923
2924 Can also be used as a |method|: >
2925 GetLnum()->foldlevel()
2926<
2927 *foldtext()*
2928foldtext() Returns a String, to be displayed for a closed fold. This is
2929 the default function used for the 'foldtext' option and should
2930 only be called from evaluating 'foldtext'. It uses the
2931 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2932 The returned string looks like this: >
2933 +-- 45 lines: abcdef
2934< The number of leading dashes depends on the foldlevel. The
2935 "45" is the number of lines in the fold. "abcdef" is the text
2936 in the first non-blank line of the fold. Leading white space,
2937 "//" or "/*" and the text from the 'foldmarker' and
2938 'commentstring' options is removed.
2939 When used to draw the actual foldtext, the rest of the line
2940 will be filled with the fold char from the 'fillchars'
2941 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002942 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002943 {not available when compiled without the |+folding| feature}
2944
2945foldtextresult({lnum}) *foldtextresult()*
2946 Returns the text that is displayed for the closed fold at line
2947 {lnum}. Evaluates 'foldtext' in the appropriate context.
2948 When there is no closed fold at {lnum} an empty string is
2949 returned.
2950 {lnum} is used like with |getline()|. Thus "." is the current
2951 line, "'m" mark m, etc.
2952 Useful when exporting folded text, e.g., to HTML.
2953 {not available when compiled without the |+folding| feature}
2954
2955
2956 Can also be used as a |method|: >
2957 GetLnum()->foldtextresult()
2958<
2959 *foreground()*
2960foreground() Move the Vim window to the foreground. Useful when sent from
2961 a client to a Vim server. |remote_send()|
2962 On Win32 systems this might not work, the OS does not always
2963 allow a window to bring itself to the foreground. Use
2964 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002965 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002966 Win32 console version}
2967
2968fullcommand({name}) *fullcommand()*
2969 Get the full command name from a short abbreviated command
2970 name; see |20.2| for details on command abbreviations.
2971
2972 The string argument {name} may start with a `:` and can
2973 include a [range], these are skipped and not returned.
2974 Returns an empty string if a command doesn't exist or if it's
2975 ambiguous (for user-defined commands).
2976
2977 For example `fullcommand('s')`, `fullcommand('sub')`,
2978 `fullcommand(':%substitute')` all return "substitute".
2979
2980 Can also be used as a |method|: >
2981 GetName()->fullcommand()
2982<
2983 *funcref()*
2984funcref({name} [, {arglist}] [, {dict}])
2985 Just like |function()|, but the returned Funcref will lookup
2986 the function by reference, not by name. This matters when the
2987 function {name} is redefined later.
2988
2989 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002990 It only works for an autoloaded function if it has already
2991 been loaded (to avoid mistakenly loading the autoload script
2992 when only intending to use the function name, use |function()|
2993 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002994 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002995
2996 Can also be used as a |method|: >
2997 GetFuncname()->funcref([arg])
2998<
2999 *function()* *partial* *E700* *E922* *E923*
3000function({name} [, {arglist}] [, {dict}])
3001 Return a |Funcref| variable that refers to function {name}.
3002 {name} can be the name of a user defined function or an
3003 internal function.
3004
3005 {name} can also be a Funcref or a partial. When it is a
3006 partial the dict stored in it will be used and the {dict}
3007 argument is not allowed. E.g.: >
3008 let FuncWithArg = function(dict.Func, [arg])
3009 let Broken = function(dict.Func, [arg], dict)
3010<
3011 When using the Funcref the function will be found by {name},
3012 also when it was redefined later. Use |funcref()| to keep the
3013 same function.
3014
3015 When {arglist} or {dict} is present this creates a partial.
3016 That means the argument list and/or the dictionary is stored in
3017 the Funcref and will be used when the Funcref is called.
3018
3019 The arguments are passed to the function in front of other
3020 arguments, but after any argument from |method|. Example: >
3021 func Callback(arg1, arg2, name)
3022 ...
3023 let Partial = function('Callback', ['one', 'two'])
3024 ...
3025 call Partial('name')
3026< Invokes the function as with: >
3027 call Callback('one', 'two', 'name')
3028
3029< With a |method|: >
3030 func Callback(one, two, three)
3031 ...
3032 let Partial = function('Callback', ['two'])
3033 ...
3034 eval 'one'->Partial('three')
3035< Invokes the function as with: >
3036 call Callback('one', 'two', 'three')
3037
3038< The function() call can be nested to add more arguments to the
3039 Funcref. The extra arguments are appended to the list of
3040 arguments. Example: >
3041 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003042 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003043 let Func = function('Callback', ['one'])
3044 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003045 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003046 call Func2('name')
3047< Invokes the function as with: >
3048 call Callback('one', 'two', 'name')
3049
3050< The Dictionary is only useful when calling a "dict" function.
3051 In that case the {dict} is passed in as "self". Example: >
3052 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003053 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003054 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003055 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003056 let context = {"name": "example"}
3057 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003058 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003059 call Func() " will echo: called for example
3060< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003061 arguments, these two are equivalent, if Callback() is defined
3062 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003063 let Func = function('Callback', context)
3064 let Func = context.Callback
3065
3066< The argument list and the Dictionary can be combined: >
3067 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003068 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003069 let context = {"name": "example"}
3070 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003071 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003072 call Func(500)
3073< Invokes the function as with: >
3074 call context.Callback('one', 500)
3075<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003076 Returns 0 on error.
3077
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003078 Can also be used as a |method|: >
3079 GetFuncname()->function([arg])
3080
3081
3082garbagecollect([{atexit}]) *garbagecollect()*
3083 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3084 that have circular references.
3085
3086 There is hardly ever a need to invoke this function, as it is
3087 automatically done when Vim runs out of memory or is waiting
3088 for the user to press a key after 'updatetime'. Items without
3089 circular references are always freed when they become unused.
3090 This is useful if you have deleted a very big |List| and/or
3091 |Dictionary| with circular references in a script that runs
3092 for a long time.
3093
3094 When the optional {atexit} argument is one, garbage
3095 collection will also be done when exiting Vim, if it wasn't
3096 done before. This is useful when checking for memory leaks.
3097
3098 The garbage collection is not done immediately but only when
3099 it's safe to perform. This is when waiting for the user to
3100 type a character. To force garbage collection immediately use
3101 |test_garbagecollect_now()|.
3102
3103get({list}, {idx} [, {default}]) *get()*
3104 Get item {idx} from |List| {list}. When this item is not
3105 available return {default}. Return zero when {default} is
3106 omitted.
3107 Preferably used as a |method|: >
3108 mylist->get(idx)
3109get({blob}, {idx} [, {default}])
3110 Get byte {idx} from |Blob| {blob}. When this byte is not
3111 available return {default}. Return -1 when {default} is
3112 omitted.
3113 Preferably used as a |method|: >
3114 myblob->get(idx)
3115get({dict}, {key} [, {default}])
3116 Get item with key {key} from |Dictionary| {dict}. When this
3117 item is not available return {default}. Return zero when
3118 {default} is omitted. Useful example: >
3119 let val = get(g:, 'var_name', 'default')
3120< This gets the value of g:var_name if it exists, and uses
3121 'default' when it does not exist.
3122 Preferably used as a |method|: >
3123 mydict->get(key)
3124get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003125 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003126 {what} are:
3127 "name" The function name
3128 "func" The function
3129 "dict" The dictionary
3130 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003131 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003132 Preferably used as a |method|: >
3133 myfunc->get(what)
3134<
3135 *getbufinfo()*
3136getbufinfo([{buf}])
3137getbufinfo([{dict}])
3138 Get information about buffers as a List of Dictionaries.
3139
3140 Without an argument information about all the buffers is
3141 returned.
3142
3143 When the argument is a |Dictionary| only the buffers matching
3144 the specified criteria are returned. The following keys can
3145 be specified in {dict}:
3146 buflisted include only listed buffers.
3147 bufloaded include only loaded buffers.
3148 bufmodified include only modified buffers.
3149
3150 Otherwise, {buf} specifies a particular buffer to return
3151 information for. For the use of {buf}, see |bufname()|
3152 above. If the buffer is found the returned List has one item.
3153 Otherwise the result is an empty list.
3154
3155 Each returned List item is a dictionary with the following
3156 entries:
3157 bufnr Buffer number.
3158 changed TRUE if the buffer is modified.
3159 changedtick Number of changes made to the buffer.
3160 hidden TRUE if the buffer is hidden.
3161 lastused Timestamp in seconds, like
3162 |localtime()|, when the buffer was
3163 last used.
3164 {only with the |+viminfo| feature}
3165 listed TRUE if the buffer is listed.
3166 lnum Line number used for the buffer when
3167 opened in the current window.
3168 Only valid if the buffer has been
3169 displayed in the window in the past.
3170 If you want the line number of the
3171 last known cursor position in a given
3172 window, use |line()|: >
3173 :echo line('.', {winid})
3174<
3175 linecount Number of lines in the buffer (only
3176 valid when loaded)
3177 loaded TRUE if the buffer is loaded.
3178 name Full path to the file in the buffer.
3179 signs List of signs placed in the buffer.
3180 Each list item is a dictionary with
3181 the following fields:
3182 id sign identifier
3183 lnum line number
3184 name sign name
3185 variables A reference to the dictionary with
3186 buffer-local variables.
3187 windows List of |window-ID|s that display this
3188 buffer
3189 popups List of popup |window-ID|s that
3190 display this buffer
3191
3192 Examples: >
3193 for buf in getbufinfo()
3194 echo buf.name
3195 endfor
3196 for buf in getbufinfo({'buflisted':1})
3197 if buf.changed
3198 ....
3199 endif
3200 endfor
3201<
3202 To get buffer-local options use: >
3203 getbufvar({bufnr}, '&option_name')
3204<
3205 Can also be used as a |method|: >
3206 GetBufnr()->getbufinfo()
3207<
3208
3209 *getbufline()*
3210getbufline({buf}, {lnum} [, {end}])
3211 Return a |List| with the lines starting from {lnum} to {end}
3212 (inclusive) in the buffer {buf}. If {end} is omitted, a
3213 |List| with only the line {lnum} is returned.
3214
3215 For the use of {buf}, see |bufname()| above.
3216
3217 For {lnum} and {end} "$" can be used for the last line of the
3218 buffer. Otherwise a number must be used.
3219
3220 When {lnum} is smaller than 1 or bigger than the number of
3221 lines in the buffer, an empty |List| is returned.
3222
3223 When {end} is greater than the number of lines in the buffer,
3224 it is treated as {end} is set to the number of lines in the
3225 buffer. When {end} is before {lnum} an empty |List| is
3226 returned.
3227
3228 This function works only for loaded buffers. For unloaded and
3229 non-existing buffers, an empty |List| is returned.
3230
3231 Example: >
3232 :let lines = getbufline(bufnr("myfile"), 1, "$")
3233
3234< Can also be used as a |method|: >
3235 GetBufnr()->getbufline(lnum)
3236
3237getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3238 The result is the value of option or local buffer variable
3239 {varname} in buffer {buf}. Note that the name without "b:"
3240 must be used.
3241 The {varname} argument is a string.
3242 When {varname} is empty returns a |Dictionary| with all the
3243 buffer-local variables.
3244 When {varname} is equal to "&" returns a |Dictionary| with all
3245 the buffer-local options.
3246 Otherwise, when {varname} starts with "&" returns the value of
3247 a buffer-local option.
3248 This also works for a global or buffer-local option, but it
3249 doesn't work for a global variable, window-local variable or
3250 window-local option.
3251 For the use of {buf}, see |bufname()| above.
3252 When the buffer or variable doesn't exist {def} or an empty
3253 string is returned, there is no error message.
3254 Examples: >
3255 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003256 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003257
3258< Can also be used as a |method|: >
3259 GetBufnr()->getbufvar(varname)
3260<
3261getchangelist([{buf}]) *getchangelist()*
3262 Returns the |changelist| for the buffer {buf}. For the use
3263 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3264 exist, an empty list is returned.
3265
3266 The returned list contains two entries: a list with the change
3267 locations and the current position in the list. Each
3268 entry in the change list is a dictionary with the following
3269 entries:
3270 col column number
3271 coladd column offset for 'virtualedit'
3272 lnum line number
3273 If buffer {buf} is the current buffer, then the current
3274 position refers to the position in the list. For other
3275 buffers, it is set to the length of the list.
3276
3277 Can also be used as a |method|: >
3278 GetBufnr()->getchangelist()
3279
3280getchar([expr]) *getchar()*
3281 Get a single character from the user or input stream.
3282 If [expr] is omitted, wait until a character is available.
3283 If [expr] is 0, only get a character when one is available.
3284 Return zero otherwise.
3285 If [expr] is 1, only check if a character is available, it is
3286 not consumed. Return zero if no character available.
3287 If you prefer always getting a string use |getcharstr()|.
3288
3289 Without [expr] and when [expr] is 0 a whole character or
3290 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003291 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003292 Otherwise a String is returned with the encoded character.
3293 For a special key it's a String with a sequence of bytes
3294 starting with 0x80 (decimal: 128). This is the same value as
3295 the String "\<Key>", e.g., "\<Left>". The returned value is
3296 also a String when a modifier (shift, control, alt) was used
3297 that is not included in the character.
3298
3299 When [expr] is 0 and Esc is typed, there will be a short delay
3300 while Vim waits to see if this is the start of an escape
3301 sequence.
3302
3303 When [expr] is 1 only the first byte is returned. For a
3304 one-byte character it is the character itself as a number.
3305 Use nr2char() to convert it to a String.
3306
3307 Use getcharmod() to obtain any additional modifiers.
3308
3309 When the user clicks a mouse button, the mouse event will be
3310 returned. The position can then be found in |v:mouse_col|,
3311 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3312 |getmousepos()| can also be used. Mouse move events will be
3313 ignored.
3314 This example positions the mouse as it would normally happen: >
3315 let c = getchar()
3316 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003317 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003318 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003319 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003320 endif
3321<
3322 When using bracketed paste only the first character is
3323 returned, the rest of the pasted text is dropped.
3324 |xterm-bracketed-paste|.
3325
3326 There is no prompt, you will somehow have to make clear to the
3327 user that a character has to be typed. The screen is not
3328 redrawn, e.g. when resizing the window. When using a popup
3329 window it should work better with a |popup-filter|.
3330
3331 There is no mapping for the character.
3332 Key codes are replaced, thus when the user presses the <Del>
3333 key you get the code for the <Del> key, not the raw character
3334 sequence. Examples: >
3335 getchar() == "\<Del>"
3336 getchar() == "\<S-Left>"
3337< This example redefines "f" to ignore case: >
3338 :nmap f :call FindChar()<CR>
3339 :function FindChar()
3340 : let c = nr2char(getchar())
3341 : while col('.') < col('$') - 1
3342 : normal l
3343 : if getline('.')[col('.') - 1] ==? c
3344 : break
3345 : endif
3346 : endwhile
3347 :endfunction
3348<
3349 You may also receive synthetic characters, such as
3350 |<CursorHold>|. Often you will want to ignore this and get
3351 another character: >
3352 :function GetKey()
3353 : let c = getchar()
3354 : while c == "\<CursorHold>"
3355 : let c = getchar()
3356 : endwhile
3357 : return c
3358 :endfunction
3359
3360getcharmod() *getcharmod()*
3361 The result is a Number which is the state of the modifiers for
3362 the last obtained character with getchar() or in another way.
3363 These values are added together:
3364 2 shift
3365 4 control
3366 8 alt (meta)
3367 16 meta (when it's different from ALT)
3368 32 mouse double click
3369 64 mouse triple click
3370 96 mouse quadruple click (== 32 + 64)
3371 128 command (Macintosh only)
3372 Only the modifiers that have not been included in the
3373 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003374 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003375
3376 *getcharpos()*
3377getcharpos({expr})
3378 Get the position for String {expr}. Same as |getpos()| but the
3379 column number in the returned List is a character index
3380 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003381 If |getpos()| returns a very large column number, equal to
3382 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003383 of the last character.
3384
3385 Example:
3386 With the cursor on '세' in line 5 with text "여보세요": >
3387 getcharpos('.') returns [0, 5, 3, 0]
3388 getpos('.') returns [0, 5, 7, 0]
3389<
3390 Can also be used as a |method|: >
3391 GetMark()->getcharpos()
3392
3393getcharsearch() *getcharsearch()*
3394 Return the current character search information as a {dict}
3395 with the following entries:
3396
3397 char character previously used for a character
3398 search (|t|, |f|, |T|, or |F|); empty string
3399 if no character search has been performed
3400 forward direction of character search; 1 for forward,
3401 0 for backward
3402 until type of character search; 1 for a |t| or |T|
3403 character search, 0 for an |f| or |F|
3404 character search
3405
3406 This can be useful to always have |;| and |,| search
3407 forward/backward regardless of the direction of the previous
3408 character search: >
3409 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3410 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3411< Also see |setcharsearch()|.
3412
3413
3414getcharstr([expr]) *getcharstr()*
3415 Get a single character from the user or input stream as a
3416 string.
3417 If [expr] is omitted, wait until a character is available.
3418 If [expr] is 0 or false, only get a character when one is
3419 available. Return an empty string otherwise.
3420 If [expr] is 1 or true, only check if a character is
3421 available, it is not consumed. Return an empty string
3422 if no character is available.
3423 Otherwise this works like |getchar()|, except that a number
3424 result is converted to a string.
3425
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003426getcmdcompltype() *getcmdcompltype()*
3427 Return the type of the current command-line completion.
3428 Only works when the command line is being edited, thus
3429 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003430 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003431 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3432 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003433 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003434
3435getcmdline() *getcmdline()*
3436 Return the current command-line. Only works when the command
3437 line is being edited, thus requires use of |c_CTRL-\_e| or
3438 |c_CTRL-R_=|.
3439 Example: >
3440 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003441< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3442 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003443 Returns an empty string when entering a password or using
3444 |inputsecret()|.
3445
3446getcmdpos() *getcmdpos()*
3447 Return the position of the cursor in the command line as a
3448 byte count. The first column is 1.
3449 Only works when editing the command line, thus requires use of
3450 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3451 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003452 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3453 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003454
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003455getcmdscreenpos() *getcmdscreenpos()*
3456 Return the screen position of the cursor in the command line
3457 as a byte count. The first column is 1.
3458 Instead of |getcmdpos()|, it adds the prompt position.
3459 Only works when editing the command line, thus requires use of
3460 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3461 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003462 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
3463 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003464
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003465getcmdtype() *getcmdtype()*
3466 Return the current command-line type. Possible return values
3467 are:
3468 : normal Ex command
3469 > debug mode command |debug-mode|
3470 / forward search command
3471 ? backward search command
3472 @ |input()| command
3473 - |:insert| or |:append| command
3474 = |i_CTRL-R_=|
3475 Only works when editing the command line, thus requires use of
3476 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3477 Returns an empty string otherwise.
3478 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3479
3480getcmdwintype() *getcmdwintype()*
3481 Return the current |command-line-window| type. Possible return
3482 values are the same as |getcmdtype()|. Returns an empty string
3483 when not in the command-line window.
3484
3485getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3486 Return a list of command-line completion matches. The String
3487 {type} argument specifies what for. The following completion
3488 types are supported:
3489
3490 arglist file names in argument list
3491 augroup autocmd groups
3492 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003493 behave |:behave| suboptions
3494 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003495 color color schemes
3496 command Ex command
3497 cmdline |cmdline-completion| result
3498 compiler compilers
3499 cscope |:cscope| suboptions
3500 diff_buffer |:diffget| and |:diffput| completion
3501 dir directory names
3502 environment environment variable names
3503 event autocommand events
3504 expression Vim expression
3505 file file and directory names
3506 file_in_path file and directory names in |'path'|
3507 filetype filetype names |'filetype'|
3508 function function name
3509 help help subjects
3510 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003511 history |:history| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003512 locale locale names (as output of locale -a)
3513 mapclear buffer argument
3514 mapping mapping name
3515 menu menus
3516 messages |:messages| suboptions
3517 option options
3518 packadd optional package |pack-add| names
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003519 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003520 shellcmd Shell command
3521 sign |:sign| suboptions
3522 syntax syntax file names |'syntax'|
3523 syntime |:syntime| suboptions
3524 tag tags
3525 tag_listfiles tags, file names
3526 user user names
3527 var user variables
3528
3529 If {pat} is an empty string, then all the matches are
3530 returned. Otherwise only items matching {pat} are returned.
3531 See |wildcards| for the use of special characters in {pat}.
3532
3533 If the optional {filtered} flag is set to 1, then 'wildignore'
3534 is applied to filter the results. Otherwise all the matches
3535 are returned. The 'wildignorecase' option always applies.
3536
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003537 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3538 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003539 regular expression matching is used. Thus this function
3540 follows the user preference, what happens on the command line.
3541 If you do not want this you can make 'wildoptions' empty
3542 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003543
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003544 If {type} is "cmdline", then the |cmdline-completion| result is
3545 returned. For example, to complete the possible values after
3546 a ":call" command: >
3547 echo getcompletion('call ', 'cmdline')
3548<
3549 If there are no matches, an empty list is returned. An
3550 invalid value for {type} produces an error.
3551
3552 Can also be used as a |method|: >
3553 GetPattern()->getcompletion('color')
3554<
3555 *getcurpos()*
3556getcurpos([{winid}])
3557 Get the position of the cursor. This is like getpos('.'), but
3558 includes an extra "curswant" item in the list:
3559 [0, lnum, col, off, curswant] ~
3560 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003561 cursor vertically. After |$| command it will be a very large
3562 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003563 |getpos()|.
3564 The first "bufnum" item is always zero. The byte position of
3565 the cursor is returned in 'col'. To get the character
3566 position, use |getcursorcharpos()|.
3567
3568 The optional {winid} argument can specify the window. It can
3569 be the window number or the |window-ID|. The last known
3570 cursor position is returned, this may be invalid for the
3571 current value of the buffer if it is not the current window.
3572 If {winid} is invalid a list with zeroes is returned.
3573
3574 This can be used to save and restore the cursor position: >
3575 let save_cursor = getcurpos()
3576 MoveTheCursorAround
3577 call setpos('.', save_cursor)
3578< Note that this only works within the window. See
3579 |winrestview()| for restoring more state.
3580
3581 Can also be used as a |method|: >
3582 GetWinid()->getcurpos()
3583<
3584 *getcursorcharpos()*
3585getcursorcharpos([{winid}])
3586 Same as |getcurpos()| but the column number in the returned
3587 List is a character index instead of a byte index.
3588
3589 Example:
3590 With the cursor on '보' in line 3 with text "여보세요": >
3591 getcursorcharpos() returns [0, 3, 2, 0, 3]
3592 getcurpos() returns [0, 3, 4, 0, 3]
3593<
3594 Can also be used as a |method|: >
3595 GetWinid()->getcursorcharpos()
3596
3597< *getcwd()*
3598getcwd([{winnr} [, {tabnr}]])
3599 The result is a String, which is the name of the current
3600 working directory. 'autochdir' is ignored.
3601
3602 With {winnr} return the local current directory of this window
3603 in the current tab page. {winnr} can be the window number or
3604 the |window-ID|.
3605 If {winnr} is -1 return the name of the global working
3606 directory. See also |haslocaldir()|.
3607
3608 With {winnr} and {tabnr} return the local current directory of
3609 the window in the specified tab page. If {winnr} is -1 return
3610 the working directory of the tabpage.
3611 If {winnr} is zero use the current window, if {tabnr} is zero
3612 use the current tabpage.
3613 Without any arguments, return the actual working directory of
3614 the current window.
3615 Return an empty string if the arguments are invalid.
3616
3617 Examples: >
3618 " Get the working directory of the current window
3619 :echo getcwd()
3620 :echo getcwd(0)
3621 :echo getcwd(0, 0)
3622 " Get the working directory of window 3 in tabpage 2
3623 :echo getcwd(3, 2)
3624 " Get the global working directory
3625 :echo getcwd(-1)
3626 " Get the working directory of tabpage 3
3627 :echo getcwd(-1, 3)
3628 " Get the working directory of current tabpage
3629 :echo getcwd(-1, 0)
3630
3631< Can also be used as a |method|: >
3632 GetWinnr()->getcwd()
3633
3634getenv({name}) *getenv()*
3635 Return the value of environment variable {name}. The {name}
3636 argument is a string, without a leading '$'. Example: >
3637 myHome = getenv('HOME')
3638
3639< When the variable does not exist |v:null| is returned. That
3640 is different from a variable set to an empty string, although
3641 some systems interpret the empty value as the variable being
3642 deleted. See also |expr-env|.
3643
3644 Can also be used as a |method|: >
3645 GetVarname()->getenv()
3646
3647getfontname([{name}]) *getfontname()*
3648 Without an argument returns the name of the normal font being
3649 used. Like what is used for the Normal highlight group
3650 |hl-Normal|.
3651 With an argument a check is done whether String {name} is a
3652 valid font name. If not then an empty string is returned.
3653 Otherwise the actual font name is returned, or {name} if the
3654 GUI does not support obtaining the real name.
3655 Only works when the GUI is running, thus not in your vimrc or
3656 gvimrc file. Use the |GUIEnter| autocommand to use this
3657 function just after the GUI has started.
3658 Note that the GTK GUI accepts any font name, thus checking for
3659 a valid name does not work.
3660
3661getfperm({fname}) *getfperm()*
3662 The result is a String, which is the read, write, and execute
3663 permissions of the given file {fname}.
3664 If {fname} does not exist or its directory cannot be read, an
3665 empty string is returned.
3666 The result is of the form "rwxrwxrwx", where each group of
3667 "rwx" flags represent, in turn, the permissions of the owner
3668 of the file, the group the file belongs to, and other users.
3669 If a user does not have a given permission the flag for this
3670 is replaced with the string "-". Examples: >
3671 :echo getfperm("/etc/passwd")
3672 :echo getfperm(expand("~/.vimrc"))
3673< This will hopefully (from a security point of view) display
3674 the string "rw-r--r--" or even "rw-------".
3675
3676 Can also be used as a |method|: >
3677 GetFilename()->getfperm()
3678<
3679 For setting permissions use |setfperm()|.
3680
3681getfsize({fname}) *getfsize()*
3682 The result is a Number, which is the size in bytes of the
3683 given file {fname}.
3684 If {fname} is a directory, 0 is returned.
3685 If the file {fname} can't be found, -1 is returned.
3686 If the size of {fname} is too big to fit in a Number then -2
3687 is returned.
3688
3689 Can also be used as a |method|: >
3690 GetFilename()->getfsize()
3691
3692getftime({fname}) *getftime()*
3693 The result is a Number, which is the last modification time of
3694 the given file {fname}. The value is measured as seconds
3695 since 1st Jan 1970, and may be passed to strftime(). See also
3696 |localtime()| and |strftime()|.
3697 If the file {fname} can't be found -1 is returned.
3698
3699 Can also be used as a |method|: >
3700 GetFilename()->getftime()
3701
3702getftype({fname}) *getftype()*
3703 The result is a String, which is a description of the kind of
3704 file of the given file {fname}.
3705 If {fname} does not exist an empty string is returned.
3706 Here is a table over different kinds of files and their
3707 results:
3708 Normal file "file"
3709 Directory "dir"
3710 Symbolic link "link"
3711 Block device "bdev"
3712 Character device "cdev"
3713 Socket "socket"
3714 FIFO "fifo"
3715 All other "other"
3716 Example: >
3717 getftype("/home")
3718< Note that a type such as "link" will only be returned on
3719 systems that support it. On some systems only "dir" and
3720 "file" are returned. On MS-Windows a symbolic link to a
3721 directory returns "dir" instead of "link".
3722
3723 Can also be used as a |method|: >
3724 GetFilename()->getftype()
3725
3726getimstatus() *getimstatus()*
3727 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003728 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003729 See 'imstatusfunc'.
3730
3731getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3732 Returns the |jumplist| for the specified window.
3733
3734 Without arguments use the current window.
3735 With {winnr} only use this window in the current tab page.
3736 {winnr} can also be a |window-ID|.
3737 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003738 page. If {winnr} or {tabnr} is invalid, an empty list is
3739 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003740
3741 The returned list contains two entries: a list with the jump
3742 locations and the last used jump position number in the list.
3743 Each entry in the jump location list is a dictionary with
3744 the following entries:
3745 bufnr buffer number
3746 col column number
3747 coladd column offset for 'virtualedit'
3748 filename filename if available
3749 lnum line number
3750
3751 Can also be used as a |method|: >
3752 GetWinnr()->getjumplist()
3753
3754< *getline()*
3755getline({lnum} [, {end}])
3756 Without {end} the result is a String, which is line {lnum}
3757 from the current buffer. Example: >
3758 getline(1)
3759< When {lnum} is a String that doesn't start with a
3760 digit, |line()| is called to translate the String into a Number.
3761 To get the line under the cursor: >
3762 getline(".")
3763< When {lnum} is a number smaller than 1 or bigger than the
3764 number of lines in the buffer, an empty string is returned.
3765
3766 When {end} is given the result is a |List| where each item is
3767 a line from the current buffer in the range {lnum} to {end},
3768 including line {end}.
3769 {end} is used in the same way as {lnum}.
3770 Non-existing lines are silently omitted.
3771 When {end} is before {lnum} an empty |List| is returned.
3772 Example: >
3773 :let start = line('.')
3774 :let end = search("^$") - 1
3775 :let lines = getline(start, end)
3776
3777< Can also be used as a |method|: >
3778 ComputeLnum()->getline()
3779
3780< To get lines from another buffer see |getbufline()|
3781
3782getloclist({nr} [, {what}]) *getloclist()*
3783 Returns a |List| with all the entries in the location list for
3784 window {nr}. {nr} can be the window number or the |window-ID|.
3785 When {nr} is zero the current window is used.
3786
3787 For a location list window, the displayed location list is
3788 returned. For an invalid window number {nr}, an empty list is
3789 returned. Otherwise, same as |getqflist()|.
3790
3791 If the optional {what} dictionary argument is supplied, then
3792 returns the items listed in {what} as a dictionary. Refer to
3793 |getqflist()| for the supported items in {what}.
3794
3795 In addition to the items supported by |getqflist()| in {what},
3796 the following item is supported by |getloclist()|:
3797
3798 filewinid id of the window used to display files
3799 from the location list. This field is
3800 applicable only when called from a
3801 location list window. See
3802 |location-list-file-window| for more
3803 details.
3804
3805 Returns a |Dictionary| with default values if there is no
3806 location list for the window {nr}.
3807 Returns an empty Dictionary if window {nr} does not exist.
3808
3809 Examples (See also |getqflist-examples|): >
3810 :echo getloclist(3, {'all': 0})
3811 :echo getloclist(5, {'filewinid': 0})
3812
3813
3814getmarklist([{buf}]) *getmarklist()*
3815 Without the {buf} argument returns a |List| with information
3816 about all the global marks. |mark|
3817
3818 If the optional {buf} argument is specified, returns the
3819 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01003820 see |bufname()|. If {buf} is invalid, an empty list is
3821 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003822
3823 Each item in the returned List is a |Dict| with the following:
3824 mark name of the mark prefixed by "'"
3825 pos a |List| with the position of the mark:
3826 [bufnum, lnum, col, off]
3827 Refer to |getpos()| for more information.
3828 file file name
3829
3830 Refer to |getpos()| for getting information about a specific
3831 mark.
3832
3833 Can also be used as a |method|: >
3834 GetBufnr()->getmarklist()
3835
3836getmatches([{win}]) *getmatches()*
3837 Returns a |List| with all matches previously defined for the
3838 current window by |matchadd()| and the |:match| commands.
3839 |getmatches()| is useful in combination with |setmatches()|,
3840 as |setmatches()| can restore a list of matches saved by
3841 |getmatches()|.
3842 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01003843 window ID instead of the current window. If {win} is invalid,
3844 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003845 Example: >
3846 :echo getmatches()
3847< [{'group': 'MyGroup1', 'pattern': 'TODO',
3848 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3849 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3850 :let m = getmatches()
3851 :call clearmatches()
3852 :echo getmatches()
3853< [] >
3854 :call setmatches(m)
3855 :echo getmatches()
3856< [{'group': 'MyGroup1', 'pattern': 'TODO',
3857 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3858 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3859 :unlet m
3860<
3861getmousepos() *getmousepos()*
3862 Returns a |Dictionary| with the last known position of the
3863 mouse. This can be used in a mapping for a mouse click or in
3864 a filter of a popup window. The items are:
3865 screenrow screen row
3866 screencol screen column
3867 winid Window ID of the click
3868 winrow row inside "winid"
3869 wincol column inside "winid"
3870 line text line inside "winid"
3871 column text column inside "winid"
3872 All numbers are 1-based.
3873
3874 If not over a window, e.g. when in the command line, then only
3875 "screenrow" and "screencol" are valid, the others are zero.
3876
3877 When on the status line below a window or the vertical
3878 separator right of a window, the "line" and "column" values
3879 are zero.
3880
3881 When the position is after the text then "column" is the
3882 length of the text in bytes plus one.
3883
3884 If the mouse is over a popup window then that window is used.
3885
3886 When using |getchar()| the Vim variables |v:mouse_lnum|,
3887 |v:mouse_col| and |v:mouse_winid| also provide these values.
3888
3889 *getpid()*
3890getpid() Return a Number which is the process ID of the Vim process.
3891 On Unix and MS-Windows this is a unique number, until Vim
3892 exits.
3893
3894 *getpos()*
3895getpos({expr}) Get the position for String {expr}. For possible values of
3896 {expr} see |line()|. For getting the cursor position see
3897 |getcurpos()|.
3898 The result is a |List| with four numbers:
3899 [bufnum, lnum, col, off]
3900 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3901 is the buffer number of the mark.
3902 "lnum" and "col" are the position in the buffer. The first
3903 column is 1.
3904 The "off" number is zero, unless 'virtualedit' is used. Then
3905 it is the offset in screen columns from the start of the
3906 character. E.g., a position within a <Tab> or after the last
3907 character.
3908 Note that for '< and '> Visual mode matters: when it is "V"
3909 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003910 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003911 The column number in the returned List is the byte position
3912 within the line. To get the character position in the line,
3913 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003914 A very large column number equal to |v:maxcol| can be returned,
3915 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01003916 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003917 This can be used to save and restore the position of a mark: >
3918 let save_a_mark = getpos("'a")
3919 ...
3920 call setpos("'a", save_a_mark)
3921< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3922
3923 Can also be used as a |method|: >
3924 GetMark()->getpos()
3925
3926getqflist([{what}]) *getqflist()*
3927 Returns a |List| with all the current quickfix errors. Each
3928 list item is a dictionary with these entries:
3929 bufnr number of buffer that has the file name, use
3930 bufname() to get the name
3931 module module name
3932 lnum line number in the buffer (first line is 1)
3933 end_lnum
3934 end of line number if the item is multiline
3935 col column number (first column is 1)
3936 end_col end of column number if the item has range
3937 vcol |TRUE|: "col" is visual column
3938 |FALSE|: "col" is byte index
3939 nr error number
3940 pattern search pattern used to locate the error
3941 text description of the error
3942 type type of the error, 'E', '1', etc.
3943 valid |TRUE|: recognized error message
3944
3945 When there is no error list or it's empty, an empty list is
3946 returned. Quickfix list entries with a non-existing buffer
3947 number are returned with "bufnr" set to zero (Note: some
3948 functions accept buffer number zero for the alternate buffer,
3949 you may need to explicitly check for zero).
3950
3951 Useful application: Find pattern matches in multiple files and
3952 do something with them: >
3953 :vimgrep /theword/jg *.c
3954 :for d in getqflist()
3955 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3956 :endfor
3957<
3958 If the optional {what} dictionary argument is supplied, then
3959 returns only the items listed in {what} as a dictionary. The
3960 following string items are supported in {what}:
3961 changedtick get the total number of changes made
3962 to the list |quickfix-changedtick|
3963 context get the |quickfix-context|
3964 efm errorformat to use when parsing "lines". If
3965 not present, then the 'errorformat' option
3966 value is used.
3967 id get information for the quickfix list with
3968 |quickfix-ID|; zero means the id for the
3969 current list or the list specified by "nr"
3970 idx get information for the quickfix entry at this
3971 index in the list specified by 'id' or 'nr'.
3972 If set to zero, then uses the current entry.
3973 See |quickfix-index|
3974 items quickfix list entries
3975 lines parse a list of lines using 'efm' and return
3976 the resulting entries. Only a |List| type is
3977 accepted. The current quickfix list is not
3978 modified. See |quickfix-parse|.
3979 nr get information for this quickfix list; zero
3980 means the current quickfix list and "$" means
3981 the last quickfix list
3982 qfbufnr number of the buffer displayed in the quickfix
3983 window. Returns 0 if the quickfix buffer is
3984 not present. See |quickfix-buffer|.
3985 size number of entries in the quickfix list
3986 title get the list title |quickfix-title|
3987 winid get the quickfix |window-ID|
3988 all all of the above quickfix properties
3989 Non-string items in {what} are ignored. To get the value of a
3990 particular item, set it to zero.
3991 If "nr" is not present then the current quickfix list is used.
3992 If both "nr" and a non-zero "id" are specified, then the list
3993 specified by "id" is used.
3994 To get the number of lists in the quickfix stack, set "nr" to
3995 "$" in {what}. The "nr" value in the returned dictionary
3996 contains the quickfix stack size.
3997 When "lines" is specified, all the other items except "efm"
3998 are ignored. The returned dictionary contains the entry
3999 "items" with the list of entries.
4000
4001 The returned dictionary contains the following entries:
4002 changedtick total number of changes made to the
4003 list |quickfix-changedtick|
4004 context quickfix list context. See |quickfix-context|
4005 If not present, set to "".
4006 id quickfix list ID |quickfix-ID|. If not
4007 present, set to 0.
4008 idx index of the quickfix entry in the list. If not
4009 present, set to 0.
4010 items quickfix list entries. If not present, set to
4011 an empty list.
4012 nr quickfix list number. If not present, set to 0
4013 qfbufnr number of the buffer displayed in the quickfix
4014 window. If not present, set to 0.
4015 size number of entries in the quickfix list. If not
4016 present, set to 0.
4017 title quickfix list title text. If not present, set
4018 to "".
4019 winid quickfix |window-ID|. If not present, set to 0
4020
4021 Examples (See also |getqflist-examples|): >
4022 :echo getqflist({'all': 1})
4023 :echo getqflist({'nr': 2, 'title': 1})
4024 :echo getqflist({'lines' : ["F1:10:L10"]})
4025<
4026getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4027 The result is a String, which is the contents of register
4028 {regname}. Example: >
4029 :let cliptext = getreg('*')
4030< When register {regname} was not set the result is an empty
4031 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004032 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004033
4034 getreg('=') returns the last evaluated value of the expression
4035 register. (For use in maps.)
4036 getreg('=', 1) returns the expression itself, so that it can
4037 be restored with |setreg()|. For other registers the extra
4038 argument is ignored, thus you can always give it.
4039
4040 If {list} is present and |TRUE|, the result type is changed
4041 to |List|. Each list item is one text line. Use it if you care
4042 about zero bytes possibly present inside register: without
4043 third argument both NLs and zero bytes are represented as NLs
4044 (see |NL-used-for-Nul|).
4045 When the register was not set an empty list is returned.
4046
4047 If {regname} is "", the unnamed register '"' is used.
4048 If {regname} is not specified, |v:register| is used.
4049 In |Vim9-script| {regname} must be one character.
4050
4051 Can also be used as a |method|: >
4052 GetRegname()->getreg()
4053
4054getreginfo([{regname}]) *getreginfo()*
4055 Returns detailed information about register {regname} as a
4056 Dictionary with the following entries:
4057 regcontents List of lines contained in register
4058 {regname}, like
4059 |getreg|({regname}, 1, 1).
4060 regtype the type of register {regname}, as in
4061 |getregtype()|.
4062 isunnamed Boolean flag, v:true if this register
4063 is currently pointed to by the unnamed
4064 register.
4065 points_to for the unnamed register, gives the
4066 single letter name of the register
4067 currently pointed to (see |quotequote|).
4068 For example, after deleting a line
4069 with `dd`, this field will be "1",
4070 which is the register that got the
4071 deleted text.
4072
4073 The {regname} argument is a string. If {regname} is invalid
4074 or not set, an empty Dictionary will be returned.
4075 If {regname} is "" or "@", the unnamed register '"' is used.
4076 If {regname} is not specified, |v:register| is used.
4077 The returned Dictionary can be passed to |setreg()|.
4078 In |Vim9-script| {regname} must be one character.
4079
4080 Can also be used as a |method|: >
4081 GetRegname()->getreginfo()
4082
4083getregtype([{regname}]) *getregtype()*
4084 The result is a String, which is type of register {regname}.
4085 The value will be one of:
4086 "v" for |characterwise| text
4087 "V" for |linewise| text
4088 "<CTRL-V>{width}" for |blockwise-visual| text
4089 "" for an empty or unknown register
4090 <CTRL-V> is one character with value 0x16.
4091 The {regname} argument is a string. If {regname} is "", the
4092 unnamed register '"' is used. If {regname} is not specified,
4093 |v:register| is used.
4094 In |Vim9-script| {regname} must be one character.
4095
4096 Can also be used as a |method|: >
4097 GetRegname()->getregtype()
4098
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004099getscriptinfo([{opts}) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004100 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004101 scripts in the order they were sourced, like what
4102 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004103
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004104 The optional Dict argument {opts} supports the following
4105 optional items:
4106 name Script name match pattern. If specified,
4107 and "sid" is not specified, information about
4108 scripts with name that match the pattern
4109 "name" are returned.
4110 sid Script ID |<SID>|. If specified, only
4111 information about the script with ID "sid" is
4112 returned and "name" is ignored.
4113
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004114 Each item in the returned List is a |Dict| with the following
4115 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004116 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004117 `import autoload` but was not actually sourced
4118 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004119 functions List of script-local function names defined in
4120 the script. Present only when a particular
4121 script is specified using the "sid" item in
4122 {opts}.
4123 name Vim script file name.
4124 sid Script ID |<SID>|.
4125 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004126 this script name links to, if any, otherwise
4127 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004128 variables A dictionary with the script-local variables.
4129 Present only when the a particular script is
4130 specified using the "sid" item in {opts}.
4131 Note that this is a copy, the value of
4132 script-local variables cannot be changed using
4133 this dictionary.
4134 version Vimscript version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004135
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004136 Examples: >
4137 :echo getscriptinfo({'name': 'myscript'})
4138 :echo getscriptinfo({'sid': 15}).variables
4139<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004140gettabinfo([{tabnr}]) *gettabinfo()*
4141 If {tabnr} is not specified, then information about all the
4142 tab pages is returned as a |List|. Each List item is a
4143 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4144 number and information about that one is returned. If the tab
4145 page does not exist an empty List is returned.
4146
4147 Each List item is a |Dictionary| with the following entries:
4148 tabnr tab page number.
4149 variables a reference to the dictionary with
4150 tabpage-local variables
4151 windows List of |window-ID|s in the tab page.
4152
4153 Can also be used as a |method|: >
4154 GetTabnr()->gettabinfo()
4155
4156gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4157 Get the value of a tab-local variable {varname} in tab page
4158 {tabnr}. |t:var|
4159 Tabs are numbered starting with one.
4160 The {varname} argument is a string. When {varname} is empty a
4161 dictionary with all tab-local variables is returned.
4162 Note that the name without "t:" must be used.
4163 When the tab or variable doesn't exist {def} or an empty
4164 string is returned, there is no error message.
4165
4166 Can also be used as a |method|: >
4167 GetTabnr()->gettabvar(varname)
4168
4169gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4170 Get the value of window-local variable {varname} in window
4171 {winnr} in tab page {tabnr}.
4172 The {varname} argument is a string. When {varname} is empty a
4173 dictionary with all window-local variables is returned.
4174 When {varname} is equal to "&" get the values of all
4175 window-local options in a |Dictionary|.
4176 Otherwise, when {varname} starts with "&" get the value of a
4177 window-local option.
4178 Note that {varname} must be the name without "w:".
4179 Tabs are numbered starting with one. For the current tabpage
4180 use |getwinvar()|.
4181 {winnr} can be the window number or the |window-ID|.
4182 When {winnr} is zero the current window is used.
4183 This also works for a global option, buffer-local option and
4184 window-local option, but it doesn't work for a global variable
4185 or buffer-local variable.
4186 When the tab, window or variable doesn't exist {def} or an
4187 empty string is returned, there is no error message.
4188 Examples: >
4189 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004190 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004191<
4192 To obtain all window-local variables use: >
4193 gettabwinvar({tabnr}, {winnr}, '&')
4194
4195< Can also be used as a |method|: >
4196 GetTabnr()->gettabwinvar(winnr, varname)
4197
4198gettagstack([{winnr}]) *gettagstack()*
4199 The result is a Dict, which is the tag stack of window {winnr}.
4200 {winnr} can be the window number or the |window-ID|.
4201 When {winnr} is not specified, the current window is used.
4202 When window {winnr} doesn't exist, an empty Dict is returned.
4203
4204 The returned dictionary contains the following entries:
4205 curidx Current index in the stack. When at
4206 top of the stack, set to (length + 1).
4207 Index of bottom of the stack is 1.
4208 items List of items in the stack. Each item
4209 is a dictionary containing the
4210 entries described below.
4211 length Number of entries in the stack.
4212
4213 Each item in the stack is a dictionary with the following
4214 entries:
4215 bufnr buffer number of the current jump
4216 from cursor position before the tag jump.
4217 See |getpos()| for the format of the
4218 returned list.
4219 matchnr current matching tag number. Used when
4220 multiple matching tags are found for a
4221 name.
4222 tagname name of the tag
4223
4224 See |tagstack| for more information about the tag stack.
4225
4226 Can also be used as a |method|: >
4227 GetWinnr()->gettagstack()
4228
4229
4230gettext({text}) *gettext()*
4231 Translate String {text} if possible.
4232 This is mainly for use in the distributed Vim scripts. When
4233 generating message translations the {text} is extracted by
4234 xgettext, the translator can add the translated message in the
4235 .po file and Vim will lookup the translation when gettext() is
4236 called.
4237 For {text} double quoted strings are preferred, because
4238 xgettext does not understand escaping in single quoted
4239 strings.
4240
4241
4242getwininfo([{winid}]) *getwininfo()*
4243 Returns information about windows as a |List| with Dictionaries.
4244
4245 If {winid} is given Information about the window with that ID
4246 is returned, as a |List| with one item. If the window does not
4247 exist the result is an empty list.
4248
4249 Without {winid} information about all the windows in all the
4250 tab pages is returned.
4251
4252 Each List item is a |Dictionary| with the following entries:
4253 botline last complete displayed buffer line
4254 bufnr number of buffer in the window
4255 height window height (excluding winbar)
4256 loclist 1 if showing a location list
4257 {only with the +quickfix feature}
4258 quickfix 1 if quickfix or location list window
4259 {only with the +quickfix feature}
4260 terminal 1 if a terminal window
4261 {only with the +terminal feature}
4262 tabnr tab page number
4263 topline first displayed buffer line
4264 variables a reference to the dictionary with
4265 window-local variables
4266 width window width
4267 winbar 1 if the window has a toolbar, 0
4268 otherwise
4269 wincol leftmost screen column of the window;
4270 "col" from |win_screenpos()|
4271 textoff number of columns occupied by any
4272 'foldcolumn', 'signcolumn' and line
4273 number in front of the text
4274 winid |window-ID|
4275 winnr window number
4276 winrow topmost screen line of the window;
4277 "row" from |win_screenpos()|
4278
4279 Can also be used as a |method|: >
4280 GetWinnr()->getwininfo()
4281
4282getwinpos([{timeout}]) *getwinpos()*
4283 The result is a |List| with two numbers, the result of
4284 |getwinposx()| and |getwinposy()| combined:
4285 [x-pos, y-pos]
4286 {timeout} can be used to specify how long to wait in msec for
4287 a response from the terminal. When omitted 100 msec is used.
4288 Use a longer time for a remote terminal.
4289 When using a value less than 10 and no response is received
4290 within that time, a previously reported position is returned,
4291 if available. This can be used to poll for the position and
4292 do some work in the meantime: >
4293 while 1
4294 let res = getwinpos(1)
4295 if res[0] >= 0
4296 break
4297 endif
4298 " Do some work here
4299 endwhile
4300<
4301
4302 Can also be used as a |method|: >
4303 GetTimeout()->getwinpos()
4304<
4305 *getwinposx()*
4306getwinposx() The result is a Number, which is the X coordinate in pixels of
4307 the left hand side of the GUI Vim window. Also works for an
4308 xterm (uses a timeout of 100 msec).
4309 The result will be -1 if the information is not available.
4310 The value can be used with `:winpos`.
4311
4312 *getwinposy()*
4313getwinposy() The result is a Number, which is the Y coordinate in pixels of
4314 the top of the GUI Vim window. Also works for an xterm (uses
4315 a timeout of 100 msec).
4316 The result will be -1 if the information is not available.
4317 The value can be used with `:winpos`.
4318
4319getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4320 Like |gettabwinvar()| for the current tabpage.
4321 Examples: >
4322 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004323 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004324
4325< Can also be used as a |method|: >
4326 GetWinnr()->getwinvar(varname)
4327<
4328glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4329 Expand the file wildcards in {expr}. See |wildcards| for the
4330 use of special characters.
4331
4332 Unless the optional {nosuf} argument is given and is |TRUE|,
4333 the 'suffixes' and 'wildignore' options apply: Names matching
4334 one of the patterns in 'wildignore' will be skipped and
4335 'suffixes' affect the ordering of matches.
4336 'wildignorecase' always applies.
4337
4338 When {list} is present and it is |TRUE| the result is a |List|
4339 with all matching files. The advantage of using a List is,
4340 you also get filenames containing newlines correctly.
4341 Otherwise the result is a String and when there are several
4342 matches, they are separated by <NL> characters.
4343
4344 If the expansion fails, the result is an empty String or List.
4345
4346 You can also use |readdir()| if you need to do complicated
4347 things, such as limiting the number of matches.
4348
4349 A name for a non-existing file is not included. A symbolic
4350 link is only included if it points to an existing file.
4351 However, when the {alllinks} argument is present and it is
4352 |TRUE| then all symbolic links are included.
4353
4354 For most systems backticks can be used to get files names from
4355 any external command. Example: >
4356 :let tagfiles = glob("`find . -name tags -print`")
4357 :let &tags = substitute(tagfiles, "\n", ",", "g")
4358< The result of the program inside the backticks should be one
4359 item per line. Spaces inside an item are allowed.
4360
4361 See |expand()| for expanding special Vim variables. See
4362 |system()| for getting the raw output of an external command.
4363
4364 Can also be used as a |method|: >
4365 GetExpr()->glob()
4366
4367glob2regpat({string}) *glob2regpat()*
4368 Convert a file pattern, as used by glob(), into a search
4369 pattern. The result can be used to match with a string that
4370 is a file name. E.g. >
4371 if filename =~ glob2regpat('Make*.mak')
4372< This is equivalent to: >
4373 if filename =~ '^Make.*\.mak$'
4374< When {string} is an empty string the result is "^$", match an
4375 empty string.
4376 Note that the result depends on the system. On MS-Windows
4377 a backslash usually means a path separator.
4378
4379 Can also be used as a |method|: >
4380 GetExpr()->glob2regpat()
4381< *globpath()*
4382globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4383 Perform glob() for String {expr} on all directories in {path}
4384 and concatenate the results. Example: >
4385 :echo globpath(&rtp, "syntax/c.vim")
4386<
4387 {path} is a comma-separated list of directory names. Each
4388 directory name is prepended to {expr} and expanded like with
4389 |glob()|. A path separator is inserted when needed.
4390 To add a comma inside a directory name escape it with a
4391 backslash. Note that on MS-Windows a directory may have a
4392 trailing backslash, remove it if you put a comma after it.
4393 If the expansion fails for one of the directories, there is no
4394 error message.
4395
4396 Unless the optional {nosuf} argument is given and is |TRUE|,
4397 the 'suffixes' and 'wildignore' options apply: Names matching
4398 one of the patterns in 'wildignore' will be skipped and
4399 'suffixes' affect the ordering of matches.
4400
4401 When {list} is present and it is |TRUE| the result is a |List|
4402 with all matching files. The advantage of using a List is, you
4403 also get filenames containing newlines correctly. Otherwise
4404 the result is a String and when there are several matches,
4405 they are separated by <NL> characters. Example: >
4406 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4407<
4408 {alllinks} is used as with |glob()|.
4409
4410 The "**" item can be used to search in a directory tree.
4411 For example, to find all "README.txt" files in the directories
4412 in 'runtimepath' and below: >
4413 :echo globpath(&rtp, "**/README.txt")
4414< Upwards search and limiting the depth of "**" is not
4415 supported, thus using 'path' will not always work properly.
4416
4417 Can also be used as a |method|, the base is passed as the
4418 second argument: >
4419 GetExpr()->globpath(&rtp)
4420<
4421 *has()*
4422has({feature} [, {check}])
4423 When {check} is omitted or is zero: The result is a Number,
4424 which is 1 if the feature {feature} is supported, zero
4425 otherwise. The {feature} argument is a string, case is
4426 ignored. See |feature-list| below.
4427
4428 When {check} is present and not zero: The result is a Number,
4429 which is 1 if the feature {feature} could ever be supported,
4430 zero otherwise. This is useful to check for a typo in
4431 {feature} and to detect dead code. Keep in mind that an older
4432 Vim version will not know about a feature added later and
4433 features that have been abandoned will not be known by the
4434 current Vim version.
4435
4436 Also see |exists()| and |exists_compiled()|.
4437
4438 Note that to skip code that has a syntax error when the
4439 feature is not available, Vim may skip the rest of the line
4440 and miss a following `endif`. Therefore put the `endif` on a
4441 separate line: >
4442 if has('feature')
4443 let x = this->breaks->without->the->feature
4444 endif
4445< If the `endif` would be moved to the second line as "| endif" it
4446 would not be found.
4447
4448
4449has_key({dict}, {key}) *has_key()*
4450 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01004451 has an entry with key {key}. FALSE otherwise.
4452 The {key} argument is a string. In |Vim9| script a number is
4453 also accepted (and converted to a string) but no other types.
4454 In legacy script the usual automatic conversion to string is
4455 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004456
4457 Can also be used as a |method|: >
4458 mydict->has_key(key)
4459
4460haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4461 The result is a Number:
4462 1 when the window has set a local directory via |:lcd|
4463 2 when the tab-page has set a local directory via |:tcd|
4464 0 otherwise.
4465
4466 Without arguments use the current window.
4467 With {winnr} use this window in the current tab page.
4468 With {winnr} and {tabnr} use the window in the specified tab
4469 page.
4470 {winnr} can be the window number or the |window-ID|.
4471 If {winnr} is -1 it is ignored and only the tabpage is used.
4472 Return 0 if the arguments are invalid.
4473 Examples: >
4474 if haslocaldir() == 1
4475 " window local directory case
4476 elseif haslocaldir() == 2
4477 " tab-local directory case
4478 else
4479 " global directory case
4480 endif
4481
4482 " current window
4483 :echo haslocaldir()
4484 :echo haslocaldir(0)
4485 :echo haslocaldir(0, 0)
4486 " window n in current tab page
4487 :echo haslocaldir(n)
4488 :echo haslocaldir(n, 0)
4489 " window n in tab page m
4490 :echo haslocaldir(n, m)
4491 " tab page m
4492 :echo haslocaldir(-1, m)
4493<
4494 Can also be used as a |method|: >
4495 GetWinnr()->haslocaldir()
4496
4497hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4498 The result is a Number, which is TRUE if there is a mapping
4499 that contains {what} in somewhere in the rhs (what it is
4500 mapped to) and this mapping exists in one of the modes
4501 indicated by {mode}.
4502 The arguments {what} and {mode} are strings.
4503 When {abbr} is there and it is |TRUE| use abbreviations
4504 instead of mappings. Don't forget to specify Insert and/or
4505 Command-line mode.
4506 Both the global mappings and the mappings local to the current
4507 buffer are checked for a match.
4508 If no matching mapping is found FALSE is returned.
4509 The following characters are recognized in {mode}:
4510 n Normal mode
4511 v Visual and Select mode
4512 x Visual mode
4513 s Select mode
4514 o Operator-pending mode
4515 i Insert mode
4516 l Language-Argument ("r", "f", "t", etc.)
4517 c Command-line mode
4518 When {mode} is omitted, "nvo" is used.
4519
4520 This function is useful to check if a mapping already exists
4521 to a function in a Vim script. Example: >
4522 :if !hasmapto('\ABCdoit')
4523 : map <Leader>d \ABCdoit
4524 :endif
4525< This installs the mapping to "\ABCdoit" only if there isn't
4526 already a mapping to "\ABCdoit".
4527
4528 Can also be used as a |method|: >
4529 GetRHS()->hasmapto()
4530
4531histadd({history}, {item}) *histadd()*
4532 Add the String {item} to the history {history} which can be
4533 one of: *hist-names*
4534 "cmd" or ":" command line history
4535 "search" or "/" search pattern history
4536 "expr" or "=" typed expression history
4537 "input" or "@" input line history
4538 "debug" or ">" debug command history
4539 empty the current or last used history
4540 The {history} string does not need to be the whole name, one
4541 character is sufficient.
4542 If {item} does already exist in the history, it will be
4543 shifted to become the newest entry.
4544 The result is a Number: TRUE if the operation was successful,
4545 otherwise FALSE is returned.
4546
4547 Example: >
4548 :call histadd("input", strftime("%Y %b %d"))
4549 :let date=input("Enter date: ")
4550< This function is not available in the |sandbox|.
4551
4552 Can also be used as a |method|, the base is passed as the
4553 second argument: >
4554 GetHistory()->histadd('search')
4555
4556histdel({history} [, {item}]) *histdel()*
4557 Clear {history}, i.e. delete all its entries. See |hist-names|
4558 for the possible values of {history}.
4559
4560 If the parameter {item} evaluates to a String, it is used as a
4561 regular expression. All entries matching that expression will
4562 be removed from the history (if there are any).
4563 Upper/lowercase must match, unless "\c" is used |/\c|.
4564 If {item} evaluates to a Number, it will be interpreted as
4565 an index, see |:history-indexing|. The respective entry will
4566 be removed if it exists.
4567
4568 The result is TRUE for a successful operation, otherwise FALSE
4569 is returned.
4570
4571 Examples:
4572 Clear expression register history: >
4573 :call histdel("expr")
4574<
4575 Remove all entries starting with "*" from the search history: >
4576 :call histdel("/", '^\*')
4577<
4578 The following three are equivalent: >
4579 :call histdel("search", histnr("search"))
4580 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004581 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004582<
4583 To delete the last search pattern and use the last-but-one for
4584 the "n" command and 'hlsearch': >
4585 :call histdel("search", -1)
4586 :let @/ = histget("search", -1)
4587<
4588 Can also be used as a |method|: >
4589 GetHistory()->histdel()
4590
4591histget({history} [, {index}]) *histget()*
4592 The result is a String, the entry with Number {index} from
4593 {history}. See |hist-names| for the possible values of
4594 {history}, and |:history-indexing| for {index}. If there is
4595 no such entry, an empty String is returned. When {index} is
4596 omitted, the most recent item from the history is used.
4597
4598 Examples:
4599 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004600 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004601
4602< Define an Ex command ":H {num}" that supports re-execution of
4603 the {num}th entry from the output of |:history|. >
4604 :command -nargs=1 H execute histget("cmd", 0+<args>)
4605<
4606 Can also be used as a |method|: >
4607 GetHistory()->histget()
4608
4609histnr({history}) *histnr()*
4610 The result is the Number of the current entry in {history}.
4611 See |hist-names| for the possible values of {history}.
4612 If an error occurred, -1 is returned.
4613
4614 Example: >
4615 :let inp_index = histnr("expr")
4616
4617< Can also be used as a |method|: >
4618 GetHistory()->histnr()
4619<
4620hlexists({name}) *hlexists()*
4621 The result is a Number, which is TRUE if a highlight group
4622 called {name} exists. This is when the group has been
4623 defined in some way. Not necessarily when highlighting has
4624 been defined for it, it may also have been used for a syntax
4625 item.
4626 *highlight_exists()*
4627 Obsolete name: highlight_exists().
4628
4629 Can also be used as a |method|: >
4630 GetName()->hlexists()
4631<
4632hlget([{name} [, {resolve}]]) *hlget()*
4633 Returns a List of all the highlight group attributes. If the
4634 optional {name} is specified, then returns a List with only
4635 the attributes of the specified highlight group. Returns an
4636 empty List if the highlight group {name} is not present.
4637
4638 If the optional {resolve} argument is set to v:true and the
4639 highlight group {name} is linked to another group, then the
4640 link is resolved recursively and the attributes of the
4641 resolved highlight group are returned.
4642
4643 Each entry in the returned List is a Dictionary with the
4644 following items:
4645 cleared boolean flag, set to v:true if the highlight
4646 group attributes are cleared or not yet
4647 specified. See |highlight-clear|.
4648 cterm cterm attributes. See |highlight-cterm|.
4649 ctermbg cterm background color.
4650 See |highlight-ctermbg|.
4651 ctermfg cterm foreground color.
4652 See |highlight-ctermfg|.
4653 ctermul cterm underline color. See |highlight-ctermul|.
4654 default boolean flag, set to v:true if the highlight
4655 group link is a default link. See
4656 |highlight-default|.
4657 font highlight group font. See |highlight-font|.
4658 gui gui attributes. See |highlight-gui|.
4659 guibg gui background color. See |highlight-guibg|.
4660 guifg gui foreground color. See |highlight-guifg|.
4661 guisp gui special color. See |highlight-guisp|.
4662 id highlight group ID.
4663 linksto linked highlight group name.
4664 See |:highlight-link|.
4665 name highlight group name. See |group-name|.
4666 start start terminal keycode. See |highlight-start|.
4667 stop stop terminal keycode. See |highlight-stop|.
4668 term term attributes. See |highlight-term|.
4669
4670 The 'term', 'cterm' and 'gui' items in the above Dictionary
4671 have a dictionary value with the following optional boolean
4672 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4673 'reverse', 'inverse' and 'strikethrough'.
4674
4675 Example(s): >
4676 :echo hlget()
4677 :echo hlget('ModeMsg')
4678 :echo hlget('Number', v:true)
4679<
4680 Can also be used as a |method|: >
4681 GetName()->hlget()
4682<
4683hlset({list}) *hlset()*
4684 Creates or modifies the attributes of a List of highlight
4685 groups. Each item in {list} is a dictionary containing the
4686 attributes of a highlight group. See |hlget()| for the list of
4687 supported items in this dictionary.
4688
4689 In addition to the items described in |hlget()|, the following
4690 additional items are supported in the dictionary:
4691
4692 force boolean flag to force the creation of
4693 a link for an existing highlight group
4694 with attributes.
4695
4696 The highlight group is identified using the 'name' item and
4697 the 'id' item (if supplied) is ignored. If a highlight group
4698 with a specified name doesn't exist, then it is created.
4699 Otherwise the attributes of an existing highlight group are
4700 modified.
4701
4702 If an empty dictionary value is used for the 'term' or 'cterm'
4703 or 'gui' entries, then the corresponding attributes are
4704 cleared. If the 'cleared' item is set to v:true, then all the
4705 attributes of the highlight group are cleared.
4706
4707 The 'linksto' item can be used to link a highlight group to
4708 another highlight group. See |:highlight-link|.
4709
4710 Returns zero for success, -1 for failure.
4711
4712 Example(s): >
4713 " add bold attribute to the Visual highlight group
4714 :call hlset([#{name: 'Visual',
4715 \ term: #{reverse: 1 , bold: 1}}])
4716 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4717 :let l = hlget()
4718 :call hlset(l)
4719 " clear the Search highlight group
4720 :call hlset([#{name: 'Search', cleared: v:true}])
4721 " clear the 'term' attributes for a highlight group
4722 :call hlset([#{name: 'Title', term: {}}])
4723 " create the MyHlg group linking it to DiffAdd
4724 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4725 " remove the MyHlg group link
4726 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4727 " clear the attributes and a link
4728 :call hlset([#{name: 'MyHlg', cleared: v:true,
4729 \ linksto: 'NONE'}])
4730<
4731 Can also be used as a |method|: >
4732 GetAttrList()->hlset()
4733<
4734 *hlID()*
4735hlID({name}) The result is a Number, which is the ID of the highlight group
4736 with name {name}. When the highlight group doesn't exist,
4737 zero is returned.
4738 This can be used to retrieve information about the highlight
4739 group. For example, to get the background color of the
4740 "Comment" group: >
4741 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4742< *highlightID()*
4743 Obsolete name: highlightID().
4744
4745 Can also be used as a |method|: >
4746 GetName()->hlID()
4747
4748hostname() *hostname()*
4749 The result is a String, which is the name of the machine on
4750 which Vim is currently running. Machine names greater than
4751 256 characters long are truncated.
4752
4753iconv({string}, {from}, {to}) *iconv()*
4754 The result is a String, which is the text {string} converted
4755 from encoding {from} to encoding {to}.
4756 When the conversion completely fails an empty string is
4757 returned. When some characters could not be converted they
4758 are replaced with "?".
4759 The encoding names are whatever the iconv() library function
4760 can accept, see ":!man 3 iconv".
4761 Most conversions require Vim to be compiled with the |+iconv|
4762 feature. Otherwise only UTF-8 to latin1 conversion and back
4763 can be done.
4764 This can be used to display messages with special characters,
4765 no matter what 'encoding' is set to. Write the message in
4766 UTF-8 and use: >
4767 echo iconv(utf8_str, "utf-8", &enc)
4768< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4769 from/to UCS-2 is automatically changed to use UTF-8. You
4770 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4771
4772 Can also be used as a |method|: >
4773 GetText()->iconv('latin1', 'utf-8')
4774<
4775 *indent()*
4776indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4777 current buffer. The indent is counted in spaces, the value
4778 of 'tabstop' is relevant. {lnum} is used just like in
4779 |getline()|.
4780 When {lnum} is invalid -1 is returned. In |Vim9| script an
4781 error is given.
4782
4783 Can also be used as a |method|: >
4784 GetLnum()->indent()
4785
4786index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004787 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004788 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004789
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004790 If {object} is a |List| return the lowest index where the item
4791 has a value equal to {expr}. There is no automatic
4792 conversion, so the String "4" is different from the Number 4.
4793 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004794 of 'ignorecase' is not used here, case matters as indicated by
4795 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004796
4797 If {object} is |Blob| return the lowest index where the byte
4798 value is equal to {expr}.
4799
4800 If {start} is given then start looking at the item with index
4801 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004802
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004803 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4804 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004805
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004806 -1 is returned when {expr} is not found in {object}.
4807 Example: >
4808 :let idx = index(words, "the")
4809 :if index(numbers, 123) >= 0
4810
4811< Can also be used as a |method|: >
4812 GetObject()->index(what)
4813
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004814indexof({object}, {expr} [, {opts}]) *indexof()*
4815 Returns the index of an item in {object} where {expr} is
4816 v:true. {object} must be a |List| or a |Blob|.
4817
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004818 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004819 List until the expression is v:true and return the index of
4820 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004821
4822 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004823 Blob until the expression is v:true and return the index of
4824 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004825
4826 {expr} must be a |string| or |Funcref|.
4827
4828 If {expr} is a |string|: If {object} is a |List|, inside
4829 {expr} |v:key| has the index of the current List item and
4830 |v:val| has the value of the item. If {object} is a |Blob|,
4831 inside {expr} |v:key| has the index of the current byte and
4832 |v:val| has the byte value.
4833
4834 If {expr} is a |Funcref| it must take two arguments:
4835 1. the key or the index of the current item.
4836 2. the value of the current item.
4837 The function must return |TRUE| if the item is found and the
4838 search should stop.
4839
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004840 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004841 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004842 startidx start evaluating {expr} at the item with this
4843 index; may be negative for an item relative to
4844 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004845 Returns -1 when {expr} evaluates to v:false for all the items.
4846 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004847 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
4848 :echo indexof(l, "v:val.n == 20")
4849 :echo indexof(l, {i, v -> v.n == 30})
4850 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004851
4852< Can also be used as a |method|: >
4853 mylist->indexof(expr)
4854
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004855input({prompt} [, {text} [, {completion}]]) *input()*
4856 The result is a String, which is whatever the user typed on
4857 the command-line. The {prompt} argument is either a prompt
4858 string, or a blank string (for no prompt). A '\n' can be used
4859 in the prompt to start a new line.
4860 The highlighting set with |:echohl| is used for the prompt.
4861 The input is entered just like a command-line, with the same
4862 editing commands and mappings. There is a separate history
4863 for lines typed for input().
4864 Example: >
4865 :if input("Coffee or beer? ") == "beer"
4866 : echo "Cheers!"
4867 :endif
4868<
4869 If the optional {text} argument is present and not empty, this
4870 is used for the default reply, as if the user typed this.
4871 Example: >
4872 :let color = input("Color? ", "white")
4873
4874< The optional {completion} argument specifies the type of
4875 completion supported for the input. Without it completion is
4876 not performed. The supported completion types are the same as
4877 that can be supplied to a user-defined command using the
4878 "-complete=" argument. Refer to |:command-completion| for
4879 more information. Example: >
4880 let fname = input("File: ", "", "file")
4881<
4882 NOTE: This function must not be used in a startup file, for
4883 the versions that only run in GUI mode (e.g., the Win32 GUI).
4884 Note: When input() is called from within a mapping it will
4885 consume remaining characters from that mapping, because a
4886 mapping is handled like the characters were typed.
4887 Use |inputsave()| before input() and |inputrestore()|
4888 after input() to avoid that. Another solution is to avoid
4889 that further characters follow in the mapping, e.g., by using
4890 |:execute| or |:normal|.
4891
4892 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004893 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004894 :function GetFoo()
4895 : call inputsave()
4896 : let g:Foo = input("enter search pattern: ")
4897 : call inputrestore()
4898 :endfunction
4899
4900< Can also be used as a |method|: >
4901 GetPrompt()->input()
4902
4903inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4904 Like |input()|, but when the GUI is running and text dialogs
4905 are supported, a dialog window pops up to input the text.
4906 Example: >
4907 :let n = inputdialog("value for shiftwidth", shiftwidth())
4908 :if n != ""
4909 : let &sw = n
4910 :endif
4911< When the dialog is cancelled {cancelreturn} is returned. When
4912 omitted an empty string is returned.
4913 Hitting <Enter> works like pressing the OK button. Hitting
4914 <Esc> works like pressing the Cancel button.
4915 NOTE: Command-line completion is not supported.
4916
4917 Can also be used as a |method|: >
4918 GetPrompt()->inputdialog()
4919
4920inputlist({textlist}) *inputlist()*
4921 {textlist} must be a |List| of strings. This |List| is
4922 displayed, one string per line. The user will be prompted to
4923 enter a number, which is returned.
4924 The user can also select an item by clicking on it with the
4925 mouse, if the mouse is enabled in the command line ('mouse' is
4926 "a" or includes "c"). For the first string 0 is returned.
4927 When clicking above the first item a negative number is
4928 returned. When clicking on the prompt one more than the
4929 length of {textlist} is returned.
4930 Make sure {textlist} has less than 'lines' entries, otherwise
4931 it won't work. It's a good idea to put the entry number at
4932 the start of the string. And put a prompt in the first item.
4933 Example: >
4934 let color = inputlist(['Select color:', '1. red',
4935 \ '2. green', '3. blue'])
4936
4937< Can also be used as a |method|: >
4938 GetChoices()->inputlist()
4939
4940inputrestore() *inputrestore()*
4941 Restore typeahead that was saved with a previous |inputsave()|.
4942 Should be called the same number of times inputsave() is
4943 called. Calling it more often is harmless though.
4944 Returns TRUE when there is nothing to restore, FALSE otherwise.
4945
4946inputsave() *inputsave()*
4947 Preserve typeahead (also from mappings) and clear it, so that
4948 a following prompt gets input from the user. Should be
4949 followed by a matching inputrestore() after the prompt. Can
4950 be used several times, in which case there must be just as
4951 many inputrestore() calls.
4952 Returns TRUE when out of memory, FALSE otherwise.
4953
4954inputsecret({prompt} [, {text}]) *inputsecret()*
4955 This function acts much like the |input()| function with but
4956 two exceptions:
4957 a) the user's response will be displayed as a sequence of
4958 asterisks ("*") thereby keeping the entry secret, and
4959 b) the user's response will not be recorded on the input
4960 |history| stack.
4961 The result is a String, which is whatever the user actually
4962 typed on the command-line in response to the issued prompt.
4963 NOTE: Command-line completion is not supported.
4964
4965 Can also be used as a |method|: >
4966 GetPrompt()->inputsecret()
4967
4968insert({object}, {item} [, {idx}]) *insert()*
4969 When {object} is a |List| or a |Blob| insert {item} at the start
4970 of it.
4971
4972 If {idx} is specified insert {item} before the item with index
4973 {idx}. If {idx} is zero it goes before the first item, just
4974 like omitting {idx}. A negative {idx} is also possible, see
4975 |list-index|. -1 inserts just before the last item.
4976
4977 Returns the resulting |List| or |Blob|. Examples: >
4978 :let mylist = insert([2, 3, 5], 1)
4979 :call insert(mylist, 4, -1)
4980 :call insert(mylist, 6, len(mylist))
4981< The last example can be done simpler with |add()|.
4982 Note that when {item} is a |List| it is inserted as a single
4983 item. Use |extend()| to concatenate |Lists|.
4984
4985 Can also be used as a |method|: >
4986 mylist->insert(item)
4987
4988interrupt() *interrupt()*
4989 Interrupt script execution. It works more or less like the
4990 user typing CTRL-C, most commands won't execute and control
4991 returns to the user. This is useful to abort execution
4992 from lower down, e.g. in an autocommand. Example: >
4993 :function s:check_typoname(file)
4994 : if fnamemodify(a:file, ':t') == '['
4995 : echomsg 'Maybe typo'
4996 : call interrupt()
4997 : endif
4998 :endfunction
4999 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
5000
5001invert({expr}) *invert()*
5002 Bitwise invert. The argument is converted to a number. A
5003 List, Dict or Float argument causes an error. Example: >
5004 :let bits = invert(bits)
5005< Can also be used as a |method|: >
5006 :let bits = bits->invert()
5007
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005008isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005009 The result is a Number, which is |TRUE| when {path} is an
5010 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005011 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005012 On MS-Windows, it is considered absolute when it starts with an
5013 optional drive prefix and is followed by a '\' or '/'. UNC paths
5014 are always absolute.
5015 Example: >
5016 echo isabsolutepath('/usr/share/') " 1
5017 echo isabsolutepath('./foobar') " 0
5018 echo isabsolutepath('C:\Windows') " 1
5019 echo isabsolutepath('foobar') " 0
5020 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005021<
LemonBoydca1d402022-04-28 15:26:33 +01005022 Can also be used as a |method|: >
5023 GetName()->isabsolutepath()
5024
5025
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005026isdirectory({directory}) *isdirectory()*
5027 The result is a Number, which is |TRUE| when a directory
5028 with the name {directory} exists. If {directory} doesn't
5029 exist, or isn't a directory, the result is |FALSE|. {directory}
5030 is any expression, which is used as a String.
5031
5032 Can also be used as a |method|: >
5033 GetName()->isdirectory()
5034
5035isinf({expr}) *isinf()*
5036 Return 1 if {expr} is a positive infinity, or -1 a negative
5037 infinity, otherwise 0. >
5038 :echo isinf(1.0 / 0.0)
5039< 1 >
5040 :echo isinf(-1.0 / 0.0)
5041< -1
5042
5043 Can also be used as a |method|: >
5044 Compute()->isinf()
5045<
5046 {only available when compiled with the |+float| feature}
5047
5048islocked({expr}) *islocked()* *E786*
5049 The result is a Number, which is |TRUE| when {expr} is the
5050 name of a locked variable.
5051 The string argument {expr} must be the name of a variable,
5052 |List| item or |Dictionary| entry, not the variable itself!
5053 Example: >
5054 :let alist = [0, ['a', 'b'], 2, 3]
5055 :lockvar 1 alist
5056 :echo islocked('alist') " 1
5057 :echo islocked('alist[1]') " 0
5058
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005059< When {expr} is a variable that does not exist -1 is returned.
5060 If {expr} uses a range, list or dict index that is out of
5061 range or does not exist you get an error message. Use
5062 |exists()| to check for existence.
5063 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005064
5065 Can also be used as a |method|: >
5066 GetName()->islocked()
5067
5068isnan({expr}) *isnan()*
5069 Return |TRUE| if {expr} is a float with value NaN. >
5070 echo isnan(0.0 / 0.0)
5071< 1
5072
5073 Can also be used as a |method|: >
5074 Compute()->isnan()
5075<
5076 {only available when compiled with the |+float| feature}
5077
5078items({dict}) *items()*
5079 Return a |List| with all the key-value pairs of {dict}. Each
5080 |List| item is a list with two items: the key of a {dict}
5081 entry and the value of this entry. The |List| is in arbitrary
5082 order. Also see |keys()| and |values()|.
5083 Example: >
5084 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005085 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005086 endfor
5087
5088< Can also be used as a |method|: >
5089 mydict->items()
5090
5091job_ functions are documented here: |job-functions-details|
5092
5093
5094join({list} [, {sep}]) *join()*
5095 Join the items in {list} together into one String.
5096 When {sep} is specified it is put in between the items. If
5097 {sep} is omitted a single space is used.
5098 Note that {sep} is not added at the end. You might want to
5099 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005100 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005101< String items are used as-is. |Lists| and |Dictionaries| are
5102 converted into a string like with |string()|.
5103 The opposite function is |split()|.
5104
5105 Can also be used as a |method|: >
5106 mylist->join()
5107
5108js_decode({string}) *js_decode()*
5109 This is similar to |json_decode()| with these differences:
5110 - Object key names do not have to be in quotes.
5111 - Strings can be in single quotes.
5112 - Empty items in an array (between two commas) are allowed and
5113 result in v:none items.
5114
5115 Can also be used as a |method|: >
5116 ReadObject()->js_decode()
5117
5118js_encode({expr}) *js_encode()*
5119 This is similar to |json_encode()| with these differences:
5120 - Object key names are not in quotes.
5121 - v:none items in an array result in an empty item between
5122 commas.
5123 For example, the Vim object:
5124 [1,v:none,{"one":1},v:none] ~
5125 Will be encoded as:
5126 [1,,{one:1},,] ~
5127 While json_encode() would produce:
5128 [1,null,{"one":1},null] ~
5129 This encoding is valid for JavaScript. It is more efficient
5130 than JSON, especially when using an array with optional items.
5131
5132 Can also be used as a |method|: >
5133 GetObject()->js_encode()
5134
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005135json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005136 This parses a JSON formatted string and returns the equivalent
5137 in Vim values. See |json_encode()| for the relation between
5138 JSON and Vim values.
5139 The decoding is permissive:
5140 - A trailing comma in an array and object is ignored, e.g.
5141 "[1, 2, ]" is the same as "[1, 2]".
5142 - Integer keys are accepted in objects, e.g. {1:2} is the
5143 same as {"1":2}.
5144 - More floating point numbers are recognized, e.g. "1." for
5145 "1.0", or "001.2" for "1.2". Special floating point values
5146 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5147 are accepted.
5148 - Leading zeroes in integer numbers are ignored, e.g. "012"
5149 for "12" or "-012" for "-12".
5150 - Capitalization is ignored in literal names null, true or
5151 false, e.g. "NULL" for "null", "True" for "true".
5152 - Control characters U+0000 through U+001F which are not
5153 escaped in strings are accepted, e.g. " " (tab
5154 character in string) for "\t".
5155 - An empty JSON expression or made of only spaces is accepted
5156 and results in v:none.
5157 - Backslash in an invalid 2-character sequence escape is
5158 ignored, e.g. "\a" is decoded as "a".
5159 - A correct surrogate pair in JSON strings should normally be
5160 a 12 character sequence such as "\uD834\uDD1E", but
5161 json_decode() silently accepts truncated surrogate pairs
5162 such as "\uD834" or "\uD834\u"
5163 *E938*
5164 A duplicate key in an object, valid in rfc7159, is not
5165 accepted by json_decode() as the result must be a valid Vim
5166 type, e.g. this fails: {"a":"b", "a":"c"}
5167
5168 Can also be used as a |method|: >
5169 ReadObject()->json_decode()
5170
5171json_encode({expr}) *json_encode()*
5172 Encode {expr} as JSON and return this as a string.
5173 The encoding is specified in:
5174 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005175 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005176 |Number| decimal number
5177 |Float| floating point number
5178 Float nan "NaN"
5179 Float inf "Infinity"
5180 Float -inf "-Infinity"
5181 |String| in double quotes (possibly null)
5182 |Funcref| not possible, error
5183 |List| as an array (possibly null); when
5184 used recursively: []
5185 |Dict| as an object (possibly null); when
5186 used recursively: {}
5187 |Blob| as an array of the individual bytes
5188 v:false "false"
5189 v:true "true"
5190 v:none "null"
5191 v:null "null"
5192 Note that NaN and Infinity are passed on as values. This is
5193 missing in the JSON standard, but several implementations do
5194 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005195 If a string contains an illegal character then the replacement
5196 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005197
5198 Can also be used as a |method|: >
5199 GetObject()->json_encode()
5200
5201keys({dict}) *keys()*
5202 Return a |List| with all the keys of {dict}. The |List| is in
5203 arbitrary order. Also see |items()| and |values()|.
5204
5205 Can also be used as a |method|: >
5206 mydict->keys()
5207
5208< *len()* *E701*
5209len({expr}) The result is a Number, which is the length of the argument.
5210 When {expr} is a String or a Number the length in bytes is
5211 used, as with |strlen()|.
5212 When {expr} is a |List| the number of items in the |List| is
5213 returned.
5214 When {expr} is a |Blob| the number of bytes is returned.
5215 When {expr} is a |Dictionary| the number of entries in the
5216 |Dictionary| is returned.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005217 Otherwise an error is given and returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005218
5219 Can also be used as a |method|: >
5220 mylist->len()
5221
5222< *libcall()* *E364* *E368*
5223libcall({libname}, {funcname}, {argument})
5224 Call function {funcname} in the run-time library {libname}
5225 with single argument {argument}.
5226 This is useful to call functions in a library that you
5227 especially made to be used with Vim. Since only one argument
5228 is possible, calling standard library functions is rather
5229 limited.
5230 The result is the String returned by the function. If the
5231 function returns NULL, this will appear as an empty string ""
5232 to Vim.
5233 If the function returns a number, use libcallnr()!
5234 If {argument} is a number, it is passed to the function as an
5235 int; if {argument} is a string, it is passed as a
5236 null-terminated string.
5237 This function will fail in |restricted-mode|.
5238
5239 libcall() allows you to write your own 'plug-in' extensions to
5240 Vim without having to recompile the program. It is NOT a
5241 means to call system functions! If you try to do so Vim will
5242 very probably crash.
5243
5244 For Win32, the functions you write must be placed in a DLL
5245 and use the normal C calling convention (NOT Pascal which is
5246 used in Windows System DLLs). The function must take exactly
5247 one parameter, either a character pointer or a long integer,
5248 and must return a character pointer or NULL. The character
5249 pointer returned must point to memory that will remain valid
5250 after the function has returned (e.g. in static data in the
5251 DLL). If it points to allocated memory, that memory will
5252 leak away. Using a static buffer in the function should work,
5253 it's then freed when the DLL is unloaded.
5254
5255 WARNING: If the function returns a non-valid pointer, Vim may
5256 crash! This also happens if the function returns a number,
5257 because Vim thinks it's a pointer.
5258 For Win32 systems, {libname} should be the filename of the DLL
5259 without the ".DLL" suffix. A full path is only required if
5260 the DLL is not in the usual places.
5261 For Unix: When compiling your own plugins, remember that the
5262 object code must be compiled as position-independent ('PIC').
5263 {only in Win32 and some Unix versions, when the |+libcall|
5264 feature is present}
5265 Examples: >
5266 :echo libcall("libc.so", "getenv", "HOME")
5267
5268< Can also be used as a |method|, the base is passed as the
5269 third argument: >
5270 GetValue()->libcall("libc.so", "getenv")
5271<
5272 *libcallnr()*
5273libcallnr({libname}, {funcname}, {argument})
5274 Just like |libcall()|, but used for a function that returns an
5275 int instead of a string.
5276 {only in Win32 on some Unix versions, when the |+libcall|
5277 feature is present}
5278 Examples: >
5279 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5280 :call libcallnr("libc.so", "printf", "Hello World!\n")
5281 :call libcallnr("libc.so", "sleep", 10)
5282<
5283 Can also be used as a |method|, the base is passed as the
5284 third argument: >
5285 GetValue()->libcallnr("libc.so", "printf")
5286<
5287
5288line({expr} [, {winid}]) *line()*
5289 The result is a Number, which is the line number of the file
5290 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005291 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005292 . the cursor position
5293 $ the last line in the current buffer
5294 'x position of mark x (if the mark is not set, 0 is
5295 returned)
5296 w0 first line visible in current window (one if the
5297 display isn't updated, e.g. in silent Ex mode)
5298 w$ last line visible in current window (this is one
5299 less than "w0" if no lines are visible)
5300 v In Visual mode: the start of the Visual area (the
5301 cursor is the end). When not in Visual mode
5302 returns the cursor position. Differs from |'<| in
5303 that it's updated right away.
5304 Note that a mark in another file can be used. The line number
5305 then applies to another buffer.
5306 To get the column number use |col()|. To get both use
5307 |getpos()|.
5308 With the optional {winid} argument the values are obtained for
5309 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005310 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005311 Examples: >
5312 line(".") line number of the cursor
5313 line(".", winid) idem, in window "winid"
5314 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005315 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005316<
5317 To jump to the last known position when opening a file see
5318 |last-position-jump|.
5319
5320 Can also be used as a |method|: >
5321 GetValue()->line()
5322
5323line2byte({lnum}) *line2byte()*
5324 Return the byte count from the start of the buffer for line
5325 {lnum}. This includes the end-of-line character, depending on
5326 the 'fileformat' option for the current buffer. The first
5327 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5328 This can also be used to get the byte count for the line just
5329 below the last line: >
5330 line2byte(line("$") + 1)
5331< This is the buffer size plus one. If 'fileencoding' is empty
5332 it is the file size plus one. {lnum} is used like with
5333 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5334 feature has been disabled at compile time, -1 is returned.
5335 Also see |byte2line()|, |go| and |:goto|.
5336
5337 Can also be used as a |method|: >
5338 GetLnum()->line2byte()
5339
5340lispindent({lnum}) *lispindent()*
5341 Get the amount of indent for line {lnum} according the lisp
5342 indenting rules, as with 'lisp'.
5343 The indent is counted in spaces, the value of 'tabstop' is
5344 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005345 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005346 error is given.
5347
5348 Can also be used as a |method|: >
5349 GetLnum()->lispindent()
5350
5351list2blob({list}) *list2blob()*
5352 Return a Blob concatenating all the number values in {list}.
5353 Examples: >
5354 list2blob([1, 2, 3, 4]) returns 0z01020304
5355 list2blob([]) returns 0z
5356< Returns an empty Blob on error. If one of the numbers is
5357 negative or more than 255 error *E1239* is given.
5358
5359 |blob2list()| does the opposite.
5360
5361 Can also be used as a |method|: >
5362 GetList()->list2blob()
5363
5364list2str({list} [, {utf8}]) *list2str()*
5365 Convert each number in {list} to a character string can
5366 concatenate them all. Examples: >
5367 list2str([32]) returns " "
5368 list2str([65, 66, 67]) returns "ABC"
5369< The same can be done (slowly) with: >
5370 join(map(list, {nr, val -> nr2char(val)}), '')
5371< |str2list()| does the opposite.
5372
5373 When {utf8} is omitted or zero, the current 'encoding' is used.
5374 When {utf8} is TRUE, always return UTF-8 characters.
5375 With UTF-8 composing characters work as expected: >
5376 list2str([97, 769]) returns "á"
5377<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005378 Returns an empty string on error.
5379
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005380 Can also be used as a |method|: >
5381 GetList()->list2str()
5382
5383listener_add({callback} [, {buf}]) *listener_add()*
5384 Add a callback function that will be invoked when changes have
5385 been made to buffer {buf}.
5386 {buf} refers to a buffer name or number. For the accepted
5387 values, see |bufname()|. When {buf} is omitted the current
5388 buffer is used.
5389 Returns a unique ID that can be passed to |listener_remove()|.
5390
5391 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005392 bufnr the buffer that was changed
5393 start first changed line number
5394 end first line number below the change
5395 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005396 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005397 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005398
5399 Example: >
5400 func Listener(bufnr, start, end, added, changes)
5401 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5402 endfunc
5403 call listener_add('Listener', bufnr)
5404
Bram Moolenaar944697a2022-02-20 19:48:20 +00005405< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005406 dictionary with these entries:
5407 lnum the first line number of the change
5408 end the first line below the change
5409 added number of lines added; negative if lines were
5410 deleted
5411 col first column in "lnum" that was affected by
5412 the change; one if unknown or the whole line
5413 was affected; this is a byte index, first
5414 character has a value of one.
5415 When lines are inserted the values are:
5416 lnum line above which the new line is added
5417 end equal to "lnum"
5418 added number of lines inserted
5419 col 1
5420 When lines are deleted the values are:
5421 lnum the first deleted line
5422 end the line below the first deleted line, before
5423 the deletion was done
5424 added negative, number of lines deleted
5425 col 1
5426 When lines are changed:
5427 lnum the first changed line
5428 end the line below the last changed line
5429 added 0
5430 col first column with a change or 1
5431
5432 The entries are in the order the changes were made, thus the
5433 most recent change is at the end. The line numbers are valid
5434 when the callback is invoked, but later changes may make them
5435 invalid, thus keeping a copy for later might not work.
5436
5437 The {callback} is invoked just before the screen is updated,
5438 when |listener_flush()| is called or when a change is being
5439 made that changes the line count in a way it causes a line
5440 number in the list of changes to become invalid.
5441
5442 The {callback} is invoked with the text locked, see
5443 |textlock|. If you do need to make changes to the buffer, use
5444 a timer to do this later |timer_start()|.
5445
5446 The {callback} is not invoked when the buffer is first loaded.
5447 Use the |BufReadPost| autocmd event to handle the initial text
5448 of a buffer.
5449 The {callback} is also not invoked when the buffer is
5450 unloaded, use the |BufUnload| autocmd event for that.
5451
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005452 Returns zero if {callback} or {buf} is invalid.
5453
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005454 Can also be used as a |method|, the base is passed as the
5455 second argument: >
5456 GetBuffer()->listener_add(callback)
5457
5458listener_flush([{buf}]) *listener_flush()*
5459 Invoke listener callbacks for buffer {buf}. If there are no
5460 pending changes then no callbacks are invoked.
5461
5462 {buf} refers to a buffer name or number. For the accepted
5463 values, see |bufname()|. When {buf} is omitted the current
5464 buffer is used.
5465
5466 Can also be used as a |method|: >
5467 GetBuffer()->listener_flush()
5468
5469listener_remove({id}) *listener_remove()*
5470 Remove a listener previously added with listener_add().
5471 Returns FALSE when {id} could not be found, TRUE when {id} was
5472 removed.
5473
5474 Can also be used as a |method|: >
5475 GetListenerId()->listener_remove()
5476
5477localtime() *localtime()*
5478 Return the current time, measured as seconds since 1st Jan
5479 1970. See also |strftime()|, |strptime()| and |getftime()|.
5480
5481
5482log({expr}) *log()*
5483 Return the natural logarithm (base e) of {expr} as a |Float|.
5484 {expr} must evaluate to a |Float| or a |Number| in the range
5485 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005486 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005487 Examples: >
5488 :echo log(10)
5489< 2.302585 >
5490 :echo log(exp(5))
5491< 5.0
5492
5493 Can also be used as a |method|: >
5494 Compute()->log()
5495<
5496 {only available when compiled with the |+float| feature}
5497
5498
5499log10({expr}) *log10()*
5500 Return the logarithm of Float {expr} to base 10 as a |Float|.
5501 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005502 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005503 Examples: >
5504 :echo log10(1000)
5505< 3.0 >
5506 :echo log10(0.01)
5507< -2.0
5508
5509 Can also be used as a |method|: >
5510 Compute()->log10()
5511<
5512 {only available when compiled with the |+float| feature}
5513
5514luaeval({expr} [, {expr}]) *luaeval()*
5515 Evaluate Lua expression {expr} and return its result converted
5516 to Vim data structures. Second {expr} may hold additional
5517 argument accessible as _A inside first {expr}.
5518 Strings are returned as they are.
5519 Boolean objects are converted to numbers.
5520 Numbers are converted to |Float| values if vim was compiled
5521 with |+float| and to numbers otherwise.
5522 Dictionaries and lists obtained by vim.eval() are returned
5523 as-is.
5524 Other objects are returned as zero without any errors.
5525 See |lua-luaeval| for more details.
5526 Note that in a `:def` function local variables are not visible
5527 to {expr}.
5528
5529 Can also be used as a |method|: >
5530 GetExpr()->luaeval()
5531
5532< {only available when compiled with the |+lua| feature}
5533
5534map({expr1}, {expr2}) *map()*
5535 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005536 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005537 item in {expr1} with the result of evaluating {expr2}.
5538 For a |Blob| each byte is replaced.
5539 For a |String|, each character, including composing
5540 characters, is replaced.
5541 If the item type changes you may want to use |mapnew()| to
5542 create a new List or Dictionary. This is required when using
5543 Vim9 script.
5544
5545 {expr2} must be a |String| or |Funcref|.
5546
5547 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5548 of the current item. For a |Dictionary| |v:key| has the key
5549 of the current item and for a |List| |v:key| has the index of
5550 the current item. For a |Blob| |v:key| has the index of the
5551 current byte. For a |String| |v:key| has the index of the
5552 current character.
5553 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005554 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005555< This puts "> " before and " <" after each item in "mylist".
5556
5557 Note that {expr2} is the result of an expression and is then
5558 used as an expression again. Often it is good to use a
5559 |literal-string| to avoid having to double backslashes. You
5560 still have to double ' quotes
5561
5562 If {expr2} is a |Funcref| it is called with two arguments:
5563 1. The key or the index of the current item.
5564 2. the value of the current item.
5565 The function must return the new value of the item. Example
5566 that changes each value by "key-value": >
5567 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005568 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005569 endfunc
5570 call map(myDict, function('KeyValue'))
5571< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005572 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005573< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005574 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005575< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005576 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005577<
5578 The operation is done in-place for a |List| and |Dictionary|.
5579 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005580 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005581
5582< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5583 or a new |Blob| or |String|.
5584 When an error is encountered while evaluating {expr2} no
5585 further items in {expr1} are processed.
5586 When {expr2} is a Funcref errors inside a function are ignored,
5587 unless it was defined with the "abort" flag.
5588
5589 Can also be used as a |method|: >
5590 mylist->map(expr2)
5591
5592
5593maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5594 When {dict} is omitted or zero: Return the rhs of mapping
5595 {name} in mode {mode}. The returned String has special
5596 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005597 listing. When {dict} is TRUE a dictionary is returned, see
5598 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005599
5600 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005601 returned if {dict} is FALSE, otherwise returns an empty Dict.
5602 When the mapping for {name} is empty, then "<Nop>" is
5603 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005604
5605 The {name} can have special key names, like in the ":map"
5606 command.
5607
5608 {mode} can be one of these strings:
5609 "n" Normal
5610 "v" Visual (including Select)
5611 "o" Operator-pending
5612 "i" Insert
5613 "c" Cmd-line
5614 "s" Select
5615 "x" Visual
5616 "l" langmap |language-mapping|
5617 "t" Terminal-Job
5618 "" Normal, Visual and Operator-pending
5619 When {mode} is omitted, the modes for "" are used.
5620
5621 When {abbr} is there and it is |TRUE| use abbreviations
5622 instead of mappings.
5623
5624 When {dict} is there and it is |TRUE| return a dictionary
5625 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005626 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005627 "lhs" The {lhs} of the mapping as it would be typed
5628 "lhsraw" The {lhs} of the mapping as raw bytes
5629 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5630 form, only present when it differs from "lhsraw"
5631 "rhs" The {rhs} of the mapping as typed.
5632 "silent" 1 for a |:map-silent| mapping, else 0.
5633 "noremap" 1 if the {rhs} of the mapping is not remappable.
5634 "script" 1 if mapping was defined with <script>.
5635 "expr" 1 for an expression mapping (|:map-<expr>|).
5636 "buffer" 1 for a buffer local mapping (|:map-local|).
5637 "mode" Modes for which the mapping is defined. In
5638 addition to the modes mentioned above, these
5639 characters will be used:
5640 " " Normal, Visual and Operator-pending
5641 "!" Insert and Commandline mode
5642 (|mapmode-ic|)
5643 "sid" The script local ID, used for <sid> mappings
5644 (|<SID>|).
Bram Moolenaara9528b32022-01-18 20:51:35 +00005645 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005646 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005647 "lnum" The line number in "sid", zero if unknown.
5648 "nowait" Do not wait for other, longer mappings.
5649 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005650 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005651 "mode_bits" Vim's internal binary representation of "mode".
5652 |mapset()| ignores this; only "mode" is used.
5653 See |maplist()| for usage examples. The values
5654 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005655
5656 The dictionary can be used to restore a mapping with
5657 |mapset()|.
5658
5659 The mappings local to the current buffer are checked first,
5660 then the global mappings.
5661 This function can be used to map a key even when it's already
5662 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005663 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005664
5665< Can also be used as a |method|: >
5666 GetKey()->maparg('n')
5667
5668mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5669 Check if there is a mapping that matches with {name} in mode
5670 {mode}. See |maparg()| for {mode} and special names in
5671 {name}.
5672 When {abbr} is there and it is |TRUE| use abbreviations
5673 instead of mappings.
5674 A match happens with a mapping that starts with {name} and
5675 with a mapping which is equal to the start of {name}.
5676
5677 matches mapping "a" "ab" "abc" ~
5678 mapcheck("a") yes yes yes
5679 mapcheck("abc") yes yes yes
5680 mapcheck("ax") yes no no
5681 mapcheck("b") no no no
5682
5683 The difference with maparg() is that mapcheck() finds a
5684 mapping that matches with {name}, while maparg() only finds a
5685 mapping for {name} exactly.
5686 When there is no mapping that starts with {name}, an empty
5687 String is returned. If there is one, the RHS of that mapping
5688 is returned. If there are several mappings that start with
5689 {name}, the RHS of one of them is returned. This will be
5690 "<Nop>" if the RHS is empty.
5691 The mappings local to the current buffer are checked first,
5692 then the global mappings.
5693 This function can be used to check if a mapping can be added
5694 without being ambiguous. Example: >
5695 :if mapcheck("_vv") == ""
5696 : map _vv :set guifont=7x13<CR>
5697 :endif
5698< This avoids adding the "_vv" mapping when there already is a
5699 mapping for "_v" or for "_vvv".
5700
5701 Can also be used as a |method|: >
5702 GetKey()->mapcheck('n')
5703
5704
Ernie Rael09661202022-04-25 14:40:44 +01005705maplist([{abbr}]) *maplist()*
5706 Returns a |List| of all mappings. Each List item is a |Dict|,
5707 the same as what is returned by |maparg()|, see
5708 |mapping-dict|. When {abbr} is there and it is |TRUE| use
5709 abbreviations instead of mappings.
5710
5711 Example to show all mappings with 'MultiMatch' in rhs: >
5712 vim9script
5713 echo maplist()->filter(
5714 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01005715< It can be tricky to find mappings for particular |:map-modes|.
5716 |mapping-dict|'s "mode_bits" can simplify this. For example,
5717 the mode_bits for Normal, Insert or Command-line modes are
5718 0x19. To find all the mappings available in those modes you
5719 can do: >
5720 vim9script
5721 var saved_maps = []
5722 for m in maplist()
5723 if and(m.mode_bits, 0x19) != 0
5724 saved_maps->add(m)
5725 endif
5726 endfor
5727 echo saved_maps->mapnew((_, m) => m.lhs)
5728< The values of the mode_bits are defined in Vim's src/vim.h
5729 file and they can be discovered at runtime using
5730 |:map-commands| and "maplist()". Example: >
5731 vim9script
5732 omap xyzzy <Nop>
5733 var op_bit = maplist()->filter(
5734 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
5735 ounmap xyzzy
5736 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01005737
5738
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005739mapnew({expr1}, {expr2}) *mapnew()*
5740 Like |map()| but instead of replacing items in {expr1} a new
5741 List or Dictionary is created and returned. {expr1} remains
5742 unchanged. Items can still be changed by {expr2}, if you
5743 don't want that use |deepcopy()| first.
5744
5745
5746mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01005747mapset({dict})
5748 Restore a mapping from a dictionary, possibly returned by
5749 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
5750 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005751 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01005752 feature allows copying mappings from one buffer to another.
5753 The dict.mode value may restore a single mapping that covers
5754 more than one mode, like with mode values of '!', ' ', 'nox',
5755 or 'v'. *E1276*
5756
5757 In the first form, {mode} and {abbr} should be the same as
5758 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005759 {mode} is used to define the mode in which the mapping is set,
5760 not the "mode" entry in {dict}.
5761 Example for saving and restoring a mapping: >
5762 let save_map = maparg('K', 'n', 0, 1)
5763 nnoremap K somethingelse
5764 ...
5765 call mapset('n', 0, save_map)
5766< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01005767 e.g. with `:map!`, you need to save/restore the mapping for
5768 all of them, when they might differ.
5769
5770 In the second form, with {dict} as the only argument, mode
5771 and abbr are taken from the dict.
5772 Example: >
5773 vim9script
5774 var save_maps = maplist()->filter(
5775 (_, m) => m.lhs == 'K')
5776 nnoremap K somethingelse
5777 cnoremap K somethingelse2
5778 # ...
5779 unmap K
5780 for d in save_maps
5781 mapset(d)
5782 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005783
5784
5785match({expr}, {pat} [, {start} [, {count}]]) *match()*
5786 When {expr} is a |List| then this returns the index of the
5787 first item where {pat} matches. Each item is used as a
5788 String, |Lists| and |Dictionaries| are used as echoed.
5789
5790 Otherwise, {expr} is used as a String. The result is a
5791 Number, which gives the index (byte offset) in {expr} where
5792 {pat} matches.
5793
5794 A match at the first character or |List| item returns zero.
5795 If there is no match -1 is returned.
5796
5797 For getting submatches see |matchlist()|.
5798 Example: >
5799 :echo match("testing", "ing") " results in 4
5800 :echo match([1, 'x'], '\a') " results in 1
5801< See |string-match| for how {pat} is used.
5802 *strpbrk()*
5803 Vim doesn't have a strpbrk() function. But you can do: >
5804 :let sepidx = match(line, '[.,;: \t]')
5805< *strcasestr()*
5806 Vim doesn't have a strcasestr() function. But you can add
5807 "\c" to the pattern to ignore case: >
5808 :let idx = match(haystack, '\cneedle')
5809<
5810 If {start} is given, the search starts from byte index
5811 {start} in a String or item {start} in a |List|.
5812 The result, however, is still the index counted from the
5813 first character/item. Example: >
5814 :echo match("testing", "ing", 2)
5815< result is again "4". >
5816 :echo match("testing", "ing", 4)
5817< result is again "4". >
5818 :echo match("testing", "t", 2)
5819< result is "3".
5820 For a String, if {start} > 0 then it is like the string starts
5821 {start} bytes later, thus "^" will match at {start}. Except
5822 when {count} is given, then it's like matches before the
5823 {start} byte are ignored (this is a bit complicated to keep it
5824 backwards compatible).
5825 For a String, if {start} < 0, it will be set to 0. For a list
5826 the index is counted from the end.
5827 If {start} is out of range ({start} > strlen({expr}) for a
5828 String or {start} > len({expr}) for a |List|) -1 is returned.
5829
5830 When {count} is given use the {count}'th match. When a match
5831 is found in a String the search for the next one starts one
5832 character further. Thus this example results in 1: >
5833 echo match("testing", "..", 0, 2)
5834< In a |List| the search continues in the next item.
5835 Note that when {count} is added the way {start} works changes,
5836 see above.
5837
5838 See |pattern| for the patterns that are accepted.
5839 The 'ignorecase' option is used to set the ignore-caseness of
5840 the pattern. 'smartcase' is NOT used. The matching is always
5841 done like 'magic' is set and 'cpoptions' is empty.
5842 Note that a match at the start is preferred, thus when the
5843 pattern is using "*" (any number of matches) it tends to find
5844 zero matches at the start instead of a number of matches
5845 further down in the text.
5846
5847 Can also be used as a |method|: >
5848 GetText()->match('word')
5849 GetList()->match('word')
5850<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005851 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005852matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5853 Defines a pattern to be highlighted in the current window (a
5854 "match"). It will be highlighted with {group}. Returns an
5855 identification number (ID), which can be used to delete the
5856 match using |matchdelete()|. The ID is bound to the window.
5857 Matching is case sensitive and magic, unless case sensitivity
5858 or magicness are explicitly overridden in {pattern}. The
5859 'magic', 'smartcase' and 'ignorecase' options are not used.
5860 The "Conceal" value is special, it causes the match to be
5861 concealed.
5862
5863 The optional {priority} argument assigns a priority to the
5864 match. A match with a high priority will have its
5865 highlighting overrule that of a match with a lower priority.
5866 A priority is specified as an integer (negative numbers are no
5867 exception). If the {priority} argument is not specified, the
5868 default priority is 10. The priority of 'hlsearch' is zero,
5869 hence all matches with a priority greater than zero will
5870 overrule it. Syntax highlighting (see 'syntax') is a separate
5871 mechanism, and regardless of the chosen priority a match will
5872 always overrule syntax highlighting.
5873
5874 The optional {id} argument allows the request for a specific
5875 match ID. If a specified ID is already taken, an error
5876 message will appear and the match will not be added. An ID
5877 is specified as a positive integer (zero excluded). IDs 1, 2
5878 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01005879 respectively. 3 is reserved for use by the |matchparen|
5880 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005881 If the {id} argument is not specified or -1, |matchadd()|
5882 automatically chooses a free ID.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005883
5884 The optional {dict} argument allows for further custom
5885 values. Currently this is used to specify a match specific
5886 conceal character that will be shown for |hl-Conceal|
5887 highlighted matches. The dict can have the following members:
5888
5889 conceal Special character to show instead of the
5890 match (only for |hl-Conceal| highlighted
5891 matches, see |:syn-cchar|)
5892 window Instead of the current window use the
5893 window with this number or window ID.
5894
5895 The number of matches is not limited, as it is the case with
5896 the |:match| commands.
5897
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005898 Returns -1 on error.
5899
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005900 Example: >
5901 :highlight MyGroup ctermbg=green guibg=green
5902 :let m = matchadd("MyGroup", "TODO")
5903< Deletion of the pattern: >
5904 :call matchdelete(m)
5905
5906< A list of matches defined by |matchadd()| and |:match| are
5907 available from |getmatches()|. All matches can be deleted in
5908 one operation by |clearmatches()|.
5909
5910 Can also be used as a |method|: >
5911 GetGroup()->matchadd('TODO')
5912<
5913 *matchaddpos()*
5914matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5915 Same as |matchadd()|, but requires a list of positions {pos}
5916 instead of a pattern. This command is faster than |matchadd()|
5917 because it does not require to handle regular expressions and
5918 sets buffer line boundaries to redraw screen. It is supposed
5919 to be used when fast match additions and deletions are
5920 required, for example to highlight matching parentheses.
5921
5922 {pos} is a list of positions. Each position can be one of
5923 these:
5924 - A number. This whole line will be highlighted. The first
5925 line has number 1.
5926 - A list with one number, e.g., [23]. The whole line with this
5927 number will be highlighted.
5928 - A list with two numbers, e.g., [23, 11]. The first number is
5929 the line number, the second one is the column number (first
5930 column is 1, the value must correspond to the byte index as
5931 |col()| would return). The character at this position will
5932 be highlighted.
5933 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5934 the third number gives the length of the highlight in bytes.
5935
5936 The maximum number of positions in {pos} is 8.
5937
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005938 Returns -1 on error.
5939
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005940 Example: >
5941 :highlight MyGroup ctermbg=green guibg=green
5942 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5943< Deletion of the pattern: >
5944 :call matchdelete(m)
5945
5946< Matches added by |matchaddpos()| are returned by
5947 |getmatches()|.
5948
5949 Can also be used as a |method|: >
5950 GetGroup()->matchaddpos([23, 11])
5951
5952matcharg({nr}) *matcharg()*
5953 Selects the {nr} match item, as set with a |:match|,
5954 |:2match| or |:3match| command.
5955 Return a |List| with two elements:
5956 The name of the highlight group used
5957 The pattern used.
5958 When {nr} is not 1, 2 or 3 returns an empty |List|.
5959 When there is no match item set returns ['', ''].
5960 This is useful to save and restore a |:match|.
5961 Highlighting matches using the |:match| commands are limited
5962 to three matches. |matchadd()| does not have this limitation.
5963
5964 Can also be used as a |method|: >
5965 GetMatch()->matcharg()
5966
5967matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5968 Deletes a match with ID {id} previously defined by |matchadd()|
5969 or one of the |:match| commands. Returns 0 if successful,
5970 otherwise -1. See example for |matchadd()|. All matches can
5971 be deleted in one operation by |clearmatches()|.
5972 If {win} is specified, use the window with this number or
5973 window ID instead of the current window.
5974
5975 Can also be used as a |method|: >
5976 GetMatch()->matchdelete()
5977
5978matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5979 Same as |match()|, but return the index of first character
5980 after the match. Example: >
5981 :echo matchend("testing", "ing")
5982< results in "7".
5983 *strspn()* *strcspn()*
5984 Vim doesn't have a strspn() or strcspn() function, but you can
5985 do it with matchend(): >
5986 :let span = matchend(line, '[a-zA-Z]')
5987 :let span = matchend(line, '[^a-zA-Z]')
5988< Except that -1 is returned when there are no matches.
5989
5990 The {start}, if given, has the same meaning as for |match()|. >
5991 :echo matchend("testing", "ing", 2)
5992< results in "7". >
5993 :echo matchend("testing", "ing", 5)
5994< result is "-1".
5995 When {expr} is a |List| the result is equal to |match()|.
5996
5997 Can also be used as a |method|: >
5998 GetText()->matchend('word')
5999
6000
6001matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
6002 If {list} is a list of strings, then returns a |List| with all
6003 the strings in {list} that fuzzy match {str}. The strings in
6004 the returned list are sorted based on the matching score.
6005
6006 The optional {dict} argument always supports the following
6007 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01006008 matchseq When this item is present return only matches
6009 that contain the characters in {str} in the
6010 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01006011 limit Maximum number of matches in {list} to be
6012 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006013
6014 If {list} is a list of dictionaries, then the optional {dict}
6015 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006016 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006017 {str}. The value of this item should be a
6018 string.
6019 text_cb |Funcref| that will be called for every item
6020 in {list} to get the text for fuzzy matching.
6021 This should accept a dictionary item as the
6022 argument and return the text for that item to
6023 use for fuzzy matching.
6024
6025 {str} is treated as a literal string and regular expression
6026 matching is NOT supported. The maximum supported {str} length
6027 is 256.
6028
6029 When {str} has multiple words each separated by white space,
6030 then the list of strings that have all the words is returned.
6031
6032 If there are no matching strings or there is an error, then an
6033 empty list is returned. If length of {str} is greater than
6034 256, then returns an empty list.
6035
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006036 When {limit} is given, matchfuzzy() will find up to this
6037 number of matches in {list} and return them in sorted order.
6038
Bram Moolenaar1588bc82022-03-08 21:35:07 +00006039 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006040 matching strings.
6041
6042 Example: >
6043 :echo matchfuzzy(["clay", "crow"], "cay")
6044< results in ["clay"]. >
6045 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
6046< results in a list of buffer names fuzzy matching "ndl". >
6047 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
6048< results in a list of buffer information dicts with buffer
6049 names fuzzy matching "ndl". >
6050 :echo getbufinfo()->matchfuzzy("spl",
6051 \ {'text_cb' : {v -> v.name}})
6052< results in a list of buffer information dicts with buffer
6053 names fuzzy matching "spl". >
6054 :echo v:oldfiles->matchfuzzy("test")
6055< results in a list of file names fuzzy matching "test". >
6056 :let l = readfile("buffer.c")->matchfuzzy("str")
6057< results in a list of lines in "buffer.c" fuzzy matching "str". >
6058 :echo ['one two', 'two one']->matchfuzzy('two one')
6059< results in ['two one', 'one two']. >
6060 :echo ['one two', 'two one']->matchfuzzy('two one',
6061 \ {'matchseq': 1})
6062< results in ['two one'].
6063
6064matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6065 Same as |matchfuzzy()|, but returns the list of matched
6066 strings, the list of character positions where characters
6067 in {str} matches and a list of matching scores. You can
6068 use |byteidx()| to convert a character position to a byte
6069 position.
6070
6071 If {str} matches multiple times in a string, then only the
6072 positions for the best match is returned.
6073
6074 If there are no matching strings or there is an error, then a
6075 list with three empty list items is returned.
6076
6077 Example: >
6078 :echo matchfuzzypos(['testing'], 'tsg')
6079< results in [['testing'], [[0, 2, 6]], [99]] >
6080 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6081< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6082 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6083< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6084
6085matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6086 Same as |match()|, but return a |List|. The first item in the
6087 list is the matched string, same as what matchstr() would
6088 return. Following items are submatches, like "\1", "\2", etc.
6089 in |:substitute|. When an optional submatch didn't match an
6090 empty string is used. Example: >
6091 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6092< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6093 When there is no match an empty list is returned.
6094
6095 You can pass in a List, but that is not very useful.
6096
6097 Can also be used as a |method|: >
6098 GetText()->matchlist('word')
6099
6100matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6101 Same as |match()|, but return the matched string. Example: >
6102 :echo matchstr("testing", "ing")
6103< results in "ing".
6104 When there is no match "" is returned.
6105 The {start}, if given, has the same meaning as for |match()|. >
6106 :echo matchstr("testing", "ing", 2)
6107< results in "ing". >
6108 :echo matchstr("testing", "ing", 5)
6109< result is "".
6110 When {expr} is a |List| then the matching item is returned.
6111 The type isn't changed, it's not necessarily a String.
6112
6113 Can also be used as a |method|: >
6114 GetText()->matchstr('word')
6115
6116matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6117 Same as |matchstr()|, but return the matched string, the start
6118 position and the end position of the match. Example: >
6119 :echo matchstrpos("testing", "ing")
6120< results in ["ing", 4, 7].
6121 When there is no match ["", -1, -1] is returned.
6122 The {start}, if given, has the same meaning as for |match()|. >
6123 :echo matchstrpos("testing", "ing", 2)
6124< results in ["ing", 4, 7]. >
6125 :echo matchstrpos("testing", "ing", 5)
6126< result is ["", -1, -1].
6127 When {expr} is a |List| then the matching item, the index
6128 of first item where {pat} matches, the start position and the
6129 end position of the match are returned. >
6130 :echo matchstrpos([1, '__x'], '\a')
6131< result is ["x", 1, 2, 3].
6132 The type isn't changed, it's not necessarily a String.
6133
6134 Can also be used as a |method|: >
6135 GetText()->matchstrpos('word')
6136<
6137
6138 *max()*
6139max({expr}) Return the maximum value of all items in {expr}. Example: >
6140 echo max([apples, pears, oranges])
6141
6142< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6143 it returns the maximum of all values in the Dictionary.
6144 If {expr} is neither a List nor a Dictionary, or one of the
6145 items in {expr} cannot be used as a Number this results in
6146 an error. An empty |List| or |Dictionary| results in zero.
6147
6148 Can also be used as a |method|: >
6149 mylist->max()
6150
6151
6152menu_info({name} [, {mode}]) *menu_info()*
6153 Return information about the specified menu {name} in
6154 mode {mode}. The menu name should be specified without the
6155 shortcut character ('&'). If {name} is "", then the top-level
6156 menu names are returned.
6157
6158 {mode} can be one of these strings:
6159 "n" Normal
6160 "v" Visual (including Select)
6161 "o" Operator-pending
6162 "i" Insert
6163 "c" Cmd-line
6164 "s" Select
6165 "x" Visual
6166 "t" Terminal-Job
6167 "" Normal, Visual and Operator-pending
6168 "!" Insert and Cmd-line
6169 When {mode} is omitted, the modes for "" are used.
6170
6171 Returns a |Dictionary| containing the following items:
6172 accel menu item accelerator text |menu-text|
6173 display display name (name without '&')
6174 enabled v:true if this menu item is enabled
6175 Refer to |:menu-enable|
6176 icon name of the icon file (for toolbar)
6177 |toolbar-icon|
6178 iconidx index of a built-in icon
6179 modes modes for which the menu is defined. In
6180 addition to the modes mentioned above, these
6181 characters will be used:
6182 " " Normal, Visual and Operator-pending
6183 name menu item name.
6184 noremenu v:true if the {rhs} of the menu item is not
6185 remappable else v:false.
6186 priority menu order priority |menu-priority|
6187 rhs right-hand-side of the menu item. The returned
6188 string has special characters translated like
6189 in the output of the ":menu" command listing.
6190 When the {rhs} of a menu item is empty, then
6191 "<Nop>" is returned.
6192 script v:true if script-local remapping of {rhs} is
6193 allowed else v:false. See |:menu-script|.
6194 shortcut shortcut key (character after '&' in
6195 the menu name) |menu-shortcut|
6196 silent v:true if the menu item is created
6197 with <silent> argument |:menu-silent|
6198 submenus |List| containing the names of
6199 all the submenus. Present only if the menu
6200 item has submenus.
6201
6202 Returns an empty dictionary if the menu item is not found.
6203
6204 Examples: >
6205 :echo menu_info('Edit.Cut')
6206 :echo menu_info('File.Save', 'n')
6207
6208 " Display the entire menu hierarchy in a buffer
6209 func ShowMenu(name, pfx)
6210 let m = menu_info(a:name)
6211 call append(line('$'), a:pfx .. m.display)
6212 for child in m->get('submenus', [])
6213 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6214 \ a:pfx .. ' ')
6215 endfor
6216 endfunc
6217 new
6218 for topmenu in menu_info('').submenus
6219 call ShowMenu(topmenu, '')
6220 endfor
6221<
6222 Can also be used as a |method|: >
6223 GetMenuName()->menu_info('v')
6224
6225
6226< *min()*
6227min({expr}) Return the minimum value of all items in {expr}. Example: >
6228 echo min([apples, pears, oranges])
6229
6230< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6231 it returns the minimum of all values in the Dictionary.
6232 If {expr} is neither a List nor a Dictionary, or one of the
6233 items in {expr} cannot be used as a Number this results in
6234 an error. An empty |List| or |Dictionary| results in zero.
6235
6236 Can also be used as a |method|: >
6237 mylist->min()
6238
6239< *mkdir()* *E739*
6240mkdir({name} [, {path} [, {prot}]])
6241 Create directory {name}.
6242
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006243 If {path} contains "p" then intermediate directories are
6244 created as necessary. Otherwise it must be "".
6245
6246 If {path} contains "D" then {name} is deleted at the end of
6247 the current function, as with: >
6248 defer delete({name}, 'd')
6249<
6250 If {path} contains "R" then {name} is deleted recursively at
6251 the end of the current function, as with: >
6252 defer delete({name}, 'rf')
6253< Note that when {name} has more than one part and "p" is used
6254 some directories may already exist. Only the first one that
6255 is created and what it contains is scheduled to be deleted.
6256 E.g. when using: >
6257 call mkdir('subdir/tmp/autoload', 'pR')
6258< and "subdir" already exists then "subdir/tmp" will be
6259 scheduled for deletion, like with: >
6260 defer delete('subdir/tmp', 'rf')
6261< Note that if scheduling the defer fails the directory is not
6262 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006263
6264 If {prot} is given it is used to set the protection bits of
6265 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6266 the user, readable for others). Use 0o700 to make it
6267 unreadable for others. This is only used for the last part of
6268 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6269 created with 0o755.
6270 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006271 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006272
6273< This function is not available in the |sandbox|.
6274
6275 There is no error if the directory already exists and the "p"
6276 flag is passed (since patch 8.0.1708). However, without the
6277 "p" option the call will fail.
6278
6279 The function result is a Number, which is TRUE if the call was
6280 successful or FALSE if the directory creation failed or partly
6281 failed.
6282
6283 Not available on all systems. To check use: >
6284 :if exists("*mkdir")
6285
6286< Can also be used as a |method|: >
6287 GetName()->mkdir()
6288<
6289 *mode()*
6290mode([expr]) Return a string that indicates the current mode.
6291 If [expr] is supplied and it evaluates to a non-zero Number or
6292 a non-empty String (|non-zero-arg|), then the full mode is
6293 returned, otherwise only the first letter is returned.
6294 Also see |state()|.
6295
6296 n Normal
6297 no Operator-pending
6298 nov Operator-pending (forced characterwise |o_v|)
6299 noV Operator-pending (forced linewise |o_V|)
6300 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6301 CTRL-V is one character
6302 niI Normal using |i_CTRL-O| in |Insert-mode|
6303 niR Normal using |i_CTRL-O| in |Replace-mode|
6304 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6305 nt Terminal-Normal (insert goes to Terminal-Job mode)
6306 v Visual by character
6307 vs Visual by character using |v_CTRL-O| in Select mode
6308 V Visual by line
6309 Vs Visual by line using |v_CTRL-O| in Select mode
6310 CTRL-V Visual blockwise
6311 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6312 s Select by character
6313 S Select by line
6314 CTRL-S Select blockwise
6315 i Insert
6316 ic Insert mode completion |compl-generic|
6317 ix Insert mode |i_CTRL-X| completion
6318 R Replace |R|
6319 Rc Replace mode completion |compl-generic|
6320 Rx Replace mode |i_CTRL-X| completion
6321 Rv Virtual Replace |gR|
6322 Rvc Virtual Replace mode completion |compl-generic|
6323 Rvx Virtual Replace mode |i_CTRL-X| completion
6324 c Command-line editing
6325 cv Vim Ex mode |gQ|
6326 ce Normal Ex mode |Q|
6327 r Hit-enter prompt
6328 rm The -- more -- prompt
6329 r? A |:confirm| query of some sort
6330 ! Shell or external command is executing
6331 t Terminal-Job mode: keys go to the job
6332
6333 This is useful in the 'statusline' option or when used
6334 with |remote_expr()| In most other places it always returns
6335 "c" or "n".
6336 Note that in the future more modes and more specific modes may
6337 be added. It's better not to compare the whole string but only
6338 the leading character(s).
6339 Also see |visualmode()|.
6340
6341 Can also be used as a |method|: >
6342 DoFull()->mode()
6343
6344mzeval({expr}) *mzeval()*
6345 Evaluate MzScheme expression {expr} and return its result
6346 converted to Vim data structures.
6347 Numbers and strings are returned as they are.
6348 Pairs (including lists and improper lists) and vectors are
6349 returned as Vim |Lists|.
6350 Hash tables are represented as Vim |Dictionary| type with keys
6351 converted to strings.
6352 All other types are converted to string with display function.
6353 Examples: >
6354 :mz (define l (list 1 2 3))
6355 :mz (define h (make-hash)) (hash-set! h "list" l)
6356 :echo mzeval("l")
6357 :echo mzeval("h")
6358<
6359 Note that in a `:def` function local variables are not visible
6360 to {expr}.
6361
6362 Can also be used as a |method|: >
6363 GetExpr()->mzeval()
6364<
6365 {only available when compiled with the |+mzscheme| feature}
6366
6367nextnonblank({lnum}) *nextnonblank()*
6368 Return the line number of the first line at or below {lnum}
6369 that is not blank. Example: >
6370 if getline(nextnonblank(1)) =~ "Java"
6371< When {lnum} is invalid or there is no non-blank line at or
6372 below it, zero is returned.
6373 {lnum} is used like with |getline()|.
6374 See also |prevnonblank()|.
6375
6376 Can also be used as a |method|: >
6377 GetLnum()->nextnonblank()
6378
6379nr2char({expr} [, {utf8}]) *nr2char()*
6380 Return a string with a single character, which has the number
6381 value {expr}. Examples: >
6382 nr2char(64) returns "@"
6383 nr2char(32) returns " "
6384< When {utf8} is omitted or zero, the current 'encoding' is used.
6385 Example for "utf-8": >
6386 nr2char(300) returns I with bow character
6387< When {utf8} is TRUE, always return UTF-8 characters.
6388 Note that a NUL character in the file is specified with
6389 nr2char(10), because NULs are represented with newline
6390 characters. nr2char(0) is a real NUL and terminates the
6391 string, thus results in an empty string.
6392 To turn a list of character numbers into a string: >
6393 let list = [65, 66, 67]
6394 let str = join(map(list, {_, val -> nr2char(val)}), '')
6395< Result: "ABC"
6396
6397 Can also be used as a |method|: >
6398 GetNumber()->nr2char()
6399
6400or({expr}, {expr}) *or()*
6401 Bitwise OR on the two arguments. The arguments are converted
6402 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006403 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006404 Example: >
6405 :let bits = or(bits, 0x80)
6406< Can also be used as a |method|: >
6407 :let bits = bits->or(0x80)
6408
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006409< Rationale: The reason this is a function and not using the "|"
6410 character like many languages, is that Vi has always used "|"
6411 to separate commands. In many places it would not be clear if
6412 "|" is an operator or a command separator.
6413
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006414
6415pathshorten({path} [, {len}]) *pathshorten()*
6416 Shorten directory names in the path {path} and return the
6417 result. The tail, the file name, is kept as-is. The other
6418 components in the path are reduced to {len} letters in length.
6419 If {len} is omitted or smaller than 1 then 1 is used (single
6420 letters). Leading '~' and '.' characters are kept. Examples: >
6421 :echo pathshorten('~/.vim/autoload/myfile.vim')
6422< ~/.v/a/myfile.vim ~
6423>
6424 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6425< ~/.vi/au/myfile.vim ~
6426 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006427 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006428
6429 Can also be used as a |method|: >
6430 GetDirectories()->pathshorten()
6431
6432perleval({expr}) *perleval()*
6433 Evaluate Perl expression {expr} in scalar context and return
6434 its result converted to Vim data structures. If value can't be
6435 converted, it is returned as a string Perl representation.
6436 Note: If you want an array or hash, {expr} must return a
6437 reference to it.
6438 Example: >
6439 :echo perleval('[1 .. 4]')
6440< [1, 2, 3, 4]
6441
6442 Note that in a `:def` function local variables are not visible
6443 to {expr}.
6444
6445 Can also be used as a |method|: >
6446 GetExpr()->perleval()
6447
6448< {only available when compiled with the |+perl| feature}
6449
6450
6451popup_ functions are documented here: |popup-functions|
6452
6453
6454pow({x}, {y}) *pow()*
6455 Return the power of {x} to the exponent {y} as a |Float|.
6456 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006457 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006458 Examples: >
6459 :echo pow(3, 3)
6460< 27.0 >
6461 :echo pow(2, 16)
6462< 65536.0 >
6463 :echo pow(32, 0.20)
6464< 2.0
6465
6466 Can also be used as a |method|: >
6467 Compute()->pow(3)
6468<
6469 {only available when compiled with the |+float| feature}
6470
6471prevnonblank({lnum}) *prevnonblank()*
6472 Return the line number of the first line at or above {lnum}
6473 that is not blank. Example: >
6474 let ind = indent(prevnonblank(v:lnum - 1))
6475< When {lnum} is invalid or there is no non-blank line at or
6476 above it, zero is returned.
6477 {lnum} is used like with |getline()|.
6478 Also see |nextnonblank()|.
6479
6480 Can also be used as a |method|: >
6481 GetLnum()->prevnonblank()
6482
6483printf({fmt}, {expr1} ...) *printf()*
6484 Return a String with {fmt}, where "%" items are replaced by
6485 the formatted form of their respective arguments. Example: >
6486 printf("%4d: E%d %.30s", lnum, errno, msg)
6487< May result in:
6488 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6489
6490 When used as a |method| the base is passed as the second
6491 argument: >
6492 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006493<
6494 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006495
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006496 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006497 %s string
6498 %6S string right-aligned in 6 display cells
6499 %6s string right-aligned in 6 bytes
6500 %.9s string truncated to 9 bytes
6501 %c single byte
6502 %d decimal number
6503 %5d decimal number padded with spaces to 5 characters
6504 %x hex number
6505 %04x hex number padded with zeros to at least 4 characters
6506 %X hex number using upper case letters
6507 %o octal number
6508 %08b binary number padded with zeros to at least 8 chars
6509 %f floating point number as 12.23, inf, -inf or nan
6510 %F floating point number as 12.23, INF, -INF or NAN
6511 %e floating point number as 1.23e3, inf, -inf or nan
6512 %E floating point number as 1.23E3, INF, -INF or NAN
6513 %g floating point number, as %f or %e depending on value
6514 %G floating point number, as %F or %E depending on value
6515 %% the % character itself
6516
6517 Conversion specifications start with '%' and end with the
6518 conversion type. All other characters are copied unchanged to
6519 the result.
6520
6521 The "%" starts a conversion specification. The following
6522 arguments appear in sequence:
6523
6524 % [flags] [field-width] [.precision] type
6525
6526 flags
6527 Zero or more of the following flags:
6528
6529 # The value should be converted to an "alternate
6530 form". For c, d, and s conversions, this option
6531 has no effect. For o conversions, the precision
6532 of the number is increased to force the first
6533 character of the output string to a zero (except
6534 if a zero value is printed with an explicit
6535 precision of zero).
6536 For b and B conversions, a non-zero result has
6537 the string "0b" (or "0B" for B conversions)
6538 prepended to it.
6539 For x and X conversions, a non-zero result has
6540 the string "0x" (or "0X" for X conversions)
6541 prepended to it.
6542
6543 0 (zero) Zero padding. For all conversions the converted
6544 value is padded on the left with zeros rather
6545 than blanks. If a precision is given with a
6546 numeric conversion (d, b, B, o, x, and X), the 0
6547 flag is ignored.
6548
6549 - A negative field width flag; the converted value
6550 is to be left adjusted on the field boundary.
6551 The converted value is padded on the right with
6552 blanks, rather than on the left with blanks or
6553 zeros. A - overrides a 0 if both are given.
6554
6555 ' ' (space) A blank should be left before a positive
6556 number produced by a signed conversion (d).
6557
6558 + A sign must always be placed before a number
6559 produced by a signed conversion. A + overrides
6560 a space if both are used.
6561
6562 field-width
6563 An optional decimal digit string specifying a minimum
6564 field width. If the converted value has fewer bytes
6565 than the field width, it will be padded with spaces on
6566 the left (or right, if the left-adjustment flag has
6567 been given) to fill out the field width. For the S
6568 conversion the count is in cells.
6569
6570 .precision
6571 An optional precision, in the form of a period '.'
6572 followed by an optional digit string. If the digit
6573 string is omitted, the precision is taken as zero.
6574 This gives the minimum number of digits to appear for
6575 d, o, x, and X conversions, the maximum number of
6576 bytes to be printed from a string for s conversions,
6577 or the maximum number of cells to be printed from a
6578 string for S conversions.
6579 For floating point it is the number of digits after
6580 the decimal point.
6581
6582 type
6583 A character that specifies the type of conversion to
6584 be applied, see below.
6585
6586 A field width or precision, or both, may be indicated by an
6587 asterisk '*' instead of a digit string. In this case, a
6588 Number argument supplies the field width or precision. A
6589 negative field width is treated as a left adjustment flag
6590 followed by a positive field width; a negative precision is
6591 treated as though it were missing. Example: >
6592 :echo printf("%d: %.*s", nr, width, line)
6593< This limits the length of the text used from "line" to
6594 "width" bytes.
6595
6596 The conversion specifiers and their meanings are:
6597
6598 *printf-d* *printf-b* *printf-B* *printf-o*
6599 *printf-x* *printf-X*
6600 dbBoxX The Number argument is converted to signed decimal
6601 (d), unsigned binary (b and B), unsigned octal (o), or
6602 unsigned hexadecimal (x and X) notation. The letters
6603 "abcdef" are used for x conversions; the letters
6604 "ABCDEF" are used for X conversions.
6605 The precision, if any, gives the minimum number of
6606 digits that must appear; if the converted value
6607 requires fewer digits, it is padded on the left with
6608 zeros.
6609 In no case does a non-existent or small field width
6610 cause truncation of a numeric field; if the result of
6611 a conversion is wider than the field width, the field
6612 is expanded to contain the conversion result.
6613 The 'h' modifier indicates the argument is 16 bits.
6614 The 'l' modifier indicates the argument is 32 bits.
6615 The 'L' modifier indicates the argument is 64 bits.
6616 Generally, these modifiers are not useful. They are
6617 ignored when type is known from the argument.
6618
6619 i alias for d
6620 D alias for ld
6621 U alias for lu
6622 O alias for lo
6623
6624 *printf-c*
6625 c The Number argument is converted to a byte, and the
6626 resulting character is written.
6627
6628 *printf-s*
6629 s The text of the String argument is used. If a
6630 precision is specified, no more bytes than the number
6631 specified are used.
6632 If the argument is not a String type, it is
6633 automatically converted to text with the same format
6634 as ":echo".
6635 *printf-S*
6636 S The text of the String argument is used. If a
6637 precision is specified, no more display cells than the
6638 number specified are used.
6639
6640 *printf-f* *E807*
6641 f F The Float argument is converted into a string of the
6642 form 123.456. The precision specifies the number of
6643 digits after the decimal point. When the precision is
6644 zero the decimal point is omitted. When the precision
6645 is not specified 6 is used. A really big number
6646 (out of range or dividing by zero) results in "inf"
6647 or "-inf" with %f (INF or -INF with %F).
6648 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6649 Example: >
6650 echo printf("%.2f", 12.115)
6651< 12.12
6652 Note that roundoff depends on the system libraries.
6653 Use |round()| when in doubt.
6654
6655 *printf-e* *printf-E*
6656 e E The Float argument is converted into a string of the
6657 form 1.234e+03 or 1.234E+03 when using 'E'. The
6658 precision specifies the number of digits after the
6659 decimal point, like with 'f'.
6660
6661 *printf-g* *printf-G*
6662 g G The Float argument is converted like with 'f' if the
6663 value is between 0.001 (inclusive) and 10000000.0
6664 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6665 for 'G'. When no precision is specified superfluous
6666 zeroes and '+' signs are removed, except for the zero
6667 immediately after the decimal point. Thus 10000000.0
6668 results in 1.0e7.
6669
6670 *printf-%*
6671 % A '%' is written. No argument is converted. The
6672 complete conversion specification is "%%".
6673
6674 When a Number argument is expected a String argument is also
6675 accepted and automatically converted.
6676 When a Float or String argument is expected a Number argument
6677 is also accepted and automatically converted.
6678 Any other argument type results in an error message.
6679
6680 *E766* *E767*
6681 The number of {exprN} arguments must exactly match the number
6682 of "%" items. If there are not sufficient or too many
6683 arguments an error is given. Up to 18 arguments can be used.
6684
6685
6686prompt_getprompt({buf}) *prompt_getprompt()*
6687 Returns the effective prompt text for buffer {buf}. {buf} can
6688 be a buffer name or number. See |prompt-buffer|.
6689
6690 If the buffer doesn't exist or isn't a prompt buffer, an empty
6691 string is returned.
6692
6693 Can also be used as a |method|: >
6694 GetBuffer()->prompt_getprompt()
6695
6696< {only available when compiled with the |+channel| feature}
6697
6698
6699prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6700 Set prompt callback for buffer {buf} to {expr}. When {expr}
6701 is an empty string the callback is removed. This has only
6702 effect if {buf} has 'buftype' set to "prompt".
6703
6704 The callback is invoked when pressing Enter. The current
6705 buffer will always be the prompt buffer. A new line for a
6706 prompt is added before invoking the callback, thus the prompt
6707 for which the callback was invoked will be in the last but one
6708 line.
6709 If the callback wants to add text to the buffer, it must
6710 insert it above the last line, since that is where the current
6711 prompt is. This can also be done asynchronously.
6712 The callback is invoked with one argument, which is the text
6713 that was entered at the prompt. This can be an empty string
6714 if the user only typed Enter.
6715 Example: >
6716 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6717 func s:TextEntered(text)
6718 if a:text == 'exit' || a:text == 'quit'
6719 stopinsert
6720 close
6721 else
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006722 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006723 " Reset 'modified' to allow the buffer to be closed.
6724 set nomodified
6725 endif
6726 endfunc
6727
6728< Can also be used as a |method|: >
6729 GetBuffer()->prompt_setcallback(callback)
6730
6731< {only available when compiled with the |+channel| feature}
6732
6733prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6734 Set a callback for buffer {buf} to {expr}. When {expr} is an
6735 empty string the callback is removed. This has only effect if
6736 {buf} has 'buftype' set to "prompt".
6737
6738 This callback will be invoked when pressing CTRL-C in Insert
6739 mode. Without setting a callback Vim will exit Insert mode,
6740 as in any buffer.
6741
6742 Can also be used as a |method|: >
6743 GetBuffer()->prompt_setinterrupt(callback)
6744
6745< {only available when compiled with the |+channel| feature}
6746
6747prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6748 Set prompt for buffer {buf} to {text}. You most likely want
6749 {text} to end in a space.
6750 The result is only visible if {buf} has 'buftype' set to
6751 "prompt". Example: >
6752 call prompt_setprompt(bufnr(), 'command: ')
6753<
6754 Can also be used as a |method|: >
6755 GetBuffer()->prompt_setprompt('command: ')
6756
6757< {only available when compiled with the |+channel| feature}
6758
6759prop_ functions are documented here: |text-prop-functions|
6760
6761pum_getpos() *pum_getpos()*
6762 If the popup menu (see |ins-completion-menu|) is not visible,
6763 returns an empty |Dictionary|, otherwise, returns a
6764 |Dictionary| with the following keys:
6765 height nr of items visible
6766 width screen cells
6767 row top screen row (0 first row)
6768 col leftmost screen column (0 first col)
6769 size total nr of items
6770 scrollbar |TRUE| if scrollbar is visible
6771
6772 The values are the same as in |v:event| during
6773 |CompleteChanged|.
6774
6775pumvisible() *pumvisible()*
6776 Returns non-zero when the popup menu is visible, zero
6777 otherwise. See |ins-completion-menu|.
6778 This can be used to avoid some things that would remove the
6779 popup menu.
6780
6781py3eval({expr}) *py3eval()*
6782 Evaluate Python expression {expr} and return its result
6783 converted to Vim data structures.
6784 Numbers and strings are returned as they are (strings are
6785 copied though, Unicode strings are additionally converted to
6786 'encoding').
6787 Lists are represented as Vim |List| type.
6788 Dictionaries are represented as Vim |Dictionary| type with
6789 keys converted to strings.
6790 Note that in a `:def` function local variables are not visible
6791 to {expr}.
6792
6793 Can also be used as a |method|: >
6794 GetExpr()->py3eval()
6795
6796< {only available when compiled with the |+python3| feature}
6797
6798 *E858* *E859*
6799pyeval({expr}) *pyeval()*
6800 Evaluate Python expression {expr} and return its result
6801 converted to Vim data structures.
6802 Numbers and strings are returned as they are (strings are
6803 copied though).
6804 Lists are represented as Vim |List| type.
6805 Dictionaries are represented as Vim |Dictionary| type,
6806 non-string keys result in error.
6807 Note that in a `:def` function local variables are not visible
6808 to {expr}.
6809
6810 Can also be used as a |method|: >
6811 GetExpr()->pyeval()
6812
6813< {only available when compiled with the |+python| feature}
6814
6815pyxeval({expr}) *pyxeval()*
6816 Evaluate Python expression {expr} and return its result
6817 converted to Vim data structures.
6818 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6819 See also: |pyeval()|, |py3eval()|
6820
6821 Can also be used as a |method|: >
6822 GetExpr()->pyxeval()
6823
6824< {only available when compiled with the |+python| or the
6825 |+python3| feature}
6826
6827rand([{expr}]) *rand()* *random*
6828 Return a pseudo-random Number generated with an xoshiro128**
6829 algorithm using seed {expr}. The returned number is 32 bits,
6830 also on 64 bits systems, for consistency.
6831 {expr} can be initialized by |srand()| and will be updated by
6832 rand(). If {expr} is omitted, an internal seed value is used
6833 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006834 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006835
6836 Examples: >
6837 :echo rand()
6838 :let seed = srand()
6839 :echo rand(seed)
6840 :echo rand(seed) % 16 " random number 0 - 15
6841<
6842
6843 *E726* *E727*
6844range({expr} [, {max} [, {stride}]]) *range()*
6845 Returns a |List| with Numbers:
6846 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6847 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6848 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6849 {max}] (increasing {expr} with {stride} each time, not
6850 producing a value past {max}).
6851 When the maximum is one before the start the result is an
6852 empty list. When the maximum is more than one before the
6853 start this is an error.
6854 Examples: >
6855 range(4) " [0, 1, 2, 3]
6856 range(2, 4) " [2, 3, 4]
6857 range(2, 9, 3) " [2, 5, 8]
6858 range(2, -2, -1) " [2, 1, 0, -1, -2]
6859 range(0) " []
6860 range(2, 0) " error!
6861<
6862 Can also be used as a |method|: >
6863 GetExpr()->range()
6864<
6865
6866readblob({fname}) *readblob()*
6867 Read file {fname} in binary mode and return a |Blob|.
6868 When the file can't be opened an error message is given and
6869 the result is an empty |Blob|.
6870 Also see |readfile()| and |writefile()|.
6871
6872
6873readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6874 Return a list with file and directory names in {directory}.
6875 You can also use |glob()| if you don't need to do complicated
6876 things, such as limiting the number of matches.
6877 The list will be sorted (case sensitive), see the {dict}
6878 argument below for changing the sort order.
6879
6880 When {expr} is omitted all entries are included.
6881 When {expr} is given, it is evaluated to check what to do:
6882 If {expr} results in -1 then no further entries will
6883 be handled.
6884 If {expr} results in 0 then this entry will not be
6885 added to the list.
6886 If {expr} results in 1 then this entry will be added
6887 to the list.
6888 The entries "." and ".." are always excluded.
6889 Each time {expr} is evaluated |v:val| is set to the entry name.
6890 When {expr} is a function the name is passed as the argument.
6891 For example, to get a list of files ending in ".txt": >
6892 readdir(dirname, {n -> n =~ '.txt$'})
6893< To skip hidden and backup files: >
6894 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00006895< *E857*
6896 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006897 values. Currently this is used to specify if and how sorting
6898 should be performed. The dict can have the following members:
6899
6900 sort How to sort the result returned from the system.
6901 Valid values are:
6902 "none" do not sort (fastest method)
6903 "case" sort case sensitive (byte value of
6904 each character, technically, using
6905 strcmp()) (default)
6906 "icase" sort case insensitive (technically
6907 using strcasecmp())
6908 "collate" sort using the collation order
6909 of the "POSIX" or "C" |locale|
6910 (technically using strcoll())
6911 Other values are silently ignored.
6912
6913 For example, to get a list of all files in the current
6914 directory without sorting the individual entries: >
6915 readdir('.', '1', #{sort: 'none'})
6916< If you want to get a directory tree: >
6917 function! s:tree(dir)
6918 return {a:dir : map(readdir(a:dir),
6919 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006920 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006921 endfunction
6922 echo s:tree(".")
6923<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006924 Returns an empty List on error.
6925
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006926 Can also be used as a |method|: >
6927 GetDirName()->readdir()
6928<
6929readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6930 Extended version of |readdir()|.
6931 Return a list of Dictionaries with file and directory
6932 information in {directory}.
6933 This is useful if you want to get the attributes of file and
6934 directory at the same time as getting a list of a directory.
6935 This is much faster than calling |readdir()| then calling
6936 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6937 each file and directory especially on MS-Windows.
6938 The list will by default be sorted by name (case sensitive),
6939 the sorting can be changed by using the optional {dict}
6940 argument, see |readdir()|.
6941
6942 The Dictionary for file and directory information has the
6943 following items:
6944 group Group name of the entry. (Only on Unix)
6945 name Name of the entry.
6946 perm Permissions of the entry. See |getfperm()|.
6947 size Size of the entry. See |getfsize()|.
6948 time Timestamp of the entry. See |getftime()|.
6949 type Type of the entry.
6950 On Unix, almost same as |getftype()| except:
6951 Symlink to a dir "linkd"
6952 Other symlink "link"
6953 On MS-Windows:
6954 Normal file "file"
6955 Directory "dir"
6956 Junction "junction"
6957 Symlink to a dir "linkd"
6958 Other symlink "link"
6959 Other reparse point "reparse"
6960 user User name of the entry's owner. (Only on Unix)
6961 On Unix, if the entry is a symlink, the Dictionary includes
6962 the information of the target (except the "type" item).
6963 On MS-Windows, it includes the information of the symlink
6964 itself because of performance reasons.
6965
6966 When {expr} is omitted all entries are included.
6967 When {expr} is given, it is evaluated to check what to do:
6968 If {expr} results in -1 then no further entries will
6969 be handled.
6970 If {expr} results in 0 then this entry will not be
6971 added to the list.
6972 If {expr} results in 1 then this entry will be added
6973 to the list.
6974 The entries "." and ".." are always excluded.
6975 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6976 of the entry.
6977 When {expr} is a function the entry is passed as the argument.
6978 For example, to get a list of files ending in ".txt": >
6979 readdirex(dirname, {e -> e.name =~ '.txt$'})
6980<
6981 For example, to get a list of all files in the current
6982 directory without sorting the individual entries: >
6983 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006984<
6985 Can also be used as a |method|: >
6986 GetDirName()->readdirex()
6987<
6988
6989 *readfile()*
6990readfile({fname} [, {type} [, {max}]])
6991 Read file {fname} and return a |List|, each line of the file
6992 as an item. Lines are broken at NL characters. Macintosh
6993 files separated with CR will result in a single long line
6994 (unless a NL appears somewhere).
6995 All NUL characters are replaced with a NL character.
6996 When {type} contains "b" binary mode is used:
6997 - When the last line ends in a NL an extra empty list item is
6998 added.
6999 - No CR characters are removed.
7000 Otherwise:
7001 - CR characters that appear before a NL are removed.
7002 - Whether the last line ends in a NL or not does not matter.
7003 - When 'encoding' is Unicode any UTF-8 byte order mark is
7004 removed from the text.
7005 When {max} is given this specifies the maximum number of lines
7006 to be read. Useful if you only want to check the first ten
7007 lines of a file: >
7008 :for line in readfile(fname, '', 10)
7009 : if line =~ 'Date' | echo line | endif
7010 :endfor
7011< When {max} is negative -{max} lines from the end of the file
7012 are returned, or as many as there are.
7013 When {max} is zero the result is an empty list.
7014 Note that without {max} the whole file is read into memory.
7015 Also note that there is no recognition of encoding. Read a
7016 file into a buffer if you need to.
7017 Deprecated (use |readblob()| instead): When {type} contains
7018 "B" a |Blob| is returned with the binary data of the file
7019 unmodified.
7020 When the file can't be opened an error message is given and
7021 the result is an empty list.
7022 Also see |writefile()|.
7023
7024 Can also be used as a |method|: >
7025 GetFileName()->readfile()
7026
7027reduce({object}, {func} [, {initial}]) *reduce()* *E998*
7028 {func} is called for every item in {object}, which can be a
7029 |String|, |List| or a |Blob|. {func} is called with two
7030 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007031 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007032
7033 {initial} is the initial result. When omitted, the first item
7034 in {object} is used and {func} is first called for the second
7035 item. If {initial} is not given and {object} is empty no
7036 result can be computed, an E998 error is given.
7037
7038 Examples: >
7039 echo reduce([1, 3, 5], { acc, val -> acc + val })
7040 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
7041 echo reduce(0z1122, { acc, val -> 2 * acc + val })
7042 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
7043<
7044 Can also be used as a |method|: >
7045 echo mylist->reduce({ acc, val -> acc + val }, 0)
7046
7047
7048reg_executing() *reg_executing()*
7049 Returns the single letter name of the register being executed.
7050 Returns an empty string when no register is being executed.
7051 See |@|.
7052
7053reg_recording() *reg_recording()*
7054 Returns the single letter name of the register being recorded.
7055 Returns an empty string when not recording. See |q|.
7056
7057reltime([{start} [, {end}]]) *reltime()*
7058 Return an item that represents a time value. The item is a
7059 list with items that depend on the system. In Vim 9 script
7060 list<any> can be used.
7061 The item can be passed to |reltimestr()| to convert it to a
7062 string or |reltimefloat()| to convert to a Float.
7063
Bram Moolenaar016188f2022-06-06 20:52:59 +01007064 Without an argument reltime() returns the current time (the
Bram Moolenaareb490412022-06-28 13:44:46 +01007065 representation is system-dependent, it can not be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01007066 wall-clock time, see |localtime()| for that).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007067 With one argument is returns the time passed since the time
7068 specified in the argument.
7069 With two arguments it returns the time passed between {start}
7070 and {end}.
7071
7072 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007073 reltime(). If there is an error an empty List is returned in
7074 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007075
7076 Can also be used as a |method|: >
7077 GetStart()->reltime()
7078<
7079 {only available when compiled with the |+reltime| feature}
7080
7081reltimefloat({time}) *reltimefloat()*
7082 Return a Float that represents the time value of {time}.
7083 Example: >
7084 let start = reltime()
7085 call MyFunction()
7086 let seconds = reltimefloat(reltime(start))
7087< See the note of reltimestr() about overhead.
7088 Also see |profiling|.
7089 If there is an error 0.0 is returned in legacy script, in Vim9
7090 script an error is given.
7091
7092 Can also be used as a |method|: >
7093 reltime(start)->reltimefloat()
7094
7095< {only available when compiled with the |+reltime| feature}
7096
7097reltimestr({time}) *reltimestr()*
7098 Return a String that represents the time value of {time}.
7099 This is the number of seconds, a dot and the number of
7100 microseconds. Example: >
7101 let start = reltime()
7102 call MyFunction()
7103 echo reltimestr(reltime(start))
7104< Note that overhead for the commands will be added to the time.
7105 The accuracy depends on the system.
7106 Leading spaces are used to make the string align nicely. You
7107 can use split() to remove it. >
7108 echo split(reltimestr(reltime(start)))[0]
7109< Also see |profiling|.
7110 If there is an error an empty string is returned in legacy
7111 script, in Vim9 script an error is given.
7112
7113 Can also be used as a |method|: >
7114 reltime(start)->reltimestr()
7115
7116< {only available when compiled with the |+reltime| feature}
7117
7118 *remote_expr()* *E449*
7119remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007120 Send the {string} to {server}. The {server} argument is a
7121 string, also see |{server}|.
7122
7123 The string is sent as an expression and the result is returned
7124 after evaluation. The result must be a String or a |List|. A
7125 |List| is turned into a String by joining the items with a
7126 line break in between (not at the end), like with join(expr,
7127 "\n").
7128
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007129 If {idvar} is present and not empty, it is taken as the name
7130 of a variable and a {serverid} for later use with
7131 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007132
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007133 If {timeout} is given the read times out after this many
7134 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007135
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007136 See also |clientserver| |RemoteReply|.
7137 This function is not available in the |sandbox|.
7138 {only available when compiled with the |+clientserver| feature}
7139 Note: Any errors will cause a local error message to be issued
7140 and the result will be the empty string.
7141
7142 Variables will be evaluated in the global namespace,
7143 independent of a function currently being active. Except
7144 when in debug mode, then local function variables and
7145 arguments can be evaluated.
7146
7147 Examples: >
7148 :echo remote_expr("gvim", "2+2")
7149 :echo remote_expr("gvim1", "b:current_syntax")
7150<
7151 Can also be used as a |method|: >
7152 ServerName()->remote_expr(expr)
7153
7154remote_foreground({server}) *remote_foreground()*
7155 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007156 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007157 This works like: >
7158 remote_expr({server}, "foreground()")
7159< Except that on Win32 systems the client does the work, to work
7160 around the problem that the OS doesn't always allow the server
7161 to bring itself to the foreground.
7162 Note: This does not restore the window if it was minimized,
7163 like foreground() does.
7164 This function is not available in the |sandbox|.
7165
7166 Can also be used as a |method|: >
7167 ServerName()->remote_foreground()
7168
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007169< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007170 Win32 console version}
7171
7172
7173remote_peek({serverid} [, {retvar}]) *remote_peek()*
7174 Returns a positive number if there are available strings
7175 from {serverid}. Copies any reply string into the variable
7176 {retvar} if specified. {retvar} must be a string with the
7177 name of a variable.
7178 Returns zero if none are available.
7179 Returns -1 if something is wrong.
7180 See also |clientserver|.
7181 This function is not available in the |sandbox|.
7182 {only available when compiled with the |+clientserver| feature}
7183 Examples: >
7184 :let repl = ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007185 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007186
7187< Can also be used as a |method|: >
7188 ServerId()->remote_peek()
7189
7190remote_read({serverid}, [{timeout}]) *remote_read()*
7191 Return the oldest available reply from {serverid} and consume
7192 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007193 reply is available. Returns an empty string, if a reply is
7194 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007195 See also |clientserver|.
7196 This function is not available in the |sandbox|.
7197 {only available when compiled with the |+clientserver| feature}
7198 Example: >
7199 :echo remote_read(id)
7200
7201< Can also be used as a |method|: >
7202 ServerId()->remote_read()
7203<
7204 *remote_send()* *E241*
7205remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007206 Send the {string} to {server}. The {server} argument is a
7207 string, also see |{server}|.
7208
7209 The string is sent as input keys and the function returns
7210 immediately. At the Vim server the keys are not mapped
7211 |:map|.
7212
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007213 If {idvar} is present, it is taken as the name of a variable
7214 and a {serverid} for later use with remote_read() is stored
7215 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007216
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007217 See also |clientserver| |RemoteReply|.
7218 This function is not available in the |sandbox|.
7219 {only available when compiled with the |+clientserver| feature}
7220
7221 Note: Any errors will be reported in the server and may mess
7222 up the display.
7223 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007224 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007225 \ remote_read(serverid)
7226
7227 :autocmd NONE RemoteReply *
7228 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007229 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007230 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7231<
7232 Can also be used as a |method|: >
7233 ServerName()->remote_send(keys)
7234<
7235 *remote_startserver()* *E941* *E942*
7236remote_startserver({name})
7237 Become the server {name}. This fails if already running as a
7238 server, when |v:servername| is not empty.
7239
7240 Can also be used as a |method|: >
7241 ServerName()->remote_startserver()
7242
7243< {only available when compiled with the |+clientserver| feature}
7244
7245remove({list}, {idx} [, {end}]) *remove()*
7246 Without {end}: Remove the item at {idx} from |List| {list} and
7247 return the item.
7248 With {end}: Remove items from {idx} to {end} (inclusive) and
7249 return a |List| with these items. When {idx} points to the same
7250 item as {end} a list with one item is returned. When {end}
7251 points to an item before {idx} this is an error.
7252 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007253 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007254 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007255 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007256 :call remove(mylist, 0, 9)
7257<
7258 Use |delete()| to remove a file.
7259
7260 Can also be used as a |method|: >
7261 mylist->remove(idx)
7262
7263remove({blob}, {idx} [, {end}])
7264 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7265 return the byte.
7266 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7267 return a |Blob| with these bytes. When {idx} points to the same
7268 byte as {end} a |Blob| with one byte is returned. When {end}
7269 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007270 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007271 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007272 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007273 :call remove(mylist, 0, 9)
7274
7275remove({dict}, {key})
7276 Remove the entry from {dict} with key {key} and return it.
7277 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007278 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007279< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007280 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007281
7282rename({from}, {to}) *rename()*
7283 Rename the file by the name {from} to the name {to}. This
7284 should also work to move files across file systems. The
7285 result is a Number, which is 0 if the file was renamed
7286 successfully, and non-zero when the renaming failed.
7287 NOTE: If {to} exists it is overwritten without warning.
7288 This function is not available in the |sandbox|.
7289
7290 Can also be used as a |method|: >
7291 GetOldName()->rename(newname)
7292
7293repeat({expr}, {count}) *repeat()*
7294 Repeat {expr} {count} times and return the concatenated
7295 result. Example: >
7296 :let separator = repeat('-', 80)
7297< When {count} is zero or negative the result is empty.
Bakudankun375141e2022-09-09 18:46:47 +01007298 When {expr} is a |List| or a |Blob| the result is {expr}
7299 concatenated {count} times. Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007300 :let longlist = repeat(['a', 'b'], 3)
7301< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7302
7303 Can also be used as a |method|: >
7304 mylist->repeat(count)
7305
7306resolve({filename}) *resolve()* *E655*
7307 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7308 returns the path the shortcut points to in a simplified form.
7309 When {filename} is a symbolic link or junction point, return
7310 the full path to the target. If the target of junction is
7311 removed, return {filename}.
7312 On Unix, repeat resolving symbolic links in all path
7313 components of {filename} and return the simplified result.
7314 To cope with link cycles, resolving of symbolic links is
7315 stopped after 100 iterations.
7316 On other systems, return the simplified {filename}.
7317 The simplification step is done as by |simplify()|.
7318 resolve() keeps a leading path component specifying the
7319 current directory (provided the result is still a relative
7320 path name) and also keeps a trailing path separator.
7321
7322 Can also be used as a |method|: >
7323 GetName()->resolve()
7324
7325reverse({object}) *reverse()*
7326 Reverse the order of items in {object} in-place.
7327 {object} can be a |List| or a |Blob|.
7328 Returns {object}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007329 Returns zero if {object} is not a List or a Blob.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007330 If you want an object to remain unmodified make a copy first: >
7331 :let revlist = reverse(copy(mylist))
7332< Can also be used as a |method|: >
7333 mylist->reverse()
7334
7335round({expr}) *round()*
7336 Round off {expr} to the nearest integral value and return it
7337 as a |Float|. If {expr} lies halfway between two integral
7338 values, then use the larger one (away from zero).
7339 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007340 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007341 Examples: >
7342 echo round(0.456)
7343< 0.0 >
7344 echo round(4.5)
7345< 5.0 >
7346 echo round(-4.5)
7347< -5.0
7348
7349 Can also be used as a |method|: >
7350 Compute()->round()
7351<
7352 {only available when compiled with the |+float| feature}
7353
7354rubyeval({expr}) *rubyeval()*
7355 Evaluate Ruby expression {expr} and return its result
7356 converted to Vim data structures.
7357 Numbers, floats and strings are returned as they are (strings
7358 are copied though).
7359 Arrays are represented as Vim |List| type.
7360 Hashes are represented as Vim |Dictionary| type.
7361 Other objects are represented as strings resulted from their
7362 "Object#to_s" method.
7363 Note that in a `:def` function local variables are not visible
7364 to {expr}.
7365
7366 Can also be used as a |method|: >
7367 GetRubyExpr()->rubyeval()
7368
7369< {only available when compiled with the |+ruby| feature}
7370
7371screenattr({row}, {col}) *screenattr()*
7372 Like |screenchar()|, but return the attribute. This is a rather
7373 arbitrary number that can only be used to compare to the
7374 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007375 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007376
7377 Can also be used as a |method|: >
7378 GetRow()->screenattr(col)
7379
7380screenchar({row}, {col}) *screenchar()*
7381 The result is a Number, which is the character at position
7382 [row, col] on the screen. This works for every possible
7383 screen position, also status lines, window separators and the
7384 command line. The top left position is row one, column one
7385 The character excludes composing characters. For double-byte
7386 encodings it may only be the first byte.
7387 This is mainly to be used for testing.
7388 Returns -1 when row or col is out of range.
7389
7390 Can also be used as a |method|: >
7391 GetRow()->screenchar(col)
7392
7393screenchars({row}, {col}) *screenchars()*
7394 The result is a |List| of Numbers. The first number is the same
7395 as what |screenchar()| returns. Further numbers are
7396 composing characters on top of the base character.
7397 This is mainly to be used for testing.
7398 Returns an empty List when row or col is out of range.
7399
7400 Can also be used as a |method|: >
7401 GetRow()->screenchars(col)
7402
7403screencol() *screencol()*
7404 The result is a Number, which is the current screen column of
7405 the cursor. The leftmost column has number 1.
7406 This function is mainly used for testing.
7407
7408 Note: Always returns the current screen column, thus if used
7409 in a command (e.g. ":echo screencol()") it will return the
7410 column inside the command line, which is 1 when the command is
7411 executed. To get the cursor position in the file use one of
7412 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007413 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007414 nnoremap <silent> GG :echom screencol()<CR>
7415 nnoremap GG <Cmd>echom screencol()<CR>
7416<
7417screenpos({winid}, {lnum}, {col}) *screenpos()*
7418 The result is a Dict with the screen position of the text
7419 character in window {winid} at buffer line {lnum} and column
7420 {col}. {col} is a one-based byte index.
7421 The Dict has these members:
7422 row screen row
7423 col first screen column
7424 endcol last screen column
7425 curscol cursor screen column
7426 If the specified position is not visible, all values are zero.
7427 The "endcol" value differs from "col" when the character
7428 occupies more than one screen cell. E.g. for a Tab "col" can
7429 be 1 and "endcol" can be 8.
7430 The "curscol" value is where the cursor would be placed. For
7431 a Tab it would be the same as "endcol", while for a double
7432 width character it would be the same as "col".
7433 The |conceal| feature is ignored here, the column numbers are
7434 as if 'conceallevel' is zero. You can set the cursor to the
7435 right position and use |screencol()| to get the value with
7436 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007437 If the position is in a closed fold the screen position of the
7438 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007439 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007440
7441 Can also be used as a |method|: >
7442 GetWinid()->screenpos(lnum, col)
7443
7444screenrow() *screenrow()*
7445 The result is a Number, which is the current screen row of the
7446 cursor. The top line has number one.
7447 This function is mainly used for testing.
7448 Alternatively you can use |winline()|.
7449
7450 Note: Same restrictions as with |screencol()|.
7451
7452screenstring({row}, {col}) *screenstring()*
7453 The result is a String that contains the base character and
7454 any composing characters at position [row, col] on the screen.
7455 This is like |screenchars()| but returning a String with the
7456 characters.
7457 This is mainly to be used for testing.
7458 Returns an empty String when row or col is out of range.
7459
7460 Can also be used as a |method|: >
7461 GetRow()->screenstring(col)
7462<
7463 *search()*
7464search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7465 Search for regexp pattern {pattern}. The search starts at the
7466 cursor position (you can use |cursor()| to set it).
7467
7468 When a match has been found its line number is returned.
7469 If there is no match a 0 is returned and the cursor doesn't
7470 move. No error message is given.
7471
7472 {flags} is a String, which can contain these character flags:
7473 'b' search Backward instead of forward
7474 'c' accept a match at the Cursor position
7475 'e' move to the End of the match
7476 'n' do Not move the cursor
7477 'p' return number of matching sub-Pattern (see below)
7478 's' Set the ' mark at the previous location of the cursor
7479 'w' Wrap around the end of the file
7480 'W' don't Wrap around the end of the file
7481 'z' start searching at the cursor column instead of zero
7482 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7483
7484 If the 's' flag is supplied, the ' mark is set, only if the
7485 cursor is moved. The 's' flag cannot be combined with the 'n'
7486 flag.
7487
7488 'ignorecase', 'smartcase' and 'magic' are used.
7489
7490 When the 'z' flag is not given, forward searching always
7491 starts in column zero and then matches before the cursor are
7492 skipped. When the 'c' flag is present in 'cpo' the next
7493 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01007494 search starts one column after the start of the match. This
7495 matters for overlapping matches. See |cpo-c|. You can also
7496 insert "\ze" to change where the match ends, see |/\ze|.
7497
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007498 When searching backwards and the 'z' flag is given then the
7499 search starts in column zero, thus no match in the current
7500 line will be found (unless wrapping around the end of the
7501 file).
7502
7503 When the {stopline} argument is given then the search stops
7504 after searching this line. This is useful to restrict the
7505 search to a range of lines. Examples: >
7506 let match = search('(', 'b', line("w0"))
7507 let end = search('END', '', line("w$"))
7508< When {stopline} is used and it is not zero this also implies
7509 that the search does not wrap around the end of the file.
7510 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007511 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007512 When the {timeout} argument is given the search stops when
7513 more than this many milliseconds have passed. Thus when
7514 {timeout} is 500 the search stops after half a second.
7515 The value must not be negative. A zero value is like not
7516 giving the argument.
7517 {only available when compiled with the |+reltime| feature}
7518
7519 If the {skip} expression is given it is evaluated with the
7520 cursor positioned on the start of a match. If it evaluates to
7521 non-zero this match is skipped. This can be used, for
7522 example, to skip a match in a comment or a string.
7523 {skip} can be a string, which is evaluated as an expression, a
7524 function reference or a lambda.
7525 When {skip} is omitted or empty, every match is accepted.
7526 When evaluating {skip} causes an error the search is aborted
7527 and -1 returned.
7528 *search()-sub-match*
7529 With the 'p' flag the returned value is one more than the
7530 first sub-match in \(\). One if none of them matched but the
7531 whole pattern did match.
7532 To get the column number too use |searchpos()|.
7533
7534 The cursor will be positioned at the match, unless the 'n'
7535 flag is used.
7536
7537 Example (goes over all files in the argument list): >
7538 :let n = 1
7539 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007540 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007541 : " start at the last char in the file and wrap for the
7542 : " first search to find match at start of file
7543 : normal G$
7544 : let flags = "w"
7545 : while search("foo", flags) > 0
7546 : s/foo/bar/g
7547 : let flags = "W"
7548 : endwhile
7549 : update " write the file if modified
7550 : let n = n + 1
7551 :endwhile
7552<
7553 Example for using some flags: >
7554 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7555< This will search for the keywords "if", "else", and "endif"
7556 under or after the cursor. Because of the 'p' flag, it
7557 returns 1, 2, or 3 depending on which keyword is found, or 0
7558 if the search fails. With the cursor on the first word of the
7559 line:
7560 if (foo == 0) | let foo = foo + 1 | endif ~
7561 the function returns 1. Without the 'c' flag, the function
7562 finds the "endif" and returns 3. The same thing happens
7563 without the 'e' flag if the cursor is on the "f" of "if".
7564 The 'n' flag tells the function not to move the cursor.
7565
7566 Can also be used as a |method|: >
7567 GetPattern()->search()
7568
7569searchcount([{options}]) *searchcount()*
7570 Get or update the last search count, like what is displayed
7571 without the "S" flag in 'shortmess'. This works even if
7572 'shortmess' does contain the "S" flag.
7573
7574 This returns a |Dictionary|. The dictionary is empty if the
7575 previous pattern was not set and "pattern" was not specified.
7576
7577 key type meaning ~
7578 current |Number| current position of match;
7579 0 if the cursor position is
7580 before the first match
7581 exact_match |Boolean| 1 if "current" is matched on
7582 "pos", otherwise 0
7583 total |Number| total count of matches found
7584 incomplete |Number| 0: search was fully completed
7585 1: recomputing was timed out
7586 2: max count exceeded
7587
7588 For {options} see further down.
7589
7590 To get the last search count when |n| or |N| was pressed, call
7591 this function with `recompute: 0` . This sometimes returns
7592 wrong information because |n| and |N|'s maximum count is 99.
7593 If it exceeded 99 the result must be max count + 1 (100). If
7594 you want to get correct information, specify `recompute: 1`: >
7595
7596 " result == maxcount + 1 (100) when many matches
7597 let result = searchcount(#{recompute: 0})
7598
7599 " Below returns correct result (recompute defaults
7600 " to 1)
7601 let result = searchcount()
7602<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007603 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007604 function! LastSearchCount() abort
7605 let result = searchcount(#{recompute: 0})
7606 if empty(result)
7607 return ''
7608 endif
7609 if result.incomplete ==# 1 " timed out
7610 return printf(' /%s [?/??]', @/)
7611 elseif result.incomplete ==# 2 " max count exceeded
7612 if result.total > result.maxcount &&
7613 \ result.current > result.maxcount
7614 return printf(' /%s [>%d/>%d]', @/,
7615 \ result.current, result.total)
7616 elseif result.total > result.maxcount
7617 return printf(' /%s [%d/>%d]', @/,
7618 \ result.current, result.total)
7619 endif
7620 endif
7621 return printf(' /%s [%d/%d]', @/,
7622 \ result.current, result.total)
7623 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007624 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007625
7626 " Or if you want to show the count only when
7627 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007628 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007629 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7630<
7631 You can also update the search count, which can be useful in a
7632 |CursorMoved| or |CursorMovedI| autocommand: >
7633
7634 autocmd CursorMoved,CursorMovedI *
7635 \ let s:searchcount_timer = timer_start(
7636 \ 200, function('s:update_searchcount'))
7637 function! s:update_searchcount(timer) abort
7638 if a:timer ==# s:searchcount_timer
7639 call searchcount(#{
7640 \ recompute: 1, maxcount: 0, timeout: 100})
7641 redrawstatus
7642 endif
7643 endfunction
7644<
7645 This can also be used to count matched texts with specified
7646 pattern in the current buffer using "pattern": >
7647
7648 " Count '\<foo\>' in this buffer
7649 " (Note that it also updates search count)
7650 let result = searchcount(#{pattern: '\<foo\>'})
7651
7652 " To restore old search count by old pattern,
7653 " search again
7654 call searchcount()
7655<
7656 {options} must be a |Dictionary|. It can contain:
7657 key type meaning ~
7658 recompute |Boolean| if |TRUE|, recompute the count
7659 like |n| or |N| was executed.
7660 otherwise returns the last
7661 computed result (when |n| or
7662 |N| was used when "S" is not
7663 in 'shortmess', or this
7664 function was called).
7665 (default: |TRUE|)
7666 pattern |String| recompute if this was given
7667 and different with |@/|.
7668 this works as same as the
7669 below command is executed
7670 before calling this function >
7671 let @/ = pattern
7672< (default: |@/|)
7673 timeout |Number| 0 or negative number is no
7674 timeout. timeout milliseconds
7675 for recomputing the result
7676 (default: 0)
7677 maxcount |Number| 0 or negative number is no
7678 limit. max count of matched
7679 text while recomputing the
7680 result. if search exceeded
7681 total count, "total" value
7682 becomes `maxcount + 1`
7683 (default: 99)
7684 pos |List| `[lnum, col, off]` value
7685 when recomputing the result.
7686 this changes "current" result
7687 value. see |cursor()|,
7688 |getpos()|
7689 (default: cursor's position)
7690
7691 Can also be used as a |method|: >
7692 GetSearchOpts()->searchcount()
7693<
7694searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7695 Search for the declaration of {name}.
7696
7697 With a non-zero {global} argument it works like |gD|, find
7698 first match in the file. Otherwise it works like |gd|, find
7699 first match in the function.
7700
7701 With a non-zero {thisblock} argument matches in a {} block
7702 that ends before the cursor position are ignored. Avoids
7703 finding variable declarations only valid in another scope.
7704
7705 Moves the cursor to the found match.
7706 Returns zero for success, non-zero for failure.
7707 Example: >
7708 if searchdecl('myvar') == 0
7709 echo getline('.')
7710 endif
7711<
7712 Can also be used as a |method|: >
7713 GetName()->searchdecl()
7714<
7715 *searchpair()*
7716searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7717 [, {stopline} [, {timeout}]]]])
7718 Search for the match of a nested start-end pair. This can be
7719 used to find the "endif" that matches an "if", while other
7720 if/endif pairs in between are ignored.
7721 The search starts at the cursor. The default is to search
7722 forward, include 'b' in {flags} to search backward.
7723 If a match is found, the cursor is positioned at it and the
7724 line number is returned. If no match is found 0 or -1 is
7725 returned and the cursor doesn't move. No error message is
7726 given.
7727
7728 {start}, {middle} and {end} are patterns, see |pattern|. They
7729 must not contain \( \) pairs. Use of \%( \) is allowed. When
7730 {middle} is not empty, it is found when searching from either
7731 direction, but only when not in a nested start-end pair. A
7732 typical use is: >
7733 searchpair('\<if\>', '\<else\>', '\<endif\>')
7734< By leaving {middle} empty the "else" is skipped.
7735
7736 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7737 |search()|. Additionally:
7738 'r' Repeat until no more matches found; will find the
7739 outer pair. Implies the 'W' flag.
7740 'm' Return number of matches instead of line number with
7741 the match; will be > 1 when 'r' is used.
7742 Note: it's nearly always a good idea to use the 'W' flag, to
7743 avoid wrapping around the end of the file.
7744
7745 When a match for {start}, {middle} or {end} is found, the
7746 {skip} expression is evaluated with the cursor positioned on
7747 the start of the match. It should return non-zero if this
7748 match is to be skipped. E.g., because it is inside a comment
7749 or a string.
7750 When {skip} is omitted or empty, every match is accepted.
7751 When evaluating {skip} causes an error the search is aborted
7752 and -1 returned.
7753 {skip} can be a string, a lambda, a funcref or a partial.
7754 Anything else makes the function fail.
7755 In a `:def` function when the {skip} argument is a string
7756 constant it is compiled into instructions.
7757
7758 For {stopline} and {timeout} see |search()|.
7759
7760 The value of 'ignorecase' is used. 'magic' is ignored, the
7761 patterns are used like it's on.
7762
7763 The search starts exactly at the cursor. A match with
7764 {start}, {middle} or {end} at the next character, in the
7765 direction of searching, is the first one found. Example: >
7766 if 1
7767 if 2
7768 endif 2
7769 endif 1
7770< When starting at the "if 2", with the cursor on the "i", and
7771 searching forwards, the "endif 2" is found. When starting on
7772 the character just before the "if 2", the "endif 1" will be
7773 found. That's because the "if 2" will be found first, and
7774 then this is considered to be a nested if/endif from "if 2" to
7775 "endif 2".
7776 When searching backwards and {end} is more than one character,
7777 it may be useful to put "\zs" at the end of the pattern, so
7778 that when the cursor is inside a match with the end it finds
7779 the matching start.
7780
7781 Example, to find the "endif" command in a Vim script: >
7782
7783 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7784 \ 'getline(".") =~ "^\\s*\""')
7785
7786< The cursor must be at or after the "if" for which a match is
7787 to be found. Note that single-quote strings are used to avoid
7788 having to double the backslashes. The skip expression only
7789 catches comments at the start of a line, not after a command.
7790 Also, a word "en" or "if" halfway a line is considered a
7791 match.
7792 Another example, to search for the matching "{" of a "}": >
7793
7794 :echo searchpair('{', '', '}', 'bW')
7795
7796< This works when the cursor is at or before the "}" for which a
7797 match is to be found. To reject matches that syntax
7798 highlighting recognized as strings: >
7799
7800 :echo searchpair('{', '', '}', 'bW',
7801 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7802<
7803 *searchpairpos()*
7804searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7805 [, {stopline} [, {timeout}]]]])
7806 Same as |searchpair()|, but returns a |List| with the line and
7807 column position of the match. The first element of the |List|
7808 is the line number and the second element is the byte index of
7809 the column position of the match. If no match is found,
7810 returns [0, 0]. >
7811
7812 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7813<
7814 See |match-parens| for a bigger and more useful example.
7815
7816 *searchpos()*
7817searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7818 Same as |search()|, but returns a |List| with the line and
7819 column position of the match. The first element of the |List|
7820 is the line number and the second element is the byte index of
7821 the column position of the match. If no match is found,
7822 returns [0, 0].
7823 Example: >
7824 :let [lnum, col] = searchpos('mypattern', 'n')
7825
7826< When the 'p' flag is given then there is an extra item with
7827 the sub-pattern match number |search()-sub-match|. Example: >
7828 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7829< In this example "submatch" is 2 when a lowercase letter is
7830 found |/\l|, 3 when an uppercase letter is found |/\u|.
7831
7832 Can also be used as a |method|: >
7833 GetPattern()->searchpos()
7834
7835server2client({clientid}, {string}) *server2client()*
7836 Send a reply string to {clientid}. The most recent {clientid}
7837 that sent a string can be retrieved with expand("<client>").
7838 {only available when compiled with the |+clientserver| feature}
7839 Returns zero for success, -1 for failure.
7840 Note:
7841 This id has to be stored before the next command can be
7842 received. I.e. before returning from the received command and
7843 before calling any commands that waits for input.
7844 See also |clientserver|.
7845 Example: >
7846 :echo server2client(expand("<client>"), "HELLO")
7847
7848< Can also be used as a |method|: >
7849 GetClientId()->server2client(string)
7850<
7851serverlist() *serverlist()*
7852 Return a list of available server names, one per line.
7853 When there are no servers or the information is not available
7854 an empty string is returned. See also |clientserver|.
7855 {only available when compiled with the |+clientserver| feature}
7856 Example: >
7857 :echo serverlist()
7858<
7859setbufline({buf}, {lnum}, {text}) *setbufline()*
7860 Set line {lnum} to {text} in buffer {buf}. This works like
7861 |setline()| for the specified buffer.
7862
7863 This function works only for loaded buffers. First call
7864 |bufload()| if needed.
7865
7866 To insert lines use |appendbufline()|.
7867 Any text properties in {lnum} are cleared.
7868
7869 {text} can be a string to set one line, or a list of strings
7870 to set multiple lines. If the list extends below the last
7871 line then those lines are added.
7872
7873 For the use of {buf}, see |bufname()| above.
7874
7875 {lnum} is used like with |setline()|.
7876 Use "$" to refer to the last line in buffer {buf}.
7877 When {lnum} is just below the last line the {text} will be
7878 added below the last line.
7879
7880 When {buf} is not a valid buffer, the buffer is not loaded or
7881 {lnum} is not valid then 1 is returned. In |Vim9| script an
7882 error is given.
7883 On success 0 is returned.
7884
7885 Can also be used as a |method|, the base is passed as the
7886 third argument: >
7887 GetText()->setbufline(buf, lnum)
7888
7889setbufvar({buf}, {varname}, {val}) *setbufvar()*
7890 Set option or local variable {varname} in buffer {buf} to
7891 {val}.
7892 This also works for a global or local window option, but it
7893 doesn't work for a global or local window variable.
7894 For a local window option the global value is unchanged.
7895 For the use of {buf}, see |bufname()| above.
7896 The {varname} argument is a string.
7897 Note that the variable name without "b:" must be used.
7898 Examples: >
7899 :call setbufvar(1, "&mod", 1)
7900 :call setbufvar("todo", "myvar", "foobar")
7901< This function is not available in the |sandbox|.
7902
7903 Can also be used as a |method|, the base is passed as the
7904 third argument: >
7905 GetValue()->setbufvar(buf, varname)
7906
7907
7908setcellwidths({list}) *setcellwidths()*
7909 Specify overrides for cell widths of character ranges. This
7910 tells Vim how wide characters are, counted in screen cells.
7911 This overrides 'ambiwidth'. Example: >
7912 setcellwidths([[0xad, 0xad, 1],
7913 \ [0x2194, 0x2199, 2]])
7914
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007915< *E1109* *E1110* *E1111* *E1112* *E1113* *E1114*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007916 The {list} argument is a list of lists with each three
7917 numbers. These three numbers are [low, high, width]. "low"
7918 and "high" can be the same, in which case this refers to one
7919 character. Otherwise it is the range of characters from "low"
7920 to "high" (inclusive). "width" is either 1 or 2, indicating
7921 the character width in screen cells.
7922 An error is given if the argument is invalid, also when a
7923 range overlaps with another.
7924 Only characters with value 0x100 and higher can be used.
7925
7926 If the new value causes 'fillchars' or 'listchars' to become
7927 invalid it is rejected and an error is given.
7928
7929 To clear the overrides pass an empty list: >
7930 setcellwidths([]);
7931< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7932 the effect for known emoji characters.
7933
7934setcharpos({expr}, {list}) *setcharpos()*
7935 Same as |setpos()| but uses the specified column number as the
7936 character index instead of the byte index in the line.
7937
7938 Example:
7939 With the text "여보세요" in line 8: >
7940 call setcharpos('.', [0, 8, 4, 0])
7941< positions the cursor on the fourth character '요'. >
7942 call setpos('.', [0, 8, 4, 0])
7943< positions the cursor on the second character '보'.
7944
7945 Can also be used as a |method|: >
7946 GetPosition()->setcharpos('.')
7947
7948setcharsearch({dict}) *setcharsearch()*
7949 Set the current character search information to {dict},
7950 which contains one or more of the following entries:
7951
7952 char character which will be used for a subsequent
7953 |,| or |;| command; an empty string clears the
7954 character search
7955 forward direction of character search; 1 for forward,
7956 0 for backward
7957 until type of character search; 1 for a |t| or |T|
7958 character search, 0 for an |f| or |F|
7959 character search
7960
7961 This can be useful to save/restore a user's character search
7962 from a script: >
7963 :let prevsearch = getcharsearch()
7964 :" Perform a command which clobbers user's search
7965 :call setcharsearch(prevsearch)
7966< Also see |getcharsearch()|.
7967
7968 Can also be used as a |method|: >
7969 SavedSearch()->setcharsearch()
7970
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01007971setcmdline({str} [, {pos}]) *setcmdline()*
7972 Set the command line to {str} and set the cursor position to
7973 {pos}.
7974 If {pos} is omitted, the cursor is positioned after the text.
7975 Returns 0 when successful, 1 when not editing the command
7976 line.
7977
7978 Can also be used as a |method|: >
7979 GetText()->setcmdline()
7980
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007981setcmdpos({pos}) *setcmdpos()*
7982 Set the cursor position in the command line to byte position
7983 {pos}. The first position is 1.
7984 Use |getcmdpos()| to obtain the current position.
7985 Only works while editing the command line, thus you must use
7986 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7987 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7988 set after the command line is set to the expression. For
7989 |c_CTRL-R_=| it is set after evaluating the expression but
7990 before inserting the resulting text.
7991 When the number is too big the cursor is put at the end of the
7992 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01007993 Returns 0 when successful, 1 when not editing the command
7994 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007995
7996 Can also be used as a |method|: >
7997 GetPos()->setcmdpos()
7998
7999setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
8000setcursorcharpos({list})
8001 Same as |cursor()| but uses the specified column number as the
8002 character index instead of the byte index in the line.
8003
8004 Example:
8005 With the text "여보세요" in line 4: >
8006 call setcursorcharpos(4, 3)
8007< positions the cursor on the third character '세'. >
8008 call cursor(4, 3)
8009< positions the cursor on the first character '여'.
8010
8011 Can also be used as a |method|: >
8012 GetCursorPos()->setcursorcharpos()
8013
8014
8015setenv({name}, {val}) *setenv()*
8016 Set environment variable {name} to {val}. Example: >
8017 call setenv('HOME', '/home/myhome')
8018
8019< When {val} is |v:null| the environment variable is deleted.
8020 See also |expr-env|.
8021
8022 Can also be used as a |method|, the base is passed as the
8023 second argument: >
8024 GetPath()->setenv('PATH')
8025
8026setfperm({fname}, {mode}) *setfperm()* *chmod*
8027 Set the file permissions for {fname} to {mode}.
8028 {mode} must be a string with 9 characters. It is of the form
8029 "rwxrwxrwx", where each group of "rwx" flags represent, in
8030 turn, the permissions of the owner of the file, the group the
8031 file belongs to, and other users. A '-' character means the
8032 permission is off, any other character means on. Multi-byte
8033 characters are not supported.
8034
8035 For example "rw-r-----" means read-write for the user,
8036 readable by the group, not accessible by others. "xx-x-----"
8037 would do the same thing.
8038
8039 Returns non-zero for success, zero for failure.
8040
8041 Can also be used as a |method|: >
8042 GetFilename()->setfperm(mode)
8043<
8044 To read permissions see |getfperm()|.
8045
8046
8047setline({lnum}, {text}) *setline()*
8048 Set line {lnum} of the current buffer to {text}. To insert
8049 lines use |append()|. To set lines in another buffer use
8050 |setbufline()|. Any text properties in {lnum} are cleared.
8051
8052 {lnum} is used like with |getline()|.
8053 When {lnum} is just below the last line the {text} will be
8054 added below the last line.
8055 {text} can be any type or a List of any type, each item is
8056 converted to a String.
8057
8058 If this succeeds, FALSE is returned. If this fails (most likely
8059 because {lnum} is invalid) TRUE is returned.
8060 In |Vim9| script an error is given if {lnum} is invalid.
8061
8062 Example: >
8063 :call setline(5, strftime("%c"))
8064
8065< When {text} is a |List| then line {lnum} and following lines
8066 will be set to the items in the list. Example: >
8067 :call setline(5, ['aaa', 'bbb', 'ccc'])
8068< This is equivalent to: >
8069 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
8070 : call setline(n, l)
8071 :endfor
8072
8073< Note: The '[ and '] marks are not set.
8074
8075 Can also be used as a |method|, the base is passed as the
8076 second argument: >
8077 GetText()->setline(lnum)
8078
8079setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
8080 Create or replace or add to the location list for window {nr}.
8081 {nr} can be the window number or the |window-ID|.
8082 When {nr} is zero the current window is used.
8083
8084 For a location list window, the displayed location list is
8085 modified. For an invalid window number {nr}, -1 is returned.
8086 Otherwise, same as |setqflist()|.
8087 Also see |location-list|.
8088
8089 For {action} see |setqflist-action|.
8090
8091 If the optional {what} dictionary argument is supplied, then
8092 only the items listed in {what} are set. Refer to |setqflist()|
8093 for the list of supported keys in {what}.
8094
8095 Can also be used as a |method|, the base is passed as the
8096 second argument: >
8097 GetLoclist()->setloclist(winnr)
8098
8099setmatches({list} [, {win}]) *setmatches()*
8100 Restores a list of matches saved by |getmatches()| for the
8101 current window. Returns 0 if successful, otherwise -1. All
8102 current matches are cleared before the list is restored. See
8103 example for |getmatches()|.
8104 If {win} is specified, use the window with this number or
8105 window ID instead of the current window.
8106
8107 Can also be used as a |method|: >
8108 GetMatches()->setmatches()
8109<
8110 *setpos()*
8111setpos({expr}, {list})
8112 Set the position for String {expr}. Possible values:
8113 . the cursor
8114 'x mark x
8115
8116 {list} must be a |List| with four or five numbers:
8117 [bufnum, lnum, col, off]
8118 [bufnum, lnum, col, off, curswant]
8119
8120 "bufnum" is the buffer number. Zero can be used for the
8121 current buffer. When setting an uppercase mark "bufnum" is
8122 used for the mark position. For other marks it specifies the
8123 buffer to set the mark in. You can use the |bufnr()| function
8124 to turn a file name into a buffer number.
8125 For setting the cursor and the ' mark "bufnum" is ignored,
8126 since these are associated with a window, not a buffer.
8127 Does not change the jumplist.
8128
8129 "lnum" and "col" are the position in the buffer. The first
8130 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8131 smaller than 1 then 1 is used. To use the character count
8132 instead of the byte count, use |setcharpos()|.
8133
8134 The "off" number is only used when 'virtualedit' is set. Then
8135 it is the offset in screen columns from the start of the
8136 character. E.g., a position within a <Tab> or after the last
8137 character.
8138
8139 The "curswant" number is only used when setting the cursor
8140 position. It sets the preferred column for when moving the
8141 cursor vertically. When the "curswant" number is missing the
8142 preferred column is not set. When it is present and setting a
8143 mark position it is not used.
8144
8145 Note that for '< and '> changing the line number may result in
8146 the marks to be effectively be swapped, so that '< is always
8147 before '>.
8148
8149 Returns 0 when the position could be set, -1 otherwise.
8150 An error message is given if {expr} is invalid.
8151
8152 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8153
8154 This does not restore the preferred column for moving
8155 vertically; if you set the cursor position with this, |j| and
8156 |k| motions will jump to previous columns! Use |cursor()| to
8157 also set the preferred column. Also see the "curswant" key in
8158 |winrestview()|.
8159
8160 Can also be used as a |method|: >
8161 GetPosition()->setpos('.')
8162
8163setqflist({list} [, {action} [, {what}]]) *setqflist()*
8164 Create or replace or add to the quickfix list.
8165
8166 If the optional {what} dictionary argument is supplied, then
8167 only the items listed in {what} are set. The first {list}
8168 argument is ignored. See below for the supported items in
8169 {what}.
8170 *setqflist-what*
8171 When {what} is not present, the items in {list} are used. Each
8172 item must be a dictionary. Non-dictionary items in {list} are
8173 ignored. Each dictionary item can contain the following
8174 entries:
8175
8176 bufnr buffer number; must be the number of a valid
8177 buffer
8178 filename name of a file; only used when "bufnr" is not
8179 present or it is invalid.
8180 module name of a module; if given it will be used in
8181 quickfix error window instead of the filename.
8182 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008183 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008184 pattern search pattern used to locate the error
8185 col column number
8186 vcol when non-zero: "col" is visual column
8187 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008188 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008189 nr error number
8190 text description of the error
8191 type single-character error type, 'E', 'W', etc.
8192 valid recognized error message
8193
8194 The "col", "vcol", "nr", "type" and "text" entries are
8195 optional. Either "lnum" or "pattern" entry can be used to
8196 locate a matching error line.
8197 If the "filename" and "bufnr" entries are not present or
8198 neither the "lnum" or "pattern" entries are present, then the
8199 item will not be handled as an error line.
8200 If both "pattern" and "lnum" are present then "pattern" will
8201 be used.
8202 If the "valid" entry is not supplied, then the valid flag is
8203 set when "bufnr" is a valid buffer or "filename" exists.
8204 If you supply an empty {list}, the quickfix list will be
8205 cleared.
8206 Note that the list is not exactly the same as what
8207 |getqflist()| returns.
8208
8209 {action} values: *setqflist-action* *E927*
8210 'a' The items from {list} are added to the existing
8211 quickfix list. If there is no existing list, then a
8212 new list is created.
8213
8214 'r' The items from the current quickfix list are replaced
8215 with the items from {list}. This can also be used to
8216 clear the list: >
8217 :call setqflist([], 'r')
8218<
8219 'f' All the quickfix lists in the quickfix stack are
8220 freed.
8221
8222 If {action} is not present or is set to ' ', then a new list
8223 is created. The new quickfix list is added after the current
8224 quickfix list in the stack and all the following lists are
8225 freed. To add a new quickfix list at the end of the stack,
8226 set "nr" in {what} to "$".
8227
8228 The following items can be specified in dictionary {what}:
8229 context quickfix list context. See |quickfix-context|
8230 efm errorformat to use when parsing text from
8231 "lines". If this is not present, then the
8232 'errorformat' option value is used.
8233 See |quickfix-parse|
8234 id quickfix list identifier |quickfix-ID|
8235 idx index of the current entry in the quickfix
8236 list specified by 'id' or 'nr'. If set to '$',
8237 then the last entry in the list is set as the
8238 current entry. See |quickfix-index|
8239 items list of quickfix entries. Same as the {list}
8240 argument.
8241 lines use 'errorformat' to parse a list of lines and
8242 add the resulting entries to the quickfix list
8243 {nr} or {id}. Only a |List| value is supported.
8244 See |quickfix-parse|
8245 nr list number in the quickfix stack; zero
8246 means the current quickfix list and "$" means
8247 the last quickfix list.
8248 quickfixtextfunc
8249 function to get the text to display in the
8250 quickfix window. The value can be the name of
8251 a function or a funcref or a lambda. Refer to
8252 |quickfix-window-function| for an explanation
8253 of how to write the function and an example.
8254 title quickfix list title text. See |quickfix-title|
8255 Unsupported keys in {what} are ignored.
8256 If the "nr" item is not present, then the current quickfix list
8257 is modified. When creating a new quickfix list, "nr" can be
8258 set to a value one greater than the quickfix stack size.
8259 When modifying a quickfix list, to guarantee that the correct
8260 list is modified, "id" should be used instead of "nr" to
8261 specify the list.
8262
8263 Examples (See also |setqflist-examples|): >
8264 :call setqflist([], 'r', {'title': 'My search'})
8265 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8266 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8267<
8268 Returns zero for success, -1 for failure.
8269
8270 This function can be used to create a quickfix list
8271 independent of the 'errorformat' setting. Use a command like
8272 `:cc 1` to jump to the first position.
8273
8274 Can also be used as a |method|, the base is passed as the
8275 second argument: >
8276 GetErrorlist()->setqflist()
8277<
8278 *setreg()*
8279setreg({regname}, {value} [, {options}])
8280 Set the register {regname} to {value}.
8281 If {regname} is "" or "@", the unnamed register '"' is used.
8282 The {regname} argument is a string. In |Vim9-script|
8283 {regname} must be one character.
8284
8285 {value} may be any value returned by |getreg()| or
8286 |getreginfo()|, including a |List| or |Dict|.
8287 If {options} contains "a" or {regname} is upper case,
8288 then the value is appended.
8289
8290 {options} can also contain a register type specification:
8291 "c" or "v" |characterwise| mode
8292 "l" or "V" |linewise| mode
8293 "b" or "<CTRL-V>" |blockwise-visual| mode
8294 If a number immediately follows "b" or "<CTRL-V>" then this is
8295 used as the width of the selection - if it is not specified
8296 then the width of the block is set to the number of characters
8297 in the longest line (counting a <Tab> as 1 character).
8298
8299 If {options} contains no register settings, then the default
8300 is to use character mode unless {value} ends in a <NL> for
8301 string {value} and linewise mode for list {value}. Blockwise
8302 mode is never selected automatically.
8303 Returns zero for success, non-zero for failure.
8304
8305 *E883*
8306 Note: you may not use |List| containing more than one item to
8307 set search and expression registers. Lists containing no
8308 items act like empty strings.
8309
8310 Examples: >
8311 :call setreg(v:register, @*)
8312 :call setreg('*', @%, 'ac')
8313 :call setreg('a', "1\n2\n3", 'b5')
8314 :call setreg('"', { 'points_to': 'a'})
8315
8316< This example shows using the functions to save and restore a
8317 register: >
8318 :let var_a = getreginfo()
8319 :call setreg('a', var_a)
8320< or: >
8321 :let var_a = getreg('a', 1, 1)
8322 :let var_amode = getregtype('a')
8323 ....
8324 :call setreg('a', var_a, var_amode)
8325< Note: you may not reliably restore register value
8326 without using the third argument to |getreg()| as without it
8327 newlines are represented as newlines AND Nul bytes are
8328 represented as newlines as well, see |NL-used-for-Nul|.
8329
8330 You can also change the type of a register by appending
8331 nothing: >
8332 :call setreg('a', '', 'al')
8333
8334< Can also be used as a |method|, the base is passed as the
8335 second argument: >
8336 GetText()->setreg('a')
8337
8338settabvar({tabnr}, {varname}, {val}) *settabvar()*
8339 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8340 |t:var|
8341 The {varname} argument is a string.
8342 Note that autocommands are blocked, side effects may not be
8343 triggered, e.g. when setting 'filetype'.
8344 Note that the variable name without "t:" must be used.
8345 Tabs are numbered starting with one.
8346 This function is not available in the |sandbox|.
8347
8348 Can also be used as a |method|, the base is passed as the
8349 third argument: >
8350 GetValue()->settabvar(tab, name)
8351
8352settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8353 Set option or local variable {varname} in window {winnr} to
8354 {val}.
8355 Tabs are numbered starting with one. For the current tabpage
8356 use |setwinvar()|.
8357 {winnr} can be the window number or the |window-ID|.
8358 When {winnr} is zero the current window is used.
8359 Note that autocommands are blocked, side effects may not be
8360 triggered, e.g. when setting 'filetype' or 'syntax'.
8361 This also works for a global or local buffer option, but it
8362 doesn't work for a global or local buffer variable.
8363 For a local buffer option the global value is unchanged.
8364 Note that the variable name without "w:" must be used.
8365 Examples: >
8366 :call settabwinvar(1, 1, "&list", 0)
8367 :call settabwinvar(3, 2, "myvar", "foobar")
8368< This function is not available in the |sandbox|.
8369
8370 Can also be used as a |method|, the base is passed as the
8371 fourth argument: >
8372 GetValue()->settabwinvar(tab, winnr, name)
8373
8374settagstack({nr}, {dict} [, {action}]) *settagstack()*
8375 Modify the tag stack of the window {nr} using {dict}.
8376 {nr} can be the window number or the |window-ID|.
8377
8378 For a list of supported items in {dict}, refer to
8379 |gettagstack()|. "curidx" takes effect before changing the tag
8380 stack.
8381 *E962*
8382 How the tag stack is modified depends on the {action}
8383 argument:
8384 - If {action} is not present or is set to 'r', then the tag
8385 stack is replaced.
8386 - If {action} is set to 'a', then new entries from {dict} are
8387 pushed (added) onto the tag stack.
8388 - If {action} is set to 't', then all the entries from the
8389 current entry in the tag stack or "curidx" in {dict} are
8390 removed and then new entries are pushed to the stack.
8391
8392 The current index is set to one after the length of the tag
8393 stack after the modification.
8394
8395 Returns zero for success, -1 for failure.
8396
8397 Examples (for more examples see |tagstack-examples|):
8398 Empty the tag stack of window 3: >
8399 call settagstack(3, {'items' : []})
8400
8401< Save and restore the tag stack: >
8402 let stack = gettagstack(1003)
8403 " do something else
8404 call settagstack(1003, stack)
8405 unlet stack
8406<
8407 Can also be used as a |method|, the base is passed as the
8408 second argument: >
8409 GetStack()->settagstack(winnr)
8410
8411setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8412 Like |settabwinvar()| for the current tab page.
8413 Examples: >
8414 :call setwinvar(1, "&list", 0)
8415 :call setwinvar(2, "myvar", "foobar")
8416
8417< Can also be used as a |method|, the base is passed as the
8418 third argument: >
8419 GetValue()->setwinvar(winnr, name)
8420
8421sha256({string}) *sha256()*
8422 Returns a String with 64 hex characters, which is the SHA256
8423 checksum of {string}.
8424
8425 Can also be used as a |method|: >
8426 GetText()->sha256()
8427
8428< {only available when compiled with the |+cryptv| feature}
8429
8430shellescape({string} [, {special}]) *shellescape()*
8431 Escape {string} for use as a shell command argument.
8432 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008433 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008434 in single quotes and will double up all internal single
8435 quotes.
8436 On MS-Windows, when 'shellslash' is not set, it will enclose
8437 {string} in double quotes and double all double quotes within
8438 {string}.
8439 Otherwise it will enclose {string} in single quotes and
8440 replace all "'" with "'\''".
8441
8442 When the {special} argument is present and it's a non-zero
8443 Number or a non-empty String (|non-zero-arg|), then special
8444 items such as "!", "%", "#" and "<cword>" will be preceded by
8445 a backslash. This backslash will be removed again by the |:!|
8446 command.
8447
8448 The "!" character will be escaped (again with a |non-zero-arg|
8449 {special}) when 'shell' contains "csh" in the tail. That is
8450 because for csh and tcsh "!" is used for history replacement
8451 even when inside single quotes.
8452
8453 With a |non-zero-arg| {special} the <NL> character is also
8454 escaped. When 'shell' containing "csh" in the tail it's
8455 escaped a second time.
8456
8457 The "\" character will be escaped when 'shell' contains "fish"
8458 in the tail. That is because for fish "\" is used as an escape
8459 character inside single quotes.
8460
8461 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008462 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008463< This results in a directory listing for the file under the
8464 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008465 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008466< See also |::S|.
8467
8468 Can also be used as a |method|: >
8469 GetCommand()->shellescape()
8470
8471shiftwidth([{col}]) *shiftwidth()*
8472 Returns the effective value of 'shiftwidth'. This is the
8473 'shiftwidth' value unless it is zero, in which case it is the
8474 'tabstop' value. This function was introduced with patch
8475 7.3.694 in 2012, everybody should have it by now (however it
8476 did not allow for the optional {col} argument until 8.1.542).
8477
8478 When there is one argument {col} this is used as column number
8479 for which to return the 'shiftwidth' value. This matters for the
8480 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8481 no {col} argument is given, column 1 will be assumed.
8482
8483 Can also be used as a |method|: >
8484 GetColumn()->shiftwidth()
8485
8486sign_ functions are documented here: |sign-functions-details|
8487
8488
8489simplify({filename}) *simplify()*
8490 Simplify the file name as much as possible without changing
8491 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8492 Unix) are not resolved. If the first path component in
8493 {filename} designates the current directory, this will be
8494 valid for the result as well. A trailing path separator is
8495 not removed either. On Unix "//path" is unchanged, but
8496 "///path" is simplified to "/path" (this follows the Posix
8497 standard).
8498 Example: >
8499 simplify("./dir/.././/file/") == "./file/"
8500< Note: The combination "dir/.." is only removed if "dir" is
8501 a searchable directory or does not exist. On Unix, it is also
8502 removed when "dir" is a symbolic link within the same
8503 directory. In order to resolve all the involved symbolic
8504 links before simplifying the path name, use |resolve()|.
8505
8506 Can also be used as a |method|: >
8507 GetName()->simplify()
8508
8509sin({expr}) *sin()*
8510 Return the sine of {expr}, measured in radians, as a |Float|.
8511 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008512 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008513 Examples: >
8514 :echo sin(100)
8515< -0.506366 >
8516 :echo sin(-4.01)
8517< 0.763301
8518
8519 Can also be used as a |method|: >
8520 Compute()->sin()
8521<
8522 {only available when compiled with the |+float| feature}
8523
8524
8525sinh({expr}) *sinh()*
8526 Return the hyperbolic sine of {expr} as a |Float| in the range
8527 [-inf, inf].
8528 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008529 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008530 Examples: >
8531 :echo sinh(0.5)
8532< 0.521095 >
8533 :echo sinh(-0.9)
8534< -1.026517
8535
8536 Can also be used as a |method|: >
8537 Compute()->sinh()
8538<
8539 {only available when compiled with the |+float| feature}
8540
8541
8542slice({expr}, {start} [, {end}]) *slice()*
8543 Similar to using a |slice| "expr[start : end]", but "end" is
8544 used exclusive. And for a string the indexes are used as
8545 character indexes instead of byte indexes, like in
8546 |vim9script|. Also, composing characters are not counted.
8547 When {end} is omitted the slice continues to the last item.
8548 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008549 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008550
8551 Can also be used as a |method|: >
8552 GetList()->slice(offset)
8553
8554
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008555sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008556 Sort the items in {list} in-place. Returns {list}.
8557
8558 If you want a list to remain unmodified make a copy first: >
8559 :let sortedlist = sort(copy(mylist))
8560
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008561< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008562 string representation of each item to sort on. Numbers sort
8563 after Strings, |Lists| after Numbers. For sorting text in the
8564 current buffer use |:sort|.
8565
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008566 When {how} is given and it is 'i' then case is ignored.
8567 In legacy script, for backwards compatibility, the value one
8568 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008569
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008570 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008571 locale is used for ordering. Implementation details: strcoll()
8572 is used to compare strings. See |:language| check or set the
8573 collation locale. |v:collate| can also be used to check the
8574 current locale. Sorting using the locale typically ignores
8575 case. Example: >
8576 " ö is sorted similarly to o with English locale.
8577 :language collate en_US.UTF8
8578 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8579< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8580>
8581 " ö is sorted after z with Swedish locale.
8582 :language collate sv_SE.UTF8
8583 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8584< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8585 This does not work properly on Mac.
8586
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008587 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008588 sorted numerical (Implementation detail: this uses the
8589 strtod() function to parse numbers, Strings, Lists, Dicts and
8590 Funcrefs will be considered as being 0).
8591
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008592 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008593 sorted numerical. This is like 'n' but a string containing
8594 digits will be used as the number they represent.
8595
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008596 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008597 sorted numerical. All values must be a Number or a Float.
8598
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008599 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008600 is called to compare items. The function is invoked with two
8601 items as argument and must return zero if they are equal, 1 or
8602 bigger if the first one sorts after the second one, -1 or
8603 smaller if the first one sorts before the second one.
8604
8605 {dict} is for functions with the "dict" attribute. It will be
8606 used to set the local variable "self". |Dictionary-function|
8607
8608 The sort is stable, items which compare equal (as number or as
8609 string) will keep their relative position. E.g., when sorting
8610 on numbers, text strings will sort next to each other, in the
8611 same order as they were originally.
8612
8613 Can also be used as a |method|: >
8614 mylist->sort()
8615
8616< Also see |uniq()|.
8617
8618 Example: >
8619 func MyCompare(i1, i2)
8620 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8621 endfunc
8622 eval mylist->sort("MyCompare")
8623< A shorter compare version for this specific simple case, which
8624 ignores overflow: >
8625 func MyCompare(i1, i2)
8626 return a:i1 - a:i2
8627 endfunc
8628< For a simple expression you can use a lambda: >
8629 eval mylist->sort({i1, i2 -> i1 - i2})
8630<
8631sound_clear() *sound_clear()*
8632 Stop playing all sounds.
8633
8634 On some Linux systems you may need the libcanberra-pulse
8635 package, otherwise sound may not stop.
8636
8637 {only available when compiled with the |+sound| feature}
8638
8639 *sound_playevent()*
8640sound_playevent({name} [, {callback}])
8641 Play a sound identified by {name}. Which event names are
8642 supported depends on the system. Often the XDG sound names
8643 are used. On Ubuntu they may be found in
8644 /usr/share/sounds/freedesktop/stereo. Example: >
8645 call sound_playevent('bell')
8646< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8647 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8648 SystemStart, SystemWelcome, etc.
8649
8650 When {callback} is specified it is invoked when the sound is
8651 finished. The first argument is the sound ID, the second
8652 argument is the status:
8653 0 sound was played to the end
8654 1 sound was interrupted
8655 2 error occurred after sound started
8656 Example: >
8657 func Callback(id, status)
8658 echomsg "sound " .. a:id .. " finished with " .. a:status
8659 endfunc
8660 call sound_playevent('bell', 'Callback')
8661
8662< MS-Windows: {callback} doesn't work for this function.
8663
8664 Returns the sound ID, which can be passed to `sound_stop()`.
8665 Returns zero if the sound could not be played.
8666
8667 Can also be used as a |method|: >
8668 GetSoundName()->sound_playevent()
8669
8670< {only available when compiled with the |+sound| feature}
8671
8672 *sound_playfile()*
8673sound_playfile({path} [, {callback}])
8674 Like `sound_playevent()` but play sound file {path}. {path}
8675 must be a full path. On Ubuntu you may find files to play
8676 with this command: >
8677 :!find /usr/share/sounds -type f | grep -v index.theme
8678
8679< Can also be used as a |method|: >
8680 GetSoundPath()->sound_playfile()
8681
Bram Moolenaar1588bc82022-03-08 21:35:07 +00008682< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008683
8684
8685sound_stop({id}) *sound_stop()*
8686 Stop playing sound {id}. {id} must be previously returned by
8687 `sound_playevent()` or `sound_playfile()`.
8688
8689 On some Linux systems you may need the libcanberra-pulse
8690 package, otherwise sound may not stop.
8691
8692 On MS-Windows, this does not work for event sound started by
8693 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8694
8695 Can also be used as a |method|: >
8696 soundid->sound_stop()
8697
8698< {only available when compiled with the |+sound| feature}
8699
8700 *soundfold()*
8701soundfold({word})
8702 Return the sound-folded equivalent of {word}. Uses the first
8703 language in 'spelllang' for the current window that supports
8704 soundfolding. 'spell' must be set. When no sound folding is
8705 possible the {word} is returned unmodified.
8706 This can be used for making spelling suggestions. Note that
8707 the method can be quite slow.
8708
8709 Can also be used as a |method|: >
8710 GetWord()->soundfold()
8711<
8712 *spellbadword()*
8713spellbadword([{sentence}])
8714 Without argument: The result is the badly spelled word under
8715 or after the cursor. The cursor is moved to the start of the
8716 bad word. When no bad word is found in the cursor line the
8717 result is an empty string and the cursor doesn't move.
8718
8719 With argument: The result is the first word in {sentence} that
8720 is badly spelled. If there are no spelling mistakes the
8721 result is an empty string.
8722
8723 The return value is a list with two items:
8724 - The badly spelled word or an empty string.
8725 - The type of the spelling error:
8726 "bad" spelling mistake
8727 "rare" rare word
8728 "local" word only valid in another region
8729 "caps" word should start with Capital
8730 Example: >
8731 echo spellbadword("the quik brown fox")
8732< ['quik', 'bad'] ~
8733
8734 The spelling information for the current window and the value
8735 of 'spelllang' are used.
8736
8737 Can also be used as a |method|: >
8738 GetText()->spellbadword()
8739<
8740 *spellsuggest()*
8741spellsuggest({word} [, {max} [, {capital}]])
8742 Return a |List| with spelling suggestions to replace {word}.
8743 When {max} is given up to this number of suggestions are
8744 returned. Otherwise up to 25 suggestions are returned.
8745
8746 When the {capital} argument is given and it's non-zero only
8747 suggestions with a leading capital will be given. Use this
8748 after a match with 'spellcapcheck'.
8749
8750 {word} can be a badly spelled word followed by other text.
8751 This allows for joining two words that were split. The
8752 suggestions also include the following text, thus you can
8753 replace a line.
8754
8755 {word} may also be a good word. Similar words will then be
8756 returned. {word} itself is not included in the suggestions,
8757 although it may appear capitalized.
8758
8759 The spelling information for the current window is used. The
8760 values of 'spelllang' and 'spellsuggest' are used.
8761
8762 Can also be used as a |method|: >
8763 GetWord()->spellsuggest()
8764
8765split({string} [, {pattern} [, {keepempty}]]) *split()*
8766 Make a |List| out of {string}. When {pattern} is omitted or
8767 empty each white-separated sequence of characters becomes an
8768 item.
8769 Otherwise the string is split where {pattern} matches,
8770 removing the matched characters. 'ignorecase' is not used
8771 here, add \c to ignore case. |/\c|
8772 When the first or last item is empty it is omitted, unless the
8773 {keepempty} argument is given and it's non-zero.
8774 Other empty items are kept when {pattern} matches at least one
8775 character or when {keepempty} is non-zero.
8776 Example: >
8777 :let words = split(getline('.'), '\W\+')
8778< To split a string in individual characters: >
8779 :for c in split(mystring, '\zs')
8780< If you want to keep the separator you can also use '\zs' at
8781 the end of the pattern: >
8782 :echo split('abc:def:ghi', ':\zs')
8783< ['abc:', 'def:', 'ghi'] ~
8784 Splitting a table where the first element can be empty: >
8785 :let items = split(line, ':', 1)
8786< The opposite function is |join()|.
8787
8788 Can also be used as a |method|: >
8789 GetString()->split()
8790
8791sqrt({expr}) *sqrt()*
8792 Return the non-negative square root of Float {expr} as a
8793 |Float|.
8794 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008795 is negative the result is NaN (Not a Number). Returns 0.0 if
8796 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008797 Examples: >
8798 :echo sqrt(100)
8799< 10.0 >
8800 :echo sqrt(-4.01)
8801< nan
8802 "nan" may be different, it depends on system libraries.
8803
8804 Can also be used as a |method|: >
8805 Compute()->sqrt()
8806<
8807 {only available when compiled with the |+float| feature}
8808
8809
8810srand([{expr}]) *srand()*
8811 Initialize seed used by |rand()|:
8812 - If {expr} is not given, seed values are initialized by
8813 reading from /dev/urandom, if possible, or using time(NULL)
8814 a.k.a. epoch time otherwise; this only has second accuracy.
8815 - If {expr} is given it must be a Number. It is used to
8816 initialize the seed values. This is useful for testing or
8817 when a predictable sequence is intended.
8818
8819 Examples: >
8820 :let seed = srand()
8821 :let seed = srand(userinput)
8822 :echo rand(seed)
8823
8824state([{what}]) *state()*
8825 Return a string which contains characters indicating the
8826 current state. Mostly useful in callbacks that want to do
8827 work that may not always be safe. Roughly this works like:
8828 - callback uses state() to check if work is safe to do.
8829 Yes: then do it right away.
8830 No: add to work queue and add a |SafeState| and/or
8831 |SafeStateAgain| autocommand (|SafeState| triggers at
8832 toplevel, |SafeStateAgain| triggers after handling
8833 messages and callbacks).
8834 - When SafeState or SafeStateAgain is triggered and executes
8835 your autocommand, check with `state()` if the work can be
8836 done now, and if yes remove it from the queue and execute.
8837 Remove the autocommand if the queue is now empty.
8838 Also see |mode()|.
8839
8840 When {what} is given only characters in this string will be
8841 added. E.g, this checks if the screen has scrolled: >
8842 if state('s') == ''
8843 " screen has not scrolled
8844<
8845 These characters indicate the state, generally indicating that
8846 something is busy:
8847 m halfway a mapping, :normal command, feedkeys() or
8848 stuffed command
8849 o operator pending, e.g. after |d|
8850 a Insert mode autocomplete active
8851 x executing an autocommand
8852 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8853 ch_readraw() when reading json
8854 S not triggering SafeState or SafeStateAgain, e.g. after
8855 |f| or a count
8856 c callback invoked, including timer (repeats for
8857 recursiveness up to "ccc")
8858 s screen has scrolled for messages
8859
8860str2float({string} [, {quoted}]) *str2float()*
8861 Convert String {string} to a Float. This mostly works the
8862 same as when using a floating point number in an expression,
8863 see |floating-point-format|. But it's a bit more permissive.
8864 E.g., "1e40" is accepted, while in an expression you need to
8865 write "1.0e40". The hexadecimal form "0x123" is also
8866 accepted, but not others, like binary or octal.
8867 When {quoted} is present and non-zero then embedded single
8868 quotes before the dot are ignored, thus "1'000.0" is a
8869 thousand.
8870 Text after the number is silently ignored.
8871 The decimal point is always '.', no matter what the locale is
8872 set to. A comma ends the number: "12,345.67" is converted to
8873 12.0. You can strip out thousands separators with
8874 |substitute()|: >
8875 let f = str2float(substitute(text, ',', '', 'g'))
8876<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008877 Returns 0.0 if the conversion fails.
8878
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008879 Can also be used as a |method|: >
8880 let f = text->substitute(',', '', 'g')->str2float()
8881<
8882 {only available when compiled with the |+float| feature}
8883
8884str2list({string} [, {utf8}]) *str2list()*
8885 Return a list containing the number values which represent
8886 each character in String {string}. Examples: >
8887 str2list(" ") returns [32]
8888 str2list("ABC") returns [65, 66, 67]
8889< |list2str()| does the opposite.
8890
8891 When {utf8} is omitted or zero, the current 'encoding' is used.
8892 When {utf8} is TRUE, always treat the String as UTF-8
8893 characters. With UTF-8 composing characters are handled
8894 properly: >
8895 str2list("á") returns [97, 769]
8896
8897< Can also be used as a |method|: >
8898 GetString()->str2list()
8899
8900
8901str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8902 Convert string {string} to a number.
8903 {base} is the conversion base, it can be 2, 8, 10 or 16.
8904 When {quoted} is present and non-zero then embedded single
8905 quotes are ignored, thus "1'000'000" is a million.
8906
8907 When {base} is omitted base 10 is used. This also means that
8908 a leading zero doesn't cause octal conversion to be used, as
8909 with the default String to Number conversion. Example: >
8910 let nr = str2nr('0123')
8911<
8912 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8913 different base the result will be zero. Similarly, when
8914 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8915 {base} is 2 a leading "0b" or "0B" is ignored.
8916 Text after the number is silently ignored.
8917
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008918 Returns 0 if {string} is empty or on error.
8919
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008920 Can also be used as a |method|: >
8921 GetText()->str2nr()
8922
8923
8924strcharlen({string}) *strcharlen()*
8925 The result is a Number, which is the number of characters
8926 in String {string}. Composing characters are ignored.
8927 |strchars()| can count the number of characters, counting
8928 composing characters separately.
8929
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008930 Returns 0 if {string} is empty or on error.
8931
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008932 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8933
8934 Can also be used as a |method|: >
8935 GetText()->strcharlen()
8936
8937
8938strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8939 Like |strpart()| but using character index and length instead
8940 of byte index and length.
8941 When {skipcc} is omitted or zero, composing characters are
8942 counted separately.
8943 When {skipcc} set to 1, Composing characters are ignored,
8944 similar to |slice()|.
8945 When a character index is used where a character does not
8946 exist it is omitted and counted as one character. For
8947 example: >
8948 strcharpart('abc', -1, 2)
8949< results in 'a'.
8950
Bram Moolenaard592deb2022-06-17 15:42:40 +01008951 Returns an empty string on error.
8952
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008953 Can also be used as a |method|: >
8954 GetText()->strcharpart(5)
8955
8956
8957strchars({string} [, {skipcc}]) *strchars()*
8958 The result is a Number, which is the number of characters
8959 in String {string}.
8960 When {skipcc} is omitted or zero, composing characters are
8961 counted separately.
8962 When {skipcc} set to 1, Composing characters are ignored.
8963 |strcharlen()| always does this.
8964
Bram Moolenaard592deb2022-06-17 15:42:40 +01008965 Returns zero on error.
8966
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008967 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8968
8969 {skipcc} is only available after 7.4.755. For backward
8970 compatibility, you can define a wrapper function: >
8971 if has("patch-7.4.755")
8972 function s:strchars(str, skipcc)
8973 return strchars(a:str, a:skipcc)
8974 endfunction
8975 else
8976 function s:strchars(str, skipcc)
8977 if a:skipcc
8978 return strlen(substitute(a:str, ".", "x", "g"))
8979 else
8980 return strchars(a:str)
8981 endif
8982 endfunction
8983 endif
8984<
8985 Can also be used as a |method|: >
8986 GetText()->strchars()
8987
8988strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8989 The result is a Number, which is the number of display cells
8990 String {string} occupies on the screen when it starts at {col}
8991 (first column is zero). When {col} is omitted zero is used.
8992 Otherwise it is the screen column where to start. This
8993 matters for Tab characters.
8994 The option settings of the current window are used. This
8995 matters for anything that's displayed differently, such as
8996 'tabstop' and 'display'.
8997 When {string} contains characters with East Asian Width Class
8998 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01008999 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009000 Also see |strlen()|, |strwidth()| and |strchars()|.
9001
9002 Can also be used as a |method|: >
9003 GetText()->strdisplaywidth()
9004
9005strftime({format} [, {time}]) *strftime()*
9006 The result is a String, which is a formatted date and time, as
9007 specified by the {format} string. The given {time} is used,
9008 or the current time if no time is given. The accepted
9009 {format} depends on your system, thus this is not portable!
9010 See the manual page of the C function strftime() for the
9011 format. The maximum length of the result is 80 characters.
9012 See also |localtime()|, |getftime()| and |strptime()|.
9013 The language can be changed with the |:language| command.
9014 Examples: >
9015 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9016 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9017 :echo strftime("%y%m%d %T") 970427 11:53:55
9018 :echo strftime("%H:%M") 11:55
9019 :echo strftime("%c", getftime("file.c"))
9020 Show mod time of file.c.
9021< Not available on all systems. To check use: >
9022 :if exists("*strftime")
9023
9024< Can also be used as a |method|: >
9025 GetFormat()->strftime()
9026
9027strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009028 Get a Number corresponding to the character at {index} in
9029 {str}. This uses a zero-based character index, not a byte
9030 index. Composing characters are considered separate
9031 characters here. Use |nr2char()| to convert the Number to a
9032 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009033 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009034 Also see |strcharpart()| and |strchars()|.
9035
9036 Can also be used as a |method|: >
9037 GetText()->strgetchar(5)
9038
9039stridx({haystack}, {needle} [, {start}]) *stridx()*
9040 The result is a Number, which gives the byte index in
9041 {haystack} of the first occurrence of the String {needle}.
9042 If {start} is specified, the search starts at index {start}.
9043 This can be used to find a second match: >
9044 :let colon1 = stridx(line, ":")
9045 :let colon2 = stridx(line, ":", colon1 + 1)
9046< The search is done case-sensitive.
9047 For pattern searches use |match()|.
9048 -1 is returned if the {needle} does not occur in {haystack}.
9049 See also |strridx()|.
9050 Examples: >
9051 :echo stridx("An Example", "Example") 3
9052 :echo stridx("Starting point", "Start") 0
9053 :echo stridx("Starting point", "start") -1
9054< *strstr()* *strchr()*
9055 stridx() works similar to the C function strstr(). When used
9056 with a single character it works similar to strchr().
9057
9058 Can also be used as a |method|: >
9059 GetHaystack()->stridx(needle)
9060<
9061 *string()*
9062string({expr}) Return {expr} converted to a String. If {expr} is a Number,
9063 Float, String, Blob or a composition of them, then the result
9064 can be parsed back with |eval()|.
9065 {expr} type result ~
9066 String 'string' (single quotes are doubled)
9067 Number 123
9068 Float 123.123456 or 1.123456e8
9069 Funcref function('name')
9070 Blob 0z00112233.44556677.8899
9071 List [item, item]
9072 Dictionary {key: value, key: value}
9073
9074 When a |List| or |Dictionary| has a recursive reference it is
9075 replaced by "[...]" or "{...}". Using eval() on the result
9076 will then fail.
9077
9078 Can also be used as a |method|: >
9079 mylist->string()
9080
9081< Also see |strtrans()|.
9082
9083
9084strlen({string}) *strlen()*
9085 The result is a Number, which is the length of the String
9086 {string} in bytes.
9087 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009088 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009089 If you want to count the number of multibyte characters use
9090 |strchars()|.
9091 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9092
9093 Can also be used as a |method|: >
9094 GetString()->strlen()
9095
9096strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9097 The result is a String, which is part of {src}, starting from
9098 byte {start}, with the byte length {len}.
9099 When {chars} is present and TRUE then {len} is the number of
9100 characters positions (composing characters are not counted
9101 separately, thus "1" means one base character and any
9102 following composing characters).
9103 To count {start} as characters instead of bytes use
9104 |strcharpart()|.
9105
9106 When bytes are selected which do not exist, this doesn't
9107 result in an error, the bytes are simply omitted.
9108 If {len} is missing, the copy continues from {start} till the
9109 end of the {src}. >
9110 strpart("abcdefg", 3, 2) == "de"
9111 strpart("abcdefg", -2, 4) == "ab"
9112 strpart("abcdefg", 5, 4) == "fg"
9113 strpart("abcdefg", 3) == "defg"
9114
9115< Note: To get the first character, {start} must be 0. For
9116 example, to get the character under the cursor: >
9117 strpart(getline("."), col(".") - 1, 1, v:true)
9118<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009119 Returns an empty string on error.
9120
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009121 Can also be used as a |method|: >
9122 GetText()->strpart(5)
9123
9124strptime({format}, {timestring}) *strptime()*
9125 The result is a Number, which is a unix timestamp representing
9126 the date and time in {timestring}, which is expected to match
9127 the format specified in {format}.
9128
9129 The accepted {format} depends on your system, thus this is not
9130 portable! See the manual page of the C function strptime()
9131 for the format. Especially avoid "%c". The value of $TZ also
9132 matters.
9133
9134 If the {timestring} cannot be parsed with {format} zero is
9135 returned. If you do not know the format of {timestring} you
9136 can try different {format} values until you get a non-zero
9137 result.
9138
9139 See also |strftime()|.
9140 Examples: >
9141 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9142< 862156163 >
9143 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9144< Sun Apr 27 11:53:55 1997 >
9145 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9146< Sun Apr 27 12:53:55 1997
9147
9148 Can also be used as a |method|: >
9149 GetFormat()->strptime(timestring)
9150<
9151 Not available on all systems. To check use: >
9152 :if exists("*strptime")
9153
9154strridx({haystack}, {needle} [, {start}]) *strridx()*
9155 The result is a Number, which gives the byte index in
9156 {haystack} of the last occurrence of the String {needle}.
9157 When {start} is specified, matches beyond this index are
9158 ignored. This can be used to find a match before a previous
9159 match: >
9160 :let lastcomma = strridx(line, ",")
9161 :let comma2 = strridx(line, ",", lastcomma - 1)
9162< The search is done case-sensitive.
9163 For pattern searches use |match()|.
9164 -1 is returned if the {needle} does not occur in {haystack}.
9165 If the {needle} is empty the length of {haystack} is returned.
9166 See also |stridx()|. Examples: >
9167 :echo strridx("an angry armadillo", "an") 3
9168< *strrchr()*
9169 When used with a single character it works similar to the C
9170 function strrchr().
9171
9172 Can also be used as a |method|: >
9173 GetHaystack()->strridx(needle)
9174
9175strtrans({string}) *strtrans()*
9176 The result is a String, which is {string} with all unprintable
9177 characters translated into printable characters |'isprint'|.
9178 Like they are shown in a window. Example: >
9179 echo strtrans(@a)
9180< This displays a newline in register a as "^@" instead of
9181 starting a new line.
9182
Bram Moolenaard592deb2022-06-17 15:42:40 +01009183 Returns an empty string on error.
9184
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009185 Can also be used as a |method|: >
9186 GetString()->strtrans()
9187
9188strwidth({string}) *strwidth()*
9189 The result is a Number, which is the number of display cells
9190 String {string} occupies. A Tab character is counted as one
9191 cell, alternatively use |strdisplaywidth()|.
9192 When {string} contains characters with East Asian Width Class
9193 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009194 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009195 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9196
9197 Can also be used as a |method|: >
9198 GetString()->strwidth()
9199
9200submatch({nr} [, {list}]) *submatch()* *E935*
9201 Only for an expression in a |:substitute| command or
9202 substitute() function.
9203 Returns the {nr}'th submatch of the matched text. When {nr}
9204 is 0 the whole matched text is returned.
9205 Note that a NL in the string can stand for a line break of a
9206 multi-line match or a NUL character in the text.
9207 Also see |sub-replace-expression|.
9208
9209 If {list} is present and non-zero then submatch() returns
9210 a list of strings, similar to |getline()| with two arguments.
9211 NL characters in the text represent NUL characters in the
9212 text.
9213 Only returns more than one item for |:substitute|, inside
9214 |substitute()| this list will always contain one or zero
9215 items, since there are no real line breaks.
9216
9217 When substitute() is used recursively only the submatches in
9218 the current (deepest) call can be obtained.
9219
Bram Moolenaard592deb2022-06-17 15:42:40 +01009220 Returns an empty string or list on error.
9221
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009222 Examples: >
9223 :s/\d\+/\=submatch(0) + 1/
9224 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9225< This finds the first number in the line and adds one to it.
9226 A line break is included as a newline character.
9227
9228 Can also be used as a |method|: >
9229 GetNr()->submatch()
9230
9231substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9232 The result is a String, which is a copy of {string}, in which
9233 the first match of {pat} is replaced with {sub}.
9234 When {flags} is "g", all matches of {pat} in {string} are
9235 replaced. Otherwise {flags} should be "".
9236
9237 This works like the ":substitute" command (without any flags).
9238 But the matching with {pat} is always done like the 'magic'
9239 option is set and 'cpoptions' is empty (to make scripts
9240 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9241 if you want to ignore or match case and ignore 'ignorecase'.
9242 'smartcase' is not used. See |string-match| for how {pat} is
9243 used.
9244
9245 A "~" in {sub} is not replaced with the previous {sub}.
9246 Note that some codes in {sub} have a special meaning
9247 |sub-replace-special|. For example, to replace something with
9248 "\n" (two characters), use "\\\\n" or '\\n'.
9249
9250 When {pat} does not match in {string}, {string} is returned
9251 unmodified.
9252
9253 Example: >
9254 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9255< This removes the last component of the 'path' option. >
9256 :echo substitute("testing", ".*", "\\U\\0", "")
9257< results in "TESTING".
9258
9259 When {sub} starts with "\=", the remainder is interpreted as
9260 an expression. See |sub-replace-expression|. Example: >
9261 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009262 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009263
9264< When {sub} is a Funcref that function is called, with one
9265 optional argument. Example: >
9266 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9267< The optional argument is a list which contains the whole
9268 matched string and up to nine submatches, like what
9269 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009270 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009271
Bram Moolenaard592deb2022-06-17 15:42:40 +01009272< Returns an empty string on error.
9273
9274 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009275 GetString()->substitute(pat, sub, flags)
9276
9277swapinfo({fname}) *swapinfo()*
9278 The result is a dictionary, which holds information about the
9279 swapfile {fname}. The available fields are:
9280 version Vim version
9281 user user name
9282 host host name
9283 fname original file name
9284 pid PID of the Vim process that created the swap
9285 file
9286 mtime last modification time in seconds
9287 inode Optional: INODE number of the file
9288 dirty 1 if file was modified, 0 if not
9289 Note that "user" and "host" are truncated to at most 39 bytes.
9290 In case of failure an "error" item is added with the reason:
9291 Cannot open file: file not found or in accessible
9292 Cannot read file: cannot read first block
9293 Not a swap file: does not contain correct block ID
9294 Magic number mismatch: Info in first block is invalid
9295
9296 Can also be used as a |method|: >
9297 GetFilename()->swapinfo()
9298
9299swapname({buf}) *swapname()*
9300 The result is the swap file path of the buffer {expr}.
9301 For the use of {buf}, see |bufname()| above.
9302 If buffer {buf} is the current buffer, the result is equal to
9303 |:swapname| (unless there is no swap file).
9304 If buffer {buf} has no swap file, returns an empty string.
9305
9306 Can also be used as a |method|: >
9307 GetBufname()->swapname()
9308
9309synID({lnum}, {col}, {trans}) *synID()*
9310 The result is a Number, which is the syntax ID at the position
9311 {lnum} and {col} in the current window.
9312 The syntax ID can be used with |synIDattr()| and
9313 |synIDtrans()| to obtain syntax information about text.
9314
9315 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9316 line. 'synmaxcol' applies, in a longer line zero is returned.
9317 Note that when the position is after the last character,
9318 that's where the cursor can be in Insert mode, synID() returns
9319 zero. {lnum} is used like with |getline()|.
9320
9321 When {trans} is |TRUE|, transparent items are reduced to the
9322 item that they reveal. This is useful when wanting to know
9323 the effective color. When {trans} is |FALSE|, the transparent
9324 item is returned. This is useful when wanting to know which
9325 syntax item is effective (e.g. inside parens).
9326 Warning: This function can be very slow. Best speed is
9327 obtained by going through the file in forward direction.
9328
Bram Moolenaard592deb2022-06-17 15:42:40 +01009329 Returns zero on error.
9330
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009331 Example (echoes the name of the syntax item under the cursor): >
9332 :echo synIDattr(synID(line("."), col("."), 1), "name")
9333<
9334
9335synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9336 The result is a String, which is the {what} attribute of
9337 syntax ID {synID}. This can be used to obtain information
9338 about a syntax item.
9339 {mode} can be "gui", "cterm" or "term", to get the attributes
9340 for that mode. When {mode} is omitted, or an invalid value is
9341 used, the attributes for the currently active highlighting are
9342 used (GUI, cterm or term).
9343 Use synIDtrans() to follow linked highlight groups.
9344 {what} result
9345 "name" the name of the syntax item
9346 "fg" foreground color (GUI: color name used to set
9347 the color, cterm: color number as a string,
9348 term: empty string)
9349 "bg" background color (as with "fg")
9350 "font" font name (only available in the GUI)
9351 |highlight-font|
9352 "sp" special color for the GUI (as with "fg")
9353 |highlight-guisp|
9354 "ul" underline color for cterm: number as a string
9355 "fg#" like "fg", but for the GUI and the GUI is
9356 running the name in "#RRGGBB" form
9357 "bg#" like "fg#" for "bg"
9358 "sp#" like "fg#" for "sp"
9359 "bold" "1" if bold
9360 "italic" "1" if italic
9361 "reverse" "1" if reverse
9362 "inverse" "1" if inverse (= reverse)
9363 "standout" "1" if standout
9364 "underline" "1" if underlined
9365 "undercurl" "1" if undercurled
9366 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009367 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009368
Bram Moolenaard592deb2022-06-17 15:42:40 +01009369 Returns an empty string on error.
9370
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009371 Example (echoes the color of the syntax item under the
9372 cursor): >
9373 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9374<
9375 Can also be used as a |method|: >
9376 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9377
9378
9379synIDtrans({synID}) *synIDtrans()*
9380 The result is a Number, which is the translated syntax ID of
9381 {synID}. This is the syntax group ID of what is being used to
9382 highlight the character. Highlight links given with
9383 ":highlight link" are followed.
9384
Bram Moolenaard592deb2022-06-17 15:42:40 +01009385 Returns zero on error.
9386
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009387 Can also be used as a |method|: >
9388 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9389
9390synconcealed({lnum}, {col}) *synconcealed()*
9391 The result is a |List| with currently three items:
9392 1. The first item in the list is 0 if the character at the
9393 position {lnum} and {col} is not part of a concealable
9394 region, 1 if it is. {lnum} is used like with |getline()|.
9395 2. The second item in the list is a string. If the first item
9396 is 1, the second item contains the text which will be
9397 displayed in place of the concealed text, depending on the
9398 current setting of 'conceallevel' and 'listchars'.
9399 3. The third and final item in the list is a number
9400 representing the specific syntax region matched in the
9401 line. When the character is not concealed the value is
9402 zero. This allows detection of the beginning of a new
9403 concealable region if there are two consecutive regions
9404 with the same replacement character. For an example, if
9405 the text is "123456" and both "23" and "45" are concealed
9406 and replaced by the character "X", then:
9407 call returns ~
9408 synconcealed(lnum, 1) [0, '', 0]
9409 synconcealed(lnum, 2) [1, 'X', 1]
9410 synconcealed(lnum, 3) [1, 'X', 1]
9411 synconcealed(lnum, 4) [1, 'X', 2]
9412 synconcealed(lnum, 5) [1, 'X', 2]
9413 synconcealed(lnum, 6) [0, '', 0]
9414
9415
9416synstack({lnum}, {col}) *synstack()*
9417 Return a |List|, which is the stack of syntax items at the
9418 position {lnum} and {col} in the current window. {lnum} is
9419 used like with |getline()|. Each item in the List is an ID
9420 like what |synID()| returns.
9421 The first item in the List is the outer region, following are
9422 items contained in that one. The last one is what |synID()|
9423 returns, unless not the whole item is highlighted or it is a
9424 transparent item.
9425 This function is useful for debugging a syntax file.
9426 Example that shows the syntax stack under the cursor: >
9427 for id in synstack(line("."), col("."))
9428 echo synIDattr(id, "name")
9429 endfor
9430< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +01009431 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009432 character in a line and the first column in an empty line are
9433 valid positions.
9434
9435system({expr} [, {input}]) *system()* *E677*
9436 Get the output of the shell command {expr} as a |String|. See
9437 |systemlist()| to get the output as a |List|.
9438
9439 When {input} is given and is a |String| this string is written
9440 to a file and passed as stdin to the command. The string is
9441 written as-is, you need to take care of using the correct line
9442 separators yourself.
9443 If {input} is given and is a |List| it is written to the file
9444 in a way |writefile()| does with {binary} set to "b" (i.e.
9445 with a newline between each list item with newlines inside
9446 list items converted to NULs).
9447 When {input} is given and is a number that is a valid id for
9448 an existing buffer then the content of the buffer is written
9449 to the file line by line, each line terminated by a NL and
9450 NULs characters where the text has a NL.
9451
9452 Pipes are not used, the 'shelltemp' option is not used.
9453
9454 When prepended by |:silent| the terminal will not be set to
9455 cooked mode. This is meant to be used for commands that do
9456 not need the user to type. It avoids stray characters showing
9457 up on the screen which require |CTRL-L| to remove. >
9458 :silent let f = system('ls *.vim')
9459<
9460 Note: Use |shellescape()| or |::S| with |expand()| or
9461 |fnamemodify()| to escape special characters in a command
9462 argument. Newlines in {expr} may cause the command to fail.
9463 The characters in 'shellquote' and 'shellxquote' may also
9464 cause trouble.
9465 This is not to be used for interactive commands.
9466
9467 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009468 :let files = system('ls ' .. shellescape(expand('%:h')))
9469 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009470
9471< To make the result more system-independent, the shell output
9472 is filtered to replace <CR> with <NL> for Macintosh, and
9473 <CR><NL> with <NL> for DOS-like systems.
9474 To avoid the string being truncated at a NUL, all NUL
9475 characters are replaced with SOH (0x01).
9476
9477 The command executed is constructed using several options:
9478 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9479 ({tmp} is an automatically generated file name).
9480 For Unix, braces are put around {expr} to allow for
9481 concatenated commands.
9482
9483 The command will be executed in "cooked" mode, so that a
9484 CTRL-C will interrupt the command (on Unix at least).
9485
9486 The resulting error code can be found in |v:shell_error|.
9487 This function will fail in |restricted-mode|.
9488
9489 Note that any wrong value in the options mentioned above may
9490 make the function fail. It has also been reported to fail
9491 when using a security agent application.
9492 Unlike ":!cmd" there is no automatic check for changed files.
9493 Use |:checktime| to force a check.
9494
9495 Can also be used as a |method|: >
9496 :echo GetCmd()->system()
9497
9498
9499systemlist({expr} [, {input}]) *systemlist()*
9500 Same as |system()|, but returns a |List| with lines (parts of
9501 output separated by NL) with NULs transformed into NLs. Output
9502 is the same as |readfile()| will output with {binary} argument
9503 set to "b", except that there is no extra empty item when the
9504 result ends in a NL.
9505 Note that on MS-Windows you may get trailing CR characters.
9506
9507 To see the difference between "echo hello" and "echo -n hello"
9508 use |system()| and |split()|: >
9509 echo system('echo hello')->split('\n', 1)
9510<
9511 Returns an empty string on error.
9512
9513 Can also be used as a |method|: >
9514 :echo GetCmd()->systemlist()
9515
9516
9517tabpagebuflist([{arg}]) *tabpagebuflist()*
9518 The result is a |List|, where each item is the number of the
9519 buffer associated with each window in the current tab page.
9520 {arg} specifies the number of the tab page to be used. When
9521 omitted the current tab page is used.
9522 When {arg} is invalid the number zero is returned.
9523 To get a list of all buffers in all tabs use this: >
9524 let buflist = []
9525 for i in range(tabpagenr('$'))
9526 call extend(buflist, tabpagebuflist(i + 1))
9527 endfor
9528< Note that a buffer may appear in more than one window.
9529
9530 Can also be used as a |method|: >
9531 GetTabpage()->tabpagebuflist()
9532
9533tabpagenr([{arg}]) *tabpagenr()*
9534 The result is a Number, which is the number of the current
9535 tab page. The first tab page has number 1.
9536
9537 The optional argument {arg} supports the following values:
9538 $ the number of the last tab page (the tab page
9539 count).
9540 # the number of the last accessed tab page
9541 (where |g<Tab>| goes to). if there is no
9542 previous tab page 0 is returned.
9543 The number can be used with the |:tab| command.
9544
Bram Moolenaard592deb2022-06-17 15:42:40 +01009545 Returns zero on error.
9546
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009547
9548tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9549 Like |winnr()| but for tab page {tabarg}.
9550 {tabarg} specifies the number of tab page to be used.
9551 {arg} is used like with |winnr()|:
9552 - When omitted the current window number is returned. This is
9553 the window which will be used when going to this tab page.
9554 - When "$" the number of windows is returned.
9555 - When "#" the previous window nr is returned.
9556 Useful examples: >
9557 tabpagewinnr(1) " current window of tab page 1
9558 tabpagewinnr(4, '$') " number of windows in tab page 4
9559< When {tabarg} is invalid zero is returned.
9560
9561 Can also be used as a |method|: >
9562 GetTabpage()->tabpagewinnr()
9563<
9564 *tagfiles()*
9565tagfiles() Returns a |List| with the file names used to search for tags
9566 for the current buffer. This is the 'tags' option expanded.
9567
9568
9569taglist({expr} [, {filename}]) *taglist()*
9570 Returns a |List| of tags matching the regular expression {expr}.
9571
9572 If {filename} is passed it is used to prioritize the results
9573 in the same way that |:tselect| does. See |tag-priority|.
9574 {filename} should be the full path of the file.
9575
9576 Each list item is a dictionary with at least the following
9577 entries:
9578 name Name of the tag.
9579 filename Name of the file where the tag is
9580 defined. It is either relative to the
9581 current directory or a full path.
9582 cmd Ex command used to locate the tag in
9583 the file.
9584 kind Type of the tag. The value for this
9585 entry depends on the language specific
9586 kind values. Only available when
9587 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +00009588 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009589 static A file specific tag. Refer to
9590 |static-tag| for more information.
9591 More entries may be present, depending on the content of the
9592 tags file: access, implementation, inherits and signature.
9593 Refer to the ctags documentation for information about these
9594 fields. For C code the fields "struct", "class" and "enum"
9595 may appear, they give the name of the entity the tag is
9596 contained in.
9597
9598 The ex-command "cmd" can be either an ex search pattern, a
9599 line number or a line number followed by a byte number.
9600
9601 If there are no matching tags, then an empty list is returned.
9602
9603 To get an exact tag match, the anchors '^' and '$' should be
9604 used in {expr}. This also make the function work faster.
9605 Refer to |tag-regexp| for more information about the tag
9606 search regular expression pattern.
9607
9608 Refer to |'tags'| for information about how the tags file is
9609 located by Vim. Refer to |tags-file-format| for the format of
9610 the tags file generated by the different ctags tools.
9611
9612 Can also be used as a |method|: >
9613 GetTagpattern()->taglist()
9614
9615tan({expr}) *tan()*
9616 Return the tangent of {expr}, measured in radians, as a |Float|
9617 in the range [-inf, inf].
9618 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009619 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009620 Examples: >
9621 :echo tan(10)
9622< 0.648361 >
9623 :echo tan(-4.01)
9624< -1.181502
9625
9626 Can also be used as a |method|: >
9627 Compute()->tan()
9628<
9629 {only available when compiled with the |+float| feature}
9630
9631
9632tanh({expr}) *tanh()*
9633 Return the hyperbolic tangent of {expr} as a |Float| in the
9634 range [-1, 1].
9635 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009636 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009637 Examples: >
9638 :echo tanh(0.5)
9639< 0.462117 >
9640 :echo tanh(-1)
9641< -0.761594
9642
9643 Can also be used as a |method|: >
9644 Compute()->tanh()
9645<
9646 {only available when compiled with the |+float| feature}
9647
9648
9649tempname() *tempname()* *temp-file-name*
9650 The result is a String, which is the name of a file that
9651 doesn't exist. It can be used for a temporary file. The name
9652 is different for at least 26 consecutive calls. Example: >
9653 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009654 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009655< For Unix, the file will be in a private directory |tempfile|.
9656 For MS-Windows forward slashes are used when the 'shellslash'
9657 option is set, or when 'shellcmdflag' starts with '-' and
9658 'shell' does not contain powershell or pwsh.
9659
9660
9661term_ functions are documented here: |terminal-function-details|
9662
9663
9664terminalprops() *terminalprops()*
9665 Returns a |Dictionary| with properties of the terminal that Vim
9666 detected from the response to |t_RV| request. See
9667 |v:termresponse| for the response itself. If |v:termresponse|
9668 is empty most values here will be 'u' for unknown.
9669 cursor_style whether sending |t_RS| works **
9670 cursor_blink_mode whether sending |t_RC| works **
9671 underline_rgb whether |t_8u| works **
9672 mouse mouse type supported
9673
9674 ** value 'u' for unknown, 'y' for yes, 'n' for no
9675
9676 If the |+termresponse| feature is missing then the result is
9677 an empty dictionary.
9678
9679 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9680 current cursor style.
9681 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9682 request the cursor blink status.
9683 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9684 is not empty, Vim will detect the working of sending |t_RS|
9685 and |t_RC| on startup.
9686
9687 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9688 This avoids sending it to xterm, which would clear the colors.
9689
9690 For "mouse" the value 'u' is unknown
9691
9692 Also see:
9693 - 'ambiwidth' - detected by using |t_u7|.
9694 - |v:termstyleresp| and |v:termblinkresp| for the response to
9695 |t_RS| and |t_RC|.
9696
9697
9698test_ functions are documented here: |test-functions-details|
9699
9700
9701 *timer_info()*
9702timer_info([{id}])
9703 Return a list with information about timers.
9704 When {id} is given only information about this timer is
9705 returned. When timer {id} does not exist an empty list is
9706 returned.
9707 When {id} is omitted information about all timers is returned.
9708
9709 For each timer the information is stored in a |Dictionary| with
9710 these items:
9711 "id" the timer ID
9712 "time" time the timer was started with
9713 "remaining" time until the timer fires
9714 "repeat" number of times the timer will still fire;
9715 -1 means forever
9716 "callback" the callback
9717 "paused" 1 if the timer is paused, 0 otherwise
9718
9719 Can also be used as a |method|: >
9720 GetTimer()->timer_info()
9721
9722< {only available when compiled with the |+timers| feature}
9723
9724timer_pause({timer}, {paused}) *timer_pause()*
9725 Pause or unpause a timer. A paused timer does not invoke its
9726 callback when its time expires. Unpausing a timer may cause
9727 the callback to be invoked almost immediately if enough time
9728 has passed.
9729
9730 Pausing a timer is useful to avoid the callback to be called
9731 for a short time.
9732
9733 If {paused} evaluates to a non-zero Number or a non-empty
9734 String, then the timer is paused, otherwise it is unpaused.
9735 See |non-zero-arg|.
9736
9737 Can also be used as a |method|: >
9738 GetTimer()->timer_pause(1)
9739
9740< {only available when compiled with the |+timers| feature}
9741
9742 *timer_start()* *timer* *timers*
9743timer_start({time}, {callback} [, {options}])
9744 Create a timer and return the timer ID.
9745
9746 {time} is the waiting time in milliseconds. This is the
9747 minimum time before invoking the callback. When the system is
9748 busy or Vim is not waiting for input the time will be longer.
9749
9750 {callback} is the function to call. It can be the name of a
9751 function or a |Funcref|. It is called with one argument, which
9752 is the timer ID. The callback is only invoked when Vim is
9753 waiting for input.
9754 If you want to show a message look at |popup_notification()|
9755 to avoid interfering with what the user is doing.
9756
9757 {options} is a dictionary. Supported entries:
9758 "repeat" Number of times to repeat calling the
9759 callback. -1 means forever. When not present
9760 the callback will be called once.
9761 If the timer causes an error three times in a
9762 row the repeat is cancelled. This avoids that
9763 Vim becomes unusable because of all the error
9764 messages.
9765
Bram Moolenaard592deb2022-06-17 15:42:40 +01009766 Returns -1 on error.
9767
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009768 Example: >
9769 func MyHandler(timer)
9770 echo 'Handler called'
9771 endfunc
9772 let timer = timer_start(500, 'MyHandler',
9773 \ {'repeat': 3})
9774< This will invoke MyHandler() three times at 500 msec
9775 intervals.
9776
9777 Can also be used as a |method|: >
9778 GetMsec()->timer_start(callback)
9779
9780< Not available in the |sandbox|.
9781 {only available when compiled with the |+timers| feature}
9782
9783timer_stop({timer}) *timer_stop()*
9784 Stop a timer. The timer callback will no longer be invoked.
9785 {timer} is an ID returned by timer_start(), thus it must be a
9786 Number. If {timer} does not exist there is no error.
9787
9788 Can also be used as a |method|: >
9789 GetTimer()->timer_stop()
9790
9791< {only available when compiled with the |+timers| feature}
9792
9793timer_stopall() *timer_stopall()*
9794 Stop all timers. The timer callbacks will no longer be
9795 invoked. Useful if a timer is misbehaving. If there are no
9796 timers there is no error.
9797
9798 {only available when compiled with the |+timers| feature}
9799
9800tolower({expr}) *tolower()*
9801 The result is a copy of the String given, with all uppercase
9802 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009803 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009804
9805 Can also be used as a |method|: >
9806 GetText()->tolower()
9807
9808toupper({expr}) *toupper()*
9809 The result is a copy of the String given, with all lowercase
9810 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009811 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009812
9813 Can also be used as a |method|: >
9814 GetText()->toupper()
9815
9816tr({src}, {fromstr}, {tostr}) *tr()*
9817 The result is a copy of the {src} string with all characters
9818 which appear in {fromstr} replaced by the character in that
9819 position in the {tostr} string. Thus the first character in
9820 {fromstr} is translated into the first character in {tostr}
9821 and so on. Exactly like the unix "tr" command.
9822 This code also deals with multibyte characters properly.
9823
Bram Moolenaard592deb2022-06-17 15:42:40 +01009824 Returns an empty string on error.
9825
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009826 Examples: >
9827 echo tr("hello there", "ht", "HT")
9828< returns "Hello THere" >
9829 echo tr("<blob>", "<>", "{}")
9830< returns "{blob}"
9831
9832 Can also be used as a |method|: >
9833 GetText()->tr(from, to)
9834
9835trim({text} [, {mask} [, {dir}]]) *trim()*
9836 Return {text} as a String where any character in {mask} is
9837 removed from the beginning and/or end of {text}.
9838
9839 If {mask} is not given, {mask} is all characters up to 0x20,
9840 which includes Tab, space, NL and CR, plus the non-breaking
9841 space character 0xa0.
9842
9843 The optional {dir} argument specifies where to remove the
9844 characters:
9845 0 remove from the beginning and end of {text}
9846 1 remove only at the beginning of {text}
9847 2 remove only at the end of {text}
9848 When omitted both ends are trimmed.
9849
9850 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009851 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009852
9853 Examples: >
9854 echo trim(" some text ")
9855< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009856 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009857< returns "RESERVE_TAIL" >
9858 echo trim("rm<Xrm<>X>rrm", "rm<>")
9859< returns "Xrm<>X" (characters in the middle are not removed) >
9860 echo trim(" vim ", " ", 2)
9861< returns " vim"
9862
9863 Can also be used as a |method|: >
9864 GetText()->trim()
9865
9866trunc({expr}) *trunc()*
9867 Return the largest integral value with magnitude less than or
9868 equal to {expr} as a |Float| (truncate towards zero).
9869 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009870 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009871 Examples: >
9872 echo trunc(1.456)
9873< 1.0 >
9874 echo trunc(-5.456)
9875< -5.0 >
9876 echo trunc(4.0)
9877< 4.0
9878
9879 Can also be used as a |method|: >
9880 Compute()->trunc()
9881<
9882 {only available when compiled with the |+float| feature}
9883
9884 *type()*
9885type({expr}) The result is a Number representing the type of {expr}.
9886 Instead of using the number directly, it is better to use the
9887 v:t_ variable that has the value:
9888 Number: 0 |v:t_number|
9889 String: 1 |v:t_string|
9890 Funcref: 2 |v:t_func|
9891 List: 3 |v:t_list|
9892 Dictionary: 4 |v:t_dict|
9893 Float: 5 |v:t_float|
9894 Boolean: 6 |v:t_bool| (v:false and v:true)
9895 None: 7 |v:t_none| (v:null and v:none)
9896 Job: 8 |v:t_job|
9897 Channel: 9 |v:t_channel|
9898 Blob: 10 |v:t_blob|
9899 For backward compatibility, this method can be used: >
9900 :if type(myvar) == type(0)
9901 :if type(myvar) == type("")
9902 :if type(myvar) == type(function("tr"))
9903 :if type(myvar) == type([])
9904 :if type(myvar) == type({})
9905 :if type(myvar) == type(0.0)
9906 :if type(myvar) == type(v:false)
9907 :if type(myvar) == type(v:none)
9908< To check if the v:t_ variables exist use this: >
9909 :if exists('v:t_number')
9910
9911< Can also be used as a |method|: >
9912 mylist->type()
9913
9914
9915typename({expr}) *typename()*
9916 Return a string representation of the type of {expr}.
9917 Example: >
9918 echo typename([1, 2, 3])
9919 list<number>
9920
9921
9922undofile({name}) *undofile()*
9923 Return the name of the undo file that would be used for a file
9924 with name {name} when writing. This uses the 'undodir'
9925 option, finding directories that exist. It does not check if
9926 the undo file exists.
9927 {name} is always expanded to the full path, since that is what
9928 is used internally.
9929 If {name} is empty undofile() returns an empty string, since a
9930 buffer without a file name will not write an undo file.
9931 Useful in combination with |:wundo| and |:rundo|.
9932 When compiled without the |+persistent_undo| option this always
9933 returns an empty string.
9934
9935 Can also be used as a |method|: >
9936 GetFilename()->undofile()
9937
9938undotree() *undotree()*
9939 Return the current state of the undo tree in a dictionary with
9940 the following items:
9941 "seq_last" The highest undo sequence number used.
9942 "seq_cur" The sequence number of the current position in
9943 the undo tree. This differs from "seq_last"
9944 when some changes were undone.
9945 "time_cur" Time last used for |:earlier| and related
9946 commands. Use |strftime()| to convert to
9947 something readable.
9948 "save_last" Number of the last file write. Zero when no
9949 write yet.
9950 "save_cur" Number of the current position in the undo
9951 tree.
9952 "synced" Non-zero when the last undo block was synced.
9953 This happens when waiting from input from the
9954 user. See |undo-blocks|.
9955 "entries" A list of dictionaries with information about
9956 undo blocks.
9957
9958 The first item in the "entries" list is the oldest undo item.
9959 Each List item is a |Dictionary| with these items:
9960 "seq" Undo sequence number. Same as what appears in
9961 |:undolist|.
9962 "time" Timestamp when the change happened. Use
9963 |strftime()| to convert to something readable.
9964 "newhead" Only appears in the item that is the last one
9965 that was added. This marks the last change
9966 and where further changes will be added.
9967 "curhead" Only appears in the item that is the last one
9968 that was undone. This marks the current
9969 position in the undo tree, the block that will
9970 be used by a redo command. When nothing was
9971 undone after the last change this item will
9972 not appear anywhere.
9973 "save" Only appears on the last block before a file
9974 write. The number is the write count. The
9975 first write has number 1, the last one the
9976 "save_last" mentioned above.
9977 "alt" Alternate entry. This is again a List of undo
9978 blocks. Each item may again have an "alt"
9979 item.
9980
9981uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9982 Remove second and succeeding copies of repeated adjacent
9983 {list} items in-place. Returns {list}. If you want a list
9984 to remain unmodified make a copy first: >
9985 :let newlist = uniq(copy(mylist))
9986< The default compare function uses the string representation of
9987 each item. For the use of {func} and {dict} see |sort()|.
9988
Bram Moolenaard592deb2022-06-17 15:42:40 +01009989 Returns zero if {list} is not a |List|.
9990
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009991 Can also be used as a |method|: >
9992 mylist->uniq()
9993
9994values({dict}) *values()*
9995 Return a |List| with all the values of {dict}. The |List| is
9996 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009997 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009998
9999 Can also be used as a |method|: >
10000 mydict->values()
10001
LemonBoy0f7a3e12022-05-26 12:10:37 +010010002virtcol({expr} [, {list}]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010003 The result is a Number, which is the screen column of the file
10004 position given with {expr}. That is, the last screen position
10005 occupied by the character at that position, when the screen
10006 would be of unlimited width. When there is a <Tab> at the
10007 position, the returned Number will be the column at the end of
10008 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
10009 set to 8, it returns 8. |conceal| is ignored.
10010 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010011
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010012 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010013
10014 When 'virtualedit' is used {expr} can be [lnum, col, off],
10015 where "off" is the offset in screen columns from the start of
10016 the character. E.g., a position within a <Tab> or after the
10017 last character. When "off" is omitted zero is used. When
10018 Virtual editing is active in the current mode, a position
10019 beyond the end of the line can be returned. Also see
10020 |'virtualedit'|
10021
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010022 The accepted positions are:
10023 . the cursor position
10024 $ the end of the cursor line (the result is the
10025 number of displayed characters in the cursor line
10026 plus one)
10027 'x position of mark x (if the mark is not set, 0 is
10028 returned)
10029 v In Visual mode: the start of the Visual area (the
10030 cursor is the end). When not in Visual mode
10031 returns the cursor position. Differs from |'<| in
10032 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010033
10034 If {list} is present and non-zero then virtcol() returns a List
10035 with the first and last screen position occupied by the
10036 character.
10037
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010038 Note that only marks in the current file can be used.
10039 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010010040 " With text "foo^Lbar" and cursor on the "^L":
10041
10042 virtcol(".") " returns 5
10043 virtcol(".", 1) " returns [4, 5]
10044 virtcol("$") " returns 9
10045
10046 " With text " there", with 't at 'h':
10047
10048 virtcol("'t") " returns 6
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010049< The first column is 1. 0 is returned for an error.
10050 A more advanced example that echoes the maximum length of
10051 all lines: >
10052 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10053
10054< Can also be used as a |method|: >
10055 GetPos()->virtcol()
10056
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010057virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
10058 The result is a Number, which is the byte index of the
10059 character in window {winid} at buffer line {lnum} and virtual
10060 column {col}.
10061
10062 If {col} is greater than the last virtual column in line
10063 {lnum}, then the byte index of the character at the last
10064 virtual column is returned.
10065
10066 The {winid} argument can be the window number or the
10067 |window-ID|. If this is zero, then the current window is used.
10068
10069 Returns -1 if the window {winid} doesn't exist or the buffer
10070 line {lnum} or virtual column {col} is invalid.
10071
10072 See also |screenpos()|, |virtcol()| and |col()|.
10073
10074 Can also be used as a |method|: >
10075 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010076
10077visualmode([{expr}]) *visualmode()*
10078 The result is a String, which describes the last Visual mode
10079 used in the current buffer. Initially it returns an empty
10080 string, but once Visual mode has been used, it returns "v",
10081 "V", or "<CTRL-V>" (a single CTRL-V character) for
10082 character-wise, line-wise, or block-wise Visual mode
10083 respectively.
10084 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010085 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010086< This enters the same Visual mode as before. It is also useful
10087 in scripts if you wish to act differently depending on the
10088 Visual mode that was used.
10089 If Visual mode is active, use |mode()| to get the Visual mode
10090 (e.g., in a |:vmap|).
10091 If {expr} is supplied and it evaluates to a non-zero Number or
10092 a non-empty String, then the Visual mode will be cleared and
10093 the old value is returned. See |non-zero-arg|.
10094
10095wildmenumode() *wildmenumode()*
10096 Returns |TRUE| when the wildmenu is active and |FALSE|
10097 otherwise. See 'wildmenu' and 'wildmode'.
10098 This can be used in mappings to handle the 'wildcharm' option
10099 gracefully. (Makes only sense with |mapmode-c| mappings).
10100
10101 For example to make <c-j> work like <down> in wildmode, use: >
10102 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10103<
10104 (Note, this needs the 'wildcharm' option set appropriately).
10105
10106win_execute({id}, {command} [, {silent}]) *win_execute()*
10107 Like `execute()` but in the context of window {id}.
10108 The window will temporarily be made the current window,
10109 without triggering autocommands or changing directory. When
10110 executing {command} autocommands will be triggered, this may
10111 have unexpected side effects. Use |:noautocmd| if needed.
10112 Example: >
10113 call win_execute(winid, 'set syntax=python')
10114< Doing the same with `setwinvar()` would not trigger
10115 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010116 *E994*
10117 Not all commands are allowed in popup windows.
10118 When window {id} does not exist then no error is given and
10119 an empty string is returned.
10120
10121 Can also be used as a |method|, the base is passed as the
10122 second argument: >
10123 GetCommand()->win_execute(winid)
10124
10125win_findbuf({bufnr}) *win_findbuf()*
10126 Returns a |List| with |window-ID|s for windows that contain
10127 buffer {bufnr}. When there is none the list is empty.
10128
10129 Can also be used as a |method|: >
10130 GetBufnr()->win_findbuf()
10131
10132win_getid([{win} [, {tab}]]) *win_getid()*
10133 Get the |window-ID| for the specified window.
10134 When {win} is missing use the current window.
10135 With {win} this is the window number. The top window has
10136 number 1.
10137 Without {tab} use the current tab, otherwise the tab with
10138 number {tab}. The first tab has number one.
10139 Return zero if the window cannot be found.
10140
10141 Can also be used as a |method|: >
10142 GetWinnr()->win_getid()
10143
10144
10145win_gettype([{nr}]) *win_gettype()*
10146 Return the type of the window:
10147 "autocmd" autocommand window. Temporary window
10148 used to execute autocommands.
10149 "command" command-line window |cmdwin|
10150 (empty) normal window
10151 "loclist" |location-list-window|
10152 "popup" popup window |popup|
10153 "preview" preview window |preview-window|
10154 "quickfix" |quickfix-window|
10155 "unknown" window {nr} not found
10156
10157 When {nr} is omitted return the type of the current window.
10158 When {nr} is given return the type of this window by number or
10159 |window-ID|.
10160
10161 Also see the 'buftype' option. When running a terminal in a
10162 popup window then 'buftype' is "terminal" and win_gettype()
10163 returns "popup".
10164
10165 Can also be used as a |method|: >
10166 GetWinid()->win_gettype()
10167<
10168win_gotoid({expr}) *win_gotoid()*
10169 Go to window with ID {expr}. This may also change the current
10170 tabpage.
10171 Return TRUE if successful, FALSE if the window cannot be found.
10172
10173 Can also be used as a |method|: >
10174 GetWinid()->win_gotoid()
10175
10176win_id2tabwin({expr}) *win_id2tabwin()*
10177 Return a list with the tab number and window number of window
10178 with ID {expr}: [tabnr, winnr].
10179 Return [0, 0] if the window cannot be found.
10180
10181 Can also be used as a |method|: >
10182 GetWinid()->win_id2tabwin()
10183
10184win_id2win({expr}) *win_id2win()*
10185 Return the window number of window with ID {expr}.
10186 Return 0 if the window cannot be found in the current tabpage.
10187
10188 Can also be used as a |method|: >
10189 GetWinid()->win_id2win()
10190
Daniel Steinbergee630312022-01-10 13:36:34 +000010191win_move_separator({nr}, {offset}) *win_move_separator()*
10192 Move window {nr}'s vertical separator (i.e., the right border)
10193 by {offset} columns, as if being dragged by the mouse. {nr}
10194 can be a window number or |window-ID|. A positive {offset}
10195 moves right and a negative {offset} moves left. Moving a
10196 window's vertical separator will change the width of the
10197 window and the width of other windows adjacent to the vertical
10198 separator. The magnitude of movement may be smaller than
10199 specified (e.g., as a consequence of maintaining
10200 'winminwidth'). Returns TRUE if the window can be found and
10201 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010202 This will fail for the rightmost window and a full-width
10203 window, since it has no separator on the right.
Daniel Steinbergee630312022-01-10 13:36:34 +000010204
10205 Can also be used as a |method|: >
10206 GetWinnr()->win_move_separator(offset)
10207
10208win_move_statusline({nr}, {offset}) *win_move_statusline()*
10209 Move window {nr}'s status line (i.e., the bottom border) by
10210 {offset} rows, as if being dragged by the mouse. {nr} can be a
10211 window number or |window-ID|. A positive {offset} moves down
10212 and a negative {offset} moves up. Moving a window's status
10213 line will change the height of the window and the height of
10214 other windows adjacent to the status line. The magnitude of
10215 movement may be smaller than specified (e.g., as a consequence
10216 of maintaining 'winminheight'). Returns TRUE if the window can
10217 be found and FALSE otherwise.
10218
10219 Can also be used as a |method|: >
10220 GetWinnr()->win_move_statusline(offset)
10221
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010222win_screenpos({nr}) *win_screenpos()*
10223 Return the screen position of window {nr} as a list with two
10224 numbers: [row, col]. The first window always has position
10225 [1, 1], unless there is a tabline, then it is [2, 1].
10226 {nr} can be the window number or the |window-ID|. Use zero
10227 for the current window.
10228 Returns [0, 0] if the window cannot be found in the current
10229 tabpage.
10230
10231 Can also be used as a |method|: >
10232 GetWinid()->win_screenpos()
10233<
10234win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10235 Move the window {nr} to a new split of the window {target}.
10236 This is similar to moving to {target}, creating a new window
10237 using |:split| but having the same contents as window {nr}, and
10238 then closing {nr}.
10239
10240 Both {nr} and {target} can be window numbers or |window-ID|s.
10241 Both must be in the current tab page.
10242
10243 Returns zero for success, non-zero for failure.
10244
10245 {options} is a |Dictionary| with the following optional entries:
10246 "vertical" When TRUE, the split is created vertically,
10247 like with |:vsplit|.
10248 "rightbelow" When TRUE, the split is made below or to the
10249 right (if vertical). When FALSE, it is done
10250 above or to the left (if vertical). When not
10251 present, the values of 'splitbelow' and
10252 'splitright' are used.
10253
10254 Can also be used as a |method|: >
10255 GetWinid()->win_splitmove(target)
10256<
10257
10258 *winbufnr()*
10259winbufnr({nr}) The result is a Number, which is the number of the buffer
10260 associated with window {nr}. {nr} can be the window number or
10261 the |window-ID|.
10262 When {nr} is zero, the number of the buffer in the current
10263 window is returned.
10264 When window {nr} doesn't exist, -1 is returned.
10265 Example: >
10266 :echo "The file in the current window is " . bufname(winbufnr(0))
10267<
10268 Can also be used as a |method|: >
10269 FindWindow()->winbufnr()->bufname()
10270<
10271 *wincol()*
10272wincol() The result is a Number, which is the virtual column of the
10273 cursor in the window. This is counting screen cells from the
10274 left side of the window. The leftmost column is one.
10275
10276 *windowsversion()*
10277windowsversion()
10278 The result is a String. For MS-Windows it indicates the OS
10279 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10280 Windows XP is "5.1". For non-MS-Windows systems the result is
10281 an empty string.
10282
10283winheight({nr}) *winheight()*
10284 The result is a Number, which is the height of window {nr}.
10285 {nr} can be the window number or the |window-ID|.
10286 When {nr} is zero, the height of the current window is
10287 returned. When window {nr} doesn't exist, -1 is returned.
10288 An existing window always has a height of zero or more.
10289 This excludes any window toolbar line.
10290 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010291 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010292
10293< Can also be used as a |method|: >
10294 GetWinid()->winheight()
10295<
10296winlayout([{tabnr}]) *winlayout()*
10297 The result is a nested List containing the layout of windows
10298 in a tabpage.
10299
10300 Without {tabnr} use the current tabpage, otherwise the tabpage
10301 with number {tabnr}. If the tabpage {tabnr} is not found,
10302 returns an empty list.
10303
10304 For a leaf window, it returns:
10305 ['leaf', {winid}]
10306 For horizontally split windows, which form a column, it
10307 returns:
10308 ['col', [{nested list of windows}]]
10309 For vertically split windows, which form a row, it returns:
10310 ['row', [{nested list of windows}]]
10311
10312 Example: >
10313 " Only one window in the tab page
10314 :echo winlayout()
10315 ['leaf', 1000]
10316 " Two horizontally split windows
10317 :echo winlayout()
10318 ['col', [['leaf', 1000], ['leaf', 1001]]]
10319 " The second tab page, with three horizontally split
10320 " windows, with two vertically split windows in the
10321 " middle window
10322 :echo winlayout(2)
10323 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10324 ['leaf', 1001]]], ['leaf', 1000]]]
10325<
10326 Can also be used as a |method|: >
10327 GetTabnr()->winlayout()
10328<
10329 *winline()*
10330winline() The result is a Number, which is the screen line of the cursor
10331 in the window. This is counting screen lines from the top of
10332 the window. The first line is one.
10333 If the cursor was moved the view on the file will be updated
10334 first, this may cause a scroll.
10335
10336 *winnr()*
10337winnr([{arg}]) The result is a Number, which is the number of the current
10338 window. The top window has number 1.
10339 Returns zero for a popup window.
10340
10341 The optional argument {arg} supports the following values:
10342 $ the number of the last window (the window
10343 count).
10344 # the number of the last accessed window (where
10345 |CTRL-W_p| goes to). If there is no previous
10346 window or it is in another tab page 0 is
10347 returned.
10348 {N}j the number of the Nth window below the
10349 current window (where |CTRL-W_j| goes to).
10350 {N}k the number of the Nth window above the current
10351 window (where |CTRL-W_k| goes to).
10352 {N}h the number of the Nth window left of the
10353 current window (where |CTRL-W_h| goes to).
10354 {N}l the number of the Nth window right of the
10355 current window (where |CTRL-W_l| goes to).
10356 The number can be used with |CTRL-W_w| and ":wincmd w"
10357 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010010358 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010359 Also see |tabpagewinnr()| and |win_getid()|.
10360 Examples: >
10361 let window_count = winnr('$')
10362 let prev_window = winnr('#')
10363 let wnum = winnr('3k')
10364
10365< Can also be used as a |method|: >
10366 GetWinval()->winnr()
10367<
10368 *winrestcmd()*
10369winrestcmd() Returns a sequence of |:resize| commands that should restore
10370 the current window sizes. Only works properly when no windows
10371 are opened or closed and the current window and tab page is
10372 unchanged.
10373 Example: >
10374 :let cmd = winrestcmd()
10375 :call MessWithWindowSizes()
10376 :exe cmd
10377<
10378 *winrestview()*
10379winrestview({dict})
10380 Uses the |Dictionary| returned by |winsaveview()| to restore
10381 the view of the current window.
10382 Note: The {dict} does not have to contain all values, that are
10383 returned by |winsaveview()|. If values are missing, those
10384 settings won't be restored. So you can use: >
10385 :call winrestview({'curswant': 4})
10386<
10387 This will only set the curswant value (the column the cursor
10388 wants to move on vertical movements) of the cursor to column 5
10389 (yes, that is 5), while all other settings will remain the
10390 same. This is useful, if you set the cursor position manually.
10391
10392 If you have changed the values the result is unpredictable.
10393 If the window size changed the result won't be the same.
10394
10395 Can also be used as a |method|: >
10396 GetView()->winrestview()
10397<
10398 *winsaveview()*
10399winsaveview() Returns a |Dictionary| that contains information to restore
10400 the view of the current window. Use |winrestview()| to
10401 restore the view.
10402 This is useful if you have a mapping that jumps around in the
10403 buffer and you want to go back to the original view.
10404 This does not save fold information. Use the 'foldenable'
10405 option to temporarily switch off folding, so that folds are
10406 not opened when moving around. This may have side effects.
10407 The return value includes:
10408 lnum cursor line number
10409 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000010410 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010411 returns)
10412 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000010413 curswant column for vertical movement (Note:
10414 the first column is zero, as opposed
10415 to what |getcurpos()| returns). After
10416 |$| command it will be a very large
10417 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010418 topline first line in the window
10419 topfill filler lines, only in diff mode
10420 leftcol first column displayed; only used when
10421 'wrap' is off
10422 skipcol columns skipped
10423 Note that no option values are saved.
10424
10425
10426winwidth({nr}) *winwidth()*
10427 The result is a Number, which is the width of window {nr}.
10428 {nr} can be the window number or the |window-ID|.
10429 When {nr} is zero, the width of the current window is
10430 returned. When window {nr} doesn't exist, -1 is returned.
10431 An existing window always has a width of zero or more.
10432 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010433 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010434 :if winwidth(0) <= 50
10435 : 50 wincmd |
10436 :endif
10437< For getting the terminal or screen size, see the 'columns'
10438 option.
10439
10440 Can also be used as a |method|: >
10441 GetWinid()->winwidth()
10442
10443
10444wordcount() *wordcount()*
10445 The result is a dictionary of byte/chars/word statistics for
10446 the current buffer. This is the same info as provided by
10447 |g_CTRL-G|
10448 The return value includes:
10449 bytes Number of bytes in the buffer
10450 chars Number of chars in the buffer
10451 words Number of words in the buffer
10452 cursor_bytes Number of bytes before cursor position
10453 (not in Visual mode)
10454 cursor_chars Number of chars before cursor position
10455 (not in Visual mode)
10456 cursor_words Number of words before cursor position
10457 (not in Visual mode)
10458 visual_bytes Number of bytes visually selected
10459 (only in Visual mode)
10460 visual_chars Number of chars visually selected
10461 (only in Visual mode)
10462 visual_words Number of words visually selected
10463 (only in Visual mode)
10464
10465
10466 *writefile()*
10467writefile({object}, {fname} [, {flags}])
10468 When {object} is a |List| write it to file {fname}. Each list
10469 item is separated with a NL. Each list item must be a String
10470 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010471 All NL characters are replaced with a NUL character.
10472 Inserting CR characters needs to be done before passing {list}
10473 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010010474
10475 When {object} is a |Blob| write the bytes to file {fname}
10476 unmodified, also when binary mode is not specified.
10477
10478 {flags} must be a String. These characters are recognized:
10479
10480 'b' Binary mode is used: There will not be a NL after the
10481 last list item. An empty item at the end does cause the
10482 last line in the file to end in a NL.
10483
10484 'a' Append mode is used, lines are appended to the file: >
10485 :call writefile(["foo"], "event.log", "a")
10486 :call writefile(["bar"], "event.log", "a")
10487<
10488 'D' Delete the file when the current function ends. This
10489 works like: >
10490 :defer delete({fname})
10491< Fails when not in a function. Also see |:defer|.
10492
10493 's' fsync() is called after writing the file. This flushes
10494 the file to disk, if possible. This takes more time but
10495 avoids losing the file if the system crashes.
10496
10497 'S' fsync() is not called, even when 'fsync' is set.
10498
10499 When {flags} does not contain "S" or "s" then fsync() is
10500 called if the 'fsync' option is set.
10501
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010502 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010503
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010504 When the write fails -1 is returned, otherwise 0. There is an
10505 error message if the file can't be created or when writing
10506 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010507
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010508 Also see |readfile()|.
10509 To copy a file byte for byte: >
10510 :let fl = readfile("foo", "b")
10511 :call writefile(fl, "foocopy", "b")
10512
10513< Can also be used as a |method|: >
10514 GetText()->writefile("thefile")
10515
10516
10517xor({expr}, {expr}) *xor()*
10518 Bitwise XOR on the two arguments. The arguments are converted
10519 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010520 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010521 Example: >
10522 :let bits = xor(bits, 0x80)
10523<
10524 Can also be used as a |method|: >
10525 :let bits = bits->xor(0x80)
10526<
10527
10528==============================================================================
105293. Feature list *feature-list*
10530
10531There are three types of features:
105321. Features that are only supported when they have been enabled when Vim
10533 was compiled |+feature-list|. Example: >
10534 :if has("cindent")
10535< *gui_running*
105362. Features that are only supported when certain conditions have been met.
10537 Example: >
10538 :if has("gui_running")
10539< *has-patch*
105403. Beyond a certain version or at a certain version and including a specific
10541 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10542 later, or it is version 7.4 and patch 248 was included. Example: >
10543 :if has("patch-7.4.248")
10544< Note that it's possible for patch 248 to be omitted even though 249 is
10545 included. Only happens when cherry-picking patches.
10546 Note that this form only works for patch 7.4.237 and later, before that
10547 you need to check for the patch and the v:version. Example (checking
10548 version 6.2.148 or later): >
10549 :if v:version > 602 || (v:version == 602 && has("patch148"))
10550
10551Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10552use: `if exists('+shellslash')`
10553
10554
10555acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010556all_builtin_terms Compiled with all builtin terminals enabled. (always
10557 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010558amiga Amiga version of Vim.
10559arabic Compiled with Arabic support |Arabic|.
10560arp Compiled with ARP support (Amiga).
10561autocmd Compiled with autocommand support. (always true)
10562autochdir Compiled with support for 'autochdir'
10563autoservername Automatically enable |clientserver|
10564balloon_eval Compiled with |balloon-eval| support.
10565balloon_multiline GUI supports multiline balloons.
10566beos BeOS version of Vim.
10567browse Compiled with |:browse| support, and browse() will
10568 work.
10569browsefilter Compiled with support for |browsefilter|.
10570bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010571builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010572byte_offset Compiled with support for 'o' in 'statusline'
10573channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010574cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010575clientserver Compiled with remote invocation support |clientserver|.
10576clipboard Compiled with 'clipboard' support.
10577clipboard_working Compiled with 'clipboard' support and it can be used.
10578cmdline_compl Compiled with |cmdline-completion| support.
10579cmdline_hist Compiled with |cmdline-history| support.
10580cmdline_info Compiled with 'showcmd' and 'ruler' support.
10581comments Compiled with |'comments'| support.
10582compatible Compiled to be very Vi compatible.
10583conpty Platform where |ConPTY| can be used.
10584cryptv Compiled with encryption support |encryption|.
10585cscope Compiled with |cscope| support.
10586cursorbind Compiled with |'cursorbind'| (always true)
10587debug Compiled with "DEBUG" defined.
10588dialog_con Compiled with console dialog support.
10589dialog_gui Compiled with GUI dialog support.
10590diff Compiled with |vimdiff| and 'diff' support.
10591digraphs Compiled with support for digraphs.
10592directx Compiled with support for DirectX and 'renderoptions'.
10593dnd Compiled with support for the "~ register |quote_~|.
10594drop_file Compiled with |drop_file| support.
10595ebcdic Compiled on a machine with ebcdic character set.
10596emacs_tags Compiled with support for Emacs tags.
10597eval Compiled with expression evaluation support. Always
10598 true, of course!
10599ex_extra |+ex_extra| (always true)
10600extra_search Compiled with support for |'incsearch'| and
10601 |'hlsearch'|
10602farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010010603file_in_path Compiled with support for |gf| and |<cfile>| (always
10604 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010605filterpipe When 'shelltemp' is off pipes are used for shell
10606 read/write/filter commands
10607find_in_path Compiled with support for include file searches
10608 |+find_in_path|.
10609float Compiled with support for |Float|.
10610fname_case Case in file names matters (for Amiga and MS-Windows
10611 this is not present).
10612folding Compiled with |folding| support.
10613footer Compiled with GUI footer support. |gui-footer|
10614fork Compiled to use fork()/exec() instead of system().
10615gettext Compiled with message translation |multi-lang|
10616gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010010617gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010618gui_gnome Compiled with Gnome support (gui_gtk is also defined).
10619gui_gtk Compiled with GTK+ GUI (any version).
10620gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
10621gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
10622gui_haiku Compiled with Haiku GUI.
10623gui_mac Compiled with Macintosh GUI.
10624gui_motif Compiled with Motif GUI.
10625gui_photon Compiled with Photon GUI.
10626gui_running Vim is running in the GUI, or it will start soon.
10627gui_win32 Compiled with MS-Windows Win32 GUI.
10628gui_win32s idem, and Win32s system being used (Windows 3.1)
10629haiku Haiku version of Vim.
10630hangul_input Compiled with Hangul input support. |hangul|
10631hpux HP-UX version of Vim.
10632iconv Can use iconv() for conversion.
10633insert_expand Compiled with support for CTRL-X expansion commands in
10634 Insert mode. (always true)
10635job Compiled with support for |channel| and |job|
10636ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010637jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010638keymap Compiled with 'keymap' support.
10639lambda Compiled with |lambda| support.
10640langmap Compiled with 'langmap' support.
10641libcall Compiled with |libcall()| support.
10642linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10643 'breakindent' support.
10644linux Linux version of Vim.
10645lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010646 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010647listcmds Compiled with commands for the buffer list |:files|
10648 and the argument list |arglist|.
10649localmap Compiled with local mappings and abbr. |:map-local|
10650lua Compiled with Lua interface |Lua|.
10651mac Any Macintosh version of Vim cf. osx
10652macunix Synonym for osxdarwin
10653menu Compiled with support for |:menu|.
10654mksession Compiled with support for |:mksession|.
10655modify_fname Compiled with file name modifiers. |filename-modifiers|
10656 (always true)
10657mouse Compiled with support for mouse.
10658mouse_dec Compiled with support for Dec terminal mouse.
10659mouse_gpm Compiled with support for gpm (Linux console mouse)
10660mouse_gpm_enabled GPM mouse is working
10661mouse_netterm Compiled with support for netterm mouse.
10662mouse_pterm Compiled with support for qnx pterm mouse.
10663mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
10664mouse_sgr Compiled with support for sgr mouse.
10665mouse_urxvt Compiled with support for urxvt mouse.
10666mouse_xterm Compiled with support for xterm mouse.
10667mouseshape Compiled with support for 'mouseshape'.
10668multi_byte Compiled with support for 'encoding' (always true)
10669multi_byte_encoding 'encoding' is set to a multibyte encoding.
10670multi_byte_ime Compiled with support for IME input method.
10671multi_lang Compiled with support for multiple languages.
10672mzscheme Compiled with MzScheme interface |mzscheme|.
10673nanotime Compiled with sub-second time stamp checks.
10674netbeans_enabled Compiled with support for |netbeans| and connected.
10675netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010676num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010677ole Compiled with OLE automation support for Win32.
10678osx Compiled for macOS cf. mac
10679osxdarwin Compiled for macOS, with |mac-darwin-feature|
10680packages Compiled with |packages| support.
10681path_extra Compiled with up/downwards search in 'path' and 'tags'
10682perl Compiled with Perl interface.
10683persistent_undo Compiled with support for persistent undo history.
10684postscript Compiled with PostScript file printing.
10685printer Compiled with |:hardcopy| support.
10686profile Compiled with |:profile| support.
10687python Python 2.x interface available. |has-python|
10688python_compiled Compiled with Python 2.x interface. |has-python|
10689python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10690python3 Python 3.x interface available. |has-python|
10691python3_compiled Compiled with Python 3.x interface. |has-python|
10692python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10693pythonx Python 2.x and/or 3.x interface available. |python_x|
10694qnx QNX version of Vim.
10695quickfix Compiled with |quickfix| support.
10696reltime Compiled with |reltime()| support.
10697rightleft Compiled with 'rightleft' support.
10698ruby Compiled with Ruby interface |ruby|.
10699scrollbind Compiled with 'scrollbind' support. (always true)
10700showcmd Compiled with 'showcmd' support.
10701signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010702smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010703sodium Compiled with libsodium for better crypt support
10704sound Compiled with sound support, e.g. `sound_playevent()`
10705spell Compiled with spell checking support |spell|.
10706startuptime Compiled with |--startuptime| support.
10707statusline Compiled with support for 'statusline', 'rulerformat'
10708 and special formats of 'titlestring' and 'iconstring'.
10709sun SunOS version of Vim.
10710sun_workshop Support for Sun |workshop| has been removed.
10711syntax Compiled with syntax highlighting support |syntax|.
10712syntax_items There are active syntax highlighting items for the
10713 current buffer.
10714system Compiled to use system() instead of fork()/exec().
10715tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010716 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010717tag_old_static Support for old static tags was removed, see
10718 |tag-old-static|.
10719tcl Compiled with Tcl interface.
10720termguicolors Compiled with true color in terminal support.
10721terminal Compiled with |terminal| support.
10722terminfo Compiled with terminfo instead of termcap.
10723termresponse Compiled with support for |t_RV| and |v:termresponse|.
10724textobjects Compiled with support for |text-objects|.
10725textprop Compiled with support for |text-properties|.
10726tgetent Compiled with tgetent support, able to use a termcap
10727 or terminfo file.
10728timers Compiled with |timer_start()| support.
10729title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010730 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010731toolbar Compiled with support for |gui-toolbar|.
10732ttyin input is a terminal (tty)
10733ttyout output is a terminal (tty)
10734unix Unix version of Vim. *+unix*
10735unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10736user_commands User-defined commands. (always true)
10737vartabs Compiled with variable tabstop support |'vartabstop'|.
10738vcon Win32: Virtual console support is working, can use
10739 'termguicolors'. Also see |+vtp|.
10740vertsplit Compiled with vertically split windows |:vsplit|.
10741 (always true)
10742vim_starting True while initial source'ing takes place. |startup|
10743 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000010744vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010745viminfo Compiled with viminfo support.
10746vimscript-1 Compiled Vim script version 1 support
10747vimscript-2 Compiled Vim script version 2 support
10748vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010010749vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010750virtualedit Compiled with 'virtualedit' option. (always true)
10751visual Compiled with Visual mode. (always true)
10752visualextra Compiled with extra Visual mode commands. (always
10753 true) |blockwise-operators|.
10754vms VMS version of Vim.
10755vreplace Compiled with |gR| and |gr| commands. (always true)
10756vtp Compiled for vcon support |+vtp| (check vcon to find
10757 out if it works in the current console).
10758wildignore Compiled with 'wildignore' option.
10759wildmenu Compiled with 'wildmenu' option.
10760win16 old version for MS-Windows 3.1 (always false)
10761win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10762 64 bits)
10763win32unix Win32 version of Vim, using Unix files (Cygwin)
10764win64 Win64 version of Vim (MS-Windows 64 bit).
10765win95 Win32 version for MS-Windows 95/98/ME (always false)
10766winaltkeys Compiled with 'winaltkeys' option.
10767windows Compiled with support for more than one window.
10768 (always true)
10769writebackup Compiled with 'writebackup' default on.
10770xfontset Compiled with X fontset support |xfontset|.
10771xim Compiled with X input method support |xim|.
10772xpm Compiled with pixmap support.
10773xpm_w32 Compiled with pixmap support for Win32. (Only for
10774 backward compatibility. Use "xpm" instead.)
10775xsmp Compiled with X session management support.
10776xsmp_interact Compiled with interactive X session management support.
10777xterm_clipboard Compiled with support for xterm clipboard.
10778xterm_save Compiled with support for saving and restoring the
10779 xterm screen.
10780x11 Compiled with X11 support.
10781
10782
10783==============================================================================
107844. Matching a pattern in a String *string-match*
10785
10786This is common between several functions. A regexp pattern as explained at
10787|pattern| is normally used to find a match in the buffer lines. When a
10788pattern is used to find a match in a String, almost everything works in the
10789same way. The difference is that a String is handled like it is one line.
10790When it contains a "\n" character, this is not seen as a line break for the
10791pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10792>
10793 :let a = "aaaa\nxxxx"
10794 :echo matchstr(a, "..\n..")
10795 aa
10796 xx
10797 :echo matchstr(a, "a.x")
10798 a
10799 x
10800
10801Don't forget that "^" will only match at the first character of the String and
10802"$" at the last character of the string. They don't match after or before a
10803"\n".
10804
10805 vim:tw=78:ts=8:noet:ft=help:norl: