blob: 8695edd2dd7e9ba2f1810cae82df077422dc94c7 [file] [log] [blame]
Bram Moolenaar75ab5902022-04-18 15:36:40 +01001*builtin.txt* For Vim version 8.2. Last change: 2022 Apr 16
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}
63balloon_gettext() String current text in the balloon
64balloon_show({expr}) none show {expr} inside the balloon
65balloon_split({msg}) List split {msg} as used for a balloon
66blob2list({blob}) List convert {blob} into a list of numbers
67browse({save}, {title}, {initdir}, {default})
68 String put up a file requester
69browsedir({title}, {initdir}) String put up a directory requester
70bufadd({name}) Number add a buffer to the buffer list
71bufexists({buf}) Number |TRUE| if buffer {buf} exists
72buflisted({buf}) Number |TRUE| if buffer {buf} is listed
73bufload({buf}) Number load buffer {buf} if not loaded yet
74bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
75bufname([{buf}]) String Name of the buffer {buf}
76bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
77bufwinid({buf}) Number window ID of buffer {buf}
78bufwinnr({buf}) Number window number of buffer {buf}
79byte2line({byte}) Number line number at byte count {byte}
80byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
81byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
82call({func}, {arglist} [, {dict}])
83 any call {func} with arguments {arglist}
84ceil({expr}) Float round {expr} up
85ch_canread({handle}) Number check if there is something to read
86ch_close({handle}) none close {handle}
87ch_close_in({handle}) none close in part of {handle}
88ch_evalexpr({handle}, {expr} [, {options}])
89 any evaluate {expr} on JSON {handle}
90ch_evalraw({handle}, {string} [, {options}])
91 any evaluate {string} on raw {handle}
92ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
93ch_getjob({channel}) Job get the Job of {channel}
94ch_info({handle}) String info about channel {handle}
95ch_log({msg} [, {handle}]) none write {msg} in the channel log file
96ch_logfile({fname} [, {mode}]) none start logging channel activity
97ch_open({address} [, {options}])
98 Channel open a channel to {address}
99ch_read({handle} [, {options}]) String read from {handle}
100ch_readblob({handle} [, {options}])
101 Blob read Blob from {handle}
102ch_readraw({handle} [, {options}])
103 String read raw from {handle}
104ch_sendexpr({handle}, {expr} [, {options}])
105 any send {expr} over JSON {handle}
106ch_sendraw({handle}, {expr} [, {options}])
107 any send {expr} over raw {handle}
108ch_setoptions({handle}, {options})
109 none set options for {handle}
110ch_status({handle} [, {options}])
111 String status of channel {handle}
112changenr() Number current change number
113char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
114charclass({string}) Number character class of {string}
115charcol({expr}) Number column number of cursor or mark
116charidx({string}, {idx} [, {countcc}])
117 Number char index of byte {idx} in {string}
118chdir({dir}) String change current working directory
119cindent({lnum}) Number C indent for line {lnum}
120clearmatches([{win}]) none clear all matches
121col({expr}) Number column byte index of cursor or mark
122complete({startcol}, {matches}) none set Insert mode completion
123complete_add({expr}) Number add completion match
124complete_check() Number check for key typed during completion
125complete_info([{what}]) Dict get current completion information
126confirm({msg} [, {choices} [, {default} [, {type}]]])
127 Number number of choice picked by user
128copy({expr}) any make a shallow copy of {expr}
129cos({expr}) Float cosine of {expr}
130cosh({expr}) Float hyperbolic cosine of {expr}
131count({comp}, {expr} [, {ic} [, {start}]])
132 Number count how many {expr} are in {comp}
133cscope_connection([{num}, {dbpath} [, {prepend}]])
134 Number checks existence of cscope connection
135cursor({lnum}, {col} [, {off}])
136 Number move cursor to {lnum}, {col}, {off}
137cursor({list}) Number move cursor to position in {list}
138debugbreak({pid}) Number interrupt process being debugged
139deepcopy({expr} [, {noref}]) any make a full copy of {expr}
140delete({fname} [, {flags}]) Number delete the file or directory {fname}
141deletebufline({buf}, {first} [, {last}])
142 Number delete lines from buffer {buf}
143did_filetype() Number |TRUE| if FileType autocmd event used
144diff_filler({lnum}) Number diff filler lines about {lnum}
145diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
146digraph_get({chars}) String get the |digraph| of {chars}
147digraph_getlist([{listall}]) List get all |digraph|s
148digraph_set({chars}, {digraph}) Boolean register |digraph|
149digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
150echoraw({expr}) none output {expr} as-is
151empty({expr}) Number |TRUE| if {expr} is empty
152environ() Dict return environment variables
153escape({string}, {chars}) String escape {chars} in {string} with '\'
154eval({string}) any evaluate {string} into its value
155eventhandler() Number |TRUE| if inside an event handler
156executable({expr}) Number 1 if executable {expr} exists
157execute({command}) String execute {command} and get the output
158exepath({expr}) String full path of the command {expr}
159exists({expr}) Number |TRUE| if {expr} exists
160exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
161exp({expr}) Float exponential of {expr}
162expand({expr} [, {nosuf} [, {list}]])
163 any expand special keywords in {expr}
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +0100164expandcmd({string} [, {options}])
165 String expand {string} like with `:edit`
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000166extend({expr1}, {expr2} [, {expr3}])
167 List/Dict insert items of {expr2} into {expr1}
168extendnew({expr1}, {expr2} [, {expr3}])
169 List/Dict like |extend()| but creates a new
170 List or Dictionary
171feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
172filereadable({file}) Number |TRUE| if {file} is a readable file
173filewritable({file}) Number |TRUE| if {file} is a writable file
174filter({expr1}, {expr2}) List/Dict/Blob/String
175 remove items from {expr1} where
176 {expr2} is 0
177finddir({name} [, {path} [, {count}]])
178 String find directory {name} in {path}
179findfile({name} [, {path} [, {count}]])
180 String find file {name} in {path}
181flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
182flattennew({list} [, {maxdepth}])
183 List flatten a copy of {list}
184float2nr({expr}) Number convert Float {expr} to a Number
185floor({expr}) Float round {expr} down
186fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
187fnameescape({fname}) String escape special characters in {fname}
188fnamemodify({fname}, {mods}) String modify file name
189foldclosed({lnum}) Number first line of fold at {lnum} if closed
190foldclosedend({lnum}) Number last line of fold at {lnum} if closed
191foldlevel({lnum}) Number fold level at {lnum}
192foldtext() String line displayed for closed fold
193foldtextresult({lnum}) String text for closed fold at {lnum}
194foreground() Number bring the Vim window to the foreground
195fullcommand({name}) String get full command from {name}
196funcref({name} [, {arglist}] [, {dict}])
197 Funcref reference to function {name}
198function({name} [, {arglist}] [, {dict}])
199 Funcref named reference to function {name}
200garbagecollect([{atexit}]) none free memory, breaking cyclic references
201get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
202get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
203get({func}, {what}) any get property of funcref/partial {func}
204getbufinfo([{buf}]) List information about buffers
205getbufline({buf}, {lnum} [, {end}])
206 List lines {lnum} to {end} of buffer {buf}
207getbufvar({buf}, {varname} [, {def}])
208 any variable {varname} in buffer {buf}
209getchangelist([{buf}]) List list of change list items
210getchar([expr]) Number or String
211 get one character from the user
212getcharmod() Number modifiers for the last typed character
213getcharpos({expr}) List position of cursor, mark, etc.
214getcharsearch() Dict last character search
215getcharstr([expr]) String get one character from the user
216getcmdline() String return the current command-line
217getcmdpos() Number return cursor position in command-line
218getcmdtype() String return current command-line type
219getcmdwintype() String return current command-line window type
220getcompletion({pat}, {type} [, {filtered}])
221 List list of cmdline completion matches
222getcurpos([{winnr}]) List position of the cursor
223getcursorcharpos([{winnr}]) List character position of the cursor
224getcwd([{winnr} [, {tabnr}]]) String get the current working directory
225getenv({name}) String return environment variable
226getfontname([{name}]) String name of font being used
227getfperm({fname}) String file permissions of file {fname}
228getfsize({fname}) Number size in bytes of file {fname}
229getftime({fname}) Number last modification time of file
230getftype({fname}) String description of type of file {fname}
231getimstatus() Number |TRUE| if the IME status is active
232getjumplist([{winnr} [, {tabnr}]])
233 List list of jump list items
234getline({lnum}) String line {lnum} of current buffer
235getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
236getloclist({nr}) List list of location list items
237getloclist({nr}, {what}) Dict get specific location list properties
238getmarklist([{buf}]) List list of global/local marks
239getmatches([{win}]) List list of current matches
240getmousepos() Dict last known mouse position
241getpid() Number process ID of Vim
242getpos({expr}) List position of cursor, mark, etc.
243getqflist() List list of quickfix items
244getqflist({what}) Dict get specific quickfix list properties
245getreg([{regname} [, 1 [, {list}]]])
246 String or List contents of a register
247getreginfo([{regname}]) Dict information about a register
248getregtype([{regname}]) String type of a register
249gettabinfo([{expr}]) List list of tab pages
250gettabvar({nr}, {varname} [, {def}])
251 any variable {varname} in tab {nr} or {def}
252gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
253 any {name} in {winnr} in tab page {tabnr}
254gettagstack([{nr}]) Dict get the tag stack of window {nr}
255gettext({text}) String lookup translation of {text}
256getwininfo([{winid}]) List list of info about each window
257getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
258getwinposx() Number X coord in pixels of the Vim window
259getwinposy() Number Y coord in pixels of the Vim window
260getwinvar({nr}, {varname} [, {def}])
261 any variable {varname} in window {nr}
262glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
263 any expand file wildcards in {expr}
264glob2regpat({expr}) String convert a glob pat into a search pat
265globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
266 String do glob({expr}) for all dirs in {path}
267has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
268has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
269haslocaldir([{winnr} [, {tabnr}]])
270 Number |TRUE| if the window executed |:lcd|
271 or |:tcd|
272hasmapto({what} [, {mode} [, {abbr}]])
273 Number |TRUE| if mapping to {what} exists
274histadd({history}, {item}) Number add an item to a history
275histdel({history} [, {item}]) Number remove an item from a history
276histget({history} [, {index}]) String get the item {index} from a history
277histnr({history}) Number highest index of a history
278hlID({name}) Number syntax ID of highlight group {name}
279hlexists({name}) Number |TRUE| if highlight group {name} exists
280hlget([{name} [, {resolve}]]) List get highlight group attributes
281hlset({list}) Number set highlight group attributes
282hostname() String name of the machine Vim is running on
283iconv({expr}, {from}, {to}) String convert encoding of {expr}
284indent({lnum}) Number indent of line {lnum}
285index({object}, {expr} [, {start} [, {ic}]])
286 Number index in {object} where {expr} appears
287input({prompt} [, {text} [, {completion}]])
288 String get input from the user
289inputdialog({prompt} [, {text} [, {completion}]])
290 String like input() but in a GUI dialog
291inputlist({textlist}) Number let the user pick from a choice list
292inputrestore() Number restore typeahead
293inputsave() Number save and clear typeahead
294inputsecret({prompt} [, {text}]) String like input() but hiding the text
295insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
296interrupt() none interrupt script execution
297invert({expr}) Number bitwise invert
298isdirectory({directory}) Number |TRUE| if {directory} is a directory
299isinf({expr}) Number determine if {expr} is infinity value
300 (positive or negative)
301islocked({expr}) Number |TRUE| if {expr} is locked
302isnan({expr}) Number |TRUE| if {expr} is NaN
303items({dict}) List key-value pairs in {dict}
304job_getchannel({job}) Channel get the channel handle for {job}
305job_info([{job}]) Dict get information about {job}
306job_setoptions({job}, {options}) none set options for {job}
307job_start({command} [, {options}])
308 Job start a job
309job_status({job}) String get the status of {job}
310job_stop({job} [, {how}]) Number stop {job}
311join({list} [, {sep}]) String join {list} items into one String
312js_decode({string}) any decode JS style JSON
313js_encode({expr}) String encode JS style JSON
314json_decode({string}) any decode JSON
315json_encode({expr}) String encode JSON
316keys({dict}) List keys in {dict}
317len({expr}) Number the length of {expr}
318libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
319libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
320line({expr} [, {winid}]) Number line nr of cursor, last line or mark
321line2byte({lnum}) Number byte count of line {lnum}
322lispindent({lnum}) Number Lisp indent for line {lnum}
323list2blob({list}) Blob turn {list} of numbers into a Blob
324list2str({list} [, {utf8}]) String turn {list} of numbers into a String
325listener_add({callback} [, {buf}])
326 Number add a callback to listen to changes
327listener_flush([{buf}]) none invoke listener callbacks
328listener_remove({id}) none remove a listener callback
329localtime() Number current time
330log({expr}) Float natural logarithm (base e) of {expr}
331log10({expr}) Float logarithm of Float {expr} to base 10
332luaeval({expr} [, {expr}]) any evaluate |Lua| expression
333map({expr1}, {expr2}) List/Dict/Blob/String
334 change each item in {expr1} to {expr2}
335maparg({name} [, {mode} [, {abbr} [, {dict}]]])
336 String or Dict
337 rhs of mapping {name} in mode {mode}
338mapcheck({name} [, {mode} [, {abbr}]])
339 String check for mappings matching {name}
340mapnew({expr1}, {expr2}) List/Dict/Blob/String
341 like |map()| but creates a new List or
342 Dictionary
343mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
344match({expr}, {pat} [, {start} [, {count}]])
345 Number position where {pat} matches in {expr}
346matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
347 Number highlight {pattern} with {group}
348matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
349 Number highlight positions with {group}
350matcharg({nr}) List arguments of |:match|
351matchdelete({id} [, {win}]) Number delete match identified by {id}
352matchend({expr}, {pat} [, {start} [, {count}]])
353 Number position where {pat} ends in {expr}
354matchfuzzy({list}, {str} [, {dict}])
355 List fuzzy match {str} in {list}
356matchfuzzypos({list}, {str} [, {dict}])
357 List fuzzy match {str} in {list}
358matchlist({expr}, {pat} [, {start} [, {count}]])
359 List match and submatches of {pat} in {expr}
360matchstr({expr}, {pat} [, {start} [, {count}]])
361 String {count}'th match of {pat} in {expr}
362matchstrpos({expr}, {pat} [, {start} [, {count}]])
363 List {count}'th match of {pat} in {expr}
364max({expr}) Number maximum value of items in {expr}
365menu_info({name} [, {mode}]) Dict get menu item information
366min({expr}) Number minimum value of items in {expr}
367mkdir({name} [, {path} [, {prot}]])
368 Number create directory {name}
369mode([expr]) String current editing mode
370mzeval({expr}) any evaluate |MzScheme| expression
371nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
372nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
373or({expr}, {expr}) Number bitwise OR
374pathshorten({expr} [, {len}]) String shorten directory names in a path
375perleval({expr}) any evaluate |Perl| expression
376popup_atcursor({what}, {options}) Number create popup window near the cursor
377popup_beval({what}, {options}) Number create popup window for 'ballooneval'
378popup_clear() none close all popup windows
379popup_close({id} [, {result}]) none close popup window {id}
380popup_create({what}, {options}) Number create a popup window
381popup_dialog({what}, {options}) Number create a popup window used as a dialog
382popup_filter_menu({id}, {key}) Number filter for a menu popup window
383popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
384popup_findinfo() Number get window ID of info popup window
385popup_findpreview() Number get window ID of preview popup window
386popup_getoptions({id}) Dict get options of popup window {id}
387popup_getpos({id}) Dict get position of popup window {id}
388popup_hide({id}) none hide popup menu {id}
389popup_list() List get a list of window IDs of all popups
390popup_locate({row}, {col}) Number get window ID of popup at position
391popup_menu({what}, {options}) Number create a popup window used as a menu
392popup_move({id}, {options}) none set position of popup window {id}
393popup_notification({what}, {options})
394 Number create a notification popup window
395popup_setoptions({id}, {options})
396 none set options for popup window {id}
397popup_settext({id}, {text}) none set the text of popup window {id}
398popup_show({id}) none unhide popup window {id}
399pow({x}, {y}) Float {x} to the power of {y}
400prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
401printf({fmt}, {expr1}...) String format text
402prompt_getprompt({buf}) String get prompt text
403prompt_setcallback({buf}, {expr}) none set prompt callback function
404prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
405prompt_setprompt({buf}, {text}) none set prompt text
406prop_add({lnum}, {col}, {props}) none add one text property
407prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
408 none add multiple text properties
409prop_clear({lnum} [, {lnum-end} [, {props}]])
410 none remove all text properties
411prop_find({props} [, {direction}])
412 Dict search for a text property
413prop_list({lnum} [, {props}]) List text properties in {lnum}
414prop_remove({props} [, {lnum} [, {lnum-end}]])
415 Number remove a text property
416prop_type_add({name}, {props}) none define a new property type
417prop_type_change({name}, {props})
418 none change an existing property type
419prop_type_delete({name} [, {props}])
420 none delete a property type
421prop_type_get({name} [, {props}])
422 Dict get property type values
423prop_type_list([{props}]) List get list of property types
424pum_getpos() Dict position and size of pum if visible
425pumvisible() Number whether popup menu is visible
426py3eval({expr}) any evaluate |python3| expression
427pyeval({expr}) any evaluate |Python| expression
428pyxeval({expr}) any evaluate |python_x| expression
429rand([{expr}]) Number get pseudo-random number
430range({expr} [, {max} [, {stride}]])
431 List items from {expr} to {max}
432readblob({fname}) Blob read a |Blob| from {fname}
433readdir({dir} [, {expr} [, {dict}]])
434 List file names in {dir} selected by {expr}
435readdirex({dir} [, {expr} [, {dict}]])
436 List file info in {dir} selected by {expr}
437readfile({fname} [, {type} [, {max}]])
438 List get list of lines from file {fname}
439reduce({object}, {func} [, {initial}])
440 any reduce {object} using {func}
441reg_executing() String get the executing register name
442reg_recording() String get the recording register name
443reltime([{start} [, {end}]]) List get time value
444reltimefloat({time}) Float turn the time value into a Float
445reltimestr({time}) String turn time value into a String
446remote_expr({server}, {string} [, {idvar} [, {timeout}]])
447 String send expression
448remote_foreground({server}) Number bring Vim server to the foreground
449remote_peek({serverid} [, {retvar}])
450 Number check for reply string
451remote_read({serverid} [, {timeout}])
452 String read reply string
453remote_send({server}, {string} [, {idvar}])
454 String send key sequence
455remote_startserver({name}) none become server {name}
456remove({list}, {idx} [, {end}]) any/List
457 remove items {idx}-{end} from {list}
458remove({blob}, {idx} [, {end}]) Number/Blob
459 remove bytes {idx}-{end} from {blob}
460remove({dict}, {key}) any remove entry {key} from {dict}
461rename({from}, {to}) Number rename (move) file from {from} to {to}
462repeat({expr}, {count}) String repeat {expr} {count} times
463resolve({filename}) String get filename a shortcut points to
464reverse({list}) List reverse {list} in-place
465round({expr}) Float round off {expr}
466rubyeval({expr}) any evaluate |Ruby| expression
467screenattr({row}, {col}) Number attribute at screen position
468screenchar({row}, {col}) Number character at screen position
469screenchars({row}, {col}) List List of characters at screen position
470screencol() Number current cursor column
471screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
472screenrow() Number current cursor row
473screenstring({row}, {col}) String characters at screen position
474search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
475 Number search for {pattern}
476searchcount([{options}]) Dict get or update search stats
477searchdecl({name} [, {global} [, {thisblock}]])
478 Number search for variable declaration
479searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
480 Number search for other end of start/end pair
481searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
482 List search for other end of start/end pair
483searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
484 List search for {pattern}
485server2client({clientid}, {string})
486 Number send reply string
487serverlist() String get a list of available servers
488setbufline({expr}, {lnum}, {text})
489 Number set line {lnum} to {text} in buffer
490 {expr}
491setbufvar({buf}, {varname}, {val})
492 none set {varname} in buffer {buf} to {val}
493setcellwidths({list}) none set character cell width overrides
494setcharpos({expr}, {list}) Number set the {expr} position to {list}
495setcharsearch({dict}) Dict set character search from {dict}
496setcmdpos({pos}) Number set cursor position in command-line
497setcursorcharpos({list}) Number move cursor to position in {list}
498setenv({name}, {val}) none set environment variable
499setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
500setline({lnum}, {line}) Number set line {lnum} to {line}
501setloclist({nr}, {list} [, {action}])
502 Number modify location list using {list}
503setloclist({nr}, {list}, {action}, {what})
504 Number modify specific location list props
505setmatches({list} [, {win}]) Number restore a list of matches
506setpos({expr}, {list}) Number set the {expr} position to {list}
507setqflist({list} [, {action}]) Number modify quickfix list using {list}
508setqflist({list}, {action}, {what})
509 Number modify specific quickfix list props
510setreg({n}, {v} [, {opt}]) Number set register to value and type
511settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
512settabwinvar({tabnr}, {winnr}, {varname}, {val})
513 none set {varname} in window {winnr} in tab
514 page {tabnr} to {val}
515settagstack({nr}, {dict} [, {action}])
516 Number modify tag stack using {dict}
517setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
518sha256({string}) String SHA256 checksum of {string}
519shellescape({string} [, {special}])
520 String escape {string} for use as shell
521 command argument
522shiftwidth([{col}]) Number effective value of 'shiftwidth'
523sign_define({name} [, {dict}]) Number define or update a sign
524sign_define({list}) List define or update a list of signs
525sign_getdefined([{name}]) List get a list of defined signs
526sign_getplaced([{buf} [, {dict}]])
527 List get a list of placed signs
528sign_jump({id}, {group}, {buf})
529 Number jump to a sign
530sign_place({id}, {group}, {name}, {buf} [, {dict}])
531 Number place a sign
532sign_placelist({list}) List place a list of signs
533sign_undefine([{name}]) Number undefine a sign
534sign_undefine({list}) List undefine a list of signs
535sign_unplace({group} [, {dict}])
536 Number unplace a sign
537sign_unplacelist({list}) List unplace a list of signs
538simplify({filename}) String simplify filename as much as possible
539sin({expr}) Float sine of {expr}
540sinh({expr}) Float hyperbolic sine of {expr}
541slice({expr}, {start} [, {end}]) String, List or Blob
542 slice of a String, List or Blob
Bram Moolenaar2007dd42022-02-23 13:17:47 +0000543sort({list} [, {how} [, {dict}]])
544 List sort {list}, compare with {how}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000545sound_clear() none stop playing all sounds
546sound_playevent({name} [, {callback}])
547 Number play an event sound
548sound_playfile({path} [, {callback}])
549 Number play sound file {path}
550sound_stop({id}) none stop playing sound {id}
551soundfold({word}) String sound-fold {word}
552spellbadword() String badly spelled word at cursor
553spellsuggest({word} [, {max} [, {capital}]])
554 List spelling suggestions
555split({expr} [, {pat} [, {keepempty}]])
556 List make |List| from {pat} separated {expr}
557sqrt({expr}) Float square root of {expr}
558srand([{expr}]) List get seed for |rand()|
559state([{what}]) String current state of Vim
560str2float({expr} [, {quoted}]) Float convert String to Float
561str2list({expr} [, {utf8}]) List convert each character of {expr} to
562 ASCII/UTF-8 value
563str2nr({expr} [, {base} [, {quoted}]])
564 Number convert String to Number
565strcharlen({expr}) Number character length of the String {expr}
566strcharpart({str}, {start} [, {len} [, {skipcc}]])
567 String {len} characters of {str} at
568 character {start}
569strchars({expr} [, {skipcc}]) Number character count of the String {expr}
570strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
571strftime({format} [, {time}]) String format time with a specified format
572strgetchar({str}, {index}) Number get char {index} from {str}
573stridx({haystack}, {needle} [, {start}])
574 Number index of {needle} in {haystack}
575string({expr}) String String representation of {expr} value
576strlen({expr}) Number length of the String {expr}
577strpart({str}, {start} [, {len} [, {chars}]])
578 String {len} bytes/chars of {str} at
579 byte {start}
580strptime({format}, {timestring})
581 Number Convert {timestring} to unix timestamp
582strridx({haystack}, {needle} [, {start}])
583 Number last index of {needle} in {haystack}
584strtrans({expr}) String translate string to make it printable
585strwidth({expr}) Number display cell length of the String {expr}
586submatch({nr} [, {list}]) String or List
587 specific match in ":s" or substitute()
588substitute({expr}, {pat}, {sub}, {flags})
589 String all {pat} in {expr} replaced with {sub}
590swapinfo({fname}) Dict information about swap file {fname}
591swapname({buf}) String swap file of buffer {buf}
592synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
593synIDattr({synID}, {what} [, {mode}])
594 String attribute {what} of syntax ID {synID}
595synIDtrans({synID}) Number translated syntax ID of {synID}
596synconcealed({lnum}, {col}) List info about concealing
597synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
598system({expr} [, {input}]) String output of shell command/filter {expr}
599systemlist({expr} [, {input}]) List output of shell command/filter {expr}
600tabpagebuflist([{arg}]) List list of buffer numbers in tab page
601tabpagenr([{arg}]) Number number of current or last tab page
602tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
603tagfiles() List tags files used
604taglist({expr} [, {filename}]) List list of tags matching {expr}
605tan({expr}) Float tangent of {expr}
606tanh({expr}) Float hyperbolic tangent of {expr}
607tempname() String name for a temporary file
608term_dumpdiff({filename}, {filename} [, {options}])
609 Number display difference between two dumps
610term_dumpload({filename} [, {options}])
611 Number displaying a screen dump
612term_dumpwrite({buf}, {filename} [, {options}])
613 none dump terminal window contents
614term_getaltscreen({buf}) Number get the alternate screen flag
615term_getansicolors({buf}) List get ANSI palette in GUI color mode
616term_getattr({attr}, {what}) Number get the value of attribute {what}
617term_getcursor({buf}) List get the cursor position of a terminal
618term_getjob({buf}) Job get the job associated with a terminal
619term_getline({buf}, {row}) String get a line of text from a terminal
620term_getscrolled({buf}) Number get the scroll count of a terminal
621term_getsize({buf}) List get the size of a terminal
622term_getstatus({buf}) String get the status of a terminal
623term_gettitle({buf}) String get the title of a terminal
624term_gettty({buf}, [{input}]) String get the tty name of a terminal
625term_list() List get the list of terminal buffers
626term_scrape({buf}, {row}) List get row of a terminal screen
627term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
628term_setansicolors({buf}, {colors})
629 none set ANSI palette in GUI color mode
630term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
631term_setkill({buf}, {how}) none set signal to stop job in terminal
632term_setrestore({buf}, {command}) none set command to restore terminal
633term_setsize({buf}, {rows}, {cols})
634 none set the size of a terminal
635term_start({cmd} [, {options}]) Number open a terminal window and run a job
636term_wait({buf} [, {time}]) Number wait for screen to be updated
637terminalprops() Dict properties of the terminal
638test_alloc_fail({id}, {countdown}, {repeat})
639 none make memory allocation fail
640test_autochdir() none enable 'autochdir' during startup
641test_feedinput({string}) none add key sequence to input buffer
642test_garbagecollect_now() none free memory right now for testing
643test_garbagecollect_soon() none free memory soon for testing
644test_getvalue({string}) any get value of an internal variable
Yegappan Lakshmanan06011e12022-01-30 12:37:29 +0000645test_gui_event({event}, {args}) bool generate a GUI event for testing
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000646test_ignore_error({expr}) none ignore a specific error
647test_null_blob() Blob null value for testing
648test_null_channel() Channel null value for testing
649test_null_dict() Dict null value for testing
650test_null_function() Funcref null value for testing
651test_null_job() Job null value for testing
652test_null_list() List null value for testing
653test_null_partial() Funcref null value for testing
654test_null_string() String null value for testing
655test_option_not_set({name}) none reset flag indicating option was set
656test_override({expr}, {val}) none test with Vim internal overrides
657test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000658test_setmouse({row}, {col}) none set the mouse position for testing
659test_settime({expr}) none set current time for testing
660test_srand_seed([seed]) none set seed for testing srand()
661test_unknown() any unknown value for testing
662test_void() any void value for testing
663timer_info([{id}]) List information about timers
664timer_pause({id}, {pause}) none pause or unpause a timer
665timer_start({time}, {callback} [, {options}])
666 Number create a timer
667timer_stop({timer}) none stop a timer
668timer_stopall() none stop all timers
669tolower({expr}) String the String {expr} switched to lowercase
670toupper({expr}) String the String {expr} switched to uppercase
671tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
672 to chars in {tostr}
673trim({text} [, {mask} [, {dir}]])
674 String trim characters in {mask} from {text}
675trunc({expr}) Float truncate Float {expr}
676type({expr}) Number type of value {expr}
677typename({expr}) String representation of the type of {expr}
678undofile({name}) String undo file name for {name}
679undotree() List undo file tree
680uniq({list} [, {func} [, {dict}]])
681 List remove adjacent duplicates from a list
682values({dict}) List values in {dict}
683virtcol({expr}) Number screen column of cursor or mark
684visualmode([expr]) String last visual mode used
685wildmenumode() Number whether 'wildmenu' mode is active
686win_execute({id}, {command} [, {silent}])
687 String execute {command} in window {id}
688win_findbuf({bufnr}) List find windows containing {bufnr}
689win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
690win_gettype([{nr}]) String type of window {nr}
691win_gotoid({expr}) Number go to window with ID {expr}
692win_id2tabwin({expr}) List get tab and window nr from window ID
693win_id2win({expr}) Number get window nr from window ID
Daniel Steinbergee630312022-01-10 13:36:34 +0000694win_move_separator({nr}) Number move window vertical separator
695win_move_statusline({nr}) Number move window status line
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000696win_screenpos({nr}) List get screen position of window {nr}
697win_splitmove({nr}, {target} [, {options}])
698 Number move window {nr} to split of {target}
699winbufnr({nr}) Number buffer number of window {nr}
700wincol() Number window column of the cursor
701windowsversion() String MS-Windows OS version
702winheight({nr}) Number height of window {nr}
703winlayout([{tabnr}]) List layout of windows in tab {tabnr}
704winline() Number window line of the cursor
705winnr([{expr}]) Number number of current window
706winrestcmd() String returns command to restore window sizes
707winrestview({dict}) none restore view of current window
708winsaveview() Dict save view of current window
709winwidth({nr}) Number width of window {nr}
710wordcount() Dict get byte/char/word statistics
711writefile({object}, {fname} [, {flags}])
712 Number write |Blob| or |List| of lines to file
713xor({expr}, {expr}) Number bitwise XOR
714
715==============================================================================
7162. Details *builtin-function-details*
717
718Not all functions are here, some have been moved to a help file covering the
719specific functionality.
720
721abs({expr}) *abs()*
722 Return the absolute value of {expr}. When {expr} evaluates to
723 a |Float| abs() returns a |Float|. When {expr} can be
724 converted to a |Number| abs() returns a |Number|. Otherwise
725 abs() gives an error message and returns -1.
726 Examples: >
727 echo abs(1.456)
728< 1.456 >
729 echo abs(-5.456)
730< 5.456 >
731 echo abs(-4)
732< 4
733
734 Can also be used as a |method|: >
735 Compute()->abs()
736
737< {only available when compiled with the |+float| feature}
738
739
740acos({expr}) *acos()*
741 Return the arc cosine of {expr} measured in radians, as a
742 |Float| in the range of [0, pi].
743 {expr} must evaluate to a |Float| or a |Number| in the range
744 [-1, 1].
745 Examples: >
746 :echo acos(0)
747< 1.570796 >
748 :echo acos(-0.5)
749< 2.094395
750
751 Can also be used as a |method|: >
752 Compute()->acos()
753
754< {only available when compiled with the |+float| feature}
755
756
757add({object}, {expr}) *add()*
758 Append the item {expr} to |List| or |Blob| {object}. Returns
759 the resulting |List| or |Blob|. Examples: >
760 :let alist = add([1, 2, 3], item)
761 :call add(mylist, "woodstock")
762< Note that when {expr} is a |List| it is appended as a single
763 item. Use |extend()| to concatenate |Lists|.
764 When {object} is a |Blob| then {expr} must be a number.
765 Use |insert()| to add an item at another position.
766
767 Can also be used as a |method|: >
768 mylist->add(val1)->add(val2)
769
770
771and({expr}, {expr}) *and()*
772 Bitwise AND on the two arguments. The arguments are converted
773 to a number. A List, Dict or Float argument causes an error.
774 Example: >
775 :let flag = and(bits, 0x80)
776< Can also be used as a |method|: >
777 :let flag = bits->and(0x80)
778
779
780append({lnum}, {text}) *append()*
781 When {text} is a |List|: Append each item of the |List| as a
782 text line below line {lnum} in the current buffer.
783 Otherwise append {text} as one text line below line {lnum} in
784 the current buffer.
785 Any type of item is accepted and converted to a String.
786 {lnum} can be zero to insert a line before the first one.
787 {lnum} is used like with |getline()|.
788 Returns 1 for failure ({lnum} out of range or out of memory),
789 0 for success. In |Vim9| script an invalid argument or
790 negative number results in an error. Example: >
791 :let failed = append(line('$'), "# THE END")
792 :let failed = append(0, ["Chapter 1", "the beginning"])
793
794< Can also be used as a |method| after a List, the base is
795 passed as the second argument: >
796 mylist->append(lnum)
797
798
799appendbufline({buf}, {lnum}, {text}) *appendbufline()*
800 Like |append()| but append the text in buffer {buf}.
801
802 This function works only for loaded buffers. First call
803 |bufload()| if needed.
804
805 For the use of {buf}, see |bufname()|.
806
Bram Moolenaar8b6256f2021-12-28 11:24:49 +0000807 {lnum} is the line number to append below. Note that using
808 |line()| would use the current buffer, not the one appending
809 to. Use "$" to append at the end of the buffer. Other string
810 values are not supported.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000811
812 On success 0 is returned, on failure 1 is returned.
813 In |Vim9| script an error is given for an invalid {lnum}.
814
815 If {buf} is not a valid buffer or {lnum} is not valid, an
816 error message is given. Example: >
817 :let failed = appendbufline(13, 0, "# THE START")
818<
819 Can also be used as a |method| after a List, the base is
820 passed as the second argument: >
821 mylist->appendbufline(buf, lnum)
822
823
824argc([{winid}]) *argc()*
825 The result is the number of files in the argument list. See
826 |arglist|.
827 If {winid} is not supplied, the argument list of the current
828 window is used.
829 If {winid} is -1, the global argument list is used.
830 Otherwise {winid} specifies the window of which the argument
831 list is used: either the window number or the window ID.
832 Returns -1 if the {winid} argument is invalid.
833
834 *argidx()*
835argidx() The result is the current index in the argument list. 0 is
836 the first file. argc() - 1 is the last one. See |arglist|.
837
838 *arglistid()*
839arglistid([{winnr} [, {tabnr}]])
840 Return the argument list ID. This is a number which
841 identifies the argument list being used. Zero is used for the
842 global argument list. See |arglist|.
843 Returns -1 if the arguments are invalid.
844
845 Without arguments use the current window.
846 With {winnr} only use this window in the current tab page.
847 With {winnr} and {tabnr} use the window in the specified tab
848 page.
849 {winnr} can be the window number or the |window-ID|.
850
851 *argv()*
852argv([{nr} [, {winid}]])
853 The result is the {nr}th file in the argument list. See
854 |arglist|. "argv(0)" is the first one. Example: >
855 :let i = 0
856 :while i < argc()
857 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000858 : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +0000859 : let i = i + 1
860 :endwhile
861< Without the {nr} argument, or when {nr} is -1, a |List| with
862 the whole |arglist| is returned.
863
864 The {winid} argument specifies the window ID, see |argc()|.
865 For the Vim command line arguments see |v:argv|.
866
867asin({expr}) *asin()*
868 Return the arc sine of {expr} measured in radians, as a |Float|
869 in the range of [-pi/2, pi/2].
870 {expr} must evaluate to a |Float| or a |Number| in the range
871 [-1, 1].
872 Examples: >
873 :echo asin(0.8)
874< 0.927295 >
875 :echo asin(-0.5)
876< -0.523599
877
878 Can also be used as a |method|: >
879 Compute()->asin()
880<
881 {only available when compiled with the |+float| feature}
882
883
884assert_ functions are documented here: |assert-functions-details|
885
886
887
888atan({expr}) *atan()*
889 Return the principal value of the arc tangent of {expr}, in
890 the range [-pi/2, +pi/2] radians, as a |Float|.
891 {expr} must evaluate to a |Float| or a |Number|.
892 Examples: >
893 :echo atan(100)
894< 1.560797 >
895 :echo atan(-4.01)
896< -1.326405
897
898 Can also be used as a |method|: >
899 Compute()->atan()
900<
901 {only available when compiled with the |+float| feature}
902
903
904atan2({expr1}, {expr2}) *atan2()*
905 Return the arc tangent of {expr1} / {expr2}, measured in
906 radians, as a |Float| in the range [-pi, pi].
907 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
908 Examples: >
909 :echo atan2(-1, 1)
910< -0.785398 >
911 :echo atan2(1, -1)
912< 2.356194
913
914 Can also be used as a |method|: >
915 Compute()->atan2(1)
916<
917 {only available when compiled with the |+float| feature}
918
919balloon_gettext() *balloon_gettext()*
920 Return the current text in the balloon. Only for the string,
921 not used for the List.
922
923balloon_show({expr}) *balloon_show()*
924 Show {expr} inside the balloon. For the GUI {expr} is used as
925 a string. For a terminal {expr} can be a list, which contains
926 the lines of the balloon. If {expr} is not a list it will be
927 split with |balloon_split()|.
928 If {expr} is an empty string any existing balloon is removed.
929
930 Example: >
931 func GetBalloonContent()
932 " ... initiate getting the content
933 return ''
934 endfunc
935 set balloonexpr=GetBalloonContent()
936
937 func BalloonCallback(result)
938 call balloon_show(a:result)
939 endfunc
940< Can also be used as a |method|: >
941 GetText()->balloon_show()
942<
943 The intended use is that fetching the content of the balloon
944 is initiated from 'balloonexpr'. It will invoke an
945 asynchronous method, in which a callback invokes
946 balloon_show(). The 'balloonexpr' itself can return an
947 empty string or a placeholder.
948
949 When showing a balloon is not possible nothing happens, no
950 error message.
951 {only available when compiled with the |+balloon_eval| or
952 |+balloon_eval_term| feature}
953
954balloon_split({msg}) *balloon_split()*
955 Split String {msg} into lines to be displayed in a balloon.
956 The splits are made for the current window size and optimize
957 to show debugger output.
958 Returns a |List| with the split lines.
959 Can also be used as a |method|: >
960 GetText()->balloon_split()->balloon_show()
961
962< {only available when compiled with the |+balloon_eval_term|
963 feature}
964
965blob2list({blob}) *blob2list()*
966 Return a List containing the number value of each byte in Blob
967 {blob}. Examples: >
968 blob2list(0z0102.0304) returns [1, 2, 3, 4]
969 blob2list(0z) returns []
970< Returns an empty List on error. |list2blob()| does the
971 opposite.
972
973 Can also be used as a |method|: >
974 GetBlob()->blob2list()
975
976 *browse()*
977browse({save}, {title}, {initdir}, {default})
978 Put up a file requester. This only works when "has("browse")"
979 returns |TRUE| (only in some GUI versions).
980 The input fields are:
981 {save} when |TRUE|, select file to write
982 {title} title for the requester
983 {initdir} directory to start browsing in
984 {default} default file name
985 An empty string is returned when the "Cancel" button is hit,
986 something went wrong, or browsing is not possible.
987
988 *browsedir()*
989browsedir({title}, {initdir})
990 Put up a directory requester. This only works when
991 "has("browse")" returns |TRUE| (only in some GUI versions).
992 On systems where a directory browser is not supported a file
993 browser is used. In that case: select a file in the directory
994 to be used.
995 The input fields are:
996 {title} title for the requester
997 {initdir} directory to start browsing in
998 When the "Cancel" button is hit, something went wrong, or
999 browsing is not possible, an empty string is returned.
1000
1001bufadd({name}) *bufadd()*
1002 Add a buffer to the buffer list with String {name}.
1003 If a buffer for file {name} already exists, return that buffer
1004 number. Otherwise return the buffer number of the newly
1005 created buffer. When {name} is an empty string then a new
1006 buffer is always created.
1007 The buffer will not have 'buflisted' set and not be loaded
1008 yet. To add some text to the buffer use this: >
1009 let bufnr = bufadd('someName')
1010 call bufload(bufnr)
1011 call setbufline(bufnr, 1, ['some', 'text'])
1012< Can also be used as a |method|: >
1013 let bufnr = 'somename'->bufadd()
1014
1015bufexists({buf}) *bufexists()*
1016 The result is a Number, which is |TRUE| if a buffer called
1017 {buf} exists.
1018 If the {buf} argument is a number, buffer numbers are used.
1019 Number zero is the alternate buffer for the current window.
1020
1021 If the {buf} argument is a string it must match a buffer name
1022 exactly. The name can be:
1023 - Relative to the current directory.
1024 - A full path.
1025 - The name of a buffer with 'buftype' set to "nofile".
1026 - A URL name.
1027 Unlisted buffers will be found.
1028 Note that help files are listed by their short name in the
1029 output of |:buffers|, but bufexists() requires using their
1030 long name to be able to find them.
1031 bufexists() may report a buffer exists, but to use the name
1032 with a |:buffer| command you may need to use |expand()|. Esp
1033 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1034 Use "bufexists(0)" to test for the existence of an alternate
1035 file name.
1036
1037 Can also be used as a |method|: >
1038 let exists = 'somename'->bufexists()
1039<
1040 Obsolete name: buffer_exists(). *buffer_exists()*
1041
1042buflisted({buf}) *buflisted()*
1043 The result is a Number, which is |TRUE| if a buffer called
1044 {buf} exists and is listed (has the 'buflisted' option set).
1045 The {buf} argument is used like with |bufexists()|.
1046
1047 Can also be used as a |method|: >
1048 let listed = 'somename'->buflisted()
1049
1050bufload({buf}) *bufload()*
1051 Ensure the buffer {buf} is loaded. When the buffer name
1052 refers to an existing file then the file is read. Otherwise
1053 the buffer will be empty. If the buffer was already loaded
1054 then there is no change.
1055 If there is an existing swap file for the file of the buffer,
1056 there will be no dialog, the buffer will be loaded anyway.
1057 The {buf} argument is used like with |bufexists()|.
1058
1059 Can also be used as a |method|: >
1060 eval 'somename'->bufload()
1061
1062bufloaded({buf}) *bufloaded()*
1063 The result is a Number, which is |TRUE| if a buffer called
1064 {buf} exists and is loaded (shown in a window or hidden).
1065 The {buf} argument is used like with |bufexists()|.
1066
1067 Can also be used as a |method|: >
1068 let loaded = 'somename'->bufloaded()
1069
1070bufname([{buf}]) *bufname()*
1071 The result is the name of a buffer. Mostly as it is displayed
1072 by the `:ls` command, but not using special names such as
1073 "[No Name]".
1074 If {buf} is omitted the current buffer is used.
1075 If {buf} is a Number, that buffer number's name is given.
1076 Number zero is the alternate buffer for the current window.
1077 If {buf} is a String, it is used as a |file-pattern| to match
1078 with the buffer names. This is always done like 'magic' is
1079 set and 'cpoptions' is empty. When there is more than one
1080 match an empty string is returned.
1081 "" or "%" can be used for the current buffer, "#" for the
1082 alternate buffer.
1083 A full match is preferred, otherwise a match at the start, end
1084 or middle of the buffer name is accepted. If you only want a
1085 full match then put "^" at the start and "$" at the end of the
1086 pattern.
1087 Listed buffers are found first. If there is a single match
1088 with a listed buffer, that one is returned. Next unlisted
1089 buffers are searched for.
1090 If the {buf} is a String, but you want to use it as a buffer
1091 number, force it to be a Number by adding zero to it: >
1092 :echo bufname("3" + 0)
1093< Can also be used as a |method|: >
1094 echo bufnr->bufname()
1095
1096< If the buffer doesn't exist, or doesn't have a name, an empty
1097 string is returned. >
1098 bufname("#") alternate buffer name
1099 bufname(3) name of buffer 3
1100 bufname("%") name of current buffer
1101 bufname("file2") name of buffer where "file2" matches.
1102< *buffer_name()*
1103 Obsolete name: buffer_name().
1104
1105 *bufnr()*
1106bufnr([{buf} [, {create}]])
1107 The result is the number of a buffer, as it is displayed by
1108 the `:ls` command. For the use of {buf}, see |bufname()|
1109 above.
1110
1111 If the buffer doesn't exist, -1 is returned. Or, if the
1112 {create} argument is present and TRUE, a new, unlisted,
1113 buffer is created and its number is returned. Example: >
1114 let newbuf = bufnr('Scratch001', 1)
1115< Using an empty name uses the current buffer. To create a new
1116 buffer with an empty name use |bufadd()|.
1117
1118 bufnr("$") is the last buffer: >
1119 :let last_buffer = bufnr("$")
1120< The result is a Number, which is the highest buffer number
1121 of existing buffers. Note that not all buffers with a smaller
1122 number necessarily exist, because ":bwipeout" may have removed
1123 them. Use bufexists() to test for the existence of a buffer.
1124
1125 Can also be used as a |method|: >
1126 echo bufref->bufnr()
1127<
1128 Obsolete name: buffer_number(). *buffer_number()*
1129 *last_buffer_nr()*
1130 Obsolete name for bufnr("$"): last_buffer_nr().
1131
1132bufwinid({buf}) *bufwinid()*
1133 The result is a Number, which is the |window-ID| of the first
1134 window associated with buffer {buf}. For the use of {buf},
1135 see |bufname()| above. If buffer {buf} doesn't exist or
1136 there is no such window, -1 is returned. Example: >
1137
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001138 echo "A window containing buffer 1 is " .. (bufwinid(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001139<
1140 Only deals with the current tab page.
1141
1142 Can also be used as a |method|: >
1143 FindBuffer()->bufwinid()
1144
1145bufwinnr({buf}) *bufwinnr()*
1146 Like |bufwinid()| but return the window number instead of the
1147 |window-ID|.
1148 If buffer {buf} doesn't exist or there is no such window, -1
1149 is returned. Example: >
1150
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001151 echo "A window containing buffer 1 is " .. (bufwinnr(1))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001152
1153< The number can be used with |CTRL-W_w| and ":wincmd w"
1154 |:wincmd|.
1155
1156 Can also be used as a |method|: >
1157 FindBuffer()->bufwinnr()
1158
1159byte2line({byte}) *byte2line()*
1160 Return the line number that contains the character at byte
1161 count {byte} in the current buffer. This includes the
1162 end-of-line character, depending on the 'fileformat' option
1163 for the current buffer. The first character has byte count
1164 one.
1165 Also see |line2byte()|, |go| and |:goto|.
1166
1167 Can also be used as a |method|: >
1168 GetOffset()->byte2line()
1169
1170< {not available when compiled without the |+byte_offset|
1171 feature}
1172
1173byteidx({expr}, {nr}) *byteidx()*
1174 Return byte index of the {nr}'th character in the String
1175 {expr}. Use zero for the first character, it then returns
1176 zero.
1177 If there are no multibyte characters the returned value is
1178 equal to {nr}.
1179 Composing characters are not counted separately, their byte
1180 length is added to the preceding base character. See
1181 |byteidxcomp()| below for counting composing characters
1182 separately.
1183 Example : >
1184 echo matchstr(str, ".", byteidx(str, 3))
1185< will display the fourth character. Another way to do the
1186 same: >
1187 let s = strpart(str, byteidx(str, 3))
1188 echo strpart(s, 0, byteidx(s, 1))
1189< Also see |strgetchar()| and |strcharpart()|.
1190
1191 If there are less than {nr} characters -1 is returned.
1192 If there are exactly {nr} characters the length of the string
1193 in bytes is returned.
1194
1195 Can also be used as a |method|: >
1196 GetName()->byteidx(idx)
1197
1198byteidxcomp({expr}, {nr}) *byteidxcomp()*
1199 Like byteidx(), except that a composing character is counted
1200 as a separate character. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001201 let s = 'e' .. nr2char(0x301)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001202 echo byteidx(s, 1)
1203 echo byteidxcomp(s, 1)
1204 echo byteidxcomp(s, 2)
1205< The first and third echo result in 3 ('e' plus composing
1206 character is 3 bytes), the second echo results in 1 ('e' is
1207 one byte).
1208 Only works differently from byteidx() when 'encoding' is set
1209 to a Unicode encoding.
1210
1211 Can also be used as a |method|: >
1212 GetName()->byteidxcomp(idx)
1213
1214call({func}, {arglist} [, {dict}]) *call()* *E699*
1215 Call function {func} with the items in |List| {arglist} as
1216 arguments.
1217 {func} can either be a |Funcref| or the name of a function.
1218 a:firstline and a:lastline are set to the cursor line.
1219 Returns the return value of the called function.
1220 {dict} is for functions with the "dict" attribute. It will be
1221 used to set the local variable "self". |Dictionary-function|
1222
1223 Can also be used as a |method|: >
1224 GetFunc()->call([arg, arg], dict)
1225
1226ceil({expr}) *ceil()*
1227 Return the smallest integral value greater than or equal to
1228 {expr} as a |Float| (round up).
1229 {expr} must evaluate to a |Float| or a |Number|.
1230 Examples: >
1231 echo ceil(1.456)
1232< 2.0 >
1233 echo ceil(-5.456)
1234< -5.0 >
1235 echo ceil(4.0)
1236< 4.0
1237
1238 Can also be used as a |method|: >
1239 Compute()->ceil()
1240<
1241 {only available when compiled with the |+float| feature}
1242
1243
1244ch_ functions are documented here: |channel-functions-details|
1245
1246
1247changenr() *changenr()*
1248 Return the number of the most recent change. This is the same
1249 number as what is displayed with |:undolist| and can be used
1250 with the |:undo| command.
1251 When a change was made it is the number of that change. After
1252 redo it is the number of the redone change. After undo it is
1253 one less than the number of the undone change.
1254
1255char2nr({string} [, {utf8}]) *char2nr()*
1256 Return number value of the first char in {string}.
1257 Examples: >
1258 char2nr(" ") returns 32
1259 char2nr("ABC") returns 65
1260< When {utf8} is omitted or zero, the current 'encoding' is used.
1261 Example for "utf-8": >
1262 char2nr("á") returns 225
1263 char2nr("á"[0]) returns 195
1264< When {utf8} is TRUE, always treat as UTF-8 characters.
1265 A combining character is a separate character.
1266 |nr2char()| does the opposite.
1267 To turn a string into a list of character numbers: >
1268 let str = "ABC"
1269 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
1270< Result: [65, 66, 67]
1271
1272 Can also be used as a |method|: >
1273 GetChar()->char2nr()
1274
1275
1276charclass({string}) *charclass()*
1277 Return the character class of the first character in {string}.
1278 The character class is one of:
1279 0 blank
1280 1 punctuation
1281 2 word character
1282 3 emoji
1283 other specific Unicode class
1284 The class is used in patterns and word motions.
1285
1286
1287charcol({expr}) *charcol()*
1288 Same as |col()| but returns the character index of the column
1289 position given with {expr} instead of the byte position.
1290
1291 Example:
1292 With the cursor on '세' in line 5 with text "여보세요": >
1293 charcol('.') returns 3
1294 col('.') returns 7
1295
1296< Can also be used as a |method|: >
1297 GetPos()->col()
1298<
1299 *charidx()*
1300charidx({string}, {idx} [, {countcc}])
1301 Return the character index of the byte at {idx} in {string}.
1302 The index of the first character is zero.
1303 If there are no multibyte characters the returned value is
1304 equal to {idx}.
1305 When {countcc} is omitted or |FALSE|, then composing characters
1306 are not counted separately, their byte length is
1307 added to the preceding base character.
1308 When {countcc} is |TRUE|, then composing characters are
1309 counted as separate characters.
1310 Returns -1 if the arguments are invalid or if {idx} is greater
1311 than the index of the last byte in {string}. An error is
1312 given if the first argument is not a string, the second
1313 argument is not a number or when the third argument is present
1314 and is not zero or one.
1315 See |byteidx()| and |byteidxcomp()| for getting the byte index
1316 from the character index.
1317 Examples: >
1318 echo charidx('áb́ć', 3) returns 1
1319 echo charidx('áb́ć', 6, 1) returns 4
1320 echo charidx('áb́ć', 16) returns -1
1321<
1322 Can also be used as a |method|: >
1323 GetName()->charidx(idx)
1324
1325chdir({dir}) *chdir()*
1326 Change the current working directory to {dir}. The scope of
1327 the directory change depends on the directory of the current
1328 window:
1329 - If the current window has a window-local directory
1330 (|:lcd|), then changes the window local directory.
1331 - Otherwise, if the current tabpage has a local
1332 directory (|:tcd|) then changes the tabpage local
1333 directory.
1334 - Otherwise, changes the global directory.
1335 {dir} must be a String.
1336 If successful, returns the previous working directory. Pass
1337 this to another chdir() to restore the directory.
1338 On failure, returns an empty string.
1339
1340 Example: >
1341 let save_dir = chdir(newdir)
1342 if save_dir != ""
1343 " ... do some work
1344 call chdir(save_dir)
1345 endif
1346
1347< Can also be used as a |method|: >
1348 GetDir()->chdir()
1349<
1350cindent({lnum}) *cindent()*
1351 Get the amount of indent for line {lnum} according the C
1352 indenting rules, as with 'cindent'.
1353 The indent is counted in spaces, the value of 'tabstop' is
1354 relevant. {lnum} is used just like in |getline()|.
1355 When {lnum} is invalid or Vim was not compiled the |+cindent|
1356 feature, -1 is returned.
1357 See |C-indenting|.
1358
1359 Can also be used as a |method|: >
1360 GetLnum()->cindent()
1361
1362clearmatches([{win}]) *clearmatches()*
1363 Clears all matches previously defined for the current window
1364 by |matchadd()| and the |:match| commands.
1365 If {win} is specified, use the window with this number or
1366 window ID instead of the current window.
1367
1368 Can also be used as a |method|: >
1369 GetWin()->clearmatches()
1370<
1371 *col()*
1372col({expr}) The result is a Number, which is the byte index of the column
1373 position given with {expr}. The accepted positions are:
1374 . the cursor position
1375 $ the end of the cursor line (the result is the
1376 number of bytes in the cursor line plus one)
1377 'x position of mark x (if the mark is not set, 0 is
1378 returned)
1379 v In Visual mode: the start of the Visual area (the
1380 cursor is the end). When not in Visual mode
1381 returns the cursor position. Differs from |'<| in
1382 that it's updated right away.
1383 Additionally {expr} can be [lnum, col]: a |List| with the line
1384 and column number. Most useful when the column is "$", to get
1385 the last column of a specific line. When "lnum" or "col" is
1386 out of range then col() returns zero.
1387 To get the line number use |line()|. To get both use
1388 |getpos()|.
1389 For the screen column position use |virtcol()|. For the
1390 character position use |charcol()|.
1391 Note that only marks in the current file can be used.
1392 Examples: >
1393 col(".") column of cursor
1394 col("$") length of cursor line plus one
1395 col("'t") column of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001396 col("'" .. markname) column of mark markname
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001397< The first column is 1. 0 is returned for an error.
1398 For an uppercase mark the column may actually be in another
1399 buffer.
1400 For the cursor position, when 'virtualedit' is active, the
1401 column is one higher if the cursor is after the end of the
1402 line. This can be used to obtain the column in Insert mode: >
1403 :imap <F2> <C-O>:let save_ve = &ve<CR>
1404 \<C-O>:set ve=all<CR>
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001405 \<C-O>:echo col(".") .. "\n" <Bar>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001406 \let &ve = save_ve<CR>
1407
1408< Can also be used as a |method|: >
1409 GetPos()->col()
1410<
1411
1412complete({startcol}, {matches}) *complete()* *E785*
1413 Set the matches for Insert mode completion.
1414 Can only be used in Insert mode. You need to use a mapping
1415 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
1416 or with an expression mapping.
1417 {startcol} is the byte offset in the line where the completed
1418 text start. The text up to the cursor is the original text
1419 that will be replaced by the matches. Use col('.') for an
1420 empty string. "col('.') - 1" will replace one character by a
1421 match.
1422 {matches} must be a |List|. Each |List| item is one match.
1423 See |complete-items| for the kind of items that are possible.
1424 "longest" in 'completeopt' is ignored.
1425 Note that the after calling this function you need to avoid
1426 inserting anything that would cause completion to stop.
1427 The match can be selected with CTRL-N and CTRL-P as usual with
1428 Insert mode completion. The popup menu will appear if
1429 specified, see |ins-completion-menu|.
1430 Example: >
1431 inoremap <F5> <C-R>=ListMonths()<CR>
1432
1433 func! ListMonths()
1434 call complete(col('.'), ['January', 'February', 'March',
1435 \ 'April', 'May', 'June', 'July', 'August', 'September',
1436 \ 'October', 'November', 'December'])
1437 return ''
1438 endfunc
1439< This isn't very useful, but it shows how it works. Note that
1440 an empty string is returned to avoid a zero being inserted.
1441
1442 Can also be used as a |method|, the base is passed as the
1443 second argument: >
1444 GetMatches()->complete(col('.'))
1445
1446complete_add({expr}) *complete_add()*
1447 Add {expr} to the list of matches. Only to be used by the
1448 function specified with the 'completefunc' option.
1449 Returns 0 for failure (empty string or out of memory),
1450 1 when the match was added, 2 when the match was already in
1451 the list.
1452 See |complete-functions| for an explanation of {expr}. It is
1453 the same as one item in the list that 'omnifunc' would return.
1454
1455 Can also be used as a |method|: >
1456 GetMoreMatches()->complete_add()
1457
1458complete_check() *complete_check()*
1459 Check for a key typed while looking for completion matches.
1460 This is to be used when looking for matches takes some time.
1461 Returns |TRUE| when searching for matches is to be aborted,
1462 zero otherwise.
1463 Only to be used by the function specified with the
1464 'completefunc' option.
1465
1466
1467complete_info([{what}]) *complete_info()*
1468 Returns a |Dictionary| with information about Insert mode
1469 completion. See |ins-completion|.
1470 The items are:
1471 mode Current completion mode name string.
1472 See |complete_info_mode| for the values.
1473 pum_visible |TRUE| if popup menu is visible.
1474 See |pumvisible()|.
1475 items List of completion matches. Each item is a
1476 dictionary containing the entries "word",
1477 "abbr", "menu", "kind", "info" and "user_data".
1478 See |complete-items|.
1479 selected Selected item index. First index is zero.
1480 Index is -1 if no item is selected (showing
1481 typed text only, or the last completion after
1482 no item is selected when using the <Up> or
1483 <Down> keys)
1484 inserted Inserted string. [NOT IMPLEMENT YET]
1485
1486 *complete_info_mode*
1487 mode values are:
1488 "" Not in completion mode
1489 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
1490 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
1491 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
1492 |i_CTRL-X_CTRL-Y|
1493 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
1494 "files" File names |i_CTRL-X_CTRL-F|
1495 "tags" Tags |i_CTRL-X_CTRL-]|
1496 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
1497 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
1498 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
1499 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
1500 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
1501 "function" User defined completion |i_CTRL-X_CTRL-U|
1502 "omni" Omni completion |i_CTRL-X_CTRL-O|
1503 "spell" Spelling suggestions |i_CTRL-X_s|
1504 "eval" |complete()| completion
1505 "unknown" Other internal modes
1506
1507 If the optional {what} list argument is supplied, then only
1508 the items listed in {what} are returned. Unsupported items in
1509 {what} are silently ignored.
1510
1511 To get the position and size of the popup menu, see
1512 |pum_getpos()|. It's also available in |v:event| during the
1513 |CompleteChanged| event.
1514
1515 Examples: >
1516 " Get all items
1517 call complete_info()
1518 " Get only 'mode'
1519 call complete_info(['mode'])
1520 " Get only 'mode' and 'pum_visible'
1521 call complete_info(['mode', 'pum_visible'])
1522
1523< Can also be used as a |method|: >
1524 GetItems()->complete_info()
1525<
1526 *confirm()*
1527confirm({msg} [, {choices} [, {default} [, {type}]]])
1528 confirm() offers the user a dialog, from which a choice can be
1529 made. It returns the number of the choice. For the first
1530 choice this is 1.
1531 Note: confirm() is only supported when compiled with dialog
1532 support, see |+dialog_con| and |+dialog_gui|.
1533
1534 {msg} is displayed in a |dialog| with {choices} as the
1535 alternatives. When {choices} is missing or empty, "&OK" is
1536 used (and translated).
1537 {msg} is a String, use '\n' to include a newline. Only on
1538 some systems the string is wrapped when it doesn't fit.
1539
1540 {choices} is a String, with the individual choices separated
1541 by '\n', e.g. >
1542 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1543< The letter after the '&' is the shortcut key for that choice.
1544 Thus you can type 'c' to select "Cancel". The shortcut does
1545 not need to be the first letter: >
1546 confirm("file has been modified", "&Save\nSave &All")
1547< For the console, the first letter of each choice is used as
1548 the default shortcut key. Case is ignored.
1549
1550 The optional {default} argument is the number of the choice
1551 that is made if the user hits <CR>. Use 1 to make the first
1552 choice the default one. Use 0 to not set a default. If
1553 {default} is omitted, 1 is used.
1554
1555 The optional {type} String argument gives the type of dialog.
1556 This is only used for the icon of the GTK, Mac, Motif and
1557 Win32 GUI. It can be one of these values: "Error",
1558 "Question", "Info", "Warning" or "Generic". Only the first
1559 character is relevant. When {type} is omitted, "Generic" is
1560 used.
1561
1562 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1563 or another valid interrupt key, confirm() returns 0.
1564
1565 An example: >
Bram Moolenaar46eea442022-03-30 10:51:39 +01001566 let choice = confirm("What do you want?",
1567 \ "&Apples\n&Oranges\n&Bananas", 2)
1568 if choice == 0
1569 echo "make up your mind!"
1570 elseif choice == 3
1571 echo "tasteful"
1572 else
1573 echo "I prefer bananas myself."
1574 endif
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001575< In a GUI dialog, buttons are used. The layout of the buttons
1576 depends on the 'v' flag in 'guioptions'. If it is included,
1577 the buttons are always put vertically. Otherwise, confirm()
1578 tries to put the buttons in one horizontal line. If they
1579 don't fit, a vertical layout is used anyway. For some systems
1580 the horizontal layout is always used.
1581
1582 Can also be used as a |method|in: >
1583 BuildMessage()->confirm("&Yes\n&No")
1584<
1585 *copy()*
1586copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1587 different from using {expr} directly.
1588 When {expr} is a |List| a shallow copy is created. This means
1589 that the original |List| can be changed without changing the
1590 copy, and vice versa. But the items are identical, thus
1591 changing an item changes the contents of both |Lists|.
1592 A |Dictionary| is copied in a similar way as a |List|.
1593 Also see |deepcopy()|.
1594 Can also be used as a |method|: >
1595 mylist->copy()
1596
1597cos({expr}) *cos()*
1598 Return the cosine of {expr}, measured in radians, as a |Float|.
1599 {expr} must evaluate to a |Float| or a |Number|.
1600 Examples: >
1601 :echo cos(100)
1602< 0.862319 >
1603 :echo cos(-4.01)
1604< -0.646043
1605
1606 Can also be used as a |method|: >
1607 Compute()->cos()
1608<
1609 {only available when compiled with the |+float| feature}
1610
1611
1612cosh({expr}) *cosh()*
1613 Return the hyperbolic cosine of {expr} as a |Float| in the range
1614 [1, inf].
1615 {expr} must evaluate to a |Float| or a |Number|.
1616 Examples: >
1617 :echo cosh(0.5)
1618< 1.127626 >
1619 :echo cosh(-0.5)
1620< -1.127626
1621
1622 Can also be used as a |method|: >
1623 Compute()->cosh()
1624<
1625 {only available when compiled with the |+float| feature}
1626
1627
1628count({comp}, {expr} [, {ic} [, {start}]]) *count()*
1629 Return the number of times an item with value {expr} appears
1630 in |String|, |List| or |Dictionary| {comp}.
1631
1632 If {start} is given then start with the item with this index.
1633 {start} can only be used with a |List|.
1634
1635 When {ic} is given and it's |TRUE| then case is ignored.
1636
1637 When {comp} is a string then the number of not overlapping
1638 occurrences of {expr} is returned. Zero is returned when
1639 {expr} is an empty string.
1640
1641 Can also be used as a |method|: >
1642 mylist->count(val)
1643<
1644 *cscope_connection()*
1645cscope_connection([{num} , {dbpath} [, {prepend}]])
1646 Checks for the existence of a |cscope| connection. If no
1647 parameters are specified, then the function returns:
1648 0, if cscope was not available (not compiled in), or
1649 if there are no cscope connections;
1650 1, if there is at least one cscope connection.
1651
1652 If parameters are specified, then the value of {num}
1653 determines how existence of a cscope connection is checked:
1654
1655 {num} Description of existence check
1656 ----- ------------------------------
1657 0 Same as no parameters (e.g., "cscope_connection()").
1658 1 Ignore {prepend}, and use partial string matches for
1659 {dbpath}.
1660 2 Ignore {prepend}, and use exact string matches for
1661 {dbpath}.
1662 3 Use {prepend}, use partial string matches for both
1663 {dbpath} and {prepend}.
1664 4 Use {prepend}, use exact string matches for both
1665 {dbpath} and {prepend}.
1666
1667 Note: All string comparisons are case sensitive!
1668
1669 Examples. Suppose we had the following (from ":cs show"): >
1670
1671 # pid database name prepend path
1672 0 27664 cscope.out /usr/local
1673<
1674 Invocation Return Val ~
1675 ---------- ---------- >
1676 cscope_connection() 1
1677 cscope_connection(1, "out") 1
1678 cscope_connection(2, "out") 0
1679 cscope_connection(3, "out") 0
1680 cscope_connection(3, "out", "local") 1
1681 cscope_connection(4, "out") 0
1682 cscope_connection(4, "out", "local") 0
1683 cscope_connection(4, "cscope.out", "/usr/local") 1
1684<
1685cursor({lnum}, {col} [, {off}]) *cursor()*
1686cursor({list})
1687 Positions the cursor at the column (byte count) {col} in the
1688 line {lnum}. The first column is one.
1689
1690 When there is one argument {list} this is used as a |List|
1691 with two, three or four item:
1692 [{lnum}, {col}]
1693 [{lnum}, {col}, {off}]
1694 [{lnum}, {col}, {off}, {curswant}]
1695 This is like the return value of |getpos()| or |getcurpos()|,
1696 but without the first item.
1697
1698 To position the cursor using the character count, use
1699 |setcursorcharpos()|.
1700
1701 Does not change the jumplist.
1702 {lnum} is used like with |getline()|.
1703 If {lnum} is greater than the number of lines in the buffer,
1704 the cursor will be positioned at the last line in the buffer.
1705 If {lnum} is zero, the cursor will stay in the current line.
1706 If {col} is greater than the number of bytes in the line,
1707 the cursor will be positioned at the last character in the
1708 line.
1709 If {col} is zero, the cursor will stay in the current column.
1710 If {curswant} is given it is used to set the preferred column
1711 for vertical movement. Otherwise {col} is used.
1712
1713 When 'virtualedit' is used {off} specifies the offset in
1714 screen columns from the start of the character. E.g., a
1715 position within a <Tab> or after the last character.
1716 Returns 0 when the position could be set, -1 otherwise.
1717
1718 Can also be used as a |method|: >
1719 GetCursorPos()->cursor()
1720
1721debugbreak({pid}) *debugbreak()*
1722 Specifically used to interrupt a program being debugged. It
1723 will cause process {pid} to get a SIGTRAP. Behavior for other
1724 processes is undefined. See |terminal-debugger|.
1725 {only available on MS-Windows}
1726
1727 Can also be used as a |method|: >
1728 GetPid()->debugbreak()
1729
1730deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
1731 Make a copy of {expr}. For Numbers and Strings this isn't
1732 different from using {expr} directly.
1733 When {expr} is a |List| a full copy is created. This means
1734 that the original |List| can be changed without changing the
1735 copy, and vice versa. When an item is a |List| or
1736 |Dictionary|, a copy for it is made, recursively. Thus
1737 changing an item in the copy does not change the contents of
1738 the original |List|.
1739 A |Dictionary| is copied in a similar way as a |List|.
1740
1741 When {noref} is omitted or zero a contained |List| or
1742 |Dictionary| is only copied once. All references point to
1743 this single copy. With {noref} set to 1 every occurrence of a
1744 |List| or |Dictionary| results in a new copy. This also means
1745 that a cyclic reference causes deepcopy() to fail.
1746 *E724*
1747 Nesting is possible up to 100 levels. When there is an item
1748 that refers back to a higher level making a deep copy with
1749 {noref} set to 1 will fail.
1750 Also see |copy()|.
1751
1752 Can also be used as a |method|: >
1753 GetObject()->deepcopy()
1754
1755delete({fname} [, {flags}]) *delete()*
1756 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001757 name {fname}.
1758
1759 This also works when {fname} is a symbolic link. The symbolic
1760 link itself is deleted, not what it points to.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001761
1762 When {flags} is "d": Deletes the directory by the name
1763 {fname}. This fails when directory {fname} is not empty.
1764
1765 When {flags} is "rf": Deletes the directory by the name
1766 {fname} and everything in it, recursively. BE CAREFUL!
1767 Note: on MS-Windows it is not possible to delete a directory
1768 that is being used.
1769
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001770 The result is a Number, which is 0/false if the delete
1771 operation was successful and -1/true when the deletion failed
1772 or partly failed.
1773
1774 Use |remove()| to delete an item from a |List|.
1775 To delete a line from the buffer use |:delete| or
1776 |deletebufline()|.
1777
1778 Can also be used as a |method|: >
1779 GetName()->delete()
1780
1781deletebufline({buf}, {first} [, {last}]) *deletebufline()*
1782 Delete lines {first} to {last} (inclusive) from buffer {buf}.
1783 If {last} is omitted then delete line {first} only.
1784 On success 0 is returned, on failure 1 is returned.
1785
1786 This function works only for loaded buffers. First call
1787 |bufload()| if needed.
1788
1789 For the use of {buf}, see |bufname()| above.
1790
1791 {first} and {last} are used like with |getline()|. Note that
1792 when using |line()| this refers to the current buffer. Use "$"
1793 to refer to the last line in buffer {buf}.
1794
1795 Can also be used as a |method|: >
1796 GetBuffer()->deletebufline(1)
1797<
1798 *did_filetype()*
1799did_filetype() Returns |TRUE| when autocommands are being executed and the
1800 FileType event has been triggered at least once. Can be used
1801 to avoid triggering the FileType event again in the scripts
1802 that detect the file type. |FileType|
1803 Returns |FALSE| when `:setf FALLBACK` was used.
1804 When editing another file, the counter is reset, thus this
1805 really checks if the FileType event has been triggered for the
1806 current buffer. This allows an autocommand that starts
1807 editing another buffer to set 'filetype' and load a syntax
1808 file.
1809
1810diff_filler({lnum}) *diff_filler()*
1811 Returns the number of filler lines above line {lnum}.
1812 These are the lines that were inserted at this point in
1813 another diff'ed window. These filler lines are shown in the
1814 display but don't exist in the buffer.
1815 {lnum} is used like with |getline()|. Thus "." is the current
1816 line, "'m" mark m, etc.
1817 Returns 0 if the current window is not in diff mode.
1818
1819 Can also be used as a |method|: >
1820 GetLnum()->diff_filler()
1821
1822diff_hlID({lnum}, {col}) *diff_hlID()*
1823 Returns the highlight ID for diff mode at line {lnum} column
1824 {col} (byte index). When the current line does not have a
1825 diff change zero is returned.
1826 {lnum} is used like with |getline()|. Thus "." is the current
1827 line, "'m" mark m, etc.
1828 {col} is 1 for the leftmost column, {lnum} is 1 for the first
1829 line.
1830 The highlight ID can be used with |synIDattr()| to obtain
1831 syntax information about the highlighting.
1832
1833 Can also be used as a |method|: >
1834 GetLnum()->diff_hlID(col)
1835<
1836
1837digraph_get({chars}) *digraph_get()* *E1214*
1838 Return the digraph of {chars}. This should be a string with
1839 exactly two characters. If {chars} are not just two
1840 characters, or the digraph of {chars} does not exist, an error
1841 is given and an empty string is returned.
1842
1843 The character will be converted from Unicode to 'encoding'
1844 when needed. This does require the conversion to be
1845 available, it might fail.
1846
1847 Also see |digraph_getlist()|.
1848
1849 Examples: >
1850 " Get a built-in digraph
1851 :echo digraph_get('00') " Returns '∞'
1852
1853 " Get a user-defined digraph
1854 :call digraph_set('aa', 'あ')
1855 :echo digraph_get('aa') " Returns 'あ'
1856<
1857 Can also be used as a |method|: >
1858 GetChars()->digraph_get()
1859<
1860 This function works only when compiled with the |+digraphs|
1861 feature. If this feature is disabled, this function will
1862 display an error message.
1863
1864
1865digraph_getlist([{listall}]) *digraph_getlist()*
1866 Return a list of digraphs. If the {listall} argument is given
1867 and it is TRUE, return all digraphs, including the default
1868 digraphs. Otherwise, return only user-defined digraphs.
1869
1870 The characters will be converted from Unicode to 'encoding'
1871 when needed. This does require the conservation to be
1872 available, it might fail.
1873
1874 Also see |digraph_get()|.
1875
1876 Examples: >
1877 " Get user-defined digraphs
1878 :echo digraph_getlist()
1879
1880 " Get all the digraphs, including default digraphs
1881 :echo digraph_getlist(1)
1882<
1883 Can also be used as a |method|: >
1884 GetNumber()->digraph_getlist()
1885<
1886 This function works only when compiled with the |+digraphs|
1887 feature. If this feature is disabled, this function will
1888 display an error message.
1889
1890
Bram Moolenaara2baa732022-02-04 16:09:54 +00001891digraph_set({chars}, {digraph}) *digraph_set()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001892 Add digraph {chars} to the list. {chars} must be a string
1893 with two characters. {digraph} is a string with one UTF-8
Bram Moolenaara2baa732022-02-04 16:09:54 +00001894 encoded character. *E1215*
1895 Be careful, composing characters are NOT ignored. This
1896 function is similar to |:digraphs| command, but useful to add
1897 digraphs start with a white space.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001898
1899 The function result is v:true if |digraph| is registered. If
1900 this fails an error message is given and v:false is returned.
1901
1902 If you want to define multiple digraphs at once, you can use
1903 |digraph_setlist()|.
1904
1905 Example: >
1906 call digraph_set(' ', 'あ')
1907<
1908 Can be used as a |method|: >
1909 GetString()->digraph_set('あ')
1910<
1911 This function works only when compiled with the |+digraphs|
1912 feature. If this feature is disabled, this function will
1913 display an error message.
1914
1915
1916digraph_setlist({digraphlist}) *digraph_setlist()*
1917 Similar to |digraph_set()| but this function can add multiple
1918 digraphs at once. {digraphlist} is a list composed of lists,
1919 where each list contains two strings with {chars} and
Bram Moolenaara2baa732022-02-04 16:09:54 +00001920 {digraph} as in |digraph_set()|. *E1216*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00001921 Example: >
1922 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
1923<
1924 It is similar to the following: >
1925 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
1926 call digraph_set(chars, digraph)
1927 endfor
1928< Except that the function returns after the first error,
1929 following digraphs will not be added.
1930
1931 Can be used as a |method|: >
1932 GetList()->digraph_setlist()
1933<
1934 This function works only when compiled with the |+digraphs|
1935 feature. If this feature is disabled, this function will
1936 display an error message.
1937
1938
1939echoraw({string}) *echoraw()*
1940 Output {string} as-is, including unprintable characters.
1941 This can be used to output a terminal code. For example, to
1942 disable modifyOtherKeys: >
1943 call echoraw(&t_TE)
1944< and to enable it again: >
1945 call echoraw(&t_TI)
1946< Use with care, you can mess up the terminal this way.
1947
1948
1949empty({expr}) *empty()*
1950 Return the Number 1 if {expr} is empty, zero otherwise.
1951 - A |List| or |Dictionary| is empty when it does not have any
1952 items.
1953 - A |String| is empty when its length is zero.
1954 - A |Number| and |Float| are empty when their value is zero.
1955 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
1956 - A |Job| is empty when it failed to start.
1957 - A |Channel| is empty when it is closed.
1958 - A |Blob| is empty when its length is zero.
1959
1960 For a long |List| this is much faster than comparing the
1961 length with zero.
1962
1963 Can also be used as a |method|: >
1964 mylist->empty()
1965
1966environ() *environ()*
1967 Return all of environment variables as dictionary. You can
1968 check if an environment variable exists like this: >
1969 :echo has_key(environ(), 'HOME')
1970< Note that the variable name may be CamelCase; to ignore case
1971 use this: >
1972 :echo index(keys(environ()), 'HOME', 0, 1) != -1
1973
1974escape({string}, {chars}) *escape()*
1975 Escape the characters in {chars} that occur in {string} with a
1976 backslash. Example: >
1977 :echo escape('c:\program files\vim', ' \')
1978< results in: >
1979 c:\\program\ files\\vim
1980< Also see |shellescape()| and |fnameescape()|.
1981
1982 Can also be used as a |method|: >
1983 GetText()->escape(' \')
1984<
1985 *eval()*
1986eval({string}) Evaluate {string} and return the result. Especially useful to
1987 turn the result of |string()| back into the original value.
1988 This works for Numbers, Floats, Strings, Blobs and composites
1989 of them. Also works for |Funcref|s that refer to existing
1990 functions.
1991
1992 Can also be used as a |method|: >
1993 argv->join()->eval()
1994
1995eventhandler() *eventhandler()*
1996 Returns 1 when inside an event handler. That is that Vim got
1997 interrupted while waiting for the user to type a character,
1998 e.g., when dropping a file on Vim. This means interactive
1999 commands cannot be used. Otherwise zero is returned.
2000
2001executable({expr}) *executable()*
2002 This function checks if an executable with the name {expr}
2003 exists. {expr} must be the name of the program without any
2004 arguments.
2005 executable() uses the value of $PATH and/or the normal
2006 searchpath for programs. *PATHEXT*
2007 On MS-Windows the ".exe", ".bat", etc. can optionally be
2008 included. Then the extensions in $PATHEXT are tried. Thus if
2009 "foo.exe" does not exist, "foo.exe.bat" can be found. If
2010 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
2011 by itself can be used in $PATHEXT to try using the name
2012 without an extension. When 'shell' looks like a Unix shell,
2013 then the name is also tried without adding an extension.
2014 On MS-Windows it only checks if the file exists and is not a
2015 directory, not if it's really executable.
2016 On MS-Windows an executable in the same directory as Vim is
2017 always found. Since this directory is added to $PATH it
2018 should also work to execute it |win32-PATH|.
2019 The result is a Number:
2020 1 exists
2021 0 does not exist
2022 -1 not implemented on this system
2023 |exepath()| can be used to get the full path of an executable.
2024
2025 Can also be used as a |method|: >
2026 GetCommand()->executable()
2027
2028execute({command} [, {silent}]) *execute()*
2029 Execute an Ex command or commands and return the output as a
2030 string.
2031 {command} can be a string or a List. In case of a List the
2032 lines are executed one by one.
2033 This is equivalent to: >
2034 redir => var
2035 {command}
2036 redir END
2037<
2038 The optional {silent} argument can have these values:
2039 "" no `:silent` used
2040 "silent" `:silent` used
2041 "silent!" `:silent!` used
2042 The default is "silent". Note that with "silent!", unlike
2043 `:redir`, error messages are dropped. When using an external
2044 command the screen may be messed up, use `system()` instead.
2045 *E930*
2046 It is not possible to use `:redir` anywhere in {command}.
2047
2048 To get a list of lines use |split()| on the result: >
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002049 execute('args')->split("\n")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002050
2051< To execute a command in another window than the current one
2052 use `win_execute()`.
2053
2054 When used recursively the output of the recursive call is not
2055 included in the output of the higher level call.
2056
2057 Can also be used as a |method|: >
2058 GetCommand()->execute()
2059
2060exepath({expr}) *exepath()*
2061 If {expr} is an executable and is either an absolute path, a
2062 relative path or found in $PATH, return the full path.
2063 Note that the current directory is used when {expr} starts
2064 with "./", which may be a problem for Vim: >
2065 echo exepath(v:progpath)
2066< If {expr} cannot be found in $PATH or is not executable then
2067 an empty string is returned.
2068
2069 Can also be used as a |method|: >
2070 GetCommand()->exepath()
2071<
2072 *exists()*
2073exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
2074 zero otherwise.
2075
2076 Note: In a compiled |:def| function the evaluation is done at
2077 runtime. Use `exists_compiled()` to evaluate the expression
2078 at compile time.
2079
2080 For checking for a supported feature use |has()|.
2081 For checking if a file exists use |filereadable()|.
2082
2083 The {expr} argument is a string, which contains one of these:
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002084 varname internal variable (see
2085 dict.key |internal-variables|). Also works
2086 list[i] for |curly-braces-names|, |Dictionary|
2087 import.Func entries, |List| items, imported
Bram Moolenaar944697a2022-02-20 19:48:20 +00002088 items, etc.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002089 Does not work for local variables in a
2090 compiled `:def` function.
Bram Moolenaar944697a2022-02-20 19:48:20 +00002091 Also works for a function in |Vim9|
2092 script, since it can be used as a
2093 function reference.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002094 Beware that evaluating an index may
2095 cause an error message for an invalid
2096 expression. E.g.: >
2097 :let l = [1, 2, 3]
2098 :echo exists("l[5]")
2099< 0 >
2100 :echo exists("l[xx]")
2101< E121: Undefined variable: xx
2102 0
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002103 &option-name Vim option (only checks if it exists,
2104 not if it really works)
2105 +option-name Vim option that works.
2106 $ENVNAME environment variable (could also be
2107 done by comparing with an empty
2108 string)
2109 *funcname built-in function (see |functions|)
2110 or user defined function (see
2111 |user-functions|) that is implemented.
2112 Also works for a variable that is a
2113 Funcref.
2114 ?funcname built-in function that could be
2115 implemented; to be used to check if
2116 "funcname" is valid
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002117 :cmdname Ex command: built-in command, user
2118 command or command modifier |:command|.
2119 Returns:
2120 1 for match with start of a command
2121 2 full match with a command
2122 3 matches several user commands
2123 To check for a supported command
2124 always check the return value to be 2.
2125 :2match The |:2match| command.
2126 :3match The |:3match| command.
2127 #event autocommand defined for this event
2128 #event#pattern autocommand defined for this event and
2129 pattern (the pattern is taken
2130 literally and compared to the
2131 autocommand patterns character by
2132 character)
2133 #group autocommand group exists
2134 #group#event autocommand defined for this group and
2135 event.
2136 #group#event#pattern
2137 autocommand defined for this group,
2138 event and pattern.
2139 ##event autocommand for this event is
2140 supported.
2141
2142 Examples: >
2143 exists("&shortname")
2144 exists("$HOSTNAME")
2145 exists("*strftime")
Bram Moolenaar944697a2022-02-20 19:48:20 +00002146 exists("*s:MyFunc") " only for legacy script
2147 exists("*MyFunc")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002148 exists("bufcount")
2149 exists(":Make")
2150 exists("#CursorHold")
2151 exists("#BufReadPre#*.gz")
2152 exists("#filetypeindent")
2153 exists("#filetypeindent#FileType")
2154 exists("#filetypeindent#FileType#*")
2155 exists("##ColorScheme")
2156< There must be no space between the symbol (&/$/*/#) and the
2157 name.
2158 There must be no extra characters after the name, although in
2159 a few cases this is ignored. That may become more strict in
2160 the future, thus don't count on it!
2161 Working example: >
2162 exists(":make")
2163< NOT working example: >
2164 exists(":make install")
2165
2166< Note that the argument must be a string, not the name of the
2167 variable itself. For example: >
2168 exists(bufcount)
2169< This doesn't check for existence of the "bufcount" variable,
2170 but gets the value of "bufcount", and checks if that exists.
2171
2172 Can also be used as a |method|: >
2173 Varname()->exists()
2174<
2175
2176exists_compiled({expr}) *exists_compiled()*
2177 Like `exists()` but evaluated at compile time. This is useful
2178 to skip a block where a function is used that would otherwise
2179 give an error: >
2180 if exists_compiled('*ThatFunction')
2181 ThatFunction('works')
2182 endif
2183< If `exists()` were used then a compilation error would be
2184 given if ThatFunction() is not defined.
2185
2186 {expr} must be a literal string. *E1232*
2187 Can only be used in a |:def| function. *E1233*
2188 This does not work to check for arguments or local variables.
2189
2190
2191exp({expr}) *exp()*
2192 Return the exponential of {expr} as a |Float| in the range
2193 [0, inf].
2194 {expr} must evaluate to a |Float| or a |Number|.
2195 Examples: >
2196 :echo exp(2)
2197< 7.389056 >
2198 :echo exp(-1)
2199< 0.367879
2200
2201 Can also be used as a |method|: >
2202 Compute()->exp()
2203<
2204 {only available when compiled with the |+float| feature}
2205
2206
2207expand({string} [, {nosuf} [, {list}]]) *expand()*
2208 Expand wildcards and the following special keywords in
2209 {string}. 'wildignorecase' applies.
2210
2211 If {list} is given and it is |TRUE|, a List will be returned.
2212 Otherwise the result is a String and when there are several
2213 matches, they are separated by <NL> characters. [Note: in
2214 version 5.0 a space was used, which caused problems when a
2215 file name contains a space]
2216
2217 If the expansion fails, the result is an empty string. A name
2218 for a non-existing file is not included, unless {string} does
2219 not start with '%', '#' or '<', see below.
2220
2221 When {string} starts with '%', '#' or '<', the expansion is
2222 done like for the |cmdline-special| variables with their
2223 associated modifiers. Here is a short overview:
2224
2225 % current file name
2226 # alternate file name
2227 #n alternate file name n
2228 <cfile> file name under the cursor
2229 <afile> autocmd file name
2230 <abuf> autocmd buffer number (as a String!)
2231 <amatch> autocmd matched name
2232 <cexpr> C expression under the cursor
2233 <sfile> sourced script file or function name
2234 <slnum> sourced script line number or function
2235 line number
2236 <sflnum> script file line number, also when in
2237 a function
2238 <SID> "<SNR>123_" where "123" is the
2239 current script ID |<SID>|
Bram Moolenaar75ab5902022-04-18 15:36:40 +01002240 <script> sourced script file, or script file
2241 where the current function was defined
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002242 <stack> call stack
2243 <cword> word under the cursor
2244 <cWORD> WORD under the cursor
2245 <client> the {clientid} of the last received
2246 message |server2client()|
2247 Modifiers:
2248 :p expand to full path
2249 :h head (last path component removed)
2250 :t tail (last path component only)
2251 :r root (one extension removed)
2252 :e extension only
2253
2254 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002255 :let &tags = expand("%:p:h") .. "/tags"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002256< Note that when expanding a string that starts with '%', '#' or
2257 '<', any following text is ignored. This does NOT work: >
2258 :let doesntwork = expand("%:h.bak")
2259< Use this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002260 :let doeswork = expand("%:h") .. ".bak"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002261< Also note that expanding "<cfile>" and others only returns the
2262 referenced file name without further expansion. If "<cfile>"
2263 is "~/.cshrc", you need to do another expand() to have the
2264 "~/" expanded into the path of the home directory: >
2265 :echo expand(expand("<cfile>"))
2266<
2267 There cannot be white space between the variables and the
2268 following modifier. The |fnamemodify()| function can be used
2269 to modify normal file names.
2270
2271 When using '%' or '#', and the current or alternate file name
2272 is not defined, an empty string is used. Using "%:p" in a
2273 buffer with no name, results in the current directory, with a
2274 '/' added.
Bram Moolenaar57544522022-04-12 12:54:11 +01002275 When 'verbose' is set then expanding '%', '#' and <> items
2276 will result in an error message if the argument cannot be
2277 expanded.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002278
2279 When {string} does not start with '%', '#' or '<', it is
2280 expanded like a file name is expanded on the command line.
2281 'suffixes' and 'wildignore' are used, unless the optional
2282 {nosuf} argument is given and it is |TRUE|.
2283 Names for non-existing files are included. The "**" item can
2284 be used to search in a directory tree. For example, to find
2285 all "README" files in the current directory and below: >
2286 :echo expand("**/README")
2287<
2288 expand() can also be used to expand variables and environment
2289 variables that are only known in a shell. But this can be
2290 slow, because a shell may be used to do the expansion. See
2291 |expr-env-expand|.
2292 The expanded variable is still handled like a list of file
2293 names. When an environment variable cannot be expanded, it is
2294 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2295 "$FOOBAR".
2296
2297 See |glob()| for finding existing files. See |system()| for
2298 getting the raw output of an external command.
2299
2300 Can also be used as a |method|: >
2301 Getpattern()->expand()
2302
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002303expandcmd({string} [, {options}]) *expandcmd()*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002304 Expand special items in String {string} like what is done for
2305 an Ex command such as `:edit`. This expands special keywords,
2306 like with |expand()|, and environment variables, anywhere in
2307 {string}. "~user" and "~/path" are only expanded at the
2308 start.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002309
2310 The following items are supported in the {options} Dict
2311 argument:
2312 errmsg If set to TRUE, error messages are displayed
2313 if an error is encountered during expansion.
2314 By default, error messages are not displayed.
2315
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002316 Returns the expanded string. If an error is encountered
2317 during expansion, the unmodified {string} is returned.
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002318
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002319 Example: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002320 :echo expandcmd('make %<.o')
Yegappan Lakshmanan2b74b682022-04-03 21:30:32 +01002321 make /path/runtime/doc/builtin.o
2322 :echo expandcmd('make %<.o', {'errmsg': v:true})
2323<
Yegappan Lakshmanan5018a832022-04-02 21:12:21 +01002324 Can also be used as a |method|: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002325 GetCommand()->expandcmd()
2326<
2327extend({expr1}, {expr2} [, {expr3}]) *extend()*
2328 {expr1} and {expr2} must be both |Lists| or both
2329 |Dictionaries|.
2330
2331 If they are |Lists|: Append {expr2} to {expr1}.
2332 If {expr3} is given insert the items of {expr2} before the
2333 item with index {expr3} in {expr1}. When {expr3} is zero
2334 insert before the first item. When {expr3} is equal to
2335 len({expr1}) then {expr2} is appended.
2336 Examples: >
2337 :echo sort(extend(mylist, [7, 5]))
2338 :call extend(mylist, [2, 3], 1)
2339< When {expr1} is the same List as {expr2} then the number of
2340 items copied is equal to the original length of the List.
2341 E.g., when {expr3} is 1 you get N new copies of the first item
2342 (where N is the original length of the List).
2343 Use |add()| to concatenate one item to a list. To concatenate
2344 two lists into a new list use the + operator: >
2345 :let newlist = [1, 2, 3] + [4, 5]
2346<
2347 If they are |Dictionaries|:
2348 Add all entries from {expr2} to {expr1}.
2349 If a key exists in both {expr1} and {expr2} then {expr3} is
2350 used to decide what to do:
2351 {expr3} = "keep": keep the value of {expr1}
2352 {expr3} = "force": use the value of {expr2}
2353 {expr3} = "error": give an error message *E737*
2354 When {expr3} is omitted then "force" is assumed.
2355
2356 {expr1} is changed when {expr2} is not empty. If necessary
2357 make a copy of {expr1} first.
2358 {expr2} remains unchanged.
2359 When {expr1} is locked and {expr2} is not empty the operation
2360 fails.
2361 Returns {expr1}.
2362
2363 Can also be used as a |method|: >
2364 mylist->extend(otherlist)
2365
2366
2367extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
2368 Like |extend()| but instead of adding items to {expr1} a new
2369 List or Dictionary is created and returned. {expr1} remains
2370 unchanged. Items can still be changed by {expr2}, if you
2371 don't want that use |deepcopy()| first.
2372
2373
2374feedkeys({string} [, {mode}]) *feedkeys()*
2375 Characters in {string} are queued for processing as if they
2376 come from a mapping or were typed by the user.
2377
2378 By default the string is added to the end of the typeahead
2379 buffer, thus if a mapping is still being executed the
2380 characters come after them. Use the 'i' flag to insert before
2381 other characters, they will be executed next, before any
2382 characters from a mapping.
2383
2384 The function does not wait for processing of keys contained in
2385 {string}.
2386
2387 To include special keys into {string}, use double-quotes
2388 and "\..." notation |expr-quote|. For example,
2389 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2390 feedkeys('\<CR>') pushes 5 characters.
2391 A special code that might be useful is <Ignore>, it exits the
2392 wait for a character without doing anything. *<Ignore>*
2393
2394 {mode} is a String, which can contain these character flags:
2395 'm' Remap keys. This is default. If {mode} is absent,
2396 keys are remapped.
2397 'n' Do not remap keys.
2398 't' Handle keys as if typed; otherwise they are handled as
2399 if coming from a mapping. This matters for undo,
2400 opening folds, etc.
2401 'L' Lowlevel input. Only works for Unix or when using the
2402 GUI. Keys are used as if they were coming from the
2403 terminal. Other flags are not used. *E980*
2404 When a CTRL-C interrupts and 't' is included it sets
2405 the internal "got_int" flag.
2406 'i' Insert the string instead of appending (see above).
2407 'x' Execute commands until typeahead is empty. This is
2408 similar to using ":normal!". You can call feedkeys()
2409 several times without 'x' and then one time with 'x'
2410 (possibly with an empty {string}) to execute all the
2411 typeahead. Note that when Vim ends in Insert mode it
2412 will behave as if <Esc> is typed, to avoid getting
2413 stuck, waiting for a character to be typed before the
2414 script continues.
2415 Note that if you manage to call feedkeys() while
2416 executing commands, thus calling it recursively, then
2417 all typeahead will be consumed by the last call.
Bram Moolenaara9725222022-01-16 13:30:33 +00002418 'c' Remove any script context when executing, so that
2419 legacy script syntax applies, "s:var" does not work,
2420 etc.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002421 '!' When used with 'x' will not end Insert mode. Can be
2422 used in a test when a timer is set to exit Insert mode
2423 a little later. Useful for testing CursorHoldI.
2424
2425 Return value is always 0.
2426
2427 Can also be used as a |method|: >
2428 GetInput()->feedkeys()
2429
2430filereadable({file}) *filereadable()*
2431 The result is a Number, which is |TRUE| when a file with the
2432 name {file} exists, and can be read. If {file} doesn't exist,
2433 or is a directory, the result is |FALSE|. {file} is any
2434 expression, which is used as a String.
2435 If you don't care about the file being readable you can use
2436 |glob()|.
2437 {file} is used as-is, you may want to expand wildcards first: >
2438 echo filereadable('~/.vimrc')
2439 0
2440 echo filereadable(expand('~/.vimrc'))
2441 1
2442
2443< Can also be used as a |method|: >
2444 GetName()->filereadable()
2445< *file_readable()*
2446 Obsolete name: file_readable().
2447
2448
2449filewritable({file}) *filewritable()*
2450 The result is a Number, which is 1 when a file with the
2451 name {file} exists, and can be written. If {file} doesn't
2452 exist, or is not writable, the result is 0. If {file} is a
2453 directory, and we can write to it, the result is 2.
2454
2455 Can also be used as a |method|: >
2456 GetName()->filewritable()
2457
2458
2459filter({expr1}, {expr2}) *filter()*
2460 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
2461 For each item in {expr1} evaluate {expr2} and when the result
2462 is zero or false remove the item from the |List| or
2463 |Dictionary|. Similarly for each byte in a |Blob| and each
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002464 character in a |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002465
2466 {expr2} must be a |string| or |Funcref|.
2467
2468 If {expr2} is a |string|, inside {expr2} |v:val| has the value
2469 of the current item. For a |Dictionary| |v:key| has the key
2470 of the current item and for a |List| |v:key| has the index of
2471 the current item. For a |Blob| |v:key| has the index of the
2472 current byte. For a |String| |v:key| has the index of the
2473 current character.
2474 Examples: >
2475 call filter(mylist, 'v:val !~ "OLD"')
2476< Removes the items where "OLD" appears. >
2477 call filter(mydict, 'v:key >= 8')
2478< Removes the items with a key below 8. >
2479 call filter(var, 0)
2480< Removes all the items, thus clears the |List| or |Dictionary|.
2481
2482 Note that {expr2} is the result of expression and is then
2483 used as an expression again. Often it is good to use a
2484 |literal-string| to avoid having to double backslashes.
2485
2486 If {expr2} is a |Funcref| it must take two arguments:
2487 1. the key or the index of the current item.
2488 2. the value of the current item.
2489 The function must return |TRUE| if the item should be kept.
2490 Example that keeps the odd items of a list: >
2491 func Odd(idx, val)
2492 return a:idx % 2 == 1
2493 endfunc
2494 call filter(mylist, function('Odd'))
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002495< It is shorter when using a |lambda|. In |Vim9| syntax: >
2496 call filter(myList, (idx, val) => idx * val <= 42)
2497< In legacy script syntax: >
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002498 call filter(myList, {idx, val -> idx * val <= 42})
2499< If you do not use "val" you can leave it out: >
2500 call filter(myList, {idx -> idx % 2 == 1})
2501<
2502 In |Vim9| script the result must be true, false, zero or one.
2503 Other values will result in a type error.
2504
2505 For a |List| and a |Dictionary| the operation is done
2506 in-place. If you want it to remain unmodified make a copy
2507 first: >
2508 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2509
2510< Returns {expr1}, the |List| or |Dictionary| that was filtered,
naohiro ono56200ee2022-01-01 14:59:44 +00002511 or a new |Blob| or |String|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002512 When an error is encountered while evaluating {expr2} no
2513 further items in {expr1} are processed.
2514 When {expr2} is a Funcref errors inside a function are ignored,
2515 unless it was defined with the "abort" flag.
2516
2517 Can also be used as a |method|: >
2518 mylist->filter(expr2)
2519
2520finddir({name} [, {path} [, {count}]]) *finddir()*
2521 Find directory {name} in {path}. Supports both downwards and
2522 upwards recursive directory searches. See |file-searching|
2523 for the syntax of {path}.
2524
2525 Returns the path of the first found match. When the found
2526 directory is below the current directory a relative path is
2527 returned. Otherwise a full path is returned.
2528 If {path} is omitted or empty then 'path' is used.
2529
2530 If the optional {count} is given, find {count}'s occurrence of
2531 {name} in {path} instead of the first one.
2532 When {count} is negative return all the matches in a |List|.
2533
2534 This is quite similar to the ex-command `:find`.
2535 {only available when compiled with the |+file_in_path|
2536 feature}
2537
2538 Can also be used as a |method|: >
2539 GetName()->finddir()
2540
2541findfile({name} [, {path} [, {count}]]) *findfile()*
2542 Just like |finddir()|, but find a file instead of a directory.
2543 Uses 'suffixesadd'.
2544 Example: >
2545 :echo findfile("tags.vim", ".;")
2546< Searches from the directory of the current file upwards until
2547 it finds the file "tags.vim".
2548
2549 Can also be used as a |method|: >
2550 GetName()->findfile()
2551
2552flatten({list} [, {maxdepth}]) *flatten()*
2553 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
2554 the result is a |List| without nesting, as if {maxdepth} is
2555 a very large number.
2556 The {list} is changed in place, use |flattennew()| if you do
2557 not want that.
2558 In Vim9 script flatten() cannot be used, you must always use
Bram Moolenaara2baa732022-02-04 16:09:54 +00002559 |flattennew()|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002560 *E900*
2561 {maxdepth} means how deep in nested lists changes are made.
2562 {list} is not modified when {maxdepth} is 0.
2563 {maxdepth} must be positive number.
2564
2565 If there is an error the number zero is returned.
2566
2567 Example: >
2568 :echo flatten([1, [2, [3, 4]], 5])
2569< [1, 2, 3, 4, 5] >
2570 :echo flatten([1, [2, [3, 4]], 5], 1)
2571< [1, 2, [3, 4], 5]
2572
2573 Can also be used as a |method|: >
2574 mylist->flatten()
2575<
2576flattennew({list} [, {maxdepth}]) *flattennew()*
2577 Like |flatten()| but first make a copy of {list}.
2578
2579
2580float2nr({expr}) *float2nr()*
2581 Convert {expr} to a Number by omitting the part after the
2582 decimal point.
2583 {expr} must evaluate to a |Float| or a Number.
2584 When the value of {expr} is out of range for a |Number| the
2585 result is truncated to 0x7fffffff or -0x7fffffff (or when
2586 64-bit Number support is enabled, 0x7fffffffffffffff or
2587 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
2588 64-bit Number support is enabled, -0x8000000000000000).
2589 Examples: >
2590 echo float2nr(3.95)
2591< 3 >
2592 echo float2nr(-23.45)
2593< -23 >
2594 echo float2nr(1.0e100)
2595< 2147483647 (or 9223372036854775807) >
2596 echo float2nr(-1.0e150)
2597< -2147483647 (or -9223372036854775807) >
2598 echo float2nr(1.0e-100)
2599< 0
2600
2601 Can also be used as a |method|: >
2602 Compute()->float2nr()
2603<
2604 {only available when compiled with the |+float| feature}
2605
2606
2607floor({expr}) *floor()*
2608 Return the largest integral value less than or equal to
2609 {expr} as a |Float| (round down).
2610 {expr} must evaluate to a |Float| or a |Number|.
2611 Examples: >
2612 echo floor(1.856)
2613< 1.0 >
2614 echo floor(-5.456)
2615< -6.0 >
2616 echo floor(4.0)
2617< 4.0
2618
2619 Can also be used as a |method|: >
2620 Compute()->floor()
2621<
2622 {only available when compiled with the |+float| feature}
2623
2624
2625fmod({expr1}, {expr2}) *fmod()*
2626 Return the remainder of {expr1} / {expr2}, even if the
2627 division is not representable. Returns {expr1} - i * {expr2}
2628 for some integer i such that if {expr2} is non-zero, the
2629 result has the same sign as {expr1} and magnitude less than
2630 the magnitude of {expr2}. If {expr2} is zero, the value
2631 returned is zero. The value returned is a |Float|.
2632 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
2633 Examples: >
2634 :echo fmod(12.33, 1.22)
2635< 0.13 >
2636 :echo fmod(-12.33, 1.22)
2637< -0.13
2638
2639 Can also be used as a |method|: >
2640 Compute()->fmod(1.22)
2641<
2642 {only available when compiled with |+float| feature}
2643
2644
2645fnameescape({string}) *fnameescape()*
2646 Escape {string} for use as file name command argument. All
2647 characters that have a special meaning, such as '%' and '|'
2648 are escaped with a backslash.
2649 For most systems the characters escaped are
2650 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2651 appears in a filename, it depends on the value of 'isfname'.
2652 A leading '+' and '>' is also escaped (special after |:edit|
2653 and |:write|). And a "-" by itself (special after |:cd|).
2654 Example: >
2655 :let fname = '+some str%nge|name'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002656 :exe "edit " .. fnameescape(fname)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002657< results in executing: >
2658 edit \+some\ str\%nge\|name
2659<
2660 Can also be used as a |method|: >
2661 GetName()->fnameescape()
2662
2663fnamemodify({fname}, {mods}) *fnamemodify()*
2664 Modify file name {fname} according to {mods}. {mods} is a
2665 string of characters like it is used for file names on the
2666 command line. See |filename-modifiers|.
2667 Example: >
2668 :echo fnamemodify("main.c", ":p:h")
2669< results in: >
2670 /home/mool/vim/vim/src
2671< If {mods} is empty then {fname} is returned.
2672 Note: Environment variables don't work in {fname}, use
2673 |expand()| first then.
2674
2675 Can also be used as a |method|: >
2676 GetName()->fnamemodify(':p:h')
2677
2678foldclosed({lnum}) *foldclosed()*
2679 The result is a Number. If the line {lnum} is in a closed
2680 fold, the result is the number of the first line in that fold.
2681 If the line {lnum} is not in a closed fold, -1 is returned.
2682 {lnum} is used like with |getline()|. Thus "." is the current
2683 line, "'m" mark m, etc.
2684
2685 Can also be used as a |method|: >
2686 GetLnum()->foldclosed()
2687
2688foldclosedend({lnum}) *foldclosedend()*
2689 The result is a Number. If the line {lnum} is in a closed
2690 fold, the result is the number of the last line in that fold.
2691 If the line {lnum} is not in a closed fold, -1 is returned.
2692 {lnum} is used like with |getline()|. Thus "." is the current
2693 line, "'m" mark m, etc.
2694
2695 Can also be used as a |method|: >
2696 GetLnum()->foldclosedend()
2697
2698foldlevel({lnum}) *foldlevel()*
2699 The result is a Number, which is the foldlevel of line {lnum}
2700 in the current buffer. For nested folds the deepest level is
2701 returned. If there is no fold at line {lnum}, zero is
2702 returned. It doesn't matter if the folds are open or closed.
2703 When used while updating folds (from 'foldexpr') -1 is
2704 returned for lines where folds are still to be updated and the
2705 foldlevel is unknown. As a special case the level of the
2706 previous line is usually available.
2707 {lnum} is used like with |getline()|. Thus "." is the current
2708 line, "'m" mark m, etc.
2709
2710 Can also be used as a |method|: >
2711 GetLnum()->foldlevel()
2712<
2713 *foldtext()*
2714foldtext() Returns a String, to be displayed for a closed fold. This is
2715 the default function used for the 'foldtext' option and should
2716 only be called from evaluating 'foldtext'. It uses the
2717 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2718 The returned string looks like this: >
2719 +-- 45 lines: abcdef
2720< The number of leading dashes depends on the foldlevel. The
2721 "45" is the number of lines in the fold. "abcdef" is the text
2722 in the first non-blank line of the fold. Leading white space,
2723 "//" or "/*" and the text from the 'foldmarker' and
2724 'commentstring' options is removed.
2725 When used to draw the actual foldtext, the rest of the line
2726 will be filled with the fold char from the 'fillchars'
2727 setting.
2728 {not available when compiled without the |+folding| feature}
2729
2730foldtextresult({lnum}) *foldtextresult()*
2731 Returns the text that is displayed for the closed fold at line
2732 {lnum}. Evaluates 'foldtext' in the appropriate context.
2733 When there is no closed fold at {lnum} an empty string is
2734 returned.
2735 {lnum} is used like with |getline()|. Thus "." is the current
2736 line, "'m" mark m, etc.
2737 Useful when exporting folded text, e.g., to HTML.
2738 {not available when compiled without the |+folding| feature}
2739
2740
2741 Can also be used as a |method|: >
2742 GetLnum()->foldtextresult()
2743<
2744 *foreground()*
2745foreground() Move the Vim window to the foreground. Useful when sent from
2746 a client to a Vim server. |remote_send()|
2747 On Win32 systems this might not work, the OS does not always
2748 allow a window to bring itself to the foreground. Use
2749 |remote_foreground()| instead.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002750 {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002751 Win32 console version}
2752
2753fullcommand({name}) *fullcommand()*
2754 Get the full command name from a short abbreviated command
2755 name; see |20.2| for details on command abbreviations.
2756
2757 The string argument {name} may start with a `:` and can
2758 include a [range], these are skipped and not returned.
2759 Returns an empty string if a command doesn't exist or if it's
2760 ambiguous (for user-defined commands).
2761
2762 For example `fullcommand('s')`, `fullcommand('sub')`,
2763 `fullcommand(':%substitute')` all return "substitute".
2764
2765 Can also be used as a |method|: >
2766 GetName()->fullcommand()
2767<
2768 *funcref()*
2769funcref({name} [, {arglist}] [, {dict}])
2770 Just like |function()|, but the returned Funcref will lookup
2771 the function by reference, not by name. This matters when the
2772 function {name} is redefined later.
2773
2774 Unlike |function()|, {name} must be an existing user function.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002775 It only works for an autoloaded function if it has already
2776 been loaded (to avoid mistakenly loading the autoload script
2777 when only intending to use the function name, use |function()|
2778 instead). {name} cannot be a builtin function.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002779
2780 Can also be used as a |method|: >
2781 GetFuncname()->funcref([arg])
2782<
2783 *function()* *partial* *E700* *E922* *E923*
2784function({name} [, {arglist}] [, {dict}])
2785 Return a |Funcref| variable that refers to function {name}.
2786 {name} can be the name of a user defined function or an
2787 internal function.
2788
2789 {name} can also be a Funcref or a partial. When it is a
2790 partial the dict stored in it will be used and the {dict}
2791 argument is not allowed. E.g.: >
2792 let FuncWithArg = function(dict.Func, [arg])
2793 let Broken = function(dict.Func, [arg], dict)
2794<
2795 When using the Funcref the function will be found by {name},
2796 also when it was redefined later. Use |funcref()| to keep the
2797 same function.
2798
2799 When {arglist} or {dict} is present this creates a partial.
2800 That means the argument list and/or the dictionary is stored in
2801 the Funcref and will be used when the Funcref is called.
2802
2803 The arguments are passed to the function in front of other
2804 arguments, but after any argument from |method|. Example: >
2805 func Callback(arg1, arg2, name)
2806 ...
2807 let Partial = function('Callback', ['one', 'two'])
2808 ...
2809 call Partial('name')
2810< Invokes the function as with: >
2811 call Callback('one', 'two', 'name')
2812
2813< With a |method|: >
2814 func Callback(one, two, three)
2815 ...
2816 let Partial = function('Callback', ['two'])
2817 ...
2818 eval 'one'->Partial('three')
2819< Invokes the function as with: >
2820 call Callback('one', 'two', 'three')
2821
2822< The function() call can be nested to add more arguments to the
2823 Funcref. The extra arguments are appended to the list of
2824 arguments. Example: >
2825 func Callback(arg1, arg2, name)
2826 ...
2827 let Func = function('Callback', ['one'])
2828 let Func2 = function(Func, ['two'])
2829 ...
2830 call Func2('name')
2831< Invokes the function as with: >
2832 call Callback('one', 'two', 'name')
2833
2834< The Dictionary is only useful when calling a "dict" function.
2835 In that case the {dict} is passed in as "self". Example: >
2836 function Callback() dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002837 echo "called for " .. self.name
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002838 endfunction
2839 ...
2840 let context = {"name": "example"}
2841 let Func = function('Callback', context)
2842 ...
2843 call Func() " will echo: called for example
2844< The use of function() is not needed when there are no extra
2845 arguments, these two are equivalent: >
2846 let Func = function('Callback', context)
2847 let Func = context.Callback
2848
2849< The argument list and the Dictionary can be combined: >
2850 function Callback(arg1, count) dict
2851 ...
2852 let context = {"name": "example"}
2853 let Func = function('Callback', ['one'], context)
2854 ...
2855 call Func(500)
2856< Invokes the function as with: >
2857 call context.Callback('one', 500)
2858<
2859 Can also be used as a |method|: >
2860 GetFuncname()->function([arg])
2861
2862
2863garbagecollect([{atexit}]) *garbagecollect()*
2864 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
2865 that have circular references.
2866
2867 There is hardly ever a need to invoke this function, as it is
2868 automatically done when Vim runs out of memory or is waiting
2869 for the user to press a key after 'updatetime'. Items without
2870 circular references are always freed when they become unused.
2871 This is useful if you have deleted a very big |List| and/or
2872 |Dictionary| with circular references in a script that runs
2873 for a long time.
2874
2875 When the optional {atexit} argument is one, garbage
2876 collection will also be done when exiting Vim, if it wasn't
2877 done before. This is useful when checking for memory leaks.
2878
2879 The garbage collection is not done immediately but only when
2880 it's safe to perform. This is when waiting for the user to
2881 type a character. To force garbage collection immediately use
2882 |test_garbagecollect_now()|.
2883
2884get({list}, {idx} [, {default}]) *get()*
2885 Get item {idx} from |List| {list}. When this item is not
2886 available return {default}. Return zero when {default} is
2887 omitted.
2888 Preferably used as a |method|: >
2889 mylist->get(idx)
2890get({blob}, {idx} [, {default}])
2891 Get byte {idx} from |Blob| {blob}. When this byte is not
2892 available return {default}. Return -1 when {default} is
2893 omitted.
2894 Preferably used as a |method|: >
2895 myblob->get(idx)
2896get({dict}, {key} [, {default}])
2897 Get item with key {key} from |Dictionary| {dict}. When this
2898 item is not available return {default}. Return zero when
2899 {default} is omitted. Useful example: >
2900 let val = get(g:, 'var_name', 'default')
2901< This gets the value of g:var_name if it exists, and uses
2902 'default' when it does not exist.
2903 Preferably used as a |method|: >
2904 mydict->get(key)
2905get({func}, {what})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00002906 Get item {what} from Funcref {func}. Possible values for
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002907 {what} are:
2908 "name" The function name
2909 "func" The function
2910 "dict" The dictionary
2911 "args" The list with arguments
2912 Preferably used as a |method|: >
2913 myfunc->get(what)
2914<
2915 *getbufinfo()*
2916getbufinfo([{buf}])
2917getbufinfo([{dict}])
2918 Get information about buffers as a List of Dictionaries.
2919
2920 Without an argument information about all the buffers is
2921 returned.
2922
2923 When the argument is a |Dictionary| only the buffers matching
2924 the specified criteria are returned. The following keys can
2925 be specified in {dict}:
2926 buflisted include only listed buffers.
2927 bufloaded include only loaded buffers.
2928 bufmodified include only modified buffers.
2929
2930 Otherwise, {buf} specifies a particular buffer to return
2931 information for. For the use of {buf}, see |bufname()|
2932 above. If the buffer is found the returned List has one item.
2933 Otherwise the result is an empty list.
2934
2935 Each returned List item is a dictionary with the following
2936 entries:
2937 bufnr Buffer number.
2938 changed TRUE if the buffer is modified.
2939 changedtick Number of changes made to the buffer.
2940 hidden TRUE if the buffer is hidden.
2941 lastused Timestamp in seconds, like
2942 |localtime()|, when the buffer was
2943 last used.
2944 {only with the |+viminfo| feature}
2945 listed TRUE if the buffer is listed.
2946 lnum Line number used for the buffer when
2947 opened in the current window.
2948 Only valid if the buffer has been
2949 displayed in the window in the past.
2950 If you want the line number of the
2951 last known cursor position in a given
2952 window, use |line()|: >
2953 :echo line('.', {winid})
2954<
2955 linecount Number of lines in the buffer (only
2956 valid when loaded)
2957 loaded TRUE if the buffer is loaded.
2958 name Full path to the file in the buffer.
2959 signs List of signs placed in the buffer.
2960 Each list item is a dictionary with
2961 the following fields:
2962 id sign identifier
2963 lnum line number
2964 name sign name
2965 variables A reference to the dictionary with
2966 buffer-local variables.
2967 windows List of |window-ID|s that display this
2968 buffer
2969 popups List of popup |window-ID|s that
2970 display this buffer
2971
2972 Examples: >
2973 for buf in getbufinfo()
2974 echo buf.name
2975 endfor
2976 for buf in getbufinfo({'buflisted':1})
2977 if buf.changed
2978 ....
2979 endif
2980 endfor
2981<
2982 To get buffer-local options use: >
2983 getbufvar({bufnr}, '&option_name')
2984<
2985 Can also be used as a |method|: >
2986 GetBufnr()->getbufinfo()
2987<
2988
2989 *getbufline()*
2990getbufline({buf}, {lnum} [, {end}])
2991 Return a |List| with the lines starting from {lnum} to {end}
2992 (inclusive) in the buffer {buf}. If {end} is omitted, a
2993 |List| with only the line {lnum} is returned.
2994
2995 For the use of {buf}, see |bufname()| above.
2996
2997 For {lnum} and {end} "$" can be used for the last line of the
2998 buffer. Otherwise a number must be used.
2999
3000 When {lnum} is smaller than 1 or bigger than the number of
3001 lines in the buffer, an empty |List| is returned.
3002
3003 When {end} is greater than the number of lines in the buffer,
3004 it is treated as {end} is set to the number of lines in the
3005 buffer. When {end} is before {lnum} an empty |List| is
3006 returned.
3007
3008 This function works only for loaded buffers. For unloaded and
3009 non-existing buffers, an empty |List| is returned.
3010
3011 Example: >
3012 :let lines = getbufline(bufnr("myfile"), 1, "$")
3013
3014< Can also be used as a |method|: >
3015 GetBufnr()->getbufline(lnum)
3016
3017getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
3018 The result is the value of option or local buffer variable
3019 {varname} in buffer {buf}. Note that the name without "b:"
3020 must be used.
3021 The {varname} argument is a string.
3022 When {varname} is empty returns a |Dictionary| with all the
3023 buffer-local variables.
3024 When {varname} is equal to "&" returns a |Dictionary| with all
3025 the buffer-local options.
3026 Otherwise, when {varname} starts with "&" returns the value of
3027 a buffer-local option.
3028 This also works for a global or buffer-local option, but it
3029 doesn't work for a global variable, window-local variable or
3030 window-local option.
3031 For the use of {buf}, see |bufname()| above.
3032 When the buffer or variable doesn't exist {def} or an empty
3033 string is returned, there is no error message.
3034 Examples: >
3035 :let bufmodified = getbufvar(1, "&mod")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003036 :echo "todo myvar = " .. getbufvar("todo", "myvar")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003037
3038< Can also be used as a |method|: >
3039 GetBufnr()->getbufvar(varname)
3040<
3041getchangelist([{buf}]) *getchangelist()*
3042 Returns the |changelist| for the buffer {buf}. For the use
3043 of {buf}, see |bufname()| above. If buffer {buf} doesn't
3044 exist, an empty list is returned.
3045
3046 The returned list contains two entries: a list with the change
3047 locations and the current position in the list. Each
3048 entry in the change list is a dictionary with the following
3049 entries:
3050 col column number
3051 coladd column offset for 'virtualedit'
3052 lnum line number
3053 If buffer {buf} is the current buffer, then the current
3054 position refers to the position in the list. For other
3055 buffers, it is set to the length of the list.
3056
3057 Can also be used as a |method|: >
3058 GetBufnr()->getchangelist()
3059
3060getchar([expr]) *getchar()*
3061 Get a single character from the user or input stream.
3062 If [expr] is omitted, wait until a character is available.
3063 If [expr] is 0, only get a character when one is available.
3064 Return zero otherwise.
3065 If [expr] is 1, only check if a character is available, it is
3066 not consumed. Return zero if no character available.
3067 If you prefer always getting a string use |getcharstr()|.
3068
3069 Without [expr] and when [expr] is 0 a whole character or
3070 special key is returned. If it is a single character, the
3071 result is a number. Use nr2char() to convert it to a String.
3072 Otherwise a String is returned with the encoded character.
3073 For a special key it's a String with a sequence of bytes
3074 starting with 0x80 (decimal: 128). This is the same value as
3075 the String "\<Key>", e.g., "\<Left>". The returned value is
3076 also a String when a modifier (shift, control, alt) was used
3077 that is not included in the character.
3078
3079 When [expr] is 0 and Esc is typed, there will be a short delay
3080 while Vim waits to see if this is the start of an escape
3081 sequence.
3082
3083 When [expr] is 1 only the first byte is returned. For a
3084 one-byte character it is the character itself as a number.
3085 Use nr2char() to convert it to a String.
3086
3087 Use getcharmod() to obtain any additional modifiers.
3088
3089 When the user clicks a mouse button, the mouse event will be
3090 returned. The position can then be found in |v:mouse_col|,
3091 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
3092 |getmousepos()| can also be used. Mouse move events will be
3093 ignored.
3094 This example positions the mouse as it would normally happen: >
3095 let c = getchar()
3096 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003097 exe v:mouse_win .. "wincmd w"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003098 exe v:mouse_lnum
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003099 exe "normal " .. v:mouse_col .. "|"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003100 endif
3101<
3102 When using bracketed paste only the first character is
3103 returned, the rest of the pasted text is dropped.
3104 |xterm-bracketed-paste|.
3105
3106 There is no prompt, you will somehow have to make clear to the
3107 user that a character has to be typed. The screen is not
3108 redrawn, e.g. when resizing the window. When using a popup
3109 window it should work better with a |popup-filter|.
3110
3111 There is no mapping for the character.
3112 Key codes are replaced, thus when the user presses the <Del>
3113 key you get the code for the <Del> key, not the raw character
3114 sequence. Examples: >
3115 getchar() == "\<Del>"
3116 getchar() == "\<S-Left>"
3117< This example redefines "f" to ignore case: >
3118 :nmap f :call FindChar()<CR>
3119 :function FindChar()
3120 : let c = nr2char(getchar())
3121 : while col('.') < col('$') - 1
3122 : normal l
3123 : if getline('.')[col('.') - 1] ==? c
3124 : break
3125 : endif
3126 : endwhile
3127 :endfunction
3128<
3129 You may also receive synthetic characters, such as
3130 |<CursorHold>|. Often you will want to ignore this and get
3131 another character: >
3132 :function GetKey()
3133 : let c = getchar()
3134 : while c == "\<CursorHold>"
3135 : let c = getchar()
3136 : endwhile
3137 : return c
3138 :endfunction
3139
3140getcharmod() *getcharmod()*
3141 The result is a Number which is the state of the modifiers for
3142 the last obtained character with getchar() or in another way.
3143 These values are added together:
3144 2 shift
3145 4 control
3146 8 alt (meta)
3147 16 meta (when it's different from ALT)
3148 32 mouse double click
3149 64 mouse triple click
3150 96 mouse quadruple click (== 32 + 64)
3151 128 command (Macintosh only)
3152 Only the modifiers that have not been included in the
3153 character itself are obtained. Thus Shift-a results in "A"
3154 without a modifier.
3155
3156 *getcharpos()*
3157getcharpos({expr})
3158 Get the position for String {expr}. Same as |getpos()| but the
3159 column number in the returned List is a character index
3160 instead of a byte index.
naohiro ono56200ee2022-01-01 14:59:44 +00003161 If |getpos()| returns a very large column number, equal to
3162 |v:maxcol|, then getcharpos() will return the character index
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003163 of the last character.
3164
3165 Example:
3166 With the cursor on '세' in line 5 with text "여보세요": >
3167 getcharpos('.') returns [0, 5, 3, 0]
3168 getpos('.') returns [0, 5, 7, 0]
3169<
3170 Can also be used as a |method|: >
3171 GetMark()->getcharpos()
3172
3173getcharsearch() *getcharsearch()*
3174 Return the current character search information as a {dict}
3175 with the following entries:
3176
3177 char character previously used for a character
3178 search (|t|, |f|, |T|, or |F|); empty string
3179 if no character search has been performed
3180 forward direction of character search; 1 for forward,
3181 0 for backward
3182 until type of character search; 1 for a |t| or |T|
3183 character search, 0 for an |f| or |F|
3184 character search
3185
3186 This can be useful to always have |;| and |,| search
3187 forward/backward regardless of the direction of the previous
3188 character search: >
3189 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3190 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3191< Also see |setcharsearch()|.
3192
3193
3194getcharstr([expr]) *getcharstr()*
3195 Get a single character from the user or input stream as a
3196 string.
3197 If [expr] is omitted, wait until a character is available.
3198 If [expr] is 0 or false, only get a character when one is
3199 available. Return an empty string otherwise.
3200 If [expr] is 1 or true, only check if a character is
3201 available, it is not consumed. Return an empty string
3202 if no character is available.
3203 Otherwise this works like |getchar()|, except that a number
3204 result is converted to a string.
3205
3206
3207getcmdline() *getcmdline()*
3208 Return the current command-line. Only works when the command
3209 line is being edited, thus requires use of |c_CTRL-\_e| or
3210 |c_CTRL-R_=|.
3211 Example: >
3212 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3213< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3214 Returns an empty string when entering a password or using
3215 |inputsecret()|.
3216
3217getcmdpos() *getcmdpos()*
3218 Return the position of the cursor in the command line as a
3219 byte count. The first column is 1.
3220 Only works when editing the command line, thus requires use of
3221 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3222 Returns 0 otherwise.
3223 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3224
3225getcmdtype() *getcmdtype()*
3226 Return the current command-line type. Possible return values
3227 are:
3228 : normal Ex command
3229 > debug mode command |debug-mode|
3230 / forward search command
3231 ? backward search command
3232 @ |input()| command
3233 - |:insert| or |:append| command
3234 = |i_CTRL-R_=|
3235 Only works when editing the command line, thus requires use of
3236 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3237 Returns an empty string otherwise.
3238 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3239
3240getcmdwintype() *getcmdwintype()*
3241 Return the current |command-line-window| type. Possible return
3242 values are the same as |getcmdtype()|. Returns an empty string
3243 when not in the command-line window.
3244
3245getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
3246 Return a list of command-line completion matches. The String
3247 {type} argument specifies what for. The following completion
3248 types are supported:
3249
3250 arglist file names in argument list
3251 augroup autocmd groups
3252 buffer buffer names
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003253 behave |:behave| suboptions
3254 breakpoint |:breakadd| and |:breakdel| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003255 color color schemes
3256 command Ex command
3257 cmdline |cmdline-completion| result
3258 compiler compilers
3259 cscope |:cscope| suboptions
3260 diff_buffer |:diffget| and |:diffput| completion
3261 dir directory names
3262 environment environment variable names
3263 event autocommand events
3264 expression Vim expression
3265 file file and directory names
3266 file_in_path file and directory names in |'path'|
3267 filetype filetype names |'filetype'|
3268 function function name
3269 help help subjects
3270 highlight highlight groups
Bram Moolenaar6e2e2cc2022-03-14 19:24:46 +00003271 history |:history| suboptions
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003272 locale locale names (as output of locale -a)
3273 mapclear buffer argument
3274 mapping mapping name
3275 menu menus
3276 messages |:messages| suboptions
3277 option options
3278 packadd optional package |pack-add| names
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003279 scriptnames sourced script names |:scriptnames|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003280 shellcmd Shell command
3281 sign |:sign| suboptions
3282 syntax syntax file names |'syntax'|
3283 syntime |:syntime| suboptions
3284 tag tags
3285 tag_listfiles tags, file names
3286 user user names
3287 var user variables
3288
3289 If {pat} is an empty string, then all the matches are
3290 returned. Otherwise only items matching {pat} are returned.
3291 See |wildcards| for the use of special characters in {pat}.
3292
3293 If the optional {filtered} flag is set to 1, then 'wildignore'
3294 is applied to filter the results. Otherwise all the matches
3295 are returned. The 'wildignorecase' option always applies.
3296
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003297 If the 'wildoptions' option contains 'fuzzy', then fuzzy
3298 matching is used to get the completion matches. Otherwise
Yegappan Lakshmanan454ce672022-03-24 11:22:13 +00003299 regular expression matching is used. Thus this function
3300 follows the user preference, what happens on the command line.
3301 If you do not want this you can make 'wildoptions' empty
3302 before calling getcompletion() and restore it afterwards.
Yegappan Lakshmanane7dd0fa2022-03-22 16:06:31 +00003303
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003304 If {type} is "cmdline", then the |cmdline-completion| result is
3305 returned. For example, to complete the possible values after
3306 a ":call" command: >
3307 echo getcompletion('call ', 'cmdline')
3308<
3309 If there are no matches, an empty list is returned. An
3310 invalid value for {type} produces an error.
3311
3312 Can also be used as a |method|: >
3313 GetPattern()->getcompletion('color')
3314<
3315 *getcurpos()*
3316getcurpos([{winid}])
3317 Get the position of the cursor. This is like getpos('.'), but
3318 includes an extra "curswant" item in the list:
3319 [0, lnum, col, off, curswant] ~
3320 The "curswant" number is the preferred column when moving the
naohiro ono56200ee2022-01-01 14:59:44 +00003321 cursor vertically. After |$| command it will be a very large
3322 number equal to |v:maxcol|. Also see |getcursorcharpos()| and
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003323 |getpos()|.
3324 The first "bufnum" item is always zero. The byte position of
3325 the cursor is returned in 'col'. To get the character
3326 position, use |getcursorcharpos()|.
3327
3328 The optional {winid} argument can specify the window. It can
3329 be the window number or the |window-ID|. The last known
3330 cursor position is returned, this may be invalid for the
3331 current value of the buffer if it is not the current window.
3332 If {winid} is invalid a list with zeroes is returned.
3333
3334 This can be used to save and restore the cursor position: >
3335 let save_cursor = getcurpos()
3336 MoveTheCursorAround
3337 call setpos('.', save_cursor)
3338< Note that this only works within the window. See
3339 |winrestview()| for restoring more state.
3340
3341 Can also be used as a |method|: >
3342 GetWinid()->getcurpos()
3343<
3344 *getcursorcharpos()*
3345getcursorcharpos([{winid}])
3346 Same as |getcurpos()| but the column number in the returned
3347 List is a character index instead of a byte index.
3348
3349 Example:
3350 With the cursor on '보' in line 3 with text "여보세요": >
3351 getcursorcharpos() returns [0, 3, 2, 0, 3]
3352 getcurpos() returns [0, 3, 4, 0, 3]
3353<
3354 Can also be used as a |method|: >
3355 GetWinid()->getcursorcharpos()
3356
3357< *getcwd()*
3358getcwd([{winnr} [, {tabnr}]])
3359 The result is a String, which is the name of the current
3360 working directory. 'autochdir' is ignored.
3361
3362 With {winnr} return the local current directory of this window
3363 in the current tab page. {winnr} can be the window number or
3364 the |window-ID|.
3365 If {winnr} is -1 return the name of the global working
3366 directory. See also |haslocaldir()|.
3367
3368 With {winnr} and {tabnr} return the local current directory of
3369 the window in the specified tab page. If {winnr} is -1 return
3370 the working directory of the tabpage.
3371 If {winnr} is zero use the current window, if {tabnr} is zero
3372 use the current tabpage.
3373 Without any arguments, return the actual working directory of
3374 the current window.
3375 Return an empty string if the arguments are invalid.
3376
3377 Examples: >
3378 " Get the working directory of the current window
3379 :echo getcwd()
3380 :echo getcwd(0)
3381 :echo getcwd(0, 0)
3382 " Get the working directory of window 3 in tabpage 2
3383 :echo getcwd(3, 2)
3384 " Get the global working directory
3385 :echo getcwd(-1)
3386 " Get the working directory of tabpage 3
3387 :echo getcwd(-1, 3)
3388 " Get the working directory of current tabpage
3389 :echo getcwd(-1, 0)
3390
3391< Can also be used as a |method|: >
3392 GetWinnr()->getcwd()
3393
3394getenv({name}) *getenv()*
3395 Return the value of environment variable {name}. The {name}
3396 argument is a string, without a leading '$'. Example: >
3397 myHome = getenv('HOME')
3398
3399< When the variable does not exist |v:null| is returned. That
3400 is different from a variable set to an empty string, although
3401 some systems interpret the empty value as the variable being
3402 deleted. See also |expr-env|.
3403
3404 Can also be used as a |method|: >
3405 GetVarname()->getenv()
3406
3407getfontname([{name}]) *getfontname()*
3408 Without an argument returns the name of the normal font being
3409 used. Like what is used for the Normal highlight group
3410 |hl-Normal|.
3411 With an argument a check is done whether String {name} is a
3412 valid font name. If not then an empty string is returned.
3413 Otherwise the actual font name is returned, or {name} if the
3414 GUI does not support obtaining the real name.
3415 Only works when the GUI is running, thus not in your vimrc or
3416 gvimrc file. Use the |GUIEnter| autocommand to use this
3417 function just after the GUI has started.
3418 Note that the GTK GUI accepts any font name, thus checking for
3419 a valid name does not work.
3420
3421getfperm({fname}) *getfperm()*
3422 The result is a String, which is the read, write, and execute
3423 permissions of the given file {fname}.
3424 If {fname} does not exist or its directory cannot be read, an
3425 empty string is returned.
3426 The result is of the form "rwxrwxrwx", where each group of
3427 "rwx" flags represent, in turn, the permissions of the owner
3428 of the file, the group the file belongs to, and other users.
3429 If a user does not have a given permission the flag for this
3430 is replaced with the string "-". Examples: >
3431 :echo getfperm("/etc/passwd")
3432 :echo getfperm(expand("~/.vimrc"))
3433< This will hopefully (from a security point of view) display
3434 the string "rw-r--r--" or even "rw-------".
3435
3436 Can also be used as a |method|: >
3437 GetFilename()->getfperm()
3438<
3439 For setting permissions use |setfperm()|.
3440
3441getfsize({fname}) *getfsize()*
3442 The result is a Number, which is the size in bytes of the
3443 given file {fname}.
3444 If {fname} is a directory, 0 is returned.
3445 If the file {fname} can't be found, -1 is returned.
3446 If the size of {fname} is too big to fit in a Number then -2
3447 is returned.
3448
3449 Can also be used as a |method|: >
3450 GetFilename()->getfsize()
3451
3452getftime({fname}) *getftime()*
3453 The result is a Number, which is the last modification time of
3454 the given file {fname}. The value is measured as seconds
3455 since 1st Jan 1970, and may be passed to strftime(). See also
3456 |localtime()| and |strftime()|.
3457 If the file {fname} can't be found -1 is returned.
3458
3459 Can also be used as a |method|: >
3460 GetFilename()->getftime()
3461
3462getftype({fname}) *getftype()*
3463 The result is a String, which is a description of the kind of
3464 file of the given file {fname}.
3465 If {fname} does not exist an empty string is returned.
3466 Here is a table over different kinds of files and their
3467 results:
3468 Normal file "file"
3469 Directory "dir"
3470 Symbolic link "link"
3471 Block device "bdev"
3472 Character device "cdev"
3473 Socket "socket"
3474 FIFO "fifo"
3475 All other "other"
3476 Example: >
3477 getftype("/home")
3478< Note that a type such as "link" will only be returned on
3479 systems that support it. On some systems only "dir" and
3480 "file" are returned. On MS-Windows a symbolic link to a
3481 directory returns "dir" instead of "link".
3482
3483 Can also be used as a |method|: >
3484 GetFilename()->getftype()
3485
3486getimstatus() *getimstatus()*
3487 The result is a Number, which is |TRUE| when the IME status is
3488 active.
3489 See 'imstatusfunc'.
3490
3491getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
3492 Returns the |jumplist| for the specified window.
3493
3494 Without arguments use the current window.
3495 With {winnr} only use this window in the current tab page.
3496 {winnr} can also be a |window-ID|.
3497 With {winnr} and {tabnr} use the window in the specified tab
3498 page.
3499
3500 The returned list contains two entries: a list with the jump
3501 locations and the last used jump position number in the list.
3502 Each entry in the jump location list is a dictionary with
3503 the following entries:
3504 bufnr buffer number
3505 col column number
3506 coladd column offset for 'virtualedit'
3507 filename filename if available
3508 lnum line number
3509
3510 Can also be used as a |method|: >
3511 GetWinnr()->getjumplist()
3512
3513< *getline()*
3514getline({lnum} [, {end}])
3515 Without {end} the result is a String, which is line {lnum}
3516 from the current buffer. Example: >
3517 getline(1)
3518< When {lnum} is a String that doesn't start with a
3519 digit, |line()| is called to translate the String into a Number.
3520 To get the line under the cursor: >
3521 getline(".")
3522< When {lnum} is a number smaller than 1 or bigger than the
3523 number of lines in the buffer, an empty string is returned.
3524
3525 When {end} is given the result is a |List| where each item is
3526 a line from the current buffer in the range {lnum} to {end},
3527 including line {end}.
3528 {end} is used in the same way as {lnum}.
3529 Non-existing lines are silently omitted.
3530 When {end} is before {lnum} an empty |List| is returned.
3531 Example: >
3532 :let start = line('.')
3533 :let end = search("^$") - 1
3534 :let lines = getline(start, end)
3535
3536< Can also be used as a |method|: >
3537 ComputeLnum()->getline()
3538
3539< To get lines from another buffer see |getbufline()|
3540
3541getloclist({nr} [, {what}]) *getloclist()*
3542 Returns a |List| with all the entries in the location list for
3543 window {nr}. {nr} can be the window number or the |window-ID|.
3544 When {nr} is zero the current window is used.
3545
3546 For a location list window, the displayed location list is
3547 returned. For an invalid window number {nr}, an empty list is
3548 returned. Otherwise, same as |getqflist()|.
3549
3550 If the optional {what} dictionary argument is supplied, then
3551 returns the items listed in {what} as a dictionary. Refer to
3552 |getqflist()| for the supported items in {what}.
3553
3554 In addition to the items supported by |getqflist()| in {what},
3555 the following item is supported by |getloclist()|:
3556
3557 filewinid id of the window used to display files
3558 from the location list. This field is
3559 applicable only when called from a
3560 location list window. See
3561 |location-list-file-window| for more
3562 details.
3563
3564 Returns a |Dictionary| with default values if there is no
3565 location list for the window {nr}.
3566 Returns an empty Dictionary if window {nr} does not exist.
3567
3568 Examples (See also |getqflist-examples|): >
3569 :echo getloclist(3, {'all': 0})
3570 :echo getloclist(5, {'filewinid': 0})
3571
3572
3573getmarklist([{buf}]) *getmarklist()*
3574 Without the {buf} argument returns a |List| with information
3575 about all the global marks. |mark|
3576
3577 If the optional {buf} argument is specified, returns the
3578 local marks defined in buffer {buf}. For the use of {buf},
3579 see |bufname()|.
3580
3581 Each item in the returned List is a |Dict| with the following:
3582 mark name of the mark prefixed by "'"
3583 pos a |List| with the position of the mark:
3584 [bufnum, lnum, col, off]
3585 Refer to |getpos()| for more information.
3586 file file name
3587
3588 Refer to |getpos()| for getting information about a specific
3589 mark.
3590
3591 Can also be used as a |method|: >
3592 GetBufnr()->getmarklist()
3593
3594getmatches([{win}]) *getmatches()*
3595 Returns a |List| with all matches previously defined for the
3596 current window by |matchadd()| and the |:match| commands.
3597 |getmatches()| is useful in combination with |setmatches()|,
3598 as |setmatches()| can restore a list of matches saved by
3599 |getmatches()|.
3600 If {win} is specified, use the window with this number or
3601 window ID instead of the current window.
3602 Example: >
3603 :echo getmatches()
3604< [{'group': 'MyGroup1', 'pattern': 'TODO',
3605 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3606 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3607 :let m = getmatches()
3608 :call clearmatches()
3609 :echo getmatches()
3610< [] >
3611 :call setmatches(m)
3612 :echo getmatches()
3613< [{'group': 'MyGroup1', 'pattern': 'TODO',
3614 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3615 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3616 :unlet m
3617<
3618getmousepos() *getmousepos()*
3619 Returns a |Dictionary| with the last known position of the
3620 mouse. This can be used in a mapping for a mouse click or in
3621 a filter of a popup window. The items are:
3622 screenrow screen row
3623 screencol screen column
3624 winid Window ID of the click
3625 winrow row inside "winid"
3626 wincol column inside "winid"
3627 line text line inside "winid"
3628 column text column inside "winid"
3629 All numbers are 1-based.
3630
3631 If not over a window, e.g. when in the command line, then only
3632 "screenrow" and "screencol" are valid, the others are zero.
3633
3634 When on the status line below a window or the vertical
3635 separator right of a window, the "line" and "column" values
3636 are zero.
3637
3638 When the position is after the text then "column" is the
3639 length of the text in bytes plus one.
3640
3641 If the mouse is over a popup window then that window is used.
3642
3643 When using |getchar()| the Vim variables |v:mouse_lnum|,
3644 |v:mouse_col| and |v:mouse_winid| also provide these values.
3645
3646 *getpid()*
3647getpid() Return a Number which is the process ID of the Vim process.
3648 On Unix and MS-Windows this is a unique number, until Vim
3649 exits.
3650
3651 *getpos()*
3652getpos({expr}) Get the position for String {expr}. For possible values of
3653 {expr} see |line()|. For getting the cursor position see
3654 |getcurpos()|.
3655 The result is a |List| with four numbers:
3656 [bufnum, lnum, col, off]
3657 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3658 is the buffer number of the mark.
3659 "lnum" and "col" are the position in the buffer. The first
3660 column is 1.
3661 The "off" number is zero, unless 'virtualedit' is used. Then
3662 it is the offset in screen columns from the start of the
3663 character. E.g., a position within a <Tab> or after the last
3664 character.
3665 Note that for '< and '> Visual mode matters: when it is "V"
3666 (visual line mode) the column of '< is zero and the column of
naohiro ono56200ee2022-01-01 14:59:44 +00003667 '> is a large number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003668 The column number in the returned List is the byte position
3669 within the line. To get the character position in the line,
3670 use |getcharpos()|.
naohiro ono56200ee2022-01-01 14:59:44 +00003671 A very large column number equal to |v:maxcol| can be returned,
3672 in which case it means "after the end of the line".
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003673 This can be used to save and restore the position of a mark: >
3674 let save_a_mark = getpos("'a")
3675 ...
3676 call setpos("'a", save_a_mark)
3677< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
3678
3679 Can also be used as a |method|: >
3680 GetMark()->getpos()
3681
3682getqflist([{what}]) *getqflist()*
3683 Returns a |List| with all the current quickfix errors. Each
3684 list item is a dictionary with these entries:
3685 bufnr number of buffer that has the file name, use
3686 bufname() to get the name
3687 module module name
3688 lnum line number in the buffer (first line is 1)
3689 end_lnum
3690 end of line number if the item is multiline
3691 col column number (first column is 1)
3692 end_col end of column number if the item has range
3693 vcol |TRUE|: "col" is visual column
3694 |FALSE|: "col" is byte index
3695 nr error number
3696 pattern search pattern used to locate the error
3697 text description of the error
3698 type type of the error, 'E', '1', etc.
3699 valid |TRUE|: recognized error message
3700
3701 When there is no error list or it's empty, an empty list is
3702 returned. Quickfix list entries with a non-existing buffer
3703 number are returned with "bufnr" set to zero (Note: some
3704 functions accept buffer number zero for the alternate buffer,
3705 you may need to explicitly check for zero).
3706
3707 Useful application: Find pattern matches in multiple files and
3708 do something with them: >
3709 :vimgrep /theword/jg *.c
3710 :for d in getqflist()
3711 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3712 :endfor
3713<
3714 If the optional {what} dictionary argument is supplied, then
3715 returns only the items listed in {what} as a dictionary. The
3716 following string items are supported in {what}:
3717 changedtick get the total number of changes made
3718 to the list |quickfix-changedtick|
3719 context get the |quickfix-context|
3720 efm errorformat to use when parsing "lines". If
3721 not present, then the 'errorformat' option
3722 value is used.
3723 id get information for the quickfix list with
3724 |quickfix-ID|; zero means the id for the
3725 current list or the list specified by "nr"
3726 idx get information for the quickfix entry at this
3727 index in the list specified by 'id' or 'nr'.
3728 If set to zero, then uses the current entry.
3729 See |quickfix-index|
3730 items quickfix list entries
3731 lines parse a list of lines using 'efm' and return
3732 the resulting entries. Only a |List| type is
3733 accepted. The current quickfix list is not
3734 modified. See |quickfix-parse|.
3735 nr get information for this quickfix list; zero
3736 means the current quickfix list and "$" means
3737 the last quickfix list
3738 qfbufnr number of the buffer displayed in the quickfix
3739 window. Returns 0 if the quickfix buffer is
3740 not present. See |quickfix-buffer|.
3741 size number of entries in the quickfix list
3742 title get the list title |quickfix-title|
3743 winid get the quickfix |window-ID|
3744 all all of the above quickfix properties
3745 Non-string items in {what} are ignored. To get the value of a
3746 particular item, set it to zero.
3747 If "nr" is not present then the current quickfix list is used.
3748 If both "nr" and a non-zero "id" are specified, then the list
3749 specified by "id" is used.
3750 To get the number of lists in the quickfix stack, set "nr" to
3751 "$" in {what}. The "nr" value in the returned dictionary
3752 contains the quickfix stack size.
3753 When "lines" is specified, all the other items except "efm"
3754 are ignored. The returned dictionary contains the entry
3755 "items" with the list of entries.
3756
3757 The returned dictionary contains the following entries:
3758 changedtick total number of changes made to the
3759 list |quickfix-changedtick|
3760 context quickfix list context. See |quickfix-context|
3761 If not present, set to "".
3762 id quickfix list ID |quickfix-ID|. If not
3763 present, set to 0.
3764 idx index of the quickfix entry in the list. If not
3765 present, set to 0.
3766 items quickfix list entries. If not present, set to
3767 an empty list.
3768 nr quickfix list number. If not present, set to 0
3769 qfbufnr number of the buffer displayed in the quickfix
3770 window. If not present, set to 0.
3771 size number of entries in the quickfix list. If not
3772 present, set to 0.
3773 title quickfix list title text. If not present, set
3774 to "".
3775 winid quickfix |window-ID|. If not present, set to 0
3776
3777 Examples (See also |getqflist-examples|): >
3778 :echo getqflist({'all': 1})
3779 :echo getqflist({'nr': 2, 'title': 1})
3780 :echo getqflist({'lines' : ["F1:10:L10"]})
3781<
3782getreg([{regname} [, 1 [, {list}]]]) *getreg()*
3783 The result is a String, which is the contents of register
3784 {regname}. Example: >
3785 :let cliptext = getreg('*')
3786< When register {regname} was not set the result is an empty
3787 string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00003788 The {regname} argument must be a string. *E1162*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003789
3790 getreg('=') returns the last evaluated value of the expression
3791 register. (For use in maps.)
3792 getreg('=', 1) returns the expression itself, so that it can
3793 be restored with |setreg()|. For other registers the extra
3794 argument is ignored, thus you can always give it.
3795
3796 If {list} is present and |TRUE|, the result type is changed
3797 to |List|. Each list item is one text line. Use it if you care
3798 about zero bytes possibly present inside register: without
3799 third argument both NLs and zero bytes are represented as NLs
3800 (see |NL-used-for-Nul|).
3801 When the register was not set an empty list is returned.
3802
3803 If {regname} is "", the unnamed register '"' is used.
3804 If {regname} is not specified, |v:register| is used.
3805 In |Vim9-script| {regname} must be one character.
3806
3807 Can also be used as a |method|: >
3808 GetRegname()->getreg()
3809
3810getreginfo([{regname}]) *getreginfo()*
3811 Returns detailed information about register {regname} as a
3812 Dictionary with the following entries:
3813 regcontents List of lines contained in register
3814 {regname}, like
3815 |getreg|({regname}, 1, 1).
3816 regtype the type of register {regname}, as in
3817 |getregtype()|.
3818 isunnamed Boolean flag, v:true if this register
3819 is currently pointed to by the unnamed
3820 register.
3821 points_to for the unnamed register, gives the
3822 single letter name of the register
3823 currently pointed to (see |quotequote|).
3824 For example, after deleting a line
3825 with `dd`, this field will be "1",
3826 which is the register that got the
3827 deleted text.
3828
3829 The {regname} argument is a string. If {regname} is invalid
3830 or not set, an empty Dictionary will be returned.
3831 If {regname} is "" or "@", the unnamed register '"' is used.
3832 If {regname} is not specified, |v:register| is used.
3833 The returned Dictionary can be passed to |setreg()|.
3834 In |Vim9-script| {regname} must be one character.
3835
3836 Can also be used as a |method|: >
3837 GetRegname()->getreginfo()
3838
3839getregtype([{regname}]) *getregtype()*
3840 The result is a String, which is type of register {regname}.
3841 The value will be one of:
3842 "v" for |characterwise| text
3843 "V" for |linewise| text
3844 "<CTRL-V>{width}" for |blockwise-visual| text
3845 "" for an empty or unknown register
3846 <CTRL-V> is one character with value 0x16.
3847 The {regname} argument is a string. If {regname} is "", the
3848 unnamed register '"' is used. If {regname} is not specified,
3849 |v:register| is used.
3850 In |Vim9-script| {regname} must be one character.
3851
3852 Can also be used as a |method|: >
3853 GetRegname()->getregtype()
3854
3855gettabinfo([{tabnr}]) *gettabinfo()*
3856 If {tabnr} is not specified, then information about all the
3857 tab pages is returned as a |List|. Each List item is a
3858 |Dictionary|. Otherwise, {tabnr} specifies the tab page
3859 number and information about that one is returned. If the tab
3860 page does not exist an empty List is returned.
3861
3862 Each List item is a |Dictionary| with the following entries:
3863 tabnr tab page number.
3864 variables a reference to the dictionary with
3865 tabpage-local variables
3866 windows List of |window-ID|s in the tab page.
3867
3868 Can also be used as a |method|: >
3869 GetTabnr()->gettabinfo()
3870
3871gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
3872 Get the value of a tab-local variable {varname} in tab page
3873 {tabnr}. |t:var|
3874 Tabs are numbered starting with one.
3875 The {varname} argument is a string. When {varname} is empty a
3876 dictionary with all tab-local variables is returned.
3877 Note that the name without "t:" must be used.
3878 When the tab or variable doesn't exist {def} or an empty
3879 string is returned, there is no error message.
3880
3881 Can also be used as a |method|: >
3882 GetTabnr()->gettabvar(varname)
3883
3884gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
3885 Get the value of window-local variable {varname} in window
3886 {winnr} in tab page {tabnr}.
3887 The {varname} argument is a string. When {varname} is empty a
3888 dictionary with all window-local variables is returned.
3889 When {varname} is equal to "&" get the values of all
3890 window-local options in a |Dictionary|.
3891 Otherwise, when {varname} starts with "&" get the value of a
3892 window-local option.
3893 Note that {varname} must be the name without "w:".
3894 Tabs are numbered starting with one. For the current tabpage
3895 use |getwinvar()|.
3896 {winnr} can be the window number or the |window-ID|.
3897 When {winnr} is zero the current window is used.
3898 This also works for a global option, buffer-local option and
3899 window-local option, but it doesn't work for a global variable
3900 or buffer-local variable.
3901 When the tab, window or variable doesn't exist {def} or an
3902 empty string is returned, there is no error message.
3903 Examples: >
3904 :let list_is_on = gettabwinvar(1, 2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003905 :echo "myvar = " .. gettabwinvar(3, 1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00003906<
3907 To obtain all window-local variables use: >
3908 gettabwinvar({tabnr}, {winnr}, '&')
3909
3910< Can also be used as a |method|: >
3911 GetTabnr()->gettabwinvar(winnr, varname)
3912
3913gettagstack([{winnr}]) *gettagstack()*
3914 The result is a Dict, which is the tag stack of window {winnr}.
3915 {winnr} can be the window number or the |window-ID|.
3916 When {winnr} is not specified, the current window is used.
3917 When window {winnr} doesn't exist, an empty Dict is returned.
3918
3919 The returned dictionary contains the following entries:
3920 curidx Current index in the stack. When at
3921 top of the stack, set to (length + 1).
3922 Index of bottom of the stack is 1.
3923 items List of items in the stack. Each item
3924 is a dictionary containing the
3925 entries described below.
3926 length Number of entries in the stack.
3927
3928 Each item in the stack is a dictionary with the following
3929 entries:
3930 bufnr buffer number of the current jump
3931 from cursor position before the tag jump.
3932 See |getpos()| for the format of the
3933 returned list.
3934 matchnr current matching tag number. Used when
3935 multiple matching tags are found for a
3936 name.
3937 tagname name of the tag
3938
3939 See |tagstack| for more information about the tag stack.
3940
3941 Can also be used as a |method|: >
3942 GetWinnr()->gettagstack()
3943
3944
3945gettext({text}) *gettext()*
3946 Translate String {text} if possible.
3947 This is mainly for use in the distributed Vim scripts. When
3948 generating message translations the {text} is extracted by
3949 xgettext, the translator can add the translated message in the
3950 .po file and Vim will lookup the translation when gettext() is
3951 called.
3952 For {text} double quoted strings are preferred, because
3953 xgettext does not understand escaping in single quoted
3954 strings.
3955
3956
3957getwininfo([{winid}]) *getwininfo()*
3958 Returns information about windows as a |List| with Dictionaries.
3959
3960 If {winid} is given Information about the window with that ID
3961 is returned, as a |List| with one item. If the window does not
3962 exist the result is an empty list.
3963
3964 Without {winid} information about all the windows in all the
3965 tab pages is returned.
3966
3967 Each List item is a |Dictionary| with the following entries:
3968 botline last complete displayed buffer line
3969 bufnr number of buffer in the window
3970 height window height (excluding winbar)
3971 loclist 1 if showing a location list
3972 {only with the +quickfix feature}
3973 quickfix 1 if quickfix or location list window
3974 {only with the +quickfix feature}
3975 terminal 1 if a terminal window
3976 {only with the +terminal feature}
3977 tabnr tab page number
3978 topline first displayed buffer line
3979 variables a reference to the dictionary with
3980 window-local variables
3981 width window width
3982 winbar 1 if the window has a toolbar, 0
3983 otherwise
3984 wincol leftmost screen column of the window;
3985 "col" from |win_screenpos()|
3986 textoff number of columns occupied by any
3987 'foldcolumn', 'signcolumn' and line
3988 number in front of the text
3989 winid |window-ID|
3990 winnr window number
3991 winrow topmost screen line of the window;
3992 "row" from |win_screenpos()|
3993
3994 Can also be used as a |method|: >
3995 GetWinnr()->getwininfo()
3996
3997getwinpos([{timeout}]) *getwinpos()*
3998 The result is a |List| with two numbers, the result of
3999 |getwinposx()| and |getwinposy()| combined:
4000 [x-pos, y-pos]
4001 {timeout} can be used to specify how long to wait in msec for
4002 a response from the terminal. When omitted 100 msec is used.
4003 Use a longer time for a remote terminal.
4004 When using a value less than 10 and no response is received
4005 within that time, a previously reported position is returned,
4006 if available. This can be used to poll for the position and
4007 do some work in the meantime: >
4008 while 1
4009 let res = getwinpos(1)
4010 if res[0] >= 0
4011 break
4012 endif
4013 " Do some work here
4014 endwhile
4015<
4016
4017 Can also be used as a |method|: >
4018 GetTimeout()->getwinpos()
4019<
4020 *getwinposx()*
4021getwinposx() The result is a Number, which is the X coordinate in pixels of
4022 the left hand side of the GUI Vim window. Also works for an
4023 xterm (uses a timeout of 100 msec).
4024 The result will be -1 if the information is not available.
4025 The value can be used with `:winpos`.
4026
4027 *getwinposy()*
4028getwinposy() The result is a Number, which is the Y coordinate in pixels of
4029 the top of the GUI Vim window. Also works for an xterm (uses
4030 a timeout of 100 msec).
4031 The result will be -1 if the information is not available.
4032 The value can be used with `:winpos`.
4033
4034getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
4035 Like |gettabwinvar()| for the current tabpage.
4036 Examples: >
4037 :let list_is_on = getwinvar(2, '&list')
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004038 :echo "myvar = " .. getwinvar(1, 'myvar')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004039
4040< Can also be used as a |method|: >
4041 GetWinnr()->getwinvar(varname)
4042<
4043glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
4044 Expand the file wildcards in {expr}. See |wildcards| for the
4045 use of special characters.
4046
4047 Unless the optional {nosuf} argument is given and is |TRUE|,
4048 the 'suffixes' and 'wildignore' options apply: Names matching
4049 one of the patterns in 'wildignore' will be skipped and
4050 'suffixes' affect the ordering of matches.
4051 'wildignorecase' always applies.
4052
4053 When {list} is present and it is |TRUE| the result is a |List|
4054 with all matching files. The advantage of using a List is,
4055 you also get filenames containing newlines correctly.
4056 Otherwise the result is a String and when there are several
4057 matches, they are separated by <NL> characters.
4058
4059 If the expansion fails, the result is an empty String or List.
4060
4061 You can also use |readdir()| if you need to do complicated
4062 things, such as limiting the number of matches.
4063
4064 A name for a non-existing file is not included. A symbolic
4065 link is only included if it points to an existing file.
4066 However, when the {alllinks} argument is present and it is
4067 |TRUE| then all symbolic links are included.
4068
4069 For most systems backticks can be used to get files names from
4070 any external command. Example: >
4071 :let tagfiles = glob("`find . -name tags -print`")
4072 :let &tags = substitute(tagfiles, "\n", ",", "g")
4073< The result of the program inside the backticks should be one
4074 item per line. Spaces inside an item are allowed.
4075
4076 See |expand()| for expanding special Vim variables. See
4077 |system()| for getting the raw output of an external command.
4078
4079 Can also be used as a |method|: >
4080 GetExpr()->glob()
4081
4082glob2regpat({string}) *glob2regpat()*
4083 Convert a file pattern, as used by glob(), into a search
4084 pattern. The result can be used to match with a string that
4085 is a file name. E.g. >
4086 if filename =~ glob2regpat('Make*.mak')
4087< This is equivalent to: >
4088 if filename =~ '^Make.*\.mak$'
4089< When {string} is an empty string the result is "^$", match an
4090 empty string.
4091 Note that the result depends on the system. On MS-Windows
4092 a backslash usually means a path separator.
4093
4094 Can also be used as a |method|: >
4095 GetExpr()->glob2regpat()
4096< *globpath()*
4097globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
4098 Perform glob() for String {expr} on all directories in {path}
4099 and concatenate the results. Example: >
4100 :echo globpath(&rtp, "syntax/c.vim")
4101<
4102 {path} is a comma-separated list of directory names. Each
4103 directory name is prepended to {expr} and expanded like with
4104 |glob()|. A path separator is inserted when needed.
4105 To add a comma inside a directory name escape it with a
4106 backslash. Note that on MS-Windows a directory may have a
4107 trailing backslash, remove it if you put a comma after it.
4108 If the expansion fails for one of the directories, there is no
4109 error message.
4110
4111 Unless the optional {nosuf} argument is given and is |TRUE|,
4112 the 'suffixes' and 'wildignore' options apply: Names matching
4113 one of the patterns in 'wildignore' will be skipped and
4114 'suffixes' affect the ordering of matches.
4115
4116 When {list} is present and it is |TRUE| the result is a |List|
4117 with all matching files. The advantage of using a List is, you
4118 also get filenames containing newlines correctly. Otherwise
4119 the result is a String and when there are several matches,
4120 they are separated by <NL> characters. Example: >
4121 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4122<
4123 {alllinks} is used as with |glob()|.
4124
4125 The "**" item can be used to search in a directory tree.
4126 For example, to find all "README.txt" files in the directories
4127 in 'runtimepath' and below: >
4128 :echo globpath(&rtp, "**/README.txt")
4129< Upwards search and limiting the depth of "**" is not
4130 supported, thus using 'path' will not always work properly.
4131
4132 Can also be used as a |method|, the base is passed as the
4133 second argument: >
4134 GetExpr()->globpath(&rtp)
4135<
4136 *has()*
4137has({feature} [, {check}])
4138 When {check} is omitted or is zero: The result is a Number,
4139 which is 1 if the feature {feature} is supported, zero
4140 otherwise. The {feature} argument is a string, case is
4141 ignored. See |feature-list| below.
4142
4143 When {check} is present and not zero: The result is a Number,
4144 which is 1 if the feature {feature} could ever be supported,
4145 zero otherwise. This is useful to check for a typo in
4146 {feature} and to detect dead code. Keep in mind that an older
4147 Vim version will not know about a feature added later and
4148 features that have been abandoned will not be known by the
4149 current Vim version.
4150
4151 Also see |exists()| and |exists_compiled()|.
4152
4153 Note that to skip code that has a syntax error when the
4154 feature is not available, Vim may skip the rest of the line
4155 and miss a following `endif`. Therefore put the `endif` on a
4156 separate line: >
4157 if has('feature')
4158 let x = this->breaks->without->the->feature
4159 endif
4160< If the `endif` would be moved to the second line as "| endif" it
4161 would not be found.
4162
4163
4164has_key({dict}, {key}) *has_key()*
4165 The result is a Number, which is TRUE if |Dictionary| {dict}
4166 has an entry with key {key}. FALSE otherwise. The {key}
4167 argument is a string.
4168
4169 Can also be used as a |method|: >
4170 mydict->has_key(key)
4171
4172haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4173 The result is a Number:
4174 1 when the window has set a local directory via |:lcd|
4175 2 when the tab-page has set a local directory via |:tcd|
4176 0 otherwise.
4177
4178 Without arguments use the current window.
4179 With {winnr} use this window in the current tab page.
4180 With {winnr} and {tabnr} use the window in the specified tab
4181 page.
4182 {winnr} can be the window number or the |window-ID|.
4183 If {winnr} is -1 it is ignored and only the tabpage is used.
4184 Return 0 if the arguments are invalid.
4185 Examples: >
4186 if haslocaldir() == 1
4187 " window local directory case
4188 elseif haslocaldir() == 2
4189 " tab-local directory case
4190 else
4191 " global directory case
4192 endif
4193
4194 " current window
4195 :echo haslocaldir()
4196 :echo haslocaldir(0)
4197 :echo haslocaldir(0, 0)
4198 " window n in current tab page
4199 :echo haslocaldir(n)
4200 :echo haslocaldir(n, 0)
4201 " window n in tab page m
4202 :echo haslocaldir(n, m)
4203 " tab page m
4204 :echo haslocaldir(-1, m)
4205<
4206 Can also be used as a |method|: >
4207 GetWinnr()->haslocaldir()
4208
4209hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
4210 The result is a Number, which is TRUE if there is a mapping
4211 that contains {what} in somewhere in the rhs (what it is
4212 mapped to) and this mapping exists in one of the modes
4213 indicated by {mode}.
4214 The arguments {what} and {mode} are strings.
4215 When {abbr} is there and it is |TRUE| use abbreviations
4216 instead of mappings. Don't forget to specify Insert and/or
4217 Command-line mode.
4218 Both the global mappings and the mappings local to the current
4219 buffer are checked for a match.
4220 If no matching mapping is found FALSE is returned.
4221 The following characters are recognized in {mode}:
4222 n Normal mode
4223 v Visual and Select mode
4224 x Visual mode
4225 s Select mode
4226 o Operator-pending mode
4227 i Insert mode
4228 l Language-Argument ("r", "f", "t", etc.)
4229 c Command-line mode
4230 When {mode} is omitted, "nvo" is used.
4231
4232 This function is useful to check if a mapping already exists
4233 to a function in a Vim script. Example: >
4234 :if !hasmapto('\ABCdoit')
4235 : map <Leader>d \ABCdoit
4236 :endif
4237< This installs the mapping to "\ABCdoit" only if there isn't
4238 already a mapping to "\ABCdoit".
4239
4240 Can also be used as a |method|: >
4241 GetRHS()->hasmapto()
4242
4243histadd({history}, {item}) *histadd()*
4244 Add the String {item} to the history {history} which can be
4245 one of: *hist-names*
4246 "cmd" or ":" command line history
4247 "search" or "/" search pattern history
4248 "expr" or "=" typed expression history
4249 "input" or "@" input line history
4250 "debug" or ">" debug command history
4251 empty the current or last used history
4252 The {history} string does not need to be the whole name, one
4253 character is sufficient.
4254 If {item} does already exist in the history, it will be
4255 shifted to become the newest entry.
4256 The result is a Number: TRUE if the operation was successful,
4257 otherwise FALSE is returned.
4258
4259 Example: >
4260 :call histadd("input", strftime("%Y %b %d"))
4261 :let date=input("Enter date: ")
4262< This function is not available in the |sandbox|.
4263
4264 Can also be used as a |method|, the base is passed as the
4265 second argument: >
4266 GetHistory()->histadd('search')
4267
4268histdel({history} [, {item}]) *histdel()*
4269 Clear {history}, i.e. delete all its entries. See |hist-names|
4270 for the possible values of {history}.
4271
4272 If the parameter {item} evaluates to a String, it is used as a
4273 regular expression. All entries matching that expression will
4274 be removed from the history (if there are any).
4275 Upper/lowercase must match, unless "\c" is used |/\c|.
4276 If {item} evaluates to a Number, it will be interpreted as
4277 an index, see |:history-indexing|. The respective entry will
4278 be removed if it exists.
4279
4280 The result is TRUE for a successful operation, otherwise FALSE
4281 is returned.
4282
4283 Examples:
4284 Clear expression register history: >
4285 :call histdel("expr")
4286<
4287 Remove all entries starting with "*" from the search history: >
4288 :call histdel("/", '^\*')
4289<
4290 The following three are equivalent: >
4291 :call histdel("search", histnr("search"))
4292 :call histdel("search", -1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004293 :call histdel("search", '^' .. histget("search", -1) .. '$')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004294<
4295 To delete the last search pattern and use the last-but-one for
4296 the "n" command and 'hlsearch': >
4297 :call histdel("search", -1)
4298 :let @/ = histget("search", -1)
4299<
4300 Can also be used as a |method|: >
4301 GetHistory()->histdel()
4302
4303histget({history} [, {index}]) *histget()*
4304 The result is a String, the entry with Number {index} from
4305 {history}. See |hist-names| for the possible values of
4306 {history}, and |:history-indexing| for {index}. If there is
4307 no such entry, an empty String is returned. When {index} is
4308 omitted, the most recent item from the history is used.
4309
4310 Examples:
4311 Redo the second last search from history. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004312 :execute '/' .. histget("search", -2)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004313
4314< Define an Ex command ":H {num}" that supports re-execution of
4315 the {num}th entry from the output of |:history|. >
4316 :command -nargs=1 H execute histget("cmd", 0+<args>)
4317<
4318 Can also be used as a |method|: >
4319 GetHistory()->histget()
4320
4321histnr({history}) *histnr()*
4322 The result is the Number of the current entry in {history}.
4323 See |hist-names| for the possible values of {history}.
4324 If an error occurred, -1 is returned.
4325
4326 Example: >
4327 :let inp_index = histnr("expr")
4328
4329< Can also be used as a |method|: >
4330 GetHistory()->histnr()
4331<
4332hlexists({name}) *hlexists()*
4333 The result is a Number, which is TRUE if a highlight group
4334 called {name} exists. This is when the group has been
4335 defined in some way. Not necessarily when highlighting has
4336 been defined for it, it may also have been used for a syntax
4337 item.
4338 *highlight_exists()*
4339 Obsolete name: highlight_exists().
4340
4341 Can also be used as a |method|: >
4342 GetName()->hlexists()
4343<
4344hlget([{name} [, {resolve}]]) *hlget()*
4345 Returns a List of all the highlight group attributes. If the
4346 optional {name} is specified, then returns a List with only
4347 the attributes of the specified highlight group. Returns an
4348 empty List if the highlight group {name} is not present.
4349
4350 If the optional {resolve} argument is set to v:true and the
4351 highlight group {name} is linked to another group, then the
4352 link is resolved recursively and the attributes of the
4353 resolved highlight group are returned.
4354
4355 Each entry in the returned List is a Dictionary with the
4356 following items:
4357 cleared boolean flag, set to v:true if the highlight
4358 group attributes are cleared or not yet
4359 specified. See |highlight-clear|.
4360 cterm cterm attributes. See |highlight-cterm|.
4361 ctermbg cterm background color.
4362 See |highlight-ctermbg|.
4363 ctermfg cterm foreground color.
4364 See |highlight-ctermfg|.
4365 ctermul cterm underline color. See |highlight-ctermul|.
4366 default boolean flag, set to v:true if the highlight
4367 group link is a default link. See
4368 |highlight-default|.
4369 font highlight group font. See |highlight-font|.
4370 gui gui attributes. See |highlight-gui|.
4371 guibg gui background color. See |highlight-guibg|.
4372 guifg gui foreground color. See |highlight-guifg|.
4373 guisp gui special color. See |highlight-guisp|.
4374 id highlight group ID.
4375 linksto linked highlight group name.
4376 See |:highlight-link|.
4377 name highlight group name. See |group-name|.
4378 start start terminal keycode. See |highlight-start|.
4379 stop stop terminal keycode. See |highlight-stop|.
4380 term term attributes. See |highlight-term|.
4381
4382 The 'term', 'cterm' and 'gui' items in the above Dictionary
4383 have a dictionary value with the following optional boolean
4384 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
4385 'reverse', 'inverse' and 'strikethrough'.
4386
4387 Example(s): >
4388 :echo hlget()
4389 :echo hlget('ModeMsg')
4390 :echo hlget('Number', v:true)
4391<
4392 Can also be used as a |method|: >
4393 GetName()->hlget()
4394<
4395hlset({list}) *hlset()*
4396 Creates or modifies the attributes of a List of highlight
4397 groups. Each item in {list} is a dictionary containing the
4398 attributes of a highlight group. See |hlget()| for the list of
4399 supported items in this dictionary.
4400
4401 In addition to the items described in |hlget()|, the following
4402 additional items are supported in the dictionary:
4403
4404 force boolean flag to force the creation of
4405 a link for an existing highlight group
4406 with attributes.
4407
4408 The highlight group is identified using the 'name' item and
4409 the 'id' item (if supplied) is ignored. If a highlight group
4410 with a specified name doesn't exist, then it is created.
4411 Otherwise the attributes of an existing highlight group are
4412 modified.
4413
4414 If an empty dictionary value is used for the 'term' or 'cterm'
4415 or 'gui' entries, then the corresponding attributes are
4416 cleared. If the 'cleared' item is set to v:true, then all the
4417 attributes of the highlight group are cleared.
4418
4419 The 'linksto' item can be used to link a highlight group to
4420 another highlight group. See |:highlight-link|.
4421
4422 Returns zero for success, -1 for failure.
4423
4424 Example(s): >
4425 " add bold attribute to the Visual highlight group
4426 :call hlset([#{name: 'Visual',
4427 \ term: #{reverse: 1 , bold: 1}}])
4428 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
4429 :let l = hlget()
4430 :call hlset(l)
4431 " clear the Search highlight group
4432 :call hlset([#{name: 'Search', cleared: v:true}])
4433 " clear the 'term' attributes for a highlight group
4434 :call hlset([#{name: 'Title', term: {}}])
4435 " create the MyHlg group linking it to DiffAdd
4436 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
4437 " remove the MyHlg group link
4438 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
4439 " clear the attributes and a link
4440 :call hlset([#{name: 'MyHlg', cleared: v:true,
4441 \ linksto: 'NONE'}])
4442<
4443 Can also be used as a |method|: >
4444 GetAttrList()->hlset()
4445<
4446 *hlID()*
4447hlID({name}) The result is a Number, which is the ID of the highlight group
4448 with name {name}. When the highlight group doesn't exist,
4449 zero is returned.
4450 This can be used to retrieve information about the highlight
4451 group. For example, to get the background color of the
4452 "Comment" group: >
4453 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4454< *highlightID()*
4455 Obsolete name: highlightID().
4456
4457 Can also be used as a |method|: >
4458 GetName()->hlID()
4459
4460hostname() *hostname()*
4461 The result is a String, which is the name of the machine on
4462 which Vim is currently running. Machine names greater than
4463 256 characters long are truncated.
4464
4465iconv({string}, {from}, {to}) *iconv()*
4466 The result is a String, which is the text {string} converted
4467 from encoding {from} to encoding {to}.
4468 When the conversion completely fails an empty string is
4469 returned. When some characters could not be converted they
4470 are replaced with "?".
4471 The encoding names are whatever the iconv() library function
4472 can accept, see ":!man 3 iconv".
4473 Most conversions require Vim to be compiled with the |+iconv|
4474 feature. Otherwise only UTF-8 to latin1 conversion and back
4475 can be done.
4476 This can be used to display messages with special characters,
4477 no matter what 'encoding' is set to. Write the message in
4478 UTF-8 and use: >
4479 echo iconv(utf8_str, "utf-8", &enc)
4480< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4481 from/to UCS-2 is automatically changed to use UTF-8. You
4482 cannot use UCS-2 in a string anyway, because of the NUL bytes.
4483
4484 Can also be used as a |method|: >
4485 GetText()->iconv('latin1', 'utf-8')
4486<
4487 *indent()*
4488indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4489 current buffer. The indent is counted in spaces, the value
4490 of 'tabstop' is relevant. {lnum} is used just like in
4491 |getline()|.
4492 When {lnum} is invalid -1 is returned. In |Vim9| script an
4493 error is given.
4494
4495 Can also be used as a |method|: >
4496 GetLnum()->indent()
4497
4498index({object}, {expr} [, {start} [, {ic}]]) *index()*
4499 If {object} is a |List| return the lowest index where the item
4500 has a value equal to {expr}. There is no automatic
4501 conversion, so the String "4" is different from the Number 4.
4502 And the number 4 is different from the Float 4.0. The value
4503 of 'ignorecase' is not used here, case always matters.
4504
4505 If {object} is |Blob| return the lowest index where the byte
4506 value is equal to {expr}.
4507
4508 If {start} is given then start looking at the item with index
4509 {start} (may be negative for an item relative to the end).
4510 When {ic} is given and it is |TRUE|, ignore case. Otherwise
4511 case must match.
4512 -1 is returned when {expr} is not found in {object}.
4513 Example: >
4514 :let idx = index(words, "the")
4515 :if index(numbers, 123) >= 0
4516
4517< Can also be used as a |method|: >
4518 GetObject()->index(what)
4519
4520input({prompt} [, {text} [, {completion}]]) *input()*
4521 The result is a String, which is whatever the user typed on
4522 the command-line. The {prompt} argument is either a prompt
4523 string, or a blank string (for no prompt). A '\n' can be used
4524 in the prompt to start a new line.
4525 The highlighting set with |:echohl| is used for the prompt.
4526 The input is entered just like a command-line, with the same
4527 editing commands and mappings. There is a separate history
4528 for lines typed for input().
4529 Example: >
4530 :if input("Coffee or beer? ") == "beer"
4531 : echo "Cheers!"
4532 :endif
4533<
4534 If the optional {text} argument is present and not empty, this
4535 is used for the default reply, as if the user typed this.
4536 Example: >
4537 :let color = input("Color? ", "white")
4538
4539< The optional {completion} argument specifies the type of
4540 completion supported for the input. Without it completion is
4541 not performed. The supported completion types are the same as
4542 that can be supplied to a user-defined command using the
4543 "-complete=" argument. Refer to |:command-completion| for
4544 more information. Example: >
4545 let fname = input("File: ", "", "file")
4546<
4547 NOTE: This function must not be used in a startup file, for
4548 the versions that only run in GUI mode (e.g., the Win32 GUI).
4549 Note: When input() is called from within a mapping it will
4550 consume remaining characters from that mapping, because a
4551 mapping is handled like the characters were typed.
4552 Use |inputsave()| before input() and |inputrestore()|
4553 after input() to avoid that. Another solution is to avoid
4554 that further characters follow in the mapping, e.g., by using
4555 |:execute| or |:normal|.
4556
4557 Example with a mapping: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004558 :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR>
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004559 :function GetFoo()
4560 : call inputsave()
4561 : let g:Foo = input("enter search pattern: ")
4562 : call inputrestore()
4563 :endfunction
4564
4565< Can also be used as a |method|: >
4566 GetPrompt()->input()
4567
4568inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
4569 Like |input()|, but when the GUI is running and text dialogs
4570 are supported, a dialog window pops up to input the text.
4571 Example: >
4572 :let n = inputdialog("value for shiftwidth", shiftwidth())
4573 :if n != ""
4574 : let &sw = n
4575 :endif
4576< When the dialog is cancelled {cancelreturn} is returned. When
4577 omitted an empty string is returned.
4578 Hitting <Enter> works like pressing the OK button. Hitting
4579 <Esc> works like pressing the Cancel button.
4580 NOTE: Command-line completion is not supported.
4581
4582 Can also be used as a |method|: >
4583 GetPrompt()->inputdialog()
4584
4585inputlist({textlist}) *inputlist()*
4586 {textlist} must be a |List| of strings. This |List| is
4587 displayed, one string per line. The user will be prompted to
4588 enter a number, which is returned.
4589 The user can also select an item by clicking on it with the
4590 mouse, if the mouse is enabled in the command line ('mouse' is
4591 "a" or includes "c"). For the first string 0 is returned.
4592 When clicking above the first item a negative number is
4593 returned. When clicking on the prompt one more than the
4594 length of {textlist} is returned.
4595 Make sure {textlist} has less than 'lines' entries, otherwise
4596 it won't work. It's a good idea to put the entry number at
4597 the start of the string. And put a prompt in the first item.
4598 Example: >
4599 let color = inputlist(['Select color:', '1. red',
4600 \ '2. green', '3. blue'])
4601
4602< Can also be used as a |method|: >
4603 GetChoices()->inputlist()
4604
4605inputrestore() *inputrestore()*
4606 Restore typeahead that was saved with a previous |inputsave()|.
4607 Should be called the same number of times inputsave() is
4608 called. Calling it more often is harmless though.
4609 Returns TRUE when there is nothing to restore, FALSE otherwise.
4610
4611inputsave() *inputsave()*
4612 Preserve typeahead (also from mappings) and clear it, so that
4613 a following prompt gets input from the user. Should be
4614 followed by a matching inputrestore() after the prompt. Can
4615 be used several times, in which case there must be just as
4616 many inputrestore() calls.
4617 Returns TRUE when out of memory, FALSE otherwise.
4618
4619inputsecret({prompt} [, {text}]) *inputsecret()*
4620 This function acts much like the |input()| function with but
4621 two exceptions:
4622 a) the user's response will be displayed as a sequence of
4623 asterisks ("*") thereby keeping the entry secret, and
4624 b) the user's response will not be recorded on the input
4625 |history| stack.
4626 The result is a String, which is whatever the user actually
4627 typed on the command-line in response to the issued prompt.
4628 NOTE: Command-line completion is not supported.
4629
4630 Can also be used as a |method|: >
4631 GetPrompt()->inputsecret()
4632
4633insert({object}, {item} [, {idx}]) *insert()*
4634 When {object} is a |List| or a |Blob| insert {item} at the start
4635 of it.
4636
4637 If {idx} is specified insert {item} before the item with index
4638 {idx}. If {idx} is zero it goes before the first item, just
4639 like omitting {idx}. A negative {idx} is also possible, see
4640 |list-index|. -1 inserts just before the last item.
4641
4642 Returns the resulting |List| or |Blob|. Examples: >
4643 :let mylist = insert([2, 3, 5], 1)
4644 :call insert(mylist, 4, -1)
4645 :call insert(mylist, 6, len(mylist))
4646< The last example can be done simpler with |add()|.
4647 Note that when {item} is a |List| it is inserted as a single
4648 item. Use |extend()| to concatenate |Lists|.
4649
4650 Can also be used as a |method|: >
4651 mylist->insert(item)
4652
4653interrupt() *interrupt()*
4654 Interrupt script execution. It works more or less like the
4655 user typing CTRL-C, most commands won't execute and control
4656 returns to the user. This is useful to abort execution
4657 from lower down, e.g. in an autocommand. Example: >
4658 :function s:check_typoname(file)
4659 : if fnamemodify(a:file, ':t') == '['
4660 : echomsg 'Maybe typo'
4661 : call interrupt()
4662 : endif
4663 :endfunction
4664 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
4665
4666invert({expr}) *invert()*
4667 Bitwise invert. The argument is converted to a number. A
4668 List, Dict or Float argument causes an error. Example: >
4669 :let bits = invert(bits)
4670< Can also be used as a |method|: >
4671 :let bits = bits->invert()
4672
4673isdirectory({directory}) *isdirectory()*
4674 The result is a Number, which is |TRUE| when a directory
4675 with the name {directory} exists. If {directory} doesn't
4676 exist, or isn't a directory, the result is |FALSE|. {directory}
4677 is any expression, which is used as a String.
4678
4679 Can also be used as a |method|: >
4680 GetName()->isdirectory()
4681
4682isinf({expr}) *isinf()*
4683 Return 1 if {expr} is a positive infinity, or -1 a negative
4684 infinity, otherwise 0. >
4685 :echo isinf(1.0 / 0.0)
4686< 1 >
4687 :echo isinf(-1.0 / 0.0)
4688< -1
4689
4690 Can also be used as a |method|: >
4691 Compute()->isinf()
4692<
4693 {only available when compiled with the |+float| feature}
4694
4695islocked({expr}) *islocked()* *E786*
4696 The result is a Number, which is |TRUE| when {expr} is the
4697 name of a locked variable.
4698 The string argument {expr} must be the name of a variable,
4699 |List| item or |Dictionary| entry, not the variable itself!
4700 Example: >
4701 :let alist = [0, ['a', 'b'], 2, 3]
4702 :lockvar 1 alist
4703 :echo islocked('alist') " 1
4704 :echo islocked('alist[1]') " 0
4705
Bram Moolenaar9da17d72022-02-09 21:50:44 +00004706< When {expr} is a variable that does not exist -1 is returned.
4707 If {expr} uses a range, list or dict index that is out of
4708 range or does not exist you get an error message. Use
4709 |exists()| to check for existence.
4710 In Vim9 script it does not work for local function variables.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004711
4712 Can also be used as a |method|: >
4713 GetName()->islocked()
4714
4715isnan({expr}) *isnan()*
4716 Return |TRUE| if {expr} is a float with value NaN. >
4717 echo isnan(0.0 / 0.0)
4718< 1
4719
4720 Can also be used as a |method|: >
4721 Compute()->isnan()
4722<
4723 {only available when compiled with the |+float| feature}
4724
4725items({dict}) *items()*
4726 Return a |List| with all the key-value pairs of {dict}. Each
4727 |List| item is a list with two items: the key of a {dict}
4728 entry and the value of this entry. The |List| is in arbitrary
4729 order. Also see |keys()| and |values()|.
4730 Example: >
4731 for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004732 echo key .. ': ' .. value
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004733 endfor
4734
4735< Can also be used as a |method|: >
4736 mydict->items()
4737
4738job_ functions are documented here: |job-functions-details|
4739
4740
4741join({list} [, {sep}]) *join()*
4742 Join the items in {list} together into one String.
4743 When {sep} is specified it is put in between the items. If
4744 {sep} is omitted a single space is used.
4745 Note that {sep} is not added at the end. You might want to
4746 add it there too: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004747 let lines = join(mylist, "\n") .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004748< String items are used as-is. |Lists| and |Dictionaries| are
4749 converted into a string like with |string()|.
4750 The opposite function is |split()|.
4751
4752 Can also be used as a |method|: >
4753 mylist->join()
4754
4755js_decode({string}) *js_decode()*
4756 This is similar to |json_decode()| with these differences:
4757 - Object key names do not have to be in quotes.
4758 - Strings can be in single quotes.
4759 - Empty items in an array (between two commas) are allowed and
4760 result in v:none items.
4761
4762 Can also be used as a |method|: >
4763 ReadObject()->js_decode()
4764
4765js_encode({expr}) *js_encode()*
4766 This is similar to |json_encode()| with these differences:
4767 - Object key names are not in quotes.
4768 - v:none items in an array result in an empty item between
4769 commas.
4770 For example, the Vim object:
4771 [1,v:none,{"one":1},v:none] ~
4772 Will be encoded as:
4773 [1,,{one:1},,] ~
4774 While json_encode() would produce:
4775 [1,null,{"one":1},null] ~
4776 This encoding is valid for JavaScript. It is more efficient
4777 than JSON, especially when using an array with optional items.
4778
4779 Can also be used as a |method|: >
4780 GetObject()->js_encode()
4781
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00004782json_decode({string}) *json_decode()* *E491*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004783 This parses a JSON formatted string and returns the equivalent
4784 in Vim values. See |json_encode()| for the relation between
4785 JSON and Vim values.
4786 The decoding is permissive:
4787 - A trailing comma in an array and object is ignored, e.g.
4788 "[1, 2, ]" is the same as "[1, 2]".
4789 - Integer keys are accepted in objects, e.g. {1:2} is the
4790 same as {"1":2}.
4791 - More floating point numbers are recognized, e.g. "1." for
4792 "1.0", or "001.2" for "1.2". Special floating point values
4793 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
4794 are accepted.
4795 - Leading zeroes in integer numbers are ignored, e.g. "012"
4796 for "12" or "-012" for "-12".
4797 - Capitalization is ignored in literal names null, true or
4798 false, e.g. "NULL" for "null", "True" for "true".
4799 - Control characters U+0000 through U+001F which are not
4800 escaped in strings are accepted, e.g. " " (tab
4801 character in string) for "\t".
4802 - An empty JSON expression or made of only spaces is accepted
4803 and results in v:none.
4804 - Backslash in an invalid 2-character sequence escape is
4805 ignored, e.g. "\a" is decoded as "a".
4806 - A correct surrogate pair in JSON strings should normally be
4807 a 12 character sequence such as "\uD834\uDD1E", but
4808 json_decode() silently accepts truncated surrogate pairs
4809 such as "\uD834" or "\uD834\u"
4810 *E938*
4811 A duplicate key in an object, valid in rfc7159, is not
4812 accepted by json_decode() as the result must be a valid Vim
4813 type, e.g. this fails: {"a":"b", "a":"c"}
4814
4815 Can also be used as a |method|: >
4816 ReadObject()->json_decode()
4817
4818json_encode({expr}) *json_encode()*
4819 Encode {expr} as JSON and return this as a string.
4820 The encoding is specified in:
4821 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaara2baa732022-02-04 16:09:54 +00004822 Vim values are converted as follows: *E1161*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004823 |Number| decimal number
4824 |Float| floating point number
4825 Float nan "NaN"
4826 Float inf "Infinity"
4827 Float -inf "-Infinity"
4828 |String| in double quotes (possibly null)
4829 |Funcref| not possible, error
4830 |List| as an array (possibly null); when
4831 used recursively: []
4832 |Dict| as an object (possibly null); when
4833 used recursively: {}
4834 |Blob| as an array of the individual bytes
4835 v:false "false"
4836 v:true "true"
4837 v:none "null"
4838 v:null "null"
4839 Note that NaN and Infinity are passed on as values. This is
4840 missing in the JSON standard, but several implementations do
4841 allow it. If not then you will get an error.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004842 If a string contains an illegal character then the replacement
4843 character 0xfffd is used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004844
4845 Can also be used as a |method|: >
4846 GetObject()->json_encode()
4847
4848keys({dict}) *keys()*
4849 Return a |List| with all the keys of {dict}. The |List| is in
4850 arbitrary order. Also see |items()| and |values()|.
4851
4852 Can also be used as a |method|: >
4853 mydict->keys()
4854
4855< *len()* *E701*
4856len({expr}) The result is a Number, which is the length of the argument.
4857 When {expr} is a String or a Number the length in bytes is
4858 used, as with |strlen()|.
4859 When {expr} is a |List| the number of items in the |List| is
4860 returned.
4861 When {expr} is a |Blob| the number of bytes is returned.
4862 When {expr} is a |Dictionary| the number of entries in the
4863 |Dictionary| is returned.
4864 Otherwise an error is given.
4865
4866 Can also be used as a |method|: >
4867 mylist->len()
4868
4869< *libcall()* *E364* *E368*
4870libcall({libname}, {funcname}, {argument})
4871 Call function {funcname} in the run-time library {libname}
4872 with single argument {argument}.
4873 This is useful to call functions in a library that you
4874 especially made to be used with Vim. Since only one argument
4875 is possible, calling standard library functions is rather
4876 limited.
4877 The result is the String returned by the function. If the
4878 function returns NULL, this will appear as an empty string ""
4879 to Vim.
4880 If the function returns a number, use libcallnr()!
4881 If {argument} is a number, it is passed to the function as an
4882 int; if {argument} is a string, it is passed as a
4883 null-terminated string.
4884 This function will fail in |restricted-mode|.
4885
4886 libcall() allows you to write your own 'plug-in' extensions to
4887 Vim without having to recompile the program. It is NOT a
4888 means to call system functions! If you try to do so Vim will
4889 very probably crash.
4890
4891 For Win32, the functions you write must be placed in a DLL
4892 and use the normal C calling convention (NOT Pascal which is
4893 used in Windows System DLLs). The function must take exactly
4894 one parameter, either a character pointer or a long integer,
4895 and must return a character pointer or NULL. The character
4896 pointer returned must point to memory that will remain valid
4897 after the function has returned (e.g. in static data in the
4898 DLL). If it points to allocated memory, that memory will
4899 leak away. Using a static buffer in the function should work,
4900 it's then freed when the DLL is unloaded.
4901
4902 WARNING: If the function returns a non-valid pointer, Vim may
4903 crash! This also happens if the function returns a number,
4904 because Vim thinks it's a pointer.
4905 For Win32 systems, {libname} should be the filename of the DLL
4906 without the ".DLL" suffix. A full path is only required if
4907 the DLL is not in the usual places.
4908 For Unix: When compiling your own plugins, remember that the
4909 object code must be compiled as position-independent ('PIC').
4910 {only in Win32 and some Unix versions, when the |+libcall|
4911 feature is present}
4912 Examples: >
4913 :echo libcall("libc.so", "getenv", "HOME")
4914
4915< Can also be used as a |method|, the base is passed as the
4916 third argument: >
4917 GetValue()->libcall("libc.so", "getenv")
4918<
4919 *libcallnr()*
4920libcallnr({libname}, {funcname}, {argument})
4921 Just like |libcall()|, but used for a function that returns an
4922 int instead of a string.
4923 {only in Win32 on some Unix versions, when the |+libcall|
4924 feature is present}
4925 Examples: >
4926 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
4927 :call libcallnr("libc.so", "printf", "Hello World!\n")
4928 :call libcallnr("libc.so", "sleep", 10)
4929<
4930 Can also be used as a |method|, the base is passed as the
4931 third argument: >
4932 GetValue()->libcallnr("libc.so", "printf")
4933<
4934
4935line({expr} [, {winid}]) *line()*
4936 The result is a Number, which is the line number of the file
4937 position given with {expr}. The {expr} argument is a string.
Bram Moolenaara2baa732022-02-04 16:09:54 +00004938 The accepted positions are: *E1209*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004939 . the cursor position
4940 $ the last line in the current buffer
4941 'x position of mark x (if the mark is not set, 0 is
4942 returned)
4943 w0 first line visible in current window (one if the
4944 display isn't updated, e.g. in silent Ex mode)
4945 w$ last line visible in current window (this is one
4946 less than "w0" if no lines are visible)
4947 v In Visual mode: the start of the Visual area (the
4948 cursor is the end). When not in Visual mode
4949 returns the cursor position. Differs from |'<| in
4950 that it's updated right away.
4951 Note that a mark in another file can be used. The line number
4952 then applies to another buffer.
4953 To get the column number use |col()|. To get both use
4954 |getpos()|.
4955 With the optional {winid} argument the values are obtained for
4956 that window instead of the current window.
4957 Examples: >
4958 line(".") line number of the cursor
4959 line(".", winid) idem, in window "winid"
4960 line("'t") line number of mark t
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004961 line("'" .. marker) line number of mark marker
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00004962<
4963 To jump to the last known position when opening a file see
4964 |last-position-jump|.
4965
4966 Can also be used as a |method|: >
4967 GetValue()->line()
4968
4969line2byte({lnum}) *line2byte()*
4970 Return the byte count from the start of the buffer for line
4971 {lnum}. This includes the end-of-line character, depending on
4972 the 'fileformat' option for the current buffer. The first
4973 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
4974 This can also be used to get the byte count for the line just
4975 below the last line: >
4976 line2byte(line("$") + 1)
4977< This is the buffer size plus one. If 'fileencoding' is empty
4978 it is the file size plus one. {lnum} is used like with
4979 |getline()|. When {lnum} is invalid, or the |+byte_offset|
4980 feature has been disabled at compile time, -1 is returned.
4981 Also see |byte2line()|, |go| and |:goto|.
4982
4983 Can also be used as a |method|: >
4984 GetLnum()->line2byte()
4985
4986lispindent({lnum}) *lispindent()*
4987 Get the amount of indent for line {lnum} according the lisp
4988 indenting rules, as with 'lisp'.
4989 The indent is counted in spaces, the value of 'tabstop' is
4990 relevant. {lnum} is used just like in |getline()|.
4991 When {lnum} is invalid or Vim was not compiled the
4992 |+lispindent| feature, -1 is returned. In |Vim9| script an
4993 error is given.
4994
4995 Can also be used as a |method|: >
4996 GetLnum()->lispindent()
4997
4998list2blob({list}) *list2blob()*
4999 Return a Blob concatenating all the number values in {list}.
5000 Examples: >
5001 list2blob([1, 2, 3, 4]) returns 0z01020304
5002 list2blob([]) returns 0z
5003< Returns an empty Blob on error. If one of the numbers is
5004 negative or more than 255 error *E1239* is given.
5005
5006 |blob2list()| does the opposite.
5007
5008 Can also be used as a |method|: >
5009 GetList()->list2blob()
5010
5011list2str({list} [, {utf8}]) *list2str()*
5012 Convert each number in {list} to a character string can
5013 concatenate them all. Examples: >
5014 list2str([32]) returns " "
5015 list2str([65, 66, 67]) returns "ABC"
5016< The same can be done (slowly) with: >
5017 join(map(list, {nr, val -> nr2char(val)}), '')
5018< |str2list()| does the opposite.
5019
5020 When {utf8} is omitted or zero, the current 'encoding' is used.
5021 When {utf8} is TRUE, always return UTF-8 characters.
5022 With UTF-8 composing characters work as expected: >
5023 list2str([97, 769]) returns "á"
5024<
5025 Can also be used as a |method|: >
5026 GetList()->list2str()
5027
5028listener_add({callback} [, {buf}]) *listener_add()*
5029 Add a callback function that will be invoked when changes have
5030 been made to buffer {buf}.
5031 {buf} refers to a buffer name or number. For the accepted
5032 values, see |bufname()|. When {buf} is omitted the current
5033 buffer is used.
5034 Returns a unique ID that can be passed to |listener_remove()|.
5035
5036 The {callback} is invoked with five arguments:
Bram Moolenaar944697a2022-02-20 19:48:20 +00005037 bufnr the buffer that was changed
5038 start first changed line number
5039 end first line number below the change
5040 added number of lines added, negative if lines were
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005041 deleted
Bram Moolenaar944697a2022-02-20 19:48:20 +00005042 changes a List of items with details about the changes
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005043
5044 Example: >
5045 func Listener(bufnr, start, end, added, changes)
5046 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
5047 endfunc
5048 call listener_add('Listener', bufnr)
5049
Bram Moolenaar944697a2022-02-20 19:48:20 +00005050< The List cannot be changed. Each item in "changes" is a
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005051 dictionary with these entries:
5052 lnum the first line number of the change
5053 end the first line below the change
5054 added number of lines added; negative if lines were
5055 deleted
5056 col first column in "lnum" that was affected by
5057 the change; one if unknown or the whole line
5058 was affected; this is a byte index, first
5059 character has a value of one.
5060 When lines are inserted the values are:
5061 lnum line above which the new line is added
5062 end equal to "lnum"
5063 added number of lines inserted
5064 col 1
5065 When lines are deleted the values are:
5066 lnum the first deleted line
5067 end the line below the first deleted line, before
5068 the deletion was done
5069 added negative, number of lines deleted
5070 col 1
5071 When lines are changed:
5072 lnum the first changed line
5073 end the line below the last changed line
5074 added 0
5075 col first column with a change or 1
5076
5077 The entries are in the order the changes were made, thus the
5078 most recent change is at the end. The line numbers are valid
5079 when the callback is invoked, but later changes may make them
5080 invalid, thus keeping a copy for later might not work.
5081
5082 The {callback} is invoked just before the screen is updated,
5083 when |listener_flush()| is called or when a change is being
5084 made that changes the line count in a way it causes a line
5085 number in the list of changes to become invalid.
5086
5087 The {callback} is invoked with the text locked, see
5088 |textlock|. If you do need to make changes to the buffer, use
5089 a timer to do this later |timer_start()|.
5090
5091 The {callback} is not invoked when the buffer is first loaded.
5092 Use the |BufReadPost| autocmd event to handle the initial text
5093 of a buffer.
5094 The {callback} is also not invoked when the buffer is
5095 unloaded, use the |BufUnload| autocmd event for that.
5096
5097 Can also be used as a |method|, the base is passed as the
5098 second argument: >
5099 GetBuffer()->listener_add(callback)
5100
5101listener_flush([{buf}]) *listener_flush()*
5102 Invoke listener callbacks for buffer {buf}. If there are no
5103 pending changes then no callbacks are invoked.
5104
5105 {buf} refers to a buffer name or number. For the accepted
5106 values, see |bufname()|. When {buf} is omitted the current
5107 buffer is used.
5108
5109 Can also be used as a |method|: >
5110 GetBuffer()->listener_flush()
5111
5112listener_remove({id}) *listener_remove()*
5113 Remove a listener previously added with listener_add().
5114 Returns FALSE when {id} could not be found, TRUE when {id} was
5115 removed.
5116
5117 Can also be used as a |method|: >
5118 GetListenerId()->listener_remove()
5119
5120localtime() *localtime()*
5121 Return the current time, measured as seconds since 1st Jan
5122 1970. See also |strftime()|, |strptime()| and |getftime()|.
5123
5124
5125log({expr}) *log()*
5126 Return the natural logarithm (base e) of {expr} as a |Float|.
5127 {expr} must evaluate to a |Float| or a |Number| in the range
5128 (0, inf].
5129 Examples: >
5130 :echo log(10)
5131< 2.302585 >
5132 :echo log(exp(5))
5133< 5.0
5134
5135 Can also be used as a |method|: >
5136 Compute()->log()
5137<
5138 {only available when compiled with the |+float| feature}
5139
5140
5141log10({expr}) *log10()*
5142 Return the logarithm of Float {expr} to base 10 as a |Float|.
5143 {expr} must evaluate to a |Float| or a |Number|.
5144 Examples: >
5145 :echo log10(1000)
5146< 3.0 >
5147 :echo log10(0.01)
5148< -2.0
5149
5150 Can also be used as a |method|: >
5151 Compute()->log10()
5152<
5153 {only available when compiled with the |+float| feature}
5154
5155luaeval({expr} [, {expr}]) *luaeval()*
5156 Evaluate Lua expression {expr} and return its result converted
5157 to Vim data structures. Second {expr} may hold additional
5158 argument accessible as _A inside first {expr}.
5159 Strings are returned as they are.
5160 Boolean objects are converted to numbers.
5161 Numbers are converted to |Float| values if vim was compiled
5162 with |+float| and to numbers otherwise.
5163 Dictionaries and lists obtained by vim.eval() are returned
5164 as-is.
5165 Other objects are returned as zero without any errors.
5166 See |lua-luaeval| for more details.
5167 Note that in a `:def` function local variables are not visible
5168 to {expr}.
5169
5170 Can also be used as a |method|: >
5171 GetExpr()->luaeval()
5172
5173< {only available when compiled with the |+lua| feature}
5174
5175map({expr1}, {expr2}) *map()*
5176 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
Bram Moolenaar944697a2022-02-20 19:48:20 +00005177 When {expr1} is a |List| or |Dictionary|, replace each
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005178 item in {expr1} with the result of evaluating {expr2}.
5179 For a |Blob| each byte is replaced.
5180 For a |String|, each character, including composing
5181 characters, is replaced.
5182 If the item type changes you may want to use |mapnew()| to
5183 create a new List or Dictionary. This is required when using
5184 Vim9 script.
5185
5186 {expr2} must be a |String| or |Funcref|.
5187
5188 If {expr2} is a |String|, inside {expr2} |v:val| has the value
5189 of the current item. For a |Dictionary| |v:key| has the key
5190 of the current item and for a |List| |v:key| has the index of
5191 the current item. For a |Blob| |v:key| has the index of the
5192 current byte. For a |String| |v:key| has the index of the
5193 current character.
5194 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005195 :call map(mylist, '"> " .. v:val .. " <"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005196< This puts "> " before and " <" after each item in "mylist".
5197
5198 Note that {expr2} is the result of an expression and is then
5199 used as an expression again. Often it is good to use a
5200 |literal-string| to avoid having to double backslashes. You
5201 still have to double ' quotes
5202
5203 If {expr2} is a |Funcref| it is called with two arguments:
5204 1. The key or the index of the current item.
5205 2. the value of the current item.
5206 The function must return the new value of the item. Example
5207 that changes each value by "key-value": >
5208 func KeyValue(key, val)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005209 return a:key .. '-' .. a:val
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005210 endfunc
5211 call map(myDict, function('KeyValue'))
5212< It is shorter when using a |lambda|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005213 call map(myDict, {key, val -> key .. '-' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005214< If you do not use "val" you can leave it out: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005215 call map(myDict, {key -> 'item: ' .. key})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005216< If you do not use "key" you can use a short name: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005217 call map(myDict, {_, val -> 'item: ' .. val})
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005218<
5219 The operation is done in-place for a |List| and |Dictionary|.
5220 If you want it to remain unmodified make a copy first: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005221 :let tlist = map(copy(mylist), ' v:val .. "\t"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005222
5223< Returns {expr1}, the |List| or |Dictionary| that was filtered,
5224 or a new |Blob| or |String|.
5225 When an error is encountered while evaluating {expr2} no
5226 further items in {expr1} are processed.
5227 When {expr2} is a Funcref errors inside a function are ignored,
5228 unless it was defined with the "abort" flag.
5229
5230 Can also be used as a |method|: >
5231 mylist->map(expr2)
5232
5233
5234maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5235 When {dict} is omitted or zero: Return the rhs of mapping
5236 {name} in mode {mode}. The returned String has special
5237 characters translated like in the output of the ":map" command
5238 listing.
5239
5240 When there is no mapping for {name}, an empty String is
5241 returned. When the mapping for {name} is empty, then "<Nop>"
5242 is returned.
5243
5244 The {name} can have special key names, like in the ":map"
5245 command.
5246
5247 {mode} can be one of these strings:
5248 "n" Normal
5249 "v" Visual (including Select)
5250 "o" Operator-pending
5251 "i" Insert
5252 "c" Cmd-line
5253 "s" Select
5254 "x" Visual
5255 "l" langmap |language-mapping|
5256 "t" Terminal-Job
5257 "" Normal, Visual and Operator-pending
5258 When {mode} is omitted, the modes for "" are used.
5259
5260 When {abbr} is there and it is |TRUE| use abbreviations
5261 instead of mappings.
5262
5263 When {dict} is there and it is |TRUE| return a dictionary
5264 containing all the information of the mapping with the
5265 following items:
5266 "lhs" The {lhs} of the mapping as it would be typed
5267 "lhsraw" The {lhs} of the mapping as raw bytes
5268 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
5269 form, only present when it differs from "lhsraw"
5270 "rhs" The {rhs} of the mapping as typed.
5271 "silent" 1 for a |:map-silent| mapping, else 0.
5272 "noremap" 1 if the {rhs} of the mapping is not remappable.
5273 "script" 1 if mapping was defined with <script>.
5274 "expr" 1 for an expression mapping (|:map-<expr>|).
5275 "buffer" 1 for a buffer local mapping (|:map-local|).
5276 "mode" Modes for which the mapping is defined. In
5277 addition to the modes mentioned above, these
5278 characters will be used:
5279 " " Normal, Visual and Operator-pending
5280 "!" Insert and Commandline mode
5281 (|mapmode-ic|)
5282 "sid" The script local ID, used for <sid> mappings
5283 (|<SID>|).
Bram Moolenaara9528b32022-01-18 20:51:35 +00005284 "scriptversion" The version of the script. 999999 for
5285 |Vim9| script.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005286 "lnum" The line number in "sid", zero if unknown.
5287 "nowait" Do not wait for other, longer mappings.
5288 (|:map-<nowait>|).
5289
5290 The dictionary can be used to restore a mapping with
5291 |mapset()|.
5292
5293 The mappings local to the current buffer are checked first,
5294 then the global mappings.
5295 This function can be used to map a key even when it's already
5296 mapped, and have it do the original mapping too. Sketch: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005297 exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005298
5299< Can also be used as a |method|: >
5300 GetKey()->maparg('n')
5301
5302mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
5303 Check if there is a mapping that matches with {name} in mode
5304 {mode}. See |maparg()| for {mode} and special names in
5305 {name}.
5306 When {abbr} is there and it is |TRUE| use abbreviations
5307 instead of mappings.
5308 A match happens with a mapping that starts with {name} and
5309 with a mapping which is equal to the start of {name}.
5310
5311 matches mapping "a" "ab" "abc" ~
5312 mapcheck("a") yes yes yes
5313 mapcheck("abc") yes yes yes
5314 mapcheck("ax") yes no no
5315 mapcheck("b") no no no
5316
5317 The difference with maparg() is that mapcheck() finds a
5318 mapping that matches with {name}, while maparg() only finds a
5319 mapping for {name} exactly.
5320 When there is no mapping that starts with {name}, an empty
5321 String is returned. If there is one, the RHS of that mapping
5322 is returned. If there are several mappings that start with
5323 {name}, the RHS of one of them is returned. This will be
5324 "<Nop>" if the RHS is empty.
5325 The mappings local to the current buffer are checked first,
5326 then the global mappings.
5327 This function can be used to check if a mapping can be added
5328 without being ambiguous. Example: >
5329 :if mapcheck("_vv") == ""
5330 : map _vv :set guifont=7x13<CR>
5331 :endif
5332< This avoids adding the "_vv" mapping when there already is a
5333 mapping for "_v" or for "_vvv".
5334
5335 Can also be used as a |method|: >
5336 GetKey()->mapcheck('n')
5337
5338
5339mapnew({expr1}, {expr2}) *mapnew()*
5340 Like |map()| but instead of replacing items in {expr1} a new
5341 List or Dictionary is created and returned. {expr1} remains
5342 unchanged. Items can still be changed by {expr2}, if you
5343 don't want that use |deepcopy()| first.
5344
5345
5346mapset({mode}, {abbr}, {dict}) *mapset()*
5347 Restore a mapping from a dictionary returned by |maparg()|.
5348 {mode} and {abbr} should be the same as for the call to
5349 |maparg()|. *E460*
5350 {mode} is used to define the mode in which the mapping is set,
5351 not the "mode" entry in {dict}.
5352 Example for saving and restoring a mapping: >
5353 let save_map = maparg('K', 'n', 0, 1)
5354 nnoremap K somethingelse
5355 ...
5356 call mapset('n', 0, save_map)
5357< Note that if you are going to replace a map in several modes,
5358 e.g. with `:map!`, you need to save the mapping for all of
5359 them, since they can differ.
5360
5361
5362match({expr}, {pat} [, {start} [, {count}]]) *match()*
5363 When {expr} is a |List| then this returns the index of the
5364 first item where {pat} matches. Each item is used as a
5365 String, |Lists| and |Dictionaries| are used as echoed.
5366
5367 Otherwise, {expr} is used as a String. The result is a
5368 Number, which gives the index (byte offset) in {expr} where
5369 {pat} matches.
5370
5371 A match at the first character or |List| item returns zero.
5372 If there is no match -1 is returned.
5373
5374 For getting submatches see |matchlist()|.
5375 Example: >
5376 :echo match("testing", "ing") " results in 4
5377 :echo match([1, 'x'], '\a') " results in 1
5378< See |string-match| for how {pat} is used.
5379 *strpbrk()*
5380 Vim doesn't have a strpbrk() function. But you can do: >
5381 :let sepidx = match(line, '[.,;: \t]')
5382< *strcasestr()*
5383 Vim doesn't have a strcasestr() function. But you can add
5384 "\c" to the pattern to ignore case: >
5385 :let idx = match(haystack, '\cneedle')
5386<
5387 If {start} is given, the search starts from byte index
5388 {start} in a String or item {start} in a |List|.
5389 The result, however, is still the index counted from the
5390 first character/item. Example: >
5391 :echo match("testing", "ing", 2)
5392< result is again "4". >
5393 :echo match("testing", "ing", 4)
5394< result is again "4". >
5395 :echo match("testing", "t", 2)
5396< result is "3".
5397 For a String, if {start} > 0 then it is like the string starts
5398 {start} bytes later, thus "^" will match at {start}. Except
5399 when {count} is given, then it's like matches before the
5400 {start} byte are ignored (this is a bit complicated to keep it
5401 backwards compatible).
5402 For a String, if {start} < 0, it will be set to 0. For a list
5403 the index is counted from the end.
5404 If {start} is out of range ({start} > strlen({expr}) for a
5405 String or {start} > len({expr}) for a |List|) -1 is returned.
5406
5407 When {count} is given use the {count}'th match. When a match
5408 is found in a String the search for the next one starts one
5409 character further. Thus this example results in 1: >
5410 echo match("testing", "..", 0, 2)
5411< In a |List| the search continues in the next item.
5412 Note that when {count} is added the way {start} works changes,
5413 see above.
5414
5415 See |pattern| for the patterns that are accepted.
5416 The 'ignorecase' option is used to set the ignore-caseness of
5417 the pattern. 'smartcase' is NOT used. The matching is always
5418 done like 'magic' is set and 'cpoptions' is empty.
5419 Note that a match at the start is preferred, thus when the
5420 pattern is using "*" (any number of matches) it tends to find
5421 zero matches at the start instead of a number of matches
5422 further down in the text.
5423
5424 Can also be used as a |method|: >
5425 GetText()->match('word')
5426 GetList()->match('word')
5427<
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005428 *matchadd()* *E290* *E798* *E799* *E801* *E957*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005429matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
5430 Defines a pattern to be highlighted in the current window (a
5431 "match"). It will be highlighted with {group}. Returns an
5432 identification number (ID), which can be used to delete the
5433 match using |matchdelete()|. The ID is bound to the window.
5434 Matching is case sensitive and magic, unless case sensitivity
5435 or magicness are explicitly overridden in {pattern}. The
5436 'magic', 'smartcase' and 'ignorecase' options are not used.
5437 The "Conceal" value is special, it causes the match to be
5438 concealed.
5439
5440 The optional {priority} argument assigns a priority to the
5441 match. A match with a high priority will have its
5442 highlighting overrule that of a match with a lower priority.
5443 A priority is specified as an integer (negative numbers are no
5444 exception). If the {priority} argument is not specified, the
5445 default priority is 10. The priority of 'hlsearch' is zero,
5446 hence all matches with a priority greater than zero will
5447 overrule it. Syntax highlighting (see 'syntax') is a separate
5448 mechanism, and regardless of the chosen priority a match will
5449 always overrule syntax highlighting.
5450
5451 The optional {id} argument allows the request for a specific
5452 match ID. If a specified ID is already taken, an error
5453 message will appear and the match will not be added. An ID
5454 is specified as a positive integer (zero excluded). IDs 1, 2
5455 and 3 are reserved for |:match|, |:2match| and |:3match|,
5456 respectively. If the {id} argument is not specified or -1,
5457 |matchadd()| automatically chooses a free ID.
5458
5459 The optional {dict} argument allows for further custom
5460 values. Currently this is used to specify a match specific
5461 conceal character that will be shown for |hl-Conceal|
5462 highlighted matches. The dict can have the following members:
5463
5464 conceal Special character to show instead of the
5465 match (only for |hl-Conceal| highlighted
5466 matches, see |:syn-cchar|)
5467 window Instead of the current window use the
5468 window with this number or window ID.
5469
5470 The number of matches is not limited, as it is the case with
5471 the |:match| commands.
5472
5473 Example: >
5474 :highlight MyGroup ctermbg=green guibg=green
5475 :let m = matchadd("MyGroup", "TODO")
5476< Deletion of the pattern: >
5477 :call matchdelete(m)
5478
5479< A list of matches defined by |matchadd()| and |:match| are
5480 available from |getmatches()|. All matches can be deleted in
5481 one operation by |clearmatches()|.
5482
5483 Can also be used as a |method|: >
5484 GetGroup()->matchadd('TODO')
5485<
5486 *matchaddpos()*
5487matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
5488 Same as |matchadd()|, but requires a list of positions {pos}
5489 instead of a pattern. This command is faster than |matchadd()|
5490 because it does not require to handle regular expressions and
5491 sets buffer line boundaries to redraw screen. It is supposed
5492 to be used when fast match additions and deletions are
5493 required, for example to highlight matching parentheses.
5494
5495 {pos} is a list of positions. Each position can be one of
5496 these:
5497 - A number. This whole line will be highlighted. The first
5498 line has number 1.
5499 - A list with one number, e.g., [23]. The whole line with this
5500 number will be highlighted.
5501 - A list with two numbers, e.g., [23, 11]. The first number is
5502 the line number, the second one is the column number (first
5503 column is 1, the value must correspond to the byte index as
5504 |col()| would return). The character at this position will
5505 be highlighted.
5506 - A list with three numbers, e.g., [23, 11, 3]. As above, but
5507 the third number gives the length of the highlight in bytes.
5508
5509 The maximum number of positions in {pos} is 8.
5510
5511 Example: >
5512 :highlight MyGroup ctermbg=green guibg=green
5513 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5514< Deletion of the pattern: >
5515 :call matchdelete(m)
5516
5517< Matches added by |matchaddpos()| are returned by
5518 |getmatches()|.
5519
5520 Can also be used as a |method|: >
5521 GetGroup()->matchaddpos([23, 11])
5522
5523matcharg({nr}) *matcharg()*
5524 Selects the {nr} match item, as set with a |:match|,
5525 |:2match| or |:3match| command.
5526 Return a |List| with two elements:
5527 The name of the highlight group used
5528 The pattern used.
5529 When {nr} is not 1, 2 or 3 returns an empty |List|.
5530 When there is no match item set returns ['', ''].
5531 This is useful to save and restore a |:match|.
5532 Highlighting matches using the |:match| commands are limited
5533 to three matches. |matchadd()| does not have this limitation.
5534
5535 Can also be used as a |method|: >
5536 GetMatch()->matcharg()
5537
5538matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
5539 Deletes a match with ID {id} previously defined by |matchadd()|
5540 or one of the |:match| commands. Returns 0 if successful,
5541 otherwise -1. See example for |matchadd()|. All matches can
5542 be deleted in one operation by |clearmatches()|.
5543 If {win} is specified, use the window with this number or
5544 window ID instead of the current window.
5545
5546 Can also be used as a |method|: >
5547 GetMatch()->matchdelete()
5548
5549matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
5550 Same as |match()|, but return the index of first character
5551 after the match. Example: >
5552 :echo matchend("testing", "ing")
5553< results in "7".
5554 *strspn()* *strcspn()*
5555 Vim doesn't have a strspn() or strcspn() function, but you can
5556 do it with matchend(): >
5557 :let span = matchend(line, '[a-zA-Z]')
5558 :let span = matchend(line, '[^a-zA-Z]')
5559< Except that -1 is returned when there are no matches.
5560
5561 The {start}, if given, has the same meaning as for |match()|. >
5562 :echo matchend("testing", "ing", 2)
5563< results in "7". >
5564 :echo matchend("testing", "ing", 5)
5565< result is "-1".
5566 When {expr} is a |List| the result is equal to |match()|.
5567
5568 Can also be used as a |method|: >
5569 GetText()->matchend('word')
5570
5571
5572matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
5573 If {list} is a list of strings, then returns a |List| with all
5574 the strings in {list} that fuzzy match {str}. The strings in
5575 the returned list are sorted based on the matching score.
5576
5577 The optional {dict} argument always supports the following
5578 items:
5579 matchseq When this item is present and {str} contains
5580 multiple words separated by white space, then
5581 returns only matches that contain the words in
5582 the given sequence.
5583
5584 If {list} is a list of dictionaries, then the optional {dict}
5585 argument supports the following additional items:
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01005586 key Key of the item which is fuzzy matched against
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005587 {str}. The value of this item should be a
5588 string.
5589 text_cb |Funcref| that will be called for every item
5590 in {list} to get the text for fuzzy matching.
5591 This should accept a dictionary item as the
5592 argument and return the text for that item to
5593 use for fuzzy matching.
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01005594 limit Maximum number of matches in {list} to be
5595 returned. Zero means no limit.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005596
5597 {str} is treated as a literal string and regular expression
5598 matching is NOT supported. The maximum supported {str} length
5599 is 256.
5600
5601 When {str} has multiple words each separated by white space,
5602 then the list of strings that have all the words is returned.
5603
5604 If there are no matching strings or there is an error, then an
5605 empty list is returned. If length of {str} is greater than
5606 256, then returns an empty list.
5607
Yasuhiro Matsumoto9029a6e2022-04-16 12:35:35 +01005608 When {limit} is given, matchfuzzy() will find up to this
5609 number of matches in {list} and return them in sorted order.
5610
Bram Moolenaar1588bc82022-03-08 21:35:07 +00005611 Refer to |fuzzy-matching| for more information about fuzzy
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005612 matching strings.
5613
5614 Example: >
5615 :echo matchfuzzy(["clay", "crow"], "cay")
5616< results in ["clay"]. >
5617 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
5618< results in a list of buffer names fuzzy matching "ndl". >
5619 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
5620< results in a list of buffer information dicts with buffer
5621 names fuzzy matching "ndl". >
5622 :echo getbufinfo()->matchfuzzy("spl",
5623 \ {'text_cb' : {v -> v.name}})
5624< results in a list of buffer information dicts with buffer
5625 names fuzzy matching "spl". >
5626 :echo v:oldfiles->matchfuzzy("test")
5627< results in a list of file names fuzzy matching "test". >
5628 :let l = readfile("buffer.c")->matchfuzzy("str")
5629< results in a list of lines in "buffer.c" fuzzy matching "str". >
5630 :echo ['one two', 'two one']->matchfuzzy('two one')
5631< results in ['two one', 'one two']. >
5632 :echo ['one two', 'two one']->matchfuzzy('two one',
5633 \ {'matchseq': 1})
5634< results in ['two one'].
5635
5636matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
5637 Same as |matchfuzzy()|, but returns the list of matched
5638 strings, the list of character positions where characters
5639 in {str} matches and a list of matching scores. You can
5640 use |byteidx()| to convert a character position to a byte
5641 position.
5642
5643 If {str} matches multiple times in a string, then only the
5644 positions for the best match is returned.
5645
5646 If there are no matching strings or there is an error, then a
5647 list with three empty list items is returned.
5648
5649 Example: >
5650 :echo matchfuzzypos(['testing'], 'tsg')
5651< results in [['testing'], [[0, 2, 6]], [99]] >
5652 :echo matchfuzzypos(['clay', 'lacy'], 'la')
5653< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
5654 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
5655< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
5656
5657matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
5658 Same as |match()|, but return a |List|. The first item in the
5659 list is the matched string, same as what matchstr() would
5660 return. Following items are submatches, like "\1", "\2", etc.
5661 in |:substitute|. When an optional submatch didn't match an
5662 empty string is used. Example: >
5663 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5664< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
5665 When there is no match an empty list is returned.
5666
5667 You can pass in a List, but that is not very useful.
5668
5669 Can also be used as a |method|: >
5670 GetText()->matchlist('word')
5671
5672matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
5673 Same as |match()|, but return the matched string. Example: >
5674 :echo matchstr("testing", "ing")
5675< results in "ing".
5676 When there is no match "" is returned.
5677 The {start}, if given, has the same meaning as for |match()|. >
5678 :echo matchstr("testing", "ing", 2)
5679< results in "ing". >
5680 :echo matchstr("testing", "ing", 5)
5681< result is "".
5682 When {expr} is a |List| then the matching item is returned.
5683 The type isn't changed, it's not necessarily a String.
5684
5685 Can also be used as a |method|: >
5686 GetText()->matchstr('word')
5687
5688matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
5689 Same as |matchstr()|, but return the matched string, the start
5690 position and the end position of the match. Example: >
5691 :echo matchstrpos("testing", "ing")
5692< results in ["ing", 4, 7].
5693 When there is no match ["", -1, -1] is returned.
5694 The {start}, if given, has the same meaning as for |match()|. >
5695 :echo matchstrpos("testing", "ing", 2)
5696< results in ["ing", 4, 7]. >
5697 :echo matchstrpos("testing", "ing", 5)
5698< result is ["", -1, -1].
5699 When {expr} is a |List| then the matching item, the index
5700 of first item where {pat} matches, the start position and the
5701 end position of the match are returned. >
5702 :echo matchstrpos([1, '__x'], '\a')
5703< result is ["x", 1, 2, 3].
5704 The type isn't changed, it's not necessarily a String.
5705
5706 Can also be used as a |method|: >
5707 GetText()->matchstrpos('word')
5708<
5709
5710 *max()*
5711max({expr}) Return the maximum value of all items in {expr}. Example: >
5712 echo max([apples, pears, oranges])
5713
5714< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5715 it returns the maximum of all values in the Dictionary.
5716 If {expr} is neither a List nor a Dictionary, or one of the
5717 items in {expr} cannot be used as a Number this results in
5718 an error. An empty |List| or |Dictionary| results in zero.
5719
5720 Can also be used as a |method|: >
5721 mylist->max()
5722
5723
5724menu_info({name} [, {mode}]) *menu_info()*
5725 Return information about the specified menu {name} in
5726 mode {mode}. The menu name should be specified without the
5727 shortcut character ('&'). If {name} is "", then the top-level
5728 menu names are returned.
5729
5730 {mode} can be one of these strings:
5731 "n" Normal
5732 "v" Visual (including Select)
5733 "o" Operator-pending
5734 "i" Insert
5735 "c" Cmd-line
5736 "s" Select
5737 "x" Visual
5738 "t" Terminal-Job
5739 "" Normal, Visual and Operator-pending
5740 "!" Insert and Cmd-line
5741 When {mode} is omitted, the modes for "" are used.
5742
5743 Returns a |Dictionary| containing the following items:
5744 accel menu item accelerator text |menu-text|
5745 display display name (name without '&')
5746 enabled v:true if this menu item is enabled
5747 Refer to |:menu-enable|
5748 icon name of the icon file (for toolbar)
5749 |toolbar-icon|
5750 iconidx index of a built-in icon
5751 modes modes for which the menu is defined. In
5752 addition to the modes mentioned above, these
5753 characters will be used:
5754 " " Normal, Visual and Operator-pending
5755 name menu item name.
5756 noremenu v:true if the {rhs} of the menu item is not
5757 remappable else v:false.
5758 priority menu order priority |menu-priority|
5759 rhs right-hand-side of the menu item. The returned
5760 string has special characters translated like
5761 in the output of the ":menu" command listing.
5762 When the {rhs} of a menu item is empty, then
5763 "<Nop>" is returned.
5764 script v:true if script-local remapping of {rhs} is
5765 allowed else v:false. See |:menu-script|.
5766 shortcut shortcut key (character after '&' in
5767 the menu name) |menu-shortcut|
5768 silent v:true if the menu item is created
5769 with <silent> argument |:menu-silent|
5770 submenus |List| containing the names of
5771 all the submenus. Present only if the menu
5772 item has submenus.
5773
5774 Returns an empty dictionary if the menu item is not found.
5775
5776 Examples: >
5777 :echo menu_info('Edit.Cut')
5778 :echo menu_info('File.Save', 'n')
5779
5780 " Display the entire menu hierarchy in a buffer
5781 func ShowMenu(name, pfx)
5782 let m = menu_info(a:name)
5783 call append(line('$'), a:pfx .. m.display)
5784 for child in m->get('submenus', [])
5785 call ShowMenu(a:name .. '.' .. escape(child, '.'),
5786 \ a:pfx .. ' ')
5787 endfor
5788 endfunc
5789 new
5790 for topmenu in menu_info('').submenus
5791 call ShowMenu(topmenu, '')
5792 endfor
5793<
5794 Can also be used as a |method|: >
5795 GetMenuName()->menu_info('v')
5796
5797
5798< *min()*
5799min({expr}) Return the minimum value of all items in {expr}. Example: >
5800 echo min([apples, pears, oranges])
5801
5802< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
5803 it returns the minimum of all values in the Dictionary.
5804 If {expr} is neither a List nor a Dictionary, or one of the
5805 items in {expr} cannot be used as a Number this results in
5806 an error. An empty |List| or |Dictionary| results in zero.
5807
5808 Can also be used as a |method|: >
5809 mylist->min()
5810
5811< *mkdir()* *E739*
5812mkdir({name} [, {path} [, {prot}]])
5813 Create directory {name}.
5814
5815 If {path} is "p" then intermediate directories are created as
5816 necessary. Otherwise it must be "".
5817
5818 If {prot} is given it is used to set the protection bits of
5819 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
5820 the user, readable for others). Use 0o700 to make it
5821 unreadable for others. This is only used for the last part of
5822 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
5823 created with 0o755.
5824 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005825 :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00005826
5827< This function is not available in the |sandbox|.
5828
5829 There is no error if the directory already exists and the "p"
5830 flag is passed (since patch 8.0.1708). However, without the
5831 "p" option the call will fail.
5832
5833 The function result is a Number, which is TRUE if the call was
5834 successful or FALSE if the directory creation failed or partly
5835 failed.
5836
5837 Not available on all systems. To check use: >
5838 :if exists("*mkdir")
5839
5840< Can also be used as a |method|: >
5841 GetName()->mkdir()
5842<
5843 *mode()*
5844mode([expr]) Return a string that indicates the current mode.
5845 If [expr] is supplied and it evaluates to a non-zero Number or
5846 a non-empty String (|non-zero-arg|), then the full mode is
5847 returned, otherwise only the first letter is returned.
5848 Also see |state()|.
5849
5850 n Normal
5851 no Operator-pending
5852 nov Operator-pending (forced characterwise |o_v|)
5853 noV Operator-pending (forced linewise |o_V|)
5854 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
5855 CTRL-V is one character
5856 niI Normal using |i_CTRL-O| in |Insert-mode|
5857 niR Normal using |i_CTRL-O| in |Replace-mode|
5858 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
5859 nt Terminal-Normal (insert goes to Terminal-Job mode)
5860 v Visual by character
5861 vs Visual by character using |v_CTRL-O| in Select mode
5862 V Visual by line
5863 Vs Visual by line using |v_CTRL-O| in Select mode
5864 CTRL-V Visual blockwise
5865 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
5866 s Select by character
5867 S Select by line
5868 CTRL-S Select blockwise
5869 i Insert
5870 ic Insert mode completion |compl-generic|
5871 ix Insert mode |i_CTRL-X| completion
5872 R Replace |R|
5873 Rc Replace mode completion |compl-generic|
5874 Rx Replace mode |i_CTRL-X| completion
5875 Rv Virtual Replace |gR|
5876 Rvc Virtual Replace mode completion |compl-generic|
5877 Rvx Virtual Replace mode |i_CTRL-X| completion
5878 c Command-line editing
5879 cv Vim Ex mode |gQ|
5880 ce Normal Ex mode |Q|
5881 r Hit-enter prompt
5882 rm The -- more -- prompt
5883 r? A |:confirm| query of some sort
5884 ! Shell or external command is executing
5885 t Terminal-Job mode: keys go to the job
5886
5887 This is useful in the 'statusline' option or when used
5888 with |remote_expr()| In most other places it always returns
5889 "c" or "n".
5890 Note that in the future more modes and more specific modes may
5891 be added. It's better not to compare the whole string but only
5892 the leading character(s).
5893 Also see |visualmode()|.
5894
5895 Can also be used as a |method|: >
5896 DoFull()->mode()
5897
5898mzeval({expr}) *mzeval()*
5899 Evaluate MzScheme expression {expr} and return its result
5900 converted to Vim data structures.
5901 Numbers and strings are returned as they are.
5902 Pairs (including lists and improper lists) and vectors are
5903 returned as Vim |Lists|.
5904 Hash tables are represented as Vim |Dictionary| type with keys
5905 converted to strings.
5906 All other types are converted to string with display function.
5907 Examples: >
5908 :mz (define l (list 1 2 3))
5909 :mz (define h (make-hash)) (hash-set! h "list" l)
5910 :echo mzeval("l")
5911 :echo mzeval("h")
5912<
5913 Note that in a `:def` function local variables are not visible
5914 to {expr}.
5915
5916 Can also be used as a |method|: >
5917 GetExpr()->mzeval()
5918<
5919 {only available when compiled with the |+mzscheme| feature}
5920
5921nextnonblank({lnum}) *nextnonblank()*
5922 Return the line number of the first line at or below {lnum}
5923 that is not blank. Example: >
5924 if getline(nextnonblank(1)) =~ "Java"
5925< When {lnum} is invalid or there is no non-blank line at or
5926 below it, zero is returned.
5927 {lnum} is used like with |getline()|.
5928 See also |prevnonblank()|.
5929
5930 Can also be used as a |method|: >
5931 GetLnum()->nextnonblank()
5932
5933nr2char({expr} [, {utf8}]) *nr2char()*
5934 Return a string with a single character, which has the number
5935 value {expr}. Examples: >
5936 nr2char(64) returns "@"
5937 nr2char(32) returns " "
5938< When {utf8} is omitted or zero, the current 'encoding' is used.
5939 Example for "utf-8": >
5940 nr2char(300) returns I with bow character
5941< When {utf8} is TRUE, always return UTF-8 characters.
5942 Note that a NUL character in the file is specified with
5943 nr2char(10), because NULs are represented with newline
5944 characters. nr2char(0) is a real NUL and terminates the
5945 string, thus results in an empty string.
5946 To turn a list of character numbers into a string: >
5947 let list = [65, 66, 67]
5948 let str = join(map(list, {_, val -> nr2char(val)}), '')
5949< Result: "ABC"
5950
5951 Can also be used as a |method|: >
5952 GetNumber()->nr2char()
5953
5954or({expr}, {expr}) *or()*
5955 Bitwise OR on the two arguments. The arguments are converted
5956 to a number. A List, Dict or Float argument causes an error.
5957 Example: >
5958 :let bits = or(bits, 0x80)
5959< Can also be used as a |method|: >
5960 :let bits = bits->or(0x80)
5961
5962
5963pathshorten({path} [, {len}]) *pathshorten()*
5964 Shorten directory names in the path {path} and return the
5965 result. The tail, the file name, is kept as-is. The other
5966 components in the path are reduced to {len} letters in length.
5967 If {len} is omitted or smaller than 1 then 1 is used (single
5968 letters). Leading '~' and '.' characters are kept. Examples: >
5969 :echo pathshorten('~/.vim/autoload/myfile.vim')
5970< ~/.v/a/myfile.vim ~
5971>
5972 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
5973< ~/.vi/au/myfile.vim ~
5974 It doesn't matter if the path exists or not.
5975
5976 Can also be used as a |method|: >
5977 GetDirectories()->pathshorten()
5978
5979perleval({expr}) *perleval()*
5980 Evaluate Perl expression {expr} in scalar context and return
5981 its result converted to Vim data structures. If value can't be
5982 converted, it is returned as a string Perl representation.
5983 Note: If you want an array or hash, {expr} must return a
5984 reference to it.
5985 Example: >
5986 :echo perleval('[1 .. 4]')
5987< [1, 2, 3, 4]
5988
5989 Note that in a `:def` function local variables are not visible
5990 to {expr}.
5991
5992 Can also be used as a |method|: >
5993 GetExpr()->perleval()
5994
5995< {only available when compiled with the |+perl| feature}
5996
5997
5998popup_ functions are documented here: |popup-functions|
5999
6000
6001pow({x}, {y}) *pow()*
6002 Return the power of {x} to the exponent {y} as a |Float|.
6003 {x} and {y} must evaluate to a |Float| or a |Number|.
6004 Examples: >
6005 :echo pow(3, 3)
6006< 27.0 >
6007 :echo pow(2, 16)
6008< 65536.0 >
6009 :echo pow(32, 0.20)
6010< 2.0
6011
6012 Can also be used as a |method|: >
6013 Compute()->pow(3)
6014<
6015 {only available when compiled with the |+float| feature}
6016
6017prevnonblank({lnum}) *prevnonblank()*
6018 Return the line number of the first line at or above {lnum}
6019 that is not blank. Example: >
6020 let ind = indent(prevnonblank(v:lnum - 1))
6021< When {lnum} is invalid or there is no non-blank line at or
6022 above it, zero is returned.
6023 {lnum} is used like with |getline()|.
6024 Also see |nextnonblank()|.
6025
6026 Can also be used as a |method|: >
6027 GetLnum()->prevnonblank()
6028
6029printf({fmt}, {expr1} ...) *printf()*
6030 Return a String with {fmt}, where "%" items are replaced by
6031 the formatted form of their respective arguments. Example: >
6032 printf("%4d: E%d %.30s", lnum, errno, msg)
6033< May result in:
6034 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
6035
6036 When used as a |method| the base is passed as the second
6037 argument: >
6038 Compute()->printf("result: %d")
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006039<
6040 You can use `call()` to pass the items as a list.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006041
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006042 Often used items are:
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006043 %s string
6044 %6S string right-aligned in 6 display cells
6045 %6s string right-aligned in 6 bytes
6046 %.9s string truncated to 9 bytes
6047 %c single byte
6048 %d decimal number
6049 %5d decimal number padded with spaces to 5 characters
6050 %x hex number
6051 %04x hex number padded with zeros to at least 4 characters
6052 %X hex number using upper case letters
6053 %o octal number
6054 %08b binary number padded with zeros to at least 8 chars
6055 %f floating point number as 12.23, inf, -inf or nan
6056 %F floating point number as 12.23, INF, -INF or NAN
6057 %e floating point number as 1.23e3, inf, -inf or nan
6058 %E floating point number as 1.23E3, INF, -INF or NAN
6059 %g floating point number, as %f or %e depending on value
6060 %G floating point number, as %F or %E depending on value
6061 %% the % character itself
6062
6063 Conversion specifications start with '%' and end with the
6064 conversion type. All other characters are copied unchanged to
6065 the result.
6066
6067 The "%" starts a conversion specification. The following
6068 arguments appear in sequence:
6069
6070 % [flags] [field-width] [.precision] type
6071
6072 flags
6073 Zero or more of the following flags:
6074
6075 # The value should be converted to an "alternate
6076 form". For c, d, and s conversions, this option
6077 has no effect. For o conversions, the precision
6078 of the number is increased to force the first
6079 character of the output string to a zero (except
6080 if a zero value is printed with an explicit
6081 precision of zero).
6082 For b and B conversions, a non-zero result has
6083 the string "0b" (or "0B" for B conversions)
6084 prepended to it.
6085 For x and X conversions, a non-zero result has
6086 the string "0x" (or "0X" for X conversions)
6087 prepended to it.
6088
6089 0 (zero) Zero padding. For all conversions the converted
6090 value is padded on the left with zeros rather
6091 than blanks. If a precision is given with a
6092 numeric conversion (d, b, B, o, x, and X), the 0
6093 flag is ignored.
6094
6095 - A negative field width flag; the converted value
6096 is to be left adjusted on the field boundary.
6097 The converted value is padded on the right with
6098 blanks, rather than on the left with blanks or
6099 zeros. A - overrides a 0 if both are given.
6100
6101 ' ' (space) A blank should be left before a positive
6102 number produced by a signed conversion (d).
6103
6104 + A sign must always be placed before a number
6105 produced by a signed conversion. A + overrides
6106 a space if both are used.
6107
6108 field-width
6109 An optional decimal digit string specifying a minimum
6110 field width. If the converted value has fewer bytes
6111 than the field width, it will be padded with spaces on
6112 the left (or right, if the left-adjustment flag has
6113 been given) to fill out the field width. For the S
6114 conversion the count is in cells.
6115
6116 .precision
6117 An optional precision, in the form of a period '.'
6118 followed by an optional digit string. If the digit
6119 string is omitted, the precision is taken as zero.
6120 This gives the minimum number of digits to appear for
6121 d, o, x, and X conversions, the maximum number of
6122 bytes to be printed from a string for s conversions,
6123 or the maximum number of cells to be printed from a
6124 string for S conversions.
6125 For floating point it is the number of digits after
6126 the decimal point.
6127
6128 type
6129 A character that specifies the type of conversion to
6130 be applied, see below.
6131
6132 A field width or precision, or both, may be indicated by an
6133 asterisk '*' instead of a digit string. In this case, a
6134 Number argument supplies the field width or precision. A
6135 negative field width is treated as a left adjustment flag
6136 followed by a positive field width; a negative precision is
6137 treated as though it were missing. Example: >
6138 :echo printf("%d: %.*s", nr, width, line)
6139< This limits the length of the text used from "line" to
6140 "width" bytes.
6141
6142 The conversion specifiers and their meanings are:
6143
6144 *printf-d* *printf-b* *printf-B* *printf-o*
6145 *printf-x* *printf-X*
6146 dbBoxX The Number argument is converted to signed decimal
6147 (d), unsigned binary (b and B), unsigned octal (o), or
6148 unsigned hexadecimal (x and X) notation. The letters
6149 "abcdef" are used for x conversions; the letters
6150 "ABCDEF" are used for X conversions.
6151 The precision, if any, gives the minimum number of
6152 digits that must appear; if the converted value
6153 requires fewer digits, it is padded on the left with
6154 zeros.
6155 In no case does a non-existent or small field width
6156 cause truncation of a numeric field; if the result of
6157 a conversion is wider than the field width, the field
6158 is expanded to contain the conversion result.
6159 The 'h' modifier indicates the argument is 16 bits.
6160 The 'l' modifier indicates the argument is 32 bits.
6161 The 'L' modifier indicates the argument is 64 bits.
6162 Generally, these modifiers are not useful. They are
6163 ignored when type is known from the argument.
6164
6165 i alias for d
6166 D alias for ld
6167 U alias for lu
6168 O alias for lo
6169
6170 *printf-c*
6171 c The Number argument is converted to a byte, and the
6172 resulting character is written.
6173
6174 *printf-s*
6175 s The text of the String argument is used. If a
6176 precision is specified, no more bytes than the number
6177 specified are used.
6178 If the argument is not a String type, it is
6179 automatically converted to text with the same format
6180 as ":echo".
6181 *printf-S*
6182 S The text of the String argument is used. If a
6183 precision is specified, no more display cells than the
6184 number specified are used.
6185
6186 *printf-f* *E807*
6187 f F The Float argument is converted into a string of the
6188 form 123.456. The precision specifies the number of
6189 digits after the decimal point. When the precision is
6190 zero the decimal point is omitted. When the precision
6191 is not specified 6 is used. A really big number
6192 (out of range or dividing by zero) results in "inf"
6193 or "-inf" with %f (INF or -INF with %F).
6194 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
6195 Example: >
6196 echo printf("%.2f", 12.115)
6197< 12.12
6198 Note that roundoff depends on the system libraries.
6199 Use |round()| when in doubt.
6200
6201 *printf-e* *printf-E*
6202 e E The Float argument is converted into a string of the
6203 form 1.234e+03 or 1.234E+03 when using 'E'. The
6204 precision specifies the number of digits after the
6205 decimal point, like with 'f'.
6206
6207 *printf-g* *printf-G*
6208 g G The Float argument is converted like with 'f' if the
6209 value is between 0.001 (inclusive) and 10000000.0
6210 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6211 for 'G'. When no precision is specified superfluous
6212 zeroes and '+' signs are removed, except for the zero
6213 immediately after the decimal point. Thus 10000000.0
6214 results in 1.0e7.
6215
6216 *printf-%*
6217 % A '%' is written. No argument is converted. The
6218 complete conversion specification is "%%".
6219
6220 When a Number argument is expected a String argument is also
6221 accepted and automatically converted.
6222 When a Float or String argument is expected a Number argument
6223 is also accepted and automatically converted.
6224 Any other argument type results in an error message.
6225
6226 *E766* *E767*
6227 The number of {exprN} arguments must exactly match the number
6228 of "%" items. If there are not sufficient or too many
6229 arguments an error is given. Up to 18 arguments can be used.
6230
6231
6232prompt_getprompt({buf}) *prompt_getprompt()*
6233 Returns the effective prompt text for buffer {buf}. {buf} can
6234 be a buffer name or number. See |prompt-buffer|.
6235
6236 If the buffer doesn't exist or isn't a prompt buffer, an empty
6237 string is returned.
6238
6239 Can also be used as a |method|: >
6240 GetBuffer()->prompt_getprompt()
6241
6242< {only available when compiled with the |+channel| feature}
6243
6244
6245prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
6246 Set prompt callback for buffer {buf} to {expr}. When {expr}
6247 is an empty string the callback is removed. This has only
6248 effect if {buf} has 'buftype' set to "prompt".
6249
6250 The callback is invoked when pressing Enter. The current
6251 buffer will always be the prompt buffer. A new line for a
6252 prompt is added before invoking the callback, thus the prompt
6253 for which the callback was invoked will be in the last but one
6254 line.
6255 If the callback wants to add text to the buffer, it must
6256 insert it above the last line, since that is where the current
6257 prompt is. This can also be done asynchronously.
6258 The callback is invoked with one argument, which is the text
6259 that was entered at the prompt. This can be an empty string
6260 if the user only typed Enter.
6261 Example: >
6262 call prompt_setcallback(bufnr(), function('s:TextEntered'))
6263 func s:TextEntered(text)
6264 if a:text == 'exit' || a:text == 'quit'
6265 stopinsert
6266 close
6267 else
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006268 call append(line('$') - 1, 'Entered: "' .. a:text .. '"')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006269 " Reset 'modified' to allow the buffer to be closed.
6270 set nomodified
6271 endif
6272 endfunc
6273
6274< Can also be used as a |method|: >
6275 GetBuffer()->prompt_setcallback(callback)
6276
6277< {only available when compiled with the |+channel| feature}
6278
6279prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6280 Set a callback for buffer {buf} to {expr}. When {expr} is an
6281 empty string the callback is removed. This has only effect if
6282 {buf} has 'buftype' set to "prompt".
6283
6284 This callback will be invoked when pressing CTRL-C in Insert
6285 mode. Without setting a callback Vim will exit Insert mode,
6286 as in any buffer.
6287
6288 Can also be used as a |method|: >
6289 GetBuffer()->prompt_setinterrupt(callback)
6290
6291< {only available when compiled with the |+channel| feature}
6292
6293prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6294 Set prompt for buffer {buf} to {text}. You most likely want
6295 {text} to end in a space.
6296 The result is only visible if {buf} has 'buftype' set to
6297 "prompt". Example: >
6298 call prompt_setprompt(bufnr(), 'command: ')
6299<
6300 Can also be used as a |method|: >
6301 GetBuffer()->prompt_setprompt('command: ')
6302
6303< {only available when compiled with the |+channel| feature}
6304
6305prop_ functions are documented here: |text-prop-functions|
6306
6307pum_getpos() *pum_getpos()*
6308 If the popup menu (see |ins-completion-menu|) is not visible,
6309 returns an empty |Dictionary|, otherwise, returns a
6310 |Dictionary| with the following keys:
6311 height nr of items visible
6312 width screen cells
6313 row top screen row (0 first row)
6314 col leftmost screen column (0 first col)
6315 size total nr of items
6316 scrollbar |TRUE| if scrollbar is visible
6317
6318 The values are the same as in |v:event| during
6319 |CompleteChanged|.
6320
6321pumvisible() *pumvisible()*
6322 Returns non-zero when the popup menu is visible, zero
6323 otherwise. See |ins-completion-menu|.
6324 This can be used to avoid some things that would remove the
6325 popup menu.
6326
6327py3eval({expr}) *py3eval()*
6328 Evaluate Python expression {expr} and return its result
6329 converted to Vim data structures.
6330 Numbers and strings are returned as they are (strings are
6331 copied though, Unicode strings are additionally converted to
6332 'encoding').
6333 Lists are represented as Vim |List| type.
6334 Dictionaries are represented as Vim |Dictionary| type with
6335 keys converted to strings.
6336 Note that in a `:def` function local variables are not visible
6337 to {expr}.
6338
6339 Can also be used as a |method|: >
6340 GetExpr()->py3eval()
6341
6342< {only available when compiled with the |+python3| feature}
6343
6344 *E858* *E859*
6345pyeval({expr}) *pyeval()*
6346 Evaluate Python expression {expr} and return its result
6347 converted to Vim data structures.
6348 Numbers and strings are returned as they are (strings are
6349 copied though).
6350 Lists are represented as Vim |List| type.
6351 Dictionaries are represented as Vim |Dictionary| type,
6352 non-string keys result in error.
6353 Note that in a `:def` function local variables are not visible
6354 to {expr}.
6355
6356 Can also be used as a |method|: >
6357 GetExpr()->pyeval()
6358
6359< {only available when compiled with the |+python| feature}
6360
6361pyxeval({expr}) *pyxeval()*
6362 Evaluate Python expression {expr} and return its result
6363 converted to Vim data structures.
6364 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6365 See also: |pyeval()|, |py3eval()|
6366
6367 Can also be used as a |method|: >
6368 GetExpr()->pyxeval()
6369
6370< {only available when compiled with the |+python| or the
6371 |+python3| feature}
6372
6373rand([{expr}]) *rand()* *random*
6374 Return a pseudo-random Number generated with an xoshiro128**
6375 algorithm using seed {expr}. The returned number is 32 bits,
6376 also on 64 bits systems, for consistency.
6377 {expr} can be initialized by |srand()| and will be updated by
6378 rand(). If {expr} is omitted, an internal seed value is used
6379 and updated.
6380
6381 Examples: >
6382 :echo rand()
6383 :let seed = srand()
6384 :echo rand(seed)
6385 :echo rand(seed) % 16 " random number 0 - 15
6386<
6387
6388 *E726* *E727*
6389range({expr} [, {max} [, {stride}]]) *range()*
6390 Returns a |List| with Numbers:
6391 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6392 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6393 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6394 {max}] (increasing {expr} with {stride} each time, not
6395 producing a value past {max}).
6396 When the maximum is one before the start the result is an
6397 empty list. When the maximum is more than one before the
6398 start this is an error.
6399 Examples: >
6400 range(4) " [0, 1, 2, 3]
6401 range(2, 4) " [2, 3, 4]
6402 range(2, 9, 3) " [2, 5, 8]
6403 range(2, -2, -1) " [2, 1, 0, -1, -2]
6404 range(0) " []
6405 range(2, 0) " error!
6406<
6407 Can also be used as a |method|: >
6408 GetExpr()->range()
6409<
6410
6411readblob({fname}) *readblob()*
6412 Read file {fname} in binary mode and return a |Blob|.
6413 When the file can't be opened an error message is given and
6414 the result is an empty |Blob|.
6415 Also see |readfile()| and |writefile()|.
6416
6417
6418readdir({directory} [, {expr} [, {dict}]]) *readdir()*
6419 Return a list with file and directory names in {directory}.
6420 You can also use |glob()| if you don't need to do complicated
6421 things, such as limiting the number of matches.
6422 The list will be sorted (case sensitive), see the {dict}
6423 argument below for changing the sort order.
6424
6425 When {expr} is omitted all entries are included.
6426 When {expr} is given, it is evaluated to check what to do:
6427 If {expr} results in -1 then no further entries will
6428 be handled.
6429 If {expr} results in 0 then this entry will not be
6430 added to the list.
6431 If {expr} results in 1 then this entry will be added
6432 to the list.
6433 The entries "." and ".." are always excluded.
6434 Each time {expr} is evaluated |v:val| is set to the entry name.
6435 When {expr} is a function the name is passed as the argument.
6436 For example, to get a list of files ending in ".txt": >
6437 readdir(dirname, {n -> n =~ '.txt$'})
6438< To skip hidden and backup files: >
6439 readdir(dirname, {n -> n !~ '^\.\|\~$'})
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00006440< *E857*
6441 The optional {dict} argument allows for further custom
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006442 values. Currently this is used to specify if and how sorting
6443 should be performed. The dict can have the following members:
6444
6445 sort How to sort the result returned from the system.
6446 Valid values are:
6447 "none" do not sort (fastest method)
6448 "case" sort case sensitive (byte value of
6449 each character, technically, using
6450 strcmp()) (default)
6451 "icase" sort case insensitive (technically
6452 using strcasecmp())
6453 "collate" sort using the collation order
6454 of the "POSIX" or "C" |locale|
6455 (technically using strcoll())
6456 Other values are silently ignored.
6457
6458 For example, to get a list of all files in the current
6459 directory without sorting the individual entries: >
6460 readdir('.', '1', #{sort: 'none'})
6461< If you want to get a directory tree: >
6462 function! s:tree(dir)
6463 return {a:dir : map(readdir(a:dir),
6464 \ {_, x -> isdirectory(x) ?
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006465 \ {x : s:tree(a:dir .. '/' .. x)} : x})}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006466 endfunction
6467 echo s:tree(".")
6468<
6469 Can also be used as a |method|: >
6470 GetDirName()->readdir()
6471<
6472readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
6473 Extended version of |readdir()|.
6474 Return a list of Dictionaries with file and directory
6475 information in {directory}.
6476 This is useful if you want to get the attributes of file and
6477 directory at the same time as getting a list of a directory.
6478 This is much faster than calling |readdir()| then calling
6479 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
6480 each file and directory especially on MS-Windows.
6481 The list will by default be sorted by name (case sensitive),
6482 the sorting can be changed by using the optional {dict}
6483 argument, see |readdir()|.
6484
6485 The Dictionary for file and directory information has the
6486 following items:
6487 group Group name of the entry. (Only on Unix)
6488 name Name of the entry.
6489 perm Permissions of the entry. See |getfperm()|.
6490 size Size of the entry. See |getfsize()|.
6491 time Timestamp of the entry. See |getftime()|.
6492 type Type of the entry.
6493 On Unix, almost same as |getftype()| except:
6494 Symlink to a dir "linkd"
6495 Other symlink "link"
6496 On MS-Windows:
6497 Normal file "file"
6498 Directory "dir"
6499 Junction "junction"
6500 Symlink to a dir "linkd"
6501 Other symlink "link"
6502 Other reparse point "reparse"
6503 user User name of the entry's owner. (Only on Unix)
6504 On Unix, if the entry is a symlink, the Dictionary includes
6505 the information of the target (except the "type" item).
6506 On MS-Windows, it includes the information of the symlink
6507 itself because of performance reasons.
6508
6509 When {expr} is omitted all entries are included.
6510 When {expr} is given, it is evaluated to check what to do:
6511 If {expr} results in -1 then no further entries will
6512 be handled.
6513 If {expr} results in 0 then this entry will not be
6514 added to the list.
6515 If {expr} results in 1 then this entry will be added
6516 to the list.
6517 The entries "." and ".." are always excluded.
6518 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
6519 of the entry.
6520 When {expr} is a function the entry is passed as the argument.
6521 For example, to get a list of files ending in ".txt": >
6522 readdirex(dirname, {e -> e.name =~ '.txt$'})
6523<
6524 For example, to get a list of all files in the current
6525 directory without sorting the individual entries: >
6526 readdirex(dirname, '1', #{sort: 'none'})
6527
6528<
6529 Can also be used as a |method|: >
6530 GetDirName()->readdirex()
6531<
6532
6533 *readfile()*
6534readfile({fname} [, {type} [, {max}]])
6535 Read file {fname} and return a |List|, each line of the file
6536 as an item. Lines are broken at NL characters. Macintosh
6537 files separated with CR will result in a single long line
6538 (unless a NL appears somewhere).
6539 All NUL characters are replaced with a NL character.
6540 When {type} contains "b" binary mode is used:
6541 - When the last line ends in a NL an extra empty list item is
6542 added.
6543 - No CR characters are removed.
6544 Otherwise:
6545 - CR characters that appear before a NL are removed.
6546 - Whether the last line ends in a NL or not does not matter.
6547 - When 'encoding' is Unicode any UTF-8 byte order mark is
6548 removed from the text.
6549 When {max} is given this specifies the maximum number of lines
6550 to be read. Useful if you only want to check the first ten
6551 lines of a file: >
6552 :for line in readfile(fname, '', 10)
6553 : if line =~ 'Date' | echo line | endif
6554 :endfor
6555< When {max} is negative -{max} lines from the end of the file
6556 are returned, or as many as there are.
6557 When {max} is zero the result is an empty list.
6558 Note that without {max} the whole file is read into memory.
6559 Also note that there is no recognition of encoding. Read a
6560 file into a buffer if you need to.
6561 Deprecated (use |readblob()| instead): When {type} contains
6562 "B" a |Blob| is returned with the binary data of the file
6563 unmodified.
6564 When the file can't be opened an error message is given and
6565 the result is an empty list.
6566 Also see |writefile()|.
6567
6568 Can also be used as a |method|: >
6569 GetFileName()->readfile()
6570
6571reduce({object}, {func} [, {initial}]) *reduce()* *E998*
6572 {func} is called for every item in {object}, which can be a
6573 |String|, |List| or a |Blob|. {func} is called with two
6574 arguments: the result so far and current item. After
Bram Moolenaarf10911e2022-01-29 22:20:48 +00006575 processing all items the result is returned. *E1132*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006576
6577 {initial} is the initial result. When omitted, the first item
6578 in {object} is used and {func} is first called for the second
6579 item. If {initial} is not given and {object} is empty no
6580 result can be computed, an E998 error is given.
6581
6582 Examples: >
6583 echo reduce([1, 3, 5], { acc, val -> acc + val })
6584 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
6585 echo reduce(0z1122, { acc, val -> 2 * acc + val })
6586 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
6587<
6588 Can also be used as a |method|: >
6589 echo mylist->reduce({ acc, val -> acc + val }, 0)
6590
6591
6592reg_executing() *reg_executing()*
6593 Returns the single letter name of the register being executed.
6594 Returns an empty string when no register is being executed.
6595 See |@|.
6596
6597reg_recording() *reg_recording()*
6598 Returns the single letter name of the register being recorded.
6599 Returns an empty string when not recording. See |q|.
6600
6601reltime([{start} [, {end}]]) *reltime()*
6602 Return an item that represents a time value. The item is a
6603 list with items that depend on the system. In Vim 9 script
6604 list<any> can be used.
6605 The item can be passed to |reltimestr()| to convert it to a
6606 string or |reltimefloat()| to convert to a Float.
6607
6608 Without an argument reltime() returns the current time.
6609 With one argument is returns the time passed since the time
6610 specified in the argument.
6611 With two arguments it returns the time passed between {start}
6612 and {end}.
6613
6614 The {start} and {end} arguments must be values returned by
6615 reltime(). If there is an error zero is returned in legacy
6616 script, in Vim9 script an error is given.
6617
6618 Can also be used as a |method|: >
6619 GetStart()->reltime()
6620<
6621 {only available when compiled with the |+reltime| feature}
6622
6623reltimefloat({time}) *reltimefloat()*
6624 Return a Float that represents the time value of {time}.
6625 Example: >
6626 let start = reltime()
6627 call MyFunction()
6628 let seconds = reltimefloat(reltime(start))
6629< See the note of reltimestr() about overhead.
6630 Also see |profiling|.
6631 If there is an error 0.0 is returned in legacy script, in Vim9
6632 script an error is given.
6633
6634 Can also be used as a |method|: >
6635 reltime(start)->reltimefloat()
6636
6637< {only available when compiled with the |+reltime| feature}
6638
6639reltimestr({time}) *reltimestr()*
6640 Return a String that represents the time value of {time}.
6641 This is the number of seconds, a dot and the number of
6642 microseconds. Example: >
6643 let start = reltime()
6644 call MyFunction()
6645 echo reltimestr(reltime(start))
6646< Note that overhead for the commands will be added to the time.
6647 The accuracy depends on the system.
6648 Leading spaces are used to make the string align nicely. You
6649 can use split() to remove it. >
6650 echo split(reltimestr(reltime(start)))[0]
6651< Also see |profiling|.
6652 If there is an error an empty string is returned in legacy
6653 script, in Vim9 script an error is given.
6654
6655 Can also be used as a |method|: >
6656 reltime(start)->reltimestr()
6657
6658< {only available when compiled with the |+reltime| feature}
6659
6660 *remote_expr()* *E449*
6661remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar944697a2022-02-20 19:48:20 +00006662 Send the {string} to {server}. The {server} argument is a
6663 string, also see |{server}|.
6664
6665 The string is sent as an expression and the result is returned
6666 after evaluation. The result must be a String or a |List|. A
6667 |List| is turned into a String by joining the items with a
6668 line break in between (not at the end), like with join(expr,
6669 "\n").
6670
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006671 If {idvar} is present and not empty, it is taken as the name
6672 of a variable and a {serverid} for later use with
6673 |remote_read()| is stored there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006674
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006675 If {timeout} is given the read times out after this many
6676 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006677
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006678 See also |clientserver| |RemoteReply|.
6679 This function is not available in the |sandbox|.
6680 {only available when compiled with the |+clientserver| feature}
6681 Note: Any errors will cause a local error message to be issued
6682 and the result will be the empty string.
6683
6684 Variables will be evaluated in the global namespace,
6685 independent of a function currently being active. Except
6686 when in debug mode, then local function variables and
6687 arguments can be evaluated.
6688
6689 Examples: >
6690 :echo remote_expr("gvim", "2+2")
6691 :echo remote_expr("gvim1", "b:current_syntax")
6692<
6693 Can also be used as a |method|: >
6694 ServerName()->remote_expr(expr)
6695
6696remote_foreground({server}) *remote_foreground()*
6697 Move the Vim server with the name {server} to the foreground.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006698 The {server} argument is a string, also see |{server}|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006699 This works like: >
6700 remote_expr({server}, "foreground()")
6701< Except that on Win32 systems the client does the work, to work
6702 around the problem that the OS doesn't always allow the server
6703 to bring itself to the foreground.
6704 Note: This does not restore the window if it was minimized,
6705 like foreground() does.
6706 This function is not available in the |sandbox|.
6707
6708 Can also be used as a |method|: >
6709 ServerName()->remote_foreground()
6710
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006711< {only in the Win32, Motif and GTK GUI versions and the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006712 Win32 console version}
6713
6714
6715remote_peek({serverid} [, {retvar}]) *remote_peek()*
6716 Returns a positive number if there are available strings
6717 from {serverid}. Copies any reply string into the variable
6718 {retvar} if specified. {retvar} must be a string with the
6719 name of a variable.
6720 Returns zero if none are available.
6721 Returns -1 if something is wrong.
6722 See also |clientserver|.
6723 This function is not available in the |sandbox|.
6724 {only available when compiled with the |+clientserver| feature}
6725 Examples: >
6726 :let repl = ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006727 :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006728
6729< Can also be used as a |method|: >
6730 ServerId()->remote_peek()
6731
6732remote_read({serverid}, [{timeout}]) *remote_read()*
6733 Return the oldest available reply from {serverid} and consume
6734 it. Unless a {timeout} in seconds is given, it blocks until a
6735 reply is available.
6736 See also |clientserver|.
6737 This function is not available in the |sandbox|.
6738 {only available when compiled with the |+clientserver| feature}
6739 Example: >
6740 :echo remote_read(id)
6741
6742< Can also be used as a |method|: >
6743 ServerId()->remote_read()
6744<
6745 *remote_send()* *E241*
6746remote_send({server}, {string} [, {idvar}])
Bram Moolenaar944697a2022-02-20 19:48:20 +00006747 Send the {string} to {server}. The {server} argument is a
6748 string, also see |{server}|.
6749
6750 The string is sent as input keys and the function returns
6751 immediately. At the Vim server the keys are not mapped
6752 |:map|.
6753
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006754 If {idvar} is present, it is taken as the name of a variable
6755 and a {serverid} for later use with remote_read() is stored
6756 there.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006757
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006758 See also |clientserver| |RemoteReply|.
6759 This function is not available in the |sandbox|.
6760 {only available when compiled with the |+clientserver| feature}
6761
6762 Note: Any errors will be reported in the server and may mess
6763 up the display.
6764 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006765 :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006766 \ remote_read(serverid)
6767
6768 :autocmd NONE RemoteReply *
6769 \ echo remote_read(expand("<amatch>"))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006770 :echo remote_send("gvim", ":sleep 10 | echo " ..
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006771 \ 'server2client(expand("<client>"), "HELLO")<CR>')
6772<
6773 Can also be used as a |method|: >
6774 ServerName()->remote_send(keys)
6775<
6776 *remote_startserver()* *E941* *E942*
6777remote_startserver({name})
6778 Become the server {name}. This fails if already running as a
6779 server, when |v:servername| is not empty.
6780
6781 Can also be used as a |method|: >
6782 ServerName()->remote_startserver()
6783
6784< {only available when compiled with the |+clientserver| feature}
6785
6786remove({list}, {idx} [, {end}]) *remove()*
6787 Without {end}: Remove the item at {idx} from |List| {list} and
6788 return the item.
6789 With {end}: Remove items from {idx} to {end} (inclusive) and
6790 return a |List| with these items. When {idx} points to the same
6791 item as {end} a list with one item is returned. When {end}
6792 points to an item before {idx} this is an error.
6793 See |list-index| for possible values of {idx} and {end}.
6794 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006795 :echo "last item: " .. remove(mylist, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006796 :call remove(mylist, 0, 9)
6797<
6798 Use |delete()| to remove a file.
6799
6800 Can also be used as a |method|: >
6801 mylist->remove(idx)
6802
6803remove({blob}, {idx} [, {end}])
6804 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
6805 return the byte.
6806 With {end}: Remove bytes from {idx} to {end} (inclusive) and
6807 return a |Blob| with these bytes. When {idx} points to the same
6808 byte as {end} a |Blob| with one byte is returned. When {end}
6809 points to a byte before {idx} this is an error.
6810 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006811 :echo "last byte: " .. remove(myblob, -1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006812 :call remove(mylist, 0, 9)
6813
6814remove({dict}, {key})
6815 Remove the entry from {dict} with key {key} and return it.
6816 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006817 :echo "removed " .. remove(dict, "one")
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006818< If there is no {key} in {dict} this is an error.
6819
6820rename({from}, {to}) *rename()*
6821 Rename the file by the name {from} to the name {to}. This
6822 should also work to move files across file systems. The
6823 result is a Number, which is 0 if the file was renamed
6824 successfully, and non-zero when the renaming failed.
6825 NOTE: If {to} exists it is overwritten without warning.
6826 This function is not available in the |sandbox|.
6827
6828 Can also be used as a |method|: >
6829 GetOldName()->rename(newname)
6830
6831repeat({expr}, {count}) *repeat()*
6832 Repeat {expr} {count} times and return the concatenated
6833 result. Example: >
6834 :let separator = repeat('-', 80)
6835< When {count} is zero or negative the result is empty.
6836 When {expr} is a |List| the result is {expr} concatenated
6837 {count} times. Example: >
6838 :let longlist = repeat(['a', 'b'], 3)
6839< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
6840
6841 Can also be used as a |method|: >
6842 mylist->repeat(count)
6843
6844resolve({filename}) *resolve()* *E655*
6845 On MS-Windows, when {filename} is a shortcut (a .lnk file),
6846 returns the path the shortcut points to in a simplified form.
6847 When {filename} is a symbolic link or junction point, return
6848 the full path to the target. If the target of junction is
6849 removed, return {filename}.
6850 On Unix, repeat resolving symbolic links in all path
6851 components of {filename} and return the simplified result.
6852 To cope with link cycles, resolving of symbolic links is
6853 stopped after 100 iterations.
6854 On other systems, return the simplified {filename}.
6855 The simplification step is done as by |simplify()|.
6856 resolve() keeps a leading path component specifying the
6857 current directory (provided the result is still a relative
6858 path name) and also keeps a trailing path separator.
6859
6860 Can also be used as a |method|: >
6861 GetName()->resolve()
6862
6863reverse({object}) *reverse()*
6864 Reverse the order of items in {object} in-place.
6865 {object} can be a |List| or a |Blob|.
6866 Returns {object}.
6867 If you want an object to remain unmodified make a copy first: >
6868 :let revlist = reverse(copy(mylist))
6869< Can also be used as a |method|: >
6870 mylist->reverse()
6871
6872round({expr}) *round()*
6873 Round off {expr} to the nearest integral value and return it
6874 as a |Float|. If {expr} lies halfway between two integral
6875 values, then use the larger one (away from zero).
6876 {expr} must evaluate to a |Float| or a |Number|.
6877 Examples: >
6878 echo round(0.456)
6879< 0.0 >
6880 echo round(4.5)
6881< 5.0 >
6882 echo round(-4.5)
6883< -5.0
6884
6885 Can also be used as a |method|: >
6886 Compute()->round()
6887<
6888 {only available when compiled with the |+float| feature}
6889
6890rubyeval({expr}) *rubyeval()*
6891 Evaluate Ruby expression {expr} and return its result
6892 converted to Vim data structures.
6893 Numbers, floats and strings are returned as they are (strings
6894 are copied though).
6895 Arrays are represented as Vim |List| type.
6896 Hashes are represented as Vim |Dictionary| type.
6897 Other objects are represented as strings resulted from their
6898 "Object#to_s" method.
6899 Note that in a `:def` function local variables are not visible
6900 to {expr}.
6901
6902 Can also be used as a |method|: >
6903 GetRubyExpr()->rubyeval()
6904
6905< {only available when compiled with the |+ruby| feature}
6906
6907screenattr({row}, {col}) *screenattr()*
6908 Like |screenchar()|, but return the attribute. This is a rather
6909 arbitrary number that can only be used to compare to the
6910 attribute at other positions.
6911
6912 Can also be used as a |method|: >
6913 GetRow()->screenattr(col)
6914
6915screenchar({row}, {col}) *screenchar()*
6916 The result is a Number, which is the character at position
6917 [row, col] on the screen. This works for every possible
6918 screen position, also status lines, window separators and the
6919 command line. The top left position is row one, column one
6920 The character excludes composing characters. For double-byte
6921 encodings it may only be the first byte.
6922 This is mainly to be used for testing.
6923 Returns -1 when row or col is out of range.
6924
6925 Can also be used as a |method|: >
6926 GetRow()->screenchar(col)
6927
6928screenchars({row}, {col}) *screenchars()*
6929 The result is a |List| of Numbers. The first number is the same
6930 as what |screenchar()| returns. Further numbers are
6931 composing characters on top of the base character.
6932 This is mainly to be used for testing.
6933 Returns an empty List when row or col is out of range.
6934
6935 Can also be used as a |method|: >
6936 GetRow()->screenchars(col)
6937
6938screencol() *screencol()*
6939 The result is a Number, which is the current screen column of
6940 the cursor. The leftmost column has number 1.
6941 This function is mainly used for testing.
6942
6943 Note: Always returns the current screen column, thus if used
6944 in a command (e.g. ":echo screencol()") it will return the
6945 column inside the command line, which is 1 when the command is
6946 executed. To get the cursor position in the file use one of
6947 the following mappings: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006948 nnoremap <expr> GG ":echom " .. screencol() .. "\n"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006949 nnoremap <silent> GG :echom screencol()<CR>
6950 nnoremap GG <Cmd>echom screencol()<CR>
6951<
6952screenpos({winid}, {lnum}, {col}) *screenpos()*
6953 The result is a Dict with the screen position of the text
6954 character in window {winid} at buffer line {lnum} and column
6955 {col}. {col} is a one-based byte index.
6956 The Dict has these members:
6957 row screen row
6958 col first screen column
6959 endcol last screen column
6960 curscol cursor screen column
6961 If the specified position is not visible, all values are zero.
6962 The "endcol" value differs from "col" when the character
6963 occupies more than one screen cell. E.g. for a Tab "col" can
6964 be 1 and "endcol" can be 8.
6965 The "curscol" value is where the cursor would be placed. For
6966 a Tab it would be the same as "endcol", while for a double
6967 width character it would be the same as "col".
6968 The |conceal| feature is ignored here, the column numbers are
6969 as if 'conceallevel' is zero. You can set the cursor to the
6970 right position and use |screencol()| to get the value with
6971 |conceal| taken into account.
Bram Moolenaar944697a2022-02-20 19:48:20 +00006972 If the position is in a closed fold the screen position of the
6973 first character is returned, {col} is not used.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00006974
6975 Can also be used as a |method|: >
6976 GetWinid()->screenpos(lnum, col)
6977
6978screenrow() *screenrow()*
6979 The result is a Number, which is the current screen row of the
6980 cursor. The top line has number one.
6981 This function is mainly used for testing.
6982 Alternatively you can use |winline()|.
6983
6984 Note: Same restrictions as with |screencol()|.
6985
6986screenstring({row}, {col}) *screenstring()*
6987 The result is a String that contains the base character and
6988 any composing characters at position [row, col] on the screen.
6989 This is like |screenchars()| but returning a String with the
6990 characters.
6991 This is mainly to be used for testing.
6992 Returns an empty String when row or col is out of range.
6993
6994 Can also be used as a |method|: >
6995 GetRow()->screenstring(col)
6996<
6997 *search()*
6998search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
6999 Search for regexp pattern {pattern}. The search starts at the
7000 cursor position (you can use |cursor()| to set it).
7001
7002 When a match has been found its line number is returned.
7003 If there is no match a 0 is returned and the cursor doesn't
7004 move. No error message is given.
7005
7006 {flags} is a String, which can contain these character flags:
7007 'b' search Backward instead of forward
7008 'c' accept a match at the Cursor position
7009 'e' move to the End of the match
7010 'n' do Not move the cursor
7011 'p' return number of matching sub-Pattern (see below)
7012 's' Set the ' mark at the previous location of the cursor
7013 'w' Wrap around the end of the file
7014 'W' don't Wrap around the end of the file
7015 'z' start searching at the cursor column instead of zero
7016 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7017
7018 If the 's' flag is supplied, the ' mark is set, only if the
7019 cursor is moved. The 's' flag cannot be combined with the 'n'
7020 flag.
7021
7022 'ignorecase', 'smartcase' and 'magic' are used.
7023
7024 When the 'z' flag is not given, forward searching always
7025 starts in column zero and then matches before the cursor are
7026 skipped. When the 'c' flag is present in 'cpo' the next
7027 search starts after the match. Without the 'c' flag the next
7028 search starts one column further. This matters for
7029 overlapping matches.
7030 When searching backwards and the 'z' flag is given then the
7031 search starts in column zero, thus no match in the current
7032 line will be found (unless wrapping around the end of the
7033 file).
7034
7035 When the {stopline} argument is given then the search stops
7036 after searching this line. This is useful to restrict the
7037 search to a range of lines. Examples: >
7038 let match = search('(', 'b', line("w0"))
7039 let end = search('END', '', line("w$"))
7040< When {stopline} is used and it is not zero this also implies
7041 that the search does not wrap around the end of the file.
7042 A zero value is equal to not giving the argument.
7043
7044 When the {timeout} argument is given the search stops when
7045 more than this many milliseconds have passed. Thus when
7046 {timeout} is 500 the search stops after half a second.
7047 The value must not be negative. A zero value is like not
7048 giving the argument.
7049 {only available when compiled with the |+reltime| feature}
7050
7051 If the {skip} expression is given it is evaluated with the
7052 cursor positioned on the start of a match. If it evaluates to
7053 non-zero this match is skipped. This can be used, for
7054 example, to skip a match in a comment or a string.
7055 {skip} can be a string, which is evaluated as an expression, a
7056 function reference or a lambda.
7057 When {skip} is omitted or empty, every match is accepted.
7058 When evaluating {skip} causes an error the search is aborted
7059 and -1 returned.
7060 *search()-sub-match*
7061 With the 'p' flag the returned value is one more than the
7062 first sub-match in \(\). One if none of them matched but the
7063 whole pattern did match.
7064 To get the column number too use |searchpos()|.
7065
7066 The cursor will be positioned at the match, unless the 'n'
7067 flag is used.
7068
7069 Example (goes over all files in the argument list): >
7070 :let n = 1
7071 :while n <= argc() " loop over all files in arglist
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007072 : exe "argument " .. n
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007073 : " start at the last char in the file and wrap for the
7074 : " first search to find match at start of file
7075 : normal G$
7076 : let flags = "w"
7077 : while search("foo", flags) > 0
7078 : s/foo/bar/g
7079 : let flags = "W"
7080 : endwhile
7081 : update " write the file if modified
7082 : let n = n + 1
7083 :endwhile
7084<
7085 Example for using some flags: >
7086 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7087< This will search for the keywords "if", "else", and "endif"
7088 under or after the cursor. Because of the 'p' flag, it
7089 returns 1, 2, or 3 depending on which keyword is found, or 0
7090 if the search fails. With the cursor on the first word of the
7091 line:
7092 if (foo == 0) | let foo = foo + 1 | endif ~
7093 the function returns 1. Without the 'c' flag, the function
7094 finds the "endif" and returns 3. The same thing happens
7095 without the 'e' flag if the cursor is on the "f" of "if".
7096 The 'n' flag tells the function not to move the cursor.
7097
7098 Can also be used as a |method|: >
7099 GetPattern()->search()
7100
7101searchcount([{options}]) *searchcount()*
7102 Get or update the last search count, like what is displayed
7103 without the "S" flag in 'shortmess'. This works even if
7104 'shortmess' does contain the "S" flag.
7105
7106 This returns a |Dictionary|. The dictionary is empty if the
7107 previous pattern was not set and "pattern" was not specified.
7108
7109 key type meaning ~
7110 current |Number| current position of match;
7111 0 if the cursor position is
7112 before the first match
7113 exact_match |Boolean| 1 if "current" is matched on
7114 "pos", otherwise 0
7115 total |Number| total count of matches found
7116 incomplete |Number| 0: search was fully completed
7117 1: recomputing was timed out
7118 2: max count exceeded
7119
7120 For {options} see further down.
7121
7122 To get the last search count when |n| or |N| was pressed, call
7123 this function with `recompute: 0` . This sometimes returns
7124 wrong information because |n| and |N|'s maximum count is 99.
7125 If it exceeded 99 the result must be max count + 1 (100). If
7126 you want to get correct information, specify `recompute: 1`: >
7127
7128 " result == maxcount + 1 (100) when many matches
7129 let result = searchcount(#{recompute: 0})
7130
7131 " Below returns correct result (recompute defaults
7132 " to 1)
7133 let result = searchcount()
7134<
7135 The function is useful to add the count to |statusline|: >
7136 function! LastSearchCount() abort
7137 let result = searchcount(#{recompute: 0})
7138 if empty(result)
7139 return ''
7140 endif
7141 if result.incomplete ==# 1 " timed out
7142 return printf(' /%s [?/??]', @/)
7143 elseif result.incomplete ==# 2 " max count exceeded
7144 if result.total > result.maxcount &&
7145 \ result.current > result.maxcount
7146 return printf(' /%s [>%d/>%d]', @/,
7147 \ result.current, result.total)
7148 elseif result.total > result.maxcount
7149 return printf(' /%s [%d/>%d]', @/,
7150 \ result.current, result.total)
7151 endif
7152 endif
7153 return printf(' /%s [%d/%d]', @/,
7154 \ result.current, result.total)
7155 endfunction
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007156 let &statusline ..= '%{LastSearchCount()}'
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007157
7158 " Or if you want to show the count only when
7159 " 'hlsearch' was on
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007160 " let &statusline ..=
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007161 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
7162<
7163 You can also update the search count, which can be useful in a
7164 |CursorMoved| or |CursorMovedI| autocommand: >
7165
7166 autocmd CursorMoved,CursorMovedI *
7167 \ let s:searchcount_timer = timer_start(
7168 \ 200, function('s:update_searchcount'))
7169 function! s:update_searchcount(timer) abort
7170 if a:timer ==# s:searchcount_timer
7171 call searchcount(#{
7172 \ recompute: 1, maxcount: 0, timeout: 100})
7173 redrawstatus
7174 endif
7175 endfunction
7176<
7177 This can also be used to count matched texts with specified
7178 pattern in the current buffer using "pattern": >
7179
7180 " Count '\<foo\>' in this buffer
7181 " (Note that it also updates search count)
7182 let result = searchcount(#{pattern: '\<foo\>'})
7183
7184 " To restore old search count by old pattern,
7185 " search again
7186 call searchcount()
7187<
7188 {options} must be a |Dictionary|. It can contain:
7189 key type meaning ~
7190 recompute |Boolean| if |TRUE|, recompute the count
7191 like |n| or |N| was executed.
7192 otherwise returns the last
7193 computed result (when |n| or
7194 |N| was used when "S" is not
7195 in 'shortmess', or this
7196 function was called).
7197 (default: |TRUE|)
7198 pattern |String| recompute if this was given
7199 and different with |@/|.
7200 this works as same as the
7201 below command is executed
7202 before calling this function >
7203 let @/ = pattern
7204< (default: |@/|)
7205 timeout |Number| 0 or negative number is no
7206 timeout. timeout milliseconds
7207 for recomputing the result
7208 (default: 0)
7209 maxcount |Number| 0 or negative number is no
7210 limit. max count of matched
7211 text while recomputing the
7212 result. if search exceeded
7213 total count, "total" value
7214 becomes `maxcount + 1`
7215 (default: 99)
7216 pos |List| `[lnum, col, off]` value
7217 when recomputing the result.
7218 this changes "current" result
7219 value. see |cursor()|,
7220 |getpos()|
7221 (default: cursor's position)
7222
7223 Can also be used as a |method|: >
7224 GetSearchOpts()->searchcount()
7225<
7226searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7227 Search for the declaration of {name}.
7228
7229 With a non-zero {global} argument it works like |gD|, find
7230 first match in the file. Otherwise it works like |gd|, find
7231 first match in the function.
7232
7233 With a non-zero {thisblock} argument matches in a {} block
7234 that ends before the cursor position are ignored. Avoids
7235 finding variable declarations only valid in another scope.
7236
7237 Moves the cursor to the found match.
7238 Returns zero for success, non-zero for failure.
7239 Example: >
7240 if searchdecl('myvar') == 0
7241 echo getline('.')
7242 endif
7243<
7244 Can also be used as a |method|: >
7245 GetName()->searchdecl()
7246<
7247 *searchpair()*
7248searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7249 [, {stopline} [, {timeout}]]]])
7250 Search for the match of a nested start-end pair. This can be
7251 used to find the "endif" that matches an "if", while other
7252 if/endif pairs in between are ignored.
7253 The search starts at the cursor. The default is to search
7254 forward, include 'b' in {flags} to search backward.
7255 If a match is found, the cursor is positioned at it and the
7256 line number is returned. If no match is found 0 or -1 is
7257 returned and the cursor doesn't move. No error message is
7258 given.
7259
7260 {start}, {middle} and {end} are patterns, see |pattern|. They
7261 must not contain \( \) pairs. Use of \%( \) is allowed. When
7262 {middle} is not empty, it is found when searching from either
7263 direction, but only when not in a nested start-end pair. A
7264 typical use is: >
7265 searchpair('\<if\>', '\<else\>', '\<endif\>')
7266< By leaving {middle} empty the "else" is skipped.
7267
7268 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7269 |search()|. Additionally:
7270 'r' Repeat until no more matches found; will find the
7271 outer pair. Implies the 'W' flag.
7272 'm' Return number of matches instead of line number with
7273 the match; will be > 1 when 'r' is used.
7274 Note: it's nearly always a good idea to use the 'W' flag, to
7275 avoid wrapping around the end of the file.
7276
7277 When a match for {start}, {middle} or {end} is found, the
7278 {skip} expression is evaluated with the cursor positioned on
7279 the start of the match. It should return non-zero if this
7280 match is to be skipped. E.g., because it is inside a comment
7281 or a string.
7282 When {skip} is omitted or empty, every match is accepted.
7283 When evaluating {skip} causes an error the search is aborted
7284 and -1 returned.
7285 {skip} can be a string, a lambda, a funcref or a partial.
7286 Anything else makes the function fail.
7287 In a `:def` function when the {skip} argument is a string
7288 constant it is compiled into instructions.
7289
7290 For {stopline} and {timeout} see |search()|.
7291
7292 The value of 'ignorecase' is used. 'magic' is ignored, the
7293 patterns are used like it's on.
7294
7295 The search starts exactly at the cursor. A match with
7296 {start}, {middle} or {end} at the next character, in the
7297 direction of searching, is the first one found. Example: >
7298 if 1
7299 if 2
7300 endif 2
7301 endif 1
7302< When starting at the "if 2", with the cursor on the "i", and
7303 searching forwards, the "endif 2" is found. When starting on
7304 the character just before the "if 2", the "endif 1" will be
7305 found. That's because the "if 2" will be found first, and
7306 then this is considered to be a nested if/endif from "if 2" to
7307 "endif 2".
7308 When searching backwards and {end} is more than one character,
7309 it may be useful to put "\zs" at the end of the pattern, so
7310 that when the cursor is inside a match with the end it finds
7311 the matching start.
7312
7313 Example, to find the "endif" command in a Vim script: >
7314
7315 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7316 \ 'getline(".") =~ "^\\s*\""')
7317
7318< The cursor must be at or after the "if" for which a match is
7319 to be found. Note that single-quote strings are used to avoid
7320 having to double the backslashes. The skip expression only
7321 catches comments at the start of a line, not after a command.
7322 Also, a word "en" or "if" halfway a line is considered a
7323 match.
7324 Another example, to search for the matching "{" of a "}": >
7325
7326 :echo searchpair('{', '', '}', 'bW')
7327
7328< This works when the cursor is at or before the "}" for which a
7329 match is to be found. To reject matches that syntax
7330 highlighting recognized as strings: >
7331
7332 :echo searchpair('{', '', '}', 'bW',
7333 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7334<
7335 *searchpairpos()*
7336searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7337 [, {stopline} [, {timeout}]]]])
7338 Same as |searchpair()|, but returns a |List| with the line and
7339 column position of the match. The first element of the |List|
7340 is the line number and the second element is the byte index of
7341 the column position of the match. If no match is found,
7342 returns [0, 0]. >
7343
7344 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7345<
7346 See |match-parens| for a bigger and more useful example.
7347
7348 *searchpos()*
7349searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
7350 Same as |search()|, but returns a |List| with the line and
7351 column position of the match. The first element of the |List|
7352 is the line number and the second element is the byte index of
7353 the column position of the match. If no match is found,
7354 returns [0, 0].
7355 Example: >
7356 :let [lnum, col] = searchpos('mypattern', 'n')
7357
7358< When the 'p' flag is given then there is an extra item with
7359 the sub-pattern match number |search()-sub-match|. Example: >
7360 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7361< In this example "submatch" is 2 when a lowercase letter is
7362 found |/\l|, 3 when an uppercase letter is found |/\u|.
7363
7364 Can also be used as a |method|: >
7365 GetPattern()->searchpos()
7366
7367server2client({clientid}, {string}) *server2client()*
7368 Send a reply string to {clientid}. The most recent {clientid}
7369 that sent a string can be retrieved with expand("<client>").
7370 {only available when compiled with the |+clientserver| feature}
7371 Returns zero for success, -1 for failure.
7372 Note:
7373 This id has to be stored before the next command can be
7374 received. I.e. before returning from the received command and
7375 before calling any commands that waits for input.
7376 See also |clientserver|.
7377 Example: >
7378 :echo server2client(expand("<client>"), "HELLO")
7379
7380< Can also be used as a |method|: >
7381 GetClientId()->server2client(string)
7382<
7383serverlist() *serverlist()*
7384 Return a list of available server names, one per line.
7385 When there are no servers or the information is not available
7386 an empty string is returned. See also |clientserver|.
7387 {only available when compiled with the |+clientserver| feature}
7388 Example: >
7389 :echo serverlist()
7390<
7391setbufline({buf}, {lnum}, {text}) *setbufline()*
7392 Set line {lnum} to {text} in buffer {buf}. This works like
7393 |setline()| for the specified buffer.
7394
7395 This function works only for loaded buffers. First call
7396 |bufload()| if needed.
7397
7398 To insert lines use |appendbufline()|.
7399 Any text properties in {lnum} are cleared.
7400
7401 {text} can be a string to set one line, or a list of strings
7402 to set multiple lines. If the list extends below the last
7403 line then those lines are added.
7404
7405 For the use of {buf}, see |bufname()| above.
7406
7407 {lnum} is used like with |setline()|.
7408 Use "$" to refer to the last line in buffer {buf}.
7409 When {lnum} is just below the last line the {text} will be
7410 added below the last line.
7411
7412 When {buf} is not a valid buffer, the buffer is not loaded or
7413 {lnum} is not valid then 1 is returned. In |Vim9| script an
7414 error is given.
7415 On success 0 is returned.
7416
7417 Can also be used as a |method|, the base is passed as the
7418 third argument: >
7419 GetText()->setbufline(buf, lnum)
7420
7421setbufvar({buf}, {varname}, {val}) *setbufvar()*
7422 Set option or local variable {varname} in buffer {buf} to
7423 {val}.
7424 This also works for a global or local window option, but it
7425 doesn't work for a global or local window variable.
7426 For a local window option the global value is unchanged.
7427 For the use of {buf}, see |bufname()| above.
7428 The {varname} argument is a string.
7429 Note that the variable name without "b:" must be used.
7430 Examples: >
7431 :call setbufvar(1, "&mod", 1)
7432 :call setbufvar("todo", "myvar", "foobar")
7433< This function is not available in the |sandbox|.
7434
7435 Can also be used as a |method|, the base is passed as the
7436 third argument: >
7437 GetValue()->setbufvar(buf, varname)
7438
7439
7440setcellwidths({list}) *setcellwidths()*
7441 Specify overrides for cell widths of character ranges. This
7442 tells Vim how wide characters are, counted in screen cells.
7443 This overrides 'ambiwidth'. Example: >
7444 setcellwidths([[0xad, 0xad, 1],
7445 \ [0x2194, 0x2199, 2]])
7446
Bram Moolenaarf10911e2022-01-29 22:20:48 +00007447< *E1109* *E1110* *E1111* *E1112* *E1113* *E1114*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007448 The {list} argument is a list of lists with each three
7449 numbers. These three numbers are [low, high, width]. "low"
7450 and "high" can be the same, in which case this refers to one
7451 character. Otherwise it is the range of characters from "low"
7452 to "high" (inclusive). "width" is either 1 or 2, indicating
7453 the character width in screen cells.
7454 An error is given if the argument is invalid, also when a
7455 range overlaps with another.
7456 Only characters with value 0x100 and higher can be used.
7457
7458 If the new value causes 'fillchars' or 'listchars' to become
7459 invalid it is rejected and an error is given.
7460
7461 To clear the overrides pass an empty list: >
7462 setcellwidths([]);
7463< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
7464 the effect for known emoji characters.
7465
7466setcharpos({expr}, {list}) *setcharpos()*
7467 Same as |setpos()| but uses the specified column number as the
7468 character index instead of the byte index in the line.
7469
7470 Example:
7471 With the text "여보세요" in line 8: >
7472 call setcharpos('.', [0, 8, 4, 0])
7473< positions the cursor on the fourth character '요'. >
7474 call setpos('.', [0, 8, 4, 0])
7475< positions the cursor on the second character '보'.
7476
7477 Can also be used as a |method|: >
7478 GetPosition()->setcharpos('.')
7479
7480setcharsearch({dict}) *setcharsearch()*
7481 Set the current character search information to {dict},
7482 which contains one or more of the following entries:
7483
7484 char character which will be used for a subsequent
7485 |,| or |;| command; an empty string clears the
7486 character search
7487 forward direction of character search; 1 for forward,
7488 0 for backward
7489 until type of character search; 1 for a |t| or |T|
7490 character search, 0 for an |f| or |F|
7491 character search
7492
7493 This can be useful to save/restore a user's character search
7494 from a script: >
7495 :let prevsearch = getcharsearch()
7496 :" Perform a command which clobbers user's search
7497 :call setcharsearch(prevsearch)
7498< Also see |getcharsearch()|.
7499
7500 Can also be used as a |method|: >
7501 SavedSearch()->setcharsearch()
7502
7503setcmdpos({pos}) *setcmdpos()*
7504 Set the cursor position in the command line to byte position
7505 {pos}. The first position is 1.
7506 Use |getcmdpos()| to obtain the current position.
7507 Only works while editing the command line, thus you must use
7508 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7509 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7510 set after the command line is set to the expression. For
7511 |c_CTRL-R_=| it is set after evaluating the expression but
7512 before inserting the resulting text.
7513 When the number is too big the cursor is put at the end of the
7514 line. A number smaller than one has undefined results.
7515 Returns FALSE when successful, TRUE when not editing the
7516 command line.
7517
7518 Can also be used as a |method|: >
7519 GetPos()->setcmdpos()
7520
7521setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
7522setcursorcharpos({list})
7523 Same as |cursor()| but uses the specified column number as the
7524 character index instead of the byte index in the line.
7525
7526 Example:
7527 With the text "여보세요" in line 4: >
7528 call setcursorcharpos(4, 3)
7529< positions the cursor on the third character '세'. >
7530 call cursor(4, 3)
7531< positions the cursor on the first character '여'.
7532
7533 Can also be used as a |method|: >
7534 GetCursorPos()->setcursorcharpos()
7535
7536
7537setenv({name}, {val}) *setenv()*
7538 Set environment variable {name} to {val}. Example: >
7539 call setenv('HOME', '/home/myhome')
7540
7541< When {val} is |v:null| the environment variable is deleted.
7542 See also |expr-env|.
7543
7544 Can also be used as a |method|, the base is passed as the
7545 second argument: >
7546 GetPath()->setenv('PATH')
7547
7548setfperm({fname}, {mode}) *setfperm()* *chmod*
7549 Set the file permissions for {fname} to {mode}.
7550 {mode} must be a string with 9 characters. It is of the form
7551 "rwxrwxrwx", where each group of "rwx" flags represent, in
7552 turn, the permissions of the owner of the file, the group the
7553 file belongs to, and other users. A '-' character means the
7554 permission is off, any other character means on. Multi-byte
7555 characters are not supported.
7556
7557 For example "rw-r-----" means read-write for the user,
7558 readable by the group, not accessible by others. "xx-x-----"
7559 would do the same thing.
7560
7561 Returns non-zero for success, zero for failure.
7562
7563 Can also be used as a |method|: >
7564 GetFilename()->setfperm(mode)
7565<
7566 To read permissions see |getfperm()|.
7567
7568
7569setline({lnum}, {text}) *setline()*
7570 Set line {lnum} of the current buffer to {text}. To insert
7571 lines use |append()|. To set lines in another buffer use
7572 |setbufline()|. Any text properties in {lnum} are cleared.
7573
7574 {lnum} is used like with |getline()|.
7575 When {lnum} is just below the last line the {text} will be
7576 added below the last line.
7577 {text} can be any type or a List of any type, each item is
7578 converted to a String.
7579
7580 If this succeeds, FALSE is returned. If this fails (most likely
7581 because {lnum} is invalid) TRUE is returned.
7582 In |Vim9| script an error is given if {lnum} is invalid.
7583
7584 Example: >
7585 :call setline(5, strftime("%c"))
7586
7587< When {text} is a |List| then line {lnum} and following lines
7588 will be set to the items in the list. Example: >
7589 :call setline(5, ['aaa', 'bbb', 'ccc'])
7590< This is equivalent to: >
7591 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
7592 : call setline(n, l)
7593 :endfor
7594
7595< Note: The '[ and '] marks are not set.
7596
7597 Can also be used as a |method|, the base is passed as the
7598 second argument: >
7599 GetText()->setline(lnum)
7600
7601setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
7602 Create or replace or add to the location list for window {nr}.
7603 {nr} can be the window number or the |window-ID|.
7604 When {nr} is zero the current window is used.
7605
7606 For a location list window, the displayed location list is
7607 modified. For an invalid window number {nr}, -1 is returned.
7608 Otherwise, same as |setqflist()|.
7609 Also see |location-list|.
7610
7611 For {action} see |setqflist-action|.
7612
7613 If the optional {what} dictionary argument is supplied, then
7614 only the items listed in {what} are set. Refer to |setqflist()|
7615 for the list of supported keys in {what}.
7616
7617 Can also be used as a |method|, the base is passed as the
7618 second argument: >
7619 GetLoclist()->setloclist(winnr)
7620
7621setmatches({list} [, {win}]) *setmatches()*
7622 Restores a list of matches saved by |getmatches()| for the
7623 current window. Returns 0 if successful, otherwise -1. All
7624 current matches are cleared before the list is restored. See
7625 example for |getmatches()|.
7626 If {win} is specified, use the window with this number or
7627 window ID instead of the current window.
7628
7629 Can also be used as a |method|: >
7630 GetMatches()->setmatches()
7631<
7632 *setpos()*
7633setpos({expr}, {list})
7634 Set the position for String {expr}. Possible values:
7635 . the cursor
7636 'x mark x
7637
7638 {list} must be a |List| with four or five numbers:
7639 [bufnum, lnum, col, off]
7640 [bufnum, lnum, col, off, curswant]
7641
7642 "bufnum" is the buffer number. Zero can be used for the
7643 current buffer. When setting an uppercase mark "bufnum" is
7644 used for the mark position. For other marks it specifies the
7645 buffer to set the mark in. You can use the |bufnr()| function
7646 to turn a file name into a buffer number.
7647 For setting the cursor and the ' mark "bufnum" is ignored,
7648 since these are associated with a window, not a buffer.
7649 Does not change the jumplist.
7650
7651 "lnum" and "col" are the position in the buffer. The first
7652 column is 1. Use a zero "lnum" to delete a mark. If "col" is
7653 smaller than 1 then 1 is used. To use the character count
7654 instead of the byte count, use |setcharpos()|.
7655
7656 The "off" number is only used when 'virtualedit' is set. Then
7657 it is the offset in screen columns from the start of the
7658 character. E.g., a position within a <Tab> or after the last
7659 character.
7660
7661 The "curswant" number is only used when setting the cursor
7662 position. It sets the preferred column for when moving the
7663 cursor vertically. When the "curswant" number is missing the
7664 preferred column is not set. When it is present and setting a
7665 mark position it is not used.
7666
7667 Note that for '< and '> changing the line number may result in
7668 the marks to be effectively be swapped, so that '< is always
7669 before '>.
7670
7671 Returns 0 when the position could be set, -1 otherwise.
7672 An error message is given if {expr} is invalid.
7673
7674 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
7675
7676 This does not restore the preferred column for moving
7677 vertically; if you set the cursor position with this, |j| and
7678 |k| motions will jump to previous columns! Use |cursor()| to
7679 also set the preferred column. Also see the "curswant" key in
7680 |winrestview()|.
7681
7682 Can also be used as a |method|: >
7683 GetPosition()->setpos('.')
7684
7685setqflist({list} [, {action} [, {what}]]) *setqflist()*
7686 Create or replace or add to the quickfix list.
7687
7688 If the optional {what} dictionary argument is supplied, then
7689 only the items listed in {what} are set. The first {list}
7690 argument is ignored. See below for the supported items in
7691 {what}.
7692 *setqflist-what*
7693 When {what} is not present, the items in {list} are used. Each
7694 item must be a dictionary. Non-dictionary items in {list} are
7695 ignored. Each dictionary item can contain the following
7696 entries:
7697
7698 bufnr buffer number; must be the number of a valid
7699 buffer
7700 filename name of a file; only used when "bufnr" is not
7701 present or it is invalid.
7702 module name of a module; if given it will be used in
7703 quickfix error window instead of the filename.
7704 lnum line number in the file
Bram Moolenaara2baa732022-02-04 16:09:54 +00007705 end_lnum end of lines, if the item spans multiple lines
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007706 pattern search pattern used to locate the error
7707 col column number
7708 vcol when non-zero: "col" is visual column
7709 when zero: "col" is byte index
Bram Moolenaara2baa732022-02-04 16:09:54 +00007710 end_col end column, if the item spans multiple columns
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007711 nr error number
7712 text description of the error
7713 type single-character error type, 'E', 'W', etc.
7714 valid recognized error message
7715
7716 The "col", "vcol", "nr", "type" and "text" entries are
7717 optional. Either "lnum" or "pattern" entry can be used to
7718 locate a matching error line.
7719 If the "filename" and "bufnr" entries are not present or
7720 neither the "lnum" or "pattern" entries are present, then the
7721 item will not be handled as an error line.
7722 If both "pattern" and "lnum" are present then "pattern" will
7723 be used.
7724 If the "valid" entry is not supplied, then the valid flag is
7725 set when "bufnr" is a valid buffer or "filename" exists.
7726 If you supply an empty {list}, the quickfix list will be
7727 cleared.
7728 Note that the list is not exactly the same as what
7729 |getqflist()| returns.
7730
7731 {action} values: *setqflist-action* *E927*
7732 'a' The items from {list} are added to the existing
7733 quickfix list. If there is no existing list, then a
7734 new list is created.
7735
7736 'r' The items from the current quickfix list are replaced
7737 with the items from {list}. This can also be used to
7738 clear the list: >
7739 :call setqflist([], 'r')
7740<
7741 'f' All the quickfix lists in the quickfix stack are
7742 freed.
7743
7744 If {action} is not present or is set to ' ', then a new list
7745 is created. The new quickfix list is added after the current
7746 quickfix list in the stack and all the following lists are
7747 freed. To add a new quickfix list at the end of the stack,
7748 set "nr" in {what} to "$".
7749
7750 The following items can be specified in dictionary {what}:
7751 context quickfix list context. See |quickfix-context|
7752 efm errorformat to use when parsing text from
7753 "lines". If this is not present, then the
7754 'errorformat' option value is used.
7755 See |quickfix-parse|
7756 id quickfix list identifier |quickfix-ID|
7757 idx index of the current entry in the quickfix
7758 list specified by 'id' or 'nr'. If set to '$',
7759 then the last entry in the list is set as the
7760 current entry. See |quickfix-index|
7761 items list of quickfix entries. Same as the {list}
7762 argument.
7763 lines use 'errorformat' to parse a list of lines and
7764 add the resulting entries to the quickfix list
7765 {nr} or {id}. Only a |List| value is supported.
7766 See |quickfix-parse|
7767 nr list number in the quickfix stack; zero
7768 means the current quickfix list and "$" means
7769 the last quickfix list.
7770 quickfixtextfunc
7771 function to get the text to display in the
7772 quickfix window. The value can be the name of
7773 a function or a funcref or a lambda. Refer to
7774 |quickfix-window-function| for an explanation
7775 of how to write the function and an example.
7776 title quickfix list title text. See |quickfix-title|
7777 Unsupported keys in {what} are ignored.
7778 If the "nr" item is not present, then the current quickfix list
7779 is modified. When creating a new quickfix list, "nr" can be
7780 set to a value one greater than the quickfix stack size.
7781 When modifying a quickfix list, to guarantee that the correct
7782 list is modified, "id" should be used instead of "nr" to
7783 specify the list.
7784
7785 Examples (See also |setqflist-examples|): >
7786 :call setqflist([], 'r', {'title': 'My search'})
7787 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
7788 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
7789<
7790 Returns zero for success, -1 for failure.
7791
7792 This function can be used to create a quickfix list
7793 independent of the 'errorformat' setting. Use a command like
7794 `:cc 1` to jump to the first position.
7795
7796 Can also be used as a |method|, the base is passed as the
7797 second argument: >
7798 GetErrorlist()->setqflist()
7799<
7800 *setreg()*
7801setreg({regname}, {value} [, {options}])
7802 Set the register {regname} to {value}.
7803 If {regname} is "" or "@", the unnamed register '"' is used.
7804 The {regname} argument is a string. In |Vim9-script|
7805 {regname} must be one character.
7806
7807 {value} may be any value returned by |getreg()| or
7808 |getreginfo()|, including a |List| or |Dict|.
7809 If {options} contains "a" or {regname} is upper case,
7810 then the value is appended.
7811
7812 {options} can also contain a register type specification:
7813 "c" or "v" |characterwise| mode
7814 "l" or "V" |linewise| mode
7815 "b" or "<CTRL-V>" |blockwise-visual| mode
7816 If a number immediately follows "b" or "<CTRL-V>" then this is
7817 used as the width of the selection - if it is not specified
7818 then the width of the block is set to the number of characters
7819 in the longest line (counting a <Tab> as 1 character).
7820
7821 If {options} contains no register settings, then the default
7822 is to use character mode unless {value} ends in a <NL> for
7823 string {value} and linewise mode for list {value}. Blockwise
7824 mode is never selected automatically.
7825 Returns zero for success, non-zero for failure.
7826
7827 *E883*
7828 Note: you may not use |List| containing more than one item to
7829 set search and expression registers. Lists containing no
7830 items act like empty strings.
7831
7832 Examples: >
7833 :call setreg(v:register, @*)
7834 :call setreg('*', @%, 'ac')
7835 :call setreg('a', "1\n2\n3", 'b5')
7836 :call setreg('"', { 'points_to': 'a'})
7837
7838< This example shows using the functions to save and restore a
7839 register: >
7840 :let var_a = getreginfo()
7841 :call setreg('a', var_a)
7842< or: >
7843 :let var_a = getreg('a', 1, 1)
7844 :let var_amode = getregtype('a')
7845 ....
7846 :call setreg('a', var_a, var_amode)
7847< Note: you may not reliably restore register value
7848 without using the third argument to |getreg()| as without it
7849 newlines are represented as newlines AND Nul bytes are
7850 represented as newlines as well, see |NL-used-for-Nul|.
7851
7852 You can also change the type of a register by appending
7853 nothing: >
7854 :call setreg('a', '', 'al')
7855
7856< Can also be used as a |method|, the base is passed as the
7857 second argument: >
7858 GetText()->setreg('a')
7859
7860settabvar({tabnr}, {varname}, {val}) *settabvar()*
7861 Set tab-local variable {varname} to {val} in tab page {tabnr}.
7862 |t:var|
7863 The {varname} argument is a string.
7864 Note that autocommands are blocked, side effects may not be
7865 triggered, e.g. when setting 'filetype'.
7866 Note that the variable name without "t:" must be used.
7867 Tabs are numbered starting with one.
7868 This function is not available in the |sandbox|.
7869
7870 Can also be used as a |method|, the base is passed as the
7871 third argument: >
7872 GetValue()->settabvar(tab, name)
7873
7874settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
7875 Set option or local variable {varname} in window {winnr} to
7876 {val}.
7877 Tabs are numbered starting with one. For the current tabpage
7878 use |setwinvar()|.
7879 {winnr} can be the window number or the |window-ID|.
7880 When {winnr} is zero the current window is used.
7881 Note that autocommands are blocked, side effects may not be
7882 triggered, e.g. when setting 'filetype' or 'syntax'.
7883 This also works for a global or local buffer option, but it
7884 doesn't work for a global or local buffer variable.
7885 For a local buffer option the global value is unchanged.
7886 Note that the variable name without "w:" must be used.
7887 Examples: >
7888 :call settabwinvar(1, 1, "&list", 0)
7889 :call settabwinvar(3, 2, "myvar", "foobar")
7890< This function is not available in the |sandbox|.
7891
7892 Can also be used as a |method|, the base is passed as the
7893 fourth argument: >
7894 GetValue()->settabwinvar(tab, winnr, name)
7895
7896settagstack({nr}, {dict} [, {action}]) *settagstack()*
7897 Modify the tag stack of the window {nr} using {dict}.
7898 {nr} can be the window number or the |window-ID|.
7899
7900 For a list of supported items in {dict}, refer to
7901 |gettagstack()|. "curidx" takes effect before changing the tag
7902 stack.
7903 *E962*
7904 How the tag stack is modified depends on the {action}
7905 argument:
7906 - If {action} is not present or is set to 'r', then the tag
7907 stack is replaced.
7908 - If {action} is set to 'a', then new entries from {dict} are
7909 pushed (added) onto the tag stack.
7910 - If {action} is set to 't', then all the entries from the
7911 current entry in the tag stack or "curidx" in {dict} are
7912 removed and then new entries are pushed to the stack.
7913
7914 The current index is set to one after the length of the tag
7915 stack after the modification.
7916
7917 Returns zero for success, -1 for failure.
7918
7919 Examples (for more examples see |tagstack-examples|):
7920 Empty the tag stack of window 3: >
7921 call settagstack(3, {'items' : []})
7922
7923< Save and restore the tag stack: >
7924 let stack = gettagstack(1003)
7925 " do something else
7926 call settagstack(1003, stack)
7927 unlet stack
7928<
7929 Can also be used as a |method|, the base is passed as the
7930 second argument: >
7931 GetStack()->settagstack(winnr)
7932
7933setwinvar({winnr}, {varname}, {val}) *setwinvar()*
7934 Like |settabwinvar()| for the current tab page.
7935 Examples: >
7936 :call setwinvar(1, "&list", 0)
7937 :call setwinvar(2, "myvar", "foobar")
7938
7939< Can also be used as a |method|, the base is passed as the
7940 third argument: >
7941 GetValue()->setwinvar(winnr, name)
7942
7943sha256({string}) *sha256()*
7944 Returns a String with 64 hex characters, which is the SHA256
7945 checksum of {string}.
7946
7947 Can also be used as a |method|: >
7948 GetText()->sha256()
7949
7950< {only available when compiled with the |+cryptv| feature}
7951
7952shellescape({string} [, {special}]) *shellescape()*
7953 Escape {string} for use as a shell command argument.
7954 When the 'shell' contains powershell (MS-Windows) or pwsh
Bram Moolenaar944697a2022-02-20 19:48:20 +00007955 (MS-Windows, Linux, and macOS) then it will enclose {string}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007956 in single quotes and will double up all internal single
7957 quotes.
7958 On MS-Windows, when 'shellslash' is not set, it will enclose
7959 {string} in double quotes and double all double quotes within
7960 {string}.
7961 Otherwise it will enclose {string} in single quotes and
7962 replace all "'" with "'\''".
7963
7964 When the {special} argument is present and it's a non-zero
7965 Number or a non-empty String (|non-zero-arg|), then special
7966 items such as "!", "%", "#" and "<cword>" will be preceded by
7967 a backslash. This backslash will be removed again by the |:!|
7968 command.
7969
7970 The "!" character will be escaped (again with a |non-zero-arg|
7971 {special}) when 'shell' contains "csh" in the tail. That is
7972 because for csh and tcsh "!" is used for history replacement
7973 even when inside single quotes.
7974
7975 With a |non-zero-arg| {special} the <NL> character is also
7976 escaped. When 'shell' containing "csh" in the tail it's
7977 escaped a second time.
7978
7979 The "\" character will be escaped when 'shell' contains "fish"
7980 in the tail. That is because for fish "\" is used as an escape
7981 character inside single quotes.
7982
7983 Example of use with a |:!| command: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007984 :exe '!dir ' .. shellescape(expand('<cfile>'), 1)
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007985< This results in a directory listing for the file under the
7986 cursor. Example of use with |system()|: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00007987 :call system("chmod +w -- " .. shellescape(expand("%")))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00007988< See also |::S|.
7989
7990 Can also be used as a |method|: >
7991 GetCommand()->shellescape()
7992
7993shiftwidth([{col}]) *shiftwidth()*
7994 Returns the effective value of 'shiftwidth'. This is the
7995 'shiftwidth' value unless it is zero, in which case it is the
7996 'tabstop' value. This function was introduced with patch
7997 7.3.694 in 2012, everybody should have it by now (however it
7998 did not allow for the optional {col} argument until 8.1.542).
7999
8000 When there is one argument {col} this is used as column number
8001 for which to return the 'shiftwidth' value. This matters for the
8002 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8003 no {col} argument is given, column 1 will be assumed.
8004
8005 Can also be used as a |method|: >
8006 GetColumn()->shiftwidth()
8007
8008sign_ functions are documented here: |sign-functions-details|
8009
8010
8011simplify({filename}) *simplify()*
8012 Simplify the file name as much as possible without changing
8013 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8014 Unix) are not resolved. If the first path component in
8015 {filename} designates the current directory, this will be
8016 valid for the result as well. A trailing path separator is
8017 not removed either. On Unix "//path" is unchanged, but
8018 "///path" is simplified to "/path" (this follows the Posix
8019 standard).
8020 Example: >
8021 simplify("./dir/.././/file/") == "./file/"
8022< Note: The combination "dir/.." is only removed if "dir" is
8023 a searchable directory or does not exist. On Unix, it is also
8024 removed when "dir" is a symbolic link within the same
8025 directory. In order to resolve all the involved symbolic
8026 links before simplifying the path name, use |resolve()|.
8027
8028 Can also be used as a |method|: >
8029 GetName()->simplify()
8030
8031sin({expr}) *sin()*
8032 Return the sine of {expr}, measured in radians, as a |Float|.
8033 {expr} must evaluate to a |Float| or a |Number|.
8034 Examples: >
8035 :echo sin(100)
8036< -0.506366 >
8037 :echo sin(-4.01)
8038< 0.763301
8039
8040 Can also be used as a |method|: >
8041 Compute()->sin()
8042<
8043 {only available when compiled with the |+float| feature}
8044
8045
8046sinh({expr}) *sinh()*
8047 Return the hyperbolic sine of {expr} as a |Float| in the range
8048 [-inf, inf].
8049 {expr} must evaluate to a |Float| or a |Number|.
8050 Examples: >
8051 :echo sinh(0.5)
8052< 0.521095 >
8053 :echo sinh(-0.9)
8054< -1.026517
8055
8056 Can also be used as a |method|: >
8057 Compute()->sinh()
8058<
8059 {only available when compiled with the |+float| feature}
8060
8061
8062slice({expr}, {start} [, {end}]) *slice()*
8063 Similar to using a |slice| "expr[start : end]", but "end" is
8064 used exclusive. And for a string the indexes are used as
8065 character indexes instead of byte indexes, like in
8066 |vim9script|. Also, composing characters are not counted.
8067 When {end} is omitted the slice continues to the last item.
8068 When {end} is -1 the last item is omitted.
8069
8070 Can also be used as a |method|: >
8071 GetList()->slice(offset)
8072
8073
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008074sort({list} [, {how} [, {dict}]]) *sort()* *E702*
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008075 Sort the items in {list} in-place. Returns {list}.
8076
8077 If you want a list to remain unmodified make a copy first: >
8078 :let sortedlist = sort(copy(mylist))
8079
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008080< When {how} is omitted or is an string, then sort() uses the
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008081 string representation of each item to sort on. Numbers sort
8082 after Strings, |Lists| after Numbers. For sorting text in the
8083 current buffer use |:sort|.
8084
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008085 When {how} is given and it is 'i' then case is ignored.
8086 In legacy script, for backwards compatibility, the value one
8087 can be used to ignore case. Zero means to not ignore case.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008088
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008089 When {how} is given and it is 'l' then the current collation
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008090 locale is used for ordering. Implementation details: strcoll()
8091 is used to compare strings. See |:language| check or set the
8092 collation locale. |v:collate| can also be used to check the
8093 current locale. Sorting using the locale typically ignores
8094 case. Example: >
8095 " ö is sorted similarly to o with English locale.
8096 :language collate en_US.UTF8
8097 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8098< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
8099>
8100 " ö is sorted after z with Swedish locale.
8101 :language collate sv_SE.UTF8
8102 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
8103< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
8104 This does not work properly on Mac.
8105
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008106 When {how} is given and it is 'n' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008107 sorted numerical (Implementation detail: this uses the
8108 strtod() function to parse numbers, Strings, Lists, Dicts and
8109 Funcrefs will be considered as being 0).
8110
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008111 When {how} is given and it is 'N' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008112 sorted numerical. This is like 'n' but a string containing
8113 digits will be used as the number they represent.
8114
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008115 When {how} is given and it is 'f' then all items will be
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008116 sorted numerical. All values must be a Number or a Float.
8117
Bram Moolenaar2007dd42022-02-23 13:17:47 +00008118 When {how} is a |Funcref| or a function name, this function
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008119 is called to compare items. The function is invoked with two
8120 items as argument and must return zero if they are equal, 1 or
8121 bigger if the first one sorts after the second one, -1 or
8122 smaller if the first one sorts before the second one.
8123
8124 {dict} is for functions with the "dict" attribute. It will be
8125 used to set the local variable "self". |Dictionary-function|
8126
8127 The sort is stable, items which compare equal (as number or as
8128 string) will keep their relative position. E.g., when sorting
8129 on numbers, text strings will sort next to each other, in the
8130 same order as they were originally.
8131
8132 Can also be used as a |method|: >
8133 mylist->sort()
8134
8135< Also see |uniq()|.
8136
8137 Example: >
8138 func MyCompare(i1, i2)
8139 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8140 endfunc
8141 eval mylist->sort("MyCompare")
8142< A shorter compare version for this specific simple case, which
8143 ignores overflow: >
8144 func MyCompare(i1, i2)
8145 return a:i1 - a:i2
8146 endfunc
8147< For a simple expression you can use a lambda: >
8148 eval mylist->sort({i1, i2 -> i1 - i2})
8149<
8150sound_clear() *sound_clear()*
8151 Stop playing all sounds.
8152
8153 On some Linux systems you may need the libcanberra-pulse
8154 package, otherwise sound may not stop.
8155
8156 {only available when compiled with the |+sound| feature}
8157
8158 *sound_playevent()*
8159sound_playevent({name} [, {callback}])
8160 Play a sound identified by {name}. Which event names are
8161 supported depends on the system. Often the XDG sound names
8162 are used. On Ubuntu they may be found in
8163 /usr/share/sounds/freedesktop/stereo. Example: >
8164 call sound_playevent('bell')
8165< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8166 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8167 SystemStart, SystemWelcome, etc.
8168
8169 When {callback} is specified it is invoked when the sound is
8170 finished. The first argument is the sound ID, the second
8171 argument is the status:
8172 0 sound was played to the end
8173 1 sound was interrupted
8174 2 error occurred after sound started
8175 Example: >
8176 func Callback(id, status)
8177 echomsg "sound " .. a:id .. " finished with " .. a:status
8178 endfunc
8179 call sound_playevent('bell', 'Callback')
8180
8181< MS-Windows: {callback} doesn't work for this function.
8182
8183 Returns the sound ID, which can be passed to `sound_stop()`.
8184 Returns zero if the sound could not be played.
8185
8186 Can also be used as a |method|: >
8187 GetSoundName()->sound_playevent()
8188
8189< {only available when compiled with the |+sound| feature}
8190
8191 *sound_playfile()*
8192sound_playfile({path} [, {callback}])
8193 Like `sound_playevent()` but play sound file {path}. {path}
8194 must be a full path. On Ubuntu you may find files to play
8195 with this command: >
8196 :!find /usr/share/sounds -type f | grep -v index.theme
8197
8198< Can also be used as a |method|: >
8199 GetSoundPath()->sound_playfile()
8200
Bram Moolenaar1588bc82022-03-08 21:35:07 +00008201< {only available when compiled with the |+sound| feature}
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008202
8203
8204sound_stop({id}) *sound_stop()*
8205 Stop playing sound {id}. {id} must be previously returned by
8206 `sound_playevent()` or `sound_playfile()`.
8207
8208 On some Linux systems you may need the libcanberra-pulse
8209 package, otherwise sound may not stop.
8210
8211 On MS-Windows, this does not work for event sound started by
8212 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8213
8214 Can also be used as a |method|: >
8215 soundid->sound_stop()
8216
8217< {only available when compiled with the |+sound| feature}
8218
8219 *soundfold()*
8220soundfold({word})
8221 Return the sound-folded equivalent of {word}. Uses the first
8222 language in 'spelllang' for the current window that supports
8223 soundfolding. 'spell' must be set. When no sound folding is
8224 possible the {word} is returned unmodified.
8225 This can be used for making spelling suggestions. Note that
8226 the method can be quite slow.
8227
8228 Can also be used as a |method|: >
8229 GetWord()->soundfold()
8230<
8231 *spellbadword()*
8232spellbadword([{sentence}])
8233 Without argument: The result is the badly spelled word under
8234 or after the cursor. The cursor is moved to the start of the
8235 bad word. When no bad word is found in the cursor line the
8236 result is an empty string and the cursor doesn't move.
8237
8238 With argument: The result is the first word in {sentence} that
8239 is badly spelled. If there are no spelling mistakes the
8240 result is an empty string.
8241
8242 The return value is a list with two items:
8243 - The badly spelled word or an empty string.
8244 - The type of the spelling error:
8245 "bad" spelling mistake
8246 "rare" rare word
8247 "local" word only valid in another region
8248 "caps" word should start with Capital
8249 Example: >
8250 echo spellbadword("the quik brown fox")
8251< ['quik', 'bad'] ~
8252
8253 The spelling information for the current window and the value
8254 of 'spelllang' are used.
8255
8256 Can also be used as a |method|: >
8257 GetText()->spellbadword()
8258<
8259 *spellsuggest()*
8260spellsuggest({word} [, {max} [, {capital}]])
8261 Return a |List| with spelling suggestions to replace {word}.
8262 When {max} is given up to this number of suggestions are
8263 returned. Otherwise up to 25 suggestions are returned.
8264
8265 When the {capital} argument is given and it's non-zero only
8266 suggestions with a leading capital will be given. Use this
8267 after a match with 'spellcapcheck'.
8268
8269 {word} can be a badly spelled word followed by other text.
8270 This allows for joining two words that were split. The
8271 suggestions also include the following text, thus you can
8272 replace a line.
8273
8274 {word} may also be a good word. Similar words will then be
8275 returned. {word} itself is not included in the suggestions,
8276 although it may appear capitalized.
8277
8278 The spelling information for the current window is used. The
8279 values of 'spelllang' and 'spellsuggest' are used.
8280
8281 Can also be used as a |method|: >
8282 GetWord()->spellsuggest()
8283
8284split({string} [, {pattern} [, {keepempty}]]) *split()*
8285 Make a |List| out of {string}. When {pattern} is omitted or
8286 empty each white-separated sequence of characters becomes an
8287 item.
8288 Otherwise the string is split where {pattern} matches,
8289 removing the matched characters. 'ignorecase' is not used
8290 here, add \c to ignore case. |/\c|
8291 When the first or last item is empty it is omitted, unless the
8292 {keepempty} argument is given and it's non-zero.
8293 Other empty items are kept when {pattern} matches at least one
8294 character or when {keepempty} is non-zero.
8295 Example: >
8296 :let words = split(getline('.'), '\W\+')
8297< To split a string in individual characters: >
8298 :for c in split(mystring, '\zs')
8299< If you want to keep the separator you can also use '\zs' at
8300 the end of the pattern: >
8301 :echo split('abc:def:ghi', ':\zs')
8302< ['abc:', 'def:', 'ghi'] ~
8303 Splitting a table where the first element can be empty: >
8304 :let items = split(line, ':', 1)
8305< The opposite function is |join()|.
8306
8307 Can also be used as a |method|: >
8308 GetString()->split()
8309
8310sqrt({expr}) *sqrt()*
8311 Return the non-negative square root of Float {expr} as a
8312 |Float|.
8313 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8314 is negative the result is NaN (Not a Number).
8315 Examples: >
8316 :echo sqrt(100)
8317< 10.0 >
8318 :echo sqrt(-4.01)
8319< nan
8320 "nan" may be different, it depends on system libraries.
8321
8322 Can also be used as a |method|: >
8323 Compute()->sqrt()
8324<
8325 {only available when compiled with the |+float| feature}
8326
8327
8328srand([{expr}]) *srand()*
8329 Initialize seed used by |rand()|:
8330 - If {expr} is not given, seed values are initialized by
8331 reading from /dev/urandom, if possible, or using time(NULL)
8332 a.k.a. epoch time otherwise; this only has second accuracy.
8333 - If {expr} is given it must be a Number. It is used to
8334 initialize the seed values. This is useful for testing or
8335 when a predictable sequence is intended.
8336
8337 Examples: >
8338 :let seed = srand()
8339 :let seed = srand(userinput)
8340 :echo rand(seed)
8341
8342state([{what}]) *state()*
8343 Return a string which contains characters indicating the
8344 current state. Mostly useful in callbacks that want to do
8345 work that may not always be safe. Roughly this works like:
8346 - callback uses state() to check if work is safe to do.
8347 Yes: then do it right away.
8348 No: add to work queue and add a |SafeState| and/or
8349 |SafeStateAgain| autocommand (|SafeState| triggers at
8350 toplevel, |SafeStateAgain| triggers after handling
8351 messages and callbacks).
8352 - When SafeState or SafeStateAgain is triggered and executes
8353 your autocommand, check with `state()` if the work can be
8354 done now, and if yes remove it from the queue and execute.
8355 Remove the autocommand if the queue is now empty.
8356 Also see |mode()|.
8357
8358 When {what} is given only characters in this string will be
8359 added. E.g, this checks if the screen has scrolled: >
8360 if state('s') == ''
8361 " screen has not scrolled
8362<
8363 These characters indicate the state, generally indicating that
8364 something is busy:
8365 m halfway a mapping, :normal command, feedkeys() or
8366 stuffed command
8367 o operator pending, e.g. after |d|
8368 a Insert mode autocomplete active
8369 x executing an autocommand
8370 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
8371 ch_readraw() when reading json
8372 S not triggering SafeState or SafeStateAgain, e.g. after
8373 |f| or a count
8374 c callback invoked, including timer (repeats for
8375 recursiveness up to "ccc")
8376 s screen has scrolled for messages
8377
8378str2float({string} [, {quoted}]) *str2float()*
8379 Convert String {string} to a Float. This mostly works the
8380 same as when using a floating point number in an expression,
8381 see |floating-point-format|. But it's a bit more permissive.
8382 E.g., "1e40" is accepted, while in an expression you need to
8383 write "1.0e40". The hexadecimal form "0x123" is also
8384 accepted, but not others, like binary or octal.
8385 When {quoted} is present and non-zero then embedded single
8386 quotes before the dot are ignored, thus "1'000.0" is a
8387 thousand.
8388 Text after the number is silently ignored.
8389 The decimal point is always '.', no matter what the locale is
8390 set to. A comma ends the number: "12,345.67" is converted to
8391 12.0. You can strip out thousands separators with
8392 |substitute()|: >
8393 let f = str2float(substitute(text, ',', '', 'g'))
8394<
8395 Can also be used as a |method|: >
8396 let f = text->substitute(',', '', 'g')->str2float()
8397<
8398 {only available when compiled with the |+float| feature}
8399
8400str2list({string} [, {utf8}]) *str2list()*
8401 Return a list containing the number values which represent
8402 each character in String {string}. Examples: >
8403 str2list(" ") returns [32]
8404 str2list("ABC") returns [65, 66, 67]
8405< |list2str()| does the opposite.
8406
8407 When {utf8} is omitted or zero, the current 'encoding' is used.
8408 When {utf8} is TRUE, always treat the String as UTF-8
8409 characters. With UTF-8 composing characters are handled
8410 properly: >
8411 str2list("á") returns [97, 769]
8412
8413< Can also be used as a |method|: >
8414 GetString()->str2list()
8415
8416
8417str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
8418 Convert string {string} to a number.
8419 {base} is the conversion base, it can be 2, 8, 10 or 16.
8420 When {quoted} is present and non-zero then embedded single
8421 quotes are ignored, thus "1'000'000" is a million.
8422
8423 When {base} is omitted base 10 is used. This also means that
8424 a leading zero doesn't cause octal conversion to be used, as
8425 with the default String to Number conversion. Example: >
8426 let nr = str2nr('0123')
8427<
8428 When {base} is 16 a leading "0x" or "0X" is ignored. With a
8429 different base the result will be zero. Similarly, when
8430 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
8431 {base} is 2 a leading "0b" or "0B" is ignored.
8432 Text after the number is silently ignored.
8433
8434 Can also be used as a |method|: >
8435 GetText()->str2nr()
8436
8437
8438strcharlen({string}) *strcharlen()*
8439 The result is a Number, which is the number of characters
8440 in String {string}. Composing characters are ignored.
8441 |strchars()| can count the number of characters, counting
8442 composing characters separately.
8443
8444 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8445
8446 Can also be used as a |method|: >
8447 GetText()->strcharlen()
8448
8449
8450strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
8451 Like |strpart()| but using character index and length instead
8452 of byte index and length.
8453 When {skipcc} is omitted or zero, composing characters are
8454 counted separately.
8455 When {skipcc} set to 1, Composing characters are ignored,
8456 similar to |slice()|.
8457 When a character index is used where a character does not
8458 exist it is omitted and counted as one character. For
8459 example: >
8460 strcharpart('abc', -1, 2)
8461< results in 'a'.
8462
8463 Can also be used as a |method|: >
8464 GetText()->strcharpart(5)
8465
8466
8467strchars({string} [, {skipcc}]) *strchars()*
8468 The result is a Number, which is the number of characters
8469 in String {string}.
8470 When {skipcc} is omitted or zero, composing characters are
8471 counted separately.
8472 When {skipcc} set to 1, Composing characters are ignored.
8473 |strcharlen()| always does this.
8474
8475 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
8476
8477 {skipcc} is only available after 7.4.755. For backward
8478 compatibility, you can define a wrapper function: >
8479 if has("patch-7.4.755")
8480 function s:strchars(str, skipcc)
8481 return strchars(a:str, a:skipcc)
8482 endfunction
8483 else
8484 function s:strchars(str, skipcc)
8485 if a:skipcc
8486 return strlen(substitute(a:str, ".", "x", "g"))
8487 else
8488 return strchars(a:str)
8489 endif
8490 endfunction
8491 endif
8492<
8493 Can also be used as a |method|: >
8494 GetText()->strchars()
8495
8496strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
8497 The result is a Number, which is the number of display cells
8498 String {string} occupies on the screen when it starts at {col}
8499 (first column is zero). When {col} is omitted zero is used.
8500 Otherwise it is the screen column where to start. This
8501 matters for Tab characters.
8502 The option settings of the current window are used. This
8503 matters for anything that's displayed differently, such as
8504 'tabstop' and 'display'.
8505 When {string} contains characters with East Asian Width Class
8506 Ambiguous, this function's return value depends on 'ambiwidth'.
8507 Also see |strlen()|, |strwidth()| and |strchars()|.
8508
8509 Can also be used as a |method|: >
8510 GetText()->strdisplaywidth()
8511
8512strftime({format} [, {time}]) *strftime()*
8513 The result is a String, which is a formatted date and time, as
8514 specified by the {format} string. The given {time} is used,
8515 or the current time if no time is given. The accepted
8516 {format} depends on your system, thus this is not portable!
8517 See the manual page of the C function strftime() for the
8518 format. The maximum length of the result is 80 characters.
8519 See also |localtime()|, |getftime()| and |strptime()|.
8520 The language can be changed with the |:language| command.
8521 Examples: >
8522 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8523 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8524 :echo strftime("%y%m%d %T") 970427 11:53:55
8525 :echo strftime("%H:%M") 11:55
8526 :echo strftime("%c", getftime("file.c"))
8527 Show mod time of file.c.
8528< Not available on all systems. To check use: >
8529 :if exists("*strftime")
8530
8531< Can also be used as a |method|: >
8532 GetFormat()->strftime()
8533
8534strgetchar({str}, {index}) *strgetchar()*
8535 Get character {index} from {str}. This uses a character
8536 index, not a byte index. Composing characters are considered
8537 separate characters here.
8538 Also see |strcharpart()| and |strchars()|.
8539
8540 Can also be used as a |method|: >
8541 GetText()->strgetchar(5)
8542
8543stridx({haystack}, {needle} [, {start}]) *stridx()*
8544 The result is a Number, which gives the byte index in
8545 {haystack} of the first occurrence of the String {needle}.
8546 If {start} is specified, the search starts at index {start}.
8547 This can be used to find a second match: >
8548 :let colon1 = stridx(line, ":")
8549 :let colon2 = stridx(line, ":", colon1 + 1)
8550< The search is done case-sensitive.
8551 For pattern searches use |match()|.
8552 -1 is returned if the {needle} does not occur in {haystack}.
8553 See also |strridx()|.
8554 Examples: >
8555 :echo stridx("An Example", "Example") 3
8556 :echo stridx("Starting point", "Start") 0
8557 :echo stridx("Starting point", "start") -1
8558< *strstr()* *strchr()*
8559 stridx() works similar to the C function strstr(). When used
8560 with a single character it works similar to strchr().
8561
8562 Can also be used as a |method|: >
8563 GetHaystack()->stridx(needle)
8564<
8565 *string()*
8566string({expr}) Return {expr} converted to a String. If {expr} is a Number,
8567 Float, String, Blob or a composition of them, then the result
8568 can be parsed back with |eval()|.
8569 {expr} type result ~
8570 String 'string' (single quotes are doubled)
8571 Number 123
8572 Float 123.123456 or 1.123456e8
8573 Funcref function('name')
8574 Blob 0z00112233.44556677.8899
8575 List [item, item]
8576 Dictionary {key: value, key: value}
8577
8578 When a |List| or |Dictionary| has a recursive reference it is
8579 replaced by "[...]" or "{...}". Using eval() on the result
8580 will then fail.
8581
8582 Can also be used as a |method|: >
8583 mylist->string()
8584
8585< Also see |strtrans()|.
8586
8587
8588strlen({string}) *strlen()*
8589 The result is a Number, which is the length of the String
8590 {string} in bytes.
8591 If the argument is a Number it is first converted to a String.
8592 For other types an error is given.
8593 If you want to count the number of multibyte characters use
8594 |strchars()|.
8595 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
8596
8597 Can also be used as a |method|: >
8598 GetString()->strlen()
8599
8600strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
8601 The result is a String, which is part of {src}, starting from
8602 byte {start}, with the byte length {len}.
8603 When {chars} is present and TRUE then {len} is the number of
8604 characters positions (composing characters are not counted
8605 separately, thus "1" means one base character and any
8606 following composing characters).
8607 To count {start} as characters instead of bytes use
8608 |strcharpart()|.
8609
8610 When bytes are selected which do not exist, this doesn't
8611 result in an error, the bytes are simply omitted.
8612 If {len} is missing, the copy continues from {start} till the
8613 end of the {src}. >
8614 strpart("abcdefg", 3, 2) == "de"
8615 strpart("abcdefg", -2, 4) == "ab"
8616 strpart("abcdefg", 5, 4) == "fg"
8617 strpart("abcdefg", 3) == "defg"
8618
8619< Note: To get the first character, {start} must be 0. For
8620 example, to get the character under the cursor: >
8621 strpart(getline("."), col(".") - 1, 1, v:true)
8622<
8623 Can also be used as a |method|: >
8624 GetText()->strpart(5)
8625
8626strptime({format}, {timestring}) *strptime()*
8627 The result is a Number, which is a unix timestamp representing
8628 the date and time in {timestring}, which is expected to match
8629 the format specified in {format}.
8630
8631 The accepted {format} depends on your system, thus this is not
8632 portable! See the manual page of the C function strptime()
8633 for the format. Especially avoid "%c". The value of $TZ also
8634 matters.
8635
8636 If the {timestring} cannot be parsed with {format} zero is
8637 returned. If you do not know the format of {timestring} you
8638 can try different {format} values until you get a non-zero
8639 result.
8640
8641 See also |strftime()|.
8642 Examples: >
8643 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
8644< 862156163 >
8645 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
8646< Sun Apr 27 11:53:55 1997 >
8647 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
8648< Sun Apr 27 12:53:55 1997
8649
8650 Can also be used as a |method|: >
8651 GetFormat()->strptime(timestring)
8652<
8653 Not available on all systems. To check use: >
8654 :if exists("*strptime")
8655
8656strridx({haystack}, {needle} [, {start}]) *strridx()*
8657 The result is a Number, which gives the byte index in
8658 {haystack} of the last occurrence of the String {needle}.
8659 When {start} is specified, matches beyond this index are
8660 ignored. This can be used to find a match before a previous
8661 match: >
8662 :let lastcomma = strridx(line, ",")
8663 :let comma2 = strridx(line, ",", lastcomma - 1)
8664< The search is done case-sensitive.
8665 For pattern searches use |match()|.
8666 -1 is returned if the {needle} does not occur in {haystack}.
8667 If the {needle} is empty the length of {haystack} is returned.
8668 See also |stridx()|. Examples: >
8669 :echo strridx("an angry armadillo", "an") 3
8670< *strrchr()*
8671 When used with a single character it works similar to the C
8672 function strrchr().
8673
8674 Can also be used as a |method|: >
8675 GetHaystack()->strridx(needle)
8676
8677strtrans({string}) *strtrans()*
8678 The result is a String, which is {string} with all unprintable
8679 characters translated into printable characters |'isprint'|.
8680 Like they are shown in a window. Example: >
8681 echo strtrans(@a)
8682< This displays a newline in register a as "^@" instead of
8683 starting a new line.
8684
8685 Can also be used as a |method|: >
8686 GetString()->strtrans()
8687
8688strwidth({string}) *strwidth()*
8689 The result is a Number, which is the number of display cells
8690 String {string} occupies. A Tab character is counted as one
8691 cell, alternatively use |strdisplaywidth()|.
8692 When {string} contains characters with East Asian Width Class
8693 Ambiguous, this function's return value depends on 'ambiwidth'.
8694 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
8695
8696 Can also be used as a |method|: >
8697 GetString()->strwidth()
8698
8699submatch({nr} [, {list}]) *submatch()* *E935*
8700 Only for an expression in a |:substitute| command or
8701 substitute() function.
8702 Returns the {nr}'th submatch of the matched text. When {nr}
8703 is 0 the whole matched text is returned.
8704 Note that a NL in the string can stand for a line break of a
8705 multi-line match or a NUL character in the text.
8706 Also see |sub-replace-expression|.
8707
8708 If {list} is present and non-zero then submatch() returns
8709 a list of strings, similar to |getline()| with two arguments.
8710 NL characters in the text represent NUL characters in the
8711 text.
8712 Only returns more than one item for |:substitute|, inside
8713 |substitute()| this list will always contain one or zero
8714 items, since there are no real line breaks.
8715
8716 When substitute() is used recursively only the submatches in
8717 the current (deepest) call can be obtained.
8718
8719 Examples: >
8720 :s/\d\+/\=submatch(0) + 1/
8721 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
8722< This finds the first number in the line and adds one to it.
8723 A line break is included as a newline character.
8724
8725 Can also be used as a |method|: >
8726 GetNr()->submatch()
8727
8728substitute({string}, {pat}, {sub}, {flags}) *substitute()*
8729 The result is a String, which is a copy of {string}, in which
8730 the first match of {pat} is replaced with {sub}.
8731 When {flags} is "g", all matches of {pat} in {string} are
8732 replaced. Otherwise {flags} should be "".
8733
8734 This works like the ":substitute" command (without any flags).
8735 But the matching with {pat} is always done like the 'magic'
8736 option is set and 'cpoptions' is empty (to make scripts
8737 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
8738 if you want to ignore or match case and ignore 'ignorecase'.
8739 'smartcase' is not used. See |string-match| for how {pat} is
8740 used.
8741
8742 A "~" in {sub} is not replaced with the previous {sub}.
8743 Note that some codes in {sub} have a special meaning
8744 |sub-replace-special|. For example, to replace something with
8745 "\n" (two characters), use "\\\\n" or '\\n'.
8746
8747 When {pat} does not match in {string}, {string} is returned
8748 unmodified.
8749
8750 Example: >
8751 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
8752< This removes the last component of the 'path' option. >
8753 :echo substitute("testing", ".*", "\\U\\0", "")
8754< results in "TESTING".
8755
8756 When {sub} starts with "\=", the remainder is interpreted as
8757 an expression. See |sub-replace-expression|. Example: >
8758 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008759 \ '\=nr2char("0x" .. submatch(1))', 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008760
8761< When {sub} is a Funcref that function is called, with one
8762 optional argument. Example: >
8763 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
8764< The optional argument is a list which contains the whole
8765 matched string and up to nine submatches, like what
8766 |submatch()| returns. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008767 :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008768
8769< Can also be used as a |method|: >
8770 GetString()->substitute(pat, sub, flags)
8771
8772swapinfo({fname}) *swapinfo()*
8773 The result is a dictionary, which holds information about the
8774 swapfile {fname}. The available fields are:
8775 version Vim version
8776 user user name
8777 host host name
8778 fname original file name
8779 pid PID of the Vim process that created the swap
8780 file
8781 mtime last modification time in seconds
8782 inode Optional: INODE number of the file
8783 dirty 1 if file was modified, 0 if not
8784 Note that "user" and "host" are truncated to at most 39 bytes.
8785 In case of failure an "error" item is added with the reason:
8786 Cannot open file: file not found or in accessible
8787 Cannot read file: cannot read first block
8788 Not a swap file: does not contain correct block ID
8789 Magic number mismatch: Info in first block is invalid
8790
8791 Can also be used as a |method|: >
8792 GetFilename()->swapinfo()
8793
8794swapname({buf}) *swapname()*
8795 The result is the swap file path of the buffer {expr}.
8796 For the use of {buf}, see |bufname()| above.
8797 If buffer {buf} is the current buffer, the result is equal to
8798 |:swapname| (unless there is no swap file).
8799 If buffer {buf} has no swap file, returns an empty string.
8800
8801 Can also be used as a |method|: >
8802 GetBufname()->swapname()
8803
8804synID({lnum}, {col}, {trans}) *synID()*
8805 The result is a Number, which is the syntax ID at the position
8806 {lnum} and {col} in the current window.
8807 The syntax ID can be used with |synIDattr()| and
8808 |synIDtrans()| to obtain syntax information about text.
8809
8810 {col} is 1 for the leftmost column, {lnum} is 1 for the first
8811 line. 'synmaxcol' applies, in a longer line zero is returned.
8812 Note that when the position is after the last character,
8813 that's where the cursor can be in Insert mode, synID() returns
8814 zero. {lnum} is used like with |getline()|.
8815
8816 When {trans} is |TRUE|, transparent items are reduced to the
8817 item that they reveal. This is useful when wanting to know
8818 the effective color. When {trans} is |FALSE|, the transparent
8819 item is returned. This is useful when wanting to know which
8820 syntax item is effective (e.g. inside parens).
8821 Warning: This function can be very slow. Best speed is
8822 obtained by going through the file in forward direction.
8823
8824 Example (echoes the name of the syntax item under the cursor): >
8825 :echo synIDattr(synID(line("."), col("."), 1), "name")
8826<
8827
8828synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
8829 The result is a String, which is the {what} attribute of
8830 syntax ID {synID}. This can be used to obtain information
8831 about a syntax item.
8832 {mode} can be "gui", "cterm" or "term", to get the attributes
8833 for that mode. When {mode} is omitted, or an invalid value is
8834 used, the attributes for the currently active highlighting are
8835 used (GUI, cterm or term).
8836 Use synIDtrans() to follow linked highlight groups.
8837 {what} result
8838 "name" the name of the syntax item
8839 "fg" foreground color (GUI: color name used to set
8840 the color, cterm: color number as a string,
8841 term: empty string)
8842 "bg" background color (as with "fg")
8843 "font" font name (only available in the GUI)
8844 |highlight-font|
8845 "sp" special color for the GUI (as with "fg")
8846 |highlight-guisp|
8847 "ul" underline color for cterm: number as a string
8848 "fg#" like "fg", but for the GUI and the GUI is
8849 running the name in "#RRGGBB" form
8850 "bg#" like "fg#" for "bg"
8851 "sp#" like "fg#" for "sp"
8852 "bold" "1" if bold
8853 "italic" "1" if italic
8854 "reverse" "1" if reverse
8855 "inverse" "1" if inverse (= reverse)
8856 "standout" "1" if standout
8857 "underline" "1" if underlined
8858 "undercurl" "1" if undercurled
8859 "strike" "1" if strikethrough
8860
8861 Example (echoes the color of the syntax item under the
8862 cursor): >
8863 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
8864<
8865 Can also be used as a |method|: >
8866 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8867
8868
8869synIDtrans({synID}) *synIDtrans()*
8870 The result is a Number, which is the translated syntax ID of
8871 {synID}. This is the syntax group ID of what is being used to
8872 highlight the character. Highlight links given with
8873 ":highlight link" are followed.
8874
8875 Can also be used as a |method|: >
8876 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
8877
8878synconcealed({lnum}, {col}) *synconcealed()*
8879 The result is a |List| with currently three items:
8880 1. The first item in the list is 0 if the character at the
8881 position {lnum} and {col} is not part of a concealable
8882 region, 1 if it is. {lnum} is used like with |getline()|.
8883 2. The second item in the list is a string. If the first item
8884 is 1, the second item contains the text which will be
8885 displayed in place of the concealed text, depending on the
8886 current setting of 'conceallevel' and 'listchars'.
8887 3. The third and final item in the list is a number
8888 representing the specific syntax region matched in the
8889 line. When the character is not concealed the value is
8890 zero. This allows detection of the beginning of a new
8891 concealable region if there are two consecutive regions
8892 with the same replacement character. For an example, if
8893 the text is "123456" and both "23" and "45" are concealed
8894 and replaced by the character "X", then:
8895 call returns ~
8896 synconcealed(lnum, 1) [0, '', 0]
8897 synconcealed(lnum, 2) [1, 'X', 1]
8898 synconcealed(lnum, 3) [1, 'X', 1]
8899 synconcealed(lnum, 4) [1, 'X', 2]
8900 synconcealed(lnum, 5) [1, 'X', 2]
8901 synconcealed(lnum, 6) [0, '', 0]
8902
8903
8904synstack({lnum}, {col}) *synstack()*
8905 Return a |List|, which is the stack of syntax items at the
8906 position {lnum} and {col} in the current window. {lnum} is
8907 used like with |getline()|. Each item in the List is an ID
8908 like what |synID()| returns.
8909 The first item in the List is the outer region, following are
8910 items contained in that one. The last one is what |synID()|
8911 returns, unless not the whole item is highlighted or it is a
8912 transparent item.
8913 This function is useful for debugging a syntax file.
8914 Example that shows the syntax stack under the cursor: >
8915 for id in synstack(line("."), col("."))
8916 echo synIDattr(id, "name")
8917 endfor
8918< When the position specified with {lnum} and {col} is invalid
8919 nothing is returned. The position just after the last
8920 character in a line and the first column in an empty line are
8921 valid positions.
8922
8923system({expr} [, {input}]) *system()* *E677*
8924 Get the output of the shell command {expr} as a |String|. See
8925 |systemlist()| to get the output as a |List|.
8926
8927 When {input} is given and is a |String| this string is written
8928 to a file and passed as stdin to the command. The string is
8929 written as-is, you need to take care of using the correct line
8930 separators yourself.
8931 If {input} is given and is a |List| it is written to the file
8932 in a way |writefile()| does with {binary} set to "b" (i.e.
8933 with a newline between each list item with newlines inside
8934 list items converted to NULs).
8935 When {input} is given and is a number that is a valid id for
8936 an existing buffer then the content of the buffer is written
8937 to the file line by line, each line terminated by a NL and
8938 NULs characters where the text has a NL.
8939
8940 Pipes are not used, the 'shelltemp' option is not used.
8941
8942 When prepended by |:silent| the terminal will not be set to
8943 cooked mode. This is meant to be used for commands that do
8944 not need the user to type. It avoids stray characters showing
8945 up on the screen which require |CTRL-L| to remove. >
8946 :silent let f = system('ls *.vim')
8947<
8948 Note: Use |shellescape()| or |::S| with |expand()| or
8949 |fnamemodify()| to escape special characters in a command
8950 argument. Newlines in {expr} may cause the command to fail.
8951 The characters in 'shellquote' and 'shellxquote' may also
8952 cause trouble.
8953 This is not to be used for interactive commands.
8954
8955 The result is a String. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008956 :let files = system('ls ' .. shellescape(expand('%:h')))
8957 :let files = system('ls ' .. expand('%:h:S'))
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00008958
8959< To make the result more system-independent, the shell output
8960 is filtered to replace <CR> with <NL> for Macintosh, and
8961 <CR><NL> with <NL> for DOS-like systems.
8962 To avoid the string being truncated at a NUL, all NUL
8963 characters are replaced with SOH (0x01).
8964
8965 The command executed is constructed using several options:
8966 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
8967 ({tmp} is an automatically generated file name).
8968 For Unix, braces are put around {expr} to allow for
8969 concatenated commands.
8970
8971 The command will be executed in "cooked" mode, so that a
8972 CTRL-C will interrupt the command (on Unix at least).
8973
8974 The resulting error code can be found in |v:shell_error|.
8975 This function will fail in |restricted-mode|.
8976
8977 Note that any wrong value in the options mentioned above may
8978 make the function fail. It has also been reported to fail
8979 when using a security agent application.
8980 Unlike ":!cmd" there is no automatic check for changed files.
8981 Use |:checktime| to force a check.
8982
8983 Can also be used as a |method|: >
8984 :echo GetCmd()->system()
8985
8986
8987systemlist({expr} [, {input}]) *systemlist()*
8988 Same as |system()|, but returns a |List| with lines (parts of
8989 output separated by NL) with NULs transformed into NLs. Output
8990 is the same as |readfile()| will output with {binary} argument
8991 set to "b", except that there is no extra empty item when the
8992 result ends in a NL.
8993 Note that on MS-Windows you may get trailing CR characters.
8994
8995 To see the difference between "echo hello" and "echo -n hello"
8996 use |system()| and |split()|: >
8997 echo system('echo hello')->split('\n', 1)
8998<
8999 Returns an empty string on error.
9000
9001 Can also be used as a |method|: >
9002 :echo GetCmd()->systemlist()
9003
9004
9005tabpagebuflist([{arg}]) *tabpagebuflist()*
9006 The result is a |List|, where each item is the number of the
9007 buffer associated with each window in the current tab page.
9008 {arg} specifies the number of the tab page to be used. When
9009 omitted the current tab page is used.
9010 When {arg} is invalid the number zero is returned.
9011 To get a list of all buffers in all tabs use this: >
9012 let buflist = []
9013 for i in range(tabpagenr('$'))
9014 call extend(buflist, tabpagebuflist(i + 1))
9015 endfor
9016< Note that a buffer may appear in more than one window.
9017
9018 Can also be used as a |method|: >
9019 GetTabpage()->tabpagebuflist()
9020
9021tabpagenr([{arg}]) *tabpagenr()*
9022 The result is a Number, which is the number of the current
9023 tab page. The first tab page has number 1.
9024
9025 The optional argument {arg} supports the following values:
9026 $ the number of the last tab page (the tab page
9027 count).
9028 # the number of the last accessed tab page
9029 (where |g<Tab>| goes to). if there is no
9030 previous tab page 0 is returned.
9031 The number can be used with the |:tab| command.
9032
9033
9034tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
9035 Like |winnr()| but for tab page {tabarg}.
9036 {tabarg} specifies the number of tab page to be used.
9037 {arg} is used like with |winnr()|:
9038 - When omitted the current window number is returned. This is
9039 the window which will be used when going to this tab page.
9040 - When "$" the number of windows is returned.
9041 - When "#" the previous window nr is returned.
9042 Useful examples: >
9043 tabpagewinnr(1) " current window of tab page 1
9044 tabpagewinnr(4, '$') " number of windows in tab page 4
9045< When {tabarg} is invalid zero is returned.
9046
9047 Can also be used as a |method|: >
9048 GetTabpage()->tabpagewinnr()
9049<
9050 *tagfiles()*
9051tagfiles() Returns a |List| with the file names used to search for tags
9052 for the current buffer. This is the 'tags' option expanded.
9053
9054
9055taglist({expr} [, {filename}]) *taglist()*
9056 Returns a |List| of tags matching the regular expression {expr}.
9057
9058 If {filename} is passed it is used to prioritize the results
9059 in the same way that |:tselect| does. See |tag-priority|.
9060 {filename} should be the full path of the file.
9061
9062 Each list item is a dictionary with at least the following
9063 entries:
9064 name Name of the tag.
9065 filename Name of the file where the tag is
9066 defined. It is either relative to the
9067 current directory or a full path.
9068 cmd Ex command used to locate the tag in
9069 the file.
9070 kind Type of the tag. The value for this
9071 entry depends on the language specific
9072 kind values. Only available when
9073 using a tags file generated by
Bram Moolenaar47c532e2022-03-19 15:18:53 +00009074 Universal/Exuberant ctags or hdrtag.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009075 static A file specific tag. Refer to
9076 |static-tag| for more information.
9077 More entries may be present, depending on the content of the
9078 tags file: access, implementation, inherits and signature.
9079 Refer to the ctags documentation for information about these
9080 fields. For C code the fields "struct", "class" and "enum"
9081 may appear, they give the name of the entity the tag is
9082 contained in.
9083
9084 The ex-command "cmd" can be either an ex search pattern, a
9085 line number or a line number followed by a byte number.
9086
9087 If there are no matching tags, then an empty list is returned.
9088
9089 To get an exact tag match, the anchors '^' and '$' should be
9090 used in {expr}. This also make the function work faster.
9091 Refer to |tag-regexp| for more information about the tag
9092 search regular expression pattern.
9093
9094 Refer to |'tags'| for information about how the tags file is
9095 located by Vim. Refer to |tags-file-format| for the format of
9096 the tags file generated by the different ctags tools.
9097
9098 Can also be used as a |method|: >
9099 GetTagpattern()->taglist()
9100
9101tan({expr}) *tan()*
9102 Return the tangent of {expr}, measured in radians, as a |Float|
9103 in the range [-inf, inf].
9104 {expr} must evaluate to a |Float| or a |Number|.
9105 Examples: >
9106 :echo tan(10)
9107< 0.648361 >
9108 :echo tan(-4.01)
9109< -1.181502
9110
9111 Can also be used as a |method|: >
9112 Compute()->tan()
9113<
9114 {only available when compiled with the |+float| feature}
9115
9116
9117tanh({expr}) *tanh()*
9118 Return the hyperbolic tangent of {expr} as a |Float| in the
9119 range [-1, 1].
9120 {expr} must evaluate to a |Float| or a |Number|.
9121 Examples: >
9122 :echo tanh(0.5)
9123< 0.462117 >
9124 :echo tanh(-1)
9125< -0.761594
9126
9127 Can also be used as a |method|: >
9128 Compute()->tanh()
9129<
9130 {only available when compiled with the |+float| feature}
9131
9132
9133tempname() *tempname()* *temp-file-name*
9134 The result is a String, which is the name of a file that
9135 doesn't exist. It can be used for a temporary file. The name
9136 is different for at least 26 consecutive calls. Example: >
9137 :let tmpfile = tempname()
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009138 :exe "redir > " .. tmpfile
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009139< For Unix, the file will be in a private directory |tempfile|.
9140 For MS-Windows forward slashes are used when the 'shellslash'
9141 option is set, or when 'shellcmdflag' starts with '-' and
9142 'shell' does not contain powershell or pwsh.
9143
9144
9145term_ functions are documented here: |terminal-function-details|
9146
9147
9148terminalprops() *terminalprops()*
9149 Returns a |Dictionary| with properties of the terminal that Vim
9150 detected from the response to |t_RV| request. See
9151 |v:termresponse| for the response itself. If |v:termresponse|
9152 is empty most values here will be 'u' for unknown.
9153 cursor_style whether sending |t_RS| works **
9154 cursor_blink_mode whether sending |t_RC| works **
9155 underline_rgb whether |t_8u| works **
9156 mouse mouse type supported
9157
9158 ** value 'u' for unknown, 'y' for yes, 'n' for no
9159
9160 If the |+termresponse| feature is missing then the result is
9161 an empty dictionary.
9162
9163 If "cursor_style" is 'y' then |t_RS| will be sent to request the
9164 current cursor style.
9165 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
9166 request the cursor blink status.
9167 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
9168 is not empty, Vim will detect the working of sending |t_RS|
9169 and |t_RC| on startup.
9170
9171 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
9172 This avoids sending it to xterm, which would clear the colors.
9173
9174 For "mouse" the value 'u' is unknown
9175
9176 Also see:
9177 - 'ambiwidth' - detected by using |t_u7|.
9178 - |v:termstyleresp| and |v:termblinkresp| for the response to
9179 |t_RS| and |t_RC|.
9180
9181
9182test_ functions are documented here: |test-functions-details|
9183
9184
9185 *timer_info()*
9186timer_info([{id}])
9187 Return a list with information about timers.
9188 When {id} is given only information about this timer is
9189 returned. When timer {id} does not exist an empty list is
9190 returned.
9191 When {id} is omitted information about all timers is returned.
9192
9193 For each timer the information is stored in a |Dictionary| with
9194 these items:
9195 "id" the timer ID
9196 "time" time the timer was started with
9197 "remaining" time until the timer fires
9198 "repeat" number of times the timer will still fire;
9199 -1 means forever
9200 "callback" the callback
9201 "paused" 1 if the timer is paused, 0 otherwise
9202
9203 Can also be used as a |method|: >
9204 GetTimer()->timer_info()
9205
9206< {only available when compiled with the |+timers| feature}
9207
9208timer_pause({timer}, {paused}) *timer_pause()*
9209 Pause or unpause a timer. A paused timer does not invoke its
9210 callback when its time expires. Unpausing a timer may cause
9211 the callback to be invoked almost immediately if enough time
9212 has passed.
9213
9214 Pausing a timer is useful to avoid the callback to be called
9215 for a short time.
9216
9217 If {paused} evaluates to a non-zero Number or a non-empty
9218 String, then the timer is paused, otherwise it is unpaused.
9219 See |non-zero-arg|.
9220
9221 Can also be used as a |method|: >
9222 GetTimer()->timer_pause(1)
9223
9224< {only available when compiled with the |+timers| feature}
9225
9226 *timer_start()* *timer* *timers*
9227timer_start({time}, {callback} [, {options}])
9228 Create a timer and return the timer ID.
9229
9230 {time} is the waiting time in milliseconds. This is the
9231 minimum time before invoking the callback. When the system is
9232 busy or Vim is not waiting for input the time will be longer.
9233
9234 {callback} is the function to call. It can be the name of a
9235 function or a |Funcref|. It is called with one argument, which
9236 is the timer ID. The callback is only invoked when Vim is
9237 waiting for input.
9238 If you want to show a message look at |popup_notification()|
9239 to avoid interfering with what the user is doing.
9240
9241 {options} is a dictionary. Supported entries:
9242 "repeat" Number of times to repeat calling the
9243 callback. -1 means forever. When not present
9244 the callback will be called once.
9245 If the timer causes an error three times in a
9246 row the repeat is cancelled. This avoids that
9247 Vim becomes unusable because of all the error
9248 messages.
9249
9250 Example: >
9251 func MyHandler(timer)
9252 echo 'Handler called'
9253 endfunc
9254 let timer = timer_start(500, 'MyHandler',
9255 \ {'repeat': 3})
9256< This will invoke MyHandler() three times at 500 msec
9257 intervals.
9258
9259 Can also be used as a |method|: >
9260 GetMsec()->timer_start(callback)
9261
9262< Not available in the |sandbox|.
9263 {only available when compiled with the |+timers| feature}
9264
9265timer_stop({timer}) *timer_stop()*
9266 Stop a timer. The timer callback will no longer be invoked.
9267 {timer} is an ID returned by timer_start(), thus it must be a
9268 Number. If {timer} does not exist there is no error.
9269
9270 Can also be used as a |method|: >
9271 GetTimer()->timer_stop()
9272
9273< {only available when compiled with the |+timers| feature}
9274
9275timer_stopall() *timer_stopall()*
9276 Stop all timers. The timer callbacks will no longer be
9277 invoked. Useful if a timer is misbehaving. If there are no
9278 timers there is no error.
9279
9280 {only available when compiled with the |+timers| feature}
9281
9282tolower({expr}) *tolower()*
9283 The result is a copy of the String given, with all uppercase
9284 characters turned into lowercase (just like applying |gu| to
9285 the string).
9286
9287 Can also be used as a |method|: >
9288 GetText()->tolower()
9289
9290toupper({expr}) *toupper()*
9291 The result is a copy of the String given, with all lowercase
9292 characters turned into uppercase (just like applying |gU| to
9293 the string).
9294
9295 Can also be used as a |method|: >
9296 GetText()->toupper()
9297
9298tr({src}, {fromstr}, {tostr}) *tr()*
9299 The result is a copy of the {src} string with all characters
9300 which appear in {fromstr} replaced by the character in that
9301 position in the {tostr} string. Thus the first character in
9302 {fromstr} is translated into the first character in {tostr}
9303 and so on. Exactly like the unix "tr" command.
9304 This code also deals with multibyte characters properly.
9305
9306 Examples: >
9307 echo tr("hello there", "ht", "HT")
9308< returns "Hello THere" >
9309 echo tr("<blob>", "<>", "{}")
9310< returns "{blob}"
9311
9312 Can also be used as a |method|: >
9313 GetText()->tr(from, to)
9314
9315trim({text} [, {mask} [, {dir}]]) *trim()*
9316 Return {text} as a String where any character in {mask} is
9317 removed from the beginning and/or end of {text}.
9318
9319 If {mask} is not given, {mask} is all characters up to 0x20,
9320 which includes Tab, space, NL and CR, plus the non-breaking
9321 space character 0xa0.
9322
9323 The optional {dir} argument specifies where to remove the
9324 characters:
9325 0 remove from the beginning and end of {text}
9326 1 remove only at the beginning of {text}
9327 2 remove only at the end of {text}
9328 When omitted both ends are trimmed.
9329
9330 This function deals with multibyte characters properly.
9331
9332 Examples: >
9333 echo trim(" some text ")
9334< returns "some text" >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009335 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL"
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009336< returns "RESERVE_TAIL" >
9337 echo trim("rm<Xrm<>X>rrm", "rm<>")
9338< returns "Xrm<>X" (characters in the middle are not removed) >
9339 echo trim(" vim ", " ", 2)
9340< returns " vim"
9341
9342 Can also be used as a |method|: >
9343 GetText()->trim()
9344
9345trunc({expr}) *trunc()*
9346 Return the largest integral value with magnitude less than or
9347 equal to {expr} as a |Float| (truncate towards zero).
9348 {expr} must evaluate to a |Float| or a |Number|.
9349 Examples: >
9350 echo trunc(1.456)
9351< 1.0 >
9352 echo trunc(-5.456)
9353< -5.0 >
9354 echo trunc(4.0)
9355< 4.0
9356
9357 Can also be used as a |method|: >
9358 Compute()->trunc()
9359<
9360 {only available when compiled with the |+float| feature}
9361
9362 *type()*
9363type({expr}) The result is a Number representing the type of {expr}.
9364 Instead of using the number directly, it is better to use the
9365 v:t_ variable that has the value:
9366 Number: 0 |v:t_number|
9367 String: 1 |v:t_string|
9368 Funcref: 2 |v:t_func|
9369 List: 3 |v:t_list|
9370 Dictionary: 4 |v:t_dict|
9371 Float: 5 |v:t_float|
9372 Boolean: 6 |v:t_bool| (v:false and v:true)
9373 None: 7 |v:t_none| (v:null and v:none)
9374 Job: 8 |v:t_job|
9375 Channel: 9 |v:t_channel|
9376 Blob: 10 |v:t_blob|
9377 For backward compatibility, this method can be used: >
9378 :if type(myvar) == type(0)
9379 :if type(myvar) == type("")
9380 :if type(myvar) == type(function("tr"))
9381 :if type(myvar) == type([])
9382 :if type(myvar) == type({})
9383 :if type(myvar) == type(0.0)
9384 :if type(myvar) == type(v:false)
9385 :if type(myvar) == type(v:none)
9386< To check if the v:t_ variables exist use this: >
9387 :if exists('v:t_number')
9388
9389< Can also be used as a |method|: >
9390 mylist->type()
9391
9392
9393typename({expr}) *typename()*
9394 Return a string representation of the type of {expr}.
9395 Example: >
9396 echo typename([1, 2, 3])
9397 list<number>
9398
9399
9400undofile({name}) *undofile()*
9401 Return the name of the undo file that would be used for a file
9402 with name {name} when writing. This uses the 'undodir'
9403 option, finding directories that exist. It does not check if
9404 the undo file exists.
9405 {name} is always expanded to the full path, since that is what
9406 is used internally.
9407 If {name} is empty undofile() returns an empty string, since a
9408 buffer without a file name will not write an undo file.
9409 Useful in combination with |:wundo| and |:rundo|.
9410 When compiled without the |+persistent_undo| option this always
9411 returns an empty string.
9412
9413 Can also be used as a |method|: >
9414 GetFilename()->undofile()
9415
9416undotree() *undotree()*
9417 Return the current state of the undo tree in a dictionary with
9418 the following items:
9419 "seq_last" The highest undo sequence number used.
9420 "seq_cur" The sequence number of the current position in
9421 the undo tree. This differs from "seq_last"
9422 when some changes were undone.
9423 "time_cur" Time last used for |:earlier| and related
9424 commands. Use |strftime()| to convert to
9425 something readable.
9426 "save_last" Number of the last file write. Zero when no
9427 write yet.
9428 "save_cur" Number of the current position in the undo
9429 tree.
9430 "synced" Non-zero when the last undo block was synced.
9431 This happens when waiting from input from the
9432 user. See |undo-blocks|.
9433 "entries" A list of dictionaries with information about
9434 undo blocks.
9435
9436 The first item in the "entries" list is the oldest undo item.
9437 Each List item is a |Dictionary| with these items:
9438 "seq" Undo sequence number. Same as what appears in
9439 |:undolist|.
9440 "time" Timestamp when the change happened. Use
9441 |strftime()| to convert to something readable.
9442 "newhead" Only appears in the item that is the last one
9443 that was added. This marks the last change
9444 and where further changes will be added.
9445 "curhead" Only appears in the item that is the last one
9446 that was undone. This marks the current
9447 position in the undo tree, the block that will
9448 be used by a redo command. When nothing was
9449 undone after the last change this item will
9450 not appear anywhere.
9451 "save" Only appears on the last block before a file
9452 write. The number is the write count. The
9453 first write has number 1, the last one the
9454 "save_last" mentioned above.
9455 "alt" Alternate entry. This is again a List of undo
9456 blocks. Each item may again have an "alt"
9457 item.
9458
9459uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9460 Remove second and succeeding copies of repeated adjacent
9461 {list} items in-place. Returns {list}. If you want a list
9462 to remain unmodified make a copy first: >
9463 :let newlist = uniq(copy(mylist))
9464< The default compare function uses the string representation of
9465 each item. For the use of {func} and {dict} see |sort()|.
9466
9467 Can also be used as a |method|: >
9468 mylist->uniq()
9469
9470values({dict}) *values()*
9471 Return a |List| with all the values of {dict}. The |List| is
9472 in arbitrary order. Also see |items()| and |keys()|.
9473
9474 Can also be used as a |method|: >
9475 mydict->values()
9476
9477virtcol({expr}) *virtcol()*
9478 The result is a Number, which is the screen column of the file
9479 position given with {expr}. That is, the last screen position
9480 occupied by the character at that position, when the screen
9481 would be of unlimited width. When there is a <Tab> at the
9482 position, the returned Number will be the column at the end of
9483 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
9484 set to 8, it returns 8. |conceal| is ignored.
9485 For the byte position use |col()|.
9486 For the use of {expr} see |col()|.
9487 When 'virtualedit' is used {expr} can be [lnum, col, off], where
9488 "off" is the offset in screen columns from the start of the
9489 character. E.g., a position within a <Tab> or after the last
9490 character. When "off" is omitted zero is used.
9491 When Virtual editing is active in the current mode, a position
9492 beyond the end of the line can be returned. |'virtualedit'|
9493 The accepted positions are:
9494 . the cursor position
9495 $ the end of the cursor line (the result is the
9496 number of displayed characters in the cursor line
9497 plus one)
9498 'x position of mark x (if the mark is not set, 0 is
9499 returned)
9500 v In Visual mode: the start of the Visual area (the
9501 cursor is the end). When not in Visual mode
9502 returns the cursor position. Differs from |'<| in
9503 that it's updated right away.
9504 Note that only marks in the current file can be used.
9505 Examples: >
9506 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
9507 virtcol("$") with text "foo^Lbar", returns 9
9508 virtcol("'t") with text " there", with 't at 'h', returns 6
9509< The first column is 1. 0 is returned for an error.
9510 A more advanced example that echoes the maximum length of
9511 all lines: >
9512 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
9513
9514< Can also be used as a |method|: >
9515 GetPos()->virtcol()
9516
9517
9518visualmode([{expr}]) *visualmode()*
9519 The result is a String, which describes the last Visual mode
9520 used in the current buffer. Initially it returns an empty
9521 string, but once Visual mode has been used, it returns "v",
9522 "V", or "<CTRL-V>" (a single CTRL-V character) for
9523 character-wise, line-wise, or block-wise Visual mode
9524 respectively.
9525 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009526 :exe "normal " .. visualmode()
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009527< This enters the same Visual mode as before. It is also useful
9528 in scripts if you wish to act differently depending on the
9529 Visual mode that was used.
9530 If Visual mode is active, use |mode()| to get the Visual mode
9531 (e.g., in a |:vmap|).
9532 If {expr} is supplied and it evaluates to a non-zero Number or
9533 a non-empty String, then the Visual mode will be cleared and
9534 the old value is returned. See |non-zero-arg|.
9535
9536wildmenumode() *wildmenumode()*
9537 Returns |TRUE| when the wildmenu is active and |FALSE|
9538 otherwise. See 'wildmenu' and 'wildmode'.
9539 This can be used in mappings to handle the 'wildcharm' option
9540 gracefully. (Makes only sense with |mapmode-c| mappings).
9541
9542 For example to make <c-j> work like <down> in wildmode, use: >
9543 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
9544<
9545 (Note, this needs the 'wildcharm' option set appropriately).
9546
9547win_execute({id}, {command} [, {silent}]) *win_execute()*
9548 Like `execute()` but in the context of window {id}.
9549 The window will temporarily be made the current window,
9550 without triggering autocommands or changing directory. When
9551 executing {command} autocommands will be triggered, this may
9552 have unexpected side effects. Use |:noautocmd| if needed.
9553 Example: >
9554 call win_execute(winid, 'set syntax=python')
9555< Doing the same with `setwinvar()` would not trigger
9556 autocommands and not actually show syntax highlighting.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009557 *E994*
9558 Not all commands are allowed in popup windows.
9559 When window {id} does not exist then no error is given and
9560 an empty string is returned.
9561
9562 Can also be used as a |method|, the base is passed as the
9563 second argument: >
9564 GetCommand()->win_execute(winid)
9565
9566win_findbuf({bufnr}) *win_findbuf()*
9567 Returns a |List| with |window-ID|s for windows that contain
9568 buffer {bufnr}. When there is none the list is empty.
9569
9570 Can also be used as a |method|: >
9571 GetBufnr()->win_findbuf()
9572
9573win_getid([{win} [, {tab}]]) *win_getid()*
9574 Get the |window-ID| for the specified window.
9575 When {win} is missing use the current window.
9576 With {win} this is the window number. The top window has
9577 number 1.
9578 Without {tab} use the current tab, otherwise the tab with
9579 number {tab}. The first tab has number one.
9580 Return zero if the window cannot be found.
9581
9582 Can also be used as a |method|: >
9583 GetWinnr()->win_getid()
9584
9585
9586win_gettype([{nr}]) *win_gettype()*
9587 Return the type of the window:
9588 "autocmd" autocommand window. Temporary window
9589 used to execute autocommands.
9590 "command" command-line window |cmdwin|
9591 (empty) normal window
9592 "loclist" |location-list-window|
9593 "popup" popup window |popup|
9594 "preview" preview window |preview-window|
9595 "quickfix" |quickfix-window|
9596 "unknown" window {nr} not found
9597
9598 When {nr} is omitted return the type of the current window.
9599 When {nr} is given return the type of this window by number or
9600 |window-ID|.
9601
9602 Also see the 'buftype' option. When running a terminal in a
9603 popup window then 'buftype' is "terminal" and win_gettype()
9604 returns "popup".
9605
9606 Can also be used as a |method|: >
9607 GetWinid()->win_gettype()
9608<
9609win_gotoid({expr}) *win_gotoid()*
9610 Go to window with ID {expr}. This may also change the current
9611 tabpage.
9612 Return TRUE if successful, FALSE if the window cannot be found.
9613
9614 Can also be used as a |method|: >
9615 GetWinid()->win_gotoid()
9616
9617win_id2tabwin({expr}) *win_id2tabwin()*
9618 Return a list with the tab number and window number of window
9619 with ID {expr}: [tabnr, winnr].
9620 Return [0, 0] if the window cannot be found.
9621
9622 Can also be used as a |method|: >
9623 GetWinid()->win_id2tabwin()
9624
9625win_id2win({expr}) *win_id2win()*
9626 Return the window number of window with ID {expr}.
9627 Return 0 if the window cannot be found in the current tabpage.
9628
9629 Can also be used as a |method|: >
9630 GetWinid()->win_id2win()
9631
Daniel Steinbergee630312022-01-10 13:36:34 +00009632win_move_separator({nr}, {offset}) *win_move_separator()*
9633 Move window {nr}'s vertical separator (i.e., the right border)
9634 by {offset} columns, as if being dragged by the mouse. {nr}
9635 can be a window number or |window-ID|. A positive {offset}
9636 moves right and a negative {offset} moves left. Moving a
9637 window's vertical separator will change the width of the
9638 window and the width of other windows adjacent to the vertical
9639 separator. The magnitude of movement may be smaller than
9640 specified (e.g., as a consequence of maintaining
9641 'winminwidth'). Returns TRUE if the window can be found and
9642 FALSE otherwise.
9643
9644 Can also be used as a |method|: >
9645 GetWinnr()->win_move_separator(offset)
9646
9647win_move_statusline({nr}, {offset}) *win_move_statusline()*
9648 Move window {nr}'s status line (i.e., the bottom border) by
9649 {offset} rows, as if being dragged by the mouse. {nr} can be a
9650 window number or |window-ID|. A positive {offset} moves down
9651 and a negative {offset} moves up. Moving a window's status
9652 line will change the height of the window and the height of
9653 other windows adjacent to the status line. The magnitude of
9654 movement may be smaller than specified (e.g., as a consequence
9655 of maintaining 'winminheight'). Returns TRUE if the window can
9656 be found and FALSE otherwise.
9657
9658 Can also be used as a |method|: >
9659 GetWinnr()->win_move_statusline(offset)
9660
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009661win_screenpos({nr}) *win_screenpos()*
9662 Return the screen position of window {nr} as a list with two
9663 numbers: [row, col]. The first window always has position
9664 [1, 1], unless there is a tabline, then it is [2, 1].
9665 {nr} can be the window number or the |window-ID|. Use zero
9666 for the current window.
9667 Returns [0, 0] if the window cannot be found in the current
9668 tabpage.
9669
9670 Can also be used as a |method|: >
9671 GetWinid()->win_screenpos()
9672<
9673win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
9674 Move the window {nr} to a new split of the window {target}.
9675 This is similar to moving to {target}, creating a new window
9676 using |:split| but having the same contents as window {nr}, and
9677 then closing {nr}.
9678
9679 Both {nr} and {target} can be window numbers or |window-ID|s.
9680 Both must be in the current tab page.
9681
9682 Returns zero for success, non-zero for failure.
9683
9684 {options} is a |Dictionary| with the following optional entries:
9685 "vertical" When TRUE, the split is created vertically,
9686 like with |:vsplit|.
9687 "rightbelow" When TRUE, the split is made below or to the
9688 right (if vertical). When FALSE, it is done
9689 above or to the left (if vertical). When not
9690 present, the values of 'splitbelow' and
9691 'splitright' are used.
9692
9693 Can also be used as a |method|: >
9694 GetWinid()->win_splitmove(target)
9695<
9696
9697 *winbufnr()*
9698winbufnr({nr}) The result is a Number, which is the number of the buffer
9699 associated with window {nr}. {nr} can be the window number or
9700 the |window-ID|.
9701 When {nr} is zero, the number of the buffer in the current
9702 window is returned.
9703 When window {nr} doesn't exist, -1 is returned.
9704 Example: >
9705 :echo "The file in the current window is " . bufname(winbufnr(0))
9706<
9707 Can also be used as a |method|: >
9708 FindWindow()->winbufnr()->bufname()
9709<
9710 *wincol()*
9711wincol() The result is a Number, which is the virtual column of the
9712 cursor in the window. This is counting screen cells from the
9713 left side of the window. The leftmost column is one.
9714
9715 *windowsversion()*
9716windowsversion()
9717 The result is a String. For MS-Windows it indicates the OS
9718 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
9719 Windows XP is "5.1". For non-MS-Windows systems the result is
9720 an empty string.
9721
9722winheight({nr}) *winheight()*
9723 The result is a Number, which is the height of window {nr}.
9724 {nr} can be the window number or the |window-ID|.
9725 When {nr} is zero, the height of the current window is
9726 returned. When window {nr} doesn't exist, -1 is returned.
9727 An existing window always has a height of zero or more.
9728 This excludes any window toolbar line.
9729 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009730 :echo "The current window has " .. winheight(0) .. " lines."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009731
9732< Can also be used as a |method|: >
9733 GetWinid()->winheight()
9734<
9735winlayout([{tabnr}]) *winlayout()*
9736 The result is a nested List containing the layout of windows
9737 in a tabpage.
9738
9739 Without {tabnr} use the current tabpage, otherwise the tabpage
9740 with number {tabnr}. If the tabpage {tabnr} is not found,
9741 returns an empty list.
9742
9743 For a leaf window, it returns:
9744 ['leaf', {winid}]
9745 For horizontally split windows, which form a column, it
9746 returns:
9747 ['col', [{nested list of windows}]]
9748 For vertically split windows, which form a row, it returns:
9749 ['row', [{nested list of windows}]]
9750
9751 Example: >
9752 " Only one window in the tab page
9753 :echo winlayout()
9754 ['leaf', 1000]
9755 " Two horizontally split windows
9756 :echo winlayout()
9757 ['col', [['leaf', 1000], ['leaf', 1001]]]
9758 " The second tab page, with three horizontally split
9759 " windows, with two vertically split windows in the
9760 " middle window
9761 :echo winlayout(2)
9762 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
9763 ['leaf', 1001]]], ['leaf', 1000]]]
9764<
9765 Can also be used as a |method|: >
9766 GetTabnr()->winlayout()
9767<
9768 *winline()*
9769winline() The result is a Number, which is the screen line of the cursor
9770 in the window. This is counting screen lines from the top of
9771 the window. The first line is one.
9772 If the cursor was moved the view on the file will be updated
9773 first, this may cause a scroll.
9774
9775 *winnr()*
9776winnr([{arg}]) The result is a Number, which is the number of the current
9777 window. The top window has number 1.
9778 Returns zero for a popup window.
9779
9780 The optional argument {arg} supports the following values:
9781 $ the number of the last window (the window
9782 count).
9783 # the number of the last accessed window (where
9784 |CTRL-W_p| goes to). If there is no previous
9785 window or it is in another tab page 0 is
9786 returned.
9787 {N}j the number of the Nth window below the
9788 current window (where |CTRL-W_j| goes to).
9789 {N}k the number of the Nth window above the current
9790 window (where |CTRL-W_k| goes to).
9791 {N}h the number of the Nth window left of the
9792 current window (where |CTRL-W_h| goes to).
9793 {N}l the number of the Nth window right of the
9794 current window (where |CTRL-W_l| goes to).
9795 The number can be used with |CTRL-W_w| and ":wincmd w"
9796 |:wincmd|.
9797 Also see |tabpagewinnr()| and |win_getid()|.
9798 Examples: >
9799 let window_count = winnr('$')
9800 let prev_window = winnr('#')
9801 let wnum = winnr('3k')
9802
9803< Can also be used as a |method|: >
9804 GetWinval()->winnr()
9805<
9806 *winrestcmd()*
9807winrestcmd() Returns a sequence of |:resize| commands that should restore
9808 the current window sizes. Only works properly when no windows
9809 are opened or closed and the current window and tab page is
9810 unchanged.
9811 Example: >
9812 :let cmd = winrestcmd()
9813 :call MessWithWindowSizes()
9814 :exe cmd
9815<
9816 *winrestview()*
9817winrestview({dict})
9818 Uses the |Dictionary| returned by |winsaveview()| to restore
9819 the view of the current window.
9820 Note: The {dict} does not have to contain all values, that are
9821 returned by |winsaveview()|. If values are missing, those
9822 settings won't be restored. So you can use: >
9823 :call winrestview({'curswant': 4})
9824<
9825 This will only set the curswant value (the column the cursor
9826 wants to move on vertical movements) of the cursor to column 5
9827 (yes, that is 5), while all other settings will remain the
9828 same. This is useful, if you set the cursor position manually.
9829
9830 If you have changed the values the result is unpredictable.
9831 If the window size changed the result won't be the same.
9832
9833 Can also be used as a |method|: >
9834 GetView()->winrestview()
9835<
9836 *winsaveview()*
9837winsaveview() Returns a |Dictionary| that contains information to restore
9838 the view of the current window. Use |winrestview()| to
9839 restore the view.
9840 This is useful if you have a mapping that jumps around in the
9841 buffer and you want to go back to the original view.
9842 This does not save fold information. Use the 'foldenable'
9843 option to temporarily switch off folding, so that folds are
9844 not opened when moving around. This may have side effects.
9845 The return value includes:
9846 lnum cursor line number
9847 col cursor column (Note: the first column
naohiro ono56200ee2022-01-01 14:59:44 +00009848 zero, as opposed to what |getcurpos()|
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009849 returns)
9850 coladd cursor column offset for 'virtualedit'
naohiro ono56200ee2022-01-01 14:59:44 +00009851 curswant column for vertical movement (Note:
9852 the first column is zero, as opposed
9853 to what |getcurpos()| returns). After
9854 |$| command it will be a very large
9855 number equal to |v:maxcol|.
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009856 topline first line in the window
9857 topfill filler lines, only in diff mode
9858 leftcol first column displayed; only used when
9859 'wrap' is off
9860 skipcol columns skipped
9861 Note that no option values are saved.
9862
9863
9864winwidth({nr}) *winwidth()*
9865 The result is a Number, which is the width of window {nr}.
9866 {nr} can be the window number or the |window-ID|.
9867 When {nr} is zero, the width of the current window is
9868 returned. When window {nr} doesn't exist, -1 is returned.
9869 An existing window always has a width of zero or more.
9870 Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00009871 :echo "The current window has " .. winwidth(0) .. " columns."
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00009872 :if winwidth(0) <= 50
9873 : 50 wincmd |
9874 :endif
9875< For getting the terminal or screen size, see the 'columns'
9876 option.
9877
9878 Can also be used as a |method|: >
9879 GetWinid()->winwidth()
9880
9881
9882wordcount() *wordcount()*
9883 The result is a dictionary of byte/chars/word statistics for
9884 the current buffer. This is the same info as provided by
9885 |g_CTRL-G|
9886 The return value includes:
9887 bytes Number of bytes in the buffer
9888 chars Number of chars in the buffer
9889 words Number of words in the buffer
9890 cursor_bytes Number of bytes before cursor position
9891 (not in Visual mode)
9892 cursor_chars Number of chars before cursor position
9893 (not in Visual mode)
9894 cursor_words Number of words before cursor position
9895 (not in Visual mode)
9896 visual_bytes Number of bytes visually selected
9897 (only in Visual mode)
9898 visual_chars Number of chars visually selected
9899 (only in Visual mode)
9900 visual_words Number of words visually selected
9901 (only in Visual mode)
9902
9903
9904 *writefile()*
9905writefile({object}, {fname} [, {flags}])
9906 When {object} is a |List| write it to file {fname}. Each list
9907 item is separated with a NL. Each list item must be a String
9908 or Number.
9909 When {flags} contains "b" then binary mode is used: There will
9910 not be a NL after the last list item. An empty item at the
9911 end does cause the last line in the file to end in a NL.
9912
9913 When {object} is a |Blob| write the bytes to file {fname}
9914 unmodified.
9915
9916 When {flags} contains "a" then append mode is used, lines are
9917 appended to the file: >
9918 :call writefile(["foo"], "event.log", "a")
9919 :call writefile(["bar"], "event.log", "a")
9920<
9921 When {flags} contains "s" then fsync() is called after writing
9922 the file. This flushes the file to disk, if possible. This
9923 takes more time but avoids losing the file if the system
9924 crashes.
9925 When {flags} does not contain "S" or "s" then fsync() is
9926 called if the 'fsync' option is set.
9927 When {flags} contains "S" then fsync() is not called, even
9928 when 'fsync' is set.
9929
9930 All NL characters are replaced with a NUL character.
9931 Inserting CR characters needs to be done before passing {list}
9932 to writefile().
9933 An existing file is overwritten, if possible.
9934 When the write fails -1 is returned, otherwise 0. There is an
9935 error message if the file can't be created or when writing
9936 fails.
9937 Also see |readfile()|.
9938 To copy a file byte for byte: >
9939 :let fl = readfile("foo", "b")
9940 :call writefile(fl, "foocopy", "b")
9941
9942< Can also be used as a |method|: >
9943 GetText()->writefile("thefile")
9944
9945
9946xor({expr}, {expr}) *xor()*
9947 Bitwise XOR on the two arguments. The arguments are converted
9948 to a number. A List, Dict or Float argument causes an error.
9949 Example: >
9950 :let bits = xor(bits, 0x80)
9951<
9952 Can also be used as a |method|: >
9953 :let bits = bits->xor(0x80)
9954<
9955
9956==============================================================================
99573. Feature list *feature-list*
9958
9959There are three types of features:
99601. Features that are only supported when they have been enabled when Vim
9961 was compiled |+feature-list|. Example: >
9962 :if has("cindent")
9963< *gui_running*
99642. Features that are only supported when certain conditions have been met.
9965 Example: >
9966 :if has("gui_running")
9967< *has-patch*
99683. Beyond a certain version or at a certain version and including a specific
9969 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
9970 later, or it is version 7.4 and patch 248 was included. Example: >
9971 :if has("patch-7.4.248")
9972< Note that it's possible for patch 248 to be omitted even though 249 is
9973 included. Only happens when cherry-picking patches.
9974 Note that this form only works for patch 7.4.237 and later, before that
9975 you need to check for the patch and the v:version. Example (checking
9976 version 6.2.148 or later): >
9977 :if v:version > 602 || (v:version == 602 && has("patch148"))
9978
9979Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
9980use: `if exists('+shellslash')`
9981
9982
9983acl Compiled with |ACL| support.
9984all_builtin_terms Compiled with all builtin terminals enabled.
9985amiga Amiga version of Vim.
9986arabic Compiled with Arabic support |Arabic|.
9987arp Compiled with ARP support (Amiga).
9988autocmd Compiled with autocommand support. (always true)
9989autochdir Compiled with support for 'autochdir'
9990autoservername Automatically enable |clientserver|
9991balloon_eval Compiled with |balloon-eval| support.
9992balloon_multiline GUI supports multiline balloons.
9993beos BeOS version of Vim.
9994browse Compiled with |:browse| support, and browse() will
9995 work.
9996browsefilter Compiled with support for |browsefilter|.
9997bsd Compiled on an OS in the BSD family (excluding macOS).
9998builtin_terms Compiled with some builtin terminals.
9999byte_offset Compiled with support for 'o' in 'statusline'
10000channel Compiled with support for |channel| and |job|
10001cindent Compiled with 'cindent' support.
10002clientserver Compiled with remote invocation support |clientserver|.
10003clipboard Compiled with 'clipboard' support.
10004clipboard_working Compiled with 'clipboard' support and it can be used.
10005cmdline_compl Compiled with |cmdline-completion| support.
10006cmdline_hist Compiled with |cmdline-history| support.
10007cmdline_info Compiled with 'showcmd' and 'ruler' support.
10008comments Compiled with |'comments'| support.
10009compatible Compiled to be very Vi compatible.
10010conpty Platform where |ConPTY| can be used.
10011cryptv Compiled with encryption support |encryption|.
10012cscope Compiled with |cscope| support.
10013cursorbind Compiled with |'cursorbind'| (always true)
10014debug Compiled with "DEBUG" defined.
10015dialog_con Compiled with console dialog support.
10016dialog_gui Compiled with GUI dialog support.
10017diff Compiled with |vimdiff| and 'diff' support.
10018digraphs Compiled with support for digraphs.
10019directx Compiled with support for DirectX and 'renderoptions'.
10020dnd Compiled with support for the "~ register |quote_~|.
10021drop_file Compiled with |drop_file| support.
10022ebcdic Compiled on a machine with ebcdic character set.
10023emacs_tags Compiled with support for Emacs tags.
10024eval Compiled with expression evaluation support. Always
10025 true, of course!
10026ex_extra |+ex_extra| (always true)
10027extra_search Compiled with support for |'incsearch'| and
10028 |'hlsearch'|
10029farsi Support for Farsi was removed |farsi|.
10030file_in_path Compiled with support for |gf| and |<cfile>|
10031filterpipe When 'shelltemp' is off pipes are used for shell
10032 read/write/filter commands
10033find_in_path Compiled with support for include file searches
10034 |+find_in_path|.
10035float Compiled with support for |Float|.
10036fname_case Case in file names matters (for Amiga and MS-Windows
10037 this is not present).
10038folding Compiled with |folding| support.
10039footer Compiled with GUI footer support. |gui-footer|
10040fork Compiled to use fork()/exec() instead of system().
10041gettext Compiled with message translation |multi-lang|
10042gui Compiled with GUI enabled.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010010043gui_athena Compiled with Athena GUI (always false).
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010044gui_gnome Compiled with Gnome support (gui_gtk is also defined).
10045gui_gtk Compiled with GTK+ GUI (any version).
10046gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
10047gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
10048gui_haiku Compiled with Haiku GUI.
10049gui_mac Compiled with Macintosh GUI.
10050gui_motif Compiled with Motif GUI.
10051gui_photon Compiled with Photon GUI.
10052gui_running Vim is running in the GUI, or it will start soon.
10053gui_win32 Compiled with MS-Windows Win32 GUI.
10054gui_win32s idem, and Win32s system being used (Windows 3.1)
10055haiku Haiku version of Vim.
10056hangul_input Compiled with Hangul input support. |hangul|
10057hpux HP-UX version of Vim.
10058iconv Can use iconv() for conversion.
10059insert_expand Compiled with support for CTRL-X expansion commands in
10060 Insert mode. (always true)
10061job Compiled with support for |channel| and |job|
10062ipv6 Compiled with support for IPv6 networking in |channel|.
10063jumplist Compiled with |jumplist| support.
10064keymap Compiled with 'keymap' support.
10065lambda Compiled with |lambda| support.
10066langmap Compiled with 'langmap' support.
10067libcall Compiled with |libcall()| support.
10068linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10069 'breakindent' support.
10070linux Linux version of Vim.
10071lispindent Compiled with support for lisp indenting.
10072listcmds Compiled with commands for the buffer list |:files|
10073 and the argument list |arglist|.
10074localmap Compiled with local mappings and abbr. |:map-local|
10075lua Compiled with Lua interface |Lua|.
10076mac Any Macintosh version of Vim cf. osx
10077macunix Synonym for osxdarwin
10078menu Compiled with support for |:menu|.
10079mksession Compiled with support for |:mksession|.
10080modify_fname Compiled with file name modifiers. |filename-modifiers|
10081 (always true)
10082mouse Compiled with support for mouse.
10083mouse_dec Compiled with support for Dec terminal mouse.
10084mouse_gpm Compiled with support for gpm (Linux console mouse)
10085mouse_gpm_enabled GPM mouse is working
10086mouse_netterm Compiled with support for netterm mouse.
10087mouse_pterm Compiled with support for qnx pterm mouse.
10088mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
10089mouse_sgr Compiled with support for sgr mouse.
10090mouse_urxvt Compiled with support for urxvt mouse.
10091mouse_xterm Compiled with support for xterm mouse.
10092mouseshape Compiled with support for 'mouseshape'.
10093multi_byte Compiled with support for 'encoding' (always true)
10094multi_byte_encoding 'encoding' is set to a multibyte encoding.
10095multi_byte_ime Compiled with support for IME input method.
10096multi_lang Compiled with support for multiple languages.
10097mzscheme Compiled with MzScheme interface |mzscheme|.
10098nanotime Compiled with sub-second time stamp checks.
10099netbeans_enabled Compiled with support for |netbeans| and connected.
10100netbeans_intg Compiled with support for |netbeans|.
10101num64 Compiled with 64-bit |Number| support.
10102ole Compiled with OLE automation support for Win32.
10103osx Compiled for macOS cf. mac
10104osxdarwin Compiled for macOS, with |mac-darwin-feature|
10105packages Compiled with |packages| support.
10106path_extra Compiled with up/downwards search in 'path' and 'tags'
10107perl Compiled with Perl interface.
10108persistent_undo Compiled with support for persistent undo history.
10109postscript Compiled with PostScript file printing.
10110printer Compiled with |:hardcopy| support.
10111profile Compiled with |:profile| support.
10112python Python 2.x interface available. |has-python|
10113python_compiled Compiled with Python 2.x interface. |has-python|
10114python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10115python3 Python 3.x interface available. |has-python|
10116python3_compiled Compiled with Python 3.x interface. |has-python|
10117python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
10118pythonx Python 2.x and/or 3.x interface available. |python_x|
10119qnx QNX version of Vim.
10120quickfix Compiled with |quickfix| support.
10121reltime Compiled with |reltime()| support.
10122rightleft Compiled with 'rightleft' support.
10123ruby Compiled with Ruby interface |ruby|.
10124scrollbind Compiled with 'scrollbind' support. (always true)
10125showcmd Compiled with 'showcmd' support.
10126signs Compiled with |:sign| support.
10127smartindent Compiled with 'smartindent' support.
10128sodium Compiled with libsodium for better crypt support
10129sound Compiled with sound support, e.g. `sound_playevent()`
10130spell Compiled with spell checking support |spell|.
10131startuptime Compiled with |--startuptime| support.
10132statusline Compiled with support for 'statusline', 'rulerformat'
10133 and special formats of 'titlestring' and 'iconstring'.
10134sun SunOS version of Vim.
10135sun_workshop Support for Sun |workshop| has been removed.
10136syntax Compiled with syntax highlighting support |syntax|.
10137syntax_items There are active syntax highlighting items for the
10138 current buffer.
10139system Compiled to use system() instead of fork()/exec().
10140tag_binary Compiled with binary searching in tags files
10141 |tag-binary-search|.
10142tag_old_static Support for old static tags was removed, see
10143 |tag-old-static|.
10144tcl Compiled with Tcl interface.
10145termguicolors Compiled with true color in terminal support.
10146terminal Compiled with |terminal| support.
10147terminfo Compiled with terminfo instead of termcap.
10148termresponse Compiled with support for |t_RV| and |v:termresponse|.
10149textobjects Compiled with support for |text-objects|.
10150textprop Compiled with support for |text-properties|.
10151tgetent Compiled with tgetent support, able to use a termcap
10152 or terminfo file.
10153timers Compiled with |timer_start()| support.
10154title Compiled with window title support |'title'|.
10155toolbar Compiled with support for |gui-toolbar|.
10156ttyin input is a terminal (tty)
10157ttyout output is a terminal (tty)
10158unix Unix version of Vim. *+unix*
10159unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
10160user_commands User-defined commands. (always true)
10161vartabs Compiled with variable tabstop support |'vartabstop'|.
10162vcon Win32: Virtual console support is working, can use
10163 'termguicolors'. Also see |+vtp|.
10164vertsplit Compiled with vertically split windows |:vsplit|.
10165 (always true)
10166vim_starting True while initial source'ing takes place. |startup|
10167 *vim_starting*
Bram Moolenaara6feb162022-01-02 12:06:33 +000010168vim9script Compiled with |Vim9| script support
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000010169viminfo Compiled with viminfo support.
10170vimscript-1 Compiled Vim script version 1 support
10171vimscript-2 Compiled Vim script version 2 support
10172vimscript-3 Compiled Vim script version 3 support
10173virtualedit Compiled with 'virtualedit' option. (always true)
10174visual Compiled with Visual mode. (always true)
10175visualextra Compiled with extra Visual mode commands. (always
10176 true) |blockwise-operators|.
10177vms VMS version of Vim.
10178vreplace Compiled with |gR| and |gr| commands. (always true)
10179vtp Compiled for vcon support |+vtp| (check vcon to find
10180 out if it works in the current console).
10181wildignore Compiled with 'wildignore' option.
10182wildmenu Compiled with 'wildmenu' option.
10183win16 old version for MS-Windows 3.1 (always false)
10184win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10185 64 bits)
10186win32unix Win32 version of Vim, using Unix files (Cygwin)
10187win64 Win64 version of Vim (MS-Windows 64 bit).
10188win95 Win32 version for MS-Windows 95/98/ME (always false)
10189winaltkeys Compiled with 'winaltkeys' option.
10190windows Compiled with support for more than one window.
10191 (always true)
10192writebackup Compiled with 'writebackup' default on.
10193xfontset Compiled with X fontset support |xfontset|.
10194xim Compiled with X input method support |xim|.
10195xpm Compiled with pixmap support.
10196xpm_w32 Compiled with pixmap support for Win32. (Only for
10197 backward compatibility. Use "xpm" instead.)
10198xsmp Compiled with X session management support.
10199xsmp_interact Compiled with interactive X session management support.
10200xterm_clipboard Compiled with support for xterm clipboard.
10201xterm_save Compiled with support for saving and restoring the
10202 xterm screen.
10203x11 Compiled with X11 support.
10204
10205
10206==============================================================================
102074. Matching a pattern in a String *string-match*
10208
10209This is common between several functions. A regexp pattern as explained at
10210|pattern| is normally used to find a match in the buffer lines. When a
10211pattern is used to find a match in a String, almost everything works in the
10212same way. The difference is that a String is handled like it is one line.
10213When it contains a "\n" character, this is not seen as a line break for the
10214pattern. It can be matched with a "\n" in the pattern, or with ".". Example:
10215>
10216 :let a = "aaaa\nxxxx"
10217 :echo matchstr(a, "..\n..")
10218 aa
10219 xx
10220 :echo matchstr(a, "a.x")
10221 a
10222 x
10223
10224Don't forget that "^" will only match at the first character of the String and
10225"$" at the last character of the string. They don't match after or before a
10226"\n".
10227
10228 vim:tw=78:ts=8:noet:ft=help:norl: