blob: 12d62a6760a32db139929800da75011d64b3c148 [file] [log] [blame]
Bram Moolenaareb490412022-06-28 13:44:46 +01001*builtin.txt* For Vim version 9.0. Last change: 2022 Jun 27
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}
474repeat({expr}, {count}) String repeat {expr} {count} times
475resolve({filename}) String get filename a shortcut points to
476reverse({list}) List reverse {list} in-place
477round({expr}) Float round off {expr}
478rubyeval({expr}) any evaluate |Ruby| expression
479screenattr({row}, {col}) Number attribute at screen position
480screenchar({row}, {col}) Number character at screen position
481screenchars({row}, {col}) List List of characters at screen position
482screencol() Number current cursor column
483screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
484screenrow() Number current cursor row
485screenstring({row}, {col}) String characters at screen position
486search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
487 Number search for {pattern}
488searchcount([{options}]) Dict get or update search stats
489searchdecl({name} [, {global} [, {thisblock}]])
490 Number search for variable declaration
491searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
492 Number search for other end of start/end pair
493searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
494 List search for other end of start/end pair
495searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
496 List search for {pattern}
497server2client({clientid}, {string})
498 Number send reply string
499serverlist() String get a list of available servers
500setbufline({expr}, {lnum}, {text})
501 Number set line {lnum} to {text} in buffer
502 {expr}
503setbufvar({buf}, {varname}, {val})
504 none set {varname} in buffer {buf} to {val}
505setcellwidths({list}) none set character cell width overrides
506setcharpos({expr}, {list}) Number set the {expr} position to {list}
507setcharsearch({dict}) Dict set character search from {dict}
Shougo Matsushita07ea5f12022-08-27 12:22:25 +0100508setcmdline({str} [, {pos}]) Number set command-line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000509setcmdpos({pos}) Number set cursor position in command-line
510setcursorcharpos({list}) Number move cursor to position in {list}
511setenv({name}, {val}) none set environment variable
512setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
513setline({lnum}, {line}) Number set line {lnum} to {line}
514setloclist({nr}, {list} [, {action}])
515 Number modify location list using {list}
516setloclist({nr}, {list}, {action}, {what})
517 Number modify specific location list props
518setmatches({list} [, {win}]) Number restore a list of matches
519setpos({expr}, {list}) Number set the {expr} position to {list}
520setqflist({list} [, {action}]) Number modify quickfix list using {list}
521setqflist({list}, {action}, {what})
522 Number modify specific quickfix list props
523setreg({n}, {v} [, {opt}]) Number set register to value and type
524settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
525settabwinvar({tabnr}, {winnr}, {varname}, {val})
526 none set {varname} in window {winnr} in tab
527 page {tabnr} to {val}
528settagstack({nr}, {dict} [, {action}])
529 Number modify tag stack using {dict}
530setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
531sha256({string}) String SHA256 checksum of {string}
532shellescape({string} [, {special}])
533 String escape {string} for use as shell
534 command argument
535shiftwidth([{col}]) Number effective value of 'shiftwidth'
536sign_define({name} [, {dict}]) Number define or update a sign
537sign_define({list}) List define or update a list of signs
538sign_getdefined([{name}]) List get a list of defined signs
539sign_getplaced([{buf} [, {dict}]])
540 List get a list of placed signs
541sign_jump({id}, {group}, {buf})
542 Number jump to a sign
543sign_place({id}, {group}, {name}, {buf} [, {dict}])
544 Number place a sign
545sign_placelist({list}) List place a list of signs
546sign_undefine([{name}]) Number undefine a sign
547sign_undefine({list}) List undefine a list of signs
548sign_unplace({group} [, {dict}])
549 Number unplace a sign
550sign_unplacelist({list}) List unplace a list of signs
551simplify({filename}) String simplify filename as much as possible
552sin({expr}) Float sine of {expr}
553sinh({expr}) Float hyperbolic sine of {expr}
554slice({expr}, {start} [, {end}]) String, List or Blob
555 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000556sort({list} [, {how} [, {dict}]])
557 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000558sound_clear() none stop playing all sounds
559sound_playevent({name} [, {callback}])
560 Number play an event sound
561sound_playfile({path} [, {callback}])
562 Number play sound file {path}
563sound_stop({id}) none stop playing sound {id}
564soundfold({word}) String sound-fold {word}
565spellbadword() String badly spelled word at cursor
566spellsuggest({word} [, {max} [, {capital}]])
567 List spelling suggestions
568split({expr} [, {pat} [, {keepempty}]])
569 List make |List| from {pat} separated {expr}
570sqrt({expr}) Float square root of {expr}
571srand([{expr}]) List get seed for |rand()|
572state([{what}]) String current state of Vim
573str2float({expr} [, {quoted}]) Float convert String to Float
574str2list({expr} [, {utf8}]) List convert each character of {expr} to
575 ASCII/UTF-8 value
576str2nr({expr} [, {base} [, {quoted}]])
577 Number convert String to Number
578strcharlen({expr}) Number character length of the String {expr}
579strcharpart({str}, {start} [, {len} [, {skipcc}]])
580 String {len} characters of {str} at
581 character {start}
582strchars({expr} [, {skipcc}]) Number character count of the String {expr}
583strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
584strftime({format} [, {time}]) String format time with a specified format
585strgetchar({str}, {index}) Number get char {index} from {str}
586stridx({haystack}, {needle} [, {start}])
587 Number index of {needle} in {haystack}
588string({expr}) String String representation of {expr} value
589strlen({expr}) Number length of the String {expr}
590strpart({str}, {start} [, {len} [, {chars}]])
591 String {len} bytes/chars of {str} at
592 byte {start}
593strptime({format}, {timestring})
594 Number Convert {timestring} to unix timestamp
595strridx({haystack}, {needle} [, {start}])
596 Number last index of {needle} in {haystack}
597strtrans({expr}) String translate string to make it printable
598strwidth({expr}) Number display cell length of the String {expr}
599submatch({nr} [, {list}]) String or List
600 specific match in ":s" or substitute()
601substitute({expr}, {pat}, {sub}, {flags})
602 String all {pat} in {expr} replaced with {sub}
603swapinfo({fname}) Dict information about swap file {fname}
604swapname({buf}) String swap file of buffer {buf}
605synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
606synIDattr({synID}, {what} [, {mode}])
607 String attribute {what} of syntax ID {synID}
608synIDtrans({synID}) Number translated syntax ID of {synID}
609synconcealed({lnum}, {col}) List info about concealing
610synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
611system({expr} [, {input}]) String output of shell command/filter {expr}
612systemlist({expr} [, {input}]) List output of shell command/filter {expr}
613tabpagebuflist([{arg}]) List list of buffer numbers in tab page
614tabpagenr([{arg}]) Number number of current or last tab page
615tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
616tagfiles() List tags files used
617taglist({expr} [, {filename}]) List list of tags matching {expr}
618tan({expr}) Float tangent of {expr}
619tanh({expr}) Float hyperbolic tangent of {expr}
620tempname() String name for a temporary file
621term_dumpdiff({filename}, {filename} [, {options}])
622 Number display difference between two dumps
623term_dumpload({filename} [, {options}])
624 Number displaying a screen dump
625term_dumpwrite({buf}, {filename} [, {options}])
626 none dump terminal window contents
627term_getaltscreen({buf}) Number get the alternate screen flag
628term_getansicolors({buf}) List get ANSI palette in GUI color mode
629term_getattr({attr}, {what}) Number get the value of attribute {what}
630term_getcursor({buf}) List get the cursor position of a terminal
631term_getjob({buf}) Job get the job associated with a terminal
632term_getline({buf}, {row}) String get a line of text from a terminal
633term_getscrolled({buf}) Number get the scroll count of a terminal
634term_getsize({buf}) List get the size of a terminal
635term_getstatus({buf}) String get the status of a terminal
636term_gettitle({buf}) String get the title of a terminal
637term_gettty({buf}, [{input}]) String get the tty name of a terminal
638term_list() List get the list of terminal buffers
639term_scrape({buf}, {row}) List get row of a terminal screen
640term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
641term_setansicolors({buf}, {colors})
642 none set ANSI palette in GUI color mode
643term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
644term_setkill({buf}, {how}) none set signal to stop job in terminal
645term_setrestore({buf}, {command}) none set command to restore terminal
646term_setsize({buf}, {rows}, {cols})
647 none set the size of a terminal
648term_start({cmd} [, {options}]) Number open a terminal window and run a job
649term_wait({buf} [, {time}]) Number wait for screen to be updated
650terminalprops() Dict properties of the terminal
651test_alloc_fail({id}, {countdown}, {repeat})
652 none make memory allocation fail
653test_autochdir() none enable 'autochdir' during startup
654test_feedinput({string}) none add key sequence to input buffer
655test_garbagecollect_now() none free memory right now for testing
656test_garbagecollect_soon() none free memory soon for testing
657test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000658test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000659test_ignore_error({expr}) none ignore a specific error
660test_null_blob() Blob null value for testing
661test_null_channel() Channel null value for testing
662test_null_dict() Dict null value for testing
663test_null_function() Funcref null value for testing
664test_null_job() Job null value for testing
665test_null_list() List null value for testing
666test_null_partial() Funcref null value for testing
667test_null_string() String null value for testing
668test_option_not_set({name}) none reset flag indicating option was set
669test_override({expr}, {val}) none test with Vim internal overrides
670test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000671test_setmouse({row}, {col}) none set the mouse position for testing
672test_settime({expr}) none set current time for testing
673test_srand_seed([seed]) none set seed for testing srand()
674test_unknown() any unknown value for testing
675test_void() any void value for testing
676timer_info([{id}]) List information about timers
677timer_pause({id}, {pause}) none pause or unpause a timer
678timer_start({time}, {callback} [, {options}])
679 Number create a timer
680timer_stop({timer}) none stop a timer
681timer_stopall() none stop all timers
682tolower({expr}) String the String {expr} switched to lowercase
683toupper({expr}) String the String {expr} switched to uppercase
684tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
685 to chars in {tostr}
686trim({text} [, {mask} [, {dir}]])
687 String trim characters in {mask} from {text}
688trunc({expr}) Float truncate Float {expr}
689type({expr}) Number type of value {expr}
690typename({expr}) String representation of the type of {expr}
691undofile({name}) String undo file name for {name}
692undotree() List undo file tree
693uniq({list} [, {func} [, {dict}]])
694 List remove adjacent duplicates from a list
695values({dict}) List values in {dict}
LemonBoy0f7a3e12022-05-26 12:10:37 +0100696virtcol({expr} [, {list}]) Number or List
697 screen column of cursor or mark
Bram Moolenaar5a6ec102022-05-27 21:58:00 +0100698virtcol2col({winid}, {lnum}, {col})
699 Number byte index of a character on screen
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000700visualmode([expr]) String last visual mode used
701wildmenumode() Number whether 'wildmenu' mode is active
702win_execute({id}, {command} [, {silent}])
703 String execute {command} in window {id}
704win_findbuf({bufnr}) List find windows containing {bufnr}
705win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
706win_gettype([{nr}]) String type of window {nr}
707win_gotoid({expr}) Number go to window with ID {expr}
708win_id2tabwin({expr}) List get tab and window nr from window ID
709win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000710win_move_separator({nr}) Number move window vertical separator
711win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000712win_screenpos({nr}) List get screen position of window {nr}
713win_splitmove({nr}, {target} [, {options}])
714 Number move window {nr} to split of {target}
715winbufnr({nr}) Number buffer number of window {nr}
716wincol() Number window column of the cursor
717windowsversion() String MS-Windows OS version
718winheight({nr}) Number height of window {nr}
719winlayout([{tabnr}]) List layout of windows in tab {tabnr}
720winline() Number window line of the cursor
721winnr([{expr}]) Number number of current window
722winrestcmd() String returns command to restore window sizes
723winrestview({dict}) none restore view of current window
724winsaveview() Dict save view of current window
725winwidth({nr}) Number width of window {nr}
726wordcount() Dict get byte/char/word statistics
727writefile({object}, {fname} [, {flags}])
728 Number write |Blob| or |List| of lines to file
729xor({expr}, {expr}) Number bitwise XOR
730
731==============================================================================
7322. Details *builtin-function-details*
733
734Not all functions are here, some have been moved to a help file covering the
735specific functionality.
736
737abs({expr}) *abs()*
738 Return the absolute value of {expr}. When {expr} evaluates to
739 a |Float| abs() returns a |Float|. When {expr} can be
740 converted to a |Number| abs() returns a |Number|. Otherwise
741 abs() gives an error message and returns -1.
742 Examples: >
743 echo abs(1.456)
744< 1.456 >
745 echo abs(-5.456)
746< 5.456 >
747 echo abs(-4)
748< 4
749
750 Can also be used as a |method|: >
751 Compute()->abs()
752
753< {only available when compiled with the |+float| feature}
754
755
756acos({expr}) *acos()*
757 Return the arc cosine of {expr} measured in radians, as a
758 |Float| in the range of [0, pi].
759 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaar016188f2022-06-06 20:52:59 +0100760 [-1, 1]. Otherwise acos() returns "nan".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000761 Examples: >
762 :echo acos(0)
763< 1.570796 >
764 :echo acos(-0.5)
765< 2.094395
766
767 Can also be used as a |method|: >
768 Compute()->acos()
769
770< {only available when compiled with the |+float| feature}
771
772
773add({object}, {expr}) *add()*
774 Append the item {expr} to |List| or |Blob| {object}. Returns
775 the resulting |List| or |Blob|. Examples: >
776 :let alist = add([1, 2, 3], item)
777 :call add(mylist, "woodstock")
778< Note that when {expr} is a |List| it is appended as a single
779 item. Use |extend()| to concatenate |Lists|.
780 When {object} is a |Blob| then {expr} must be a number.
781 Use |insert()| to add an item at another position.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100782 Returns 1 if {object} is not a |List| or a |Blob|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000783
784 Can also be used as a |method|: >
785 mylist->add(val1)->add(val2)
786
787
788and({expr}, {expr}) *and()*
789 Bitwise AND on the two arguments. The arguments are converted
790 to a number. A List, Dict or Float argument causes an error.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100791 Also see `or()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000792 Example: >
793 :let flag = and(bits, 0x80)
794< Can also be used as a |method|: >
795 :let flag = bits->and(0x80)
796
797
798append({lnum}, {text}) *append()*
799 When {text} is a |List|: Append each item of the |List| as a
800 text line below line {lnum} in the current buffer.
801 Otherwise append {text} as one text line below line {lnum} in
802 the current buffer.
803 Any type of item is accepted and converted to a String.
804 {lnum} can be zero to insert a line before the first one.
805 {lnum} is used like with |getline()|.
806 Returns 1 for failure ({lnum} out of range or out of memory),
807 0 for success. In |Vim9| script an invalid argument or
808 negative number results in an error. Example: >
809 :let failed = append(line('$'), "# THE END")
810 :let failed = append(0, ["Chapter 1", "the beginning"])
811
812< Can also be used as a |method| after a List, the base is
813 passed as the second argument: >
814 mylist->append(lnum)
815
816
817appendbufline({buf}, {lnum}, {text}) *appendbufline()*
818 Like |append()| but append the text in buffer {buf}.
819
820 This function works only for loaded buffers. First call
821 |bufload()| if needed.
822
823 For the use of {buf}, see |bufname()|.
824
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000825 {lnum} is the line number to append below. Note that using
826 |line()| would use the current buffer, not the one appending
827 to. Use "$" to append at the end of the buffer. Other string
828 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000829
830 On success 0 is returned, on failure 1 is returned.
831 In |Vim9| script an error is given for an invalid {lnum}.
832
833 If {buf} is not a valid buffer or {lnum} is not valid, an
834 error message is given. Example: >
835 :let failed = appendbufline(13, 0, "# THE START")
836<
837 Can also be used as a |method| after a List, the base is
838 passed as the second argument: >
839 mylist->appendbufline(buf, lnum)
840
841
842argc([{winid}]) *argc()*
843 The result is the number of files in the argument list. See
844 |arglist|.
845 If {winid} is not supplied, the argument list of the current
846 window is used.
847 If {winid} is -1, the global argument list is used.
848 Otherwise {winid} specifies the window of which the argument
849 list is used: either the window number or the window ID.
850 Returns -1 if the {winid} argument is invalid.
851
852 *argidx()*
853argidx() The result is the current index in the argument list. 0 is
854 the first file. argc() - 1 is the last one. See |arglist|.
855
856 *arglistid()*
857arglistid([{winnr} [, {tabnr}]])
858 Return the argument list ID. This is a number which
859 identifies the argument list being used. Zero is used for the
860 global argument list. See |arglist|.
861 Returns -1 if the arguments are invalid.
862
863 Without arguments use the current window.
864 With {winnr} only use this window in the current tab page.
865 With {winnr} and {tabnr} use the window in the specified tab
866 page.
867 {winnr} can be the window number or the |window-ID|.
868
869 *argv()*
870argv([{nr} [, {winid}]])
871 The result is the {nr}th file in the argument list. See
872 |arglist|. "argv(0)" is the first one. Example: >
873 :let i = 0
874 :while i < argc()
875 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000876 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000877 : let i = i + 1
878 :endwhile
879< Without the {nr} argument, or when {nr} is -1, a |List| with
880 the whole |arglist| is returned.
881
882 The {winid} argument specifies the window ID, see |argc()|.
883 For the Vim command line arguments see |v:argv|.
884
Bram Moolenaar016188f2022-06-06 20:52:59 +0100885 Returns an empty string if {nr}th argument is not present in
886 the argument list. Returns an empty List if the {winid}
887 argument is invalid.
888
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000889asin({expr}) *asin()*
890 Return the arc sine of {expr} measured in radians, as a |Float|
891 in the range of [-pi/2, pi/2].
892 {expr} must evaluate to a |Float| or a |Number| in the range
893 [-1, 1].
Bram Moolenaar016188f2022-06-06 20:52:59 +0100894 Returns "nan" if {expr} is outside the range [-1, 1]. Returns
895 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000896 Examples: >
897 :echo asin(0.8)
898< 0.927295 >
899 :echo asin(-0.5)
900< -0.523599
901
902 Can also be used as a |method|: >
903 Compute()->asin()
904<
905 {only available when compiled with the |+float| feature}
906
907
908assert_ functions are documented here: |assert-functions-details|
909
910
911
912atan({expr}) *atan()*
913 Return the principal value of the arc tangent of {expr}, in
914 the range [-pi/2, +pi/2] radians, as a |Float|.
915 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100916 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000917 Examples: >
918 :echo atan(100)
919< 1.560797 >
920 :echo atan(-4.01)
921< -1.326405
922
923 Can also be used as a |method|: >
924 Compute()->atan()
925<
926 {only available when compiled with the |+float| feature}
927
928
929atan2({expr1}, {expr2}) *atan2()*
930 Return the arc tangent of {expr1} / {expr2}, measured in
931 radians, as a |Float| in the range [-pi, pi].
932 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +0100933 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
934 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000935 Examples: >
936 :echo atan2(-1, 1)
937< -0.785398 >
938 :echo atan2(1, -1)
939< 2.356194
940
941 Can also be used as a |method|: >
942 Compute()->atan2(1)
943<
944 {only available when compiled with the |+float| feature}
945
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100946
947autocmd_add({acmds}) *autocmd_add()*
948 Adds a List of autocmds and autocmd groups.
949
950 The {acmds} argument is a List where each item is a Dict with
951 the following optional items:
952 bufnr buffer number to add a buffer-local autocmd.
953 If this item is specified, then the "pattern"
954 item is ignored.
955 cmd Ex command to execute for this autocmd event
956 event autocmd event name. Refer to |autocmd-events|.
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100957 This can be either a String with a single
958 event name or a List of event names.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100959 group autocmd group name. Refer to |autocmd-groups|.
960 If this group doesn't exist then it is
961 created. If not specified or empty, then the
962 default group is used.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100963 nested boolean flag, set to v:true to add a nested
964 autocmd. Refer to |autocmd-nested|.
LemonBoy0f7a3e12022-05-26 12:10:37 +0100965 once boolean flag, set to v:true to add an autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100966 which executes only once. Refer to
967 |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100968 pattern autocmd pattern string. Refer to
969 |autocmd-patterns|. If "bufnr" item is
Yegappan Lakshmanane0ff3a72022-05-27 18:05:33 +0100970 present, then this item is ignored. This can
971 be a String with a single pattern or a List of
972 patterns.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100973 replace boolean flag, set to v:true to remove all the
974 commands associated with the specified autocmd
975 event and group and add the {cmd}. This is
976 useful to avoid adding the same command
LemonBoy0f7a3e12022-05-26 12:10:37 +0100977 multiple times for an autocmd event in a group.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100978
979 Returns v:true on success and v:false on failure.
980 Examples: >
981 " Create a buffer-local autocmd for buffer 5
982 let acmd = {}
983 let acmd.group = 'MyGroup'
984 let acmd.event = 'BufEnter'
985 let acmd.bufnr = 5
986 let acmd.cmd = 'call BufEnterFunc()'
987 call autocmd_add([acmd])
988
989 Can also be used as a |method|: >
990 GetAutocmdList()->autocmd_add()
991<
992autocmd_delete({acmds}) *autocmd_delete()*
993 Deletes a List of autocmds and autocmd groups.
994
995 The {acmds} argument is a List where each item is a Dict with
996 the following optional items:
997 bufnr buffer number to delete a buffer-local autocmd.
998 If this item is specified, then the "pattern"
999 item is ignored.
1000 cmd Ex command for this autocmd event
1001 event autocmd event name. Refer to |autocmd-events|.
1002 If '*' then all the autocmd events in this
1003 group are deleted.
1004 group autocmd group name. Refer to |autocmd-groups|.
1005 If not specified or empty, then the default
1006 group is used.
1007 nested set to v:true for a nested autocmd.
1008 Refer to |autocmd-nested|.
1009 once set to v:true for an autocmd which executes
1010 only once. Refer to |autocmd-once|.
1011 pattern autocmd pattern string. Refer to
1012 |autocmd-patterns|. If "bufnr" item is
1013 present, then this item is ignored.
1014
1015 If only {group} is specified in a {acmds} entry and {event},
1016 {pattern} and {cmd} are not specified, then that autocmd group
1017 is deleted.
1018
Bram Moolenaar016188f2022-06-06 20:52:59 +01001019 Returns |v:true| on success and |v:false| on failure.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001020 Examples: >
1021 " :autocmd! BufLeave *.vim
1022 let acmd = #{event: 'BufLeave', pattern: '*.vim'}
1023 call autocmd_delete([acmd]})
1024 " :autocmd! MyGroup1 BufLeave
1025 let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
1026 call autocmd_delete([acmd])
1027 " :autocmd! MyGroup2 BufEnter *.c
1028 let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1029 \ pattern: '*.c'}
1030 " :autocmd! MyGroup2 * *.c
1031 let acmd = #{group: 'MyGroup2', event: '*',
1032 \ pattern: '*.c'}
1033 call autocmd_delete([acmd])
1034 " :autocmd! MyGroup3
1035 let acmd = #{group: 'MyGroup3'}
1036 call autocmd_delete([acmd])
1037<
1038 Can also be used as a |method|: >
1039 GetAutocmdList()->autocmd_delete()
1040
1041autocmd_get([{opts}]) *autocmd_get()*
1042 Returns a |List| of autocmds. If {opts} is not supplied, then
1043 returns the autocmds for all the events in all the groups.
1044
1045 The optional {opts} Dict argument supports the following
1046 items:
1047 group Autocmd group name. If specified, returns only
1048 the autocmds defined in this group. If the
1049 specified group doesn't exist, results in an
1050 error message. If set to an empty string,
1051 then the default autocmd group is used.
1052 event Autocmd event name. If specified, returns only
1053 the autocmds defined for this event. If set
1054 to "*", then returns autocmds for all the
1055 events. If the specified event doesn't exist,
1056 results in an error message.
1057 pattern Autocmd pattern. If specified, returns only
1058 the autocmds defined for this pattern.
1059 A combination of the above three times can be supplied in
1060 {opts}.
1061
1062 Each Dict in the returned List contains the following items:
1063 bufnr For buffer-local autocmds, buffer number where
1064 the autocmd is defined.
1065 cmd Command executed for this autocmd.
1066 event Autocmd event name.
1067 group Autocmd group name.
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +01001068 nested Boolean flag, set to v:true for a nested
1069 autocmd. See |autocmd-nested|.
1070 once Boolean flag, set to v:true, if the autocmd
1071 will be executed only once. See |autocmd-once|.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001072 pattern Autocmd pattern. For a buffer-local
1073 autocmd, this will be of the form "<buffer=n>".
1074 If there are multiple commands for an autocmd event in a
1075 group, then separate items are returned for each command.
1076
Bram Moolenaar016188f2022-06-06 20:52:59 +01001077 Returns an empty List if an autocmd with the specified group
1078 or event or pattern is not found.
1079
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +01001080 Examples: >
1081 " :autocmd MyGroup
1082 echo autocmd_get(#{group: 'Mygroup'})
1083 " :autocmd G BufUnload
1084 echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1085 " :autocmd G * *.ts
1086 let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1087 echo autocmd_get(acmd)
1088 " :autocmd Syntax
1089 echo autocmd_get(#{event: 'Syntax'})
1090 " :autocmd G BufEnter *.ts
1091 let acmd = #{group: 'G', event: 'BufEnter',
1092 \ pattern: '*.ts'}
1093 echo autocmd_get(acmd)
1094<
1095 Can also be used as a |method|: >
1096 Getopts()->autocmd_get()
1097<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001098balloon_gettext() *balloon_gettext()*
1099 Return the current text in the balloon. Only for the string,
Bram Moolenaar016188f2022-06-06 20:52:59 +01001100 not used for the List. Returns an empty string if balloon
1101 is not present.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001102
1103balloon_show({expr}) *balloon_show()*
1104 Show {expr} inside the balloon. For the GUI {expr} is used as
1105 a string. For a terminal {expr} can be a list, which contains
1106 the lines of the balloon. If {expr} is not a list it will be
1107 split with |balloon_split()|.
1108 If {expr} is an empty string any existing balloon is removed.
1109
1110 Example: >
1111 func GetBalloonContent()
1112 " ... initiate getting the content
1113 return ''
1114 endfunc
1115 set balloonexpr=GetBalloonContent()
1116
1117 func BalloonCallback(result)
1118 call balloon_show(a:result)
1119 endfunc
1120< Can also be used as a |method|: >
1121 GetText()->balloon_show()
1122<
1123 The intended use is that fetching the content of the balloon
1124 is initiated from 'balloonexpr'. It will invoke an
1125 asynchronous method, in which a callback invokes
1126 balloon_show(). The 'balloonexpr' itself can return an
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001127 empty string or a placeholder, e.g. "loading...".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001128
Bram Moolenaar069a7d52022-06-27 22:16:08 +01001129 When showing a balloon is not possible then nothing happens,
1130 no error message is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001131 {only available when compiled with the |+balloon_eval| or
1132 |+balloon_eval_term| feature}
1133
1134balloon_split({msg}) *balloon_split()*
1135 Split String {msg} into lines to be displayed in a balloon.
1136 The splits are made for the current window size and optimize
1137 to show debugger output.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001138 Returns a |List| with the split lines. Returns an empty List
1139 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001140 Can also be used as a |method|: >
1141 GetText()->balloon_split()->balloon_show()
1142
1143< {only available when compiled with the |+balloon_eval_term|
1144 feature}
1145
1146blob2list({blob}) *blob2list()*
1147 Return a List containing the number value of each byte in Blob
1148 {blob}. Examples: >
1149 blob2list(0z0102.0304) returns [1, 2, 3, 4]
1150 blob2list(0z) returns []
1151< Returns an empty List on error. |list2blob()| does the
1152 opposite.
1153
1154 Can also be used as a |method|: >
1155 GetBlob()->blob2list()
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001156<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001157 *browse()*
1158browse({save}, {title}, {initdir}, {default})
1159 Put up a file requester. This only works when "has("browse")"
1160 returns |TRUE| (only in some GUI versions).
1161 The input fields are:
1162 {save} when |TRUE|, select file to write
1163 {title} title for the requester
1164 {initdir} directory to start browsing in
1165 {default} default file name
1166 An empty string is returned when the "Cancel" button is hit,
1167 something went wrong, or browsing is not possible.
1168
1169 *browsedir()*
1170browsedir({title}, {initdir})
1171 Put up a directory requester. This only works when
1172 "has("browse")" returns |TRUE| (only in some GUI versions).
1173 On systems where a directory browser is not supported a file
1174 browser is used. In that case: select a file in the directory
1175 to be used.
1176 The input fields are:
1177 {title} title for the requester
1178 {initdir} directory to start browsing in
1179 When the "Cancel" button is hit, something went wrong, or
1180 browsing is not possible, an empty string is returned.
1181
1182bufadd({name}) *bufadd()*
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001183 Add a buffer to the buffer list with name {name} (must be a
1184 String).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001185 If a buffer for file {name} already exists, return that buffer
1186 number. Otherwise return the buffer number of the newly
1187 created buffer. When {name} is an empty string then a new
1188 buffer is always created.
1189 The buffer will not have 'buflisted' set and not be loaded
1190 yet. To add some text to the buffer use this: >
1191 let bufnr = bufadd('someName')
1192 call bufload(bufnr)
1193 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar016188f2022-06-06 20:52:59 +01001194< Returns 0 on error.
1195 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001196 let bufnr = 'somename'->bufadd()
1197
1198bufexists({buf}) *bufexists()*
1199 The result is a Number, which is |TRUE| if a buffer called
1200 {buf} exists.
1201 If the {buf} argument is a number, buffer numbers are used.
1202 Number zero is the alternate buffer for the current window.
1203
1204 If the {buf} argument is a string it must match a buffer name
1205 exactly. The name can be:
1206 - Relative to the current directory.
1207 - A full path.
1208 - The name of a buffer with 'buftype' set to "nofile".
1209 - A URL name.
1210 Unlisted buffers will be found.
1211 Note that help files are listed by their short name in the
1212 output of |:buffers|, but bufexists() requires using their
1213 long name to be able to find them.
1214 bufexists() may report a buffer exists, but to use the name
1215 with a |:buffer| command you may need to use |expand()|. Esp
1216 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1217 Use "bufexists(0)" to test for the existence of an alternate
1218 file name.
1219
1220 Can also be used as a |method|: >
1221 let exists = 'somename'->bufexists()
1222<
1223 Obsolete name: buffer_exists(). *buffer_exists()*
1224
1225buflisted({buf}) *buflisted()*
1226 The result is a Number, which is |TRUE| if a buffer called
1227 {buf} exists and is listed (has the 'buflisted' option set).
1228 The {buf} argument is used like with |bufexists()|.
1229
1230 Can also be used as a |method|: >
1231 let listed = 'somename'->buflisted()
1232
1233bufload({buf}) *bufload()*
1234 Ensure the buffer {buf} is loaded. When the buffer name
1235 refers to an existing file then the file is read. Otherwise
1236 the buffer will be empty. If the buffer was already loaded
Bram Moolenaar2eddbac2022-08-25 12:45:21 +01001237 then there is no change. If the buffer is not related to a
1238 file the no file is read (e.g., when 'buftype' is "nofile").
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001239 If there is an existing swap file for the file of the buffer,
1240 there will be no dialog, the buffer will be loaded anyway.
1241 The {buf} argument is used like with |bufexists()|.
1242
1243 Can also be used as a |method|: >
1244 eval 'somename'->bufload()
1245
1246bufloaded({buf}) *bufloaded()*
1247 The result is a Number, which is |TRUE| if a buffer called
1248 {buf} exists and is loaded (shown in a window or hidden).
1249 The {buf} argument is used like with |bufexists()|.
1250
1251 Can also be used as a |method|: >
1252 let loaded = 'somename'->bufloaded()
1253
1254bufname([{buf}]) *bufname()*
1255 The result is the name of a buffer. Mostly as it is displayed
1256 by the `:ls` command, but not using special names such as
1257 "[No Name]".
1258 If {buf} is omitted the current buffer is used.
1259 If {buf} is a Number, that buffer number's name is given.
1260 Number zero is the alternate buffer for the current window.
1261 If {buf} is a String, it is used as a |file-pattern| to match
1262 with the buffer names. This is always done like 'magic' is
1263 set and 'cpoptions' is empty. When there is more than one
1264 match an empty string is returned.
1265 "" or "%" can be used for the current buffer, "#" for the
1266 alternate buffer.
1267 A full match is preferred, otherwise a match at the start, end
1268 or middle of the buffer name is accepted. If you only want a
1269 full match then put "^" at the start and "$" at the end of the
1270 pattern.
1271 Listed buffers are found first. If there is a single match
1272 with a listed buffer, that one is returned. Next unlisted
1273 buffers are searched for.
1274 If the {buf} is a String, but you want to use it as a buffer
1275 number, force it to be a Number by adding zero to it: >
1276 :echo bufname("3" + 0)
1277< Can also be used as a |method|: >
1278 echo bufnr->bufname()
1279
1280< If the buffer doesn't exist, or doesn't have a name, an empty
1281 string is returned. >
1282 bufname("#") alternate buffer name
1283 bufname(3) name of buffer 3
1284 bufname("%") name of current buffer
1285 bufname("file2") name of buffer where "file2" matches.
1286< *buffer_name()*
1287 Obsolete name: buffer_name().
1288
1289 *bufnr()*
1290bufnr([{buf} [, {create}]])
1291 The result is the number of a buffer, as it is displayed by
1292 the `:ls` command. For the use of {buf}, see |bufname()|
1293 above.
1294
1295 If the buffer doesn't exist, -1 is returned. Or, if the
1296 {create} argument is present and TRUE, a new, unlisted,
1297 buffer is created and its number is returned. Example: >
1298 let newbuf = bufnr('Scratch001', 1)
1299< Using an empty name uses the current buffer. To create a new
1300 buffer with an empty name use |bufadd()|.
1301
1302 bufnr("$") is the last buffer: >
1303 :let last_buffer = bufnr("$")
1304< The result is a Number, which is the highest buffer number
1305 of existing buffers. Note that not all buffers with a smaller
1306 number necessarily exist, because ":bwipeout" may have removed
1307 them. Use bufexists() to test for the existence of a buffer.
1308
1309 Can also be used as a |method|: >
1310 echo bufref->bufnr()
1311<
1312 Obsolete name: buffer_number(). *buffer_number()*
1313 *last_buffer_nr()*
1314 Obsolete name for bufnr("$"): last_buffer_nr().
1315
1316bufwinid({buf}) *bufwinid()*
1317 The result is a Number, which is the |window-ID| of the first
1318 window associated with buffer {buf}. For the use of {buf},
1319 see |bufname()| above. If buffer {buf} doesn't exist or
1320 there is no such window, -1 is returned. Example: >
1321
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001322 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001323<
1324 Only deals with the current tab page.
1325
1326 Can also be used as a |method|: >
1327 FindBuffer()->bufwinid()
1328
1329bufwinnr({buf}) *bufwinnr()*
1330 Like |bufwinid()| but return the window number instead of the
1331 |window-ID|.
1332 If buffer {buf} doesn't exist or there is no such window, -1
1333 is returned. Example: >
1334
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001335 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001336
1337< The number can be used with |CTRL-W_w| and ":wincmd w"
1338 |:wincmd|.
1339
1340 Can also be used as a |method|: >
1341 FindBuffer()->bufwinnr()
1342
1343byte2line({byte}) *byte2line()*
1344 Return the line number that contains the character at byte
1345 count {byte} in the current buffer. This includes the
1346 end-of-line character, depending on the 'fileformat' option
1347 for the current buffer. The first character has byte count
1348 one.
1349 Also see |line2byte()|, |go| and |:goto|.
1350
Bram Moolenaar016188f2022-06-06 20:52:59 +01001351 Returns -1 if the {byte} value is invalid.
1352
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001353 Can also be used as a |method|: >
1354 GetOffset()->byte2line()
1355
1356< {not available when compiled without the |+byte_offset|
1357 feature}
1358
1359byteidx({expr}, {nr}) *byteidx()*
1360 Return byte index of the {nr}'th character in the String
1361 {expr}. Use zero for the first character, it then returns
1362 zero.
1363 If there are no multibyte characters the returned value is
1364 equal to {nr}.
1365 Composing characters are not counted separately, their byte
1366 length is added to the preceding base character. See
1367 |byteidxcomp()| below for counting composing characters
1368 separately.
1369 Example : >
1370 echo matchstr(str, ".", byteidx(str, 3))
1371< will display the fourth character. Another way to do the
1372 same: >
1373 let s = strpart(str, byteidx(str, 3))
1374 echo strpart(s, 0, byteidx(s, 1))
1375< Also see |strgetchar()| and |strcharpart()|.
1376
1377 If there are less than {nr} characters -1 is returned.
1378 If there are exactly {nr} characters the length of the string
1379 in bytes is returned.
1380
1381 Can also be used as a |method|: >
1382 GetName()->byteidx(idx)
1383
1384byteidxcomp({expr}, {nr}) *byteidxcomp()*
1385 Like byteidx(), except that a composing character is counted
1386 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001387 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001388 echo byteidx(s, 1)
1389 echo byteidxcomp(s, 1)
1390 echo byteidxcomp(s, 2)
1391< The first and third echo result in 3 ('e' plus composing
1392 character is 3 bytes), the second echo results in 1 ('e' is
1393 one byte).
1394 Only works differently from byteidx() when 'encoding' is set
1395 to a Unicode encoding.
1396
1397 Can also be used as a |method|: >
1398 GetName()->byteidxcomp(idx)
1399
1400call({func}, {arglist} [, {dict}]) *call()* *E699*
1401 Call function {func} with the items in |List| {arglist} as
1402 arguments.
1403 {func} can either be a |Funcref| or the name of a function.
1404 a:firstline and a:lastline are set to the cursor line.
1405 Returns the return value of the called function.
1406 {dict} is for functions with the "dict" attribute. It will be
1407 used to set the local variable "self". |Dictionary-function|
1408
1409 Can also be used as a |method|: >
1410 GetFunc()->call([arg, arg], dict)
1411
1412ceil({expr}) *ceil()*
1413 Return the smallest integral value greater than or equal to
1414 {expr} as a |Float| (round up).
1415 {expr} must evaluate to a |Float| or a |Number|.
1416 Examples: >
1417 echo ceil(1.456)
1418< 2.0 >
1419 echo ceil(-5.456)
1420< -5.0 >
1421 echo ceil(4.0)
1422< 4.0
1423
Bram Moolenaar016188f2022-06-06 20:52:59 +01001424 Returns 0.0 if {expr} is not a |Float| or a |Number|.
1425
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001426 Can also be used as a |method|: >
1427 Compute()->ceil()
1428<
1429 {only available when compiled with the |+float| feature}
1430
1431
1432ch_ functions are documented here: |channel-functions-details|
1433
1434
1435changenr() *changenr()*
1436 Return the number of the most recent change. This is the same
1437 number as what is displayed with |:undolist| and can be used
1438 with the |:undo| command.
1439 When a change was made it is the number of that change. After
1440 redo it is the number of the redone change. After undo it is
1441 one less than the number of the undone change.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001442 Returns 0 if the undo list is empty.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001443
1444char2nr({string} [, {utf8}]) *char2nr()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001445 Return Number value of the first char in {string}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001446 Examples: >
1447 char2nr(" ") returns 32
1448 char2nr("ABC") returns 65
1449< When {utf8} is omitted or zero, the current 'encoding' is used.
1450 Example for "utf-8": >
1451 char2nr("á") returns 225
1452 char2nr("á"[0]) returns 195
1453< When {utf8} is TRUE, always treat as UTF-8 characters.
1454 A combining character is a separate character.
1455 |nr2char()| does the opposite.
1456 To turn a string into a list of character numbers: >
1457 let str = "ABC"
1458 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1459< Result: [65, 66, 67]
1460
Bram Moolenaar016188f2022-06-06 20:52:59 +01001461 Returns 0 if {string} is not a |String|.
1462
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001463 Can also be used as a |method|: >
1464 GetChar()->char2nr()
1465
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001466charclass({string}) *charclass()*
1467 Return the character class of the first character in {string}.
1468 The character class is one of:
1469 0 blank
1470 1 punctuation
1471 2 word character
1472 3 emoji
1473 other specific Unicode class
1474 The class is used in patterns and word motions.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001475 Returns 0 if {string} is not a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001476
1477
1478charcol({expr}) *charcol()*
1479 Same as |col()| but returns the character index of the column
1480 position given with {expr} instead of the byte position.
1481
1482 Example:
1483 With the cursor on '세' in line 5 with text "여보세요": >
1484 charcol('.') returns 3
1485 col('.') returns 7
1486
1487< Can also be used as a |method|: >
1488 GetPos()->col()
1489<
1490 *charidx()*
1491charidx({string}, {idx} [, {countcc}])
1492 Return the character index of the byte at {idx} in {string}.
1493 The index of the first character is zero.
1494 If there are no multibyte characters the returned value is
1495 equal to {idx}.
1496 When {countcc} is omitted or |FALSE|, then composing characters
1497 are not counted separately, their byte length is
1498 added to the preceding base character.
1499 When {countcc} is |TRUE|, then composing characters are
1500 counted as separate characters.
1501 Returns -1 if the arguments are invalid or if {idx} is greater
1502 than the index of the last byte in {string}. An error is
1503 given if the first argument is not a string, the second
1504 argument is not a number or when the third argument is present
1505 and is not zero or one.
1506 See |byteidx()| and |byteidxcomp()| for getting the byte index
1507 from the character index.
1508 Examples: >
1509 echo charidx('áb́ć', 3) returns 1
1510 echo charidx('áb́ć', 6, 1) returns 4
1511 echo charidx('áb́ć', 16) returns -1
1512<
1513 Can also be used as a |method|: >
1514 GetName()->charidx(idx)
1515
1516chdir({dir}) *chdir()*
1517 Change the current working directory to {dir}. The scope of
1518 the directory change depends on the directory of the current
1519 window:
1520 - If the current window has a window-local directory
1521 (|:lcd|), then changes the window local directory.
1522 - Otherwise, if the current tabpage has a local
1523 directory (|:tcd|) then changes the tabpage local
1524 directory.
1525 - Otherwise, changes the global directory.
1526 {dir} must be a String.
1527 If successful, returns the previous working directory. Pass
1528 this to another chdir() to restore the directory.
1529 On failure, returns an empty string.
1530
1531 Example: >
1532 let save_dir = chdir(newdir)
1533 if save_dir != ""
1534 " ... do some work
1535 call chdir(save_dir)
1536 endif
1537
1538< Can also be used as a |method|: >
1539 GetDir()->chdir()
1540<
1541cindent({lnum}) *cindent()*
1542 Get the amount of indent for line {lnum} according the C
1543 indenting rules, as with 'cindent'.
1544 The indent is counted in spaces, the value of 'tabstop' is
1545 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01001546 When {lnum} is invalid -1 is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001547 See |C-indenting|.
1548
1549 Can also be used as a |method|: >
1550 GetLnum()->cindent()
1551
1552clearmatches([{win}]) *clearmatches()*
1553 Clears all matches previously defined for the current window
1554 by |matchadd()| and the |:match| commands.
1555 If {win} is specified, use the window with this number or
1556 window ID instead of the current window.
1557
1558 Can also be used as a |method|: >
1559 GetWin()->clearmatches()
1560<
1561 *col()*
1562col({expr}) The result is a Number, which is the byte index of the column
1563 position given with {expr}. The accepted positions are:
1564 . the cursor position
1565 $ the end of the cursor line (the result is the
1566 number of bytes in the cursor line plus one)
1567 'x position of mark x (if the mark is not set, 0 is
1568 returned)
1569 v In Visual mode: the start of the Visual area (the
1570 cursor is the end). When not in Visual mode
1571 returns the cursor position. Differs from |'<| in
1572 that it's updated right away.
1573 Additionally {expr} can be [lnum, col]: a |List| with the line
1574 and column number. Most useful when the column is "$", to get
1575 the last column of a specific line. When "lnum" or "col" is
1576 out of range then col() returns zero.
1577 To get the line number use |line()|. To get both use
1578 |getpos()|.
1579 For the screen column position use |virtcol()|. For the
1580 character position use |charcol()|.
1581 Note that only marks in the current file can be used.
1582 Examples: >
1583 col(".") column of cursor
1584 col("$") length of cursor line plus one
1585 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001586 col("'" .. markname) column of mark markname
Bram Moolenaar016188f2022-06-06 20:52:59 +01001587< The first column is 1. Returns 0 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001588 For an uppercase mark the column may actually be in another
1589 buffer.
1590 For the cursor position, when 'virtualedit' is active, the
1591 column is one higher if the cursor is after the end of the
1592 line. This can be used to obtain the column in Insert mode: >
1593 :imap <F2> <C-O>:let save_ve = &ve<CR>
1594 \<C-O>:set ve=all<CR>
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001595 \<C-O>:echo col(".") .. "\n" <Bar>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001596 \let &ve = save_ve<CR>
1597
1598< Can also be used as a |method|: >
1599 GetPos()->col()
1600<
1601
1602complete({startcol}, {matches}) *complete()* *E785*
1603 Set the matches for Insert mode completion.
1604 Can only be used in Insert mode. You need to use a mapping
1605 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1606 or with an expression mapping.
1607 {startcol} is the byte offset in the line where the completed
1608 text start. The text up to the cursor is the original text
1609 that will be replaced by the matches. Use col('.') for an
1610 empty string. "col('.') - 1" will replace one character by a
1611 match.
1612 {matches} must be a |List|. Each |List| item is one match.
1613 See |complete-items| for the kind of items that are possible.
1614 "longest" in 'completeopt' is ignored.
1615 Note that the after calling this function you need to avoid
1616 inserting anything that would cause completion to stop.
1617 The match can be selected with CTRL-N and CTRL-P as usual with
1618 Insert mode completion. The popup menu will appear if
1619 specified, see |ins-completion-menu|.
1620 Example: >
1621 inoremap <F5> <C-R>=ListMonths()<CR>
1622
1623 func! ListMonths()
1624 call complete(col('.'), ['January', 'February', 'March',
1625 \ 'April', 'May', 'June', 'July', 'August', 'September',
1626 \ 'October', 'November', 'December'])
1627 return ''
1628 endfunc
1629< This isn't very useful, but it shows how it works. Note that
1630 an empty string is returned to avoid a zero being inserted.
1631
1632 Can also be used as a |method|, the base is passed as the
1633 second argument: >
1634 GetMatches()->complete(col('.'))
1635
1636complete_add({expr}) *complete_add()*
1637 Add {expr} to the list of matches. Only to be used by the
1638 function specified with the 'completefunc' option.
1639 Returns 0 for failure (empty string or out of memory),
1640 1 when the match was added, 2 when the match was already in
1641 the list.
1642 See |complete-functions| for an explanation of {expr}. It is
1643 the same as one item in the list that 'omnifunc' would return.
1644
1645 Can also be used as a |method|: >
1646 GetMoreMatches()->complete_add()
1647
1648complete_check() *complete_check()*
1649 Check for a key typed while looking for completion matches.
1650 This is to be used when looking for matches takes some time.
1651 Returns |TRUE| when searching for matches is to be aborted,
1652 zero otherwise.
1653 Only to be used by the function specified with the
1654 'completefunc' option.
1655
1656
1657complete_info([{what}]) *complete_info()*
1658 Returns a |Dictionary| with information about Insert mode
1659 completion. See |ins-completion|.
1660 The items are:
1661 mode Current completion mode name string.
1662 See |complete_info_mode| for the values.
1663 pum_visible |TRUE| if popup menu is visible.
1664 See |pumvisible()|.
1665 items List of completion matches. Each item is a
1666 dictionary containing the entries "word",
1667 "abbr", "menu", "kind", "info" and "user_data".
1668 See |complete-items|.
1669 selected Selected item index. First index is zero.
1670 Index is -1 if no item is selected (showing
1671 typed text only, or the last completion after
1672 no item is selected when using the <Up> or
1673 <Down> keys)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01001674 inserted Inserted string. [NOT IMPLEMENTED YET]
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001675
1676 *complete_info_mode*
1677 mode values are:
1678 "" Not in completion mode
1679 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1680 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1681 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1682 |i_CTRL-X_CTRL-Y|
1683 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1684 "files" File names |i_CTRL-X_CTRL-F|
1685 "tags" Tags |i_CTRL-X_CTRL-]|
1686 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1687 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1688 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1689 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1690 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1691 "function" User defined completion |i_CTRL-X_CTRL-U|
1692 "omni" Omni completion |i_CTRL-X_CTRL-O|
1693 "spell" Spelling suggestions |i_CTRL-X_s|
1694 "eval" |complete()| completion
1695 "unknown" Other internal modes
1696
1697 If the optional {what} list argument is supplied, then only
1698 the items listed in {what} are returned. Unsupported items in
1699 {what} are silently ignored.
1700
1701 To get the position and size of the popup menu, see
1702 |pum_getpos()|. It's also available in |v:event| during the
1703 |CompleteChanged| event.
1704
Bram Moolenaar016188f2022-06-06 20:52:59 +01001705 Returns an empty |Dictionary| on error.
1706
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001707 Examples: >
1708 " Get all items
1709 call complete_info()
1710 " Get only 'mode'
1711 call complete_info(['mode'])
1712 " Get only 'mode' and 'pum_visible'
1713 call complete_info(['mode', 'pum_visible'])
1714
1715< Can also be used as a |method|: >
1716 GetItems()->complete_info()
1717<
1718 *confirm()*
1719confirm({msg} [, {choices} [, {default} [, {type}]]])
1720 confirm() offers the user a dialog, from which a choice can be
1721 made. It returns the number of the choice. For the first
1722 choice this is 1.
1723 Note: confirm() is only supported when compiled with dialog
1724 support, see |+dialog_con| and |+dialog_gui|.
1725
1726 {msg} is displayed in a |dialog| with {choices} as the
1727 alternatives. When {choices} is missing or empty, "&OK" is
1728 used (and translated).
1729 {msg} is a String, use '\n' to include a newline. Only on
1730 some systems the string is wrapped when it doesn't fit.
1731
1732 {choices} is a String, with the individual choices separated
1733 by '\n', e.g. >
1734 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1735< The letter after the '&' is the shortcut key for that choice.
1736 Thus you can type 'c' to select "Cancel". The shortcut does
1737 not need to be the first letter: >
1738 confirm("file has been modified", "&Save\nSave &All")
1739< For the console, the first letter of each choice is used as
1740 the default shortcut key. Case is ignored.
1741
1742 The optional {default} argument is the number of the choice
1743 that is made if the user hits <CR>. Use 1 to make the first
1744 choice the default one. Use 0 to not set a default. If
1745 {default} is omitted, 1 is used.
1746
1747 The optional {type} String argument gives the type of dialog.
1748 This is only used for the icon of the GTK, Mac, Motif and
1749 Win32 GUI. It can be one of these values: "Error",
1750 "Question", "Info", "Warning" or "Generic". Only the first
1751 character is relevant. When {type} is omitted, "Generic" is
1752 used.
1753
1754 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1755 or another valid interrupt key, confirm() returns 0.
1756
1757 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001758 let choice = confirm("What do you want?",
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001759 \ "&Apples\n&Oranges\n&Bananas", 2)
Bram Moolenaar46eea442022-03-30 10:51:39 +01001760 if choice == 0
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001761 echo "make up your mind!"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001762 elseif choice == 3
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001763 echo "tasteful"
Bram Moolenaar46eea442022-03-30 10:51:39 +01001764 else
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01001765 echo "I prefer bananas myself."
Bram Moolenaar46eea442022-03-30 10:51:39 +01001766 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001767< In a GUI dialog, buttons are used. The layout of the buttons
1768 depends on the 'v' flag in 'guioptions'. If it is included,
1769 the buttons are always put vertically. Otherwise, confirm()
1770 tries to put the buttons in one horizontal line. If they
1771 don't fit, a vertical layout is used anyway. For some systems
1772 the horizontal layout is always used.
1773
1774 Can also be used as a |method|in: >
1775 BuildMessage()->confirm("&Yes\n&No")
1776<
1777 *copy()*
1778copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1779 different from using {expr} directly.
1780 When {expr} is a |List| a shallow copy is created. This means
1781 that the original |List| can be changed without changing the
1782 copy, and vice versa. But the items are identical, thus
1783 changing an item changes the contents of both |Lists|.
1784 A |Dictionary| is copied in a similar way as a |List|.
1785 Also see |deepcopy()|.
1786 Can also be used as a |method|: >
1787 mylist->copy()
1788
1789cos({expr}) *cos()*
1790 Return the cosine of {expr}, measured in radians, as a |Float|.
1791 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001792 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001793 Examples: >
1794 :echo cos(100)
1795< 0.862319 >
1796 :echo cos(-4.01)
1797< -0.646043
1798
1799 Can also be used as a |method|: >
1800 Compute()->cos()
1801<
1802 {only available when compiled with the |+float| feature}
1803
1804
1805cosh({expr}) *cosh()*
1806 Return the hyperbolic cosine of {expr} as a |Float| in the range
1807 [1, inf].
1808 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01001809 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001810 Examples: >
1811 :echo cosh(0.5)
1812< 1.127626 >
1813 :echo cosh(-0.5)
1814< -1.127626
1815
1816 Can also be used as a |method|: >
1817 Compute()->cosh()
1818<
1819 {only available when compiled with the |+float| feature}
1820
1821
1822count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1823 Return the number of times an item with value {expr} appears
1824 in |String|, |List| or |Dictionary| {comp}.
1825
1826 If {start} is given then start with the item with this index.
1827 {start} can only be used with a |List|.
1828
1829 When {ic} is given and it's |TRUE| then case is ignored.
1830
1831 When {comp} is a string then the number of not overlapping
1832 occurrences of {expr} is returned. Zero is returned when
1833 {expr} is an empty string.
1834
1835 Can also be used as a |method|: >
1836 mylist->count(val)
1837<
1838 *cscope_connection()*
1839cscope_connection([{num} , {dbpath} [, {prepend}]])
1840 Checks for the existence of a |cscope| connection. If no
1841 parameters are specified, then the function returns:
1842 0, if cscope was not available (not compiled in), or
1843 if there are no cscope connections;
1844 1, if there is at least one cscope connection.
1845
1846 If parameters are specified, then the value of {num}
1847 determines how existence of a cscope connection is checked:
1848
1849 {num} Description of existence check
1850 ----- ------------------------------
1851 0 Same as no parameters (e.g., "cscope_connection()").
1852 1 Ignore {prepend}, and use partial string matches for
1853 {dbpath}.
1854 2 Ignore {prepend}, and use exact string matches for
1855 {dbpath}.
1856 3 Use {prepend}, use partial string matches for both
1857 {dbpath} and {prepend}.
1858 4 Use {prepend}, use exact string matches for both
1859 {dbpath} and {prepend}.
1860
1861 Note: All string comparisons are case sensitive!
1862
1863 Examples. Suppose we had the following (from ":cs show"): >
1864
1865 # pid database name prepend path
1866 0 27664 cscope.out /usr/local
1867<
1868 Invocation Return Val ~
1869 ---------- ---------- >
1870 cscope_connection() 1
1871 cscope_connection(1, "out") 1
1872 cscope_connection(2, "out") 0
1873 cscope_connection(3, "out") 0
1874 cscope_connection(3, "out", "local") 1
1875 cscope_connection(4, "out") 0
1876 cscope_connection(4, "out", "local") 0
1877 cscope_connection(4, "cscope.out", "/usr/local") 1
1878<
1879cursor({lnum}, {col} [, {off}]) *cursor()*
1880cursor({list})
1881 Positions the cursor at the column (byte count) {col} in the
1882 line {lnum}. The first column is one.
1883
1884 When there is one argument {list} this is used as a |List|
1885 with two, three or four item:
1886 [{lnum}, {col}]
1887 [{lnum}, {col}, {off}]
1888 [{lnum}, {col}, {off}, {curswant}]
1889 This is like the return value of |getpos()| or |getcurpos()|,
1890 but without the first item.
1891
1892 To position the cursor using the character count, use
1893 |setcursorcharpos()|.
1894
1895 Does not change the jumplist.
1896 {lnum} is used like with |getline()|.
1897 If {lnum} is greater than the number of lines in the buffer,
1898 the cursor will be positioned at the last line in the buffer.
1899 If {lnum} is zero, the cursor will stay in the current line.
1900 If {col} is greater than the number of bytes in the line,
1901 the cursor will be positioned at the last character in the
1902 line.
1903 If {col} is zero, the cursor will stay in the current column.
1904 If {curswant} is given it is used to set the preferred column
1905 for vertical movement. Otherwise {col} is used.
1906
1907 When 'virtualedit' is used {off} specifies the offset in
1908 screen columns from the start of the character. E.g., a
1909 position within a <Tab> or after the last character.
1910 Returns 0 when the position could be set, -1 otherwise.
1911
1912 Can also be used as a |method|: >
1913 GetCursorPos()->cursor()
1914
1915debugbreak({pid}) *debugbreak()*
1916 Specifically used to interrupt a program being debugged. It
1917 will cause process {pid} to get a SIGTRAP. Behavior for other
1918 processes is undefined. See |terminal-debugger|.
1919 {only available on MS-Windows}
1920
Bram Moolenaar016188f2022-06-06 20:52:59 +01001921 Returns |TRUE| if successfully interrupted the program.
1922 Otherwise returns |FALSE|.
1923
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001924 Can also be used as a |method|: >
1925 GetPid()->debugbreak()
1926
1927deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1928 Make a copy of {expr}. For Numbers and Strings this isn't
1929 different from using {expr} directly.
1930 When {expr} is a |List| a full copy is created. This means
1931 that the original |List| can be changed without changing the
1932 copy, and vice versa. When an item is a |List| or
1933 |Dictionary|, a copy for it is made, recursively. Thus
1934 changing an item in the copy does not change the contents of
1935 the original |List|.
1936 A |Dictionary| is copied in a similar way as a |List|.
1937
1938 When {noref} is omitted or zero a contained |List| or
1939 |Dictionary| is only copied once. All references point to
1940 this single copy. With {noref} set to 1 every occurrence of a
1941 |List| or |Dictionary| results in a new copy. This also means
1942 that a cyclic reference causes deepcopy() to fail.
1943 *E724*
1944 Nesting is possible up to 100 levels. When there is an item
1945 that refers back to a higher level making a deep copy with
1946 {noref} set to 1 will fail.
1947 Also see |copy()|.
1948
1949 Can also be used as a |method|: >
1950 GetObject()->deepcopy()
1951
1952delete({fname} [, {flags}]) *delete()*
1953 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001954 name {fname}.
1955
1956 This also works when {fname} is a symbolic link. The symbolic
1957 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001958
1959 When {flags} is "d": Deletes the directory by the name
1960 {fname}. This fails when directory {fname} is not empty.
1961
1962 When {flags} is "rf": Deletes the directory by the name
1963 {fname} and everything in it, recursively. BE CAREFUL!
1964 Note: on MS-Windows it is not possible to delete a directory
1965 that is being used.
1966
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001967 The result is a Number, which is 0/false if the delete
1968 operation was successful and -1/true when the deletion failed
1969 or partly failed.
1970
1971 Use |remove()| to delete an item from a |List|.
1972 To delete a line from the buffer use |:delete| or
1973 |deletebufline()|.
1974
1975 Can also be used as a |method|: >
1976 GetName()->delete()
1977
1978deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1979 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1980 If {last} is omitted then delete line {first} only.
1981 On success 0 is returned, on failure 1 is returned.
1982
1983 This function works only for loaded buffers. First call
1984 |bufload()| if needed.
1985
1986 For the use of {buf}, see |bufname()| above.
1987
1988 {first} and {last} are used like with |getline()|. Note that
1989 when using |line()| this refers to the current buffer. Use "$"
1990 to refer to the last line in buffer {buf}.
1991
1992 Can also be used as a |method|: >
1993 GetBuffer()->deletebufline(1)
1994<
1995 *did_filetype()*
1996did_filetype() Returns |TRUE| when autocommands are being executed and the
1997 FileType event has been triggered at least once. Can be used
1998 to avoid triggering the FileType event again in the scripts
1999 that detect the file type. |FileType|
2000 Returns |FALSE| when `:setf FALLBACK` was used.
2001 When editing another file, the counter is reset, thus this
2002 really checks if the FileType event has been triggered for the
2003 current buffer. This allows an autocommand that starts
2004 editing another buffer to set 'filetype' and load a syntax
2005 file.
2006
2007diff_filler({lnum}) *diff_filler()*
2008 Returns the number of filler lines above line {lnum}.
2009 These are the lines that were inserted at this point in
2010 another diff'ed window. These filler lines are shown in the
2011 display but don't exist in the buffer.
2012 {lnum} is used like with |getline()|. Thus "." is the current
2013 line, "'m" mark m, etc.
2014 Returns 0 if the current window is not in diff mode.
2015
2016 Can also be used as a |method|: >
2017 GetLnum()->diff_filler()
2018
2019diff_hlID({lnum}, {col}) *diff_hlID()*
2020 Returns the highlight ID for diff mode at line {lnum} column
2021 {col} (byte index). When the current line does not have a
2022 diff change zero is returned.
2023 {lnum} is used like with |getline()|. Thus "." is the current
2024 line, "'m" mark m, etc.
2025 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2026 line.
2027 The highlight ID can be used with |synIDattr()| to obtain
2028 syntax information about the highlighting.
2029
2030 Can also be used as a |method|: >
2031 GetLnum()->diff_hlID(col)
2032<
2033
2034digraph_get({chars}) *digraph_get()* *E1214*
2035 Return the digraph of {chars}. This should be a string with
2036 exactly two characters. If {chars} are not just two
2037 characters, or the digraph of {chars} does not exist, an error
2038 is given and an empty string is returned.
2039
2040 The character will be converted from Unicode to 'encoding'
2041 when needed. This does require the conversion to be
2042 available, it might fail.
2043
2044 Also see |digraph_getlist()|.
2045
2046 Examples: >
2047 " Get a built-in digraph
2048 :echo digraph_get('00') " Returns '∞'
2049
2050 " Get a user-defined digraph
2051 :call digraph_set('aa', 'あ')
2052 :echo digraph_get('aa') " Returns 'あ'
2053<
2054 Can also be used as a |method|: >
2055 GetChars()->digraph_get()
2056<
2057 This function works only when compiled with the |+digraphs|
2058 feature. If this feature is disabled, this function will
2059 display an error message.
2060
2061
2062digraph_getlist([{listall}]) *digraph_getlist()*
2063 Return a list of digraphs. If the {listall} argument is given
2064 and it is TRUE, return all digraphs, including the default
2065 digraphs. Otherwise, return only user-defined digraphs.
2066
2067 The characters will be converted from Unicode to 'encoding'
2068 when needed. This does require the conservation to be
2069 available, it might fail.
2070
2071 Also see |digraph_get()|.
2072
2073 Examples: >
2074 " Get user-defined digraphs
2075 :echo digraph_getlist()
2076
2077 " Get all the digraphs, including default digraphs
2078 :echo digraph_getlist(1)
2079<
2080 Can also be used as a |method|: >
2081 GetNumber()->digraph_getlist()
2082<
2083 This function works only when compiled with the |+digraphs|
2084 feature. If this feature is disabled, this function will
2085 display an error message.
2086
2087
Bram Moolenaara2baa732022-02-04 16:09:54 +00002088digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002089 Add digraph {chars} to the list. {chars} must be a string
2090 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00002091 encoded character. *E1215*
2092 Be careful, composing characters are NOT ignored. This
2093 function is similar to |:digraphs| command, but useful to add
2094 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002095
2096 The function result is v:true if |digraph| is registered. If
2097 this fails an error message is given and v:false is returned.
2098
2099 If you want to define multiple digraphs at once, you can use
2100 |digraph_setlist()|.
2101
2102 Example: >
2103 call digraph_set(' ', 'あ')
2104<
2105 Can be used as a |method|: >
2106 GetString()->digraph_set('あ')
2107<
2108 This function works only when compiled with the |+digraphs|
2109 feature. If this feature is disabled, this function will
2110 display an error message.
2111
2112
2113digraph_setlist({digraphlist}) *digraph_setlist()*
2114 Similar to |digraph_set()| but this function can add multiple
2115 digraphs at once. {digraphlist} is a list composed of lists,
2116 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00002117 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002118 Example: >
2119 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
2120<
2121 It is similar to the following: >
2122 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
2123 call digraph_set(chars, digraph)
2124 endfor
2125< Except that the function returns after the first error,
2126 following digraphs will not be added.
2127
2128 Can be used as a |method|: >
2129 GetList()->digraph_setlist()
2130<
2131 This function works only when compiled with the |+digraphs|
2132 feature. If this feature is disabled, this function will
2133 display an error message.
2134
2135
2136echoraw({string}) *echoraw()*
2137 Output {string} as-is, including unprintable characters.
2138 This can be used to output a terminal code. For example, to
2139 disable modifyOtherKeys: >
2140 call echoraw(&t_TE)
2141< and to enable it again: >
2142 call echoraw(&t_TI)
2143< Use with care, you can mess up the terminal this way.
2144
2145
2146empty({expr}) *empty()*
2147 Return the Number 1 if {expr} is empty, zero otherwise.
2148 - A |List| or |Dictionary| is empty when it does not have any
2149 items.
2150 - A |String| is empty when its length is zero.
2151 - A |Number| and |Float| are empty when their value is zero.
2152 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
2153 - A |Job| is empty when it failed to start.
2154 - A |Channel| is empty when it is closed.
2155 - A |Blob| is empty when its length is zero.
2156
2157 For a long |List| this is much faster than comparing the
2158 length with zero.
2159
2160 Can also be used as a |method|: >
2161 mylist->empty()
2162
2163environ() *environ()*
2164 Return all of environment variables as dictionary. You can
2165 check if an environment variable exists like this: >
2166 :echo has_key(environ(), 'HOME')
2167< Note that the variable name may be CamelCase; to ignore case
2168 use this: >
2169 :echo index(keys(environ()), 'HOME', 0, 1) != -1
2170
2171escape({string}, {chars}) *escape()*
2172 Escape the characters in {chars} that occur in {string} with a
2173 backslash. Example: >
2174 :echo escape('c:\program files\vim', ' \')
2175< results in: >
2176 c:\\program\ files\\vim
2177< Also see |shellescape()| and |fnameescape()|.
2178
2179 Can also be used as a |method|: >
2180 GetText()->escape(' \')
2181<
2182 *eval()*
2183eval({string}) Evaluate {string} and return the result. Especially useful to
2184 turn the result of |string()| back into the original value.
2185 This works for Numbers, Floats, Strings, Blobs and composites
2186 of them. Also works for |Funcref|s that refer to existing
2187 functions.
2188
2189 Can also be used as a |method|: >
2190 argv->join()->eval()
2191
2192eventhandler() *eventhandler()*
2193 Returns 1 when inside an event handler. That is that Vim got
2194 interrupted while waiting for the user to type a character,
2195 e.g., when dropping a file on Vim. This means interactive
2196 commands cannot be used. Otherwise zero is returned.
2197
2198executable({expr}) *executable()*
2199 This function checks if an executable with the name {expr}
2200 exists. {expr} must be the name of the program without any
2201 arguments.
2202 executable() uses the value of $PATH and/or the normal
2203 searchpath for programs. *PATHEXT*
2204 On MS-Windows the ".exe", ".bat", etc. can optionally be
2205 included. Then the extensions in $PATHEXT are tried. Thus if
2206 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2207 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2208 by itself can be used in $PATHEXT to try using the name
2209 without an extension. When 'shell' looks like a Unix shell,
2210 then the name is also tried without adding an extension.
2211 On MS-Windows it only checks if the file exists and is not a
2212 directory, not if it's really executable.
2213 On MS-Windows an executable in the same directory as Vim is
Yasuhiro Matsumoto05cf63e2022-05-03 11:02:28 +01002214 normally found. Since this directory is added to $PATH it
2215 should also work to execute it |win32-PATH|. This can be
2216 disabled by setting the $NoDefaultCurrentDirectoryInExePath
2217 environment variable. *NoDefaultCurrentDirectoryInExePath*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002218 The result is a Number:
2219 1 exists
2220 0 does not exist
2221 -1 not implemented on this system
2222 |exepath()| can be used to get the full path of an executable.
2223
2224 Can also be used as a |method|: >
2225 GetCommand()->executable()
2226
2227execute({command} [, {silent}]) *execute()*
2228 Execute an Ex command or commands and return the output as a
2229 string.
2230 {command} can be a string or a List. In case of a List the
2231 lines are executed one by one.
2232 This is equivalent to: >
2233 redir => var
2234 {command}
2235 redir END
2236<
2237 The optional {silent} argument can have these values:
2238 "" no `:silent` used
2239 "silent" `:silent` used
2240 "silent!" `:silent!` used
2241 The default is "silent". Note that with "silent!", unlike
2242 `:redir`, error messages are dropped. When using an external
2243 command the screen may be messed up, use `system()` instead.
2244 *E930*
2245 It is not possible to use `:redir` anywhere in {command}.
2246
2247 To get a list of lines use |split()| on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002248 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002249
2250< To execute a command in another window than the current one
2251 use `win_execute()`.
2252
2253 When used recursively the output of the recursive call is not
2254 included in the output of the higher level call.
2255
2256 Can also be used as a |method|: >
2257 GetCommand()->execute()
2258
2259exepath({expr}) *exepath()*
2260 If {expr} is an executable and is either an absolute path, a
2261 relative path or found in $PATH, return the full path.
2262 Note that the current directory is used when {expr} starts
2263 with "./", which may be a problem for Vim: >
2264 echo exepath(v:progpath)
2265< If {expr} cannot be found in $PATH or is not executable then
2266 an empty string is returned.
2267
2268 Can also be used as a |method|: >
2269 GetCommand()->exepath()
2270<
2271 *exists()*
2272exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2273 zero otherwise.
2274
2275 Note: In a compiled |:def| function the evaluation is done at
2276 runtime. Use `exists_compiled()` to evaluate the expression
2277 at compile time.
2278
2279 For checking for a supported feature use |has()|.
2280 For checking if a file exists use |filereadable()|.
2281
2282 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002283 varname internal variable (see
2284 dict.key |internal-variables|). Also works
2285 list[i] for |curly-braces-names|, |Dictionary|
2286 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002287 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002288 Does not work for local variables in a
2289 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002290 Also works for a function in |Vim9|
2291 script, since it can be used as a
2292 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002293 Beware that evaluating an index may
2294 cause an error message for an invalid
2295 expression. E.g.: >
2296 :let l = [1, 2, 3]
2297 :echo exists("l[5]")
2298< 0 >
2299 :echo exists("l[xx]")
2300< E121: Undefined variable: xx
2301 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002302 &option-name Vim option (only checks if it exists,
2303 not if it really works)
2304 +option-name Vim option that works.
2305 $ENVNAME environment variable (could also be
2306 done by comparing with an empty
2307 string)
2308 *funcname built-in function (see |functions|)
2309 or user defined function (see
2310 |user-functions|) that is implemented.
2311 Also works for a variable that is a
2312 Funcref.
2313 ?funcname built-in function that could be
2314 implemented; to be used to check if
2315 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002316 :cmdname Ex command: built-in command, user
2317 command or command modifier |:command|.
2318 Returns:
2319 1 for match with start of a command
2320 2 full match with a command
2321 3 matches several user commands
2322 To check for a supported command
2323 always check the return value to be 2.
2324 :2match The |:2match| command.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01002325 :3match The |:3match| command (but you
2326 probably should not use it, it is
2327 reserved for internal usage)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002328 #event autocommand defined for this event
2329 #event#pattern autocommand defined for this event and
2330 pattern (the pattern is taken
2331 literally and compared to the
2332 autocommand patterns character by
2333 character)
2334 #group autocommand group exists
2335 #group#event autocommand defined for this group and
2336 event.
2337 #group#event#pattern
2338 autocommand defined for this group,
2339 event and pattern.
2340 ##event autocommand for this event is
2341 supported.
2342
2343 Examples: >
2344 exists("&shortname")
2345 exists("$HOSTNAME")
2346 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002347 exists("*s:MyFunc") " only for legacy script
2348 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002349 exists("bufcount")
2350 exists(":Make")
2351 exists("#CursorHold")
2352 exists("#BufReadPre#*.gz")
2353 exists("#filetypeindent")
2354 exists("#filetypeindent#FileType")
2355 exists("#filetypeindent#FileType#*")
2356 exists("##ColorScheme")
2357< There must be no space between the symbol (&/$/*/#) and the
2358 name.
2359 There must be no extra characters after the name, although in
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01002360 a few cases this is ignored. That may become stricter in the
2361 future, thus don't count on it!
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002362 Working example: >
2363 exists(":make")
2364< NOT working example: >
2365 exists(":make install")
2366
2367< Note that the argument must be a string, not the name of the
2368 variable itself. For example: >
2369 exists(bufcount)
2370< This doesn't check for existence of the "bufcount" variable,
2371 but gets the value of "bufcount", and checks if that exists.
2372
2373 Can also be used as a |method|: >
2374 Varname()->exists()
2375<
2376
2377exists_compiled({expr}) *exists_compiled()*
2378 Like `exists()` but evaluated at compile time. This is useful
2379 to skip a block where a function is used that would otherwise
2380 give an error: >
2381 if exists_compiled('*ThatFunction')
2382 ThatFunction('works')
2383 endif
2384< If `exists()` were used then a compilation error would be
2385 given if ThatFunction() is not defined.
2386
2387 {expr} must be a literal string. *E1232*
2388 Can only be used in a |:def| function. *E1233*
2389 This does not work to check for arguments or local variables.
2390
2391
2392exp({expr}) *exp()*
2393 Return the exponential of {expr} as a |Float| in the range
2394 [0, inf].
2395 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002396 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002397 Examples: >
2398 :echo exp(2)
2399< 7.389056 >
2400 :echo exp(-1)
2401< 0.367879
2402
2403 Can also be used as a |method|: >
2404 Compute()->exp()
2405<
2406 {only available when compiled with the |+float| feature}
2407
2408
2409expand({string} [, {nosuf} [, {list}]]) *expand()*
2410 Expand wildcards and the following special keywords in
2411 {string}. 'wildignorecase' applies.
2412
2413 If {list} is given and it is |TRUE|, a List will be returned.
2414 Otherwise the result is a String and when there are several
2415 matches, they are separated by <NL> characters. [Note: in
2416 version 5.0 a space was used, which caused problems when a
2417 file name contains a space]
2418
2419 If the expansion fails, the result is an empty string. A name
2420 for a non-existing file is not included, unless {string} does
2421 not start with '%', '#' or '<', see below.
2422
2423 When {string} starts with '%', '#' or '<', the expansion is
2424 done like for the |cmdline-special| variables with their
2425 associated modifiers. Here is a short overview:
2426
2427 % current file name
2428 # alternate file name
2429 #n alternate file name n
2430 <cfile> file name under the cursor
2431 <afile> autocmd file name
2432 <abuf> autocmd buffer number (as a String!)
2433 <amatch> autocmd matched name
2434 <cexpr> C expression under the cursor
2435 <sfile> sourced script file or function name
2436 <slnum> sourced script line number or function
2437 line number
2438 <sflnum> script file line number, also when in
2439 a function
2440 <SID> "<SNR>123_" where "123" is the
2441 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002442 <script> sourced script file, or script file
2443 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002444 <stack> call stack
2445 <cword> word under the cursor
2446 <cWORD> WORD under the cursor
2447 <client> the {clientid} of the last received
2448 message |server2client()|
2449 Modifiers:
2450 :p expand to full path
2451 :h head (last path component removed)
2452 :t tail (last path component only)
2453 :r root (one extension removed)
2454 :e extension only
2455
2456 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002457 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002458< Note that when expanding a string that starts with '%', '#' or
2459 '<', any following text is ignored. This does NOT work: >
2460 :let doesntwork = expand("%:h.bak")
2461< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002462 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002463< Also note that expanding "<cfile>" and others only returns the
2464 referenced file name without further expansion. If "<cfile>"
2465 is "~/.cshrc", you need to do another expand() to have the
2466 "~/" expanded into the path of the home directory: >
2467 :echo expand(expand("<cfile>"))
2468<
2469 There cannot be white space between the variables and the
2470 following modifier. The |fnamemodify()| function can be used
2471 to modify normal file names.
2472
2473 When using '%' or '#', and the current or alternate file name
2474 is not defined, an empty string is used. Using "%:p" in a
2475 buffer with no name, results in the current directory, with a
2476 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002477 When 'verbose' is set then expanding '%', '#' and <> items
2478 will result in an error message if the argument cannot be
2479 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002480
2481 When {string} does not start with '%', '#' or '<', it is
2482 expanded like a file name is expanded on the command line.
2483 'suffixes' and 'wildignore' are used, unless the optional
2484 {nosuf} argument is given and it is |TRUE|.
2485 Names for non-existing files are included. The "**" item can
2486 be used to search in a directory tree. For example, to find
2487 all "README" files in the current directory and below: >
2488 :echo expand("**/README")
2489<
2490 expand() can also be used to expand variables and environment
2491 variables that are only known in a shell. But this can be
2492 slow, because a shell may be used to do the expansion. See
2493 |expr-env-expand|.
2494 The expanded variable is still handled like a list of file
2495 names. When an environment variable cannot be expanded, it is
2496 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2497 "$FOOBAR".
2498
2499 See |glob()| for finding existing files. See |system()| for
2500 getting the raw output of an external command.
2501
2502 Can also be used as a |method|: >
2503 Getpattern()->expand()
2504
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002505expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002506 Expand special items in String {string} like what is done for
2507 an Ex command such as `:edit`. This expands special keywords,
2508 like with |expand()|, and environment variables, anywhere in
2509 {string}. "~user" and "~/path" are only expanded at the
2510 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002511
2512 The following items are supported in the {options} Dict
2513 argument:
2514 errmsg If set to TRUE, error messages are displayed
2515 if an error is encountered during expansion.
2516 By default, error messages are not displayed.
2517
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002518 Returns the expanded string. If an error is encountered
2519 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002520
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002521 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002522 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002523 make /path/runtime/doc/builtin.o
2524 :echo expandcmd('make %<.o', {'errmsg': v:true})
2525<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002526 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002527 GetCommand()->expandcmd()
2528<
2529extend({expr1}, {expr2} [, {expr3}]) *extend()*
2530 {expr1} and {expr2} must be both |Lists| or both
2531 |Dictionaries|.
2532
2533 If they are |Lists|: Append {expr2} to {expr1}.
2534 If {expr3} is given insert the items of {expr2} before the
2535 item with index {expr3} in {expr1}. When {expr3} is zero
2536 insert before the first item. When {expr3} is equal to
2537 len({expr1}) then {expr2} is appended.
2538 Examples: >
2539 :echo sort(extend(mylist, [7, 5]))
2540 :call extend(mylist, [2, 3], 1)
2541< When {expr1} is the same List as {expr2} then the number of
2542 items copied is equal to the original length of the List.
2543 E.g., when {expr3} is 1 you get N new copies of the first item
2544 (where N is the original length of the List).
2545 Use |add()| to concatenate one item to a list. To concatenate
2546 two lists into a new list use the + operator: >
2547 :let newlist = [1, 2, 3] + [4, 5]
2548<
2549 If they are |Dictionaries|:
2550 Add all entries from {expr2} to {expr1}.
2551 If a key exists in both {expr1} and {expr2} then {expr3} is
2552 used to decide what to do:
2553 {expr3} = "keep": keep the value of {expr1}
2554 {expr3} = "force": use the value of {expr2}
2555 {expr3} = "error": give an error message *E737*
2556 When {expr3} is omitted then "force" is assumed.
2557
2558 {expr1} is changed when {expr2} is not empty. If necessary
2559 make a copy of {expr1} first.
2560 {expr2} remains unchanged.
2561 When {expr1} is locked and {expr2} is not empty the operation
2562 fails.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002563 Returns {expr1}. Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002564
2565 Can also be used as a |method|: >
2566 mylist->extend(otherlist)
2567
2568
2569extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2570 Like |extend()| but instead of adding items to {expr1} a new
2571 List or Dictionary is created and returned. {expr1} remains
2572 unchanged. Items can still be changed by {expr2}, if you
2573 don't want that use |deepcopy()| first.
2574
2575
2576feedkeys({string} [, {mode}]) *feedkeys()*
2577 Characters in {string} are queued for processing as if they
2578 come from a mapping or were typed by the user.
2579
2580 By default the string is added to the end of the typeahead
2581 buffer, thus if a mapping is still being executed the
2582 characters come after them. Use the 'i' flag to insert before
2583 other characters, they will be executed next, before any
2584 characters from a mapping.
2585
2586 The function does not wait for processing of keys contained in
2587 {string}.
2588
2589 To include special keys into {string}, use double-quotes
2590 and "\..." notation |expr-quote|. For example,
2591 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2592 feedkeys('\<CR>') pushes 5 characters.
2593 A special code that might be useful is <Ignore>, it exits the
2594 wait for a character without doing anything. *<Ignore>*
2595
2596 {mode} is a String, which can contain these character flags:
2597 'm' Remap keys. This is default. If {mode} is absent,
2598 keys are remapped.
2599 'n' Do not remap keys.
2600 't' Handle keys as if typed; otherwise they are handled as
2601 if coming from a mapping. This matters for undo,
2602 opening folds, etc.
2603 'L' Lowlevel input. Only works for Unix or when using the
2604 GUI. Keys are used as if they were coming from the
2605 terminal. Other flags are not used. *E980*
2606 When a CTRL-C interrupts and 't' is included it sets
2607 the internal "got_int" flag.
2608 'i' Insert the string instead of appending (see above).
2609 'x' Execute commands until typeahead is empty. This is
2610 similar to using ":normal!". You can call feedkeys()
2611 several times without 'x' and then one time with 'x'
2612 (possibly with an empty {string}) to execute all the
2613 typeahead. Note that when Vim ends in Insert mode it
2614 will behave as if <Esc> is typed, to avoid getting
2615 stuck, waiting for a character to be typed before the
2616 script continues.
2617 Note that if you manage to call feedkeys() while
2618 executing commands, thus calling it recursively, then
2619 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002620 'c' Remove any script context when executing, so that
2621 legacy script syntax applies, "s:var" does not work,
Bram Moolenaard899e512022-05-07 21:54:03 +01002622 etc. Note that if the string being fed sets a script
Bram Moolenaarce001a32022-04-27 15:25:03 +01002623 context this still applies.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002624 '!' When used with 'x' will not end Insert mode. Can be
2625 used in a test when a timer is set to exit Insert mode
2626 a little later. Useful for testing CursorHoldI.
2627
2628 Return value is always 0.
2629
2630 Can also be used as a |method|: >
2631 GetInput()->feedkeys()
2632
2633filereadable({file}) *filereadable()*
2634 The result is a Number, which is |TRUE| when a file with the
2635 name {file} exists, and can be read. If {file} doesn't exist,
2636 or is a directory, the result is |FALSE|. {file} is any
2637 expression, which is used as a String.
2638 If you don't care about the file being readable you can use
2639 |glob()|.
2640 {file} is used as-is, you may want to expand wildcards first: >
2641 echo filereadable('~/.vimrc')
2642 0
2643 echo filereadable(expand('~/.vimrc'))
2644 1
2645
2646< Can also be used as a |method|: >
2647 GetName()->filereadable()
2648< *file_readable()*
2649 Obsolete name: file_readable().
2650
2651
2652filewritable({file}) *filewritable()*
2653 The result is a Number, which is 1 when a file with the
2654 name {file} exists, and can be written. If {file} doesn't
2655 exist, or is not writable, the result is 0. If {file} is a
2656 directory, and we can write to it, the result is 2.
2657
2658 Can also be used as a |method|: >
2659 GetName()->filewritable()
2660
2661
2662filter({expr1}, {expr2}) *filter()*
2663 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2664 For each item in {expr1} evaluate {expr2} and when the result
2665 is zero or false remove the item from the |List| or
2666 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002667 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002668
2669 {expr2} must be a |string| or |Funcref|.
2670
2671 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2672 of the current item. For a |Dictionary| |v:key| has the key
2673 of the current item and for a |List| |v:key| has the index of
2674 the current item. For a |Blob| |v:key| has the index of the
2675 current byte. For a |String| |v:key| has the index of the
2676 current character.
2677 Examples: >
2678 call filter(mylist, 'v:val !~ "OLD"')
2679< Removes the items where "OLD" appears. >
2680 call filter(mydict, 'v:key >= 8')
2681< Removes the items with a key below 8. >
2682 call filter(var, 0)
2683< Removes all the items, thus clears the |List| or |Dictionary|.
2684
2685 Note that {expr2} is the result of expression and is then
2686 used as an expression again. Often it is good to use a
2687 |literal-string| to avoid having to double backslashes.
2688
2689 If {expr2} is a |Funcref| it must take two arguments:
2690 1. the key or the index of the current item.
2691 2. the value of the current item.
2692 The function must return |TRUE| if the item should be kept.
2693 Example that keeps the odd items of a list: >
2694 func Odd(idx, val)
2695 return a:idx % 2 == 1
2696 endfunc
2697 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002698< It is shorter when using a |lambda|. In |Vim9| syntax: >
2699 call filter(myList, (idx, val) => idx * val <= 42)
2700< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002701 call filter(myList, {idx, val -> idx * val <= 42})
2702< If you do not use "val" you can leave it out: >
2703 call filter(myList, {idx -> idx % 2 == 1})
2704<
2705 In |Vim9| script the result must be true, false, zero or one.
2706 Other values will result in a type error.
2707
2708 For a |List| and a |Dictionary| the operation is done
2709 in-place. If you want it to remain unmodified make a copy
2710 first: >
2711 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2712
2713< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002714 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002715 When an error is encountered while evaluating {expr2} no
2716 further items in {expr1} are processed.
2717 When {expr2} is a Funcref errors inside a function are ignored,
2718 unless it was defined with the "abort" flag.
2719
2720 Can also be used as a |method|: >
2721 mylist->filter(expr2)
2722
2723finddir({name} [, {path} [, {count}]]) *finddir()*
2724 Find directory {name} in {path}. Supports both downwards and
2725 upwards recursive directory searches. See |file-searching|
2726 for the syntax of {path}.
2727
2728 Returns the path of the first found match. When the found
2729 directory is below the current directory a relative path is
2730 returned. Otherwise a full path is returned.
2731 If {path} is omitted or empty then 'path' is used.
2732
2733 If the optional {count} is given, find {count}'s occurrence of
2734 {name} in {path} instead of the first one.
2735 When {count} is negative return all the matches in a |List|.
2736
Bram Moolenaar016188f2022-06-06 20:52:59 +01002737 Returns an empty string if the directory is not found.
2738
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002739 This is quite similar to the ex-command `:find`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002740
2741 Can also be used as a |method|: >
2742 GetName()->finddir()
2743
2744findfile({name} [, {path} [, {count}]]) *findfile()*
2745 Just like |finddir()|, but find a file instead of a directory.
2746 Uses 'suffixesadd'.
2747 Example: >
2748 :echo findfile("tags.vim", ".;")
2749< Searches from the directory of the current file upwards until
2750 it finds the file "tags.vim".
2751
2752 Can also be used as a |method|: >
2753 GetName()->findfile()
2754
2755flatten({list} [, {maxdepth}]) *flatten()*
2756 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2757 the result is a |List| without nesting, as if {maxdepth} is
2758 a very large number.
2759 The {list} is changed in place, use |flattennew()| if you do
2760 not want that.
2761 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002762 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002763 *E900*
2764 {maxdepth} means how deep in nested lists changes are made.
2765 {list} is not modified when {maxdepth} is 0.
2766 {maxdepth} must be positive number.
2767
2768 If there is an error the number zero is returned.
2769
2770 Example: >
2771 :echo flatten([1, [2, [3, 4]], 5])
2772< [1, 2, 3, 4, 5] >
2773 :echo flatten([1, [2, [3, 4]], 5], 1)
2774< [1, 2, [3, 4], 5]
2775
2776 Can also be used as a |method|: >
2777 mylist->flatten()
2778<
2779flattennew({list} [, {maxdepth}]) *flattennew()*
2780 Like |flatten()| but first make a copy of {list}.
2781
2782
2783float2nr({expr}) *float2nr()*
2784 Convert {expr} to a Number by omitting the part after the
2785 decimal point.
2786 {expr} must evaluate to a |Float| or a Number.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002787 Returns 0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002788 When the value of {expr} is out of range for a |Number| the
2789 result is truncated to 0x7fffffff or -0x7fffffff (or when
2790 64-bit Number support is enabled, 0x7fffffffffffffff or
2791 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2792 64-bit Number support is enabled, -0x8000000000000000).
2793 Examples: >
2794 echo float2nr(3.95)
2795< 3 >
2796 echo float2nr(-23.45)
2797< -23 >
2798 echo float2nr(1.0e100)
2799< 2147483647 (or 9223372036854775807) >
2800 echo float2nr(-1.0e150)
2801< -2147483647 (or -9223372036854775807) >
2802 echo float2nr(1.0e-100)
2803< 0
2804
2805 Can also be used as a |method|: >
2806 Compute()->float2nr()
2807<
2808 {only available when compiled with the |+float| feature}
2809
2810
2811floor({expr}) *floor()*
2812 Return the largest integral value less than or equal to
2813 {expr} as a |Float| (round down).
2814 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002815 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002816 Examples: >
2817 echo floor(1.856)
2818< 1.0 >
2819 echo floor(-5.456)
2820< -6.0 >
2821 echo floor(4.0)
2822< 4.0
2823
2824 Can also be used as a |method|: >
2825 Compute()->floor()
2826<
2827 {only available when compiled with the |+float| feature}
2828
2829
2830fmod({expr1}, {expr2}) *fmod()*
2831 Return the remainder of {expr1} / {expr2}, even if the
2832 division is not representable. Returns {expr1} - i * {expr2}
2833 for some integer i such that if {expr2} is non-zero, the
2834 result has the same sign as {expr1} and magnitude less than
2835 the magnitude of {expr2}. If {expr2} is zero, the value
2836 returned is zero. The value returned is a |Float|.
2837 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002838 Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
2839 |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002840 Examples: >
2841 :echo fmod(12.33, 1.22)
2842< 0.13 >
2843 :echo fmod(-12.33, 1.22)
2844< -0.13
2845
2846 Can also be used as a |method|: >
2847 Compute()->fmod(1.22)
2848<
2849 {only available when compiled with |+float| feature}
2850
2851
2852fnameescape({string}) *fnameescape()*
2853 Escape {string} for use as file name command argument. All
2854 characters that have a special meaning, such as '%' and '|'
2855 are escaped with a backslash.
2856 For most systems the characters escaped are
2857 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2858 appears in a filename, it depends on the value of 'isfname'.
2859 A leading '+' and '>' is also escaped (special after |:edit|
2860 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaar016188f2022-06-06 20:52:59 +01002861 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002862 Example: >
2863 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002864 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002865< results in executing: >
2866 edit \+some\ str\%nge\|name
2867<
2868 Can also be used as a |method|: >
2869 GetName()->fnameescape()
2870
2871fnamemodify({fname}, {mods}) *fnamemodify()*
2872 Modify file name {fname} according to {mods}. {mods} is a
2873 string of characters like it is used for file names on the
2874 command line. See |filename-modifiers|.
2875 Example: >
2876 :echo fnamemodify("main.c", ":p:h")
2877< results in: >
Bram Moolenaard799daa2022-06-20 11:17:32 +01002878 /home/user/vim/vim/src
Bram Moolenaar016188f2022-06-06 20:52:59 +01002879< If {mods} is empty or an unsupported modifier is used then
2880 {fname} is returned.
Bram Moolenaar5ed11532022-07-06 13:18:11 +01002881 When {fname} is empty then with {mods} ":h" returns ".", so
2882 that `:cd` can be used with it. This is different from
2883 expand('%:h') without a buffer name, which returns an empty
2884 string.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002885 Note: Environment variables don't work in {fname}, use
2886 |expand()| first then.
2887
2888 Can also be used as a |method|: >
2889 GetName()->fnamemodify(':p:h')
2890
2891foldclosed({lnum}) *foldclosed()*
2892 The result is a Number. If the line {lnum} is in a closed
2893 fold, the result is the number of the first line in that fold.
2894 If the line {lnum} is not in a closed fold, -1 is returned.
2895 {lnum} is used like with |getline()|. Thus "." is the current
2896 line, "'m" mark m, etc.
2897
2898 Can also be used as a |method|: >
2899 GetLnum()->foldclosed()
2900
2901foldclosedend({lnum}) *foldclosedend()*
2902 The result is a Number. If the line {lnum} is in a closed
2903 fold, the result is the number of the last line in that fold.
2904 If the line {lnum} is not in a closed fold, -1 is returned.
2905 {lnum} is used like with |getline()|. Thus "." is the current
2906 line, "'m" mark m, etc.
2907
2908 Can also be used as a |method|: >
2909 GetLnum()->foldclosedend()
2910
2911foldlevel({lnum}) *foldlevel()*
2912 The result is a Number, which is the foldlevel of line {lnum}
2913 in the current buffer. For nested folds the deepest level is
2914 returned. If there is no fold at line {lnum}, zero is
2915 returned. It doesn't matter if the folds are open or closed.
2916 When used while updating folds (from 'foldexpr') -1 is
2917 returned for lines where folds are still to be updated and the
2918 foldlevel is unknown. As a special case the level of the
2919 previous line is usually available.
2920 {lnum} is used like with |getline()|. Thus "." is the current
2921 line, "'m" mark m, etc.
2922
2923 Can also be used as a |method|: >
2924 GetLnum()->foldlevel()
2925<
2926 *foldtext()*
2927foldtext() Returns a String, to be displayed for a closed fold. This is
2928 the default function used for the 'foldtext' option and should
2929 only be called from evaluating 'foldtext'. It uses the
2930 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2931 The returned string looks like this: >
2932 +-- 45 lines: abcdef
2933< The number of leading dashes depends on the foldlevel. The
2934 "45" is the number of lines in the fold. "abcdef" is the text
2935 in the first non-blank line of the fold. Leading white space,
2936 "//" or "/*" and the text from the 'foldmarker' and
2937 'commentstring' options is removed.
2938 When used to draw the actual foldtext, the rest of the line
2939 will be filled with the fold char from the 'fillchars'
2940 setting.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002941 Returns an empty string when there is no fold.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002942 {not available when compiled without the |+folding| feature}
2943
2944foldtextresult({lnum}) *foldtextresult()*
2945 Returns the text that is displayed for the closed fold at line
2946 {lnum}. Evaluates 'foldtext' in the appropriate context.
2947 When there is no closed fold at {lnum} an empty string is
2948 returned.
2949 {lnum} is used like with |getline()|. Thus "." is the current
2950 line, "'m" mark m, etc.
2951 Useful when exporting folded text, e.g., to HTML.
2952 {not available when compiled without the |+folding| feature}
2953
2954
2955 Can also be used as a |method|: >
2956 GetLnum()->foldtextresult()
2957<
2958 *foreground()*
2959foreground() Move the Vim window to the foreground. Useful when sent from
2960 a client to a Vim server. |remote_send()|
2961 On Win32 systems this might not work, the OS does not always
2962 allow a window to bring itself to the foreground. Use
2963 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002964 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002965 Win32 console version}
2966
2967fullcommand({name}) *fullcommand()*
2968 Get the full command name from a short abbreviated command
2969 name; see |20.2| for details on command abbreviations.
2970
2971 The string argument {name} may start with a `:` and can
2972 include a [range], these are skipped and not returned.
2973 Returns an empty string if a command doesn't exist or if it's
2974 ambiguous (for user-defined commands).
2975
2976 For example `fullcommand('s')`, `fullcommand('sub')`,
2977 `fullcommand(':%substitute')` all return "substitute".
2978
2979 Can also be used as a |method|: >
2980 GetName()->fullcommand()
2981<
2982 *funcref()*
2983funcref({name} [, {arglist}] [, {dict}])
2984 Just like |function()|, but the returned Funcref will lookup
2985 the function by reference, not by name. This matters when the
2986 function {name} is redefined later.
2987
2988 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002989 It only works for an autoloaded function if it has already
2990 been loaded (to avoid mistakenly loading the autoload script
2991 when only intending to use the function name, use |function()|
2992 instead). {name} cannot be a builtin function.
Bram Moolenaar016188f2022-06-06 20:52:59 +01002993 Returns 0 on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002994
2995 Can also be used as a |method|: >
2996 GetFuncname()->funcref([arg])
2997<
2998 *function()* *partial* *E700* *E922* *E923*
2999function({name} [, {arglist}] [, {dict}])
3000 Return a |Funcref| variable that refers to function {name}.
3001 {name} can be the name of a user defined function or an
3002 internal function.
3003
3004 {name} can also be a Funcref or a partial. When it is a
3005 partial the dict stored in it will be used and the {dict}
3006 argument is not allowed. E.g.: >
3007 let FuncWithArg = function(dict.Func, [arg])
3008 let Broken = function(dict.Func, [arg], dict)
3009<
3010 When using the Funcref the function will be found by {name},
3011 also when it was redefined later. Use |funcref()| to keep the
3012 same function.
3013
3014 When {arglist} or {dict} is present this creates a partial.
3015 That means the argument list and/or the dictionary is stored in
3016 the Funcref and will be used when the Funcref is called.
3017
3018 The arguments are passed to the function in front of other
3019 arguments, but after any argument from |method|. Example: >
3020 func Callback(arg1, arg2, name)
3021 ...
3022 let Partial = function('Callback', ['one', 'two'])
3023 ...
3024 call Partial('name')
3025< Invokes the function as with: >
3026 call Callback('one', 'two', 'name')
3027
3028< With a |method|: >
3029 func Callback(one, two, three)
3030 ...
3031 let Partial = function('Callback', ['two'])
3032 ...
3033 eval 'one'->Partial('three')
3034< Invokes the function as with: >
3035 call Callback('one', 'two', 'three')
3036
3037< The function() call can be nested to add more arguments to the
3038 Funcref. The extra arguments are appended to the list of
3039 arguments. Example: >
3040 func Callback(arg1, arg2, name)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003041 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003042 let Func = function('Callback', ['one'])
3043 let Func2 = function(Func, ['two'])
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003044 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003045 call Func2('name')
3046< Invokes the function as with: >
3047 call Callback('one', 'two', 'name')
3048
3049< The Dictionary is only useful when calling a "dict" function.
3050 In that case the {dict} is passed in as "self". Example: >
3051 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003052 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003053 endfunction
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003054 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003055 let context = {"name": "example"}
3056 let Func = function('Callback', context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003057 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003058 call Func() " will echo: called for example
3059< The use of function() is not needed when there are no extra
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003060 arguments, these two are equivalent, if Callback() is defined
3061 as context.Callback(): >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003062 let Func = function('Callback', context)
3063 let Func = context.Callback
3064
3065< The argument list and the Dictionary can be combined: >
3066 function Callback(arg1, count) dict
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003067 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003068 let context = {"name": "example"}
3069 let Func = function('Callback', ['one'], context)
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01003070 "...
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003071 call Func(500)
3072< Invokes the function as with: >
3073 call context.Callback('one', 500)
3074<
Bram Moolenaar016188f2022-06-06 20:52:59 +01003075 Returns 0 on error.
3076
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003077 Can also be used as a |method|: >
3078 GetFuncname()->function([arg])
3079
3080
3081garbagecollect([{atexit}]) *garbagecollect()*
3082 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3083 that have circular references.
3084
3085 There is hardly ever a need to invoke this function, as it is
3086 automatically done when Vim runs out of memory or is waiting
3087 for the user to press a key after 'updatetime'. Items without
3088 circular references are always freed when they become unused.
3089 This is useful if you have deleted a very big |List| and/or
3090 |Dictionary| with circular references in a script that runs
3091 for a long time.
3092
3093 When the optional {atexit} argument is one, garbage
3094 collection will also be done when exiting Vim, if it wasn't
3095 done before. This is useful when checking for memory leaks.
3096
3097 The garbage collection is not done immediately but only when
3098 it's safe to perform. This is when waiting for the user to
3099 type a character. To force garbage collection immediately use
3100 |test_garbagecollect_now()|.
3101
3102get({list}, {idx} [, {default}]) *get()*
3103 Get item {idx} from |List| {list}. When this item is not
3104 available return {default}. Return zero when {default} is
3105 omitted.
3106 Preferably used as a |method|: >
3107 mylist->get(idx)
3108get({blob}, {idx} [, {default}])
3109 Get byte {idx} from |Blob| {blob}. When this byte is not
3110 available return {default}. Return -1 when {default} is
3111 omitted.
3112 Preferably used as a |method|: >
3113 myblob->get(idx)
3114get({dict}, {key} [, {default}])
3115 Get item with key {key} from |Dictionary| {dict}. When this
3116 item is not available return {default}. Return zero when
3117 {default} is omitted. Useful example: >
3118 let val = get(g:, 'var_name', 'default')
3119< This gets the value of g:var_name if it exists, and uses
3120 'default' when it does not exist.
3121 Preferably used as a |method|: >
3122 mydict->get(key)
3123get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003124 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003125 {what} are:
3126 "name" The function name
3127 "func" The function
3128 "dict" The dictionary
3129 "args" The list with arguments
Bram Moolenaar016188f2022-06-06 20:52:59 +01003130 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003131 Preferably used as a |method|: >
3132 myfunc->get(what)
3133<
3134 *getbufinfo()*
3135getbufinfo([{buf}])
3136getbufinfo([{dict}])
3137 Get information about buffers as a List of Dictionaries.
3138
3139 Without an argument information about all the buffers is
3140 returned.
3141
3142 When the argument is a |Dictionary| only the buffers matching
3143 the specified criteria are returned. The following keys can
3144 be specified in {dict}:
3145 buflisted include only listed buffers.
3146 bufloaded include only loaded buffers.
3147 bufmodified include only modified buffers.
3148
3149 Otherwise, {buf} specifies a particular buffer to return
3150 information for. For the use of {buf}, see |bufname()|
3151 above. If the buffer is found the returned List has one item.
3152 Otherwise the result is an empty list.
3153
3154 Each returned List item is a dictionary with the following
3155 entries:
3156 bufnr Buffer number.
3157 changed TRUE if the buffer is modified.
3158 changedtick Number of changes made to the buffer.
3159 hidden TRUE if the buffer is hidden.
3160 lastused Timestamp in seconds, like
3161 |localtime()|, when the buffer was
3162 last used.
3163 {only with the |+viminfo| feature}
3164 listed TRUE if the buffer is listed.
3165 lnum Line number used for the buffer when
3166 opened in the current window.
3167 Only valid if the buffer has been
3168 displayed in the window in the past.
3169 If you want the line number of the
3170 last known cursor position in a given
3171 window, use |line()|: >
3172 :echo line('.', {winid})
3173<
3174 linecount Number of lines in the buffer (only
3175 valid when loaded)
3176 loaded TRUE if the buffer is loaded.
3177 name Full path to the file in the buffer.
3178 signs List of signs placed in the buffer.
3179 Each list item is a dictionary with
3180 the following fields:
3181 id sign identifier
3182 lnum line number
3183 name sign name
3184 variables A reference to the dictionary with
3185 buffer-local variables.
3186 windows List of |window-ID|s that display this
3187 buffer
3188 popups List of popup |window-ID|s that
3189 display this buffer
3190
3191 Examples: >
3192 for buf in getbufinfo()
3193 echo buf.name
3194 endfor
3195 for buf in getbufinfo({'buflisted':1})
3196 if buf.changed
3197 ....
3198 endif
3199 endfor
3200<
3201 To get buffer-local options use: >
3202 getbufvar({bufnr}, '&option_name')
3203<
3204 Can also be used as a |method|: >
3205 GetBufnr()->getbufinfo()
3206<
3207
3208 *getbufline()*
3209getbufline({buf}, {lnum} [, {end}])
3210 Return a |List| with the lines starting from {lnum} to {end}
3211 (inclusive) in the buffer {buf}. If {end} is omitted, a
3212 |List| with only the line {lnum} is returned.
3213
3214 For the use of {buf}, see |bufname()| above.
3215
3216 For {lnum} and {end} "$" can be used for the last line of the
3217 buffer. Otherwise a number must be used.
3218
3219 When {lnum} is smaller than 1 or bigger than the number of
3220 lines in the buffer, an empty |List| is returned.
3221
3222 When {end} is greater than the number of lines in the buffer,
3223 it is treated as {end} is set to the number of lines in the
3224 buffer. When {end} is before {lnum} an empty |List| is
3225 returned.
3226
3227 This function works only for loaded buffers. For unloaded and
3228 non-existing buffers, an empty |List| is returned.
3229
3230 Example: >
3231 :let lines = getbufline(bufnr("myfile"), 1, "$")
3232
3233< Can also be used as a |method|: >
3234 GetBufnr()->getbufline(lnum)
3235
3236getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3237 The result is the value of option or local buffer variable
3238 {varname} in buffer {buf}. Note that the name without "b:"
3239 must be used.
3240 The {varname} argument is a string.
3241 When {varname} is empty returns a |Dictionary| with all the
3242 buffer-local variables.
3243 When {varname} is equal to "&" returns a |Dictionary| with all
3244 the buffer-local options.
3245 Otherwise, when {varname} starts with "&" returns the value of
3246 a buffer-local option.
3247 This also works for a global or buffer-local option, but it
3248 doesn't work for a global variable, window-local variable or
3249 window-local option.
3250 For the use of {buf}, see |bufname()| above.
3251 When the buffer or variable doesn't exist {def} or an empty
3252 string is returned, there is no error message.
3253 Examples: >
3254 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003255 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003256
3257< Can also be used as a |method|: >
3258 GetBufnr()->getbufvar(varname)
3259<
3260getchangelist([{buf}]) *getchangelist()*
3261 Returns the |changelist| for the buffer {buf}. For the use
3262 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3263 exist, an empty list is returned.
3264
3265 The returned list contains two entries: a list with the change
3266 locations and the current position in the list. Each
3267 entry in the change list is a dictionary with the following
3268 entries:
3269 col column number
3270 coladd column offset for 'virtualedit'
3271 lnum line number
3272 If buffer {buf} is the current buffer, then the current
3273 position refers to the position in the list. For other
3274 buffers, it is set to the length of the list.
3275
3276 Can also be used as a |method|: >
3277 GetBufnr()->getchangelist()
3278
3279getchar([expr]) *getchar()*
3280 Get a single character from the user or input stream.
3281 If [expr] is omitted, wait until a character is available.
3282 If [expr] is 0, only get a character when one is available.
3283 Return zero otherwise.
3284 If [expr] is 1, only check if a character is available, it is
3285 not consumed. Return zero if no character available.
3286 If you prefer always getting a string use |getcharstr()|.
3287
3288 Without [expr] and when [expr] is 0 a whole character or
3289 special key is returned. If it is a single character, the
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01003290 result is a Number. Use |nr2char()| to convert it to a String.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003291 Otherwise a String is returned with the encoded character.
3292 For a special key it's a String with a sequence of bytes
3293 starting with 0x80 (decimal: 128). This is the same value as
3294 the String "\<Key>", e.g., "\<Left>". The returned value is
3295 also a String when a modifier (shift, control, alt) was used
3296 that is not included in the character.
3297
3298 When [expr] is 0 and Esc is typed, there will be a short delay
3299 while Vim waits to see if this is the start of an escape
3300 sequence.
3301
3302 When [expr] is 1 only the first byte is returned. For a
3303 one-byte character it is the character itself as a number.
3304 Use nr2char() to convert it to a String.
3305
3306 Use getcharmod() to obtain any additional modifiers.
3307
3308 When the user clicks a mouse button, the mouse event will be
3309 returned. The position can then be found in |v:mouse_col|,
3310 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3311 |getmousepos()| can also be used. Mouse move events will be
3312 ignored.
3313 This example positions the mouse as it would normally happen: >
3314 let c = getchar()
3315 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003316 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003317 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003318 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003319 endif
3320<
3321 When using bracketed paste only the first character is
3322 returned, the rest of the pasted text is dropped.
3323 |xterm-bracketed-paste|.
3324
3325 There is no prompt, you will somehow have to make clear to the
3326 user that a character has to be typed. The screen is not
3327 redrawn, e.g. when resizing the window. When using a popup
3328 window it should work better with a |popup-filter|.
3329
3330 There is no mapping for the character.
3331 Key codes are replaced, thus when the user presses the <Del>
3332 key you get the code for the <Del> key, not the raw character
3333 sequence. Examples: >
3334 getchar() == "\<Del>"
3335 getchar() == "\<S-Left>"
3336< This example redefines "f" to ignore case: >
3337 :nmap f :call FindChar()<CR>
3338 :function FindChar()
3339 : let c = nr2char(getchar())
3340 : while col('.') < col('$') - 1
3341 : normal l
3342 : if getline('.')[col('.') - 1] ==? c
3343 : break
3344 : endif
3345 : endwhile
3346 :endfunction
3347<
3348 You may also receive synthetic characters, such as
3349 |<CursorHold>|. Often you will want to ignore this and get
3350 another character: >
3351 :function GetKey()
3352 : let c = getchar()
3353 : while c == "\<CursorHold>"
3354 : let c = getchar()
3355 : endwhile
3356 : return c
3357 :endfunction
3358
3359getcharmod() *getcharmod()*
3360 The result is a Number which is the state of the modifiers for
3361 the last obtained character with getchar() or in another way.
3362 These values are added together:
3363 2 shift
3364 4 control
3365 8 alt (meta)
3366 16 meta (when it's different from ALT)
3367 32 mouse double click
3368 64 mouse triple click
3369 96 mouse quadruple click (== 32 + 64)
3370 128 command (Macintosh only)
3371 Only the modifiers that have not been included in the
3372 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar016188f2022-06-06 20:52:59 +01003373 without a modifier. Returns 0 if no modifiers are used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003374
3375 *getcharpos()*
3376getcharpos({expr})
3377 Get the position for String {expr}. Same as |getpos()| but the
3378 column number in the returned List is a character index
3379 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003380 If |getpos()| returns a very large column number, equal to
3381 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003382 of the last character.
3383
3384 Example:
3385 With the cursor on '세' in line 5 with text "여보세요": >
3386 getcharpos('.') returns [0, 5, 3, 0]
3387 getpos('.') returns [0, 5, 7, 0]
3388<
3389 Can also be used as a |method|: >
3390 GetMark()->getcharpos()
3391
3392getcharsearch() *getcharsearch()*
3393 Return the current character search information as a {dict}
3394 with the following entries:
3395
3396 char character previously used for a character
3397 search (|t|, |f|, |T|, or |F|); empty string
3398 if no character search has been performed
3399 forward direction of character search; 1 for forward,
3400 0 for backward
3401 until type of character search; 1 for a |t| or |T|
3402 character search, 0 for an |f| or |F|
3403 character search
3404
3405 This can be useful to always have |;| and |,| search
3406 forward/backward regardless of the direction of the previous
3407 character search: >
3408 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3409 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3410< Also see |setcharsearch()|.
3411
3412
3413getcharstr([expr]) *getcharstr()*
3414 Get a single character from the user or input stream as a
3415 string.
3416 If [expr] is omitted, wait until a character is available.
3417 If [expr] is 0 or false, only get a character when one is
3418 available. Return an empty string otherwise.
3419 If [expr] is 1 or true, only check if a character is
3420 available, it is not consumed. Return an empty string
3421 if no character is available.
3422 Otherwise this works like |getchar()|, except that a number
3423 result is converted to a string.
3424
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003425getcmdcompltype() *getcmdcompltype()*
3426 Return the type of the current command-line completion.
3427 Only works when the command line is being edited, thus
3428 requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
Bram Moolenaar921bde82022-05-09 19:50:35 +01003429 See |:command-completion| for the return string.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003430 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3431 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003432 Returns an empty string when completion is not defined.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003433
3434getcmdline() *getcmdline()*
3435 Return the current command-line. Only works when the command
3436 line is being edited, thus requires use of |c_CTRL-\_e| or
3437 |c_CTRL-R_=|.
3438 Example: >
3439 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003440< Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
3441 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003442 Returns an empty string when entering a password or using
3443 |inputsecret()|.
3444
3445getcmdpos() *getcmdpos()*
3446 Return the position of the cursor in the command line as a
3447 byte count. The first column is 1.
3448 Only works when editing the command line, thus requires use of
3449 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3450 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003451 Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
3452 |setcmdline()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003453
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003454getcmdscreenpos() *getcmdscreenpos()*
3455 Return the screen position of the cursor in the command line
3456 as a byte count. The first column is 1.
3457 Instead of |getcmdpos()|, it adds the prompt position.
3458 Only works when editing the command line, thus requires use of
3459 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3460 Returns 0 otherwise.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01003461 Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
3462 |setcmdline()|.
Shougo Matsushita79d599b2022-05-07 12:48:29 +01003463
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003464getcmdtype() *getcmdtype()*
3465 Return the current command-line type. Possible return values
3466 are:
3467 : normal Ex command
3468 > debug mode command |debug-mode|
3469 / forward search command
3470 ? backward search command
3471 @ |input()| command
3472 - |:insert| or |:append| command
3473 = |i_CTRL-R_=|
3474 Only works when editing the command line, thus requires use of
3475 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3476 Returns an empty string otherwise.
3477 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3478
3479getcmdwintype() *getcmdwintype()*
3480 Return the current |command-line-window| type. Possible return
3481 values are the same as |getcmdtype()|. Returns an empty string
3482 when not in the command-line window.
3483
3484getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3485 Return a list of command-line completion matches. The String
3486 {type} argument specifies what for. The following completion
3487 types are supported:
3488
3489 arglist file names in argument list
3490 augroup autocmd groups
3491 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003492 behave |:behave| suboptions
3493 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003494 color color schemes
3495 command Ex command
3496 cmdline |cmdline-completion| result
3497 compiler compilers
3498 cscope |:cscope| suboptions
3499 diff_buffer |:diffget| and |:diffput| completion
3500 dir directory names
3501 environment environment variable names
3502 event autocommand events
3503 expression Vim expression
3504 file file and directory names
3505 file_in_path file and directory names in |'path'|
3506 filetype filetype names |'filetype'|
3507 function function name
3508 help help subjects
3509 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003510 history |:history| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003511 locale locale names (as output of locale -a)
3512 mapclear buffer argument
3513 mapping mapping name
3514 menu menus
3515 messages |:messages| suboptions
3516 option options
3517 packadd optional package |pack-add| names
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003518 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003519 shellcmd Shell command
3520 sign |:sign| suboptions
3521 syntax syntax file names |'syntax'|
3522 syntime |:syntime| suboptions
3523 tag tags
3524 tag_listfiles tags, file names
3525 user user names
3526 var user variables
3527
3528 If {pat} is an empty string, then all the matches are
3529 returned. Otherwise only items matching {pat} are returned.
3530 See |wildcards| for the use of special characters in {pat}.
3531
3532 If the optional {filtered} flag is set to 1, then 'wildignore'
3533 is applied to filter the results. Otherwise all the matches
3534 are returned. The 'wildignorecase' option always applies.
3535
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003536 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3537 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003538 regular expression matching is used. Thus this function
3539 follows the user preference, what happens on the command line.
3540 If you do not want this you can make 'wildoptions' empty
3541 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003542
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003543 If {type} is "cmdline", then the |cmdline-completion| result is
3544 returned. For example, to complete the possible values after
3545 a ":call" command: >
3546 echo getcompletion('call ', 'cmdline')
3547<
3548 If there are no matches, an empty list is returned. An
3549 invalid value for {type} produces an error.
3550
3551 Can also be used as a |method|: >
3552 GetPattern()->getcompletion('color')
3553<
3554 *getcurpos()*
3555getcurpos([{winid}])
3556 Get the position of the cursor. This is like getpos('.'), but
3557 includes an extra "curswant" item in the list:
3558 [0, lnum, col, off, curswant] ~
3559 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003560 cursor vertically. After |$| command it will be a very large
3561 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003562 |getpos()|.
3563 The first "bufnum" item is always zero. The byte position of
3564 the cursor is returned in 'col'. To get the character
3565 position, use |getcursorcharpos()|.
3566
3567 The optional {winid} argument can specify the window. It can
3568 be the window number or the |window-ID|. The last known
3569 cursor position is returned, this may be invalid for the
3570 current value of the buffer if it is not the current window.
3571 If {winid} is invalid a list with zeroes is returned.
3572
3573 This can be used to save and restore the cursor position: >
3574 let save_cursor = getcurpos()
3575 MoveTheCursorAround
3576 call setpos('.', save_cursor)
3577< Note that this only works within the window. See
3578 |winrestview()| for restoring more state.
3579
3580 Can also be used as a |method|: >
3581 GetWinid()->getcurpos()
3582<
3583 *getcursorcharpos()*
3584getcursorcharpos([{winid}])
3585 Same as |getcurpos()| but the column number in the returned
3586 List is a character index instead of a byte index.
3587
3588 Example:
3589 With the cursor on '보' in line 3 with text "여보세요": >
3590 getcursorcharpos() returns [0, 3, 2, 0, 3]
3591 getcurpos() returns [0, 3, 4, 0, 3]
3592<
3593 Can also be used as a |method|: >
3594 GetWinid()->getcursorcharpos()
3595
3596< *getcwd()*
3597getcwd([{winnr} [, {tabnr}]])
3598 The result is a String, which is the name of the current
3599 working directory. 'autochdir' is ignored.
3600
3601 With {winnr} return the local current directory of this window
3602 in the current tab page. {winnr} can be the window number or
3603 the |window-ID|.
3604 If {winnr} is -1 return the name of the global working
3605 directory. See also |haslocaldir()|.
3606
3607 With {winnr} and {tabnr} return the local current directory of
3608 the window in the specified tab page. If {winnr} is -1 return
3609 the working directory of the tabpage.
3610 If {winnr} is zero use the current window, if {tabnr} is zero
3611 use the current tabpage.
3612 Without any arguments, return the actual working directory of
3613 the current window.
3614 Return an empty string if the arguments are invalid.
3615
3616 Examples: >
3617 " Get the working directory of the current window
3618 :echo getcwd()
3619 :echo getcwd(0)
3620 :echo getcwd(0, 0)
3621 " Get the working directory of window 3 in tabpage 2
3622 :echo getcwd(3, 2)
3623 " Get the global working directory
3624 :echo getcwd(-1)
3625 " Get the working directory of tabpage 3
3626 :echo getcwd(-1, 3)
3627 " Get the working directory of current tabpage
3628 :echo getcwd(-1, 0)
3629
3630< Can also be used as a |method|: >
3631 GetWinnr()->getcwd()
3632
3633getenv({name}) *getenv()*
3634 Return the value of environment variable {name}. The {name}
3635 argument is a string, without a leading '$'. Example: >
3636 myHome = getenv('HOME')
3637
3638< When the variable does not exist |v:null| is returned. That
3639 is different from a variable set to an empty string, although
3640 some systems interpret the empty value as the variable being
3641 deleted. See also |expr-env|.
3642
3643 Can also be used as a |method|: >
3644 GetVarname()->getenv()
3645
3646getfontname([{name}]) *getfontname()*
3647 Without an argument returns the name of the normal font being
3648 used. Like what is used for the Normal highlight group
3649 |hl-Normal|.
3650 With an argument a check is done whether String {name} is a
3651 valid font name. If not then an empty string is returned.
3652 Otherwise the actual font name is returned, or {name} if the
3653 GUI does not support obtaining the real name.
3654 Only works when the GUI is running, thus not in your vimrc or
3655 gvimrc file. Use the |GUIEnter| autocommand to use this
3656 function just after the GUI has started.
3657 Note that the GTK GUI accepts any font name, thus checking for
3658 a valid name does not work.
3659
3660getfperm({fname}) *getfperm()*
3661 The result is a String, which is the read, write, and execute
3662 permissions of the given file {fname}.
3663 If {fname} does not exist or its directory cannot be read, an
3664 empty string is returned.
3665 The result is of the form "rwxrwxrwx", where each group of
3666 "rwx" flags represent, in turn, the permissions of the owner
3667 of the file, the group the file belongs to, and other users.
3668 If a user does not have a given permission the flag for this
3669 is replaced with the string "-". Examples: >
3670 :echo getfperm("/etc/passwd")
3671 :echo getfperm(expand("~/.vimrc"))
3672< This will hopefully (from a security point of view) display
3673 the string "rw-r--r--" or even "rw-------".
3674
3675 Can also be used as a |method|: >
3676 GetFilename()->getfperm()
3677<
3678 For setting permissions use |setfperm()|.
3679
3680getfsize({fname}) *getfsize()*
3681 The result is a Number, which is the size in bytes of the
3682 given file {fname}.
3683 If {fname} is a directory, 0 is returned.
3684 If the file {fname} can't be found, -1 is returned.
3685 If the size of {fname} is too big to fit in a Number then -2
3686 is returned.
3687
3688 Can also be used as a |method|: >
3689 GetFilename()->getfsize()
3690
3691getftime({fname}) *getftime()*
3692 The result is a Number, which is the last modification time of
3693 the given file {fname}. The value is measured as seconds
3694 since 1st Jan 1970, and may be passed to strftime(). See also
3695 |localtime()| and |strftime()|.
3696 If the file {fname} can't be found -1 is returned.
3697
3698 Can also be used as a |method|: >
3699 GetFilename()->getftime()
3700
3701getftype({fname}) *getftype()*
3702 The result is a String, which is a description of the kind of
3703 file of the given file {fname}.
3704 If {fname} does not exist an empty string is returned.
3705 Here is a table over different kinds of files and their
3706 results:
3707 Normal file "file"
3708 Directory "dir"
3709 Symbolic link "link"
3710 Block device "bdev"
3711 Character device "cdev"
3712 Socket "socket"
3713 FIFO "fifo"
3714 All other "other"
3715 Example: >
3716 getftype("/home")
3717< Note that a type such as "link" will only be returned on
3718 systems that support it. On some systems only "dir" and
3719 "file" are returned. On MS-Windows a symbolic link to a
3720 directory returns "dir" instead of "link".
3721
3722 Can also be used as a |method|: >
3723 GetFilename()->getftype()
3724
3725getimstatus() *getimstatus()*
3726 The result is a Number, which is |TRUE| when the IME status is
Bram Moolenaar016188f2022-06-06 20:52:59 +01003727 active and |FALSE| otherwise.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003728 See 'imstatusfunc'.
3729
3730getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3731 Returns the |jumplist| for the specified window.
3732
3733 Without arguments use the current window.
3734 With {winnr} only use this window in the current tab page.
3735 {winnr} can also be a |window-ID|.
3736 With {winnr} and {tabnr} use the window in the specified tab
Bram Moolenaar016188f2022-06-06 20:52:59 +01003737 page. If {winnr} or {tabnr} is invalid, an empty list is
3738 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003739
3740 The returned list contains two entries: a list with the jump
3741 locations and the last used jump position number in the list.
3742 Each entry in the jump location list is a dictionary with
3743 the following entries:
3744 bufnr buffer number
3745 col column number
3746 coladd column offset for 'virtualedit'
3747 filename filename if available
3748 lnum line number
3749
3750 Can also be used as a |method|: >
3751 GetWinnr()->getjumplist()
3752
3753< *getline()*
3754getline({lnum} [, {end}])
3755 Without {end} the result is a String, which is line {lnum}
3756 from the current buffer. Example: >
3757 getline(1)
3758< When {lnum} is a String that doesn't start with a
3759 digit, |line()| is called to translate the String into a Number.
3760 To get the line under the cursor: >
3761 getline(".")
3762< When {lnum} is a number smaller than 1 or bigger than the
3763 number of lines in the buffer, an empty string is returned.
3764
3765 When {end} is given the result is a |List| where each item is
3766 a line from the current buffer in the range {lnum} to {end},
3767 including line {end}.
3768 {end} is used in the same way as {lnum}.
3769 Non-existing lines are silently omitted.
3770 When {end} is before {lnum} an empty |List| is returned.
3771 Example: >
3772 :let start = line('.')
3773 :let end = search("^$") - 1
3774 :let lines = getline(start, end)
3775
3776< Can also be used as a |method|: >
3777 ComputeLnum()->getline()
3778
3779< To get lines from another buffer see |getbufline()|
3780
3781getloclist({nr} [, {what}]) *getloclist()*
3782 Returns a |List| with all the entries in the location list for
3783 window {nr}. {nr} can be the window number or the |window-ID|.
3784 When {nr} is zero the current window is used.
3785
3786 For a location list window, the displayed location list is
3787 returned. For an invalid window number {nr}, an empty list is
3788 returned. Otherwise, same as |getqflist()|.
3789
3790 If the optional {what} dictionary argument is supplied, then
3791 returns the items listed in {what} as a dictionary. Refer to
3792 |getqflist()| for the supported items in {what}.
3793
3794 In addition to the items supported by |getqflist()| in {what},
3795 the following item is supported by |getloclist()|:
3796
3797 filewinid id of the window used to display files
3798 from the location list. This field is
3799 applicable only when called from a
3800 location list window. See
3801 |location-list-file-window| for more
3802 details.
3803
3804 Returns a |Dictionary| with default values if there is no
3805 location list for the window {nr}.
3806 Returns an empty Dictionary if window {nr} does not exist.
3807
3808 Examples (See also |getqflist-examples|): >
3809 :echo getloclist(3, {'all': 0})
3810 :echo getloclist(5, {'filewinid': 0})
3811
3812
3813getmarklist([{buf}]) *getmarklist()*
3814 Without the {buf} argument returns a |List| with information
3815 about all the global marks. |mark|
3816
3817 If the optional {buf} argument is specified, returns the
3818 local marks defined in buffer {buf}. For the use of {buf},
Bram Moolenaar016188f2022-06-06 20:52:59 +01003819 see |bufname()|. If {buf} is invalid, an empty list is
3820 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003821
3822 Each item in the returned List is a |Dict| with the following:
3823 mark name of the mark prefixed by "'"
3824 pos a |List| with the position of the mark:
3825 [bufnum, lnum, col, off]
3826 Refer to |getpos()| for more information.
3827 file file name
3828
3829 Refer to |getpos()| for getting information about a specific
3830 mark.
3831
3832 Can also be used as a |method|: >
3833 GetBufnr()->getmarklist()
3834
3835getmatches([{win}]) *getmatches()*
3836 Returns a |List| with all matches previously defined for the
3837 current window by |matchadd()| and the |:match| commands.
3838 |getmatches()| is useful in combination with |setmatches()|,
3839 as |setmatches()| can restore a list of matches saved by
3840 |getmatches()|.
3841 If {win} is specified, use the window with this number or
Bram Moolenaar016188f2022-06-06 20:52:59 +01003842 window ID instead of the current window. If {win} is invalid,
3843 an empty list is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003844 Example: >
3845 :echo getmatches()
3846< [{'group': 'MyGroup1', 'pattern': 'TODO',
3847 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3848 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3849 :let m = getmatches()
3850 :call clearmatches()
3851 :echo getmatches()
3852< [] >
3853 :call setmatches(m)
3854 :echo getmatches()
3855< [{'group': 'MyGroup1', 'pattern': 'TODO',
3856 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3857 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3858 :unlet m
3859<
3860getmousepos() *getmousepos()*
3861 Returns a |Dictionary| with the last known position of the
3862 mouse. This can be used in a mapping for a mouse click or in
3863 a filter of a popup window. The items are:
3864 screenrow screen row
3865 screencol screen column
3866 winid Window ID of the click
3867 winrow row inside "winid"
3868 wincol column inside "winid"
3869 line text line inside "winid"
3870 column text column inside "winid"
3871 All numbers are 1-based.
3872
3873 If not over a window, e.g. when in the command line, then only
3874 "screenrow" and "screencol" are valid, the others are zero.
3875
3876 When on the status line below a window or the vertical
3877 separator right of a window, the "line" and "column" values
3878 are zero.
3879
3880 When the position is after the text then "column" is the
3881 length of the text in bytes plus one.
3882
3883 If the mouse is over a popup window then that window is used.
3884
3885 When using |getchar()| the Vim variables |v:mouse_lnum|,
3886 |v:mouse_col| and |v:mouse_winid| also provide these values.
3887
3888 *getpid()*
3889getpid() Return a Number which is the process ID of the Vim process.
3890 On Unix and MS-Windows this is a unique number, until Vim
3891 exits.
3892
3893 *getpos()*
3894getpos({expr}) Get the position for String {expr}. For possible values of
3895 {expr} see |line()|. For getting the cursor position see
3896 |getcurpos()|.
3897 The result is a |List| with four numbers:
3898 [bufnum, lnum, col, off]
3899 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3900 is the buffer number of the mark.
3901 "lnum" and "col" are the position in the buffer. The first
3902 column is 1.
3903 The "off" number is zero, unless 'virtualedit' is used. Then
3904 it is the offset in screen columns from the start of the
3905 character. E.g., a position within a <Tab> or after the last
3906 character.
3907 Note that for '< and '> Visual mode matters: when it is "V"
3908 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003909 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003910 The column number in the returned List is the byte position
3911 within the line. To get the character position in the line,
3912 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003913 A very large column number equal to |v:maxcol| can be returned,
3914 in which case it means "after the end of the line".
Bram Moolenaar016188f2022-06-06 20:52:59 +01003915 If {expr} is invalid, returns a list with all zeros.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003916 This can be used to save and restore the position of a mark: >
3917 let save_a_mark = getpos("'a")
3918 ...
3919 call setpos("'a", save_a_mark)
3920< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3921
3922 Can also be used as a |method|: >
3923 GetMark()->getpos()
3924
3925getqflist([{what}]) *getqflist()*
3926 Returns a |List| with all the current quickfix errors. Each
3927 list item is a dictionary with these entries:
3928 bufnr number of buffer that has the file name, use
3929 bufname() to get the name
3930 module module name
3931 lnum line number in the buffer (first line is 1)
3932 end_lnum
3933 end of line number if the item is multiline
3934 col column number (first column is 1)
3935 end_col end of column number if the item has range
3936 vcol |TRUE|: "col" is visual column
3937 |FALSE|: "col" is byte index
3938 nr error number
3939 pattern search pattern used to locate the error
3940 text description of the error
3941 type type of the error, 'E', '1', etc.
3942 valid |TRUE|: recognized error message
3943
3944 When there is no error list or it's empty, an empty list is
3945 returned. Quickfix list entries with a non-existing buffer
3946 number are returned with "bufnr" set to zero (Note: some
3947 functions accept buffer number zero for the alternate buffer,
3948 you may need to explicitly check for zero).
3949
3950 Useful application: Find pattern matches in multiple files and
3951 do something with them: >
3952 :vimgrep /theword/jg *.c
3953 :for d in getqflist()
3954 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3955 :endfor
3956<
3957 If the optional {what} dictionary argument is supplied, then
3958 returns only the items listed in {what} as a dictionary. The
3959 following string items are supported in {what}:
3960 changedtick get the total number of changes made
3961 to the list |quickfix-changedtick|
3962 context get the |quickfix-context|
3963 efm errorformat to use when parsing "lines". If
3964 not present, then the 'errorformat' option
3965 value is used.
3966 id get information for the quickfix list with
3967 |quickfix-ID|; zero means the id for the
3968 current list or the list specified by "nr"
3969 idx get information for the quickfix entry at this
3970 index in the list specified by 'id' or 'nr'.
3971 If set to zero, then uses the current entry.
3972 See |quickfix-index|
3973 items quickfix list entries
3974 lines parse a list of lines using 'efm' and return
3975 the resulting entries. Only a |List| type is
3976 accepted. The current quickfix list is not
3977 modified. See |quickfix-parse|.
3978 nr get information for this quickfix list; zero
3979 means the current quickfix list and "$" means
3980 the last quickfix list
3981 qfbufnr number of the buffer displayed in the quickfix
3982 window. Returns 0 if the quickfix buffer is
3983 not present. See |quickfix-buffer|.
3984 size number of entries in the quickfix list
3985 title get the list title |quickfix-title|
3986 winid get the quickfix |window-ID|
3987 all all of the above quickfix properties
3988 Non-string items in {what} are ignored. To get the value of a
3989 particular item, set it to zero.
3990 If "nr" is not present then the current quickfix list is used.
3991 If both "nr" and a non-zero "id" are specified, then the list
3992 specified by "id" is used.
3993 To get the number of lists in the quickfix stack, set "nr" to
3994 "$" in {what}. The "nr" value in the returned dictionary
3995 contains the quickfix stack size.
3996 When "lines" is specified, all the other items except "efm"
3997 are ignored. The returned dictionary contains the entry
3998 "items" with the list of entries.
3999
4000 The returned dictionary contains the following entries:
4001 changedtick total number of changes made to the
4002 list |quickfix-changedtick|
4003 context quickfix list context. See |quickfix-context|
4004 If not present, set to "".
4005 id quickfix list ID |quickfix-ID|. If not
4006 present, set to 0.
4007 idx index of the quickfix entry in the list. If not
4008 present, set to 0.
4009 items quickfix list entries. If not present, set to
4010 an empty list.
4011 nr quickfix list number. If not present, set to 0
4012 qfbufnr number of the buffer displayed in the quickfix
4013 window. If not present, set to 0.
4014 size number of entries in the quickfix list. If not
4015 present, set to 0.
4016 title quickfix list title text. If not present, set
4017 to "".
4018 winid quickfix |window-ID|. If not present, set to 0
4019
4020 Examples (See also |getqflist-examples|): >
4021 :echo getqflist({'all': 1})
4022 :echo getqflist({'nr': 2, 'title': 1})
4023 :echo getqflist({'lines' : ["F1:10:L10"]})
4024<
4025getreg([{regname} [, 1 [, {list}]]]) *getreg()*
4026 The result is a String, which is the contents of register
4027 {regname}. Example: >
4028 :let cliptext = getreg('*')
4029< When register {regname} was not set the result is an empty
4030 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004031 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004032
4033 getreg('=') returns the last evaluated value of the expression
4034 register. (For use in maps.)
4035 getreg('=', 1) returns the expression itself, so that it can
4036 be restored with |setreg()|. For other registers the extra
4037 argument is ignored, thus you can always give it.
4038
4039 If {list} is present and |TRUE|, the result type is changed
4040 to |List|. Each list item is one text line. Use it if you care
4041 about zero bytes possibly present inside register: without
4042 third argument both NLs and zero bytes are represented as NLs
4043 (see |NL-used-for-Nul|).
4044 When the register was not set an empty list is returned.
4045
4046 If {regname} is "", the unnamed register '"' is used.
4047 If {regname} is not specified, |v:register| is used.
4048 In |Vim9-script| {regname} must be one character.
4049
4050 Can also be used as a |method|: >
4051 GetRegname()->getreg()
4052
4053getreginfo([{regname}]) *getreginfo()*
4054 Returns detailed information about register {regname} as a
4055 Dictionary with the following entries:
4056 regcontents List of lines contained in register
4057 {regname}, like
4058 |getreg|({regname}, 1, 1).
4059 regtype the type of register {regname}, as in
4060 |getregtype()|.
4061 isunnamed Boolean flag, v:true if this register
4062 is currently pointed to by the unnamed
4063 register.
4064 points_to for the unnamed register, gives the
4065 single letter name of the register
4066 currently pointed to (see |quotequote|).
4067 For example, after deleting a line
4068 with `dd`, this field will be "1",
4069 which is the register that got the
4070 deleted text.
4071
4072 The {regname} argument is a string. If {regname} is invalid
4073 or not set, an empty Dictionary will be returned.
4074 If {regname} is "" or "@", the unnamed register '"' is used.
4075 If {regname} is not specified, |v:register| is used.
4076 The returned Dictionary can be passed to |setreg()|.
4077 In |Vim9-script| {regname} must be one character.
4078
4079 Can also be used as a |method|: >
4080 GetRegname()->getreginfo()
4081
4082getregtype([{regname}]) *getregtype()*
4083 The result is a String, which is type of register {regname}.
4084 The value will be one of:
4085 "v" for |characterwise| text
4086 "V" for |linewise| text
4087 "<CTRL-V>{width}" for |blockwise-visual| text
4088 "" for an empty or unknown register
4089 <CTRL-V> is one character with value 0x16.
4090 The {regname} argument is a string. If {regname} is "", the
4091 unnamed register '"' is used. If {regname} is not specified,
4092 |v:register| is used.
4093 In |Vim9-script| {regname} must be one character.
4094
4095 Can also be used as a |method|: >
4096 GetRegname()->getregtype()
4097
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004098getscriptinfo([{opts}) *getscriptinfo()*
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004099 Returns a |List| with information about all the sourced Vim
Bram Moolenaar753885b2022-08-24 16:30:36 +01004100 scripts in the order they were sourced, like what
4101 `:scriptnames` shows.
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004102
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004103 The optional Dict argument {opts} supports the following
4104 optional items:
4105 name Script name match pattern. If specified,
4106 and "sid" is not specified, information about
4107 scripts with name that match the pattern
4108 "name" are returned.
4109 sid Script ID |<SID>|. If specified, only
4110 information about the script with ID "sid" is
4111 returned and "name" is ignored.
4112
Yegappan Lakshmananf768c3d2022-08-22 13:15:13 +01004113 Each item in the returned List is a |Dict| with the following
4114 items:
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004115 autoload Set to TRUE for a script that was used with
Bram Moolenaar753885b2022-08-24 16:30:36 +01004116 `import autoload` but was not actually sourced
4117 yet (see |import-autoload|).
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004118 functions List of script-local function names defined in
4119 the script. Present only when a particular
4120 script is specified using the "sid" item in
4121 {opts}.
4122 name Vim script file name.
4123 sid Script ID |<SID>|.
4124 sourced Script ID of the actually sourced script that
Bram Moolenaarfd999452022-08-24 18:30:14 +01004125 this script name links to, if any, otherwise
4126 zero
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004127 variables A dictionary with the script-local variables.
4128 Present only when the a particular script is
4129 specified using the "sid" item in {opts}.
4130 Note that this is a copy, the value of
4131 script-local variables cannot be changed using
4132 this dictionary.
4133 version Vimscript version (|scriptversion|)
Yegappan Lakshmanan520f6ef2022-08-25 17:40:40 +01004134
Yegappan Lakshmanan2f892d82022-08-28 18:52:10 +01004135 Examples: >
4136 :echo getscriptinfo({'name': 'myscript'})
4137 :echo getscriptinfo({'sid': 15}).variables
4138<
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004139gettabinfo([{tabnr}]) *gettabinfo()*
4140 If {tabnr} is not specified, then information about all the
4141 tab pages is returned as a |List|. Each List item is a
4142 |Dictionary|. Otherwise, {tabnr} specifies the tab page
4143 number and information about that one is returned. If the tab
4144 page does not exist an empty List is returned.
4145
4146 Each List item is a |Dictionary| with the following entries:
4147 tabnr tab page number.
4148 variables a reference to the dictionary with
4149 tabpage-local variables
4150 windows List of |window-ID|s in the tab page.
4151
4152 Can also be used as a |method|: >
4153 GetTabnr()->gettabinfo()
4154
4155gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
4156 Get the value of a tab-local variable {varname} in tab page
4157 {tabnr}. |t:var|
4158 Tabs are numbered starting with one.
4159 The {varname} argument is a string. When {varname} is empty a
4160 dictionary with all tab-local variables is returned.
4161 Note that the name without "t:" must be used.
4162 When the tab or variable doesn't exist {def} or an empty
4163 string is returned, there is no error message.
4164
4165 Can also be used as a |method|: >
4166 GetTabnr()->gettabvar(varname)
4167
4168gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
4169 Get the value of window-local variable {varname} in window
4170 {winnr} in tab page {tabnr}.
4171 The {varname} argument is a string. When {varname} is empty a
4172 dictionary with all window-local variables is returned.
4173 When {varname} is equal to "&" get the values of all
4174 window-local options in a |Dictionary|.
4175 Otherwise, when {varname} starts with "&" get the value of a
4176 window-local option.
4177 Note that {varname} must be the name without "w:".
4178 Tabs are numbered starting with one. For the current tabpage
4179 use |getwinvar()|.
4180 {winnr} can be the window number or the |window-ID|.
4181 When {winnr} is zero the current window is used.
4182 This also works for a global option, buffer-local option and
4183 window-local option, but it doesn't work for a global variable
4184 or buffer-local variable.
4185 When the tab, window or variable doesn't exist {def} or an
4186 empty string is returned, there is no error message.
4187 Examples: >
4188 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004189 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004190<
4191 To obtain all window-local variables use: >
4192 gettabwinvar({tabnr}, {winnr}, '&')
4193
4194< Can also be used as a |method|: >
4195 GetTabnr()->gettabwinvar(winnr, varname)
4196
4197gettagstack([{winnr}]) *gettagstack()*
4198 The result is a Dict, which is the tag stack of window {winnr}.
4199 {winnr} can be the window number or the |window-ID|.
4200 When {winnr} is not specified, the current window is used.
4201 When window {winnr} doesn't exist, an empty Dict is returned.
4202
4203 The returned dictionary contains the following entries:
4204 curidx Current index in the stack. When at
4205 top of the stack, set to (length + 1).
4206 Index of bottom of the stack is 1.
4207 items List of items in the stack. Each item
4208 is a dictionary containing the
4209 entries described below.
4210 length Number of entries in the stack.
4211
4212 Each item in the stack is a dictionary with the following
4213 entries:
4214 bufnr buffer number of the current jump
4215 from cursor position before the tag jump.
4216 See |getpos()| for the format of the
4217 returned list.
4218 matchnr current matching tag number. Used when
4219 multiple matching tags are found for a
4220 name.
4221 tagname name of the tag
4222
4223 See |tagstack| for more information about the tag stack.
4224
4225 Can also be used as a |method|: >
4226 GetWinnr()->gettagstack()
4227
4228
4229gettext({text}) *gettext()*
4230 Translate String {text} if possible.
4231 This is mainly for use in the distributed Vim scripts. When
4232 generating message translations the {text} is extracted by
4233 xgettext, the translator can add the translated message in the
4234 .po file and Vim will lookup the translation when gettext() is
4235 called.
4236 For {text} double quoted strings are preferred, because
4237 xgettext does not understand escaping in single quoted
4238 strings.
4239
4240
4241getwininfo([{winid}]) *getwininfo()*
4242 Returns information about windows as a |List| with Dictionaries.
4243
4244 If {winid} is given Information about the window with that ID
4245 is returned, as a |List| with one item. If the window does not
4246 exist the result is an empty list.
4247
4248 Without {winid} information about all the windows in all the
4249 tab pages is returned.
4250
4251 Each List item is a |Dictionary| with the following entries:
4252 botline last complete displayed buffer line
4253 bufnr number of buffer in the window
4254 height window height (excluding winbar)
4255 loclist 1 if showing a location list
4256 {only with the +quickfix feature}
4257 quickfix 1 if quickfix or location list window
4258 {only with the +quickfix feature}
4259 terminal 1 if a terminal window
4260 {only with the +terminal feature}
4261 tabnr tab page number
4262 topline first displayed buffer line
4263 variables a reference to the dictionary with
4264 window-local variables
4265 width window width
4266 winbar 1 if the window has a toolbar, 0
4267 otherwise
4268 wincol leftmost screen column of the window;
4269 "col" from |win_screenpos()|
4270 textoff number of columns occupied by any
4271 'foldcolumn', 'signcolumn' and line
4272 number in front of the text
4273 winid |window-ID|
4274 winnr window number
4275 winrow topmost screen line of the window;
4276 "row" from |win_screenpos()|
4277
4278 Can also be used as a |method|: >
4279 GetWinnr()->getwininfo()
4280
4281getwinpos([{timeout}]) *getwinpos()*
4282 The result is a |List| with two numbers, the result of
4283 |getwinposx()| and |getwinposy()| combined:
4284 [x-pos, y-pos]
4285 {timeout} can be used to specify how long to wait in msec for
4286 a response from the terminal. When omitted 100 msec is used.
4287 Use a longer time for a remote terminal.
4288 When using a value less than 10 and no response is received
4289 within that time, a previously reported position is returned,
4290 if available. This can be used to poll for the position and
4291 do some work in the meantime: >
4292 while 1
4293 let res = getwinpos(1)
4294 if res[0] >= 0
4295 break
4296 endif
4297 " Do some work here
4298 endwhile
4299<
4300
4301 Can also be used as a |method|: >
4302 GetTimeout()->getwinpos()
4303<
4304 *getwinposx()*
4305getwinposx() The result is a Number, which is the X coordinate in pixels of
4306 the left hand side of the GUI Vim window. Also works for an
4307 xterm (uses a timeout of 100 msec).
4308 The result will be -1 if the information is not available.
4309 The value can be used with `:winpos`.
4310
4311 *getwinposy()*
4312getwinposy() The result is a Number, which is the Y coordinate in pixels of
4313 the top of the GUI Vim window. Also works for an xterm (uses
4314 a timeout of 100 msec).
4315 The result will be -1 if the information is not available.
4316 The value can be used with `:winpos`.
4317
4318getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4319 Like |gettabwinvar()| for the current tabpage.
4320 Examples: >
4321 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004322 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004323
4324< Can also be used as a |method|: >
4325 GetWinnr()->getwinvar(varname)
4326<
4327glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4328 Expand the file wildcards in {expr}. See |wildcards| for the
4329 use of special characters.
4330
4331 Unless the optional {nosuf} argument is given and is |TRUE|,
4332 the 'suffixes' and 'wildignore' options apply: Names matching
4333 one of the patterns in 'wildignore' will be skipped and
4334 'suffixes' affect the ordering of matches.
4335 'wildignorecase' always applies.
4336
4337 When {list} is present and it is |TRUE| the result is a |List|
4338 with all matching files. The advantage of using a List is,
4339 you also get filenames containing newlines correctly.
4340 Otherwise the result is a String and when there are several
4341 matches, they are separated by <NL> characters.
4342
4343 If the expansion fails, the result is an empty String or List.
4344
4345 You can also use |readdir()| if you need to do complicated
4346 things, such as limiting the number of matches.
4347
4348 A name for a non-existing file is not included. A symbolic
4349 link is only included if it points to an existing file.
4350 However, when the {alllinks} argument is present and it is
4351 |TRUE| then all symbolic links are included.
4352
4353 For most systems backticks can be used to get files names from
4354 any external command. Example: >
4355 :let tagfiles = glob("`find . -name tags -print`")
4356 :let &tags = substitute(tagfiles, "\n", ",", "g")
4357< The result of the program inside the backticks should be one
4358 item per line. Spaces inside an item are allowed.
4359
4360 See |expand()| for expanding special Vim variables. See
4361 |system()| for getting the raw output of an external command.
4362
4363 Can also be used as a |method|: >
4364 GetExpr()->glob()
4365
4366glob2regpat({string}) *glob2regpat()*
4367 Convert a file pattern, as used by glob(), into a search
4368 pattern. The result can be used to match with a string that
4369 is a file name. E.g. >
4370 if filename =~ glob2regpat('Make*.mak')
4371< This is equivalent to: >
4372 if filename =~ '^Make.*\.mak$'
4373< When {string} is an empty string the result is "^$", match an
4374 empty string.
4375 Note that the result depends on the system. On MS-Windows
4376 a backslash usually means a path separator.
4377
4378 Can also be used as a |method|: >
4379 GetExpr()->glob2regpat()
4380< *globpath()*
4381globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4382 Perform glob() for String {expr} on all directories in {path}
4383 and concatenate the results. Example: >
4384 :echo globpath(&rtp, "syntax/c.vim")
4385<
4386 {path} is a comma-separated list of directory names. Each
4387 directory name is prepended to {expr} and expanded like with
4388 |glob()|. A path separator is inserted when needed.
4389 To add a comma inside a directory name escape it with a
4390 backslash. Note that on MS-Windows a directory may have a
4391 trailing backslash, remove it if you put a comma after it.
4392 If the expansion fails for one of the directories, there is no
4393 error message.
4394
4395 Unless the optional {nosuf} argument is given and is |TRUE|,
4396 the 'suffixes' and 'wildignore' options apply: Names matching
4397 one of the patterns in 'wildignore' will be skipped and
4398 'suffixes' affect the ordering of matches.
4399
4400 When {list} is present and it is |TRUE| the result is a |List|
4401 with all matching files. The advantage of using a List is, you
4402 also get filenames containing newlines correctly. Otherwise
4403 the result is a String and when there are several matches,
4404 they are separated by <NL> characters. Example: >
4405 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4406<
4407 {alllinks} is used as with |glob()|.
4408
4409 The "**" item can be used to search in a directory tree.
4410 For example, to find all "README.txt" files in the directories
4411 in 'runtimepath' and below: >
4412 :echo globpath(&rtp, "**/README.txt")
4413< Upwards search and limiting the depth of "**" is not
4414 supported, thus using 'path' will not always work properly.
4415
4416 Can also be used as a |method|, the base is passed as the
4417 second argument: >
4418 GetExpr()->globpath(&rtp)
4419<
4420 *has()*
4421has({feature} [, {check}])
4422 When {check} is omitted or is zero: The result is a Number,
4423 which is 1 if the feature {feature} is supported, zero
4424 otherwise. The {feature} argument is a string, case is
4425 ignored. See |feature-list| below.
4426
4427 When {check} is present and not zero: The result is a Number,
4428 which is 1 if the feature {feature} could ever be supported,
4429 zero otherwise. This is useful to check for a typo in
4430 {feature} and to detect dead code. Keep in mind that an older
4431 Vim version will not know about a feature added later and
4432 features that have been abandoned will not be known by the
4433 current Vim version.
4434
4435 Also see |exists()| and |exists_compiled()|.
4436
4437 Note that to skip code that has a syntax error when the
4438 feature is not available, Vim may skip the rest of the line
4439 and miss a following `endif`. Therefore put the `endif` on a
4440 separate line: >
4441 if has('feature')
4442 let x = this->breaks->without->the->feature
4443 endif
4444< If the `endif` would be moved to the second line as "| endif" it
4445 would not be found.
4446
4447
4448has_key({dict}, {key}) *has_key()*
4449 The result is a Number, which is TRUE if |Dictionary| {dict}
Bram Moolenaare8008642022-08-19 17:15:35 +01004450 has an entry with key {key}. FALSE otherwise.
4451 The {key} argument is a string. In |Vim9| script a number is
4452 also accepted (and converted to a string) but no other types.
4453 In legacy script the usual automatic conversion to string is
4454 done.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004455
4456 Can also be used as a |method|: >
4457 mydict->has_key(key)
4458
4459haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4460 The result is a Number:
4461 1 when the window has set a local directory via |:lcd|
4462 2 when the tab-page has set a local directory via |:tcd|
4463 0 otherwise.
4464
4465 Without arguments use the current window.
4466 With {winnr} use this window in the current tab page.
4467 With {winnr} and {tabnr} use the window in the specified tab
4468 page.
4469 {winnr} can be the window number or the |window-ID|.
4470 If {winnr} is -1 it is ignored and only the tabpage is used.
4471 Return 0 if the arguments are invalid.
4472 Examples: >
4473 if haslocaldir() == 1
4474 " window local directory case
4475 elseif haslocaldir() == 2
4476 " tab-local directory case
4477 else
4478 " global directory case
4479 endif
4480
4481 " current window
4482 :echo haslocaldir()
4483 :echo haslocaldir(0)
4484 :echo haslocaldir(0, 0)
4485 " window n in current tab page
4486 :echo haslocaldir(n)
4487 :echo haslocaldir(n, 0)
4488 " window n in tab page m
4489 :echo haslocaldir(n, m)
4490 " tab page m
4491 :echo haslocaldir(-1, m)
4492<
4493 Can also be used as a |method|: >
4494 GetWinnr()->haslocaldir()
4495
4496hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4497 The result is a Number, which is TRUE if there is a mapping
4498 that contains {what} in somewhere in the rhs (what it is
4499 mapped to) and this mapping exists in one of the modes
4500 indicated by {mode}.
4501 The arguments {what} and {mode} are strings.
4502 When {abbr} is there and it is |TRUE| use abbreviations
4503 instead of mappings. Don't forget to specify Insert and/or
4504 Command-line mode.
4505 Both the global mappings and the mappings local to the current
4506 buffer are checked for a match.
4507 If no matching mapping is found FALSE is returned.
4508 The following characters are recognized in {mode}:
4509 n Normal mode
4510 v Visual and Select mode
4511 x Visual mode
4512 s Select mode
4513 o Operator-pending mode
4514 i Insert mode
4515 l Language-Argument ("r", "f", "t", etc.)
4516 c Command-line mode
4517 When {mode} is omitted, "nvo" is used.
4518
4519 This function is useful to check if a mapping already exists
4520 to a function in a Vim script. Example: >
4521 :if !hasmapto('\ABCdoit')
4522 : map <Leader>d \ABCdoit
4523 :endif
4524< This installs the mapping to "\ABCdoit" only if there isn't
4525 already a mapping to "\ABCdoit".
4526
4527 Can also be used as a |method|: >
4528 GetRHS()->hasmapto()
4529
4530histadd({history}, {item}) *histadd()*
4531 Add the String {item} to the history {history} which can be
4532 one of: *hist-names*
4533 "cmd" or ":" command line history
4534 "search" or "/" search pattern history
4535 "expr" or "=" typed expression history
4536 "input" or "@" input line history
4537 "debug" or ">" debug command history
4538 empty the current or last used history
4539 The {history} string does not need to be the whole name, one
4540 character is sufficient.
4541 If {item} does already exist in the history, it will be
4542 shifted to become the newest entry.
4543 The result is a Number: TRUE if the operation was successful,
4544 otherwise FALSE is returned.
4545
4546 Example: >
4547 :call histadd("input", strftime("%Y %b %d"))
4548 :let date=input("Enter date: ")
4549< This function is not available in the |sandbox|.
4550
4551 Can also be used as a |method|, the base is passed as the
4552 second argument: >
4553 GetHistory()->histadd('search')
4554
4555histdel({history} [, {item}]) *histdel()*
4556 Clear {history}, i.e. delete all its entries. See |hist-names|
4557 for the possible values of {history}.
4558
4559 If the parameter {item} evaluates to a String, it is used as a
4560 regular expression. All entries matching that expression will
4561 be removed from the history (if there are any).
4562 Upper/lowercase must match, unless "\c" is used |/\c|.
4563 If {item} evaluates to a Number, it will be interpreted as
4564 an index, see |:history-indexing|. The respective entry will
4565 be removed if it exists.
4566
4567 The result is TRUE for a successful operation, otherwise FALSE
4568 is returned.
4569
4570 Examples:
4571 Clear expression register history: >
4572 :call histdel("expr")
4573<
4574 Remove all entries starting with "*" from the search history: >
4575 :call histdel("/", '^\*')
4576<
4577 The following three are equivalent: >
4578 :call histdel("search", histnr("search"))
4579 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004580 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004581<
4582 To delete the last search pattern and use the last-but-one for
4583 the "n" command and 'hlsearch': >
4584 :call histdel("search", -1)
4585 :let @/ = histget("search", -1)
4586<
4587 Can also be used as a |method|: >
4588 GetHistory()->histdel()
4589
4590histget({history} [, {index}]) *histget()*
4591 The result is a String, the entry with Number {index} from
4592 {history}. See |hist-names| for the possible values of
4593 {history}, and |:history-indexing| for {index}. If there is
4594 no such entry, an empty String is returned. When {index} is
4595 omitted, the most recent item from the history is used.
4596
4597 Examples:
4598 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004599 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004600
4601< Define an Ex command ":H {num}" that supports re-execution of
4602 the {num}th entry from the output of |:history|. >
4603 :command -nargs=1 H execute histget("cmd", 0+<args>)
4604<
4605 Can also be used as a |method|: >
4606 GetHistory()->histget()
4607
4608histnr({history}) *histnr()*
4609 The result is the Number of the current entry in {history}.
4610 See |hist-names| for the possible values of {history}.
4611 If an error occurred, -1 is returned.
4612
4613 Example: >
4614 :let inp_index = histnr("expr")
4615
4616< Can also be used as a |method|: >
4617 GetHistory()->histnr()
4618<
4619hlexists({name}) *hlexists()*
4620 The result is a Number, which is TRUE if a highlight group
4621 called {name} exists. This is when the group has been
4622 defined in some way. Not necessarily when highlighting has
4623 been defined for it, it may also have been used for a syntax
4624 item.
4625 *highlight_exists()*
4626 Obsolete name: highlight_exists().
4627
4628 Can also be used as a |method|: >
4629 GetName()->hlexists()
4630<
4631hlget([{name} [, {resolve}]]) *hlget()*
4632 Returns a List of all the highlight group attributes. If the
4633 optional {name} is specified, then returns a List with only
4634 the attributes of the specified highlight group. Returns an
4635 empty List if the highlight group {name} is not present.
4636
4637 If the optional {resolve} argument is set to v:true and the
4638 highlight group {name} is linked to another group, then the
4639 link is resolved recursively and the attributes of the
4640 resolved highlight group are returned.
4641
4642 Each entry in the returned List is a Dictionary with the
4643 following items:
4644 cleared boolean flag, set to v:true if the highlight
4645 group attributes are cleared or not yet
4646 specified. See |highlight-clear|.
4647 cterm cterm attributes. See |highlight-cterm|.
4648 ctermbg cterm background color.
4649 See |highlight-ctermbg|.
4650 ctermfg cterm foreground color.
4651 See |highlight-ctermfg|.
4652 ctermul cterm underline color. See |highlight-ctermul|.
4653 default boolean flag, set to v:true if the highlight
4654 group link is a default link. See
4655 |highlight-default|.
4656 font highlight group font. See |highlight-font|.
4657 gui gui attributes. See |highlight-gui|.
4658 guibg gui background color. See |highlight-guibg|.
4659 guifg gui foreground color. See |highlight-guifg|.
4660 guisp gui special color. See |highlight-guisp|.
4661 id highlight group ID.
4662 linksto linked highlight group name.
4663 See |:highlight-link|.
4664 name highlight group name. See |group-name|.
4665 start start terminal keycode. See |highlight-start|.
4666 stop stop terminal keycode. See |highlight-stop|.
4667 term term attributes. See |highlight-term|.
4668
4669 The 'term', 'cterm' and 'gui' items in the above Dictionary
4670 have a dictionary value with the following optional boolean
4671 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4672 'reverse', 'inverse' and 'strikethrough'.
4673
4674 Example(s): >
4675 :echo hlget()
4676 :echo hlget('ModeMsg')
4677 :echo hlget('Number', v:true)
4678<
4679 Can also be used as a |method|: >
4680 GetName()->hlget()
4681<
4682hlset({list}) *hlset()*
4683 Creates or modifies the attributes of a List of highlight
4684 groups. Each item in {list} is a dictionary containing the
4685 attributes of a highlight group. See |hlget()| for the list of
4686 supported items in this dictionary.
4687
4688 In addition to the items described in |hlget()|, the following
4689 additional items are supported in the dictionary:
4690
4691 force boolean flag to force the creation of
4692 a link for an existing highlight group
4693 with attributes.
4694
4695 The highlight group is identified using the 'name' item and
4696 the 'id' item (if supplied) is ignored. If a highlight group
4697 with a specified name doesn't exist, then it is created.
4698 Otherwise the attributes of an existing highlight group are
4699 modified.
4700
4701 If an empty dictionary value is used for the 'term' or 'cterm'
4702 or 'gui' entries, then the corresponding attributes are
4703 cleared. If the 'cleared' item is set to v:true, then all the
4704 attributes of the highlight group are cleared.
4705
4706 The 'linksto' item can be used to link a highlight group to
4707 another highlight group. See |:highlight-link|.
4708
4709 Returns zero for success, -1 for failure.
4710
4711 Example(s): >
4712 " add bold attribute to the Visual highlight group
4713 :call hlset([#{name: 'Visual',
4714 \ term: #{reverse: 1 , bold: 1}}])
4715 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4716 :let l = hlget()
4717 :call hlset(l)
4718 " clear the Search highlight group
4719 :call hlset([#{name: 'Search', cleared: v:true}])
4720 " clear the 'term' attributes for a highlight group
4721 :call hlset([#{name: 'Title', term: {}}])
4722 " create the MyHlg group linking it to DiffAdd
4723 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4724 " remove the MyHlg group link
4725 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4726 " clear the attributes and a link
4727 :call hlset([#{name: 'MyHlg', cleared: v:true,
4728 \ linksto: 'NONE'}])
4729<
4730 Can also be used as a |method|: >
4731 GetAttrList()->hlset()
4732<
4733 *hlID()*
4734hlID({name}) The result is a Number, which is the ID of the highlight group
4735 with name {name}. When the highlight group doesn't exist,
4736 zero is returned.
4737 This can be used to retrieve information about the highlight
4738 group. For example, to get the background color of the
4739 "Comment" group: >
4740 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4741< *highlightID()*
4742 Obsolete name: highlightID().
4743
4744 Can also be used as a |method|: >
4745 GetName()->hlID()
4746
4747hostname() *hostname()*
4748 The result is a String, which is the name of the machine on
4749 which Vim is currently running. Machine names greater than
4750 256 characters long are truncated.
4751
4752iconv({string}, {from}, {to}) *iconv()*
4753 The result is a String, which is the text {string} converted
4754 from encoding {from} to encoding {to}.
4755 When the conversion completely fails an empty string is
4756 returned. When some characters could not be converted they
4757 are replaced with "?".
4758 The encoding names are whatever the iconv() library function
4759 can accept, see ":!man 3 iconv".
4760 Most conversions require Vim to be compiled with the |+iconv|
4761 feature. Otherwise only UTF-8 to latin1 conversion and back
4762 can be done.
4763 This can be used to display messages with special characters,
4764 no matter what 'encoding' is set to. Write the message in
4765 UTF-8 and use: >
4766 echo iconv(utf8_str, "utf-8", &enc)
4767< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4768 from/to UCS-2 is automatically changed to use UTF-8. You
4769 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4770
4771 Can also be used as a |method|: >
4772 GetText()->iconv('latin1', 'utf-8')
4773<
4774 *indent()*
4775indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4776 current buffer. The indent is counted in spaces, the value
4777 of 'tabstop' is relevant. {lnum} is used just like in
4778 |getline()|.
4779 When {lnum} is invalid -1 is returned. In |Vim9| script an
4780 error is given.
4781
4782 Can also be used as a |method|: >
4783 GetLnum()->indent()
4784
4785index({object}, {expr} [, {start} [, {ic}]]) *index()*
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004786 Find {expr} in {object} and return its index. See
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004787 |indexof()| for using a lambda to select the item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004788
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004789 If {object} is a |List| return the lowest index where the item
4790 has a value equal to {expr}. There is no automatic
4791 conversion, so the String "4" is different from the Number 4.
4792 And the number 4 is different from the Float 4.0. The value
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004793 of 'ignorecase' is not used here, case matters as indicated by
4794 the {ic} argument.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004795
4796 If {object} is |Blob| return the lowest index where the byte
4797 value is equal to {expr}.
4798
4799 If {start} is given then start looking at the item with index
4800 {start} (may be negative for an item relative to the end).
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004801
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004802 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4803 case must match.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004804
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004805 -1 is returned when {expr} is not found in {object}.
4806 Example: >
4807 :let idx = index(words, "the")
4808 :if index(numbers, 123) >= 0
4809
4810< Can also be used as a |method|: >
4811 GetObject()->index(what)
4812
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004813indexof({object}, {expr} [, {opts}]) *indexof()*
4814 Returns the index of an item in {object} where {expr} is
4815 v:true. {object} must be a |List| or a |Blob|.
4816
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004817 If {object} is a |List|, evaluate {expr} for each item in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004818 List until the expression is v:true and return the index of
4819 this item.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004820
4821 If {object} is a |Blob| evaluate {expr} for each byte in the
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004822 Blob until the expression is v:true and return the index of
4823 this byte.
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004824
4825 {expr} must be a |string| or |Funcref|.
4826
4827 If {expr} is a |string|: If {object} is a |List|, inside
4828 {expr} |v:key| has the index of the current List item and
4829 |v:val| has the value of the item. If {object} is a |Blob|,
4830 inside {expr} |v:key| has the index of the current byte and
4831 |v:val| has the byte value.
4832
4833 If {expr} is a |Funcref| it must take two arguments:
4834 1. the key or the index of the current item.
4835 2. the value of the current item.
4836 The function must return |TRUE| if the item is found and the
4837 search should stop.
4838
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004839 The optional argument {opts} is a Dict and supports the
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004840 following items:
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004841 startidx start evaluating {expr} at the item with this
4842 index; may be negative for an item relative to
4843 the end
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004844 Returns -1 when {expr} evaluates to v:false for all the items.
4845 Example: >
Yegappan Lakshmanan3fbf6cd2022-08-13 21:35:13 +01004846 :let l = [#{n: 10}, #{n: 20}, #{n: 30}]
4847 :echo indexof(l, "v:val.n == 20")
4848 :echo indexof(l, {i, v -> v.n == 30})
4849 :echo indexof(l, "v:val.n == 20", #{startidx: 1})
Yegappan Lakshmananb2186552022-08-13 13:09:20 +01004850
4851< Can also be used as a |method|: >
4852 mylist->indexof(expr)
4853
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004854input({prompt} [, {text} [, {completion}]]) *input()*
4855 The result is a String, which is whatever the user typed on
4856 the command-line. The {prompt} argument is either a prompt
4857 string, or a blank string (for no prompt). A '\n' can be used
4858 in the prompt to start a new line.
4859 The highlighting set with |:echohl| is used for the prompt.
4860 The input is entered just like a command-line, with the same
4861 editing commands and mappings. There is a separate history
4862 for lines typed for input().
4863 Example: >
4864 :if input("Coffee or beer? ") == "beer"
4865 : echo "Cheers!"
4866 :endif
4867<
4868 If the optional {text} argument is present and not empty, this
4869 is used for the default reply, as if the user typed this.
4870 Example: >
4871 :let color = input("Color? ", "white")
4872
4873< The optional {completion} argument specifies the type of
4874 completion supported for the input. Without it completion is
4875 not performed. The supported completion types are the same as
4876 that can be supplied to a user-defined command using the
4877 "-complete=" argument. Refer to |:command-completion| for
4878 more information. Example: >
4879 let fname = input("File: ", "", "file")
4880<
4881 NOTE: This function must not be used in a startup file, for
4882 the versions that only run in GUI mode (e.g., the Win32 GUI).
4883 Note: When input() is called from within a mapping it will
4884 consume remaining characters from that mapping, because a
4885 mapping is handled like the characters were typed.
4886 Use |inputsave()| before input() and |inputrestore()|
4887 after input() to avoid that. Another solution is to avoid
4888 that further characters follow in the mapping, e.g., by using
4889 |:execute| or |:normal|.
4890
4891 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004892 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004893 :function GetFoo()
4894 : call inputsave()
4895 : let g:Foo = input("enter search pattern: ")
4896 : call inputrestore()
4897 :endfunction
4898
4899< Can also be used as a |method|: >
4900 GetPrompt()->input()
4901
4902inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4903 Like |input()|, but when the GUI is running and text dialogs
4904 are supported, a dialog window pops up to input the text.
4905 Example: >
4906 :let n = inputdialog("value for shiftwidth", shiftwidth())
4907 :if n != ""
4908 : let &sw = n
4909 :endif
4910< When the dialog is cancelled {cancelreturn} is returned. When
4911 omitted an empty string is returned.
4912 Hitting <Enter> works like pressing the OK button. Hitting
4913 <Esc> works like pressing the Cancel button.
4914 NOTE: Command-line completion is not supported.
4915
4916 Can also be used as a |method|: >
4917 GetPrompt()->inputdialog()
4918
4919inputlist({textlist}) *inputlist()*
4920 {textlist} must be a |List| of strings. This |List| is
4921 displayed, one string per line. The user will be prompted to
4922 enter a number, which is returned.
4923 The user can also select an item by clicking on it with the
4924 mouse, if the mouse is enabled in the command line ('mouse' is
4925 "a" or includes "c"). For the first string 0 is returned.
4926 When clicking above the first item a negative number is
4927 returned. When clicking on the prompt one more than the
4928 length of {textlist} is returned.
4929 Make sure {textlist} has less than 'lines' entries, otherwise
4930 it won't work. It's a good idea to put the entry number at
4931 the start of the string. And put a prompt in the first item.
4932 Example: >
4933 let color = inputlist(['Select color:', '1. red',
4934 \ '2. green', '3. blue'])
4935
4936< Can also be used as a |method|: >
4937 GetChoices()->inputlist()
4938
4939inputrestore() *inputrestore()*
4940 Restore typeahead that was saved with a previous |inputsave()|.
4941 Should be called the same number of times inputsave() is
4942 called. Calling it more often is harmless though.
4943 Returns TRUE when there is nothing to restore, FALSE otherwise.
4944
4945inputsave() *inputsave()*
4946 Preserve typeahead (also from mappings) and clear it, so that
4947 a following prompt gets input from the user. Should be
4948 followed by a matching inputrestore() after the prompt. Can
4949 be used several times, in which case there must be just as
4950 many inputrestore() calls.
4951 Returns TRUE when out of memory, FALSE otherwise.
4952
4953inputsecret({prompt} [, {text}]) *inputsecret()*
4954 This function acts much like the |input()| function with but
4955 two exceptions:
4956 a) the user's response will be displayed as a sequence of
4957 asterisks ("*") thereby keeping the entry secret, and
4958 b) the user's response will not be recorded on the input
4959 |history| stack.
4960 The result is a String, which is whatever the user actually
4961 typed on the command-line in response to the issued prompt.
4962 NOTE: Command-line completion is not supported.
4963
4964 Can also be used as a |method|: >
4965 GetPrompt()->inputsecret()
4966
4967insert({object}, {item} [, {idx}]) *insert()*
4968 When {object} is a |List| or a |Blob| insert {item} at the start
4969 of it.
4970
4971 If {idx} is specified insert {item} before the item with index
4972 {idx}. If {idx} is zero it goes before the first item, just
4973 like omitting {idx}. A negative {idx} is also possible, see
4974 |list-index|. -1 inserts just before the last item.
4975
4976 Returns the resulting |List| or |Blob|. Examples: >
4977 :let mylist = insert([2, 3, 5], 1)
4978 :call insert(mylist, 4, -1)
4979 :call insert(mylist, 6, len(mylist))
4980< The last example can be done simpler with |add()|.
4981 Note that when {item} is a |List| it is inserted as a single
4982 item. Use |extend()| to concatenate |Lists|.
4983
4984 Can also be used as a |method|: >
4985 mylist->insert(item)
4986
4987interrupt() *interrupt()*
4988 Interrupt script execution. It works more or less like the
4989 user typing CTRL-C, most commands won't execute and control
4990 returns to the user. This is useful to abort execution
4991 from lower down, e.g. in an autocommand. Example: >
4992 :function s:check_typoname(file)
4993 : if fnamemodify(a:file, ':t') == '['
4994 : echomsg 'Maybe typo'
4995 : call interrupt()
4996 : endif
4997 :endfunction
4998 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
4999
5000invert({expr}) *invert()*
5001 Bitwise invert. The argument is converted to a number. A
5002 List, Dict or Float argument causes an error. Example: >
5003 :let bits = invert(bits)
5004< Can also be used as a |method|: >
5005 :let bits = bits->invert()
5006
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005007isabsolutepath({path}) *isabsolutepath()*
LemonBoydca1d402022-04-28 15:26:33 +01005008 The result is a Number, which is |TRUE| when {path} is an
5009 absolute path.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005010 On Unix, a path is considered absolute when it starts with '/'.
LemonBoydca1d402022-04-28 15:26:33 +01005011 On MS-Windows, it is considered absolute when it starts with an
5012 optional drive prefix and is followed by a '\' or '/'. UNC paths
5013 are always absolute.
5014 Example: >
5015 echo isabsolutepath('/usr/share/') " 1
5016 echo isabsolutepath('./foobar') " 0
5017 echo isabsolutepath('C:\Windows') " 1
5018 echo isabsolutepath('foobar') " 0
5019 echo isabsolutepath('\\remote\file') " 1
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005020<
LemonBoydca1d402022-04-28 15:26:33 +01005021 Can also be used as a |method|: >
5022 GetName()->isabsolutepath()
5023
5024
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005025isdirectory({directory}) *isdirectory()*
5026 The result is a Number, which is |TRUE| when a directory
5027 with the name {directory} exists. If {directory} doesn't
5028 exist, or isn't a directory, the result is |FALSE|. {directory}
5029 is any expression, which is used as a String.
5030
5031 Can also be used as a |method|: >
5032 GetName()->isdirectory()
5033
5034isinf({expr}) *isinf()*
5035 Return 1 if {expr} is a positive infinity, or -1 a negative
5036 infinity, otherwise 0. >
5037 :echo isinf(1.0 / 0.0)
5038< 1 >
5039 :echo isinf(-1.0 / 0.0)
5040< -1
5041
5042 Can also be used as a |method|: >
5043 Compute()->isinf()
5044<
5045 {only available when compiled with the |+float| feature}
5046
5047islocked({expr}) *islocked()* *E786*
5048 The result is a Number, which is |TRUE| when {expr} is the
5049 name of a locked variable.
5050 The string argument {expr} must be the name of a variable,
5051 |List| item or |Dictionary| entry, not the variable itself!
5052 Example: >
5053 :let alist = [0, ['a', 'b'], 2, 3]
5054 :lockvar 1 alist
5055 :echo islocked('alist') " 1
5056 :echo islocked('alist[1]') " 0
5057
Bram Moolenaar9da17d72022-02-09 21:50:44 +00005058< When {expr} is a variable that does not exist -1 is returned.
5059 If {expr} uses a range, list or dict index that is out of
5060 range or does not exist you get an error message. Use
5061 |exists()| to check for existence.
5062 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005063
5064 Can also be used as a |method|: >
5065 GetName()->islocked()
5066
5067isnan({expr}) *isnan()*
5068 Return |TRUE| if {expr} is a float with value NaN. >
5069 echo isnan(0.0 / 0.0)
5070< 1
5071
5072 Can also be used as a |method|: >
5073 Compute()->isnan()
5074<
5075 {only available when compiled with the |+float| feature}
5076
5077items({dict}) *items()*
5078 Return a |List| with all the key-value pairs of {dict}. Each
5079 |List| item is a list with two items: the key of a {dict}
5080 entry and the value of this entry. The |List| is in arbitrary
5081 order. Also see |keys()| and |values()|.
5082 Example: >
5083 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005084 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005085 endfor
5086
5087< Can also be used as a |method|: >
5088 mydict->items()
5089
5090job_ functions are documented here: |job-functions-details|
5091
5092
5093join({list} [, {sep}]) *join()*
5094 Join the items in {list} together into one String.
5095 When {sep} is specified it is put in between the items. If
5096 {sep} is omitted a single space is used.
5097 Note that {sep} is not added at the end. You might want to
5098 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005099 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005100< String items are used as-is. |Lists| and |Dictionaries| are
5101 converted into a string like with |string()|.
5102 The opposite function is |split()|.
5103
5104 Can also be used as a |method|: >
5105 mylist->join()
5106
5107js_decode({string}) *js_decode()*
5108 This is similar to |json_decode()| with these differences:
5109 - Object key names do not have to be in quotes.
5110 - Strings can be in single quotes.
5111 - Empty items in an array (between two commas) are allowed and
5112 result in v:none items.
5113
5114 Can also be used as a |method|: >
5115 ReadObject()->js_decode()
5116
5117js_encode({expr}) *js_encode()*
5118 This is similar to |json_encode()| with these differences:
5119 - Object key names are not in quotes.
5120 - v:none items in an array result in an empty item between
5121 commas.
5122 For example, the Vim object:
5123 [1,v:none,{"one":1},v:none] ~
5124 Will be encoded as:
5125 [1,,{one:1},,] ~
5126 While json_encode() would produce:
5127 [1,null,{"one":1},null] ~
5128 This encoding is valid for JavaScript. It is more efficient
5129 than JSON, especially when using an array with optional items.
5130
5131 Can also be used as a |method|: >
5132 GetObject()->js_encode()
5133
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005134json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005135 This parses a JSON formatted string and returns the equivalent
5136 in Vim values. See |json_encode()| for the relation between
5137 JSON and Vim values.
5138 The decoding is permissive:
5139 - A trailing comma in an array and object is ignored, e.g.
5140 "[1, 2, ]" is the same as "[1, 2]".
5141 - Integer keys are accepted in objects, e.g. {1:2} is the
5142 same as {"1":2}.
5143 - More floating point numbers are recognized, e.g. "1." for
5144 "1.0", or "001.2" for "1.2". Special floating point values
5145 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5146 are accepted.
5147 - Leading zeroes in integer numbers are ignored, e.g. "012"
5148 for "12" or "-012" for "-12".
5149 - Capitalization is ignored in literal names null, true or
5150 false, e.g. "NULL" for "null", "True" for "true".
5151 - Control characters U+0000 through U+001F which are not
5152 escaped in strings are accepted, e.g. " " (tab
5153 character in string) for "\t".
5154 - An empty JSON expression or made of only spaces is accepted
5155 and results in v:none.
5156 - Backslash in an invalid 2-character sequence escape is
5157 ignored, e.g. "\a" is decoded as "a".
5158 - A correct surrogate pair in JSON strings should normally be
5159 a 12 character sequence such as "\uD834\uDD1E", but
5160 json_decode() silently accepts truncated surrogate pairs
5161 such as "\uD834" or "\uD834\u"
5162 *E938*
5163 A duplicate key in an object, valid in rfc7159, is not
5164 accepted by json_decode() as the result must be a valid Vim
5165 type, e.g. this fails: {"a":"b", "a":"c"}
5166
5167 Can also be used as a |method|: >
5168 ReadObject()->json_decode()
5169
5170json_encode({expr}) *json_encode()*
5171 Encode {expr} as JSON and return this as a string.
5172 The encoding is specified in:
5173 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00005174 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005175 |Number| decimal number
5176 |Float| floating point number
5177 Float nan "NaN"
5178 Float inf "Infinity"
5179 Float -inf "-Infinity"
5180 |String| in double quotes (possibly null)
5181 |Funcref| not possible, error
5182 |List| as an array (possibly null); when
5183 used recursively: []
5184 |Dict| as an object (possibly null); when
5185 used recursively: {}
5186 |Blob| as an array of the individual bytes
5187 v:false "false"
5188 v:true "true"
5189 v:none "null"
5190 v:null "null"
5191 Note that NaN and Infinity are passed on as values. This is
5192 missing in the JSON standard, but several implementations do
5193 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005194 If a string contains an illegal character then the replacement
5195 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005196
5197 Can also be used as a |method|: >
5198 GetObject()->json_encode()
5199
5200keys({dict}) *keys()*
5201 Return a |List| with all the keys of {dict}. The |List| is in
5202 arbitrary order. Also see |items()| and |values()|.
5203
5204 Can also be used as a |method|: >
5205 mydict->keys()
5206
5207< *len()* *E701*
5208len({expr}) The result is a Number, which is the length of the argument.
5209 When {expr} is a String or a Number the length in bytes is
5210 used, as with |strlen()|.
5211 When {expr} is a |List| the number of items in the |List| is
5212 returned.
5213 When {expr} is a |Blob| the number of bytes is returned.
5214 When {expr} is a |Dictionary| the number of entries in the
5215 |Dictionary| is returned.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005216 Otherwise an error is given and returns zero.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005217
5218 Can also be used as a |method|: >
5219 mylist->len()
5220
5221< *libcall()* *E364* *E368*
5222libcall({libname}, {funcname}, {argument})
5223 Call function {funcname} in the run-time library {libname}
5224 with single argument {argument}.
5225 This is useful to call functions in a library that you
5226 especially made to be used with Vim. Since only one argument
5227 is possible, calling standard library functions is rather
5228 limited.
5229 The result is the String returned by the function. If the
5230 function returns NULL, this will appear as an empty string ""
5231 to Vim.
5232 If the function returns a number, use libcallnr()!
5233 If {argument} is a number, it is passed to the function as an
5234 int; if {argument} is a string, it is passed as a
5235 null-terminated string.
5236 This function will fail in |restricted-mode|.
5237
5238 libcall() allows you to write your own 'plug-in' extensions to
5239 Vim without having to recompile the program. It is NOT a
5240 means to call system functions! If you try to do so Vim will
5241 very probably crash.
5242
5243 For Win32, the functions you write must be placed in a DLL
5244 and use the normal C calling convention (NOT Pascal which is
5245 used in Windows System DLLs). The function must take exactly
5246 one parameter, either a character pointer or a long integer,
5247 and must return a character pointer or NULL. The character
5248 pointer returned must point to memory that will remain valid
5249 after the function has returned (e.g. in static data in the
5250 DLL). If it points to allocated memory, that memory will
5251 leak away. Using a static buffer in the function should work,
5252 it's then freed when the DLL is unloaded.
5253
5254 WARNING: If the function returns a non-valid pointer, Vim may
5255 crash! This also happens if the function returns a number,
5256 because Vim thinks it's a pointer.
5257 For Win32 systems, {libname} should be the filename of the DLL
5258 without the ".DLL" suffix. A full path is only required if
5259 the DLL is not in the usual places.
5260 For Unix: When compiling your own plugins, remember that the
5261 object code must be compiled as position-independent ('PIC').
5262 {only in Win32 and some Unix versions, when the |+libcall|
5263 feature is present}
5264 Examples: >
5265 :echo libcall("libc.so", "getenv", "HOME")
5266
5267< Can also be used as a |method|, the base is passed as the
5268 third argument: >
5269 GetValue()->libcall("libc.so", "getenv")
5270<
5271 *libcallnr()*
5272libcallnr({libname}, {funcname}, {argument})
5273 Just like |libcall()|, but used for a function that returns an
5274 int instead of a string.
5275 {only in Win32 on some Unix versions, when the |+libcall|
5276 feature is present}
5277 Examples: >
5278 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
5279 :call libcallnr("libc.so", "printf", "Hello World!\n")
5280 :call libcallnr("libc.so", "sleep", 10)
5281<
5282 Can also be used as a |method|, the base is passed as the
5283 third argument: >
5284 GetValue()->libcallnr("libc.so", "printf")
5285<
5286
5287line({expr} [, {winid}]) *line()*
5288 The result is a Number, which is the line number of the file
5289 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00005290 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005291 . the cursor position
5292 $ the last line in the current buffer
5293 'x position of mark x (if the mark is not set, 0 is
5294 returned)
5295 w0 first line visible in current window (one if the
5296 display isn't updated, e.g. in silent Ex mode)
5297 w$ last line visible in current window (this is one
5298 less than "w0" if no lines are visible)
5299 v In Visual mode: the start of the Visual area (the
5300 cursor is the end). When not in Visual mode
5301 returns the cursor position. Differs from |'<| in
5302 that it's updated right away.
5303 Note that a mark in another file can be used. The line number
5304 then applies to another buffer.
5305 To get the column number use |col()|. To get both use
5306 |getpos()|.
5307 With the optional {winid} argument the values are obtained for
5308 that window instead of the current window.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005309 Returns 0 for invalid values of {expr} and {winid}.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005310 Examples: >
5311 line(".") line number of the cursor
5312 line(".", winid) idem, in window "winid"
5313 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005314 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005315<
5316 To jump to the last known position when opening a file see
5317 |last-position-jump|.
5318
5319 Can also be used as a |method|: >
5320 GetValue()->line()
5321
5322line2byte({lnum}) *line2byte()*
5323 Return the byte count from the start of the buffer for line
5324 {lnum}. This includes the end-of-line character, depending on
5325 the 'fileformat' option for the current buffer. The first
5326 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
5327 This can also be used to get the byte count for the line just
5328 below the last line: >
5329 line2byte(line("$") + 1)
5330< This is the buffer size plus one. If 'fileencoding' is empty
5331 it is the file size plus one. {lnum} is used like with
5332 |getline()|. When {lnum} is invalid, or the |+byte_offset|
5333 feature has been disabled at compile time, -1 is returned.
5334 Also see |byte2line()|, |go| and |:goto|.
5335
5336 Can also be used as a |method|: >
5337 GetLnum()->line2byte()
5338
5339lispindent({lnum}) *lispindent()*
5340 Get the amount of indent for line {lnum} according the lisp
5341 indenting rules, as with 'lisp'.
5342 The indent is counted in spaces, the value of 'tabstop' is
5343 relevant. {lnum} is used just like in |getline()|.
Bram Moolenaar8e145b82022-05-21 20:17:31 +01005344 When {lnum} is invalid -1 is returned. In |Vim9| script an
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005345 error is given.
5346
5347 Can also be used as a |method|: >
5348 GetLnum()->lispindent()
5349
5350list2blob({list}) *list2blob()*
5351 Return a Blob concatenating all the number values in {list}.
5352 Examples: >
5353 list2blob([1, 2, 3, 4]) returns 0z01020304
5354 list2blob([]) returns 0z
5355< Returns an empty Blob on error. If one of the numbers is
5356 negative or more than 255 error *E1239* is given.
5357
5358 |blob2list()| does the opposite.
5359
5360 Can also be used as a |method|: >
5361 GetList()->list2blob()
5362
5363list2str({list} [, {utf8}]) *list2str()*
5364 Convert each number in {list} to a character string can
5365 concatenate them all. Examples: >
5366 list2str([32]) returns " "
5367 list2str([65, 66, 67]) returns "ABC"
5368< The same can be done (slowly) with: >
5369 join(map(list, {nr, val -> nr2char(val)}), '')
5370< |str2list()| does the opposite.
5371
5372 When {utf8} is omitted or zero, the current 'encoding' is used.
5373 When {utf8} is TRUE, always return UTF-8 characters.
5374 With UTF-8 composing characters work as expected: >
5375 list2str([97, 769]) returns "á"
5376<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005377 Returns an empty string on error.
5378
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005379 Can also be used as a |method|: >
5380 GetList()->list2str()
5381
5382listener_add({callback} [, {buf}]) *listener_add()*
5383 Add a callback function that will be invoked when changes have
5384 been made to buffer {buf}.
5385 {buf} refers to a buffer name or number. For the accepted
5386 values, see |bufname()|. When {buf} is omitted the current
5387 buffer is used.
5388 Returns a unique ID that can be passed to |listener_remove()|.
5389
5390 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005391 bufnr the buffer that was changed
5392 start first changed line number
5393 end first line number below the change
5394 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005395 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005396 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005397
5398 Example: >
5399 func Listener(bufnr, start, end, added, changes)
5400 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5401 endfunc
5402 call listener_add('Listener', bufnr)
5403
Bram Moolenaar944697a2022-02-20 19:48:20 +00005404< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005405 dictionary with these entries:
5406 lnum the first line number of the change
5407 end the first line below the change
5408 added number of lines added; negative if lines were
5409 deleted
5410 col first column in "lnum" that was affected by
5411 the change; one if unknown or the whole line
5412 was affected; this is a byte index, first
5413 character has a value of one.
5414 When lines are inserted the values are:
5415 lnum line above which the new line is added
5416 end equal to "lnum"
5417 added number of lines inserted
5418 col 1
5419 When lines are deleted the values are:
5420 lnum the first deleted line
5421 end the line below the first deleted line, before
5422 the deletion was done
5423 added negative, number of lines deleted
5424 col 1
5425 When lines are changed:
5426 lnum the first changed line
5427 end the line below the last changed line
5428 added 0
5429 col first column with a change or 1
5430
5431 The entries are in the order the changes were made, thus the
5432 most recent change is at the end. The line numbers are valid
5433 when the callback is invoked, but later changes may make them
5434 invalid, thus keeping a copy for later might not work.
5435
5436 The {callback} is invoked just before the screen is updated,
5437 when |listener_flush()| is called or when a change is being
5438 made that changes the line count in a way it causes a line
5439 number in the list of changes to become invalid.
5440
5441 The {callback} is invoked with the text locked, see
5442 |textlock|. If you do need to make changes to the buffer, use
5443 a timer to do this later |timer_start()|.
5444
5445 The {callback} is not invoked when the buffer is first loaded.
5446 Use the |BufReadPost| autocmd event to handle the initial text
5447 of a buffer.
5448 The {callback} is also not invoked when the buffer is
5449 unloaded, use the |BufUnload| autocmd event for that.
5450
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005451 Returns zero if {callback} or {buf} is invalid.
5452
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005453 Can also be used as a |method|, the base is passed as the
5454 second argument: >
5455 GetBuffer()->listener_add(callback)
5456
5457listener_flush([{buf}]) *listener_flush()*
5458 Invoke listener callbacks for buffer {buf}. If there are no
5459 pending changes then no callbacks are invoked.
5460
5461 {buf} refers to a buffer name or number. For the accepted
5462 values, see |bufname()|. When {buf} is omitted the current
5463 buffer is used.
5464
5465 Can also be used as a |method|: >
5466 GetBuffer()->listener_flush()
5467
5468listener_remove({id}) *listener_remove()*
5469 Remove a listener previously added with listener_add().
5470 Returns FALSE when {id} could not be found, TRUE when {id} was
5471 removed.
5472
5473 Can also be used as a |method|: >
5474 GetListenerId()->listener_remove()
5475
5476localtime() *localtime()*
5477 Return the current time, measured as seconds since 1st Jan
5478 1970. See also |strftime()|, |strptime()| and |getftime()|.
5479
5480
5481log({expr}) *log()*
5482 Return the natural logarithm (base e) of {expr} as a |Float|.
5483 {expr} must evaluate to a |Float| or a |Number| in the range
5484 (0, inf].
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005485 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005486 Examples: >
5487 :echo log(10)
5488< 2.302585 >
5489 :echo log(exp(5))
5490< 5.0
5491
5492 Can also be used as a |method|: >
5493 Compute()->log()
5494<
5495 {only available when compiled with the |+float| feature}
5496
5497
5498log10({expr}) *log10()*
5499 Return the logarithm of Float {expr} to base 10 as a |Float|.
5500 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005501 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005502 Examples: >
5503 :echo log10(1000)
5504< 3.0 >
5505 :echo log10(0.01)
5506< -2.0
5507
5508 Can also be used as a |method|: >
5509 Compute()->log10()
5510<
5511 {only available when compiled with the |+float| feature}
5512
5513luaeval({expr} [, {expr}]) *luaeval()*
5514 Evaluate Lua expression {expr} and return its result converted
5515 to Vim data structures. Second {expr} may hold additional
5516 argument accessible as _A inside first {expr}.
5517 Strings are returned as they are.
5518 Boolean objects are converted to numbers.
5519 Numbers are converted to |Float| values if vim was compiled
5520 with |+float| and to numbers otherwise.
5521 Dictionaries and lists obtained by vim.eval() are returned
5522 as-is.
5523 Other objects are returned as zero without any errors.
5524 See |lua-luaeval| for more details.
5525 Note that in a `:def` function local variables are not visible
5526 to {expr}.
5527
5528 Can also be used as a |method|: >
5529 GetExpr()->luaeval()
5530
5531< {only available when compiled with the |+lua| feature}
5532
5533map({expr1}, {expr2}) *map()*
5534 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005535 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005536 item in {expr1} with the result of evaluating {expr2}.
5537 For a |Blob| each byte is replaced.
5538 For a |String|, each character, including composing
5539 characters, is replaced.
5540 If the item type changes you may want to use |mapnew()| to
5541 create a new List or Dictionary. This is required when using
5542 Vim9 script.
5543
5544 {expr2} must be a |String| or |Funcref|.
5545
5546 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5547 of the current item. For a |Dictionary| |v:key| has the key
5548 of the current item and for a |List| |v:key| has the index of
5549 the current item. For a |Blob| |v:key| has the index of the
5550 current byte. For a |String| |v:key| has the index of the
5551 current character.
5552 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005553 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005554< This puts "> " before and " <" after each item in "mylist".
5555
5556 Note that {expr2} is the result of an expression and is then
5557 used as an expression again. Often it is good to use a
5558 |literal-string| to avoid having to double backslashes. You
5559 still have to double ' quotes
5560
5561 If {expr2} is a |Funcref| it is called with two arguments:
5562 1. The key or the index of the current item.
5563 2. the value of the current item.
5564 The function must return the new value of the item. Example
5565 that changes each value by "key-value": >
5566 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005567 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005568 endfunc
5569 call map(myDict, function('KeyValue'))
5570< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005571 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005572< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005573 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005574< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005575 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005576<
5577 The operation is done in-place for a |List| and |Dictionary|.
5578 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005579 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005580
5581< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5582 or a new |Blob| or |String|.
5583 When an error is encountered while evaluating {expr2} no
5584 further items in {expr1} are processed.
5585 When {expr2} is a Funcref errors inside a function are ignored,
5586 unless it was defined with the "abort" flag.
5587
5588 Can also be used as a |method|: >
5589 mylist->map(expr2)
5590
5591
5592maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5593 When {dict} is omitted or zero: Return the rhs of mapping
5594 {name} in mode {mode}. The returned String has special
5595 characters translated like in the output of the ":map" command
Ernie Rael09661202022-04-25 14:40:44 +01005596 listing. When {dict} is TRUE a dictionary is returned, see
5597 below. To get a list of all mappings see |maplist()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005598
5599 When there is no mapping for {name}, an empty String is
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005600 returned if {dict} is FALSE, otherwise returns an empty Dict.
5601 When the mapping for {name} is empty, then "<Nop>" is
5602 returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005603
5604 The {name} can have special key names, like in the ":map"
5605 command.
5606
5607 {mode} can be one of these strings:
5608 "n" Normal
5609 "v" Visual (including Select)
5610 "o" Operator-pending
5611 "i" Insert
5612 "c" Cmd-line
5613 "s" Select
5614 "x" Visual
5615 "l" langmap |language-mapping|
5616 "t" Terminal-Job
5617 "" Normal, Visual and Operator-pending
5618 When {mode} is omitted, the modes for "" are used.
5619
5620 When {abbr} is there and it is |TRUE| use abbreviations
5621 instead of mappings.
5622
5623 When {dict} is there and it is |TRUE| return a dictionary
5624 containing all the information of the mapping with the
Ernie Rael659c2402022-04-24 18:40:28 +01005625 following items: *mapping-dict*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005626 "lhs" The {lhs} of the mapping as it would be typed
5627 "lhsraw" The {lhs} of the mapping as raw bytes
5628 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5629 form, only present when it differs from "lhsraw"
5630 "rhs" The {rhs} of the mapping as typed.
5631 "silent" 1 for a |:map-silent| mapping, else 0.
5632 "noremap" 1 if the {rhs} of the mapping is not remappable.
5633 "script" 1 if mapping was defined with <script>.
5634 "expr" 1 for an expression mapping (|:map-<expr>|).
5635 "buffer" 1 for a buffer local mapping (|:map-local|).
5636 "mode" Modes for which the mapping is defined. In
5637 addition to the modes mentioned above, these
5638 characters will be used:
5639 " " Normal, Visual and Operator-pending
5640 "!" Insert and Commandline mode
5641 (|mapmode-ic|)
5642 "sid" The script local ID, used for <sid> mappings
5643 (|<SID>|).
Bram Moolenaara9528b32022-01-18 20:51:35 +00005644 "scriptversion" The version of the script. 999999 for
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005645 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005646 "lnum" The line number in "sid", zero if unknown.
5647 "nowait" Do not wait for other, longer mappings.
5648 (|:map-<nowait>|).
Bram Moolenaar921bde82022-05-09 19:50:35 +01005649 "abbr" True if this is an abbreviation |abbreviations|.
Ernie Raeld8f5f762022-05-10 17:50:39 +01005650 "mode_bits" Vim's internal binary representation of "mode".
5651 |mapset()| ignores this; only "mode" is used.
5652 See |maplist()| for usage examples. The values
5653 are from src/vim.h and may change in the future.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005654
5655 The dictionary can be used to restore a mapping with
5656 |mapset()|.
5657
5658 The mappings local to the current buffer are checked first,
5659 then the global mappings.
5660 This function can be used to map a key even when it's already
5661 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005662 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005663
5664< Can also be used as a |method|: >
5665 GetKey()->maparg('n')
5666
5667mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5668 Check if there is a mapping that matches with {name} in mode
5669 {mode}. See |maparg()| for {mode} and special names in
5670 {name}.
5671 When {abbr} is there and it is |TRUE| use abbreviations
5672 instead of mappings.
5673 A match happens with a mapping that starts with {name} and
5674 with a mapping which is equal to the start of {name}.
5675
5676 matches mapping "a" "ab" "abc" ~
5677 mapcheck("a") yes yes yes
5678 mapcheck("abc") yes yes yes
5679 mapcheck("ax") yes no no
5680 mapcheck("b") no no no
5681
5682 The difference with maparg() is that mapcheck() finds a
5683 mapping that matches with {name}, while maparg() only finds a
5684 mapping for {name} exactly.
5685 When there is no mapping that starts with {name}, an empty
5686 String is returned. If there is one, the RHS of that mapping
5687 is returned. If there are several mappings that start with
5688 {name}, the RHS of one of them is returned. This will be
5689 "<Nop>" if the RHS is empty.
5690 The mappings local to the current buffer are checked first,
5691 then the global mappings.
5692 This function can be used to check if a mapping can be added
5693 without being ambiguous. Example: >
5694 :if mapcheck("_vv") == ""
5695 : map _vv :set guifont=7x13<CR>
5696 :endif
5697< This avoids adding the "_vv" mapping when there already is a
5698 mapping for "_v" or for "_vvv".
5699
5700 Can also be used as a |method|: >
5701 GetKey()->mapcheck('n')
5702
5703
Ernie Rael09661202022-04-25 14:40:44 +01005704maplist([{abbr}]) *maplist()*
5705 Returns a |List| of all mappings. Each List item is a |Dict|,
5706 the same as what is returned by |maparg()|, see
5707 |mapping-dict|. When {abbr} is there and it is |TRUE| use
5708 abbreviations instead of mappings.
5709
5710 Example to show all mappings with 'MultiMatch' in rhs: >
5711 vim9script
5712 echo maplist()->filter(
5713 (_, m) => match(m.rhs, 'MultiMatch') >= 0)
Ernie Raeld8f5f762022-05-10 17:50:39 +01005714< It can be tricky to find mappings for particular |:map-modes|.
5715 |mapping-dict|'s "mode_bits" can simplify this. For example,
5716 the mode_bits for Normal, Insert or Command-line modes are
5717 0x19. To find all the mappings available in those modes you
5718 can do: >
5719 vim9script
5720 var saved_maps = []
5721 for m in maplist()
5722 if and(m.mode_bits, 0x19) != 0
5723 saved_maps->add(m)
5724 endif
5725 endfor
5726 echo saved_maps->mapnew((_, m) => m.lhs)
5727< The values of the mode_bits are defined in Vim's src/vim.h
5728 file and they can be discovered at runtime using
5729 |:map-commands| and "maplist()". Example: >
5730 vim9script
5731 omap xyzzy <Nop>
5732 var op_bit = maplist()->filter(
5733 (_, m) => m.lhs == 'xyzzy')[0].mode_bits
5734 ounmap xyzzy
5735 echo printf("Operator-pending mode bit: 0x%x", op_bit)
Ernie Rael09661202022-04-25 14:40:44 +01005736
5737
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005738mapnew({expr1}, {expr2}) *mapnew()*
5739 Like |map()| but instead of replacing items in {expr1} a new
5740 List or Dictionary is created and returned. {expr1} remains
5741 unchanged. Items can still be changed by {expr2}, if you
5742 don't want that use |deepcopy()| first.
5743
5744
5745mapset({mode}, {abbr}, {dict}) *mapset()*
Ernie Rael51d04d12022-05-04 15:40:22 +01005746mapset({dict})
5747 Restore a mapping from a dictionary, possibly returned by
5748 |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
5749 is true, is set on the current buffer; it is up to the caller
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01005750 to ensure that the intended buffer is the current buffer. This
Ernie Rael51d04d12022-05-04 15:40:22 +01005751 feature allows copying mappings from one buffer to another.
5752 The dict.mode value may restore a single mapping that covers
5753 more than one mode, like with mode values of '!', ' ', 'nox',
5754 or 'v'. *E1276*
5755
5756 In the first form, {mode} and {abbr} should be the same as
5757 for the call to |maparg()|. *E460*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005758 {mode} is used to define the mode in which the mapping is set,
5759 not the "mode" entry in {dict}.
5760 Example for saving and restoring a mapping: >
5761 let save_map = maparg('K', 'n', 0, 1)
5762 nnoremap K somethingelse
5763 ...
5764 call mapset('n', 0, save_map)
5765< Note that if you are going to replace a map in several modes,
Ernie Rael51d04d12022-05-04 15:40:22 +01005766 e.g. with `:map!`, you need to save/restore the mapping for
5767 all of them, when they might differ.
5768
5769 In the second form, with {dict} as the only argument, mode
5770 and abbr are taken from the dict.
5771 Example: >
5772 vim9script
5773 var save_maps = maplist()->filter(
5774 (_, m) => m.lhs == 'K')
5775 nnoremap K somethingelse
5776 cnoremap K somethingelse2
5777 # ...
5778 unmap K
5779 for d in save_maps
5780 mapset(d)
5781 endfor
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005782
5783
5784match({expr}, {pat} [, {start} [, {count}]]) *match()*
5785 When {expr} is a |List| then this returns the index of the
5786 first item where {pat} matches. Each item is used as a
5787 String, |Lists| and |Dictionaries| are used as echoed.
5788
5789 Otherwise, {expr} is used as a String. The result is a
5790 Number, which gives the index (byte offset) in {expr} where
5791 {pat} matches.
5792
5793 A match at the first character or |List| item returns zero.
5794 If there is no match -1 is returned.
5795
5796 For getting submatches see |matchlist()|.
5797 Example: >
5798 :echo match("testing", "ing") " results in 4
5799 :echo match([1, 'x'], '\a') " results in 1
5800< See |string-match| for how {pat} is used.
5801 *strpbrk()*
5802 Vim doesn't have a strpbrk() function. But you can do: >
5803 :let sepidx = match(line, '[.,;: \t]')
5804< *strcasestr()*
5805 Vim doesn't have a strcasestr() function. But you can add
5806 "\c" to the pattern to ignore case: >
5807 :let idx = match(haystack, '\cneedle')
5808<
5809 If {start} is given, the search starts from byte index
5810 {start} in a String or item {start} in a |List|.
5811 The result, however, is still the index counted from the
5812 first character/item. Example: >
5813 :echo match("testing", "ing", 2)
5814< result is again "4". >
5815 :echo match("testing", "ing", 4)
5816< result is again "4". >
5817 :echo match("testing", "t", 2)
5818< result is "3".
5819 For a String, if {start} > 0 then it is like the string starts
5820 {start} bytes later, thus "^" will match at {start}. Except
5821 when {count} is given, then it's like matches before the
5822 {start} byte are ignored (this is a bit complicated to keep it
5823 backwards compatible).
5824 For a String, if {start} < 0, it will be set to 0. For a list
5825 the index is counted from the end.
5826 If {start} is out of range ({start} > strlen({expr}) for a
5827 String or {start} > len({expr}) for a |List|) -1 is returned.
5828
5829 When {count} is given use the {count}'th match. When a match
5830 is found in a String the search for the next one starts one
5831 character further. Thus this example results in 1: >
5832 echo match("testing", "..", 0, 2)
5833< In a |List| the search continues in the next item.
5834 Note that when {count} is added the way {start} works changes,
5835 see above.
5836
5837 See |pattern| for the patterns that are accepted.
5838 The 'ignorecase' option is used to set the ignore-caseness of
5839 the pattern. 'smartcase' is NOT used. The matching is always
5840 done like 'magic' is set and 'cpoptions' is empty.
5841 Note that a match at the start is preferred, thus when the
5842 pattern is using "*" (any number of matches) it tends to find
5843 zero matches at the start instead of a number of matches
5844 further down in the text.
5845
5846 Can also be used as a |method|: >
5847 GetText()->match('word')
5848 GetList()->match('word')
5849<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005850 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005851matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5852 Defines a pattern to be highlighted in the current window (a
5853 "match"). It will be highlighted with {group}. Returns an
5854 identification number (ID), which can be used to delete the
5855 match using |matchdelete()|. The ID is bound to the window.
5856 Matching is case sensitive and magic, unless case sensitivity
5857 or magicness are explicitly overridden in {pattern}. The
5858 'magic', 'smartcase' and 'ignorecase' options are not used.
5859 The "Conceal" value is special, it causes the match to be
5860 concealed.
5861
5862 The optional {priority} argument assigns a priority to the
5863 match. A match with a high priority will have its
5864 highlighting overrule that of a match with a lower priority.
5865 A priority is specified as an integer (negative numbers are no
5866 exception). If the {priority} argument is not specified, the
5867 default priority is 10. The priority of 'hlsearch' is zero,
5868 hence all matches with a priority greater than zero will
5869 overrule it. Syntax highlighting (see 'syntax') is a separate
5870 mechanism, and regardless of the chosen priority a match will
5871 always overrule syntax highlighting.
5872
5873 The optional {id} argument allows the request for a specific
5874 match ID. If a specified ID is already taken, an error
5875 message will appear and the match will not be added. An ID
5876 is specified as a positive integer (zero excluded). IDs 1, 2
5877 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01005878 respectively. 3 is reserved for use by the |matchparen|
5879 plugin.
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005880 If the {id} argument is not specified or -1, |matchadd()|
5881 automatically chooses a free ID.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005882
5883 The optional {dict} argument allows for further custom
5884 values. Currently this is used to specify a match specific
5885 conceal character that will be shown for |hl-Conceal|
5886 highlighted matches. The dict can have the following members:
5887
5888 conceal Special character to show instead of the
5889 match (only for |hl-Conceal| highlighted
5890 matches, see |:syn-cchar|)
5891 window Instead of the current window use the
5892 window with this number or window ID.
5893
5894 The number of matches is not limited, as it is the case with
5895 the |:match| commands.
5896
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005897 Returns -1 on error.
5898
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005899 Example: >
5900 :highlight MyGroup ctermbg=green guibg=green
5901 :let m = matchadd("MyGroup", "TODO")
5902< Deletion of the pattern: >
5903 :call matchdelete(m)
5904
5905< A list of matches defined by |matchadd()| and |:match| are
5906 available from |getmatches()|. All matches can be deleted in
5907 one operation by |clearmatches()|.
5908
5909 Can also be used as a |method|: >
5910 GetGroup()->matchadd('TODO')
5911<
5912 *matchaddpos()*
5913matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5914 Same as |matchadd()|, but requires a list of positions {pos}
5915 instead of a pattern. This command is faster than |matchadd()|
5916 because it does not require to handle regular expressions and
5917 sets buffer line boundaries to redraw screen. It is supposed
5918 to be used when fast match additions and deletions are
5919 required, for example to highlight matching parentheses.
5920
5921 {pos} is a list of positions. Each position can be one of
5922 these:
5923 - A number. This whole line will be highlighted. The first
5924 line has number 1.
5925 - A list with one number, e.g., [23]. The whole line with this
5926 number will be highlighted.
5927 - A list with two numbers, e.g., [23, 11]. The first number is
5928 the line number, the second one is the column number (first
5929 column is 1, the value must correspond to the byte index as
5930 |col()| would return). The character at this position will
5931 be highlighted.
5932 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5933 the third number gives the length of the highlight in bytes.
5934
5935 The maximum number of positions in {pos} is 8.
5936
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01005937 Returns -1 on error.
5938
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005939 Example: >
5940 :highlight MyGroup ctermbg=green guibg=green
5941 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5942< Deletion of the pattern: >
5943 :call matchdelete(m)
5944
5945< Matches added by |matchaddpos()| are returned by
5946 |getmatches()|.
5947
5948 Can also be used as a |method|: >
5949 GetGroup()->matchaddpos([23, 11])
5950
5951matcharg({nr}) *matcharg()*
5952 Selects the {nr} match item, as set with a |:match|,
5953 |:2match| or |:3match| command.
5954 Return a |List| with two elements:
5955 The name of the highlight group used
5956 The pattern used.
5957 When {nr} is not 1, 2 or 3 returns an empty |List|.
5958 When there is no match item set returns ['', ''].
5959 This is useful to save and restore a |:match|.
5960 Highlighting matches using the |:match| commands are limited
5961 to three matches. |matchadd()| does not have this limitation.
5962
5963 Can also be used as a |method|: >
5964 GetMatch()->matcharg()
5965
5966matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5967 Deletes a match with ID {id} previously defined by |matchadd()|
5968 or one of the |:match| commands. Returns 0 if successful,
5969 otherwise -1. See example for |matchadd()|. All matches can
5970 be deleted in one operation by |clearmatches()|.
5971 If {win} is specified, use the window with this number or
5972 window ID instead of the current window.
5973
5974 Can also be used as a |method|: >
5975 GetMatch()->matchdelete()
5976
5977matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5978 Same as |match()|, but return the index of first character
5979 after the match. Example: >
5980 :echo matchend("testing", "ing")
5981< results in "7".
5982 *strspn()* *strcspn()*
5983 Vim doesn't have a strspn() or strcspn() function, but you can
5984 do it with matchend(): >
5985 :let span = matchend(line, '[a-zA-Z]')
5986 :let span = matchend(line, '[^a-zA-Z]')
5987< Except that -1 is returned when there are no matches.
5988
5989 The {start}, if given, has the same meaning as for |match()|. >
5990 :echo matchend("testing", "ing", 2)
5991< results in "7". >
5992 :echo matchend("testing", "ing", 5)
5993< result is "-1".
5994 When {expr} is a |List| the result is equal to |match()|.
5995
5996 Can also be used as a |method|: >
5997 GetText()->matchend('word')
5998
5999
6000matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
6001 If {list} is a list of strings, then returns a |List| with all
6002 the strings in {list} that fuzzy match {str}. The strings in
6003 the returned list are sorted based on the matching score.
6004
6005 The optional {dict} argument always supports the following
6006 items:
zeertzjq9af2bc02022-05-11 14:15:37 +01006007 matchseq When this item is present return only matches
6008 that contain the characters in {str} in the
6009 given sequence.
Kazuyuki Miyagi47f1a552022-06-17 18:30:03 +01006010 limit Maximum number of matches in {list} to be
6011 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006012
6013 If {list} is a list of dictionaries, then the optional {dict}
6014 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006015 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006016 {str}. The value of this item should be a
6017 string.
6018 text_cb |Funcref| that will be called for every item
6019 in {list} to get the text for fuzzy matching.
6020 This should accept a dictionary item as the
6021 argument and return the text for that item to
6022 use for fuzzy matching.
6023
6024 {str} is treated as a literal string and regular expression
6025 matching is NOT supported. The maximum supported {str} length
6026 is 256.
6027
6028 When {str} has multiple words each separated by white space,
6029 then the list of strings that have all the words is returned.
6030
6031 If there are no matching strings or there is an error, then an
6032 empty list is returned. If length of {str} is greater than
6033 256, then returns an empty list.
6034
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01006035 When {limit} is given, matchfuzzy() will find up to this
6036 number of matches in {list} and return them in sorted order.
6037
Bram Moolenaar1588bc82022-03-08 21:35:07 +00006038 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006039 matching strings.
6040
6041 Example: >
6042 :echo matchfuzzy(["clay", "crow"], "cay")
6043< results in ["clay"]. >
6044 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
6045< results in a list of buffer names fuzzy matching "ndl". >
6046 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
6047< results in a list of buffer information dicts with buffer
6048 names fuzzy matching "ndl". >
6049 :echo getbufinfo()->matchfuzzy("spl",
6050 \ {'text_cb' : {v -> v.name}})
6051< results in a list of buffer information dicts with buffer
6052 names fuzzy matching "spl". >
6053 :echo v:oldfiles->matchfuzzy("test")
6054< results in a list of file names fuzzy matching "test". >
6055 :let l = readfile("buffer.c")->matchfuzzy("str")
6056< results in a list of lines in "buffer.c" fuzzy matching "str". >
6057 :echo ['one two', 'two one']->matchfuzzy('two one')
6058< results in ['two one', 'one two']. >
6059 :echo ['one two', 'two one']->matchfuzzy('two one',
6060 \ {'matchseq': 1})
6061< results in ['two one'].
6062
6063matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
6064 Same as |matchfuzzy()|, but returns the list of matched
6065 strings, the list of character positions where characters
6066 in {str} matches and a list of matching scores. You can
6067 use |byteidx()| to convert a character position to a byte
6068 position.
6069
6070 If {str} matches multiple times in a string, then only the
6071 positions for the best match is returned.
6072
6073 If there are no matching strings or there is an error, then a
6074 list with three empty list items is returned.
6075
6076 Example: >
6077 :echo matchfuzzypos(['testing'], 'tsg')
6078< results in [['testing'], [[0, 2, 6]], [99]] >
6079 :echo matchfuzzypos(['clay', 'lacy'], 'la')
6080< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
6081 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
6082< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
6083
6084matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
6085 Same as |match()|, but return a |List|. The first item in the
6086 list is the matched string, same as what matchstr() would
6087 return. Following items are submatches, like "\1", "\2", etc.
6088 in |:substitute|. When an optional submatch didn't match an
6089 empty string is used. Example: >
6090 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6091< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
6092 When there is no match an empty list is returned.
6093
6094 You can pass in a List, but that is not very useful.
6095
6096 Can also be used as a |method|: >
6097 GetText()->matchlist('word')
6098
6099matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
6100 Same as |match()|, but return the matched string. Example: >
6101 :echo matchstr("testing", "ing")
6102< results in "ing".
6103 When there is no match "" is returned.
6104 The {start}, if given, has the same meaning as for |match()|. >
6105 :echo matchstr("testing", "ing", 2)
6106< results in "ing". >
6107 :echo matchstr("testing", "ing", 5)
6108< result is "".
6109 When {expr} is a |List| then the matching item is returned.
6110 The type isn't changed, it's not necessarily a String.
6111
6112 Can also be used as a |method|: >
6113 GetText()->matchstr('word')
6114
6115matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
6116 Same as |matchstr()|, but return the matched string, the start
6117 position and the end position of the match. Example: >
6118 :echo matchstrpos("testing", "ing")
6119< results in ["ing", 4, 7].
6120 When there is no match ["", -1, -1] is returned.
6121 The {start}, if given, has the same meaning as for |match()|. >
6122 :echo matchstrpos("testing", "ing", 2)
6123< results in ["ing", 4, 7]. >
6124 :echo matchstrpos("testing", "ing", 5)
6125< result is ["", -1, -1].
6126 When {expr} is a |List| then the matching item, the index
6127 of first item where {pat} matches, the start position and the
6128 end position of the match are returned. >
6129 :echo matchstrpos([1, '__x'], '\a')
6130< result is ["x", 1, 2, 3].
6131 The type isn't changed, it's not necessarily a String.
6132
6133 Can also be used as a |method|: >
6134 GetText()->matchstrpos('word')
6135<
6136
6137 *max()*
6138max({expr}) Return the maximum value of all items in {expr}. Example: >
6139 echo max([apples, pears, oranges])
6140
6141< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6142 it returns the maximum of all values in the Dictionary.
6143 If {expr} is neither a List nor a Dictionary, or one of the
6144 items in {expr} cannot be used as a Number this results in
6145 an error. An empty |List| or |Dictionary| results in zero.
6146
6147 Can also be used as a |method|: >
6148 mylist->max()
6149
6150
6151menu_info({name} [, {mode}]) *menu_info()*
6152 Return information about the specified menu {name} in
6153 mode {mode}. The menu name should be specified without the
6154 shortcut character ('&'). If {name} is "", then the top-level
6155 menu names are returned.
6156
6157 {mode} can be one of these strings:
6158 "n" Normal
6159 "v" Visual (including Select)
6160 "o" Operator-pending
6161 "i" Insert
6162 "c" Cmd-line
6163 "s" Select
6164 "x" Visual
6165 "t" Terminal-Job
6166 "" Normal, Visual and Operator-pending
6167 "!" Insert and Cmd-line
6168 When {mode} is omitted, the modes for "" are used.
6169
6170 Returns a |Dictionary| containing the following items:
6171 accel menu item accelerator text |menu-text|
6172 display display name (name without '&')
6173 enabled v:true if this menu item is enabled
6174 Refer to |:menu-enable|
6175 icon name of the icon file (for toolbar)
6176 |toolbar-icon|
6177 iconidx index of a built-in icon
6178 modes modes for which the menu is defined. In
6179 addition to the modes mentioned above, these
6180 characters will be used:
6181 " " Normal, Visual and Operator-pending
6182 name menu item name.
6183 noremenu v:true if the {rhs} of the menu item is not
6184 remappable else v:false.
6185 priority menu order priority |menu-priority|
6186 rhs right-hand-side of the menu item. The returned
6187 string has special characters translated like
6188 in the output of the ":menu" command listing.
6189 When the {rhs} of a menu item is empty, then
6190 "<Nop>" is returned.
6191 script v:true if script-local remapping of {rhs} is
6192 allowed else v:false. See |:menu-script|.
6193 shortcut shortcut key (character after '&' in
6194 the menu name) |menu-shortcut|
6195 silent v:true if the menu item is created
6196 with <silent> argument |:menu-silent|
6197 submenus |List| containing the names of
6198 all the submenus. Present only if the menu
6199 item has submenus.
6200
6201 Returns an empty dictionary if the menu item is not found.
6202
6203 Examples: >
6204 :echo menu_info('Edit.Cut')
6205 :echo menu_info('File.Save', 'n')
6206
6207 " Display the entire menu hierarchy in a buffer
6208 func ShowMenu(name, pfx)
6209 let m = menu_info(a:name)
6210 call append(line('$'), a:pfx .. m.display)
6211 for child in m->get('submenus', [])
6212 call ShowMenu(a:name .. '.' .. escape(child, '.'),
6213 \ a:pfx .. ' ')
6214 endfor
6215 endfunc
6216 new
6217 for topmenu in menu_info('').submenus
6218 call ShowMenu(topmenu, '')
6219 endfor
6220<
6221 Can also be used as a |method|: >
6222 GetMenuName()->menu_info('v')
6223
6224
6225< *min()*
6226min({expr}) Return the minimum value of all items in {expr}. Example: >
6227 echo min([apples, pears, oranges])
6228
6229< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
6230 it returns the minimum of all values in the Dictionary.
6231 If {expr} is neither a List nor a Dictionary, or one of the
6232 items in {expr} cannot be used as a Number this results in
6233 an error. An empty |List| or |Dictionary| results in zero.
6234
6235 Can also be used as a |method|: >
6236 mylist->min()
6237
6238< *mkdir()* *E739*
6239mkdir({name} [, {path} [, {prot}]])
6240 Create directory {name}.
6241
Bram Moolenaar6f14da12022-09-07 21:30:44 +01006242 If {path} contains "p" then intermediate directories are
6243 created as necessary. Otherwise it must be "".
6244
6245 If {path} contains "D" then {name} is deleted at the end of
6246 the current function, as with: >
6247 defer delete({name}, 'd')
6248<
6249 If {path} contains "R" then {name} is deleted recursively at
6250 the end of the current function, as with: >
6251 defer delete({name}, 'rf')
6252< Note that when {name} has more than one part and "p" is used
6253 some directories may already exist. Only the first one that
6254 is created and what it contains is scheduled to be deleted.
6255 E.g. when using: >
6256 call mkdir('subdir/tmp/autoload', 'pR')
6257< and "subdir" already exists then "subdir/tmp" will be
6258 scheduled for deletion, like with: >
6259 defer delete('subdir/tmp', 'rf')
6260< Note that if scheduling the defer fails the directory is not
6261 deleted. This should only happen when out of memory.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006262
6263 If {prot} is given it is used to set the protection bits of
6264 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
6265 the user, readable for others). Use 0o700 to make it
6266 unreadable for others. This is only used for the last part of
6267 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
6268 created with 0o755.
6269 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006270 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006271
6272< This function is not available in the |sandbox|.
6273
6274 There is no error if the directory already exists and the "p"
6275 flag is passed (since patch 8.0.1708). However, without the
6276 "p" option the call will fail.
6277
6278 The function result is a Number, which is TRUE if the call was
6279 successful or FALSE if the directory creation failed or partly
6280 failed.
6281
6282 Not available on all systems. To check use: >
6283 :if exists("*mkdir")
6284
6285< Can also be used as a |method|: >
6286 GetName()->mkdir()
6287<
6288 *mode()*
6289mode([expr]) Return a string that indicates the current mode.
6290 If [expr] is supplied and it evaluates to a non-zero Number or
6291 a non-empty String (|non-zero-arg|), then the full mode is
6292 returned, otherwise only the first letter is returned.
6293 Also see |state()|.
6294
6295 n Normal
6296 no Operator-pending
6297 nov Operator-pending (forced characterwise |o_v|)
6298 noV Operator-pending (forced linewise |o_V|)
6299 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
6300 CTRL-V is one character
6301 niI Normal using |i_CTRL-O| in |Insert-mode|
6302 niR Normal using |i_CTRL-O| in |Replace-mode|
6303 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6304 nt Terminal-Normal (insert goes to Terminal-Job mode)
6305 v Visual by character
6306 vs Visual by character using |v_CTRL-O| in Select mode
6307 V Visual by line
6308 Vs Visual by line using |v_CTRL-O| in Select mode
6309 CTRL-V Visual blockwise
6310 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
6311 s Select by character
6312 S Select by line
6313 CTRL-S Select blockwise
6314 i Insert
6315 ic Insert mode completion |compl-generic|
6316 ix Insert mode |i_CTRL-X| completion
6317 R Replace |R|
6318 Rc Replace mode completion |compl-generic|
6319 Rx Replace mode |i_CTRL-X| completion
6320 Rv Virtual Replace |gR|
6321 Rvc Virtual Replace mode completion |compl-generic|
6322 Rvx Virtual Replace mode |i_CTRL-X| completion
6323 c Command-line editing
6324 cv Vim Ex mode |gQ|
6325 ce Normal Ex mode |Q|
6326 r Hit-enter prompt
6327 rm The -- more -- prompt
6328 r? A |:confirm| query of some sort
6329 ! Shell or external command is executing
6330 t Terminal-Job mode: keys go to the job
6331
6332 This is useful in the 'statusline' option or when used
6333 with |remote_expr()| In most other places it always returns
6334 "c" or "n".
6335 Note that in the future more modes and more specific modes may
6336 be added. It's better not to compare the whole string but only
6337 the leading character(s).
6338 Also see |visualmode()|.
6339
6340 Can also be used as a |method|: >
6341 DoFull()->mode()
6342
6343mzeval({expr}) *mzeval()*
6344 Evaluate MzScheme expression {expr} and return its result
6345 converted to Vim data structures.
6346 Numbers and strings are returned as they are.
6347 Pairs (including lists and improper lists) and vectors are
6348 returned as Vim |Lists|.
6349 Hash tables are represented as Vim |Dictionary| type with keys
6350 converted to strings.
6351 All other types are converted to string with display function.
6352 Examples: >
6353 :mz (define l (list 1 2 3))
6354 :mz (define h (make-hash)) (hash-set! h "list" l)
6355 :echo mzeval("l")
6356 :echo mzeval("h")
6357<
6358 Note that in a `:def` function local variables are not visible
6359 to {expr}.
6360
6361 Can also be used as a |method|: >
6362 GetExpr()->mzeval()
6363<
6364 {only available when compiled with the |+mzscheme| feature}
6365
6366nextnonblank({lnum}) *nextnonblank()*
6367 Return the line number of the first line at or below {lnum}
6368 that is not blank. Example: >
6369 if getline(nextnonblank(1)) =~ "Java"
6370< When {lnum} is invalid or there is no non-blank line at or
6371 below it, zero is returned.
6372 {lnum} is used like with |getline()|.
6373 See also |prevnonblank()|.
6374
6375 Can also be used as a |method|: >
6376 GetLnum()->nextnonblank()
6377
6378nr2char({expr} [, {utf8}]) *nr2char()*
6379 Return a string with a single character, which has the number
6380 value {expr}. Examples: >
6381 nr2char(64) returns "@"
6382 nr2char(32) returns " "
6383< When {utf8} is omitted or zero, the current 'encoding' is used.
6384 Example for "utf-8": >
6385 nr2char(300) returns I with bow character
6386< When {utf8} is TRUE, always return UTF-8 characters.
6387 Note that a NUL character in the file is specified with
6388 nr2char(10), because NULs are represented with newline
6389 characters. nr2char(0) is a real NUL and terminates the
6390 string, thus results in an empty string.
6391 To turn a list of character numbers into a string: >
6392 let list = [65, 66, 67]
6393 let str = join(map(list, {_, val -> nr2char(val)}), '')
6394< Result: "ABC"
6395
6396 Can also be used as a |method|: >
6397 GetNumber()->nr2char()
6398
6399or({expr}, {expr}) *or()*
6400 Bitwise OR on the two arguments. The arguments are converted
6401 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006402 Also see `and()` and `xor()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006403 Example: >
6404 :let bits = or(bits, 0x80)
6405< Can also be used as a |method|: >
6406 :let bits = bits->or(0x80)
6407
Bram Moolenaar5a6ec102022-05-27 21:58:00 +01006408< Rationale: The reason this is a function and not using the "|"
6409 character like many languages, is that Vi has always used "|"
6410 to separate commands. In many places it would not be clear if
6411 "|" is an operator or a command separator.
6412
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006413
6414pathshorten({path} [, {len}]) *pathshorten()*
6415 Shorten directory names in the path {path} and return the
6416 result. The tail, the file name, is kept as-is. The other
6417 components in the path are reduced to {len} letters in length.
6418 If {len} is omitted or smaller than 1 then 1 is used (single
6419 letters). Leading '~' and '.' characters are kept. Examples: >
6420 :echo pathshorten('~/.vim/autoload/myfile.vim')
6421< ~/.v/a/myfile.vim ~
6422>
6423 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
6424< ~/.vi/au/myfile.vim ~
6425 It doesn't matter if the path exists or not.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006426 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006427
6428 Can also be used as a |method|: >
6429 GetDirectories()->pathshorten()
6430
6431perleval({expr}) *perleval()*
6432 Evaluate Perl expression {expr} in scalar context and return
6433 its result converted to Vim data structures. If value can't be
6434 converted, it is returned as a string Perl representation.
6435 Note: If you want an array or hash, {expr} must return a
6436 reference to it.
6437 Example: >
6438 :echo perleval('[1 .. 4]')
6439< [1, 2, 3, 4]
6440
6441 Note that in a `:def` function local variables are not visible
6442 to {expr}.
6443
6444 Can also be used as a |method|: >
6445 GetExpr()->perleval()
6446
6447< {only available when compiled with the |+perl| feature}
6448
6449
6450popup_ functions are documented here: |popup-functions|
6451
6452
6453pow({x}, {y}) *pow()*
6454 Return the power of {x} to the exponent {y} as a |Float|.
6455 {x} and {y} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006456 Returns 0.0 if {x} or {y} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006457 Examples: >
6458 :echo pow(3, 3)
6459< 27.0 >
6460 :echo pow(2, 16)
6461< 65536.0 >
6462 :echo pow(32, 0.20)
6463< 2.0
6464
6465 Can also be used as a |method|: >
6466 Compute()->pow(3)
6467<
6468 {only available when compiled with the |+float| feature}
6469
6470prevnonblank({lnum}) *prevnonblank()*
6471 Return the line number of the first line at or above {lnum}
6472 that is not blank. Example: >
6473 let ind = indent(prevnonblank(v:lnum - 1))
6474< When {lnum} is invalid or there is no non-blank line at or
6475 above it, zero is returned.
6476 {lnum} is used like with |getline()|.
6477 Also see |nextnonblank()|.
6478
6479 Can also be used as a |method|: >
6480 GetLnum()->prevnonblank()
6481
6482printf({fmt}, {expr1} ...) *printf()*
6483 Return a String with {fmt}, where "%" items are replaced by
6484 the formatted form of their respective arguments. Example: >
6485 printf("%4d: E%d %.30s", lnum, errno, msg)
6486< May result in:
6487 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6488
6489 When used as a |method| the base is passed as the second
6490 argument: >
6491 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006492<
6493 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006494
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006495 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006496 %s string
6497 %6S string right-aligned in 6 display cells
6498 %6s string right-aligned in 6 bytes
6499 %.9s string truncated to 9 bytes
6500 %c single byte
6501 %d decimal number
6502 %5d decimal number padded with spaces to 5 characters
6503 %x hex number
6504 %04x hex number padded with zeros to at least 4 characters
6505 %X hex number using upper case letters
6506 %o octal number
6507 %08b binary number padded with zeros to at least 8 chars
6508 %f floating point number as 12.23, inf, -inf or nan
6509 %F floating point number as 12.23, INF, -INF or NAN
6510 %e floating point number as 1.23e3, inf, -inf or nan
6511 %E floating point number as 1.23E3, INF, -INF or NAN
6512 %g floating point number, as %f or %e depending on value
6513 %G floating point number, as %F or %E depending on value
6514 %% the % character itself
6515
6516 Conversion specifications start with '%' and end with the
6517 conversion type. All other characters are copied unchanged to
6518 the result.
6519
6520 The "%" starts a conversion specification. The following
6521 arguments appear in sequence:
6522
6523 % [flags] [field-width] [.precision] type
6524
6525 flags
6526 Zero or more of the following flags:
6527
6528 # The value should be converted to an "alternate
6529 form". For c, d, and s conversions, this option
6530 has no effect. For o conversions, the precision
6531 of the number is increased to force the first
6532 character of the output string to a zero (except
6533 if a zero value is printed with an explicit
6534 precision of zero).
6535 For b and B conversions, a non-zero result has
6536 the string "0b" (or "0B" for B conversions)
6537 prepended to it.
6538 For x and X conversions, a non-zero result has
6539 the string "0x" (or "0X" for X conversions)
6540 prepended to it.
6541
6542 0 (zero) Zero padding. For all conversions the converted
6543 value is padded on the left with zeros rather
6544 than blanks. If a precision is given with a
6545 numeric conversion (d, b, B, o, x, and X), the 0
6546 flag is ignored.
6547
6548 - A negative field width flag; the converted value
6549 is to be left adjusted on the field boundary.
6550 The converted value is padded on the right with
6551 blanks, rather than on the left with blanks or
6552 zeros. A - overrides a 0 if both are given.
6553
6554 ' ' (space) A blank should be left before a positive
6555 number produced by a signed conversion (d).
6556
6557 + A sign must always be placed before a number
6558 produced by a signed conversion. A + overrides
6559 a space if both are used.
6560
6561 field-width
6562 An optional decimal digit string specifying a minimum
6563 field width. If the converted value has fewer bytes
6564 than the field width, it will be padded with spaces on
6565 the left (or right, if the left-adjustment flag has
6566 been given) to fill out the field width. For the S
6567 conversion the count is in cells.
6568
6569 .precision
6570 An optional precision, in the form of a period '.'
6571 followed by an optional digit string. If the digit
6572 string is omitted, the precision is taken as zero.
6573 This gives the minimum number of digits to appear for
6574 d, o, x, and X conversions, the maximum number of
6575 bytes to be printed from a string for s conversions,
6576 or the maximum number of cells to be printed from a
6577 string for S conversions.
6578 For floating point it is the number of digits after
6579 the decimal point.
6580
6581 type
6582 A character that specifies the type of conversion to
6583 be applied, see below.
6584
6585 A field width or precision, or both, may be indicated by an
6586 asterisk '*' instead of a digit string. In this case, a
6587 Number argument supplies the field width or precision. A
6588 negative field width is treated as a left adjustment flag
6589 followed by a positive field width; a negative precision is
6590 treated as though it were missing. Example: >
6591 :echo printf("%d: %.*s", nr, width, line)
6592< This limits the length of the text used from "line" to
6593 "width" bytes.
6594
6595 The conversion specifiers and their meanings are:
6596
6597 *printf-d* *printf-b* *printf-B* *printf-o*
6598 *printf-x* *printf-X*
6599 dbBoxX The Number argument is converted to signed decimal
6600 (d), unsigned binary (b and B), unsigned octal (o), or
6601 unsigned hexadecimal (x and X) notation. The letters
6602 "abcdef" are used for x conversions; the letters
6603 "ABCDEF" are used for X conversions.
6604 The precision, if any, gives the minimum number of
6605 digits that must appear; if the converted value
6606 requires fewer digits, it is padded on the left with
6607 zeros.
6608 In no case does a non-existent or small field width
6609 cause truncation of a numeric field; if the result of
6610 a conversion is wider than the field width, the field
6611 is expanded to contain the conversion result.
6612 The 'h' modifier indicates the argument is 16 bits.
6613 The 'l' modifier indicates the argument is 32 bits.
6614 The 'L' modifier indicates the argument is 64 bits.
6615 Generally, these modifiers are not useful. They are
6616 ignored when type is known from the argument.
6617
6618 i alias for d
6619 D alias for ld
6620 U alias for lu
6621 O alias for lo
6622
6623 *printf-c*
6624 c The Number argument is converted to a byte, and the
6625 resulting character is written.
6626
6627 *printf-s*
6628 s The text of the String argument is used. If a
6629 precision is specified, no more bytes than the number
6630 specified are used.
6631 If the argument is not a String type, it is
6632 automatically converted to text with the same format
6633 as ":echo".
6634 *printf-S*
6635 S The text of the String argument is used. If a
6636 precision is specified, no more display cells than the
6637 number specified are used.
6638
6639 *printf-f* *E807*
6640 f F The Float argument is converted into a string of the
6641 form 123.456. The precision specifies the number of
6642 digits after the decimal point. When the precision is
6643 zero the decimal point is omitted. When the precision
6644 is not specified 6 is used. A really big number
6645 (out of range or dividing by zero) results in "inf"
6646 or "-inf" with %f (INF or -INF with %F).
6647 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6648 Example: >
6649 echo printf("%.2f", 12.115)
6650< 12.12
6651 Note that roundoff depends on the system libraries.
6652 Use |round()| when in doubt.
6653
6654 *printf-e* *printf-E*
6655 e E The Float argument is converted into a string of the
6656 form 1.234e+03 or 1.234E+03 when using 'E'. The
6657 precision specifies the number of digits after the
6658 decimal point, like with 'f'.
6659
6660 *printf-g* *printf-G*
6661 g G The Float argument is converted like with 'f' if the
6662 value is between 0.001 (inclusive) and 10000000.0
6663 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6664 for 'G'. When no precision is specified superfluous
6665 zeroes and '+' signs are removed, except for the zero
6666 immediately after the decimal point. Thus 10000000.0
6667 results in 1.0e7.
6668
6669 *printf-%*
6670 % A '%' is written. No argument is converted. The
6671 complete conversion specification is "%%".
6672
6673 When a Number argument is expected a String argument is also
6674 accepted and automatically converted.
6675 When a Float or String argument is expected a Number argument
6676 is also accepted and automatically converted.
6677 Any other argument type results in an error message.
6678
6679 *E766* *E767*
6680 The number of {exprN} arguments must exactly match the number
6681 of "%" items. If there are not sufficient or too many
6682 arguments an error is given. Up to 18 arguments can be used.
6683
6684
6685prompt_getprompt({buf}) *prompt_getprompt()*
6686 Returns the effective prompt text for buffer {buf}. {buf} can
6687 be a buffer name or number. See |prompt-buffer|.
6688
6689 If the buffer doesn't exist or isn't a prompt buffer, an empty
6690 string is returned.
6691
6692 Can also be used as a |method|: >
6693 GetBuffer()->prompt_getprompt()
6694
6695< {only available when compiled with the |+channel| feature}
6696
6697
6698prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6699 Set prompt callback for buffer {buf} to {expr}. When {expr}
6700 is an empty string the callback is removed. This has only
6701 effect if {buf} has 'buftype' set to "prompt".
6702
6703 The callback is invoked when pressing Enter. The current
6704 buffer will always be the prompt buffer. A new line for a
6705 prompt is added before invoking the callback, thus the prompt
6706 for which the callback was invoked will be in the last but one
6707 line.
6708 If the callback wants to add text to the buffer, it must
6709 insert it above the last line, since that is where the current
6710 prompt is. This can also be done asynchronously.
6711 The callback is invoked with one argument, which is the text
6712 that was entered at the prompt. This can be an empty string
6713 if the user only typed Enter.
6714 Example: >
6715 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6716 func s:TextEntered(text)
6717 if a:text == 'exit' || a:text == 'quit'
6718 stopinsert
6719 close
6720 else
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006721 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006722 " Reset 'modified' to allow the buffer to be closed.
6723 set nomodified
6724 endif
6725 endfunc
6726
6727< Can also be used as a |method|: >
6728 GetBuffer()->prompt_setcallback(callback)
6729
6730< {only available when compiled with the |+channel| feature}
6731
6732prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6733 Set a callback for buffer {buf} to {expr}. When {expr} is an
6734 empty string the callback is removed. This has only effect if
6735 {buf} has 'buftype' set to "prompt".
6736
6737 This callback will be invoked when pressing CTRL-C in Insert
6738 mode. Without setting a callback Vim will exit Insert mode,
6739 as in any buffer.
6740
6741 Can also be used as a |method|: >
6742 GetBuffer()->prompt_setinterrupt(callback)
6743
6744< {only available when compiled with the |+channel| feature}
6745
6746prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6747 Set prompt for buffer {buf} to {text}. You most likely want
6748 {text} to end in a space.
6749 The result is only visible if {buf} has 'buftype' set to
6750 "prompt". Example: >
6751 call prompt_setprompt(bufnr(), 'command: ')
6752<
6753 Can also be used as a |method|: >
6754 GetBuffer()->prompt_setprompt('command: ')
6755
6756< {only available when compiled with the |+channel| feature}
6757
6758prop_ functions are documented here: |text-prop-functions|
6759
6760pum_getpos() *pum_getpos()*
6761 If the popup menu (see |ins-completion-menu|) is not visible,
6762 returns an empty |Dictionary|, otherwise, returns a
6763 |Dictionary| with the following keys:
6764 height nr of items visible
6765 width screen cells
6766 row top screen row (0 first row)
6767 col leftmost screen column (0 first col)
6768 size total nr of items
6769 scrollbar |TRUE| if scrollbar is visible
6770
6771 The values are the same as in |v:event| during
6772 |CompleteChanged|.
6773
6774pumvisible() *pumvisible()*
6775 Returns non-zero when the popup menu is visible, zero
6776 otherwise. See |ins-completion-menu|.
6777 This can be used to avoid some things that would remove the
6778 popup menu.
6779
6780py3eval({expr}) *py3eval()*
6781 Evaluate Python expression {expr} and return its result
6782 converted to Vim data structures.
6783 Numbers and strings are returned as they are (strings are
6784 copied though, Unicode strings are additionally converted to
6785 'encoding').
6786 Lists are represented as Vim |List| type.
6787 Dictionaries are represented as Vim |Dictionary| type with
6788 keys converted to strings.
6789 Note that in a `:def` function local variables are not visible
6790 to {expr}.
6791
6792 Can also be used as a |method|: >
6793 GetExpr()->py3eval()
6794
6795< {only available when compiled with the |+python3| feature}
6796
6797 *E858* *E859*
6798pyeval({expr}) *pyeval()*
6799 Evaluate Python expression {expr} and return its result
6800 converted to Vim data structures.
6801 Numbers and strings are returned as they are (strings are
6802 copied though).
6803 Lists are represented as Vim |List| type.
6804 Dictionaries are represented as Vim |Dictionary| type,
6805 non-string keys result in error.
6806 Note that in a `:def` function local variables are not visible
6807 to {expr}.
6808
6809 Can also be used as a |method|: >
6810 GetExpr()->pyeval()
6811
6812< {only available when compiled with the |+python| feature}
6813
6814pyxeval({expr}) *pyxeval()*
6815 Evaluate Python expression {expr} and return its result
6816 converted to Vim data structures.
6817 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6818 See also: |pyeval()|, |py3eval()|
6819
6820 Can also be used as a |method|: >
6821 GetExpr()->pyxeval()
6822
6823< {only available when compiled with the |+python| or the
6824 |+python3| feature}
6825
6826rand([{expr}]) *rand()* *random*
6827 Return a pseudo-random Number generated with an xoshiro128**
6828 algorithm using seed {expr}. The returned number is 32 bits,
6829 also on 64 bits systems, for consistency.
6830 {expr} can be initialized by |srand()| and will be updated by
6831 rand(). If {expr} is omitted, an internal seed value is used
6832 and updated.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006833 Returns -1 if {expr} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006834
6835 Examples: >
6836 :echo rand()
6837 :let seed = srand()
6838 :echo rand(seed)
6839 :echo rand(seed) % 16 " random number 0 - 15
6840<
6841
6842 *E726* *E727*
6843range({expr} [, {max} [, {stride}]]) *range()*
6844 Returns a |List| with Numbers:
6845 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6846 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6847 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6848 {max}] (increasing {expr} with {stride} each time, not
6849 producing a value past {max}).
6850 When the maximum is one before the start the result is an
6851 empty list. When the maximum is more than one before the
6852 start this is an error.
6853 Examples: >
6854 range(4) " [0, 1, 2, 3]
6855 range(2, 4) " [2, 3, 4]
6856 range(2, 9, 3) " [2, 5, 8]
6857 range(2, -2, -1) " [2, 1, 0, -1, -2]
6858 range(0) " []
6859 range(2, 0) " error!
6860<
6861 Can also be used as a |method|: >
6862 GetExpr()->range()
6863<
6864
6865readblob({fname}) *readblob()*
6866 Read file {fname} in binary mode and return a |Blob|.
6867 When the file can't be opened an error message is given and
6868 the result is an empty |Blob|.
6869 Also see |readfile()| and |writefile()|.
6870
6871
6872readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6873 Return a list with file and directory names in {directory}.
6874 You can also use |glob()| if you don't need to do complicated
6875 things, such as limiting the number of matches.
6876 The list will be sorted (case sensitive), see the {dict}
6877 argument below for changing the sort order.
6878
6879 When {expr} is omitted all entries are included.
6880 When {expr} is given, it is evaluated to check what to do:
6881 If {expr} results in -1 then no further entries will
6882 be handled.
6883 If {expr} results in 0 then this entry will not be
6884 added to the list.
6885 If {expr} results in 1 then this entry will be added
6886 to the list.
6887 The entries "." and ".." are always excluded.
6888 Each time {expr} is evaluated |v:val| is set to the entry name.
6889 When {expr} is a function the name is passed as the argument.
6890 For example, to get a list of files ending in ".txt": >
6891 readdir(dirname, {n -> n =~ '.txt$'})
6892< To skip hidden and backup files: >
6893 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00006894< *E857*
6895 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006896 values. Currently this is used to specify if and how sorting
6897 should be performed. The dict can have the following members:
6898
6899 sort How to sort the result returned from the system.
6900 Valid values are:
6901 "none" do not sort (fastest method)
6902 "case" sort case sensitive (byte value of
6903 each character, technically, using
6904 strcmp()) (default)
6905 "icase" sort case insensitive (technically
6906 using strcasecmp())
6907 "collate" sort using the collation order
6908 of the "POSIX" or "C" |locale|
6909 (technically using strcoll())
6910 Other values are silently ignored.
6911
6912 For example, to get a list of all files in the current
6913 directory without sorting the individual entries: >
6914 readdir('.', '1', #{sort: 'none'})
6915< If you want to get a directory tree: >
6916 function! s:tree(dir)
6917 return {a:dir : map(readdir(a:dir),
6918 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006919 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006920 endfunction
6921 echo s:tree(".")
6922<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01006923 Returns an empty List on error.
6924
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006925 Can also be used as a |method|: >
6926 GetDirName()->readdir()
6927<
6928readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6929 Extended version of |readdir()|.
6930 Return a list of Dictionaries with file and directory
6931 information in {directory}.
6932 This is useful if you want to get the attributes of file and
6933 directory at the same time as getting a list of a directory.
6934 This is much faster than calling |readdir()| then calling
6935 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6936 each file and directory especially on MS-Windows.
6937 The list will by default be sorted by name (case sensitive),
6938 the sorting can be changed by using the optional {dict}
6939 argument, see |readdir()|.
6940
6941 The Dictionary for file and directory information has the
6942 following items:
6943 group Group name of the entry. (Only on Unix)
6944 name Name of the entry.
6945 perm Permissions of the entry. See |getfperm()|.
6946 size Size of the entry. See |getfsize()|.
6947 time Timestamp of the entry. See |getftime()|.
6948 type Type of the entry.
6949 On Unix, almost same as |getftype()| except:
6950 Symlink to a dir "linkd"
6951 Other symlink "link"
6952 On MS-Windows:
6953 Normal file "file"
6954 Directory "dir"
6955 Junction "junction"
6956 Symlink to a dir "linkd"
6957 Other symlink "link"
6958 Other reparse point "reparse"
6959 user User name of the entry's owner. (Only on Unix)
6960 On Unix, if the entry is a symlink, the Dictionary includes
6961 the information of the target (except the "type" item).
6962 On MS-Windows, it includes the information of the symlink
6963 itself because of performance reasons.
6964
6965 When {expr} is omitted all entries are included.
6966 When {expr} is given, it is evaluated to check what to do:
6967 If {expr} results in -1 then no further entries will
6968 be handled.
6969 If {expr} results in 0 then this entry will not be
6970 added to the list.
6971 If {expr} results in 1 then this entry will be added
6972 to the list.
6973 The entries "." and ".." are always excluded.
6974 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6975 of the entry.
6976 When {expr} is a function the entry is passed as the argument.
6977 For example, to get a list of files ending in ".txt": >
6978 readdirex(dirname, {e -> e.name =~ '.txt$'})
6979<
6980 For example, to get a list of all files in the current
6981 directory without sorting the individual entries: >
6982 readdirex(dirname, '1', #{sort: 'none'})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006983<
6984 Can also be used as a |method|: >
6985 GetDirName()->readdirex()
6986<
6987
6988 *readfile()*
6989readfile({fname} [, {type} [, {max}]])
6990 Read file {fname} and return a |List|, each line of the file
6991 as an item. Lines are broken at NL characters. Macintosh
6992 files separated with CR will result in a single long line
6993 (unless a NL appears somewhere).
6994 All NUL characters are replaced with a NL character.
6995 When {type} contains "b" binary mode is used:
6996 - When the last line ends in a NL an extra empty list item is
6997 added.
6998 - No CR characters are removed.
6999 Otherwise:
7000 - CR characters that appear before a NL are removed.
7001 - Whether the last line ends in a NL or not does not matter.
7002 - When 'encoding' is Unicode any UTF-8 byte order mark is
7003 removed from the text.
7004 When {max} is given this specifies the maximum number of lines
7005 to be read. Useful if you only want to check the first ten
7006 lines of a file: >
7007 :for line in readfile(fname, '', 10)
7008 : if line =~ 'Date' | echo line | endif
7009 :endfor
7010< When {max} is negative -{max} lines from the end of the file
7011 are returned, or as many as there are.
7012 When {max} is zero the result is an empty list.
7013 Note that without {max} the whole file is read into memory.
7014 Also note that there is no recognition of encoding. Read a
7015 file into a buffer if you need to.
7016 Deprecated (use |readblob()| instead): When {type} contains
7017 "B" a |Blob| is returned with the binary data of the file
7018 unmodified.
7019 When the file can't be opened an error message is given and
7020 the result is an empty list.
7021 Also see |writefile()|.
7022
7023 Can also be used as a |method|: >
7024 GetFileName()->readfile()
7025
7026reduce({object}, {func} [, {initial}]) *reduce()* *E998*
7027 {func} is called for every item in {object}, which can be a
7028 |String|, |List| or a |Blob|. {func} is called with two
7029 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007030 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007031
7032 {initial} is the initial result. When omitted, the first item
7033 in {object} is used and {func} is first called for the second
7034 item. If {initial} is not given and {object} is empty no
7035 result can be computed, an E998 error is given.
7036
7037 Examples: >
7038 echo reduce([1, 3, 5], { acc, val -> acc + val })
7039 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
7040 echo reduce(0z1122, { acc, val -> 2 * acc + val })
7041 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
7042<
7043 Can also be used as a |method|: >
7044 echo mylist->reduce({ acc, val -> acc + val }, 0)
7045
7046
7047reg_executing() *reg_executing()*
7048 Returns the single letter name of the register being executed.
7049 Returns an empty string when no register is being executed.
7050 See |@|.
7051
7052reg_recording() *reg_recording()*
7053 Returns the single letter name of the register being recorded.
7054 Returns an empty string when not recording. See |q|.
7055
7056reltime([{start} [, {end}]]) *reltime()*
7057 Return an item that represents a time value. The item is a
7058 list with items that depend on the system. In Vim 9 script
7059 list<any> can be used.
7060 The item can be passed to |reltimestr()| to convert it to a
7061 string or |reltimefloat()| to convert to a Float.
7062
Bram Moolenaar016188f2022-06-06 20:52:59 +01007063 Without an argument reltime() returns the current time (the
Bram Moolenaareb490412022-06-28 13:44:46 +01007064 representation is system-dependent, it can not be used as the
Bram Moolenaar016188f2022-06-06 20:52:59 +01007065 wall-clock time, see |localtime()| for that).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007066 With one argument is returns the time passed since the time
7067 specified in the argument.
7068 With two arguments it returns the time passed between {start}
7069 and {end}.
7070
7071 The {start} and {end} arguments must be values returned by
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007072 reltime(). If there is an error an empty List is returned in
7073 legacy script, in Vim9 script an error is given.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007074
7075 Can also be used as a |method|: >
7076 GetStart()->reltime()
7077<
7078 {only available when compiled with the |+reltime| feature}
7079
7080reltimefloat({time}) *reltimefloat()*
7081 Return a Float that represents the time value of {time}.
7082 Example: >
7083 let start = reltime()
7084 call MyFunction()
7085 let seconds = reltimefloat(reltime(start))
7086< See the note of reltimestr() about overhead.
7087 Also see |profiling|.
7088 If there is an error 0.0 is returned in legacy script, in Vim9
7089 script an error is given.
7090
7091 Can also be used as a |method|: >
7092 reltime(start)->reltimefloat()
7093
7094< {only available when compiled with the |+reltime| feature}
7095
7096reltimestr({time}) *reltimestr()*
7097 Return a String that represents the time value of {time}.
7098 This is the number of seconds, a dot and the number of
7099 microseconds. Example: >
7100 let start = reltime()
7101 call MyFunction()
7102 echo reltimestr(reltime(start))
7103< Note that overhead for the commands will be added to the time.
7104 The accuracy depends on the system.
7105 Leading spaces are used to make the string align nicely. You
7106 can use split() to remove it. >
7107 echo split(reltimestr(reltime(start)))[0]
7108< Also see |profiling|.
7109 If there is an error an empty string is returned in legacy
7110 script, in Vim9 script an error is given.
7111
7112 Can also be used as a |method|: >
7113 reltime(start)->reltimestr()
7114
7115< {only available when compiled with the |+reltime| feature}
7116
7117 *remote_expr()* *E449*
7118remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007119 Send the {string} to {server}. The {server} argument is a
7120 string, also see |{server}|.
7121
7122 The string is sent as an expression and the result is returned
7123 after evaluation. The result must be a String or a |List|. A
7124 |List| is turned into a String by joining the items with a
7125 line break in between (not at the end), like with join(expr,
7126 "\n").
7127
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007128 If {idvar} is present and not empty, it is taken as the name
7129 of a variable and a {serverid} for later use with
7130 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007131
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007132 If {timeout} is given the read times out after this many
7133 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007134
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007135 See also |clientserver| |RemoteReply|.
7136 This function is not available in the |sandbox|.
7137 {only available when compiled with the |+clientserver| feature}
7138 Note: Any errors will cause a local error message to be issued
7139 and the result will be the empty string.
7140
7141 Variables will be evaluated in the global namespace,
7142 independent of a function currently being active. Except
7143 when in debug mode, then local function variables and
7144 arguments can be evaluated.
7145
7146 Examples: >
7147 :echo remote_expr("gvim", "2+2")
7148 :echo remote_expr("gvim1", "b:current_syntax")
7149<
7150 Can also be used as a |method|: >
7151 ServerName()->remote_expr(expr)
7152
7153remote_foreground({server}) *remote_foreground()*
7154 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007155 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007156 This works like: >
7157 remote_expr({server}, "foreground()")
7158< Except that on Win32 systems the client does the work, to work
7159 around the problem that the OS doesn't always allow the server
7160 to bring itself to the foreground.
7161 Note: This does not restore the window if it was minimized,
7162 like foreground() does.
7163 This function is not available in the |sandbox|.
7164
7165 Can also be used as a |method|: >
7166 ServerName()->remote_foreground()
7167
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007168< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007169 Win32 console version}
7170
7171
7172remote_peek({serverid} [, {retvar}]) *remote_peek()*
7173 Returns a positive number if there are available strings
7174 from {serverid}. Copies any reply string into the variable
7175 {retvar} if specified. {retvar} must be a string with the
7176 name of a variable.
7177 Returns zero if none are available.
7178 Returns -1 if something is wrong.
7179 See also |clientserver|.
7180 This function is not available in the |sandbox|.
7181 {only available when compiled with the |+clientserver| feature}
7182 Examples: >
7183 :let repl = ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007184 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007185
7186< Can also be used as a |method|: >
7187 ServerId()->remote_peek()
7188
7189remote_read({serverid}, [{timeout}]) *remote_read()*
7190 Return the oldest available reply from {serverid} and consume
7191 it. Unless a {timeout} in seconds is given, it blocks until a
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007192 reply is available. Returns an empty string, if a reply is
7193 not available or on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007194 See also |clientserver|.
7195 This function is not available in the |sandbox|.
7196 {only available when compiled with the |+clientserver| feature}
7197 Example: >
7198 :echo remote_read(id)
7199
7200< Can also be used as a |method|: >
7201 ServerId()->remote_read()
7202<
7203 *remote_send()* *E241*
7204remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00007205 Send the {string} to {server}. The {server} argument is a
7206 string, also see |{server}|.
7207
7208 The string is sent as input keys and the function returns
7209 immediately. At the Vim server the keys are not mapped
7210 |:map|.
7211
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007212 If {idvar} is present, it is taken as the name of a variable
7213 and a {serverid} for later use with remote_read() is stored
7214 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007215
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007216 See also |clientserver| |RemoteReply|.
7217 This function is not available in the |sandbox|.
7218 {only available when compiled with the |+clientserver| feature}
7219
7220 Note: Any errors will be reported in the server and may mess
7221 up the display.
7222 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007223 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007224 \ remote_read(serverid)
7225
7226 :autocmd NONE RemoteReply *
7227 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007228 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007229 \ 'server2client(expand("<client>"), "HELLO")<CR>')
7230<
7231 Can also be used as a |method|: >
7232 ServerName()->remote_send(keys)
7233<
7234 *remote_startserver()* *E941* *E942*
7235remote_startserver({name})
7236 Become the server {name}. This fails if already running as a
7237 server, when |v:servername| is not empty.
7238
7239 Can also be used as a |method|: >
7240 ServerName()->remote_startserver()
7241
7242< {only available when compiled with the |+clientserver| feature}
7243
7244remove({list}, {idx} [, {end}]) *remove()*
7245 Without {end}: Remove the item at {idx} from |List| {list} and
7246 return the item.
7247 With {end}: Remove items from {idx} to {end} (inclusive) and
7248 return a |List| with these items. When {idx} points to the same
7249 item as {end} a list with one item is returned. When {end}
7250 points to an item before {idx} this is an error.
7251 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007252 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007253 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007254 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007255 :call remove(mylist, 0, 9)
7256<
7257 Use |delete()| to remove a file.
7258
7259 Can also be used as a |method|: >
7260 mylist->remove(idx)
7261
7262remove({blob}, {idx} [, {end}])
7263 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7264 return the byte.
7265 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7266 return a |Blob| with these bytes. When {idx} points to the same
7267 byte as {end} a |Blob| with one byte is returned. When {end}
7268 points to a byte before {idx} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007269 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007270 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007271 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007272 :call remove(mylist, 0, 9)
7273
7274remove({dict}, {key})
7275 Remove the entry from {dict} with key {key} and return it.
7276 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007277 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007278< If there is no {key} in {dict} this is an error.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007279 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007280
7281rename({from}, {to}) *rename()*
7282 Rename the file by the name {from} to the name {to}. This
7283 should also work to move files across file systems. The
7284 result is a Number, which is 0 if the file was renamed
7285 successfully, and non-zero when the renaming failed.
7286 NOTE: If {to} exists it is overwritten without warning.
7287 This function is not available in the |sandbox|.
7288
7289 Can also be used as a |method|: >
7290 GetOldName()->rename(newname)
7291
7292repeat({expr}, {count}) *repeat()*
7293 Repeat {expr} {count} times and return the concatenated
7294 result. Example: >
7295 :let separator = repeat('-', 80)
7296< When {count} is zero or negative the result is empty.
7297 When {expr} is a |List| the result is {expr} concatenated
7298 {count} times. Example: >
7299 :let longlist = repeat(['a', 'b'], 3)
7300< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
7301
7302 Can also be used as a |method|: >
7303 mylist->repeat(count)
7304
7305resolve({filename}) *resolve()* *E655*
7306 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7307 returns the path the shortcut points to in a simplified form.
7308 When {filename} is a symbolic link or junction point, return
7309 the full path to the target. If the target of junction is
7310 removed, return {filename}.
7311 On Unix, repeat resolving symbolic links in all path
7312 components of {filename} and return the simplified result.
7313 To cope with link cycles, resolving of symbolic links is
7314 stopped after 100 iterations.
7315 On other systems, return the simplified {filename}.
7316 The simplification step is done as by |simplify()|.
7317 resolve() keeps a leading path component specifying the
7318 current directory (provided the result is still a relative
7319 path name) and also keeps a trailing path separator.
7320
7321 Can also be used as a |method|: >
7322 GetName()->resolve()
7323
7324reverse({object}) *reverse()*
7325 Reverse the order of items in {object} in-place.
7326 {object} can be a |List| or a |Blob|.
7327 Returns {object}.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007328 Returns zero if {object} is not a List or a Blob.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007329 If you want an object to remain unmodified make a copy first: >
7330 :let revlist = reverse(copy(mylist))
7331< Can also be used as a |method|: >
7332 mylist->reverse()
7333
7334round({expr}) *round()*
7335 Round off {expr} to the nearest integral value and return it
7336 as a |Float|. If {expr} lies halfway between two integral
7337 values, then use the larger one (away from zero).
7338 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007339 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007340 Examples: >
7341 echo round(0.456)
7342< 0.0 >
7343 echo round(4.5)
7344< 5.0 >
7345 echo round(-4.5)
7346< -5.0
7347
7348 Can also be used as a |method|: >
7349 Compute()->round()
7350<
7351 {only available when compiled with the |+float| feature}
7352
7353rubyeval({expr}) *rubyeval()*
7354 Evaluate Ruby expression {expr} and return its result
7355 converted to Vim data structures.
7356 Numbers, floats and strings are returned as they are (strings
7357 are copied though).
7358 Arrays are represented as Vim |List| type.
7359 Hashes are represented as Vim |Dictionary| type.
7360 Other objects are represented as strings resulted from their
7361 "Object#to_s" method.
7362 Note that in a `:def` function local variables are not visible
7363 to {expr}.
7364
7365 Can also be used as a |method|: >
7366 GetRubyExpr()->rubyeval()
7367
7368< {only available when compiled with the |+ruby| feature}
7369
7370screenattr({row}, {col}) *screenattr()*
7371 Like |screenchar()|, but return the attribute. This is a rather
7372 arbitrary number that can only be used to compare to the
7373 attribute at other positions.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007374 Returns -1 when row or col is out of range.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007375
7376 Can also be used as a |method|: >
7377 GetRow()->screenattr(col)
7378
7379screenchar({row}, {col}) *screenchar()*
7380 The result is a Number, which is the character at position
7381 [row, col] on the screen. This works for every possible
7382 screen position, also status lines, window separators and the
7383 command line. The top left position is row one, column one
7384 The character excludes composing characters. For double-byte
7385 encodings it may only be the first byte.
7386 This is mainly to be used for testing.
7387 Returns -1 when row or col is out of range.
7388
7389 Can also be used as a |method|: >
7390 GetRow()->screenchar(col)
7391
7392screenchars({row}, {col}) *screenchars()*
7393 The result is a |List| of Numbers. The first number is the same
7394 as what |screenchar()| returns. Further numbers are
7395 composing characters on top of the base character.
7396 This is mainly to be used for testing.
7397 Returns an empty List when row or col is out of range.
7398
7399 Can also be used as a |method|: >
7400 GetRow()->screenchars(col)
7401
7402screencol() *screencol()*
7403 The result is a Number, which is the current screen column of
7404 the cursor. The leftmost column has number 1.
7405 This function is mainly used for testing.
7406
7407 Note: Always returns the current screen column, thus if used
7408 in a command (e.g. ":echo screencol()") it will return the
7409 column inside the command line, which is 1 when the command is
7410 executed. To get the cursor position in the file use one of
7411 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007412 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007413 nnoremap <silent> GG :echom screencol()<CR>
7414 nnoremap GG <Cmd>echom screencol()<CR>
7415<
7416screenpos({winid}, {lnum}, {col}) *screenpos()*
7417 The result is a Dict with the screen position of the text
7418 character in window {winid} at buffer line {lnum} and column
7419 {col}. {col} is a one-based byte index.
7420 The Dict has these members:
7421 row screen row
7422 col first screen column
7423 endcol last screen column
7424 curscol cursor screen column
7425 If the specified position is not visible, all values are zero.
7426 The "endcol" value differs from "col" when the character
7427 occupies more than one screen cell. E.g. for a Tab "col" can
7428 be 1 and "endcol" can be 8.
7429 The "curscol" value is where the cursor would be placed. For
7430 a Tab it would be the same as "endcol", while for a double
7431 width character it would be the same as "col".
7432 The |conceal| feature is ignored here, the column numbers are
7433 as if 'conceallevel' is zero. You can set the cursor to the
7434 right position and use |screencol()| to get the value with
7435 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00007436 If the position is in a closed fold the screen position of the
7437 first character is returned, {col} is not used.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01007438 Returns an empty Dict if {winid} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007439
7440 Can also be used as a |method|: >
7441 GetWinid()->screenpos(lnum, col)
7442
7443screenrow() *screenrow()*
7444 The result is a Number, which is the current screen row of the
7445 cursor. The top line has number one.
7446 This function is mainly used for testing.
7447 Alternatively you can use |winline()|.
7448
7449 Note: Same restrictions as with |screencol()|.
7450
7451screenstring({row}, {col}) *screenstring()*
7452 The result is a String that contains the base character and
7453 any composing characters at position [row, col] on the screen.
7454 This is like |screenchars()| but returning a String with the
7455 characters.
7456 This is mainly to be used for testing.
7457 Returns an empty String when row or col is out of range.
7458
7459 Can also be used as a |method|: >
7460 GetRow()->screenstring(col)
7461<
7462 *search()*
7463search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7464 Search for regexp pattern {pattern}. The search starts at the
7465 cursor position (you can use |cursor()| to set it).
7466
7467 When a match has been found its line number is returned.
7468 If there is no match a 0 is returned and the cursor doesn't
7469 move. No error message is given.
7470
7471 {flags} is a String, which can contain these character flags:
7472 'b' search Backward instead of forward
7473 'c' accept a match at the Cursor position
7474 'e' move to the End of the match
7475 'n' do Not move the cursor
7476 'p' return number of matching sub-Pattern (see below)
7477 's' Set the ' mark at the previous location of the cursor
7478 'w' Wrap around the end of the file
7479 'W' don't Wrap around the end of the file
7480 'z' start searching at the cursor column instead of zero
7481 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7482
7483 If the 's' flag is supplied, the ' mark is set, only if the
7484 cursor is moved. The 's' flag cannot be combined with the 'n'
7485 flag.
7486
7487 'ignorecase', 'smartcase' and 'magic' are used.
7488
7489 When the 'z' flag is not given, forward searching always
7490 starts in column zero and then matches before the cursor are
7491 skipped. When the 'c' flag is present in 'cpo' the next
7492 search starts after the match. Without the 'c' flag the next
Bram Moolenaarfd999452022-08-24 18:30:14 +01007493 search starts one column after the start of the match. This
7494 matters for overlapping matches. See |cpo-c|. You can also
7495 insert "\ze" to change where the match ends, see |/\ze|.
7496
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007497 When searching backwards and the 'z' flag is given then the
7498 search starts in column zero, thus no match in the current
7499 line will be found (unless wrapping around the end of the
7500 file).
7501
7502 When the {stopline} argument is given then the search stops
7503 after searching this line. This is useful to restrict the
7504 search to a range of lines. Examples: >
7505 let match = search('(', 'b', line("w0"))
7506 let end = search('END', '', line("w$"))
7507< When {stopline} is used and it is not zero this also implies
7508 that the search does not wrap around the end of the file.
7509 A zero value is equal to not giving the argument.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01007510 *E1285* *E1286* *E1287* *E1288* *E1289*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007511 When the {timeout} argument is given the search stops when
7512 more than this many milliseconds have passed. Thus when
7513 {timeout} is 500 the search stops after half a second.
7514 The value must not be negative. A zero value is like not
7515 giving the argument.
7516 {only available when compiled with the |+reltime| feature}
7517
7518 If the {skip} expression is given it is evaluated with the
7519 cursor positioned on the start of a match. If it evaluates to
7520 non-zero this match is skipped. This can be used, for
7521 example, to skip a match in a comment or a string.
7522 {skip} can be a string, which is evaluated as an expression, a
7523 function reference or a lambda.
7524 When {skip} is omitted or empty, every match is accepted.
7525 When evaluating {skip} causes an error the search is aborted
7526 and -1 returned.
7527 *search()-sub-match*
7528 With the 'p' flag the returned value is one more than the
7529 first sub-match in \(\). One if none of them matched but the
7530 whole pattern did match.
7531 To get the column number too use |searchpos()|.
7532
7533 The cursor will be positioned at the match, unless the 'n'
7534 flag is used.
7535
7536 Example (goes over all files in the argument list): >
7537 :let n = 1
7538 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007539 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007540 : " start at the last char in the file and wrap for the
7541 : " first search to find match at start of file
7542 : normal G$
7543 : let flags = "w"
7544 : while search("foo", flags) > 0
7545 : s/foo/bar/g
7546 : let flags = "W"
7547 : endwhile
7548 : update " write the file if modified
7549 : let n = n + 1
7550 :endwhile
7551<
7552 Example for using some flags: >
7553 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7554< This will search for the keywords "if", "else", and "endif"
7555 under or after the cursor. Because of the 'p' flag, it
7556 returns 1, 2, or 3 depending on which keyword is found, or 0
7557 if the search fails. With the cursor on the first word of the
7558 line:
7559 if (foo == 0) | let foo = foo + 1 | endif ~
7560 the function returns 1. Without the 'c' flag, the function
7561 finds the "endif" and returns 3. The same thing happens
7562 without the 'e' flag if the cursor is on the "f" of "if".
7563 The 'n' flag tells the function not to move the cursor.
7564
7565 Can also be used as a |method|: >
7566 GetPattern()->search()
7567
7568searchcount([{options}]) *searchcount()*
7569 Get or update the last search count, like what is displayed
7570 without the "S" flag in 'shortmess'. This works even if
7571 'shortmess' does contain the "S" flag.
7572
7573 This returns a |Dictionary|. The dictionary is empty if the
7574 previous pattern was not set and "pattern" was not specified.
7575
7576 key type meaning ~
7577 current |Number| current position of match;
7578 0 if the cursor position is
7579 before the first match
7580 exact_match |Boolean| 1 if "current" is matched on
7581 "pos", otherwise 0
7582 total |Number| total count of matches found
7583 incomplete |Number| 0: search was fully completed
7584 1: recomputing was timed out
7585 2: max count exceeded
7586
7587 For {options} see further down.
7588
7589 To get the last search count when |n| or |N| was pressed, call
7590 this function with `recompute: 0` . This sometimes returns
7591 wrong information because |n| and |N|'s maximum count is 99.
7592 If it exceeded 99 the result must be max count + 1 (100). If
7593 you want to get correct information, specify `recompute: 1`: >
7594
7595 " result == maxcount + 1 (100) when many matches
7596 let result = searchcount(#{recompute: 0})
7597
7598 " Below returns correct result (recompute defaults
7599 " to 1)
7600 let result = searchcount()
7601<
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01007602 The function is useful to add the count to 'statusline': >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007603 function! LastSearchCount() abort
7604 let result = searchcount(#{recompute: 0})
7605 if empty(result)
7606 return ''
7607 endif
7608 if result.incomplete ==# 1 " timed out
7609 return printf(' /%s [?/??]', @/)
7610 elseif result.incomplete ==# 2 " max count exceeded
7611 if result.total > result.maxcount &&
7612 \ result.current > result.maxcount
7613 return printf(' /%s [>%d/>%d]', @/,
7614 \ result.current, result.total)
7615 elseif result.total > result.maxcount
7616 return printf(' /%s [%d/>%d]', @/,
7617 \ result.current, result.total)
7618 endif
7619 endif
7620 return printf(' /%s [%d/%d]', @/,
7621 \ result.current, result.total)
7622 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007623 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007624
7625 " Or if you want to show the count only when
7626 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007627 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007628 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7629<
7630 You can also update the search count, which can be useful in a
7631 |CursorMoved| or |CursorMovedI| autocommand: >
7632
7633 autocmd CursorMoved,CursorMovedI *
7634 \ let s:searchcount_timer = timer_start(
7635 \ 200, function('s:update_searchcount'))
7636 function! s:update_searchcount(timer) abort
7637 if a:timer ==# s:searchcount_timer
7638 call searchcount(#{
7639 \ recompute: 1, maxcount: 0, timeout: 100})
7640 redrawstatus
7641 endif
7642 endfunction
7643<
7644 This can also be used to count matched texts with specified
7645 pattern in the current buffer using "pattern": >
7646
7647 " Count '\<foo\>' in this buffer
7648 " (Note that it also updates search count)
7649 let result = searchcount(#{pattern: '\<foo\>'})
7650
7651 " To restore old search count by old pattern,
7652 " search again
7653 call searchcount()
7654<
7655 {options} must be a |Dictionary|. It can contain:
7656 key type meaning ~
7657 recompute |Boolean| if |TRUE|, recompute the count
7658 like |n| or |N| was executed.
7659 otherwise returns the last
7660 computed result (when |n| or
7661 |N| was used when "S" is not
7662 in 'shortmess', or this
7663 function was called).
7664 (default: |TRUE|)
7665 pattern |String| recompute if this was given
7666 and different with |@/|.
7667 this works as same as the
7668 below command is executed
7669 before calling this function >
7670 let @/ = pattern
7671< (default: |@/|)
7672 timeout |Number| 0 or negative number is no
7673 timeout. timeout milliseconds
7674 for recomputing the result
7675 (default: 0)
7676 maxcount |Number| 0 or negative number is no
7677 limit. max count of matched
7678 text while recomputing the
7679 result. if search exceeded
7680 total count, "total" value
7681 becomes `maxcount + 1`
7682 (default: 99)
7683 pos |List| `[lnum, col, off]` value
7684 when recomputing the result.
7685 this changes "current" result
7686 value. see |cursor()|,
7687 |getpos()|
7688 (default: cursor's position)
7689
7690 Can also be used as a |method|: >
7691 GetSearchOpts()->searchcount()
7692<
7693searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7694 Search for the declaration of {name}.
7695
7696 With a non-zero {global} argument it works like |gD|, find
7697 first match in the file. Otherwise it works like |gd|, find
7698 first match in the function.
7699
7700 With a non-zero {thisblock} argument matches in a {} block
7701 that ends before the cursor position are ignored. Avoids
7702 finding variable declarations only valid in another scope.
7703
7704 Moves the cursor to the found match.
7705 Returns zero for success, non-zero for failure.
7706 Example: >
7707 if searchdecl('myvar') == 0
7708 echo getline('.')
7709 endif
7710<
7711 Can also be used as a |method|: >
7712 GetName()->searchdecl()
7713<
7714 *searchpair()*
7715searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7716 [, {stopline} [, {timeout}]]]])
7717 Search for the match of a nested start-end pair. This can be
7718 used to find the "endif" that matches an "if", while other
7719 if/endif pairs in between are ignored.
7720 The search starts at the cursor. The default is to search
7721 forward, include 'b' in {flags} to search backward.
7722 If a match is found, the cursor is positioned at it and the
7723 line number is returned. If no match is found 0 or -1 is
7724 returned and the cursor doesn't move. No error message is
7725 given.
7726
7727 {start}, {middle} and {end} are patterns, see |pattern|. They
7728 must not contain \( \) pairs. Use of \%( \) is allowed. When
7729 {middle} is not empty, it is found when searching from either
7730 direction, but only when not in a nested start-end pair. A
7731 typical use is: >
7732 searchpair('\<if\>', '\<else\>', '\<endif\>')
7733< By leaving {middle} empty the "else" is skipped.
7734
7735 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7736 |search()|. Additionally:
7737 'r' Repeat until no more matches found; will find the
7738 outer pair. Implies the 'W' flag.
7739 'm' Return number of matches instead of line number with
7740 the match; will be > 1 when 'r' is used.
7741 Note: it's nearly always a good idea to use the 'W' flag, to
7742 avoid wrapping around the end of the file.
7743
7744 When a match for {start}, {middle} or {end} is found, the
7745 {skip} expression is evaluated with the cursor positioned on
7746 the start of the match. It should return non-zero if this
7747 match is to be skipped. E.g., because it is inside a comment
7748 or a string.
7749 When {skip} is omitted or empty, every match is accepted.
7750 When evaluating {skip} causes an error the search is aborted
7751 and -1 returned.
7752 {skip} can be a string, a lambda, a funcref or a partial.
7753 Anything else makes the function fail.
7754 In a `:def` function when the {skip} argument is a string
7755 constant it is compiled into instructions.
7756
7757 For {stopline} and {timeout} see |search()|.
7758
7759 The value of 'ignorecase' is used. 'magic' is ignored, the
7760 patterns are used like it's on.
7761
7762 The search starts exactly at the cursor. A match with
7763 {start}, {middle} or {end} at the next character, in the
7764 direction of searching, is the first one found. Example: >
7765 if 1
7766 if 2
7767 endif 2
7768 endif 1
7769< When starting at the "if 2", with the cursor on the "i", and
7770 searching forwards, the "endif 2" is found. When starting on
7771 the character just before the "if 2", the "endif 1" will be
7772 found. That's because the "if 2" will be found first, and
7773 then this is considered to be a nested if/endif from "if 2" to
7774 "endif 2".
7775 When searching backwards and {end} is more than one character,
7776 it may be useful to put "\zs" at the end of the pattern, so
7777 that when the cursor is inside a match with the end it finds
7778 the matching start.
7779
7780 Example, to find the "endif" command in a Vim script: >
7781
7782 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7783 \ 'getline(".") =~ "^\\s*\""')
7784
7785< The cursor must be at or after the "if" for which a match is
7786 to be found. Note that single-quote strings are used to avoid
7787 having to double the backslashes. The skip expression only
7788 catches comments at the start of a line, not after a command.
7789 Also, a word "en" or "if" halfway a line is considered a
7790 match.
7791 Another example, to search for the matching "{" of a "}": >
7792
7793 :echo searchpair('{', '', '}', 'bW')
7794
7795< This works when the cursor is at or before the "}" for which a
7796 match is to be found. To reject matches that syntax
7797 highlighting recognized as strings: >
7798
7799 :echo searchpair('{', '', '}', 'bW',
7800 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7801<
7802 *searchpairpos()*
7803searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7804 [, {stopline} [, {timeout}]]]])
7805 Same as |searchpair()|, but returns a |List| with the line and
7806 column position of the match. The first element of the |List|
7807 is the line number and the second element is the byte index of
7808 the column position of the match. If no match is found,
7809 returns [0, 0]. >
7810
7811 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7812<
7813 See |match-parens| for a bigger and more useful example.
7814
7815 *searchpos()*
7816searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7817 Same as |search()|, but returns a |List| with the line and
7818 column position of the match. The first element of the |List|
7819 is the line number and the second element is the byte index of
7820 the column position of the match. If no match is found,
7821 returns [0, 0].
7822 Example: >
7823 :let [lnum, col] = searchpos('mypattern', 'n')
7824
7825< When the 'p' flag is given then there is an extra item with
7826 the sub-pattern match number |search()-sub-match|. Example: >
7827 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7828< In this example "submatch" is 2 when a lowercase letter is
7829 found |/\l|, 3 when an uppercase letter is found |/\u|.
7830
7831 Can also be used as a |method|: >
7832 GetPattern()->searchpos()
7833
7834server2client({clientid}, {string}) *server2client()*
7835 Send a reply string to {clientid}. The most recent {clientid}
7836 that sent a string can be retrieved with expand("<client>").
7837 {only available when compiled with the |+clientserver| feature}
7838 Returns zero for success, -1 for failure.
7839 Note:
7840 This id has to be stored before the next command can be
7841 received. I.e. before returning from the received command and
7842 before calling any commands that waits for input.
7843 See also |clientserver|.
7844 Example: >
7845 :echo server2client(expand("<client>"), "HELLO")
7846
7847< Can also be used as a |method|: >
7848 GetClientId()->server2client(string)
7849<
7850serverlist() *serverlist()*
7851 Return a list of available server names, one per line.
7852 When there are no servers or the information is not available
7853 an empty string is returned. See also |clientserver|.
7854 {only available when compiled with the |+clientserver| feature}
7855 Example: >
7856 :echo serverlist()
7857<
7858setbufline({buf}, {lnum}, {text}) *setbufline()*
7859 Set line {lnum} to {text} in buffer {buf}. This works like
7860 |setline()| for the specified buffer.
7861
7862 This function works only for loaded buffers. First call
7863 |bufload()| if needed.
7864
7865 To insert lines use |appendbufline()|.
7866 Any text properties in {lnum} are cleared.
7867
7868 {text} can be a string to set one line, or a list of strings
7869 to set multiple lines. If the list extends below the last
7870 line then those lines are added.
7871
7872 For the use of {buf}, see |bufname()| above.
7873
7874 {lnum} is used like with |setline()|.
7875 Use "$" to refer to the last line in buffer {buf}.
7876 When {lnum} is just below the last line the {text} will be
7877 added below the last line.
7878
7879 When {buf} is not a valid buffer, the buffer is not loaded or
7880 {lnum} is not valid then 1 is returned. In |Vim9| script an
7881 error is given.
7882 On success 0 is returned.
7883
7884 Can also be used as a |method|, the base is passed as the
7885 third argument: >
7886 GetText()->setbufline(buf, lnum)
7887
7888setbufvar({buf}, {varname}, {val}) *setbufvar()*
7889 Set option or local variable {varname} in buffer {buf} to
7890 {val}.
7891 This also works for a global or local window option, but it
7892 doesn't work for a global or local window variable.
7893 For a local window option the global value is unchanged.
7894 For the use of {buf}, see |bufname()| above.
7895 The {varname} argument is a string.
7896 Note that the variable name without "b:" must be used.
7897 Examples: >
7898 :call setbufvar(1, "&mod", 1)
7899 :call setbufvar("todo", "myvar", "foobar")
7900< This function is not available in the |sandbox|.
7901
7902 Can also be used as a |method|, the base is passed as the
7903 third argument: >
7904 GetValue()->setbufvar(buf, varname)
7905
7906
7907setcellwidths({list}) *setcellwidths()*
7908 Specify overrides for cell widths of character ranges. This
7909 tells Vim how wide characters are, counted in screen cells.
7910 This overrides 'ambiwidth'. Example: >
7911 setcellwidths([[0xad, 0xad, 1],
7912 \ [0x2194, 0x2199, 2]])
7913
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007914< *E1109* *E1110* *E1111* *E1112* *E1113* *E1114*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007915 The {list} argument is a list of lists with each three
7916 numbers. These three numbers are [low, high, width]. "low"
7917 and "high" can be the same, in which case this refers to one
7918 character. Otherwise it is the range of characters from "low"
7919 to "high" (inclusive). "width" is either 1 or 2, indicating
7920 the character width in screen cells.
7921 An error is given if the argument is invalid, also when a
7922 range overlaps with another.
7923 Only characters with value 0x100 and higher can be used.
7924
7925 If the new value causes 'fillchars' or 'listchars' to become
7926 invalid it is rejected and an error is given.
7927
7928 To clear the overrides pass an empty list: >
7929 setcellwidths([]);
7930< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7931 the effect for known emoji characters.
7932
7933setcharpos({expr}, {list}) *setcharpos()*
7934 Same as |setpos()| but uses the specified column number as the
7935 character index instead of the byte index in the line.
7936
7937 Example:
7938 With the text "여보세요" in line 8: >
7939 call setcharpos('.', [0, 8, 4, 0])
7940< positions the cursor on the fourth character '요'. >
7941 call setpos('.', [0, 8, 4, 0])
7942< positions the cursor on the second character '보'.
7943
7944 Can also be used as a |method|: >
7945 GetPosition()->setcharpos('.')
7946
7947setcharsearch({dict}) *setcharsearch()*
7948 Set the current character search information to {dict},
7949 which contains one or more of the following entries:
7950
7951 char character which will be used for a subsequent
7952 |,| or |;| command; an empty string clears the
7953 character search
7954 forward direction of character search; 1 for forward,
7955 0 for backward
7956 until type of character search; 1 for a |t| or |T|
7957 character search, 0 for an |f| or |F|
7958 character search
7959
7960 This can be useful to save/restore a user's character search
7961 from a script: >
7962 :let prevsearch = getcharsearch()
7963 :" Perform a command which clobbers user's search
7964 :call setcharsearch(prevsearch)
7965< Also see |getcharsearch()|.
7966
7967 Can also be used as a |method|: >
7968 SavedSearch()->setcharsearch()
7969
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01007970setcmdline({str} [, {pos}]) *setcmdline()*
7971 Set the command line to {str} and set the cursor position to
7972 {pos}.
7973 If {pos} is omitted, the cursor is positioned after the text.
7974 Returns 0 when successful, 1 when not editing the command
7975 line.
7976
7977 Can also be used as a |method|: >
7978 GetText()->setcmdline()
7979
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007980setcmdpos({pos}) *setcmdpos()*
7981 Set the cursor position in the command line to byte position
7982 {pos}. The first position is 1.
7983 Use |getcmdpos()| to obtain the current position.
7984 Only works while editing the command line, thus you must use
7985 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7986 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7987 set after the command line is set to the expression. For
7988 |c_CTRL-R_=| it is set after evaluating the expression but
7989 before inserting the resulting text.
7990 When the number is too big the cursor is put at the end of the
7991 line. A number smaller than one has undefined results.
Shougo Matsushita07ea5f12022-08-27 12:22:25 +01007992 Returns 0 when successful, 1 when not editing the command
7993 line.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007994
7995 Can also be used as a |method|: >
7996 GetPos()->setcmdpos()
7997
7998setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
7999setcursorcharpos({list})
8000 Same as |cursor()| but uses the specified column number as the
8001 character index instead of the byte index in the line.
8002
8003 Example:
8004 With the text "여보세요" in line 4: >
8005 call setcursorcharpos(4, 3)
8006< positions the cursor on the third character '세'. >
8007 call cursor(4, 3)
8008< positions the cursor on the first character '여'.
8009
8010 Can also be used as a |method|: >
8011 GetCursorPos()->setcursorcharpos()
8012
8013
8014setenv({name}, {val}) *setenv()*
8015 Set environment variable {name} to {val}. Example: >
8016 call setenv('HOME', '/home/myhome')
8017
8018< When {val} is |v:null| the environment variable is deleted.
8019 See also |expr-env|.
8020
8021 Can also be used as a |method|, the base is passed as the
8022 second argument: >
8023 GetPath()->setenv('PATH')
8024
8025setfperm({fname}, {mode}) *setfperm()* *chmod*
8026 Set the file permissions for {fname} to {mode}.
8027 {mode} must be a string with 9 characters. It is of the form
8028 "rwxrwxrwx", where each group of "rwx" flags represent, in
8029 turn, the permissions of the owner of the file, the group the
8030 file belongs to, and other users. A '-' character means the
8031 permission is off, any other character means on. Multi-byte
8032 characters are not supported.
8033
8034 For example "rw-r-----" means read-write for the user,
8035 readable by the group, not accessible by others. "xx-x-----"
8036 would do the same thing.
8037
8038 Returns non-zero for success, zero for failure.
8039
8040 Can also be used as a |method|: >
8041 GetFilename()->setfperm(mode)
8042<
8043 To read permissions see |getfperm()|.
8044
8045
8046setline({lnum}, {text}) *setline()*
8047 Set line {lnum} of the current buffer to {text}. To insert
8048 lines use |append()|. To set lines in another buffer use
8049 |setbufline()|. Any text properties in {lnum} are cleared.
8050
8051 {lnum} is used like with |getline()|.
8052 When {lnum} is just below the last line the {text} will be
8053 added below the last line.
8054 {text} can be any type or a List of any type, each item is
8055 converted to a String.
8056
8057 If this succeeds, FALSE is returned. If this fails (most likely
8058 because {lnum} is invalid) TRUE is returned.
8059 In |Vim9| script an error is given if {lnum} is invalid.
8060
8061 Example: >
8062 :call setline(5, strftime("%c"))
8063
8064< When {text} is a |List| then line {lnum} and following lines
8065 will be set to the items in the list. Example: >
8066 :call setline(5, ['aaa', 'bbb', 'ccc'])
8067< This is equivalent to: >
8068 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
8069 : call setline(n, l)
8070 :endfor
8071
8072< Note: The '[ and '] marks are not set.
8073
8074 Can also be used as a |method|, the base is passed as the
8075 second argument: >
8076 GetText()->setline(lnum)
8077
8078setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
8079 Create or replace or add to the location list for window {nr}.
8080 {nr} can be the window number or the |window-ID|.
8081 When {nr} is zero the current window is used.
8082
8083 For a location list window, the displayed location list is
8084 modified. For an invalid window number {nr}, -1 is returned.
8085 Otherwise, same as |setqflist()|.
8086 Also see |location-list|.
8087
8088 For {action} see |setqflist-action|.
8089
8090 If the optional {what} dictionary argument is supplied, then
8091 only the items listed in {what} are set. Refer to |setqflist()|
8092 for the list of supported keys in {what}.
8093
8094 Can also be used as a |method|, the base is passed as the
8095 second argument: >
8096 GetLoclist()->setloclist(winnr)
8097
8098setmatches({list} [, {win}]) *setmatches()*
8099 Restores a list of matches saved by |getmatches()| for the
8100 current window. Returns 0 if successful, otherwise -1. All
8101 current matches are cleared before the list is restored. See
8102 example for |getmatches()|.
8103 If {win} is specified, use the window with this number or
8104 window ID instead of the current window.
8105
8106 Can also be used as a |method|: >
8107 GetMatches()->setmatches()
8108<
8109 *setpos()*
8110setpos({expr}, {list})
8111 Set the position for String {expr}. Possible values:
8112 . the cursor
8113 'x mark x
8114
8115 {list} must be a |List| with four or five numbers:
8116 [bufnum, lnum, col, off]
8117 [bufnum, lnum, col, off, curswant]
8118
8119 "bufnum" is the buffer number. Zero can be used for the
8120 current buffer. When setting an uppercase mark "bufnum" is
8121 used for the mark position. For other marks it specifies the
8122 buffer to set the mark in. You can use the |bufnr()| function
8123 to turn a file name into a buffer number.
8124 For setting the cursor and the ' mark "bufnum" is ignored,
8125 since these are associated with a window, not a buffer.
8126 Does not change the jumplist.
8127
8128 "lnum" and "col" are the position in the buffer. The first
8129 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8130 smaller than 1 then 1 is used. To use the character count
8131 instead of the byte count, use |setcharpos()|.
8132
8133 The "off" number is only used when 'virtualedit' is set. Then
8134 it is the offset in screen columns from the start of the
8135 character. E.g., a position within a <Tab> or after the last
8136 character.
8137
8138 The "curswant" number is only used when setting the cursor
8139 position. It sets the preferred column for when moving the
8140 cursor vertically. When the "curswant" number is missing the
8141 preferred column is not set. When it is present and setting a
8142 mark position it is not used.
8143
8144 Note that for '< and '> changing the line number may result in
8145 the marks to be effectively be swapped, so that '< is always
8146 before '>.
8147
8148 Returns 0 when the position could be set, -1 otherwise.
8149 An error message is given if {expr} is invalid.
8150
8151 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
8152
8153 This does not restore the preferred column for moving
8154 vertically; if you set the cursor position with this, |j| and
8155 |k| motions will jump to previous columns! Use |cursor()| to
8156 also set the preferred column. Also see the "curswant" key in
8157 |winrestview()|.
8158
8159 Can also be used as a |method|: >
8160 GetPosition()->setpos('.')
8161
8162setqflist({list} [, {action} [, {what}]]) *setqflist()*
8163 Create or replace or add to the quickfix list.
8164
8165 If the optional {what} dictionary argument is supplied, then
8166 only the items listed in {what} are set. The first {list}
8167 argument is ignored. See below for the supported items in
8168 {what}.
8169 *setqflist-what*
8170 When {what} is not present, the items in {list} are used. Each
8171 item must be a dictionary. Non-dictionary items in {list} are
8172 ignored. Each dictionary item can contain the following
8173 entries:
8174
8175 bufnr buffer number; must be the number of a valid
8176 buffer
8177 filename name of a file; only used when "bufnr" is not
8178 present or it is invalid.
8179 module name of a module; if given it will be used in
8180 quickfix error window instead of the filename.
8181 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00008182 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008183 pattern search pattern used to locate the error
8184 col column number
8185 vcol when non-zero: "col" is visual column
8186 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00008187 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008188 nr error number
8189 text description of the error
8190 type single-character error type, 'E', 'W', etc.
8191 valid recognized error message
8192
8193 The "col", "vcol", "nr", "type" and "text" entries are
8194 optional. Either "lnum" or "pattern" entry can be used to
8195 locate a matching error line.
8196 If the "filename" and "bufnr" entries are not present or
8197 neither the "lnum" or "pattern" entries are present, then the
8198 item will not be handled as an error line.
8199 If both "pattern" and "lnum" are present then "pattern" will
8200 be used.
8201 If the "valid" entry is not supplied, then the valid flag is
8202 set when "bufnr" is a valid buffer or "filename" exists.
8203 If you supply an empty {list}, the quickfix list will be
8204 cleared.
8205 Note that the list is not exactly the same as what
8206 |getqflist()| returns.
8207
8208 {action} values: *setqflist-action* *E927*
8209 'a' The items from {list} are added to the existing
8210 quickfix list. If there is no existing list, then a
8211 new list is created.
8212
8213 'r' The items from the current quickfix list are replaced
8214 with the items from {list}. This can also be used to
8215 clear the list: >
8216 :call setqflist([], 'r')
8217<
8218 'f' All the quickfix lists in the quickfix stack are
8219 freed.
8220
8221 If {action} is not present or is set to ' ', then a new list
8222 is created. The new quickfix list is added after the current
8223 quickfix list in the stack and all the following lists are
8224 freed. To add a new quickfix list at the end of the stack,
8225 set "nr" in {what} to "$".
8226
8227 The following items can be specified in dictionary {what}:
8228 context quickfix list context. See |quickfix-context|
8229 efm errorformat to use when parsing text from
8230 "lines". If this is not present, then the
8231 'errorformat' option value is used.
8232 See |quickfix-parse|
8233 id quickfix list identifier |quickfix-ID|
8234 idx index of the current entry in the quickfix
8235 list specified by 'id' or 'nr'. If set to '$',
8236 then the last entry in the list is set as the
8237 current entry. See |quickfix-index|
8238 items list of quickfix entries. Same as the {list}
8239 argument.
8240 lines use 'errorformat' to parse a list of lines and
8241 add the resulting entries to the quickfix list
8242 {nr} or {id}. Only a |List| value is supported.
8243 See |quickfix-parse|
8244 nr list number in the quickfix stack; zero
8245 means the current quickfix list and "$" means
8246 the last quickfix list.
8247 quickfixtextfunc
8248 function to get the text to display in the
8249 quickfix window. The value can be the name of
8250 a function or a funcref or a lambda. Refer to
8251 |quickfix-window-function| for an explanation
8252 of how to write the function and an example.
8253 title quickfix list title text. See |quickfix-title|
8254 Unsupported keys in {what} are ignored.
8255 If the "nr" item is not present, then the current quickfix list
8256 is modified. When creating a new quickfix list, "nr" can be
8257 set to a value one greater than the quickfix stack size.
8258 When modifying a quickfix list, to guarantee that the correct
8259 list is modified, "id" should be used instead of "nr" to
8260 specify the list.
8261
8262 Examples (See also |setqflist-examples|): >
8263 :call setqflist([], 'r', {'title': 'My search'})
8264 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
8265 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
8266<
8267 Returns zero for success, -1 for failure.
8268
8269 This function can be used to create a quickfix list
8270 independent of the 'errorformat' setting. Use a command like
8271 `:cc 1` to jump to the first position.
8272
8273 Can also be used as a |method|, the base is passed as the
8274 second argument: >
8275 GetErrorlist()->setqflist()
8276<
8277 *setreg()*
8278setreg({regname}, {value} [, {options}])
8279 Set the register {regname} to {value}.
8280 If {regname} is "" or "@", the unnamed register '"' is used.
8281 The {regname} argument is a string. In |Vim9-script|
8282 {regname} must be one character.
8283
8284 {value} may be any value returned by |getreg()| or
8285 |getreginfo()|, including a |List| or |Dict|.
8286 If {options} contains "a" or {regname} is upper case,
8287 then the value is appended.
8288
8289 {options} can also contain a register type specification:
8290 "c" or "v" |characterwise| mode
8291 "l" or "V" |linewise| mode
8292 "b" or "<CTRL-V>" |blockwise-visual| mode
8293 If a number immediately follows "b" or "<CTRL-V>" then this is
8294 used as the width of the selection - if it is not specified
8295 then the width of the block is set to the number of characters
8296 in the longest line (counting a <Tab> as 1 character).
8297
8298 If {options} contains no register settings, then the default
8299 is to use character mode unless {value} ends in a <NL> for
8300 string {value} and linewise mode for list {value}. Blockwise
8301 mode is never selected automatically.
8302 Returns zero for success, non-zero for failure.
8303
8304 *E883*
8305 Note: you may not use |List| containing more than one item to
8306 set search and expression registers. Lists containing no
8307 items act like empty strings.
8308
8309 Examples: >
8310 :call setreg(v:register, @*)
8311 :call setreg('*', @%, 'ac')
8312 :call setreg('a', "1\n2\n3", 'b5')
8313 :call setreg('"', { 'points_to': 'a'})
8314
8315< This example shows using the functions to save and restore a
8316 register: >
8317 :let var_a = getreginfo()
8318 :call setreg('a', var_a)
8319< or: >
8320 :let var_a = getreg('a', 1, 1)
8321 :let var_amode = getregtype('a')
8322 ....
8323 :call setreg('a', var_a, var_amode)
8324< Note: you may not reliably restore register value
8325 without using the third argument to |getreg()| as without it
8326 newlines are represented as newlines AND Nul bytes are
8327 represented as newlines as well, see |NL-used-for-Nul|.
8328
8329 You can also change the type of a register by appending
8330 nothing: >
8331 :call setreg('a', '', 'al')
8332
8333< Can also be used as a |method|, the base is passed as the
8334 second argument: >
8335 GetText()->setreg('a')
8336
8337settabvar({tabnr}, {varname}, {val}) *settabvar()*
8338 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8339 |t:var|
8340 The {varname} argument is a string.
8341 Note that autocommands are blocked, side effects may not be
8342 triggered, e.g. when setting 'filetype'.
8343 Note that the variable name without "t:" must be used.
8344 Tabs are numbered starting with one.
8345 This function is not available in the |sandbox|.
8346
8347 Can also be used as a |method|, the base is passed as the
8348 third argument: >
8349 GetValue()->settabvar(tab, name)
8350
8351settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8352 Set option or local variable {varname} in window {winnr} to
8353 {val}.
8354 Tabs are numbered starting with one. For the current tabpage
8355 use |setwinvar()|.
8356 {winnr} can be the window number or the |window-ID|.
8357 When {winnr} is zero the current window is used.
8358 Note that autocommands are blocked, side effects may not be
8359 triggered, e.g. when setting 'filetype' or 'syntax'.
8360 This also works for a global or local buffer option, but it
8361 doesn't work for a global or local buffer variable.
8362 For a local buffer option the global value is unchanged.
8363 Note that the variable name without "w:" must be used.
8364 Examples: >
8365 :call settabwinvar(1, 1, "&list", 0)
8366 :call settabwinvar(3, 2, "myvar", "foobar")
8367< This function is not available in the |sandbox|.
8368
8369 Can also be used as a |method|, the base is passed as the
8370 fourth argument: >
8371 GetValue()->settabwinvar(tab, winnr, name)
8372
8373settagstack({nr}, {dict} [, {action}]) *settagstack()*
8374 Modify the tag stack of the window {nr} using {dict}.
8375 {nr} can be the window number or the |window-ID|.
8376
8377 For a list of supported items in {dict}, refer to
8378 |gettagstack()|. "curidx" takes effect before changing the tag
8379 stack.
8380 *E962*
8381 How the tag stack is modified depends on the {action}
8382 argument:
8383 - If {action} is not present or is set to 'r', then the tag
8384 stack is replaced.
8385 - If {action} is set to 'a', then new entries from {dict} are
8386 pushed (added) onto the tag stack.
8387 - If {action} is set to 't', then all the entries from the
8388 current entry in the tag stack or "curidx" in {dict} are
8389 removed and then new entries are pushed to the stack.
8390
8391 The current index is set to one after the length of the tag
8392 stack after the modification.
8393
8394 Returns zero for success, -1 for failure.
8395
8396 Examples (for more examples see |tagstack-examples|):
8397 Empty the tag stack of window 3: >
8398 call settagstack(3, {'items' : []})
8399
8400< Save and restore the tag stack: >
8401 let stack = gettagstack(1003)
8402 " do something else
8403 call settagstack(1003, stack)
8404 unlet stack
8405<
8406 Can also be used as a |method|, the base is passed as the
8407 second argument: >
8408 GetStack()->settagstack(winnr)
8409
8410setwinvar({winnr}, {varname}, {val}) *setwinvar()*
8411 Like |settabwinvar()| for the current tab page.
8412 Examples: >
8413 :call setwinvar(1, "&list", 0)
8414 :call setwinvar(2, "myvar", "foobar")
8415
8416< Can also be used as a |method|, the base is passed as the
8417 third argument: >
8418 GetValue()->setwinvar(winnr, name)
8419
8420sha256({string}) *sha256()*
8421 Returns a String with 64 hex characters, which is the SHA256
8422 checksum of {string}.
8423
8424 Can also be used as a |method|: >
8425 GetText()->sha256()
8426
8427< {only available when compiled with the |+cryptv| feature}
8428
8429shellescape({string} [, {special}]) *shellescape()*
8430 Escape {string} for use as a shell command argument.
8431 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00008432 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008433 in single quotes and will double up all internal single
8434 quotes.
8435 On MS-Windows, when 'shellslash' is not set, it will enclose
8436 {string} in double quotes and double all double quotes within
8437 {string}.
8438 Otherwise it will enclose {string} in single quotes and
8439 replace all "'" with "'\''".
8440
8441 When the {special} argument is present and it's a non-zero
8442 Number or a non-empty String (|non-zero-arg|), then special
8443 items such as "!", "%", "#" and "<cword>" will be preceded by
8444 a backslash. This backslash will be removed again by the |:!|
8445 command.
8446
8447 The "!" character will be escaped (again with a |non-zero-arg|
8448 {special}) when 'shell' contains "csh" in the tail. That is
8449 because for csh and tcsh "!" is used for history replacement
8450 even when inside single quotes.
8451
8452 With a |non-zero-arg| {special} the <NL> character is also
8453 escaped. When 'shell' containing "csh" in the tail it's
8454 escaped a second time.
8455
8456 The "\" character will be escaped when 'shell' contains "fish"
8457 in the tail. That is because for fish "\" is used as an escape
8458 character inside single quotes.
8459
8460 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008461 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008462< This results in a directory listing for the file under the
8463 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008464 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008465< See also |::S|.
8466
8467 Can also be used as a |method|: >
8468 GetCommand()->shellescape()
8469
8470shiftwidth([{col}]) *shiftwidth()*
8471 Returns the effective value of 'shiftwidth'. This is the
8472 'shiftwidth' value unless it is zero, in which case it is the
8473 'tabstop' value. This function was introduced with patch
8474 7.3.694 in 2012, everybody should have it by now (however it
8475 did not allow for the optional {col} argument until 8.1.542).
8476
8477 When there is one argument {col} this is used as column number
8478 for which to return the 'shiftwidth' value. This matters for the
8479 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8480 no {col} argument is given, column 1 will be assumed.
8481
8482 Can also be used as a |method|: >
8483 GetColumn()->shiftwidth()
8484
8485sign_ functions are documented here: |sign-functions-details|
8486
8487
8488simplify({filename}) *simplify()*
8489 Simplify the file name as much as possible without changing
8490 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8491 Unix) are not resolved. If the first path component in
8492 {filename} designates the current directory, this will be
8493 valid for the result as well. A trailing path separator is
8494 not removed either. On Unix "//path" is unchanged, but
8495 "///path" is simplified to "/path" (this follows the Posix
8496 standard).
8497 Example: >
8498 simplify("./dir/.././/file/") == "./file/"
8499< Note: The combination "dir/.." is only removed if "dir" is
8500 a searchable directory or does not exist. On Unix, it is also
8501 removed when "dir" is a symbolic link within the same
8502 directory. In order to resolve all the involved symbolic
8503 links before simplifying the path name, use |resolve()|.
8504
8505 Can also be used as a |method|: >
8506 GetName()->simplify()
8507
8508sin({expr}) *sin()*
8509 Return the sine of {expr}, measured in radians, as a |Float|.
8510 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008511 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008512 Examples: >
8513 :echo sin(100)
8514< -0.506366 >
8515 :echo sin(-4.01)
8516< 0.763301
8517
8518 Can also be used as a |method|: >
8519 Compute()->sin()
8520<
8521 {only available when compiled with the |+float| feature}
8522
8523
8524sinh({expr}) *sinh()*
8525 Return the hyperbolic sine of {expr} as a |Float| in the range
8526 [-inf, inf].
8527 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008528 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008529 Examples: >
8530 :echo sinh(0.5)
8531< 0.521095 >
8532 :echo sinh(-0.9)
8533< -1.026517
8534
8535 Can also be used as a |method|: >
8536 Compute()->sinh()
8537<
8538 {only available when compiled with the |+float| feature}
8539
8540
8541slice({expr}, {start} [, {end}]) *slice()*
8542 Similar to using a |slice| "expr[start : end]", but "end" is
8543 used exclusive. And for a string the indexes are used as
8544 character indexes instead of byte indexes, like in
8545 |vim9script|. Also, composing characters are not counted.
8546 When {end} is omitted the slice continues to the last item.
8547 When {end} is -1 the last item is omitted.
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008548 Returns an empty value if {start} or {end} are invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008549
8550 Can also be used as a |method|: >
8551 GetList()->slice(offset)
8552
8553
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008554sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008555 Sort the items in {list} in-place. Returns {list}.
8556
8557 If you want a list to remain unmodified make a copy first: >
8558 :let sortedlist = sort(copy(mylist))
8559
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01008560< When {how} is omitted or is a string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008561 string representation of each item to sort on. Numbers sort
8562 after Strings, |Lists| after Numbers. For sorting text in the
8563 current buffer use |:sort|.
8564
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008565 When {how} is given and it is 'i' then case is ignored.
8566 In legacy script, for backwards compatibility, the value one
8567 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008568
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008569 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008570 locale is used for ordering. Implementation details: strcoll()
8571 is used to compare strings. See |:language| check or set the
8572 collation locale. |v:collate| can also be used to check the
8573 current locale. Sorting using the locale typically ignores
8574 case. Example: >
8575 " ö is sorted similarly to o with English locale.
8576 :language collate en_US.UTF8
8577 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8578< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8579>
8580 " ö is sorted after z with Swedish locale.
8581 :language collate sv_SE.UTF8
8582 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8583< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8584 This does not work properly on Mac.
8585
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008586 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008587 sorted numerical (Implementation detail: this uses the
8588 strtod() function to parse numbers, Strings, Lists, Dicts and
8589 Funcrefs will be considered as being 0).
8590
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008591 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008592 sorted numerical. This is like 'n' but a string containing
8593 digits will be used as the number they represent.
8594
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008595 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008596 sorted numerical. All values must be a Number or a Float.
8597
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008598 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008599 is called to compare items. The function is invoked with two
8600 items as argument and must return zero if they are equal, 1 or
8601 bigger if the first one sorts after the second one, -1 or
8602 smaller if the first one sorts before the second one.
8603
8604 {dict} is for functions with the "dict" attribute. It will be
8605 used to set the local variable "self". |Dictionary-function|
8606
8607 The sort is stable, items which compare equal (as number or as
8608 string) will keep their relative position. E.g., when sorting
8609 on numbers, text strings will sort next to each other, in the
8610 same order as they were originally.
8611
8612 Can also be used as a |method|: >
8613 mylist->sort()
8614
8615< Also see |uniq()|.
8616
8617 Example: >
8618 func MyCompare(i1, i2)
8619 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8620 endfunc
8621 eval mylist->sort("MyCompare")
8622< A shorter compare version for this specific simple case, which
8623 ignores overflow: >
8624 func MyCompare(i1, i2)
8625 return a:i1 - a:i2
8626 endfunc
8627< For a simple expression you can use a lambda: >
8628 eval mylist->sort({i1, i2 -> i1 - i2})
8629<
8630sound_clear() *sound_clear()*
8631 Stop playing all sounds.
8632
8633 On some Linux systems you may need the libcanberra-pulse
8634 package, otherwise sound may not stop.
8635
8636 {only available when compiled with the |+sound| feature}
8637
8638 *sound_playevent()*
8639sound_playevent({name} [, {callback}])
8640 Play a sound identified by {name}. Which event names are
8641 supported depends on the system. Often the XDG sound names
8642 are used. On Ubuntu they may be found in
8643 /usr/share/sounds/freedesktop/stereo. Example: >
8644 call sound_playevent('bell')
8645< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8646 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8647 SystemStart, SystemWelcome, etc.
8648
8649 When {callback} is specified it is invoked when the sound is
8650 finished. The first argument is the sound ID, the second
8651 argument is the status:
8652 0 sound was played to the end
8653 1 sound was interrupted
8654 2 error occurred after sound started
8655 Example: >
8656 func Callback(id, status)
8657 echomsg "sound " .. a:id .. " finished with " .. a:status
8658 endfunc
8659 call sound_playevent('bell', 'Callback')
8660
8661< MS-Windows: {callback} doesn't work for this function.
8662
8663 Returns the sound ID, which can be passed to `sound_stop()`.
8664 Returns zero if the sound could not be played.
8665
8666 Can also be used as a |method|: >
8667 GetSoundName()->sound_playevent()
8668
8669< {only available when compiled with the |+sound| feature}
8670
8671 *sound_playfile()*
8672sound_playfile({path} [, {callback}])
8673 Like `sound_playevent()` but play sound file {path}. {path}
8674 must be a full path. On Ubuntu you may find files to play
8675 with this command: >
8676 :!find /usr/share/sounds -type f | grep -v index.theme
8677
8678< Can also be used as a |method|: >
8679 GetSoundPath()->sound_playfile()
8680
Bram Moolenaar1588bc82022-03-08 21:35:07 +00008681< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008682
8683
8684sound_stop({id}) *sound_stop()*
8685 Stop playing sound {id}. {id} must be previously returned by
8686 `sound_playevent()` or `sound_playfile()`.
8687
8688 On some Linux systems you may need the libcanberra-pulse
8689 package, otherwise sound may not stop.
8690
8691 On MS-Windows, this does not work for event sound started by
8692 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8693
8694 Can also be used as a |method|: >
8695 soundid->sound_stop()
8696
8697< {only available when compiled with the |+sound| feature}
8698
8699 *soundfold()*
8700soundfold({word})
8701 Return the sound-folded equivalent of {word}. Uses the first
8702 language in 'spelllang' for the current window that supports
8703 soundfolding. 'spell' must be set. When no sound folding is
8704 possible the {word} is returned unmodified.
8705 This can be used for making spelling suggestions. Note that
8706 the method can be quite slow.
8707
8708 Can also be used as a |method|: >
8709 GetWord()->soundfold()
8710<
8711 *spellbadword()*
8712spellbadword([{sentence}])
8713 Without argument: The result is the badly spelled word under
8714 or after the cursor. The cursor is moved to the start of the
8715 bad word. When no bad word is found in the cursor line the
8716 result is an empty string and the cursor doesn't move.
8717
8718 With argument: The result is the first word in {sentence} that
8719 is badly spelled. If there are no spelling mistakes the
8720 result is an empty string.
8721
8722 The return value is a list with two items:
8723 - The badly spelled word or an empty string.
8724 - The type of the spelling error:
8725 "bad" spelling mistake
8726 "rare" rare word
8727 "local" word only valid in another region
8728 "caps" word should start with Capital
8729 Example: >
8730 echo spellbadword("the quik brown fox")
8731< ['quik', 'bad'] ~
8732
8733 The spelling information for the current window and the value
8734 of 'spelllang' are used.
8735
8736 Can also be used as a |method|: >
8737 GetText()->spellbadword()
8738<
8739 *spellsuggest()*
8740spellsuggest({word} [, {max} [, {capital}]])
8741 Return a |List| with spelling suggestions to replace {word}.
8742 When {max} is given up to this number of suggestions are
8743 returned. Otherwise up to 25 suggestions are returned.
8744
8745 When the {capital} argument is given and it's non-zero only
8746 suggestions with a leading capital will be given. Use this
8747 after a match with 'spellcapcheck'.
8748
8749 {word} can be a badly spelled word followed by other text.
8750 This allows for joining two words that were split. The
8751 suggestions also include the following text, thus you can
8752 replace a line.
8753
8754 {word} may also be a good word. Similar words will then be
8755 returned. {word} itself is not included in the suggestions,
8756 although it may appear capitalized.
8757
8758 The spelling information for the current window is used. The
8759 values of 'spelllang' and 'spellsuggest' are used.
8760
8761 Can also be used as a |method|: >
8762 GetWord()->spellsuggest()
8763
8764split({string} [, {pattern} [, {keepempty}]]) *split()*
8765 Make a |List| out of {string}. When {pattern} is omitted or
8766 empty each white-separated sequence of characters becomes an
8767 item.
8768 Otherwise the string is split where {pattern} matches,
8769 removing the matched characters. 'ignorecase' is not used
8770 here, add \c to ignore case. |/\c|
8771 When the first or last item is empty it is omitted, unless the
8772 {keepempty} argument is given and it's non-zero.
8773 Other empty items are kept when {pattern} matches at least one
8774 character or when {keepempty} is non-zero.
8775 Example: >
8776 :let words = split(getline('.'), '\W\+')
8777< To split a string in individual characters: >
8778 :for c in split(mystring, '\zs')
8779< If you want to keep the separator you can also use '\zs' at
8780 the end of the pattern: >
8781 :echo split('abc:def:ghi', ':\zs')
8782< ['abc:', 'def:', 'ghi'] ~
8783 Splitting a table where the first element can be empty: >
8784 :let items = split(line, ':', 1)
8785< The opposite function is |join()|.
8786
8787 Can also be used as a |method|: >
8788 GetString()->split()
8789
8790sqrt({expr}) *sqrt()*
8791 Return the non-negative square root of Float {expr} as a
8792 |Float|.
8793 {expr} must evaluate to a |Float| or a |Number|. When {expr}
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008794 is negative the result is NaN (Not a Number). Returns 0.0 if
8795 {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008796 Examples: >
8797 :echo sqrt(100)
8798< 10.0 >
8799 :echo sqrt(-4.01)
8800< nan
8801 "nan" may be different, it depends on system libraries.
8802
8803 Can also be used as a |method|: >
8804 Compute()->sqrt()
8805<
8806 {only available when compiled with the |+float| feature}
8807
8808
8809srand([{expr}]) *srand()*
8810 Initialize seed used by |rand()|:
8811 - If {expr} is not given, seed values are initialized by
8812 reading from /dev/urandom, if possible, or using time(NULL)
8813 a.k.a. epoch time otherwise; this only has second accuracy.
8814 - If {expr} is given it must be a Number. It is used to
8815 initialize the seed values. This is useful for testing or
8816 when a predictable sequence is intended.
8817
8818 Examples: >
8819 :let seed = srand()
8820 :let seed = srand(userinput)
8821 :echo rand(seed)
8822
8823state([{what}]) *state()*
8824 Return a string which contains characters indicating the
8825 current state. Mostly useful in callbacks that want to do
8826 work that may not always be safe. Roughly this works like:
8827 - callback uses state() to check if work is safe to do.
8828 Yes: then do it right away.
8829 No: add to work queue and add a |SafeState| and/or
8830 |SafeStateAgain| autocommand (|SafeState| triggers at
8831 toplevel, |SafeStateAgain| triggers after handling
8832 messages and callbacks).
8833 - When SafeState or SafeStateAgain is triggered and executes
8834 your autocommand, check with `state()` if the work can be
8835 done now, and if yes remove it from the queue and execute.
8836 Remove the autocommand if the queue is now empty.
8837 Also see |mode()|.
8838
8839 When {what} is given only characters in this string will be
8840 added. E.g, this checks if the screen has scrolled: >
8841 if state('s') == ''
8842 " screen has not scrolled
8843<
8844 These characters indicate the state, generally indicating that
8845 something is busy:
8846 m halfway a mapping, :normal command, feedkeys() or
8847 stuffed command
8848 o operator pending, e.g. after |d|
8849 a Insert mode autocomplete active
8850 x executing an autocommand
8851 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8852 ch_readraw() when reading json
8853 S not triggering SafeState or SafeStateAgain, e.g. after
8854 |f| or a count
8855 c callback invoked, including timer (repeats for
8856 recursiveness up to "ccc")
8857 s screen has scrolled for messages
8858
8859str2float({string} [, {quoted}]) *str2float()*
8860 Convert String {string} to a Float. This mostly works the
8861 same as when using a floating point number in an expression,
8862 see |floating-point-format|. But it's a bit more permissive.
8863 E.g., "1e40" is accepted, while in an expression you need to
8864 write "1.0e40". The hexadecimal form "0x123" is also
8865 accepted, but not others, like binary or octal.
8866 When {quoted} is present and non-zero then embedded single
8867 quotes before the dot are ignored, thus "1'000.0" is a
8868 thousand.
8869 Text after the number is silently ignored.
8870 The decimal point is always '.', no matter what the locale is
8871 set to. A comma ends the number: "12,345.67" is converted to
8872 12.0. You can strip out thousands separators with
8873 |substitute()|: >
8874 let f = str2float(substitute(text, ',', '', 'g'))
8875<
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008876 Returns 0.0 if the conversion fails.
8877
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008878 Can also be used as a |method|: >
8879 let f = text->substitute(',', '', 'g')->str2float()
8880<
8881 {only available when compiled with the |+float| feature}
8882
8883str2list({string} [, {utf8}]) *str2list()*
8884 Return a list containing the number values which represent
8885 each character in String {string}. Examples: >
8886 str2list(" ") returns [32]
8887 str2list("ABC") returns [65, 66, 67]
8888< |list2str()| does the opposite.
8889
8890 When {utf8} is omitted or zero, the current 'encoding' is used.
8891 When {utf8} is TRUE, always treat the String as UTF-8
8892 characters. With UTF-8 composing characters are handled
8893 properly: >
8894 str2list("á") returns [97, 769]
8895
8896< Can also be used as a |method|: >
8897 GetString()->str2list()
8898
8899
8900str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8901 Convert string {string} to a number.
8902 {base} is the conversion base, it can be 2, 8, 10 or 16.
8903 When {quoted} is present and non-zero then embedded single
8904 quotes are ignored, thus "1'000'000" is a million.
8905
8906 When {base} is omitted base 10 is used. This also means that
8907 a leading zero doesn't cause octal conversion to be used, as
8908 with the default String to Number conversion. Example: >
8909 let nr = str2nr('0123')
8910<
8911 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8912 different base the result will be zero. Similarly, when
8913 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8914 {base} is 2 a leading "0b" or "0B" is ignored.
8915 Text after the number is silently ignored.
8916
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008917 Returns 0 if {string} is empty or on error.
8918
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008919 Can also be used as a |method|: >
8920 GetText()->str2nr()
8921
8922
8923strcharlen({string}) *strcharlen()*
8924 The result is a Number, which is the number of characters
8925 in String {string}. Composing characters are ignored.
8926 |strchars()| can count the number of characters, counting
8927 composing characters separately.
8928
Bram Moolenaar6ba83ba2022-06-12 22:15:57 +01008929 Returns 0 if {string} is empty or on error.
8930
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008931 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8932
8933 Can also be used as a |method|: >
8934 GetText()->strcharlen()
8935
8936
8937strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8938 Like |strpart()| but using character index and length instead
8939 of byte index and length.
8940 When {skipcc} is omitted or zero, composing characters are
8941 counted separately.
8942 When {skipcc} set to 1, Composing characters are ignored,
8943 similar to |slice()|.
8944 When a character index is used where a character does not
8945 exist it is omitted and counted as one character. For
8946 example: >
8947 strcharpart('abc', -1, 2)
8948< results in 'a'.
8949
Bram Moolenaard592deb2022-06-17 15:42:40 +01008950 Returns an empty string on error.
8951
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008952 Can also be used as a |method|: >
8953 GetText()->strcharpart(5)
8954
8955
8956strchars({string} [, {skipcc}]) *strchars()*
8957 The result is a Number, which is the number of characters
8958 in String {string}.
8959 When {skipcc} is omitted or zero, composing characters are
8960 counted separately.
8961 When {skipcc} set to 1, Composing characters are ignored.
8962 |strcharlen()| always does this.
8963
Bram Moolenaard592deb2022-06-17 15:42:40 +01008964 Returns zero on error.
8965
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008966 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8967
8968 {skipcc} is only available after 7.4.755. For backward
8969 compatibility, you can define a wrapper function: >
8970 if has("patch-7.4.755")
8971 function s:strchars(str, skipcc)
8972 return strchars(a:str, a:skipcc)
8973 endfunction
8974 else
8975 function s:strchars(str, skipcc)
8976 if a:skipcc
8977 return strlen(substitute(a:str, ".", "x", "g"))
8978 else
8979 return strchars(a:str)
8980 endif
8981 endfunction
8982 endif
8983<
8984 Can also be used as a |method|: >
8985 GetText()->strchars()
8986
8987strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8988 The result is a Number, which is the number of display cells
8989 String {string} occupies on the screen when it starts at {col}
8990 (first column is zero). When {col} is omitted zero is used.
8991 Otherwise it is the screen column where to start. This
8992 matters for Tab characters.
8993 The option settings of the current window are used. This
8994 matters for anything that's displayed differently, such as
8995 'tabstop' and 'display'.
8996 When {string} contains characters with East Asian Width Class
8997 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01008998 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008999 Also see |strlen()|, |strwidth()| and |strchars()|.
9000
9001 Can also be used as a |method|: >
9002 GetText()->strdisplaywidth()
9003
9004strftime({format} [, {time}]) *strftime()*
9005 The result is a String, which is a formatted date and time, as
9006 specified by the {format} string. The given {time} is used,
9007 or the current time if no time is given. The accepted
9008 {format} depends on your system, thus this is not portable!
9009 See the manual page of the C function strftime() for the
9010 format. The maximum length of the result is 80 characters.
9011 See also |localtime()|, |getftime()| and |strptime()|.
9012 The language can be changed with the |:language| command.
9013 Examples: >
9014 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9015 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9016 :echo strftime("%y%m%d %T") 970427 11:53:55
9017 :echo strftime("%H:%M") 11:55
9018 :echo strftime("%c", getftime("file.c"))
9019 Show mod time of file.c.
9020< Not available on all systems. To check use: >
9021 :if exists("*strftime")
9022
9023< Can also be used as a |method|: >
9024 GetFormat()->strftime()
9025
9026strgetchar({str}, {index}) *strgetchar()*
Bram Moolenaar2d8ed022022-05-21 13:08:16 +01009027 Get a Number corresponding to the character at {index} in
9028 {str}. This uses a zero-based character index, not a byte
9029 index. Composing characters are considered separate
9030 characters here. Use |nr2char()| to convert the Number to a
9031 String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009032 Returns -1 if {index} is invalid.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009033 Also see |strcharpart()| and |strchars()|.
9034
9035 Can also be used as a |method|: >
9036 GetText()->strgetchar(5)
9037
9038stridx({haystack}, {needle} [, {start}]) *stridx()*
9039 The result is a Number, which gives the byte index in
9040 {haystack} of the first occurrence of the String {needle}.
9041 If {start} is specified, the search starts at index {start}.
9042 This can be used to find a second match: >
9043 :let colon1 = stridx(line, ":")
9044 :let colon2 = stridx(line, ":", colon1 + 1)
9045< The search is done case-sensitive.
9046 For pattern searches use |match()|.
9047 -1 is returned if the {needle} does not occur in {haystack}.
9048 See also |strridx()|.
9049 Examples: >
9050 :echo stridx("An Example", "Example") 3
9051 :echo stridx("Starting point", "Start") 0
9052 :echo stridx("Starting point", "start") -1
9053< *strstr()* *strchr()*
9054 stridx() works similar to the C function strstr(). When used
9055 with a single character it works similar to strchr().
9056
9057 Can also be used as a |method|: >
9058 GetHaystack()->stridx(needle)
9059<
9060 *string()*
9061string({expr}) Return {expr} converted to a String. If {expr} is a Number,
9062 Float, String, Blob or a composition of them, then the result
9063 can be parsed back with |eval()|.
9064 {expr} type result ~
9065 String 'string' (single quotes are doubled)
9066 Number 123
9067 Float 123.123456 or 1.123456e8
9068 Funcref function('name')
9069 Blob 0z00112233.44556677.8899
9070 List [item, item]
9071 Dictionary {key: value, key: value}
9072
9073 When a |List| or |Dictionary| has a recursive reference it is
9074 replaced by "[...]" or "{...}". Using eval() on the result
9075 will then fail.
9076
9077 Can also be used as a |method|: >
9078 mylist->string()
9079
9080< Also see |strtrans()|.
9081
9082
9083strlen({string}) *strlen()*
9084 The result is a Number, which is the length of the String
9085 {string} in bytes.
9086 If the argument is a Number it is first converted to a String.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009087 For other types an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009088 If you want to count the number of multibyte characters use
9089 |strchars()|.
9090 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
9091
9092 Can also be used as a |method|: >
9093 GetString()->strlen()
9094
9095strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
9096 The result is a String, which is part of {src}, starting from
9097 byte {start}, with the byte length {len}.
9098 When {chars} is present and TRUE then {len} is the number of
9099 characters positions (composing characters are not counted
9100 separately, thus "1" means one base character and any
9101 following composing characters).
9102 To count {start} as characters instead of bytes use
9103 |strcharpart()|.
9104
9105 When bytes are selected which do not exist, this doesn't
9106 result in an error, the bytes are simply omitted.
9107 If {len} is missing, the copy continues from {start} till the
9108 end of the {src}. >
9109 strpart("abcdefg", 3, 2) == "de"
9110 strpart("abcdefg", -2, 4) == "ab"
9111 strpart("abcdefg", 5, 4) == "fg"
9112 strpart("abcdefg", 3) == "defg"
9113
9114< Note: To get the first character, {start} must be 0. For
9115 example, to get the character under the cursor: >
9116 strpart(getline("."), col(".") - 1, 1, v:true)
9117<
Bram Moolenaard592deb2022-06-17 15:42:40 +01009118 Returns an empty string on error.
9119
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009120 Can also be used as a |method|: >
9121 GetText()->strpart(5)
9122
9123strptime({format}, {timestring}) *strptime()*
9124 The result is a Number, which is a unix timestamp representing
9125 the date and time in {timestring}, which is expected to match
9126 the format specified in {format}.
9127
9128 The accepted {format} depends on your system, thus this is not
9129 portable! See the manual page of the C function strptime()
9130 for the format. Especially avoid "%c". The value of $TZ also
9131 matters.
9132
9133 If the {timestring} cannot be parsed with {format} zero is
9134 returned. If you do not know the format of {timestring} you
9135 can try different {format} values until you get a non-zero
9136 result.
9137
9138 See also |strftime()|.
9139 Examples: >
9140 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
9141< 862156163 >
9142 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
9143< Sun Apr 27 11:53:55 1997 >
9144 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
9145< Sun Apr 27 12:53:55 1997
9146
9147 Can also be used as a |method|: >
9148 GetFormat()->strptime(timestring)
9149<
9150 Not available on all systems. To check use: >
9151 :if exists("*strptime")
9152
9153strridx({haystack}, {needle} [, {start}]) *strridx()*
9154 The result is a Number, which gives the byte index in
9155 {haystack} of the last occurrence of the String {needle}.
9156 When {start} is specified, matches beyond this index are
9157 ignored. This can be used to find a match before a previous
9158 match: >
9159 :let lastcomma = strridx(line, ",")
9160 :let comma2 = strridx(line, ",", lastcomma - 1)
9161< The search is done case-sensitive.
9162 For pattern searches use |match()|.
9163 -1 is returned if the {needle} does not occur in {haystack}.
9164 If the {needle} is empty the length of {haystack} is returned.
9165 See also |stridx()|. Examples: >
9166 :echo strridx("an angry armadillo", "an") 3
9167< *strrchr()*
9168 When used with a single character it works similar to the C
9169 function strrchr().
9170
9171 Can also be used as a |method|: >
9172 GetHaystack()->strridx(needle)
9173
9174strtrans({string}) *strtrans()*
9175 The result is a String, which is {string} with all unprintable
9176 characters translated into printable characters |'isprint'|.
9177 Like they are shown in a window. Example: >
9178 echo strtrans(@a)
9179< This displays a newline in register a as "^@" instead of
9180 starting a new line.
9181
Bram Moolenaard592deb2022-06-17 15:42:40 +01009182 Returns an empty string on error.
9183
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009184 Can also be used as a |method|: >
9185 GetString()->strtrans()
9186
9187strwidth({string}) *strwidth()*
9188 The result is a Number, which is the number of display cells
9189 String {string} occupies. A Tab character is counted as one
9190 cell, alternatively use |strdisplaywidth()|.
9191 When {string} contains characters with East Asian Width Class
9192 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009193 Returns zero on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009194 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
9195
9196 Can also be used as a |method|: >
9197 GetString()->strwidth()
9198
9199submatch({nr} [, {list}]) *submatch()* *E935*
9200 Only for an expression in a |:substitute| command or
9201 substitute() function.
9202 Returns the {nr}'th submatch of the matched text. When {nr}
9203 is 0 the whole matched text is returned.
9204 Note that a NL in the string can stand for a line break of a
9205 multi-line match or a NUL character in the text.
9206 Also see |sub-replace-expression|.
9207
9208 If {list} is present and non-zero then submatch() returns
9209 a list of strings, similar to |getline()| with two arguments.
9210 NL characters in the text represent NUL characters in the
9211 text.
9212 Only returns more than one item for |:substitute|, inside
9213 |substitute()| this list will always contain one or zero
9214 items, since there are no real line breaks.
9215
9216 When substitute() is used recursively only the submatches in
9217 the current (deepest) call can be obtained.
9218
Bram Moolenaard592deb2022-06-17 15:42:40 +01009219 Returns an empty string or list on error.
9220
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009221 Examples: >
9222 :s/\d\+/\=submatch(0) + 1/
9223 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
9224< This finds the first number in the line and adds one to it.
9225 A line break is included as a newline character.
9226
9227 Can also be used as a |method|: >
9228 GetNr()->submatch()
9229
9230substitute({string}, {pat}, {sub}, {flags}) *substitute()*
9231 The result is a String, which is a copy of {string}, in which
9232 the first match of {pat} is replaced with {sub}.
9233 When {flags} is "g", all matches of {pat} in {string} are
9234 replaced. Otherwise {flags} should be "".
9235
9236 This works like the ":substitute" command (without any flags).
9237 But the matching with {pat} is always done like the 'magic'
9238 option is set and 'cpoptions' is empty (to make scripts
9239 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9240 if you want to ignore or match case and ignore 'ignorecase'.
9241 'smartcase' is not used. See |string-match| for how {pat} is
9242 used.
9243
9244 A "~" in {sub} is not replaced with the previous {sub}.
9245 Note that some codes in {sub} have a special meaning
9246 |sub-replace-special|. For example, to replace something with
9247 "\n" (two characters), use "\\\\n" or '\\n'.
9248
9249 When {pat} does not match in {string}, {string} is returned
9250 unmodified.
9251
9252 Example: >
9253 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
9254< This removes the last component of the 'path' option. >
9255 :echo substitute("testing", ".*", "\\U\\0", "")
9256< results in "TESTING".
9257
9258 When {sub} starts with "\=", the remainder is interpreted as
9259 an expression. See |sub-replace-expression|. Example: >
9260 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009261 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009262
9263< When {sub} is a Funcref that function is called, with one
9264 optional argument. Example: >
9265 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9266< The optional argument is a list which contains the whole
9267 matched string and up to nine submatches, like what
9268 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009269 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009270
Bram Moolenaard592deb2022-06-17 15:42:40 +01009271< Returns an empty string on error.
9272
9273 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009274 GetString()->substitute(pat, sub, flags)
9275
9276swapinfo({fname}) *swapinfo()*
9277 The result is a dictionary, which holds information about the
9278 swapfile {fname}. The available fields are:
9279 version Vim version
9280 user user name
9281 host host name
9282 fname original file name
9283 pid PID of the Vim process that created the swap
9284 file
9285 mtime last modification time in seconds
9286 inode Optional: INODE number of the file
9287 dirty 1 if file was modified, 0 if not
9288 Note that "user" and "host" are truncated to at most 39 bytes.
9289 In case of failure an "error" item is added with the reason:
9290 Cannot open file: file not found or in accessible
9291 Cannot read file: cannot read first block
9292 Not a swap file: does not contain correct block ID
9293 Magic number mismatch: Info in first block is invalid
9294
9295 Can also be used as a |method|: >
9296 GetFilename()->swapinfo()
9297
9298swapname({buf}) *swapname()*
9299 The result is the swap file path of the buffer {expr}.
9300 For the use of {buf}, see |bufname()| above.
9301 If buffer {buf} is the current buffer, the result is equal to
9302 |:swapname| (unless there is no swap file).
9303 If buffer {buf} has no swap file, returns an empty string.
9304
9305 Can also be used as a |method|: >
9306 GetBufname()->swapname()
9307
9308synID({lnum}, {col}, {trans}) *synID()*
9309 The result is a Number, which is the syntax ID at the position
9310 {lnum} and {col} in the current window.
9311 The syntax ID can be used with |synIDattr()| and
9312 |synIDtrans()| to obtain syntax information about text.
9313
9314 {col} is 1 for the leftmost column, {lnum} is 1 for the first
9315 line. 'synmaxcol' applies, in a longer line zero is returned.
9316 Note that when the position is after the last character,
9317 that's where the cursor can be in Insert mode, synID() returns
9318 zero. {lnum} is used like with |getline()|.
9319
9320 When {trans} is |TRUE|, transparent items are reduced to the
9321 item that they reveal. This is useful when wanting to know
9322 the effective color. When {trans} is |FALSE|, the transparent
9323 item is returned. This is useful when wanting to know which
9324 syntax item is effective (e.g. inside parens).
9325 Warning: This function can be very slow. Best speed is
9326 obtained by going through the file in forward direction.
9327
Bram Moolenaard592deb2022-06-17 15:42:40 +01009328 Returns zero on error.
9329
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009330 Example (echoes the name of the syntax item under the cursor): >
9331 :echo synIDattr(synID(line("."), col("."), 1), "name")
9332<
9333
9334synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9335 The result is a String, which is the {what} attribute of
9336 syntax ID {synID}. This can be used to obtain information
9337 about a syntax item.
9338 {mode} can be "gui", "cterm" or "term", to get the attributes
9339 for that mode. When {mode} is omitted, or an invalid value is
9340 used, the attributes for the currently active highlighting are
9341 used (GUI, cterm or term).
9342 Use synIDtrans() to follow linked highlight groups.
9343 {what} result
9344 "name" the name of the syntax item
9345 "fg" foreground color (GUI: color name used to set
9346 the color, cterm: color number as a string,
9347 term: empty string)
9348 "bg" background color (as with "fg")
9349 "font" font name (only available in the GUI)
9350 |highlight-font|
9351 "sp" special color for the GUI (as with "fg")
9352 |highlight-guisp|
9353 "ul" underline color for cterm: number as a string
9354 "fg#" like "fg", but for the GUI and the GUI is
9355 running the name in "#RRGGBB" form
9356 "bg#" like "fg#" for "bg"
9357 "sp#" like "fg#" for "sp"
9358 "bold" "1" if bold
9359 "italic" "1" if italic
9360 "reverse" "1" if reverse
9361 "inverse" "1" if inverse (= reverse)
9362 "standout" "1" if standout
9363 "underline" "1" if underlined
9364 "undercurl" "1" if undercurled
9365 "strike" "1" if strikethrough
Bram Moolenaarde786322022-07-30 14:56:17 +01009366 "nocombine" "1" if nocombine
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009367
Bram Moolenaard592deb2022-06-17 15:42:40 +01009368 Returns an empty string on error.
9369
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009370 Example (echoes the color of the syntax item under the
9371 cursor): >
9372 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9373<
9374 Can also be used as a |method|: >
9375 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9376
9377
9378synIDtrans({synID}) *synIDtrans()*
9379 The result is a Number, which is the translated syntax ID of
9380 {synID}. This is the syntax group ID of what is being used to
9381 highlight the character. Highlight links given with
9382 ":highlight link" are followed.
9383
Bram Moolenaard592deb2022-06-17 15:42:40 +01009384 Returns zero on error.
9385
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009386 Can also be used as a |method|: >
9387 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9388
9389synconcealed({lnum}, {col}) *synconcealed()*
9390 The result is a |List| with currently three items:
9391 1. The first item in the list is 0 if the character at the
9392 position {lnum} and {col} is not part of a concealable
9393 region, 1 if it is. {lnum} is used like with |getline()|.
9394 2. The second item in the list is a string. If the first item
9395 is 1, the second item contains the text which will be
9396 displayed in place of the concealed text, depending on the
9397 current setting of 'conceallevel' and 'listchars'.
9398 3. The third and final item in the list is a number
9399 representing the specific syntax region matched in the
9400 line. When the character is not concealed the value is
9401 zero. This allows detection of the beginning of a new
9402 concealable region if there are two consecutive regions
9403 with the same replacement character. For an example, if
9404 the text is "123456" and both "23" and "45" are concealed
9405 and replaced by the character "X", then:
9406 call returns ~
9407 synconcealed(lnum, 1) [0, '', 0]
9408 synconcealed(lnum, 2) [1, 'X', 1]
9409 synconcealed(lnum, 3) [1, 'X', 1]
9410 synconcealed(lnum, 4) [1, 'X', 2]
9411 synconcealed(lnum, 5) [1, 'X', 2]
9412 synconcealed(lnum, 6) [0, '', 0]
9413
9414
9415synstack({lnum}, {col}) *synstack()*
9416 Return a |List|, which is the stack of syntax items at the
9417 position {lnum} and {col} in the current window. {lnum} is
9418 used like with |getline()|. Each item in the List is an ID
9419 like what |synID()| returns.
9420 The first item in the List is the outer region, following are
9421 items contained in that one. The last one is what |synID()|
9422 returns, unless not the whole item is highlighted or it is a
9423 transparent item.
9424 This function is useful for debugging a syntax file.
9425 Example that shows the syntax stack under the cursor: >
9426 for id in synstack(line("."), col("."))
9427 echo synIDattr(id, "name")
9428 endfor
9429< When the position specified with {lnum} and {col} is invalid
Bram Moolenaard592deb2022-06-17 15:42:40 +01009430 an empty List is returned. The position just after the last
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009431 character in a line and the first column in an empty line are
9432 valid positions.
9433
9434system({expr} [, {input}]) *system()* *E677*
9435 Get the output of the shell command {expr} as a |String|. See
9436 |systemlist()| to get the output as a |List|.
9437
9438 When {input} is given and is a |String| this string is written
9439 to a file and passed as stdin to the command. The string is
9440 written as-is, you need to take care of using the correct line
9441 separators yourself.
9442 If {input} is given and is a |List| it is written to the file
9443 in a way |writefile()| does with {binary} set to "b" (i.e.
9444 with a newline between each list item with newlines inside
9445 list items converted to NULs).
9446 When {input} is given and is a number that is a valid id for
9447 an existing buffer then the content of the buffer is written
9448 to the file line by line, each line terminated by a NL and
9449 NULs characters where the text has a NL.
9450
9451 Pipes are not used, the 'shelltemp' option is not used.
9452
9453 When prepended by |:silent| the terminal will not be set to
9454 cooked mode. This is meant to be used for commands that do
9455 not need the user to type. It avoids stray characters showing
9456 up on the screen which require |CTRL-L| to remove. >
9457 :silent let f = system('ls *.vim')
9458<
9459 Note: Use |shellescape()| or |::S| with |expand()| or
9460 |fnamemodify()| to escape special characters in a command
9461 argument. Newlines in {expr} may cause the command to fail.
9462 The characters in 'shellquote' and 'shellxquote' may also
9463 cause trouble.
9464 This is not to be used for interactive commands.
9465
9466 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009467 :let files = system('ls ' .. shellescape(expand('%:h')))
9468 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009469
9470< To make the result more system-independent, the shell output
9471 is filtered to replace <CR> with <NL> for Macintosh, and
9472 <CR><NL> with <NL> for DOS-like systems.
9473 To avoid the string being truncated at a NUL, all NUL
9474 characters are replaced with SOH (0x01).
9475
9476 The command executed is constructed using several options:
9477 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9478 ({tmp} is an automatically generated file name).
9479 For Unix, braces are put around {expr} to allow for
9480 concatenated commands.
9481
9482 The command will be executed in "cooked" mode, so that a
9483 CTRL-C will interrupt the command (on Unix at least).
9484
9485 The resulting error code can be found in |v:shell_error|.
9486 This function will fail in |restricted-mode|.
9487
9488 Note that any wrong value in the options mentioned above may
9489 make the function fail. It has also been reported to fail
9490 when using a security agent application.
9491 Unlike ":!cmd" there is no automatic check for changed files.
9492 Use |:checktime| to force a check.
9493
9494 Can also be used as a |method|: >
9495 :echo GetCmd()->system()
9496
9497
9498systemlist({expr} [, {input}]) *systemlist()*
9499 Same as |system()|, but returns a |List| with lines (parts of
9500 output separated by NL) with NULs transformed into NLs. Output
9501 is the same as |readfile()| will output with {binary} argument
9502 set to "b", except that there is no extra empty item when the
9503 result ends in a NL.
9504 Note that on MS-Windows you may get trailing CR characters.
9505
9506 To see the difference between "echo hello" and "echo -n hello"
9507 use |system()| and |split()|: >
9508 echo system('echo hello')->split('\n', 1)
9509<
9510 Returns an empty string on error.
9511
9512 Can also be used as a |method|: >
9513 :echo GetCmd()->systemlist()
9514
9515
9516tabpagebuflist([{arg}]) *tabpagebuflist()*
9517 The result is a |List|, where each item is the number of the
9518 buffer associated with each window in the current tab page.
9519 {arg} specifies the number of the tab page to be used. When
9520 omitted the current tab page is used.
9521 When {arg} is invalid the number zero is returned.
9522 To get a list of all buffers in all tabs use this: >
9523 let buflist = []
9524 for i in range(tabpagenr('$'))
9525 call extend(buflist, tabpagebuflist(i + 1))
9526 endfor
9527< Note that a buffer may appear in more than one window.
9528
9529 Can also be used as a |method|: >
9530 GetTabpage()->tabpagebuflist()
9531
9532tabpagenr([{arg}]) *tabpagenr()*
9533 The result is a Number, which is the number of the current
9534 tab page. The first tab page has number 1.
9535
9536 The optional argument {arg} supports the following values:
9537 $ the number of the last tab page (the tab page
9538 count).
9539 # the number of the last accessed tab page
9540 (where |g<Tab>| goes to). if there is no
9541 previous tab page 0 is returned.
9542 The number can be used with the |:tab| command.
9543
Bram Moolenaard592deb2022-06-17 15:42:40 +01009544 Returns zero on error.
9545
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009546
9547tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9548 Like |winnr()| but for tab page {tabarg}.
9549 {tabarg} specifies the number of tab page to be used.
9550 {arg} is used like with |winnr()|:
9551 - When omitted the current window number is returned. This is
9552 the window which will be used when going to this tab page.
9553 - When "$" the number of windows is returned.
9554 - When "#" the previous window nr is returned.
9555 Useful examples: >
9556 tabpagewinnr(1) " current window of tab page 1
9557 tabpagewinnr(4, '$') " number of windows in tab page 4
9558< When {tabarg} is invalid zero is returned.
9559
9560 Can also be used as a |method|: >
9561 GetTabpage()->tabpagewinnr()
9562<
9563 *tagfiles()*
9564tagfiles() Returns a |List| with the file names used to search for tags
9565 for the current buffer. This is the 'tags' option expanded.
9566
9567
9568taglist({expr} [, {filename}]) *taglist()*
9569 Returns a |List| of tags matching the regular expression {expr}.
9570
9571 If {filename} is passed it is used to prioritize the results
9572 in the same way that |:tselect| does. See |tag-priority|.
9573 {filename} should be the full path of the file.
9574
9575 Each list item is a dictionary with at least the following
9576 entries:
9577 name Name of the tag.
9578 filename Name of the file where the tag is
9579 defined. It is either relative to the
9580 current directory or a full path.
9581 cmd Ex command used to locate the tag in
9582 the file.
9583 kind Type of the tag. The value for this
9584 entry depends on the language specific
9585 kind values. Only available when
9586 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +00009587 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009588 static A file specific tag. Refer to
9589 |static-tag| for more information.
9590 More entries may be present, depending on the content of the
9591 tags file: access, implementation, inherits and signature.
9592 Refer to the ctags documentation for information about these
9593 fields. For C code the fields "struct", "class" and "enum"
9594 may appear, they give the name of the entity the tag is
9595 contained in.
9596
9597 The ex-command "cmd" can be either an ex search pattern, a
9598 line number or a line number followed by a byte number.
9599
9600 If there are no matching tags, then an empty list is returned.
9601
9602 To get an exact tag match, the anchors '^' and '$' should be
9603 used in {expr}. This also make the function work faster.
9604 Refer to |tag-regexp| for more information about the tag
9605 search regular expression pattern.
9606
9607 Refer to |'tags'| for information about how the tags file is
9608 located by Vim. Refer to |tags-file-format| for the format of
9609 the tags file generated by the different ctags tools.
9610
9611 Can also be used as a |method|: >
9612 GetTagpattern()->taglist()
9613
9614tan({expr}) *tan()*
9615 Return the tangent of {expr}, measured in radians, as a |Float|
9616 in the range [-inf, inf].
9617 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009618 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009619 Examples: >
9620 :echo tan(10)
9621< 0.648361 >
9622 :echo tan(-4.01)
9623< -1.181502
9624
9625 Can also be used as a |method|: >
9626 Compute()->tan()
9627<
9628 {only available when compiled with the |+float| feature}
9629
9630
9631tanh({expr}) *tanh()*
9632 Return the hyperbolic tangent of {expr} as a |Float| in the
9633 range [-1, 1].
9634 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009635 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009636 Examples: >
9637 :echo tanh(0.5)
9638< 0.462117 >
9639 :echo tanh(-1)
9640< -0.761594
9641
9642 Can also be used as a |method|: >
9643 Compute()->tanh()
9644<
9645 {only available when compiled with the |+float| feature}
9646
9647
9648tempname() *tempname()* *temp-file-name*
9649 The result is a String, which is the name of a file that
9650 doesn't exist. It can be used for a temporary file. The name
9651 is different for at least 26 consecutive calls. Example: >
9652 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009653 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009654< For Unix, the file will be in a private directory |tempfile|.
9655 For MS-Windows forward slashes are used when the 'shellslash'
9656 option is set, or when 'shellcmdflag' starts with '-' and
9657 'shell' does not contain powershell or pwsh.
9658
9659
9660term_ functions are documented here: |terminal-function-details|
9661
9662
9663terminalprops() *terminalprops()*
9664 Returns a |Dictionary| with properties of the terminal that Vim
9665 detected from the response to |t_RV| request. See
9666 |v:termresponse| for the response itself. If |v:termresponse|
9667 is empty most values here will be 'u' for unknown.
9668 cursor_style whether sending |t_RS| works **
9669 cursor_blink_mode whether sending |t_RC| works **
9670 underline_rgb whether |t_8u| works **
9671 mouse mouse type supported
9672
9673 ** value 'u' for unknown, 'y' for yes, 'n' for no
9674
9675 If the |+termresponse| feature is missing then the result is
9676 an empty dictionary.
9677
9678 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9679 current cursor style.
9680 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9681 request the cursor blink status.
9682 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9683 is not empty, Vim will detect the working of sending |t_RS|
9684 and |t_RC| on startup.
9685
9686 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9687 This avoids sending it to xterm, which would clear the colors.
9688
9689 For "mouse" the value 'u' is unknown
9690
9691 Also see:
9692 - 'ambiwidth' - detected by using |t_u7|.
9693 - |v:termstyleresp| and |v:termblinkresp| for the response to
9694 |t_RS| and |t_RC|.
9695
9696
9697test_ functions are documented here: |test-functions-details|
9698
9699
9700 *timer_info()*
9701timer_info([{id}])
9702 Return a list with information about timers.
9703 When {id} is given only information about this timer is
9704 returned. When timer {id} does not exist an empty list is
9705 returned.
9706 When {id} is omitted information about all timers is returned.
9707
9708 For each timer the information is stored in a |Dictionary| with
9709 these items:
9710 "id" the timer ID
9711 "time" time the timer was started with
9712 "remaining" time until the timer fires
9713 "repeat" number of times the timer will still fire;
9714 -1 means forever
9715 "callback" the callback
9716 "paused" 1 if the timer is paused, 0 otherwise
9717
9718 Can also be used as a |method|: >
9719 GetTimer()->timer_info()
9720
9721< {only available when compiled with the |+timers| feature}
9722
9723timer_pause({timer}, {paused}) *timer_pause()*
9724 Pause or unpause a timer. A paused timer does not invoke its
9725 callback when its time expires. Unpausing a timer may cause
9726 the callback to be invoked almost immediately if enough time
9727 has passed.
9728
9729 Pausing a timer is useful to avoid the callback to be called
9730 for a short time.
9731
9732 If {paused} evaluates to a non-zero Number or a non-empty
9733 String, then the timer is paused, otherwise it is unpaused.
9734 See |non-zero-arg|.
9735
9736 Can also be used as a |method|: >
9737 GetTimer()->timer_pause(1)
9738
9739< {only available when compiled with the |+timers| feature}
9740
9741 *timer_start()* *timer* *timers*
9742timer_start({time}, {callback} [, {options}])
9743 Create a timer and return the timer ID.
9744
9745 {time} is the waiting time in milliseconds. This is the
9746 minimum time before invoking the callback. When the system is
9747 busy or Vim is not waiting for input the time will be longer.
9748
9749 {callback} is the function to call. It can be the name of a
9750 function or a |Funcref|. It is called with one argument, which
9751 is the timer ID. The callback is only invoked when Vim is
9752 waiting for input.
9753 If you want to show a message look at |popup_notification()|
9754 to avoid interfering with what the user is doing.
9755
9756 {options} is a dictionary. Supported entries:
9757 "repeat" Number of times to repeat calling the
9758 callback. -1 means forever. When not present
9759 the callback will be called once.
9760 If the timer causes an error three times in a
9761 row the repeat is cancelled. This avoids that
9762 Vim becomes unusable because of all the error
9763 messages.
9764
Bram Moolenaard592deb2022-06-17 15:42:40 +01009765 Returns -1 on error.
9766
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009767 Example: >
9768 func MyHandler(timer)
9769 echo 'Handler called'
9770 endfunc
9771 let timer = timer_start(500, 'MyHandler',
9772 \ {'repeat': 3})
9773< This will invoke MyHandler() three times at 500 msec
9774 intervals.
9775
9776 Can also be used as a |method|: >
9777 GetMsec()->timer_start(callback)
9778
9779< Not available in the |sandbox|.
9780 {only available when compiled with the |+timers| feature}
9781
9782timer_stop({timer}) *timer_stop()*
9783 Stop a timer. The timer callback will no longer be invoked.
9784 {timer} is an ID returned by timer_start(), thus it must be a
9785 Number. If {timer} does not exist there is no error.
9786
9787 Can also be used as a |method|: >
9788 GetTimer()->timer_stop()
9789
9790< {only available when compiled with the |+timers| feature}
9791
9792timer_stopall() *timer_stopall()*
9793 Stop all timers. The timer callbacks will no longer be
9794 invoked. Useful if a timer is misbehaving. If there are no
9795 timers there is no error.
9796
9797 {only available when compiled with the |+timers| feature}
9798
9799tolower({expr}) *tolower()*
9800 The result is a copy of the String given, with all uppercase
9801 characters turned into lowercase (just like applying |gu| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009802 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009803
9804 Can also be used as a |method|: >
9805 GetText()->tolower()
9806
9807toupper({expr}) *toupper()*
9808 The result is a copy of the String given, with all lowercase
9809 characters turned into uppercase (just like applying |gU| to
Bram Moolenaard592deb2022-06-17 15:42:40 +01009810 the string). Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009811
9812 Can also be used as a |method|: >
9813 GetText()->toupper()
9814
9815tr({src}, {fromstr}, {tostr}) *tr()*
9816 The result is a copy of the {src} string with all characters
9817 which appear in {fromstr} replaced by the character in that
9818 position in the {tostr} string. Thus the first character in
9819 {fromstr} is translated into the first character in {tostr}
9820 and so on. Exactly like the unix "tr" command.
9821 This code also deals with multibyte characters properly.
9822
Bram Moolenaard592deb2022-06-17 15:42:40 +01009823 Returns an empty string on error.
9824
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009825 Examples: >
9826 echo tr("hello there", "ht", "HT")
9827< returns "Hello THere" >
9828 echo tr("<blob>", "<>", "{}")
9829< returns "{blob}"
9830
9831 Can also be used as a |method|: >
9832 GetText()->tr(from, to)
9833
9834trim({text} [, {mask} [, {dir}]]) *trim()*
9835 Return {text} as a String where any character in {mask} is
9836 removed from the beginning and/or end of {text}.
9837
9838 If {mask} is not given, {mask} is all characters up to 0x20,
9839 which includes Tab, space, NL and CR, plus the non-breaking
9840 space character 0xa0.
9841
9842 The optional {dir} argument specifies where to remove the
9843 characters:
9844 0 remove from the beginning and end of {text}
9845 1 remove only at the beginning of {text}
9846 2 remove only at the end of {text}
9847 When omitted both ends are trimmed.
9848
9849 This function deals with multibyte characters properly.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009850 Returns an empty string on error.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009851
9852 Examples: >
9853 echo trim(" some text ")
9854< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009855 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009856< returns "RESERVE_TAIL" >
9857 echo trim("rm<Xrm<>X>rrm", "rm<>")
9858< returns "Xrm<>X" (characters in the middle are not removed) >
9859 echo trim(" vim ", " ", 2)
9860< returns " vim"
9861
9862 Can also be used as a |method|: >
9863 GetText()->trim()
9864
9865trunc({expr}) *trunc()*
9866 Return the largest integral value with magnitude less than or
9867 equal to {expr} as a |Float| (truncate towards zero).
9868 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009869 Returns 0.0 if {expr} is not a |Float| or a |Number|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009870 Examples: >
9871 echo trunc(1.456)
9872< 1.0 >
9873 echo trunc(-5.456)
9874< -5.0 >
9875 echo trunc(4.0)
9876< 4.0
9877
9878 Can also be used as a |method|: >
9879 Compute()->trunc()
9880<
9881 {only available when compiled with the |+float| feature}
9882
9883 *type()*
9884type({expr}) The result is a Number representing the type of {expr}.
9885 Instead of using the number directly, it is better to use the
9886 v:t_ variable that has the value:
9887 Number: 0 |v:t_number|
9888 String: 1 |v:t_string|
9889 Funcref: 2 |v:t_func|
9890 List: 3 |v:t_list|
9891 Dictionary: 4 |v:t_dict|
9892 Float: 5 |v:t_float|
9893 Boolean: 6 |v:t_bool| (v:false and v:true)
9894 None: 7 |v:t_none| (v:null and v:none)
9895 Job: 8 |v:t_job|
9896 Channel: 9 |v:t_channel|
9897 Blob: 10 |v:t_blob|
9898 For backward compatibility, this method can be used: >
9899 :if type(myvar) == type(0)
9900 :if type(myvar) == type("")
9901 :if type(myvar) == type(function("tr"))
9902 :if type(myvar) == type([])
9903 :if type(myvar) == type({})
9904 :if type(myvar) == type(0.0)
9905 :if type(myvar) == type(v:false)
9906 :if type(myvar) == type(v:none)
9907< To check if the v:t_ variables exist use this: >
9908 :if exists('v:t_number')
9909
9910< Can also be used as a |method|: >
9911 mylist->type()
9912
9913
9914typename({expr}) *typename()*
9915 Return a string representation of the type of {expr}.
9916 Example: >
9917 echo typename([1, 2, 3])
9918 list<number>
9919
9920
9921undofile({name}) *undofile()*
9922 Return the name of the undo file that would be used for a file
9923 with name {name} when writing. This uses the 'undodir'
9924 option, finding directories that exist. It does not check if
9925 the undo file exists.
9926 {name} is always expanded to the full path, since that is what
9927 is used internally.
9928 If {name} is empty undofile() returns an empty string, since a
9929 buffer without a file name will not write an undo file.
9930 Useful in combination with |:wundo| and |:rundo|.
9931 When compiled without the |+persistent_undo| option this always
9932 returns an empty string.
9933
9934 Can also be used as a |method|: >
9935 GetFilename()->undofile()
9936
9937undotree() *undotree()*
9938 Return the current state of the undo tree in a dictionary with
9939 the following items:
9940 "seq_last" The highest undo sequence number used.
9941 "seq_cur" The sequence number of the current position in
9942 the undo tree. This differs from "seq_last"
9943 when some changes were undone.
9944 "time_cur" Time last used for |:earlier| and related
9945 commands. Use |strftime()| to convert to
9946 something readable.
9947 "save_last" Number of the last file write. Zero when no
9948 write yet.
9949 "save_cur" Number of the current position in the undo
9950 tree.
9951 "synced" Non-zero when the last undo block was synced.
9952 This happens when waiting from input from the
9953 user. See |undo-blocks|.
9954 "entries" A list of dictionaries with information about
9955 undo blocks.
9956
9957 The first item in the "entries" list is the oldest undo item.
9958 Each List item is a |Dictionary| with these items:
9959 "seq" Undo sequence number. Same as what appears in
9960 |:undolist|.
9961 "time" Timestamp when the change happened. Use
9962 |strftime()| to convert to something readable.
9963 "newhead" Only appears in the item that is the last one
9964 that was added. This marks the last change
9965 and where further changes will be added.
9966 "curhead" Only appears in the item that is the last one
9967 that was undone. This marks the current
9968 position in the undo tree, the block that will
9969 be used by a redo command. When nothing was
9970 undone after the last change this item will
9971 not appear anywhere.
9972 "save" Only appears on the last block before a file
9973 write. The number is the write count. The
9974 first write has number 1, the last one the
9975 "save_last" mentioned above.
9976 "alt" Alternate entry. This is again a List of undo
9977 blocks. Each item may again have an "alt"
9978 item.
9979
9980uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9981 Remove second and succeeding copies of repeated adjacent
9982 {list} items in-place. Returns {list}. If you want a list
9983 to remain unmodified make a copy first: >
9984 :let newlist = uniq(copy(mylist))
9985< The default compare function uses the string representation of
9986 each item. For the use of {func} and {dict} see |sort()|.
9987
Bram Moolenaard592deb2022-06-17 15:42:40 +01009988 Returns zero if {list} is not a |List|.
9989
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009990 Can also be used as a |method|: >
9991 mylist->uniq()
9992
9993values({dict}) *values()*
9994 Return a |List| with all the values of {dict}. The |List| is
9995 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaard592deb2022-06-17 15:42:40 +01009996 Returns zero if {dict} is not a |Dict|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009997
9998 Can also be used as a |method|: >
9999 mydict->values()
10000
LemonBoy0f7a3e12022-05-26 12:10:37 +010010001virtcol({expr} [, {list}]) *virtcol()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010002 The result is a Number, which is the screen column of the file
10003 position given with {expr}. That is, the last screen position
10004 occupied by the character at that position, when the screen
10005 would be of unlimited width. When there is a <Tab> at the
10006 position, the returned Number will be the column at the end of
10007 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
10008 set to 8, it returns 8. |conceal| is ignored.
10009 For the byte position use |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010010
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010011 For the use of {expr} see |col()|.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010012
10013 When 'virtualedit' is used {expr} can be [lnum, col, off],
10014 where "off" is the offset in screen columns from the start of
10015 the character. E.g., a position within a <Tab> or after the
10016 last character. When "off" is omitted zero is used. When
10017 Virtual editing is active in the current mode, a position
10018 beyond the end of the line can be returned. Also see
10019 |'virtualedit'|
10020
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010021 The accepted positions are:
10022 . the cursor position
10023 $ the end of the cursor line (the result is the
10024 number of displayed characters in the cursor line
10025 plus one)
10026 'x position of mark x (if the mark is not set, 0 is
10027 returned)
10028 v In Visual mode: the start of the Visual area (the
10029 cursor is the end). When not in Visual mode
10030 returns the cursor position. Differs from |'<| in
10031 that it's updated right away.
LemonBoy0f7a3e12022-05-26 12:10:37 +010010032
10033 If {list} is present and non-zero then virtcol() returns a List
10034 with the first and last screen position occupied by the
10035 character.
10036
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010037 Note that only marks in the current file can be used.
10038 Examples: >
LemonBoy0f7a3e12022-05-26 12:10:37 +010010039 " With text "foo^Lbar" and cursor on the "^L":
10040
10041 virtcol(".") " returns 5
10042 virtcol(".", 1) " returns [4, 5]
10043 virtcol("$") " returns 9
10044
10045 " With text " there", with 't at 'h':
10046
10047 virtcol("'t") " returns 6
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010048< The first column is 1. 0 is returned for an error.
10049 A more advanced example that echoes the maximum length of
10050 all lines: >
10051 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10052
10053< Can also be used as a |method|: >
10054 GetPos()->virtcol()
10055
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010056virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
10057 The result is a Number, which is the byte index of the
10058 character in window {winid} at buffer line {lnum} and virtual
10059 column {col}.
10060
10061 If {col} is greater than the last virtual column in line
10062 {lnum}, then the byte index of the character at the last
10063 virtual column is returned.
10064
10065 The {winid} argument can be the window number or the
10066 |window-ID|. If this is zero, then the current window is used.
10067
10068 Returns -1 if the window {winid} doesn't exist or the buffer
10069 line {lnum} or virtual column {col} is invalid.
10070
10071 See also |screenpos()|, |virtcol()| and |col()|.
10072
10073 Can also be used as a |method|: >
10074 GetWinid()->virtcol2col(lnum, col)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010075
10076visualmode([{expr}]) *visualmode()*
10077 The result is a String, which describes the last Visual mode
10078 used in the current buffer. Initially it returns an empty
10079 string, but once Visual mode has been used, it returns "v",
10080 "V", or "<CTRL-V>" (a single CTRL-V character) for
10081 character-wise, line-wise, or block-wise Visual mode
10082 respectively.
10083 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010084 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010085< This enters the same Visual mode as before. It is also useful
10086 in scripts if you wish to act differently depending on the
10087 Visual mode that was used.
10088 If Visual mode is active, use |mode()| to get the Visual mode
10089 (e.g., in a |:vmap|).
10090 If {expr} is supplied and it evaluates to a non-zero Number or
10091 a non-empty String, then the Visual mode will be cleared and
10092 the old value is returned. See |non-zero-arg|.
10093
10094wildmenumode() *wildmenumode()*
10095 Returns |TRUE| when the wildmenu is active and |FALSE|
10096 otherwise. See 'wildmenu' and 'wildmode'.
10097 This can be used in mappings to handle the 'wildcharm' option
10098 gracefully. (Makes only sense with |mapmode-c| mappings).
10099
10100 For example to make <c-j> work like <down> in wildmode, use: >
10101 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10102<
10103 (Note, this needs the 'wildcharm' option set appropriately).
10104
10105win_execute({id}, {command} [, {silent}]) *win_execute()*
10106 Like `execute()` but in the context of window {id}.
10107 The window will temporarily be made the current window,
10108 without triggering autocommands or changing directory. When
10109 executing {command} autocommands will be triggered, this may
10110 have unexpected side effects. Use |:noautocmd| if needed.
10111 Example: >
10112 call win_execute(winid, 'set syntax=python')
10113< Doing the same with `setwinvar()` would not trigger
10114 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010115 *E994*
10116 Not all commands are allowed in popup windows.
10117 When window {id} does not exist then no error is given and
10118 an empty string is returned.
10119
10120 Can also be used as a |method|, the base is passed as the
10121 second argument: >
10122 GetCommand()->win_execute(winid)
10123
10124win_findbuf({bufnr}) *win_findbuf()*
10125 Returns a |List| with |window-ID|s for windows that contain
10126 buffer {bufnr}. When there is none the list is empty.
10127
10128 Can also be used as a |method|: >
10129 GetBufnr()->win_findbuf()
10130
10131win_getid([{win} [, {tab}]]) *win_getid()*
10132 Get the |window-ID| for the specified window.
10133 When {win} is missing use the current window.
10134 With {win} this is the window number. The top window has
10135 number 1.
10136 Without {tab} use the current tab, otherwise the tab with
10137 number {tab}. The first tab has number one.
10138 Return zero if the window cannot be found.
10139
10140 Can also be used as a |method|: >
10141 GetWinnr()->win_getid()
10142
10143
10144win_gettype([{nr}]) *win_gettype()*
10145 Return the type of the window:
10146 "autocmd" autocommand window. Temporary window
10147 used to execute autocommands.
10148 "command" command-line window |cmdwin|
10149 (empty) normal window
10150 "loclist" |location-list-window|
10151 "popup" popup window |popup|
10152 "preview" preview window |preview-window|
10153 "quickfix" |quickfix-window|
10154 "unknown" window {nr} not found
10155
10156 When {nr} is omitted return the type of the current window.
10157 When {nr} is given return the type of this window by number or
10158 |window-ID|.
10159
10160 Also see the 'buftype' option. When running a terminal in a
10161 popup window then 'buftype' is "terminal" and win_gettype()
10162 returns "popup".
10163
10164 Can also be used as a |method|: >
10165 GetWinid()->win_gettype()
10166<
10167win_gotoid({expr}) *win_gotoid()*
10168 Go to window with ID {expr}. This may also change the current
10169 tabpage.
10170 Return TRUE if successful, FALSE if the window cannot be found.
10171
10172 Can also be used as a |method|: >
10173 GetWinid()->win_gotoid()
10174
10175win_id2tabwin({expr}) *win_id2tabwin()*
10176 Return a list with the tab number and window number of window
10177 with ID {expr}: [tabnr, winnr].
10178 Return [0, 0] if the window cannot be found.
10179
10180 Can also be used as a |method|: >
10181 GetWinid()->win_id2tabwin()
10182
10183win_id2win({expr}) *win_id2win()*
10184 Return the window number of window with ID {expr}.
10185 Return 0 if the window cannot be found in the current tabpage.
10186
10187 Can also be used as a |method|: >
10188 GetWinid()->win_id2win()
10189
Daniel Steinbergee630312022-01-10 13:36:34 +000010190win_move_separator({nr}, {offset}) *win_move_separator()*
10191 Move window {nr}'s vertical separator (i.e., the right border)
10192 by {offset} columns, as if being dragged by the mouse. {nr}
10193 can be a window number or |window-ID|. A positive {offset}
10194 moves right and a negative {offset} moves left. Moving a
10195 window's vertical separator will change the width of the
10196 window and the width of other windows adjacent to the vertical
10197 separator. The magnitude of movement may be smaller than
10198 specified (e.g., as a consequence of maintaining
10199 'winminwidth'). Returns TRUE if the window can be found and
10200 FALSE otherwise.
Bram Moolenaard592deb2022-06-17 15:42:40 +010010201 This will fail for the rightmost window and a full-width
10202 window, since it has no separator on the right.
Daniel Steinbergee630312022-01-10 13:36:34 +000010203
10204 Can also be used as a |method|: >
10205 GetWinnr()->win_move_separator(offset)
10206
10207win_move_statusline({nr}, {offset}) *win_move_statusline()*
10208 Move window {nr}'s status line (i.e., the bottom border) by
10209 {offset} rows, as if being dragged by the mouse. {nr} can be a
10210 window number or |window-ID|. A positive {offset} moves down
10211 and a negative {offset} moves up. Moving a window's status
10212 line will change the height of the window and the height of
10213 other windows adjacent to the status line. The magnitude of
10214 movement may be smaller than specified (e.g., as a consequence
10215 of maintaining 'winminheight'). Returns TRUE if the window can
10216 be found and FALSE otherwise.
10217
10218 Can also be used as a |method|: >
10219 GetWinnr()->win_move_statusline(offset)
10220
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010221win_screenpos({nr}) *win_screenpos()*
10222 Return the screen position of window {nr} as a list with two
10223 numbers: [row, col]. The first window always has position
10224 [1, 1], unless there is a tabline, then it is [2, 1].
10225 {nr} can be the window number or the |window-ID|. Use zero
10226 for the current window.
10227 Returns [0, 0] if the window cannot be found in the current
10228 tabpage.
10229
10230 Can also be used as a |method|: >
10231 GetWinid()->win_screenpos()
10232<
10233win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10234 Move the window {nr} to a new split of the window {target}.
10235 This is similar to moving to {target}, creating a new window
10236 using |:split| but having the same contents as window {nr}, and
10237 then closing {nr}.
10238
10239 Both {nr} and {target} can be window numbers or |window-ID|s.
10240 Both must be in the current tab page.
10241
10242 Returns zero for success, non-zero for failure.
10243
10244 {options} is a |Dictionary| with the following optional entries:
10245 "vertical" When TRUE, the split is created vertically,
10246 like with |:vsplit|.
10247 "rightbelow" When TRUE, the split is made below or to the
10248 right (if vertical). When FALSE, it is done
10249 above or to the left (if vertical). When not
10250 present, the values of 'splitbelow' and
10251 'splitright' are used.
10252
10253 Can also be used as a |method|: >
10254 GetWinid()->win_splitmove(target)
10255<
10256
10257 *winbufnr()*
10258winbufnr({nr}) The result is a Number, which is the number of the buffer
10259 associated with window {nr}. {nr} can be the window number or
10260 the |window-ID|.
10261 When {nr} is zero, the number of the buffer in the current
10262 window is returned.
10263 When window {nr} doesn't exist, -1 is returned.
10264 Example: >
10265 :echo "The file in the current window is " . bufname(winbufnr(0))
10266<
10267 Can also be used as a |method|: >
10268 FindWindow()->winbufnr()->bufname()
10269<
10270 *wincol()*
10271wincol() The result is a Number, which is the virtual column of the
10272 cursor in the window. This is counting screen cells from the
10273 left side of the window. The leftmost column is one.
10274
10275 *windowsversion()*
10276windowsversion()
10277 The result is a String. For MS-Windows it indicates the OS
10278 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
10279 Windows XP is "5.1". For non-MS-Windows systems the result is
10280 an empty string.
10281
10282winheight({nr}) *winheight()*
10283 The result is a Number, which is the height of window {nr}.
10284 {nr} can be the window number or the |window-ID|.
10285 When {nr} is zero, the height of the current window is
10286 returned. When window {nr} doesn't exist, -1 is returned.
10287 An existing window always has a height of zero or more.
10288 This excludes any window toolbar line.
10289 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010290 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010291
10292< Can also be used as a |method|: >
10293 GetWinid()->winheight()
10294<
10295winlayout([{tabnr}]) *winlayout()*
10296 The result is a nested List containing the layout of windows
10297 in a tabpage.
10298
10299 Without {tabnr} use the current tabpage, otherwise the tabpage
10300 with number {tabnr}. If the tabpage {tabnr} is not found,
10301 returns an empty list.
10302
10303 For a leaf window, it returns:
10304 ['leaf', {winid}]
10305 For horizontally split windows, which form a column, it
10306 returns:
10307 ['col', [{nested list of windows}]]
10308 For vertically split windows, which form a row, it returns:
10309 ['row', [{nested list of windows}]]
10310
10311 Example: >
10312 " Only one window in the tab page
10313 :echo winlayout()
10314 ['leaf', 1000]
10315 " Two horizontally split windows
10316 :echo winlayout()
10317 ['col', [['leaf', 1000], ['leaf', 1001]]]
10318 " The second tab page, with three horizontally split
10319 " windows, with two vertically split windows in the
10320 " middle window
10321 :echo winlayout(2)
10322 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
10323 ['leaf', 1001]]], ['leaf', 1000]]]
10324<
10325 Can also be used as a |method|: >
10326 GetTabnr()->winlayout()
10327<
10328 *winline()*
10329winline() The result is a Number, which is the screen line of the cursor
10330 in the window. This is counting screen lines from the top of
10331 the window. The first line is one.
10332 If the cursor was moved the view on the file will be updated
10333 first, this may cause a scroll.
10334
10335 *winnr()*
10336winnr([{arg}]) The result is a Number, which is the number of the current
10337 window. The top window has number 1.
10338 Returns zero for a popup window.
10339
10340 The optional argument {arg} supports the following values:
10341 $ the number of the last window (the window
10342 count).
10343 # the number of the last accessed window (where
10344 |CTRL-W_p| goes to). If there is no previous
10345 window or it is in another tab page 0 is
10346 returned.
10347 {N}j the number of the Nth window below the
10348 current window (where |CTRL-W_j| goes to).
10349 {N}k the number of the Nth window above the current
10350 window (where |CTRL-W_k| goes to).
10351 {N}h the number of the Nth window left of the
10352 current window (where |CTRL-W_h| goes to).
10353 {N}l the number of the Nth window right of the
10354 current window (where |CTRL-W_l| goes to).
10355 The number can be used with |CTRL-W_w| and ":wincmd w"
10356 |:wincmd|.
Bram Moolenaar016188f2022-06-06 20:52:59 +010010357 When {arg} is invalid an error is given and zero is returned.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010358 Also see |tabpagewinnr()| and |win_getid()|.
10359 Examples: >
10360 let window_count = winnr('$')
10361 let prev_window = winnr('#')
10362 let wnum = winnr('3k')
10363
10364< Can also be used as a |method|: >
10365 GetWinval()->winnr()
10366<
10367 *winrestcmd()*
10368winrestcmd() Returns a sequence of |:resize| commands that should restore
10369 the current window sizes. Only works properly when no windows
10370 are opened or closed and the current window and tab page is
10371 unchanged.
10372 Example: >
10373 :let cmd = winrestcmd()
10374 :call MessWithWindowSizes()
10375 :exe cmd
10376<
10377 *winrestview()*
10378winrestview({dict})
10379 Uses the |Dictionary| returned by |winsaveview()| to restore
10380 the view of the current window.
10381 Note: The {dict} does not have to contain all values, that are
10382 returned by |winsaveview()|. If values are missing, those
10383 settings won't be restored. So you can use: >
10384 :call winrestview({'curswant': 4})
10385<
10386 This will only set the curswant value (the column the cursor
10387 wants to move on vertical movements) of the cursor to column 5
10388 (yes, that is 5), while all other settings will remain the
10389 same. This is useful, if you set the cursor position manually.
10390
10391 If you have changed the values the result is unpredictable.
10392 If the window size changed the result won't be the same.
10393
10394 Can also be used as a |method|: >
10395 GetView()->winrestview()
10396<
10397 *winsaveview()*
10398winsaveview() Returns a |Dictionary| that contains information to restore
10399 the view of the current window. Use |winrestview()| to
10400 restore the view.
10401 This is useful if you have a mapping that jumps around in the
10402 buffer and you want to go back to the original view.
10403 This does not save fold information. Use the 'foldenable'
10404 option to temporarily switch off folding, so that folds are
10405 not opened when moving around. This may have side effects.
10406 The return value includes:
10407 lnum cursor line number
10408 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +000010409 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010410 returns)
10411 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +000010412 curswant column for vertical movement (Note:
10413 the first column is zero, as opposed
10414 to what |getcurpos()| returns). After
10415 |$| command it will be a very large
10416 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010417 topline first line in the window
10418 topfill filler lines, only in diff mode
10419 leftcol first column displayed; only used when
10420 'wrap' is off
10421 skipcol columns skipped
10422 Note that no option values are saved.
10423
10424
10425winwidth({nr}) *winwidth()*
10426 The result is a Number, which is the width of window {nr}.
10427 {nr} can be the window number or the |window-ID|.
10428 When {nr} is zero, the width of the current window is
10429 returned. When window {nr} doesn't exist, -1 is returned.
10430 An existing window always has a width of zero or more.
10431 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +000010432 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010433 :if winwidth(0) <= 50
10434 : 50 wincmd |
10435 :endif
10436< For getting the terminal or screen size, see the 'columns'
10437 option.
10438
10439 Can also be used as a |method|: >
10440 GetWinid()->winwidth()
10441
10442
10443wordcount() *wordcount()*
10444 The result is a dictionary of byte/chars/word statistics for
10445 the current buffer. This is the same info as provided by
10446 |g_CTRL-G|
10447 The return value includes:
10448 bytes Number of bytes in the buffer
10449 chars Number of chars in the buffer
10450 words Number of words in the buffer
10451 cursor_bytes Number of bytes before cursor position
10452 (not in Visual mode)
10453 cursor_chars Number of chars before cursor position
10454 (not in Visual mode)
10455 cursor_words Number of words before cursor position
10456 (not in Visual mode)
10457 visual_bytes Number of bytes visually selected
10458 (only in Visual mode)
10459 visual_chars Number of chars visually selected
10460 (only in Visual mode)
10461 visual_words Number of words visually selected
10462 (only in Visual mode)
10463
10464
10465 *writefile()*
10466writefile({object}, {fname} [, {flags}])
10467 When {object} is a |List| write it to file {fname}. Each list
10468 item is separated with a NL. Each list item must be a String
10469 or Number.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010470 All NL characters are replaced with a NUL character.
10471 Inserting CR characters needs to be done before passing {list}
10472 to writefile().
Bram Moolenaar806a2732022-09-04 15:40:36 +010010473
10474 When {object} is a |Blob| write the bytes to file {fname}
10475 unmodified, also when binary mode is not specified.
10476
10477 {flags} must be a String. These characters are recognized:
10478
10479 'b' Binary mode is used: There will not be a NL after the
10480 last list item. An empty item at the end does cause the
10481 last line in the file to end in a NL.
10482
10483 'a' Append mode is used, lines are appended to the file: >
10484 :call writefile(["foo"], "event.log", "a")
10485 :call writefile(["bar"], "event.log", "a")
10486<
10487 'D' Delete the file when the current function ends. This
10488 works like: >
10489 :defer delete({fname})
10490< Fails when not in a function. Also see |:defer|.
10491
10492 's' fsync() is called after writing the file. This flushes
10493 the file to disk, if possible. This takes more time but
10494 avoids losing the file if the system crashes.
10495
10496 'S' fsync() is not called, even when 'fsync' is set.
10497
10498 When {flags} does not contain "S" or "s" then fsync() is
10499 called if the 'fsync' option is set.
10500
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010501 An existing file is overwritten, if possible.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010502
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010503 When the write fails -1 is returned, otherwise 0. There is an
10504 error message if the file can't be created or when writing
10505 fails.
Bram Moolenaar806a2732022-09-04 15:40:36 +010010506
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010507 Also see |readfile()|.
10508 To copy a file byte for byte: >
10509 :let fl = readfile("foo", "b")
10510 :call writefile(fl, "foocopy", "b")
10511
10512< Can also be used as a |method|: >
10513 GetText()->writefile("thefile")
10514
10515
10516xor({expr}, {expr}) *xor()*
10517 Bitwise XOR on the two arguments. The arguments are converted
10518 to a number. A List, Dict or Float argument causes an error.
Bram Moolenaar5a6ec102022-05-27 21:58:00 +010010519 Also see `and()` and `or()`.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010520 Example: >
10521 :let bits = xor(bits, 0x80)
10522<
10523 Can also be used as a |method|: >
10524 :let bits = bits->xor(0x80)
10525<
10526
10527==============================================================================
105283. Feature list *feature-list*
10529
10530There are three types of features:
105311. Features that are only supported when they have been enabled when Vim
10532 was compiled |+feature-list|. Example: >
10533 :if has("cindent")
10534< *gui_running*
105352. Features that are only supported when certain conditions have been met.
10536 Example: >
10537 :if has("gui_running")
10538< *has-patch*
105393. Beyond a certain version or at a certain version and including a specific
10540 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10541 later, or it is version 7.4 and patch 248 was included. Example: >
10542 :if has("patch-7.4.248")
10543< Note that it's possible for patch 248 to be omitted even though 249 is
10544 included. Only happens when cherry-picking patches.
10545 Note that this form only works for patch 7.4.237 and later, before that
10546 you need to check for the patch and the v:version. Example (checking
10547 version 6.2.148 or later): >
10548 :if v:version > 602 || (v:version == 602 && has("patch148"))
10549
10550Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10551use: `if exists('+shellslash')`
10552
10553
10554acl Compiled with |ACL| support.
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010555all_builtin_terms Compiled with all builtin terminals enabled. (always
10556 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010557amiga Amiga version of Vim.
10558arabic Compiled with Arabic support |Arabic|.
10559arp Compiled with ARP support (Amiga).
10560autocmd Compiled with autocommand support. (always true)
10561autochdir Compiled with support for 'autochdir'
10562autoservername Automatically enable |clientserver|
10563balloon_eval Compiled with |balloon-eval| support.
10564balloon_multiline GUI supports multiline balloons.
10565beos BeOS version of Vim.
10566browse Compiled with |:browse| support, and browse() will
10567 work.
10568browsefilter Compiled with support for |browsefilter|.
10569bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar2ee347f2022-08-26 17:53:44 +010010570builtin_terms Compiled with some builtin terminals. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010571byte_offset Compiled with support for 'o' in 'statusline'
10572channel Compiled with support for |channel| and |job|
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010573cindent Compiled with 'cindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010574clientserver Compiled with remote invocation support |clientserver|.
10575clipboard Compiled with 'clipboard' support.
10576clipboard_working Compiled with 'clipboard' support and it can be used.
10577cmdline_compl Compiled with |cmdline-completion| support.
10578cmdline_hist Compiled with |cmdline-history| support.
10579cmdline_info Compiled with 'showcmd' and 'ruler' support.
10580comments Compiled with |'comments'| support.
10581compatible Compiled to be very Vi compatible.
10582conpty Platform where |ConPTY| can be used.
10583cryptv Compiled with encryption support |encryption|.
10584cscope Compiled with |cscope| support.
10585cursorbind Compiled with |'cursorbind'| (always true)
10586debug Compiled with "DEBUG" defined.
10587dialog_con Compiled with console dialog support.
10588dialog_gui Compiled with GUI dialog support.
10589diff Compiled with |vimdiff| and 'diff' support.
10590digraphs Compiled with support for digraphs.
10591directx Compiled with support for DirectX and 'renderoptions'.
10592dnd Compiled with support for the "~ register |quote_~|.
10593drop_file Compiled with |drop_file| support.
10594ebcdic Compiled on a machine with ebcdic character set.
10595emacs_tags Compiled with support for Emacs tags.
10596eval Compiled with expression evaluation support. Always
10597 true, of course!
10598ex_extra |+ex_extra| (always true)
10599extra_search Compiled with support for |'incsearch'| and
10600 |'hlsearch'|
10601farsi Support for Farsi was removed |farsi|.
Bram Moolenaarf80f40a2022-08-25 16:02:23 +010010602file_in_path Compiled with support for |gf| and |<cfile>| (always
10603 true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010604filterpipe When 'shelltemp' is off pipes are used for shell
10605 read/write/filter commands
10606find_in_path Compiled with support for include file searches
10607 |+find_in_path|.
10608float Compiled with support for |Float|.
10609fname_case Case in file names matters (for Amiga and MS-Windows
10610 this is not present).
10611folding Compiled with |folding| support.
10612footer Compiled with GUI footer support. |gui-footer|
10613fork Compiled to use fork()/exec() instead of system().
10614gettext Compiled with message translation |multi-lang|
10615gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010010616gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010617gui_gnome Compiled with Gnome support (gui_gtk is also defined).
10618gui_gtk Compiled with GTK+ GUI (any version).
10619gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
10620gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
10621gui_haiku Compiled with Haiku GUI.
10622gui_mac Compiled with Macintosh GUI.
10623gui_motif Compiled with Motif GUI.
10624gui_photon Compiled with Photon GUI.
10625gui_running Vim is running in the GUI, or it will start soon.
10626gui_win32 Compiled with MS-Windows Win32 GUI.
10627gui_win32s idem, and Win32s system being used (Windows 3.1)
10628haiku Haiku version of Vim.
10629hangul_input Compiled with Hangul input support. |hangul|
10630hpux HP-UX version of Vim.
10631iconv Can use iconv() for conversion.
10632insert_expand Compiled with support for CTRL-X expansion commands in
10633 Insert mode. (always true)
10634job Compiled with support for |channel| and |job|
10635ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010636jumplist Compiled with |jumplist| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010637keymap Compiled with 'keymap' support.
10638lambda Compiled with |lambda| support.
10639langmap Compiled with 'langmap' support.
10640libcall Compiled with |libcall()| support.
10641linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10642 'breakindent' support.
10643linux Linux version of Vim.
10644lispindent Compiled with support for lisp indenting.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010645 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010646listcmds Compiled with commands for the buffer list |:files|
10647 and the argument list |arglist|.
10648localmap Compiled with local mappings and abbr. |:map-local|
10649lua Compiled with Lua interface |Lua|.
10650mac Any Macintosh version of Vim cf. osx
10651macunix Synonym for osxdarwin
10652menu Compiled with support for |:menu|.
10653mksession Compiled with support for |:mksession|.
10654modify_fname Compiled with file name modifiers. |filename-modifiers|
10655 (always true)
10656mouse Compiled with support for mouse.
10657mouse_dec Compiled with support for Dec terminal mouse.
10658mouse_gpm Compiled with support for gpm (Linux console mouse)
10659mouse_gpm_enabled GPM mouse is working
10660mouse_netterm Compiled with support for netterm mouse.
10661mouse_pterm Compiled with support for qnx pterm mouse.
10662mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
10663mouse_sgr Compiled with support for sgr mouse.
10664mouse_urxvt Compiled with support for urxvt mouse.
10665mouse_xterm Compiled with support for xterm mouse.
10666mouseshape Compiled with support for 'mouseshape'.
10667multi_byte Compiled with support for 'encoding' (always true)
10668multi_byte_encoding 'encoding' is set to a multibyte encoding.
10669multi_byte_ime Compiled with support for IME input method.
10670multi_lang Compiled with support for multiple languages.
10671mzscheme Compiled with MzScheme interface |mzscheme|.
10672nanotime Compiled with sub-second time stamp checks.
10673netbeans_enabled Compiled with support for |netbeans| and connected.
10674netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010675num64 Compiled with 64-bit |Number| support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010676ole Compiled with OLE automation support for Win32.
10677osx Compiled for macOS cf. mac
10678osxdarwin Compiled for macOS, with |mac-darwin-feature|
10679packages Compiled with |packages| support.
10680path_extra Compiled with up/downwards search in 'path' and 'tags'
10681perl Compiled with Perl interface.
10682persistent_undo Compiled with support for persistent undo history.
10683postscript Compiled with PostScript file printing.
10684printer Compiled with |:hardcopy| support.
10685profile Compiled with |:profile| support.
10686python Python 2.x interface available. |has-python|
10687python_compiled Compiled with Python 2.x interface. |has-python|
10688python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10689python3 Python 3.x interface available. |has-python|
10690python3_compiled Compiled with Python 3.x interface. |has-python|
10691python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10692pythonx Python 2.x and/or 3.x interface available. |python_x|
10693qnx QNX version of Vim.
10694quickfix Compiled with |quickfix| support.
10695reltime Compiled with |reltime()| support.
10696rightleft Compiled with 'rightleft' support.
10697ruby Compiled with Ruby interface |ruby|.
10698scrollbind Compiled with 'scrollbind' support. (always true)
10699showcmd Compiled with 'showcmd' support.
10700signs Compiled with |:sign| support.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010701smartindent Compiled with 'smartindent' support. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010702sodium Compiled with libsodium for better crypt support
10703sound Compiled with sound support, e.g. `sound_playevent()`
10704spell Compiled with spell checking support |spell|.
10705startuptime Compiled with |--startuptime| support.
10706statusline Compiled with support for 'statusline', 'rulerformat'
10707 and special formats of 'titlestring' and 'iconstring'.
10708sun SunOS version of Vim.
10709sun_workshop Support for Sun |workshop| has been removed.
10710syntax Compiled with syntax highlighting support |syntax|.
10711syntax_items There are active syntax highlighting items for the
10712 current buffer.
10713system Compiled to use system() instead of fork()/exec().
10714tag_binary Compiled with binary searching in tags files
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010715 |tag-binary-search|. (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010716tag_old_static Support for old static tags was removed, see
10717 |tag-old-static|.
10718tcl Compiled with Tcl interface.
10719termguicolors Compiled with true color in terminal support.
10720terminal Compiled with |terminal| support.
10721terminfo Compiled with terminfo instead of termcap.
10722termresponse Compiled with support for |t_RV| and |v:termresponse|.
10723textobjects Compiled with support for |text-objects|.
10724textprop Compiled with support for |text-properties|.
10725tgetent Compiled with tgetent support, able to use a termcap
10726 or terminfo file.
10727timers Compiled with |timer_start()| support.
10728title Compiled with window title support |'title'|.
Bram Moolenaare1dc76f2022-06-25 18:01:32 +010010729 (always true)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010730toolbar Compiled with support for |gui-toolbar|.
10731ttyin input is a terminal (tty)
10732ttyout output is a terminal (tty)
10733unix Unix version of Vim. *+unix*
10734unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10735user_commands User-defined commands. (always true)
10736vartabs Compiled with variable tabstop support |'vartabstop'|.
10737vcon Win32: Virtual console support is working, can use
10738 'termguicolors'. Also see |+vtp|.
10739vertsplit Compiled with vertically split windows |:vsplit|.
10740 (always true)
10741vim_starting True while initial source'ing takes place. |startup|
10742 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000010743vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010744viminfo Compiled with viminfo support.
10745vimscript-1 Compiled Vim script version 1 support
10746vimscript-2 Compiled Vim script version 2 support
10747vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar8a3b8052022-06-26 12:21:15 +010010748vimscript-4 Compiled Vim script version 4 support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010749virtualedit Compiled with 'virtualedit' option. (always true)
10750visual Compiled with Visual mode. (always true)
10751visualextra Compiled with extra Visual mode commands. (always
10752 true) |blockwise-operators|.
10753vms VMS version of Vim.
10754vreplace Compiled with |gR| and |gr| commands. (always true)
10755vtp Compiled for vcon support |+vtp| (check vcon to find
10756 out if it works in the current console).
10757wildignore Compiled with 'wildignore' option.
10758wildmenu Compiled with 'wildmenu' option.
10759win16 old version for MS-Windows 3.1 (always false)
10760win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10761 64 bits)
10762win32unix Win32 version of Vim, using Unix files (Cygwin)
10763win64 Win64 version of Vim (MS-Windows 64 bit).
10764win95 Win32 version for MS-Windows 95/98/ME (always false)
10765winaltkeys Compiled with 'winaltkeys' option.
10766windows Compiled with support for more than one window.
10767 (always true)
10768writebackup Compiled with 'writebackup' default on.
10769xfontset Compiled with X fontset support |xfontset|.
10770xim Compiled with X input method support |xim|.
10771xpm Compiled with pixmap support.
10772xpm_w32 Compiled with pixmap support for Win32. (Only for
10773 backward compatibility. Use "xpm" instead.)
10774xsmp Compiled with X session management support.
10775xsmp_interact Compiled with interactive X session management support.
10776xterm_clipboard Compiled with support for xterm clipboard.
10777xterm_save Compiled with support for saving and restoring the
10778 xterm screen.
10779x11 Compiled with X11 support.
10780
10781
10782==============================================================================
107834. Matching a pattern in a String *string-match*
10784
10785This is common between several functions. A regexp pattern as explained at
10786|pattern| is normally used to find a match in the buffer lines. When a
10787pattern is used to find a match in a String, almost everything works in the
10788same way. The difference is that a String is handled like it is one line.
10789When it contains a "\n" character, this is not seen as a line break for the
10790pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10791>
10792 :let a = "aaaa\nxxxx"
10793 :echo matchstr(a, "..\n..")
10794 aa
10795 xx
10796 :echo matchstr(a, "a.x")
10797 a
10798 x
10799
10800Don't forget that "^" will only match at the first character of the String and
10801"$" at the last character of the string. They don't match after or before a
10802"\n".
10803
10804 vim:tw=78:ts=8:noet:ft=help:norl: