blob: f50c8c5b879f545bafe67af8a635981e7addd800 [file] [log] [blame]
Bram Moolenaar96f45c02019-10-26 19:53:45 +02001*eval.txt* For Vim version 8.1. Last change: 2019 Oct 26
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
Bram Moolenaar446cb832008-06-24 21:56:24 +00004 VIM REFERENCE MANUAL by Bram Moolenaar
Bram Moolenaar071d4272004-06-13 20:20:40 +00005
6
7Expression evaluation *expression* *expr* *E15* *eval*
8
9Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
10
11Note: Expression evaluation can be disabled at compile time. If this has been
Bram Moolenaar58b85342016-08-14 19:54:54 +020012done, the features in this document are not available. See |+eval| and
Bram Moolenaard8b02732005-01-14 21:48:43 +000013|no-eval-feature|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000014
Bram Moolenaar13065c42005-01-08 16:08:21 +0000151. Variables |variables|
16 1.1 Variable types
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000017 1.2 Function references |Funcref|
Bram Moolenaar7c626922005-02-07 22:01:03 +000018 1.3 Lists |Lists|
Bram Moolenaard8b02732005-01-14 21:48:43 +000019 1.4 Dictionaries |Dictionaries|
Bram Moolenaard8968242019-01-15 22:51:57 +010020 1.5 Blobs |Blobs|
21 1.6 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000222. Expression syntax |expression-syntax|
233. Internal variable |internal-variables|
244. Builtin Functions |functions|
255. Defining functions |user-functions|
266. Curly braces names |curly-braces-names|
277. Commands |expression-commands|
288. Exception handling |exception-handling|
299. Examples |eval-examples|
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003010. Vim script version |vimscript-version|
3111. No +eval feature |no-eval-feature|
3212. The sandbox |eval-sandbox|
3313. Textlock |textlock|
Bram Moolenaared997ad2019-07-21 16:42:00 +020034
35Testing support is documented in |testing.txt|.
36Profiling is documented at |profiling|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000037
Bram Moolenaar071d4272004-06-13 20:20:40 +000038==============================================================================
391. Variables *variables*
40
Bram Moolenaar13065c42005-01-08 16:08:21 +0000411.1 Variable types ~
Bram Moolenaarbf821bc2019-01-23 21:15:02 +010042 *E712* *E896* *E897* *E899*
Bram Moolenaar06fe74a2019-08-31 16:20:32 +020043There are ten types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000044
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020045Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020046 64-bit Numbers are available only when compiled with the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020047 |+num64| feature.
Bram Moolenaar7571d552016-08-18 22:54:46 +020048 Examples: -123 0x10 0177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000049
Bram Moolenaar446cb832008-06-24 21:56:24 +000050Float A floating point number. |floating-point-format| *Float*
51 {only when compiled with the |+float| feature}
52 Examples: 123.456 1.15e-6 -1.1e3
53
Bram Moolenaar06481422016-04-30 15:13:38 +020054 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000055String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000056 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000057
Bram Moolenaard8968242019-01-15 22:51:57 +010058List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000059 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000061Dictionary An associative, unordered array: Each entry has a key and a
62 value. |Dictionary|
Bram Moolenaard5abb4c2019-07-13 22:46:10 +020063 Examples:
64 {'blue': "#0000ff", 'red': "#ff0000"}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +020065 #{blue: "#0000ff", red: "#ff0000"}
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000066
Bram Moolenaar835dc632016-02-07 14:27:38 +010067Funcref A reference to a function |Funcref|.
68 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020069 It can be bound to a dictionary and arguments, it then works
70 like a Partial.
71 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010072
Bram Moolenaar02e83b42016-02-21 20:10:26 +010073Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010074
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020075Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010076
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020077Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010078
Bram Moolenaard8968242019-01-15 22:51:57 +010079Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
80 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010081 Example: 0zFF00ED015DAF
82 0z is an empty Blob.
83
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000084The Number and String types are converted automatically, depending on how they
85are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000086
87Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020088the Number. Examples:
89 Number 123 --> String "123" ~
90 Number 0 --> String "0" ~
91 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020092 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010093Conversion from a String to a Number is done by converting the first digits to
94a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
Bram Moolenaar60a8de22019-09-15 14:33:22 +020095recognized (NOTE: when using |scriptversion-4| octal is not recognized). If
96the String doesn't start with digits, the result is zero.
Bram Moolenaarfa735342016-01-03 22:14:44 +010097Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020098 String "456" --> Number 456 ~
99 String "6bar" --> Number 6 ~
100 String "foo" --> Number 0 ~
101 String "0xf1" --> Number 241 ~
102 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +0100103 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200104 String "-8" --> Number -8 ~
105 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000106
107To force conversion from String to Number, add zero to it: >
108 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000109< 64 ~
110
111To avoid a leading zero to cause octal conversion, or for using a different
112base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000113
Bram Moolenaard09091d2019-01-17 16:07:22 +0100114 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200116You can also use |v:false| and |v:true|. When TRUE is returned from a
117function it is the Number one, FALSE is the number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000118
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200119Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000120 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200121 :" NOT executed
122"foo" is converted to 0, which means FALSE. If the string starts with a
123non-zero number it means TRUE: >
124 :if "8foo"
125 :" executed
126To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200127 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100128<
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200129 *non-zero-arg*
130Function arguments often behave slightly different from |TRUE|: If the
131argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200132non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100133Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
134A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200135
Bram Moolenaar38a55632016-02-15 22:07:32 +0100136 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +0100137 *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100138|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
139automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000140
Bram Moolenaar446cb832008-06-24 21:56:24 +0000141 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200142When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000143there is no automatic conversion of Float. You can use str2float() for String
144to Float, printf() for Float to String and float2nr() for Float to Number.
145
Bram Moolenaar38a55632016-02-15 22:07:32 +0100146 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100147When expecting a Float a Number can also be used, but nothing else.
148
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100149 *no-type-checking*
150You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000151
Bram Moolenaar13065c42005-01-08 16:08:21 +0000152
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001531.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000154 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200155A Funcref variable is obtained with the |function()| function, the |funcref()|
156function or created with the lambda expression |expr-lambda|. It can be used
157in an expression in the place of a function name, before the parenthesis
158around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000159
160 :let Fn = function("MyFunc")
161 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000162< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000163A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200164can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000165cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000166
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000167A special case is defining a function and directly assigning its Funcref to a
168Dictionary entry. Example: >
169 :function dict.init() dict
170 : let self.val = 0
171 :endfunction
172
173The key of the Dictionary can start with a lower case letter. The actual
174function name is not used here. Also see |numbered-function|.
175
176A Funcref can also be used with the |:call| command: >
177 :call Fn()
178 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000179
180The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000181 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000182
183You can use |call()| to invoke a Funcref and use a list variable for the
184arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000185 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200186<
187 *Partial*
188A Funcref optionally binds a Dictionary and/or arguments. This is also called
189a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200190function() or funcref(). When calling the function the Dictionary and/or
191arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200192
193 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100194 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200195
196This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100197 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200198
199This is very useful when passing a function around, e.g. in the arguments of
200|ch_open()|.
201
202Note that binding a function to a Dictionary also happens when the function is
203a member of the Dictionary: >
204
205 let myDict.myFunction = MyFunction
206 call myDict.myFunction()
207
208Here MyFunction() will get myDict passed as "self". This happens when the
209"myFunction" member is accessed. When making assigning "myFunction" to
210otherDict and calling it, it will be bound to otherDict: >
211
212 let otherDict.myFunction = myDict.myFunction
213 call otherDict.myFunction()
214
215Now "self" will be "otherDict". But when the dictionary was bound explicitly
216this won't happen: >
217
218 let myDict.myFunction = function(MyFunction, myDict)
219 let otherDict.myFunction = myDict.myFunction
220 call otherDict.myFunction()
221
Bram Moolenaard823fa92016-08-12 16:29:27 +0200222Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000223
224
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002251.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200226 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000227A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200228can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000229position in the sequence.
230
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231
232List creation ~
233 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000234A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000235Examples: >
236 :let mylist = [1, two, 3, "four"]
237 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000238
Bram Moolenaar58b85342016-08-14 19:54:54 +0200239An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000240List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000242
243An extra comma after the last item is ignored.
244
Bram Moolenaar13065c42005-01-08 16:08:21 +0000245
246List index ~
247 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000248An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249after the List. Indexes are zero-based, thus the first item has index zero. >
250 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000251 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000252
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000253When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000254 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000255<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000256A negative index is counted from the end. Index -1 refers to the last item in
257the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000258 :let last = mylist[-1] " get the last item: "four"
259
Bram Moolenaar13065c42005-01-08 16:08:21 +0000260To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000261is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000262 :echo get(mylist, idx)
263 :echo get(mylist, idx, "NONE")
264
265
266List concatenation ~
267
268Two lists can be concatenated with the "+" operator: >
269 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000270 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000271
272To prepend or append an item turn the item into a list by putting [] around
273it. To change a list in-place see |list-modification| below.
274
275
276Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200277 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000278A part of the List can be obtained by specifying the first and last index,
279separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000280 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000281
282Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000283similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000284 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
285 :let shortlist = mylist[2:2] " List with one item: [3]
286 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000287
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000288If the first index is beyond the last item of the List or the second item is
289before the first item, the result is an empty list. There is no error
290message.
291
292If the second index is equal to or greater than the length of the list the
293length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000294 :let mylist = [0, 1, 2, 3]
295 :echo mylist[2:8] " result: [2, 3]
296
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000297NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200298using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000299mylist[s : e].
300
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000301
Bram Moolenaar13065c42005-01-08 16:08:21 +0000302List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000303 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000304When variable "aa" is a list and you assign it to another variable "bb", both
305variables refer to the same list. Thus changing the list "aa" will also
306change "bb": >
307 :let aa = [1, 2, 3]
308 :let bb = aa
309 :call add(aa, 4)
310 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000311< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000312
313Making a copy of a list is done with the |copy()| function. Using [:] also
314works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000315a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000316 :let aa = [[1, 'a'], 2, 3]
317 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000318 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000319 :let aa[0][1] = 'aaa'
320 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000321< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000322 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000324
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000325To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000326copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000327
328The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000329List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000330the same value. >
331 :let alist = [1, 2, 3]
332 :let blist = [1, 2, 3]
333 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000334< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000335 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000336< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000337
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000338Note about comparing lists: Two lists are considered equal if they have the
339same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000340exception: When comparing a number with a string they are considered
341different. There is no automatic type conversion, as with using "==" on
342variables. Example: >
343 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000344< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000345 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000346< 0
347
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000348Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000349can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000350
351 :let a = 5
352 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000353 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000354< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000355 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000356< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000357
Bram Moolenaar13065c42005-01-08 16:08:21 +0000358
359List unpack ~
360
361To unpack the items in a list to individual variables, put the variables in
362square brackets, like list items: >
363 :let [var1, var2] = mylist
364
365When the number of variables does not match the number of items in the list
366this produces an error. To handle any extra items from the list append ";"
367and a variable name: >
368 :let [var1, var2; rest] = mylist
369
370This works like: >
371 :let var1 = mylist[0]
372 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000373 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000374
375Except that there is no error if there are only two items. "rest" will be an
376empty list then.
377
378
379List modification ~
380 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000381To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000382 :let list[4] = "four"
383 :let listlist[0][3] = item
384
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000385To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000386modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000387 :let list[3:5] = [3, 4, 5]
388
Bram Moolenaar13065c42005-01-08 16:08:21 +0000389Adding and removing items from a list is done with functions. Here are a few
390examples: >
391 :call insert(list, 'a') " prepend item 'a'
392 :call insert(list, 'a', 3) " insert item 'a' before list[3]
393 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000394 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000395 :call extend(list, [1, 2]) " extend the list with two more items
396 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000397 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000398 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000399 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000400 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000401
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000402Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000403 :call sort(list) " sort a list alphabetically
404 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100405 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000406
Bram Moolenaar13065c42005-01-08 16:08:21 +0000407
408For loop ~
409
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000410The |:for| loop executes commands for each item in a list. A variable is set
411to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000412 :for item in mylist
413 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000414 :endfor
415
416This works like: >
417 :let index = 0
418 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000419 : let item = mylist[index]
420 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000421 : let index = index + 1
422 :endwhile
423
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000424If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000425function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000426
Bram Moolenaar58b85342016-08-14 19:54:54 +0200427Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000428requires the argument to be a list of lists. >
429 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
430 : call Doit(lnum, col)
431 :endfor
432
433This works like a |:let| command is done for each list item. Again, the types
434must remain the same to avoid an error.
435
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000436It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000437 :for [i, j; rest] in listlist
438 : call Doit(i, j)
439 : if !empty(rest)
440 : echo "remainder: " . string(rest)
441 : endif
442 :endfor
443
444
445List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000446 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000447Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000448 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000449 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000450 :let l = len(list) " number of items in list
451 :let big = max(list) " maximum value in list
452 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000453 :let xs = count(list, 'x') " count nr of times 'x' appears in list
454 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000455 :let lines = getline(1, 10) " get ten text lines from buffer
456 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000457 :let list = split("a b c") " create list from items in a string
458 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000459 :let s = string(list) " String representation of list
460 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000461
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000462Don't forget that a combination of features can make things simple. For
463example, to add up all the numbers in a list: >
464 :exe 'let sum = ' . join(nrlist, '+')
465
Bram Moolenaar13065c42005-01-08 16:08:21 +0000466
Bram Moolenaard8b02732005-01-14 21:48:43 +00004671.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100468 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000469A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000470entry can be located with the key. The entries are stored without a specific
471ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000472
473
474Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000475 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000476A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000477braces. Each entry has a key and a value, separated by a colon. Each key can
478only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
480 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000481< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000482A key is always a String. You can use a Number, it will be converted to a
483String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200484entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaard5abb4c2019-07-13 22:46:10 +0200485Number will be converted to the String '4'. The empty string can also be used
486as a key.
Bram Moolenaar56c860c2019-08-17 20:09:31 +0200487 *literal-Dict* *#{}*
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200488To avoid having to put quotes around every key the #{} form can be used. This
Bram Moolenaard5abb4c2019-07-13 22:46:10 +0200489does require the key to consist only of ASCII letters, digits, '-' and '_'.
490Example: >
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200491 let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3}
492Note that 333 here is the string "333". Empty keys are not possible with #{}.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000493
Bram Moolenaar58b85342016-08-14 19:54:54 +0200494A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000495nested Dictionary: >
496 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
497
498An extra comma after the last entry is ignored.
499
500
501Accessing entries ~
502
503The normal way to access an entry is by putting the key in square brackets: >
504 :let val = mydict["one"]
505 :let mydict["four"] = 4
506
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000507You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000508
509For keys that consist entirely of letters, digits and underscore the following
510form can be used |expr-entry|: >
511 :let val = mydict.one
512 :let mydict.four = 4
513
514Since an entry can be any type, also a List and a Dictionary, the indexing and
515key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000516 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000517
518
519Dictionary to List conversion ~
520
Bram Moolenaar58b85342016-08-14 19:54:54 +0200521You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000522turn the Dictionary into a List and pass it to |:for|.
523
524Most often you want to loop over the keys, using the |keys()| function: >
525 :for key in keys(mydict)
526 : echo key . ': ' . mydict[key]
527 :endfor
528
529The List of keys is unsorted. You may want to sort them first: >
530 :for key in sort(keys(mydict))
531
532To loop over the values use the |values()| function: >
533 :for v in values(mydict)
534 : echo "value: " . v
535 :endfor
536
537If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100538a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000539 :for [key, value] in items(mydict)
540 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000541 :endfor
542
543
544Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000545 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000546Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
547Dictionary. Otherwise, assignment results in referring to the same
548Dictionary: >
549 :let onedict = {'a': 1, 'b': 2}
550 :let adict = onedict
551 :let adict['a'] = 11
552 :echo onedict['a']
553 11
554
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000555Two Dictionaries compare equal if all the key-value pairs compare equal. For
556more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000557
558
559Dictionary modification ~
560 *dict-modification*
561To change an already existing entry of a Dictionary, or to add a new entry,
562use |:let| this way: >
563 :let dict[4] = "four"
564 :let dict['one'] = item
565
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000566Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
567Three ways to remove the entry with key "aaa" from dict: >
568 :let i = remove(dict, 'aaa')
569 :unlet dict.aaa
570 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000571
572Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000573 :call extend(adict, bdict)
574This extends adict with all entries from bdict. Duplicate keys cause entries
575in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000576Note that the order of entries in a Dictionary is irrelevant, thus don't
577expect ":echo adict" to show the items from bdict after the older entries in
578adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000579
580Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000581 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000582This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000583
584
585Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100586 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000587When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200588special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000589 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000590 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000591 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000592 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
593 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000594
595This is like a method in object oriented programming. The entry in the
596Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
597the function was invoked from.
598
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000599It is also possible to add a function without the "dict" attribute as a
600Funcref to a Dictionary, but the "self" variable is not available then.
601
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000602 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000603To avoid the extra name for the function it can be defined and directly
604assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000605 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200606 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000607 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000608 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000609 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000610
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000611The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200612that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000613|Funcref|. It will automatically be deleted when there is no |Funcref|
614remaining that refers to it.
615
616It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000617
Bram Moolenaar1affd722010-08-04 17:49:30 +0200618If you get an error for a numbered function, you can find out what it is with
619a trick. Assuming the function is 42, the command is: >
620 :function {42}
621
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000622
623Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000624 *E715*
625Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000626 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
627 :if empty(dict) " TRUE if dict is empty
628 :let l = len(dict) " number of items in dict
629 :let big = max(dict) " maximum value in dict
630 :let small = min(dict) " minimum value in dict
631 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
632 :let s = string(dict) " String representation of dict
633 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000634
635
Bram Moolenaard8968242019-01-15 22:51:57 +01006361.5 Blobs ~
637 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100638A Blob is a binary object. It can be used to read an image from a file and
639send it over a channel, for example.
640
641A Blob mostly behaves like a |List| of numbers, where each number has the
642value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100643
644
645Blob creation ~
646
647A Blob can be created with a |blob-literal|: >
648 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100649Dots can be inserted between bytes (pair of hex characters) for readability,
650they don't change the value: >
651 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100652
653A blob can be read from a file with |readfile()| passing the {type} argument
654set to "B", for example: >
655 :let b = readfile('image.png', 'B')
656
657A blob can be read from a channel with the |ch_readblob()| function.
658
659
660Blob index ~
661 *blob-index* *E979*
662A byte in the Blob can be accessed by putting the index in square brackets
663after the Blob. Indexes are zero-based, thus the first byte has index zero. >
664 :let myblob = 0z00112233
665 :let byte = myblob[0] " get the first byte: 0x00
666 :let byte = myblob[2] " get the third byte: 0x22
667
668A negative index is counted from the end. Index -1 refers to the last byte in
669the Blob, -2 to the last but one byte, etc. >
670 :let last = myblob[-1] " get the last byte: 0x33
671
672To avoid an error for an invalid index use the |get()| function. When an item
673is not available it returns -1 or the default value you specify: >
674 :echo get(myblob, idx)
675 :echo get(myblob, idx, 999)
676
677
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100678Blob iteration ~
679
680The |:for| loop executes commands for each byte of a Blob. The loop variable is
681set to each byte in the Blob. Example: >
682 :for byte in 0z112233
683 : call Doit(byte)
684 :endfor
685This calls Doit() with 0x11, 0x22 and 0x33.
686
687
Bram Moolenaard8968242019-01-15 22:51:57 +0100688Blob concatenation ~
689
690Two blobs can be concatenated with the "+" operator: >
691 :let longblob = myblob + 0z4455
692 :let myblob += 0z6677
693
694To change a blob in-place see |blob-modification| below.
695
696
697Part of a blob ~
698
699A part of the Blob can be obtained by specifying the first and last index,
700separated by a colon in square brackets: >
701 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100702 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100703 :let shortblob = myblob[2:-1] " get 0z2233
704
705Omitting the first index is similar to zero. Omitting the last index is
706similar to -1. >
707 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
708 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
709 :let otherblob = myblob[:] " make a copy of the Blob
710
Bram Moolenaard09091d2019-01-17 16:07:22 +0100711If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100712before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100713message.
714
715If the second index is equal to or greater than the length of the list the
716length minus one is used: >
717 :echo myblob[2:8] " result: 0z2233
718
719
720Blob modification ~
721 *blob-modification*
722To change a specific byte of a blob use |:let| this way: >
723 :let blob[4] = 0x44
724
725When the index is just one beyond the end of the Blob, it is appended. Any
726higher index is an error.
727
728To change a sequence of bytes the [:] notation can be used: >
729 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100730The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100731provided. *E972*
732
733To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100734modified. The value must have the same number of bytes in the range: >
735 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100736
737You can also use the functions |add()|, |remove()| and |insert()|.
738
739
740Blob identity ~
741
742Blobs can be compared for equality: >
743 if blob == 0z001122
744And for equal identity: >
745 if blob is otherblob
746< *blob-identity* *E977*
747When variable "aa" is a Blob and you assign it to another variable "bb", both
748variables refer to the same Blob. Then the "is" operator returns true.
749
750When making a copy using [:] or |copy()| the values are the same, but the
751identity is different: >
752 :let blob = 0z112233
753 :let blob2 = blob
754 :echo blob == blob2
755< 1 >
756 :echo blob is blob2
757< 1 >
758 :let blob3 = blob[:]
759 :echo blob == blob3
760< 1 >
761 :echo blob is blob3
762< 0
763
Bram Moolenaard09091d2019-01-17 16:07:22 +0100764Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100765works, as explained above.
766
767
7681.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000769 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770If you need to know the type of a variable or expression, use the |type()|
771function.
772
773When the '!' flag is included in the 'viminfo' option, global variables that
774start with an uppercase letter, and don't contain a lowercase letter, are
775stored in the viminfo file |viminfo-file|.
776
777When the 'sessionoptions' option contains "global", global variables that
778start with an uppercase letter and contain at least one lowercase letter are
779stored in the session file |session-file|.
780
781variable name can be stored where ~
782my_var_6 not
783My_Var_6 session file
784MY_VAR_6 viminfo file
785
786
787It's possible to form a variable name with curly braces, see
788|curly-braces-names|.
789
790==============================================================================
7912. Expression syntax *expression-syntax*
792
793Expression syntax summary, from least to most significant:
794
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200795|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200796 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200798|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200799 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000800
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200801|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200802 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000803
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200804|expr4| expr5
805 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000806 expr5 != expr5 not equal
807 expr5 > expr5 greater than
808 expr5 >= expr5 greater than or equal
809 expr5 < expr5 smaller than
810 expr5 <= expr5 smaller than or equal
811 expr5 =~ expr5 regexp matches
812 expr5 !~ expr5 regexp doesn't match
813
814 expr5 ==? expr5 equal, ignoring case
815 expr5 ==# expr5 equal, match case
816 etc. As above, append ? for ignoring case, # for
817 matching case
818
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100819 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
820 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
821 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000822
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200823|expr5| expr6
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200824 expr6 + expr6 ... number addition, list or blob concatenation
825 expr6 - expr6 ... number subtraction
826 expr6 . expr6 ... string concatenation
827 expr6 .. expr6 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000828
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200829|expr6| expr7
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200830 expr7 * expr7 ... number multiplication
831 expr7 / expr7 ... number division
832 expr7 % expr7 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200834|expr7| expr8
835 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000836 - expr7 unary minus
837 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000838
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200839|expr8| expr9
840 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000841 expr8[expr1 : expr1] substring of a String or sublist of a |List|
842 expr8.name entry in a |Dictionary|
843 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar25e42232019-08-04 15:04:10 +0200844 expr8->name(expr1, ...) |method| call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000845
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200846|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000847 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000848 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000849 [expr1, ...] |List|
850 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar25e42232019-08-04 15:04:10 +0200851 #{key: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000852 &option option value
853 (expr1) nested expression
854 variable internal variable
855 va{ria}ble internal variable with curly braces
856 $VAR environment variable
857 @r contents of register 'r'
858 function(expr1, ...) function call
859 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200860 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861
862
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200863"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000864Example: >
865 &nu || &list && &shell == "csh"
866
867All expressions within one level are parsed from left to right.
868
869
870expr1 *expr1* *E109*
871-----
872
873expr2 ? expr1 : expr1
874
875The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200876|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000877otherwise the result is the value of the expression after the ':'.
878Example: >
879 :echo lnum == 1 ? "top" : lnum
880
881Since the first expression is an "expr2", it cannot contain another ?:. The
882other two expressions can, thus allow for recursive use of ?:.
883Example: >
884 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
885
886To keep this readable, using |line-continuation| is suggested: >
887 :echo lnum == 1
888 :\ ? "top"
889 :\ : lnum == 1000
890 :\ ? "last"
891 :\ : lnum
892
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000893You should always put a space before the ':', otherwise it can be mistaken for
894use in a variable such as "a:1".
895
Bram Moolenaar071d4272004-06-13 20:20:40 +0000896
897expr2 and expr3 *expr2* *expr3*
898---------------
899
Bram Moolenaar04186092016-08-29 21:55:35 +0200900expr3 || expr3 .. logical OR *expr-barbar*
901expr4 && expr4 .. logical AND *expr-&&*
902
Bram Moolenaar071d4272004-06-13 20:20:40 +0000903The "||" and "&&" operators take one argument on each side. The arguments
904are (converted to) Numbers. The result is:
905
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200906 input output ~
907n1 n2 n1 || n2 n1 && n2 ~
908|FALSE| |FALSE| |FALSE| |FALSE|
909|FALSE| |TRUE| |TRUE| |FALSE|
910|TRUE| |FALSE| |TRUE| |FALSE|
911|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000912
913The operators can be concatenated, for example: >
914
915 &nu || &list && &shell == "csh"
916
917Note that "&&" takes precedence over "||", so this has the meaning of: >
918
919 &nu || (&list && &shell == "csh")
920
921Once the result is known, the expression "short-circuits", that is, further
922arguments are not evaluated. This is like what happens in C. For example: >
923
924 let a = 1
925 echo a || b
926
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200927This is valid even if there is no variable called "b" because "a" is |TRUE|,
928so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000929
930 echo exists("b") && b == "yes"
931
932This is valid whether "b" has been defined or not. The second clause will
933only be evaluated if "b" has been defined.
934
935
936expr4 *expr4*
937-----
938
939expr5 {cmp} expr5
940
941Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
942if it evaluates to true.
943
Bram Moolenaar446cb832008-06-24 21:56:24 +0000944 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000945 *expr-<* *expr-<=* *expr-=~* *expr-!~*
946 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
947 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
948 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
949 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200950 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
951 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000952 use 'ignorecase' match case ignore case ~
953equal == ==# ==?
954not equal != !=# !=?
955greater than > ># >?
956greater than or equal >= >=# >=?
957smaller than < <# <?
958smaller than or equal <= <=# <=?
959regexp matches =~ =~# =~?
960regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200961same instance is is# is?
962different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000963
964Examples:
965"abc" ==# "Abc" evaluates to 0
966"abc" ==? "Abc" evaluates to 1
967"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
968
Bram Moolenaar13065c42005-01-08 16:08:21 +0000969 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +0100970A |List| can only be compared with a |List| and only "equal", "not equal",
971"is" and "isnot" can be used. This compares the values of the list,
972recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000973
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000974 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000975A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +0100976equal", "is" and "isnot" can be used. This compares the key/values of the
977|Dictionary| recursively. Ignoring case means case is ignored when comparing
978item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000979
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200980 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200981A |Funcref| can only be compared with a |Funcref| and only "equal", "not
982equal", "is" and "isnot" can be used. Case is never ignored. Whether
983arguments or a Dictionary are bound (with a partial) matters. The
984Dictionaries must also be equal (or the same, in case of "is") and the
985arguments must be equal (or the same).
986
987To compare Funcrefs to see if they refer to the same function, ignoring bound
988Dictionary and arguments, use |get()| to get the function name: >
989 if get(Part1, 'name') == get(Part2, 'name')
990 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000991
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100992Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
993the expressions are referring to the same |List|, |Dictionary| or |Blob|
994instance. A copy of a |List| is different from the original |List|. When
995using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
996using "equal", using "isnot" equivalent to using "not equal". Except that
997a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100998 echo 4 == '4'
999 1
1000 echo 4 is '4'
1001 0
1002 echo 0 is []
1003 0
1004"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001005
Bram Moolenaar071d4272004-06-13 20:20:40 +00001006When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +02001007and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001008 echo 0 == 'x'
1009 1
1010because 'x' converted to a Number is zero. However: >
1011 echo [0] == ['x']
1012 0
1013Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001014
1015When comparing two Strings, this is done with strcmp() or stricmp(). This
1016results in the mathematical difference (comparing byte values), not
1017necessarily the alphabetical difference in the local language.
1018
Bram Moolenaar446cb832008-06-24 21:56:24 +00001019When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001020'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001021
1022When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001023'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1024
1025'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001026
1027The "=~" and "!~" operators match the lefthand argument with the righthand
1028argument, which is used as a pattern. See |pattern| for what a pattern is.
1029This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1030matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1031portable. To avoid backslashes in the regexp pattern to be doubled, use a
1032single-quote string, see |literal-string|.
1033Since a string is considered to be a single line, a multi-line pattern
1034(containing \n, backslash-n) will not match. However, a literal NL character
1035can be matched like an ordinary character. Examples:
1036 "foo\nbar" =~ "\n" evaluates to 1
1037 "foo\nbar" =~ "\\n" evaluates to 0
1038
1039
1040expr5 and expr6 *expr5* *expr6*
1041---------------
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001042expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1043expr6 - expr6 Number subtraction *expr--*
1044expr6 . expr6 String concatenation *expr-.*
1045expr6 .. expr6 String concatenation *expr-..*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001046
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001047For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001048result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001049
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001050For String concatenation ".." is preferred, since "." is ambiguous, it is also
1051used for |Dict| member access and floating point numbers.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001052When |vimscript-version| is 2 or higher, using "." is not allowed.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001053
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001054expr7 * expr7 Number multiplication *expr-star*
1055expr7 / expr7 Number division *expr-/*
1056expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001057
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02001058For all, except "." and "..", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001059For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001060
1061Note the difference between "+" and ".":
1062 "123" + "456" = 579
1063 "123" . "456" = "123456"
1064
Bram Moolenaar446cb832008-06-24 21:56:24 +00001065Since '.' has the same precedence as '+' and '-', you need to read: >
1066 1 . 90 + 90.0
1067As: >
1068 (1 . 90) + 90.0
1069That works, since the String "190" is automatically converted to the Number
1070190, which can be added to the Float 90.0. However: >
1071 1 . 90 * 90.0
1072Should be read as: >
1073 1 . (90 * 90.0)
1074Since '.' has lower precedence than '*'. This does NOT work, since this
1075attempts to concatenate a Float and a String.
1076
1077When dividing a Number by zero the result depends on the value:
1078 0 / 0 = -0x80000000 (like NaN for Float)
1079 >0 / 0 = 0x7fffffff (like positive infinity)
1080 <0 / 0 = -0x7fffffff (like negative infinity)
1081 (before Vim 7.2 it was always 0x7fffffff)
1082
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001083When 64-bit Number support is enabled:
1084 0 / 0 = -0x8000000000000000 (like NaN for Float)
1085 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1086 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1087
Bram Moolenaar071d4272004-06-13 20:20:40 +00001088When the righthand side of '%' is zero, the result is 0.
1089
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001090None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001091
Bram Moolenaar446cb832008-06-24 21:56:24 +00001092. and % do not work for Float. *E804*
1093
Bram Moolenaar071d4272004-06-13 20:20:40 +00001094
1095expr7 *expr7*
1096-----
1097! expr7 logical NOT *expr-!*
1098- expr7 unary minus *expr-unary--*
1099+ expr7 unary plus *expr-unary-+*
1100
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001101For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001102For '-' the sign of the number is changed.
1103For '+' the number is unchanged.
1104
1105A String will be converted to a Number first.
1106
Bram Moolenaar58b85342016-08-14 19:54:54 +02001107These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001108 !-1 == 0
1109 !!8 == 1
1110 --9 == 9
1111
1112
1113expr8 *expr8*
1114-----
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001115This expression is either |expr9| or a sequence of the alternatives below,
1116in any order. E.g., these are all possible:
Bram Moolenaar25e42232019-08-04 15:04:10 +02001117 expr8[expr1].name
1118 expr8.name[expr1]
1119 expr8(expr1, ...)[expr1].name
1120 expr8->(expr1, ...)[expr1]
Bram Moolenaarac92e252019-08-03 21:58:38 +02001121Evaluation is always from left to right.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001122
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001123expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +02001124 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001125If expr8 is a Number or String this results in a String that contains the
1126expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001127Number. This doesn't recognize multi-byte encodings, see `byteidx()` for
Bram Moolenaar03413f42016-04-12 21:07:15 +02001128an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129
Bram Moolenaar256972a2015-12-29 19:10:25 +01001130Index zero gives the first byte. This is like it works in C. Careful:
1131text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001132cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001133 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001134
1135If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001136String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001137compatibility). Use [-1:] to get the last byte.
1138
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001139If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001140for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001141error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001142 :let item = mylist[-1] " get last item
1143
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001144Generally, if a |List| index is equal to or higher than the length of the
1145|List|, or more negative than the length of the |List|, this results in an
1146error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001147
Bram Moolenaard8b02732005-01-14 21:48:43 +00001148
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001149expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001150
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001151If expr8 is a Number or String this results in the substring with the bytes
1152from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001153expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
1154|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001155
1156If expr1a is omitted zero is used. If expr1b is omitted the length of the
1157string minus one is used.
1158
1159A negative number can be used to measure from the end of the string. -1 is
1160the last character, -2 the last but one, etc.
1161
1162If an index goes out of range for the string characters are omitted. If
1163expr1b is smaller than expr1a the result is an empty string.
1164
1165Examples: >
1166 :let c = name[-1:] " last byte of a string
1167 :let c = name[-2:-2] " last but one byte of a string
1168 :let s = line(".")[4:] " from the fifth byte to the end
1169 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001170<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001171 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001172If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001173the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001174just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001175 :let l = mylist[:3] " first four items
1176 :let l = mylist[4:4] " List with one item
1177 :let l = mylist[:] " shallow copy of a List
1178
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001179If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
1180indexes expr1a and expr1b, inclusive. Examples: >
1181 :let b = 0zDEADBEEF
1182 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001183 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001184
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001185Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1186error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187
Bram Moolenaarda440d22016-01-16 21:27:23 +01001188Watch out for confusion between a namespace and a variable followed by a colon
1189for a sublist: >
1190 mylist[n:] " uses variable n
1191 mylist[s:] " uses namespace s:, error!
1192
Bram Moolenaard8b02732005-01-14 21:48:43 +00001193
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001194expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001195
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001196If expr8 is a |Dictionary| and it is followed by a dot, then the following
1197name will be used as a key in the |Dictionary|. This is just like:
1198expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001199
1200The name must consist of alphanumeric characters, just like a variable name,
1201but it may start with a number. Curly braces cannot be used.
1202
1203There must not be white space before or after the dot.
1204
1205Examples: >
1206 :let dict = {"one": 1, 2: "two"}
Bram Moolenaar68e65602019-05-26 21:33:31 +02001207 :echo dict.one " shows "1"
1208 :echo dict.2 " shows "two"
1209 :echo dict .2 " error because of space before the dot
Bram Moolenaard8b02732005-01-14 21:48:43 +00001210
1211Note that the dot is also used for String concatenation. To avoid confusion
1212always put spaces around the dot for String concatenation.
1213
1214
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001215expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001216
1217When expr8 is a |Funcref| type variable, invoke the function it refers to.
1218
1219
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001220expr8->name([args]) method call *method* *->*
1221expr8->{lambda}([args])
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001222 *E276*
Bram Moolenaar25e42232019-08-04 15:04:10 +02001223For methods that are also available as global functions this is the same as: >
Bram Moolenaarac92e252019-08-03 21:58:38 +02001224 name(expr8 [, args])
1225There can also be methods specifically for the type of "expr8".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001226
Bram Moolenaar51841322019-08-08 21:10:01 +02001227This allows for chaining, passing the value that one method returns to the
1228next method: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02001229 mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
1230<
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001231Example of using a lambda: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02001232 GetPercentage()->{x -> x * 100}()->printf('%d%%')
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001233<
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02001234When using -> the |expr7| operators will be applied first, thus: >
1235 -1.234->string()
1236Is equivalent to: >
1237 (-1.234)->string()
1238And NOT: >
1239 -(1.234->string())
1240<
Bram Moolenaar51841322019-08-08 21:10:01 +02001241 *E274*
1242"->name(" must not contain white space. There can be white space before the
1243"->" and after the "(", thus you can split the lines like this: >
1244 mylist
1245 \ ->filter(filterexpr)
1246 \ ->map(mapexpr)
1247 \ ->sort()
1248 \ ->join()
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001249
1250When using the lambda form there must be no white space between the } and the
1251(.
1252
Bram Moolenaar25e42232019-08-04 15:04:10 +02001253
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001254 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001255number
1256------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001257number number constant *expr-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001258 *hex-number* *octal-number* *binary-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001259
Bram Moolenaar7571d552016-08-18 22:54:46 +02001260Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
1261and Octal (starting with 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001262
Bram Moolenaar446cb832008-06-24 21:56:24 +00001263 *floating-point-format*
1264Floating point numbers can be written in two forms:
1265
1266 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001267 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001268
1269{N} and {M} are numbers. Both {N} and {M} must be present and can only
1270contain digits.
1271[-+] means there is an optional plus or minus sign.
1272{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001273Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001274locale is.
1275{only when compiled with the |+float| feature}
1276
1277Examples:
1278 123.456
1279 +0.0001
1280 55.0
1281 -0.123
1282 1.234e03
1283 1.0E-6
1284 -3.1416e+88
1285
1286These are INVALID:
1287 3. empty {M}
1288 1e40 missing .{M}
1289
1290Rationale:
1291Before floating point was introduced, the text "123.456" was interpreted as
1292the two numbers "123" and "456", both converted to a string and concatenated,
1293resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001294could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001295incompatibility was accepted in favor of being able to use the normal notation
1296for floating point numbers.
1297
Bram Moolenaard47d5222018-12-09 20:43:55 +01001298 *float-pi* *float-e*
1299A few useful values to copy&paste: >
1300 :let pi = 3.14159265359
1301 :let e = 2.71828182846
1302Or, if you don't want to write them in as floating-point literals, you can
1303also use functions, like the following: >
1304 :let pi = acos(-1.0)
1305 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001306<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001307 *floating-point-precision*
1308The precision and range of floating points numbers depends on what "double"
1309means in the library Vim was compiled with. There is no way to change this at
1310runtime.
1311
1312The default for displaying a |Float| is to use 6 decimal places, like using
1313printf("%g", f). You can select something else when using the |printf()|
1314function. Example: >
1315 :echo printf('%.15e', atan(1))
1316< 7.853981633974483e-01
1317
1318
Bram Moolenaar071d4272004-06-13 20:20:40 +00001319
Bram Moolenaar979243b2015-06-26 19:35:49 +02001320string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001321------
1322"string" string constant *expr-quote*
1323
1324Note that double quotes are used.
1325
1326A string constant accepts these special characters:
1327\... three-digit octal number (e.g., "\316")
1328\.. two-digit octal number (must be followed by non-digit)
1329\. one-digit octal number (must be followed by non-digit)
1330\x.. byte specified with two hex numbers (e.g., "\x1f")
1331\x. byte specified with one hex number (must be followed by non-hex char)
1332\X.. same as \x..
1333\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001334\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001336\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001337\b backspace <BS>
1338\e escape <Esc>
1339\f formfeed <FF>
1340\n newline <NL>
1341\r return <CR>
1342\t tab <Tab>
1343\\ backslash
1344\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001345\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001346 in mappings, the 0x80 byte is escaped.
1347 To use the double quote character it must be escaped: "<M-\">".
1348 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1349 mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001350
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001351Note that "\xff" is stored as the byte 255, which may be invalid in some
1352encodings. Use "\u00ff" to store character 255 according to the current value
1353of 'encoding'.
1354
Bram Moolenaar071d4272004-06-13 20:20:40 +00001355Note that "\000" and "\x00" force the end of the string.
1356
1357
Bram Moolenaard8968242019-01-15 22:51:57 +01001358blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001359------------
1360
1361Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1362The sequence must be an even number of hex characters. Example: >
1363 :let b = 0zFF00ED015DAF
1364
1365
Bram Moolenaar071d4272004-06-13 20:20:40 +00001366literal-string *literal-string* *E115*
1367---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001368'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001369
1370Note that single quotes are used.
1371
Bram Moolenaar58b85342016-08-14 19:54:54 +02001372This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001373meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001374
1375Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001376to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001377 if a =~ "\\s*"
1378 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001379
1380
1381option *expr-option* *E112* *E113*
1382------
1383&option option value, local value if possible
1384&g:option global option value
1385&l:option local option value
1386
1387Examples: >
1388 echo "tabstop is " . &tabstop
1389 if &insertmode
1390
1391Any option name can be used here. See |options|. When using the local value
1392and there is no buffer-local or window-local value, the global value is used
1393anyway.
1394
1395
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001396register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001397--------
1398@r contents of register 'r'
1399
1400The result is the contents of the named register, as a single string.
1401Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001402register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001403registers.
1404
1405When using the '=' register you get the expression itself, not what it
1406evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001407
1408
1409nesting *expr-nesting* *E110*
1410-------
1411(expr1) nested expression
1412
1413
1414environment variable *expr-env*
1415--------------------
1416$VAR environment variable
1417
1418The String value of any environment variable. When it is not defined, the
1419result is an empty string.
Bram Moolenaar691ddee2019-05-09 14:52:41 +02001420
1421The functions `getenv()` and `setenv()` can also be used and work for
1422environment variables with non-alphanumeric names.
1423The function `environ()` can be used to get a Dict with all environment
1424variables.
1425
1426
Bram Moolenaar071d4272004-06-13 20:20:40 +00001427 *expr-env-expand*
1428Note that there is a difference between using $VAR directly and using
1429expand("$VAR"). Using it directly will only expand environment variables that
1430are known inside the current Vim session. Using expand() will first try using
1431the environment variables known inside the current Vim session. If that
1432fails, a shell will be used to expand the variable. This can be slow, but it
1433does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001434 :echo $shell
1435 :echo expand("$shell")
1436The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001437variable (if your shell supports it).
1438
1439
1440internal variable *expr-variable*
1441-----------------
1442variable internal variable
1443See below |internal-variables|.
1444
1445
Bram Moolenaar05159a02005-02-26 23:04:13 +00001446function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001447-------------
1448function(expr1, ...) function call
1449See below |functions|.
1450
1451
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001452lambda expression *expr-lambda* *lambda*
1453-----------------
1454{args -> expr1} lambda expression
1455
1456A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001457evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001458the following ways:
1459
14601. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1461 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020014622. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001463 :let F = {arg1, arg2 -> arg1 - arg2}
1464 :echo F(5, 2)
1465< 3
1466
1467The arguments are optional. Example: >
1468 :let F = {-> 'error function'}
1469 :echo F()
1470< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001471 *closure*
1472Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001473often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001474while they already exist in the function scope. They remain valid even after
1475the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001476 :function Foo(arg)
1477 : let i = 3
1478 : return {x -> x + i - a:arg}
1479 :endfunction
1480 :let Bar = Foo(4)
1481 :echo Bar(6)
1482< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001483
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001484Note that the variables must exist in the outer scope before the lamba is
1485defined for this to work. See also |:func-closure|.
1486
1487Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001488 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001489
1490Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1491 :echo map([1, 2, 3], {idx, val -> val + 1})
1492< [2, 3, 4] >
1493 :echo sort([3,7,2,1,4], {a, b -> a - b})
1494< [1, 2, 3, 4, 7]
1495
1496The lambda expression is also useful for Channel, Job and timer: >
1497 :let timer = timer_start(500,
1498 \ {-> execute("echo 'Handler called'", "")},
1499 \ {'repeat': 3})
1500< Handler called
1501 Handler called
1502 Handler called
1503
1504Note how execute() is used to execute an Ex command. That's ugly though.
1505
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001506
1507Lambda expressions have internal names like '<lambda>42'. If you get an error
1508for a lambda expression, you can find what it is with the following command: >
1509 :function {'<lambda>42'}
1510See also: |numbered-function|
1511
Bram Moolenaar071d4272004-06-13 20:20:40 +00001512==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020015133. Internal variable *internal-variables* *E461*
1514
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515An internal variable name can be made up of letters, digits and '_'. But it
1516cannot start with a digit. It's also possible to use curly braces, see
1517|curly-braces-names|.
1518
1519An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001520An internal variable is explicitly destroyed with the ":unlet" command
1521|:unlet|.
1522Using a name that is not an internal variable or refers to a variable that has
1523been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001524
1525There are several name spaces for variables. Which one is to be used is
1526specified by what is prepended:
1527
1528 (nothing) In a function: local to a function; otherwise: global
1529|buffer-variable| b: Local to the current buffer.
1530|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001531|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001532|global-variable| g: Global.
1533|local-variable| l: Local to a function.
1534|script-variable| s: Local to a |:source|'ed Vim script.
1535|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001536|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001538The scope name by itself can be used as a |Dictionary|. For example, to
1539delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001540 :for k in keys(s:)
1541 : unlet s:[k]
1542 :endfor
1543<
Bram Moolenaar531da592013-05-06 05:58:55 +02001544 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001545A variable name that is preceded with "b:" is local to the current buffer.
1546Thus you can have several "b:foo" variables, one for each buffer.
1547This kind of variable is deleted when the buffer is wiped out or deleted with
1548|:bdelete|.
1549
1550One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001551 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001552b:changedtick The total number of changes to the current buffer. It is
1553 incremented for each change. An undo command is also a change
Bram Moolenaarc024b462019-06-08 18:07:21 +02001554 in this case. Resetting 'modified' when writing the buffer is
1555 also counted.
1556 This can be used to perform an action only when the buffer has
1557 changed. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001559 : let my_changedtick = b:changedtick
1560 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001561 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001562< You cannot change or delete the b:changedtick variable.
1563
Bram Moolenaar531da592013-05-06 05:58:55 +02001564 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001565A variable name that is preceded with "w:" is local to the current window. It
1566is deleted when the window is closed.
1567
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001568 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001569A variable name that is preceded with "t:" is local to the current tab page,
1570It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001571without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001572
Bram Moolenaar531da592013-05-06 05:58:55 +02001573 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001575access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001576place if you like.
1577
Bram Moolenaar531da592013-05-06 05:58:55 +02001578 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001579Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001580But you can also prepend "l:" if you like. However, without prepending "l:"
1581you may run into reserved variable names. For example "count". By itself it
1582refers to "v:count". Using "l:count" you can have a local variable with the
1583same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001584
1585 *script-variable* *s:var*
1586In a Vim script variables starting with "s:" can be used. They cannot be
1587accessed from outside of the scripts, thus are local to the script.
1588
1589They can be used in:
1590- commands executed while the script is sourced
1591- functions defined in the script
1592- autocommands defined in the script
1593- functions and autocommands defined in functions and autocommands which were
1594 defined in the script (recursively)
1595- user defined commands defined in the script
1596Thus not in:
1597- other scripts sourced from this one
1598- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001599- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001600- etc.
1601
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001602Script variables can be used to avoid conflicts with global variable names.
1603Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001604
1605 let s:counter = 0
1606 function MyCounter()
1607 let s:counter = s:counter + 1
1608 echo s:counter
1609 endfunction
1610 command Tick call MyCounter()
1611
1612You can now invoke "Tick" from any script, and the "s:counter" variable in
1613that script will not be changed, only the "s:counter" in the script where
1614"Tick" was defined is used.
1615
1616Another example that does the same: >
1617
1618 let s:counter = 0
1619 command Tick let s:counter = s:counter + 1 | echo s:counter
1620
1621When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001622script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623defined.
1624
1625The script variables are also available when a function is defined inside a
1626function that is defined in a script. Example: >
1627
1628 let s:counter = 0
1629 function StartCounting(incr)
1630 if a:incr
1631 function MyCounter()
1632 let s:counter = s:counter + 1
1633 endfunction
1634 else
1635 function MyCounter()
1636 let s:counter = s:counter - 1
1637 endfunction
1638 endif
1639 endfunction
1640
1641This defines the MyCounter() function either for counting up or counting down
1642when calling StartCounting(). It doesn't matter from where StartCounting() is
1643called, the s:counter variable will be accessible in MyCounter().
1644
1645When the same script is sourced again it will use the same script variables.
1646They will remain valid as long as Vim is running. This can be used to
1647maintain a counter: >
1648
1649 if !exists("s:counter")
1650 let s:counter = 1
1651 echo "script executed for the first time"
1652 else
1653 let s:counter = s:counter + 1
1654 echo "script executed " . s:counter . " times now"
1655 endif
1656
1657Note that this means that filetype plugins don't get a different set of script
1658variables for each buffer. Use local buffer variables instead |b:var|.
1659
1660
Bram Moolenaard47d5222018-12-09 20:43:55 +01001661PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
1662 *E963*
1663Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001664
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001665 *v:beval_col* *beval_col-variable*
1666v:beval_col The number of the column, over which the mouse pointer is.
1667 This is the byte index in the |v:beval_lnum| line.
1668 Only valid while evaluating the 'balloonexpr' option.
1669
1670 *v:beval_bufnr* *beval_bufnr-variable*
1671v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1672 valid while evaluating the 'balloonexpr' option.
1673
1674 *v:beval_lnum* *beval_lnum-variable*
1675v:beval_lnum The number of the line, over which the mouse pointer is. Only
1676 valid while evaluating the 'balloonexpr' option.
1677
1678 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001679v:beval_text The text under or after the mouse pointer. Usually a word as
1680 it is useful for debugging a C program. 'iskeyword' applies,
1681 but a dot and "->" before the position is included. When on a
1682 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001683 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001684 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001685 Only valid while evaluating the 'balloonexpr' option.
1686
1687 *v:beval_winnr* *beval_winnr-variable*
1688v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001689 valid while evaluating the 'balloonexpr' option. The first
1690 window has number zero (unlike most other places where a
1691 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001692
Bram Moolenaar511972d2016-06-04 18:09:59 +02001693 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001694v:beval_winid The |window-ID| of the window, over which the mouse pointer
1695 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001696
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001697 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001698v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001699 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001700 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001701
Bram Moolenaar071d4272004-06-13 20:20:40 +00001702 *v:charconvert_from* *charconvert_from-variable*
1703v:charconvert_from
1704 The name of the character encoding of a file to be converted.
1705 Only valid while evaluating the 'charconvert' option.
1706
1707 *v:charconvert_to* *charconvert_to-variable*
1708v:charconvert_to
1709 The name of the character encoding of a file after conversion.
1710 Only valid while evaluating the 'charconvert' option.
1711
1712 *v:cmdarg* *cmdarg-variable*
1713v:cmdarg This variable is used for two purposes:
1714 1. The extra arguments given to a file read/write command.
1715 Currently these are "++enc=" and "++ff=". This variable is
1716 set before an autocommand event for a file read/write
1717 command is triggered. There is a leading space to make it
1718 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001719 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001720 included here, because it will be executed anyway.
1721 2. When printing a PostScript file with ":hardcopy" this is
1722 the argument for the ":hardcopy" command. This can be used
1723 in 'printexpr'.
1724
1725 *v:cmdbang* *cmdbang-variable*
1726v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1727 was used the value is 1, otherwise it is 0. Note that this
1728 can only be used in autocommands. For user commands |<bang>|
1729 can be used.
1730
Bram Moolenaar42a45122015-07-10 17:56:23 +02001731 *v:completed_item* *completed_item-variable*
1732v:completed_item
1733 |Dictionary| containing the |complete-items| for the most
1734 recently completed word after |CompleteDone|. The
1735 |Dictionary| is empty if the completion failed.
1736
Bram Moolenaar071d4272004-06-13 20:20:40 +00001737 *v:count* *count-variable*
1738v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001739 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001740 :map _x :<C-U>echo "the count is " . v:count<CR>
1741< Note: The <C-U> is required to remove the line range that you
1742 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001743 When there are two counts, as in "3d2w", they are multiplied,
1744 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001745 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001746 "count" also works, for backwards compatibility, unless
1747 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001748
1749 *v:count1* *count1-variable*
1750v:count1 Just like "v:count", but defaults to one when no count is
1751 used.
1752
1753 *v:ctype* *ctype-variable*
1754v:ctype The current locale setting for characters of the runtime
1755 environment. This allows Vim scripts to be aware of the
1756 current locale encoding. Technical: it's the value of
1757 LC_CTYPE. When not using a locale the value is "C".
1758 This variable can not be set directly, use the |:language|
1759 command.
1760 See |multi-lang|.
1761
1762 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001763v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764 one. When multiple signals are caught the number increases.
1765 Can be used in an autocommand to check if Vim didn't
1766 terminate normally. {only works on Unix}
1767 Example: >
1768 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001769< Note: if another deadly signal is caught when v:dying is one,
1770 VimLeave autocommands will not be executed.
1771
Bram Moolenaar37f4cbd2019-08-23 20:58:45 +02001772 *v:echospace* *echospace-variable*
1773v:echospace Number of screen cells that can be used for an `:echo` message
1774 in the last screen line before causing the |hit-enter-prompt|.
1775 Depends on 'showcmd', 'ruler' and 'columns'. You need to
1776 check 'cmdheight' for whether there are full-width lines
1777 available above the last line.
1778
Bram Moolenaar071d4272004-06-13 20:20:40 +00001779 *v:errmsg* *errmsg-variable*
1780v:errmsg Last given error message. It's allowed to set this variable.
1781 Example: >
1782 :let v:errmsg = ""
1783 :silent! next
1784 :if v:errmsg != ""
1785 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001786< "errmsg" also works, for backwards compatibility, unless
1787 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001788
Bram Moolenaar65a54642018-04-28 16:56:53 +02001789 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001790v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001791 This is a list of strings.
1792 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02001793 The return value indicates this: a one is returned if an item
1794 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01001795 To remove old results make it empty: >
1796 :let v:errors = []
1797< If v:errors is set to anything but a list it is made an empty
1798 list by the assert function.
1799
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001800 *v:event* *event-variable*
1801v:event Dictionary containing information about the current
1802 |autocommand|. The dictionary is emptied when the |autocommand|
1803 finishes, please refer to |dict-identity| for how to get an
1804 independent copy of it.
1805
Bram Moolenaar071d4272004-06-13 20:20:40 +00001806 *v:exception* *exception-variable*
1807v:exception The value of the exception most recently caught and not
1808 finished. See also |v:throwpoint| and |throw-variables|.
1809 Example: >
1810 :try
1811 : throw "oops"
1812 :catch /.*/
Bram Moolenaar54775062019-07-31 21:07:14 +02001813 : echo "caught " .. v:exception
Bram Moolenaar071d4272004-06-13 20:20:40 +00001814 :endtry
1815< Output: "caught oops".
1816
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001817 *v:false* *false-variable*
1818v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001819 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001820 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001821 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001822< v:false ~
1823 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001824 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001825
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001826 *v:fcs_reason* *fcs_reason-variable*
1827v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1828 Can be used in an autocommand to decide what to do and/or what
1829 to set v:fcs_choice to. Possible values:
1830 deleted file no longer exists
1831 conflict file contents, mode or timestamp was
1832 changed and buffer is modified
1833 changed file contents has changed
1834 mode mode of file changed
1835 time only file timestamp changed
1836
1837 *v:fcs_choice* *fcs_choice-variable*
1838v:fcs_choice What should happen after a |FileChangedShell| event was
1839 triggered. Can be used in an autocommand to tell Vim what to
1840 do with the affected buffer:
1841 reload Reload the buffer (does not work if
1842 the file was deleted).
1843 ask Ask the user what to do, as if there
1844 was no autocommand. Except that when
1845 only the timestamp changed nothing
1846 will happen.
1847 <empty> Nothing, the autocommand should do
1848 everything that needs to be done.
1849 The default is empty. If another (invalid) value is used then
1850 Vim behaves like it is empty, there is no warning message.
1851
Bram Moolenaar071d4272004-06-13 20:20:40 +00001852 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001853v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001854 option used for ~
1855 'charconvert' file to be converted
1856 'diffexpr' original file
1857 'patchexpr' original file
1858 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001859 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001860
1861 *v:fname_out* *fname_out-variable*
1862v:fname_out The name of the output file. Only valid while
1863 evaluating:
1864 option used for ~
1865 'charconvert' resulting converted file (*)
1866 'diffexpr' output of diff
1867 'patchexpr' resulting patched file
1868 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001869 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001870 for a read command (e.g., ":e file") it will be a temporary
1871 file and different from v:fname_in.
1872
1873 *v:fname_new* *fname_new-variable*
1874v:fname_new The name of the new version of the file. Only valid while
1875 evaluating 'diffexpr'.
1876
1877 *v:fname_diff* *fname_diff-variable*
1878v:fname_diff The name of the diff (patch) file. Only valid while
1879 evaluating 'patchexpr'.
1880
1881 *v:folddashes* *folddashes-variable*
1882v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1883 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001884 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001885
1886 *v:foldlevel* *foldlevel-variable*
1887v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001888 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001889
1890 *v:foldend* *foldend-variable*
1891v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001892 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001893
1894 *v:foldstart* *foldstart-variable*
1895v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001896 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001897
Bram Moolenaar817a8802013-11-09 01:44:43 +01001898 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001899v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01001900 Setting it makes sense only if 'hlsearch' is enabled which
1901 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001902 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001903 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001904< Note that the value is restored when returning from a
1905 function. |function-search-undo|.
1906
Bram Moolenaar843ee412004-06-30 16:16:41 +00001907 *v:insertmode* *insertmode-variable*
1908v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1909 events. Values:
1910 i Insert mode
1911 r Replace mode
1912 v Virtual Replace mode
1913
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001914 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001915v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001916 evaluating the expression used with |map()| and |filter()|.
1917 Read-only.
1918
Bram Moolenaar071d4272004-06-13 20:20:40 +00001919 *v:lang* *lang-variable*
1920v:lang The current locale setting for messages of the runtime
1921 environment. This allows Vim scripts to be aware of the
1922 current language. Technical: it's the value of LC_MESSAGES.
1923 The value is system dependent.
1924 This variable can not be set directly, use the |:language|
1925 command.
1926 It can be different from |v:ctype| when messages are desired
1927 in a different language than what is used for character
1928 encoding. See |multi-lang|.
1929
1930 *v:lc_time* *lc_time-variable*
1931v:lc_time The current locale setting for time messages of the runtime
1932 environment. This allows Vim scripts to be aware of the
1933 current language. Technical: it's the value of LC_TIME.
1934 This variable can not be set directly, use the |:language|
1935 command. See |multi-lang|.
1936
1937 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001938v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1939 'indentexpr' expressions, tab page number for 'guitablabel'
1940 and 'guitabtooltip'. Only valid while one of these
1941 expressions is being evaluated. Read-only when in the
1942 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943
Bram Moolenaar219b8702006-11-01 14:32:36 +00001944 *v:mouse_win* *mouse_win-variable*
1945v:mouse_win Window number for a mouse click obtained with |getchar()|.
1946 First window has number 1, like with |winnr()|. The value is
1947 zero when there was no mouse button click.
1948
Bram Moolenaar511972d2016-06-04 18:09:59 +02001949 *v:mouse_winid* *mouse_winid-variable*
1950v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1951 The value is zero when there was no mouse button click.
1952
Bram Moolenaar219b8702006-11-01 14:32:36 +00001953 *v:mouse_lnum* *mouse_lnum-variable*
1954v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1955 This is the text line number, not the screen line number. The
1956 value is zero when there was no mouse button click.
1957
1958 *v:mouse_col* *mouse_col-variable*
1959v:mouse_col Column number for a mouse click obtained with |getchar()|.
1960 This is the screen column number, like with |virtcol()|. The
1961 value is zero when there was no mouse button click.
1962
Bram Moolenaard09091d2019-01-17 16:07:22 +01001963 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001964v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001965 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001966 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001967 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001968 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001969< v:none ~
1970 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001971 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001972
1973 *v:null* *null-variable*
1974v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001975 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001976 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001977 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001978 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001979< v:null ~
1980 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001981 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001982
Bram Moolenaard812df62008-11-09 12:46:09 +00001983 *v:oldfiles* *oldfiles-variable*
1984v:oldfiles List of file names that is loaded from the |viminfo| file on
1985 startup. These are the files that Vim remembers marks for.
1986 The length of the List is limited by the ' argument of the
1987 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001988 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001989 Also see |:oldfiles| and |c_#<|.
1990 The List can be modified, but this has no effect on what is
1991 stored in the |viminfo| file later. If you use values other
1992 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001993 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001994
Bram Moolenaar53744302015-07-17 17:38:22 +02001995 *v:option_new*
1996v:option_new New value of the option. Valid while executing an |OptionSet|
1997 autocommand.
1998 *v:option_old*
1999v:option_old Old value of the option. Valid while executing an |OptionSet|
Bram Moolenaard7c96872019-06-15 17:12:48 +02002000 autocommand. Depending on the command used for setting and the
2001 kind of option this is either the local old value or the
2002 global old value.
2003 *v:option_oldlocal*
2004v:option_oldlocal
2005 Old local value of the option. Valid while executing an
2006 |OptionSet| autocommand.
2007 *v:option_oldglobal*
2008v:option_oldglobal
2009 Old global value of the option. Valid while executing an
2010 |OptionSet| autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02002011 *v:option_type*
2012v:option_type Scope of the set command. Valid while executing an
2013 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaard7c96872019-06-15 17:12:48 +02002014 *v:option_command*
2015v:option_command
2016 Command used to set the option. Valid while executing an
2017 |OptionSet| autocommand.
2018 value option was set via ~
2019 "setlocal" |:setlocal| or ":let l:xxx"
2020 "setglobal" |:setglobal| or ":let g:xxx"
2021 "set" |:set| or |:let|
2022 "modeline" |modeline|
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002023 *v:operator* *operator-variable*
2024v:operator The last operator given in Normal mode. This is a single
2025 character except for commands starting with <g> or <z>,
2026 in which case it is two characters. Best used alongside
2027 |v:prevcount| and |v:register|. Useful if you want to cancel
2028 Operator-pending mode and then use the operator, e.g.: >
2029 :omap O <Esc>:call MyMotion(v:operator)<CR>
2030< The value remains set until another operator is entered, thus
2031 don't expect it to be empty.
2032 v:operator is not set for |:delete|, |:yank| or other Ex
2033 commands.
2034 Read-only.
2035
Bram Moolenaar071d4272004-06-13 20:20:40 +00002036 *v:prevcount* *prevcount-variable*
2037v:prevcount The count given for the last but one Normal mode command.
2038 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002039 you want to cancel Visual or Operator-pending mode and then
2040 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002041 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
2042< Read-only.
2043
Bram Moolenaar05159a02005-02-26 23:04:13 +00002044 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002045v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00002046 See |profiling|.
2047
Bram Moolenaar071d4272004-06-13 20:20:40 +00002048 *v:progname* *progname-variable*
2049v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02002050 invoked. Allows you to do special initialisations for |view|,
2051 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002052 Read-only.
2053
Bram Moolenaara1706c92014-04-01 19:55:49 +02002054 *v:progpath* *progpath-variable*
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002055v:progpath Contains the command with which Vim was invoked, in a form
2056 that when passed to the shell will run the same Vim executable
2057 as the current one (if $PATH remains unchanged).
2058 Useful if you want to message a Vim server using a
Bram Moolenaara1706c92014-04-01 19:55:49 +02002059 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002060 To get the full path use: >
2061 echo exepath(v:progpath)
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002062< If the command has a relative path it will be expanded to the
2063 full path, so that it still works after `:cd`. Thus starting
2064 "./vim" results in "/home/user/path/to/vim/src/vim".
2065 On Linux and other systems it will always be the full path.
2066 On Mac it may just be "vim" and using exepath() as mentioned
2067 above should be used to get the full path.
Bram Moolenaar08cab962017-03-04 14:37:18 +01002068 On MS-Windows the executable may be called "vim.exe", but the
2069 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02002070 Read-only.
2071
Bram Moolenaar071d4272004-06-13 20:20:40 +00002072 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01002073v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02002074 command (regardless of whether that command actually used a
2075 register). Or for the currently executing normal mode mapping
2076 (use this in custom commands that take a register).
2077 If none is supplied it is the default register '"', unless
2078 'clipboard' contains "unnamed" or "unnamedplus", then it is
2079 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01002080 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002081
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002082 *v:scrollstart* *scrollstart-variable*
2083v:scrollstart String describing the script or function that caused the
2084 screen to scroll up. It's only set when it is empty, thus the
2085 first reason is remembered. It is set to "Unknown" for a
2086 typed command.
2087 This can be used to find out why your script causes the
2088 hit-enter prompt.
2089
Bram Moolenaar071d4272004-06-13 20:20:40 +00002090 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002091v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002092 Read-only.
2093
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002094
Bram Moolenaar446cb832008-06-24 21:56:24 +00002095v:searchforward *v:searchforward* *searchforward-variable*
2096 Search direction: 1 after a forward search, 0 after a
2097 backward search. It is reset to forward when directly setting
2098 the last search pattern, see |quote/|.
2099 Note that the value is restored when returning from a
2100 function. |function-search-undo|.
2101 Read-write.
2102
Bram Moolenaar071d4272004-06-13 20:20:40 +00002103 *v:shell_error* *shell_error-variable*
2104v:shell_error Result of the last shell command. When non-zero, the last
2105 shell command had an error. When zero, there was no problem.
2106 This only works when the shell returns the error code to Vim.
2107 The value -1 is often used when the command could not be
2108 executed. Read-only.
2109 Example: >
2110 :!mv foo bar
2111 :if v:shell_error
2112 : echo 'could not rename "foo" to "bar"!'
2113 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002114< "shell_error" also works, for backwards compatibility, unless
2115 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002116
2117 *v:statusmsg* *statusmsg-variable*
2118v:statusmsg Last given status message. It's allowed to set this variable.
2119
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002120 *v:swapname* *swapname-variable*
2121v:swapname Only valid when executing |SwapExists| autocommands: Name of
2122 the swap file found. Read-only.
2123
2124 *v:swapchoice* *swapchoice-variable*
2125v:swapchoice |SwapExists| autocommands can set this to the selected choice
2126 for handling an existing swap file:
2127 'o' Open read-only
2128 'e' Edit anyway
2129 'r' Recover
2130 'd' Delete swapfile
2131 'q' Quit
2132 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002133 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002134 results in the user being asked, as would happen when there is
2135 no SwapExists autocommand. The default is empty.
2136
Bram Moolenaarb3480382005-12-11 21:33:32 +00002137 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002138v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002139 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002140 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002141 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002142 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002143
Bram Moolenaard823fa92016-08-12 16:29:27 +02002144 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002145v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002146 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002147v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002148 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002149v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002150 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002151v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002152 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002153v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002154 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002155v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002156 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002157v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002158 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002159v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002160 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002161v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002162 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002163v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002164 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002165v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002166
Bram Moolenaar071d4272004-06-13 20:20:40 +00002167 *v:termresponse* *termresponse-variable*
2168v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002169 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaarb4230122019-05-30 18:40:53 +02002170 that starts with ESC [ or CSI, then '>' or '?' and ends in a
2171 'c', with only digits and ';' in between.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002172 When this option is set, the TermResponse autocommand event is
2173 fired, so that you can react to the response from the
2174 terminal.
Bram Moolenaarb4230122019-05-30 18:40:53 +02002175 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
Bram Moolenaar071d4272004-06-13 20:20:40 +00002176 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2177 patch level (since this was introduced in patch 95, it's
2178 always 95 or bigger). Pc is always zero.
2179 {only when compiled with |+termresponse| feature}
2180
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002181 *v:termblinkresp*
2182v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2183 termcap entry. This is used to find out whether the terminal
2184 cursor is blinking. This is used by |term_getcursor()|.
2185
2186 *v:termstyleresp*
2187v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2188 termcap entry. This is used to find out what the shape of the
2189 cursor is. This is used by |term_getcursor()|.
2190
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002191 *v:termrbgresp*
2192v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002193 termcap entry. This is used to find out what the terminal
2194 background color is, see 'background'.
2195
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002196 *v:termrfgresp*
2197v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2198 termcap entry. This is used to find out what the terminal
2199 foreground color is.
2200
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002201 *v:termu7resp*
2202v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2203 termcap entry. This is used to find out what the terminal
2204 does with ambiguous width characters, see 'ambiwidth'.
2205
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002206 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002207v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002208 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002209 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002210
Bram Moolenaar071d4272004-06-13 20:20:40 +00002211 *v:this_session* *this_session-variable*
2212v:this_session Full filename of the last loaded or saved session file. See
2213 |:mksession|. It is allowed to set this variable. When no
2214 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002215 "this_session" also works, for backwards compatibility, unless
2216 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002217
2218 *v:throwpoint* *throwpoint-variable*
2219v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002220 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002221 also |v:exception| and |throw-variables|.
2222 Example: >
2223 :try
2224 : throw "oops"
2225 :catch /.*/
2226 : echo "Exception from" v:throwpoint
2227 :endtry
2228< Output: "Exception from test.vim, line 2"
2229
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002230 *v:true* *true-variable*
2231v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002232 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002233 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002234 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002235< v:true ~
2236 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002237 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002238 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002239v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002240 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002241 |filter()|. Read-only.
2242
Bram Moolenaar071d4272004-06-13 20:20:40 +00002243 *v:version* *version-variable*
2244v:version Version number of Vim: Major version number times 100 plus
Bram Moolenaar9b283522019-06-17 22:19:33 +02002245 minor version number. Version 5.0 is 500. Version 5.1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002246 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002247 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002248 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002249 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002250< Note that patch numbers are specific to the version, thus both
2251 version 5.0 and 5.1 may have a patch 123, but these are
2252 completely different.
2253
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002254 *v:versionlong* *versionlong-variable*
Bram Moolenaar9b283522019-06-17 22:19:33 +02002255v:versionlong Like v:version, but also including the patchlevel in the last
2256 four digits. Version 8.1 with patch 123 has value 8010123.
2257 This can be used like this: >
2258 if v:versionlong >= 8010123
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002259< However, if there are gaps in the list of patches included
2260 this will not work well. This can happen if a recent patch
2261 was included into an older version, e.g. for a security fix.
2262 Use the has() function to make sure the patch is actually
2263 included.
2264
Bram Moolenaar14735512016-03-26 21:00:08 +01002265 *v:vim_did_enter* *vim_did_enter-variable*
2266v:vim_did_enter Zero until most of startup is done. It is set to one just
2267 before |VimEnter| autocommands are triggered.
2268
Bram Moolenaar071d4272004-06-13 20:20:40 +00002269 *v:warningmsg* *warningmsg-variable*
2270v:warningmsg Last given warning message. It's allowed to set this variable.
2271
Bram Moolenaar727c8762010-10-20 19:17:48 +02002272 *v:windowid* *windowid-variable*
2273v:windowid When any X11 based GUI is running or when running in a
2274 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002275 set to the window ID.
2276 When an MS-Windows GUI is running this will be set to the
2277 window handle.
2278 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002279 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2280 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002281
Bram Moolenaar071d4272004-06-13 20:20:40 +00002282==============================================================================
22834. Builtin Functions *functions*
2284
2285See |function-list| for a list grouped by what the function is used for.
2286
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002287(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002288
2289USAGE RESULT DESCRIPTION ~
2290
Bram Moolenaar81edd172016-04-14 13:51:37 +02002291abs({expr}) Float or Number absolute value of {expr}
2292acos({expr}) Float arc cosine of {expr}
Bram Moolenaard8968242019-01-15 22:51:57 +01002293add({object}, {item}) List/Blob append {item} to {object}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002294and({expr}, {expr}) Number bitwise AND
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002295append({lnum}, {text}) Number append {text} below line {lnum}
2296appendbufline({expr}, {lnum}, {text})
2297 Number append {text} below line {lnum}
2298 in buffer {expr}
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002299argc([{winid}]) Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002300argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002301arglistid([{winnr} [, {tabnr}]]) Number argument list id
Bram Moolenaare6e39892018-10-25 12:32:11 +02002302argv({nr} [, {winid}]) String {nr} entry of the argument list
2303argv([-1, {winid}]) List the argument list
Bram Moolenaar65a54642018-04-28 16:56:53 +02002304assert_beeps({cmd}) Number assert {cmd} causes a beep
Bram Moolenaar42205552017-03-18 19:42:22 +01002305assert_equal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002306 Number assert {exp} is equal to {act}
Bram Moolenaard96ff162018-02-18 22:13:29 +01002307assert_equalfile({fname-one}, {fname-two})
Bram Moolenaar65a54642018-04-28 16:56:53 +02002308 Number assert file contents is equal
Bram Moolenaar42205552017-03-18 19:42:22 +01002309assert_exception({error} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002310 Number assert {error} is in v:exception
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002311assert_fails({cmd} [, {error} [, {msg}]])
2312 Number assert {cmd} fails
Bram Moolenaar42205552017-03-18 19:42:22 +01002313assert_false({actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002314 Number assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002315assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002316 Number assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002317assert_match({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002318 Number assert {pat} matches {text}
Bram Moolenaar42205552017-03-18 19:42:22 +01002319assert_notequal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002320 Number assert {exp} is not equal {act}
Bram Moolenaar42205552017-03-18 19:42:22 +01002321assert_notmatch({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002322 Number assert {pat} not matches {text}
2323assert_report({msg}) Number report a test failure
2324assert_true({actual} [, {msg}]) Number assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002325asin({expr}) Float arc sine of {expr}
2326atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002327atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02002328balloon_gettext() String current text in the balloon
Bram Moolenaar74240d32017-12-10 15:26:15 +01002329balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002330balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002331browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002332 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002333browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaar15e248e2019-06-30 20:21:37 +02002334bufadd({name}) Number add a buffer to the buffer list
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002335bufexists({expr}) Number |TRUE| if buffer {expr} exists
2336buflisted({expr}) Number |TRUE| if buffer {expr} is listed
Bram Moolenaar15e248e2019-06-30 20:21:37 +02002337bufload({expr}) Number load buffer {expr} if not loaded yet
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002338bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaara8eee212019-08-24 22:14:58 +02002339bufname([{expr}]) String Name of the buffer {expr}
2340bufnr([{expr} [, {create}]]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002341bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002342bufwinnr({expr}) Number window number of buffer {expr}
2343byte2line({byte}) Number line number at byte count {byte}
2344byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2345byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2346call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002347 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002348ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002349ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002350ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002351ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002352ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002353 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002354ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002355 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002356ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2357ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002358ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002359ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2360ch_logfile({fname} [, {mode}]) none start logging channel activity
2361ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002362 Channel open a channel to {address}
2363ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002364ch_readblob({handle} [, {options}])
2365 Blob read Blob from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002366ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002367 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002368ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002369 any send {expr} over JSON {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002370ch_sendraw({handle}, {expr} [, {options}])
2371 any send {expr} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002372ch_setoptions({handle}, {options})
2373 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002374ch_status({handle} [, {options}])
2375 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002376changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002377char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02002378chdir({dir}) String change current working directory
Bram Moolenaar81edd172016-04-14 13:51:37 +02002379cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002380clearmatches([{win}]) none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002381col({expr}) Number column nr of cursor or mark
2382complete({startcol}, {matches}) none set Insert mode completion
2383complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002384complete_check() Number check for key typed during completion
Bram Moolenaarfd133322019-03-29 12:20:27 +01002385complete_info([{what}]) Dict get current completion information
Bram Moolenaar81edd172016-04-14 13:51:37 +02002386confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002387 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002388copy({expr}) any make a shallow copy of {expr}
2389cos({expr}) Float cosine of {expr}
2390cosh({expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002391count({comp}, {expr} [, {ic} [, {start}]])
2392 Number count how many {expr} are in {comp}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002393cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002394 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002395cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002396 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002397cursor({list}) Number move cursor to position in {list}
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02002398debugbreak({pid}) Number interrupt process being debugged
Bram Moolenaar81edd172016-04-14 13:51:37 +02002399deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2400delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002401deletebufline({expr}, {first} [, {last}])
Bram Moolenaard79a2622018-06-07 18:17:46 +02002402 Number delete lines from buffer {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002403did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002404diff_filler({lnum}) Number diff filler lines about {lnum}
2405diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002406empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002407environ() Dict return environment variables
Bram Moolenaar81edd172016-04-14 13:51:37 +02002408escape({string}, {chars}) String escape {chars} in {string} with '\'
2409eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002410eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002411executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002412execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002413exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002414exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002415extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002416 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002417exp({expr}) Float exponential of {expr}
2418expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002419 any expand special keywords in {expr}
Bram Moolenaar80dad482019-06-09 17:22:31 +02002420expandcmd({expr}) String expand {expr} like with `:edit`
Bram Moolenaar81edd172016-04-14 13:51:37 +02002421feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002422filereadable({file}) Number |TRUE| if {file} is a readable file
2423filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002424filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2425 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002426finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002427 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002428findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002429 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002430float2nr({expr}) Number convert Float {expr} to a Number
2431floor({expr}) Float round {expr} down
2432fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2433fnameescape({fname}) String escape special characters in {fname}
2434fnamemodify({fname}, {mods}) String modify file name
2435foldclosed({lnum}) Number first line of fold at {lnum} if closed
2436foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2437foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002438foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002439foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002440foreground() Number bring the Vim window to the foreground
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002441funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002442 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002443function({name} [, {arglist}] [, {dict}])
2444 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002445garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002446get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2447get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002448get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002449getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002450getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002451 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002452getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002453 any variable {varname} in buffer {expr}
Bram Moolenaar4c313b12019-08-24 22:58:31 +02002454getchangelist([{expr}]) List list of change list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002455getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002456getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002457getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002458getcmdline() String return the current command-line
2459getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002460getcmdtype() String return current command-line type
2461getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002462getcompletion({pat}, {type} [, {filtered}])
2463 List list of cmdline completion matches
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002464getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002465getcwd([{winnr} [, {tabnr}]]) String get the current working directory
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002466getenv({name}) String return environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002467getfontname([{name}]) String name of font being used
2468getfperm({fname}) String file permissions of file {fname}
2469getfsize({fname}) Number size in bytes of file {fname}
2470getftime({fname}) Number last modification time of file
2471getftype({fname}) String description of type of file {fname}
Bram Moolenaara3a12462019-09-07 15:08:38 +02002472getimstatus() Number |TRUE| if the IME status is active
Bram Moolenaar4f505882018-02-10 21:06:32 +01002473getjumplist([{winnr} [, {tabnr}]])
2474 List list of jump list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002475getline({lnum}) String line {lnum} of current buffer
2476getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002477getloclist({nr} [, {what}]) List list of location list items
Bram Moolenaaraff74912019-03-30 18:11:49 +01002478getmatches([{win}]) List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002479getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002480getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaard823fa92016-08-12 16:29:27 +02002481getqflist([{what}]) List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002482getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002483 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002484getregtype([{regname}]) String type of register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002485gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002486gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002487 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002488gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002489 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002490gettagstack([{nr}]) Dict get the tag stack of window {nr}
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02002491getwininfo([{winid}]) List list of info about each window
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002492getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01002493getwinposx() Number X coord in pixels of the Vim window
2494getwinposy() Number Y coord in pixels of the Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002495getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002496 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002497glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002498 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002499glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002500globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002501 String do glob({expr}) for all dirs in {path}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002502has({feature}) Number |TRUE| if feature {feature} supported
2503has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002504haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002505 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar00aa0692019-04-27 20:37:57 +02002506 or |:tcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002507hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002508 Number |TRUE| if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002509histadd({history}, {item}) String add an item to a history
2510histdel({history} [, {item}]) String remove an item from a history
2511histget({history} [, {index}]) String get the item {index} from a history
2512histnr({history}) Number highest index of a history
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002513hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002514hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002515hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002516iconv({expr}, {from}, {to}) String convert encoding of {expr}
2517indent({lnum}) Number indent of line {lnum}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002518index({object}, {expr} [, {start} [, {ic}]])
2519 Number index in {object} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002520input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002521 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002522inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002523 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002524inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002525inputrestore() Number restore typeahead
2526inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002527inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002528insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002529invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002530isdirectory({directory}) Number |TRUE| if {directory} is a directory
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02002531isinf({expr}) Number determine if {expr} is infinity value
2532 (positive or negative)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002533islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002534isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002535items({dict}) List key-value pairs in {dict}
2536job_getchannel({job}) Channel get the channel handle for {job}
Bram Moolenaare1fc5152018-04-21 19:49:08 +02002537job_info([{job}]) Dict get information about {job}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002538job_setoptions({job}, {options}) none set options for {job}
2539job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002540 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002541job_status({job}) String get the status of {job}
2542job_stop({job} [, {how}]) Number stop {job}
2543join({list} [, {sep}]) String join {list} items into one String
2544js_decode({string}) any decode JS style JSON
2545js_encode({expr}) String encode JS style JSON
2546json_decode({string}) any decode JSON
2547json_encode({expr}) String encode JSON
2548keys({dict}) List keys in {dict}
2549len({expr}) Number the length of {expr}
2550libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002551libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02002552line({expr} [, {winid}]) Number line nr of cursor, last line or mark
Bram Moolenaar81edd172016-04-14 13:51:37 +02002553line2byte({lnum}) Number byte count of line {lnum}
2554lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar9d401282019-04-06 13:18:12 +02002555list2str({list} [, {utf8}]) String turn numbers in {list} into a String
Bram Moolenaara3347722019-05-11 21:14:24 +02002556listener_add({callback} [, {buf}])
2557 Number add a callback to listen to changes
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02002558listener_flush([{buf}]) none invoke listener callbacks
Bram Moolenaara3347722019-05-11 21:14:24 +02002559listener_remove({id}) none remove a listener callback
Bram Moolenaar071d4272004-06-13 20:20:40 +00002560localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002561log({expr}) Float natural logarithm (base e) of {expr}
2562log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002563luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002564map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002565maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002566 String or Dict
2567 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002568mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002569 String check for mappings matching {name}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002570match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002571 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002572matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002573 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002574matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002575 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002576matcharg({nr}) List arguments of |:match|
Bram Moolenaaraff74912019-03-30 18:11:49 +01002577matchdelete({id} [, {win}]) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002578matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002579 Number position where {pat} ends in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002580matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002581 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002582matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002583 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002584matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002585 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002586max({expr}) Number maximum value of items in {expr}
2587min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002588mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002589 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002590mode([expr]) String current editing mode
2591mzeval({expr}) any evaluate |MzScheme| expression
2592nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002593nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002594or({expr}, {expr}) Number bitwise OR
Bram Moolenaar81edd172016-04-14 13:51:37 +02002595pathshorten({expr}) String shorten directory names in a path
2596perleval({expr}) any evaluate |Perl| expression
Bram Moolenaar931a2772019-07-04 16:54:54 +02002597popup_atcursor({what}, {options}) Number create popup window near the cursor
Bram Moolenaar589edb32019-09-20 14:38:13 +02002598popup_beval({what}, {options}) Number create popup window for 'ballooneval'
Bram Moolenaar931a2772019-07-04 16:54:54 +02002599popup_clear() none close all popup windows
2600popup_close({id} [, {result}]) none close popup window {id}
2601popup_create({what}, {options}) Number create a popup window
2602popup_dialog({what}, {options}) Number create a popup window used as a dialog
2603popup_filter_menu({id}, {key}) Number filter for a menu popup window
2604popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaare49fbff2019-08-21 22:50:07 +02002605popup_findinfo() Number get window ID of info popup window
2606popup_findpreview() Number get window ID of preview popup window
Bram Moolenaar931a2772019-07-04 16:54:54 +02002607popup_getoptions({id}) Dict get options of popup window {id}
2608popup_getpos({id}) Dict get position of popup window {id}
2609popup_hide({id}) none hide popup menu {id}
2610popup_menu({what}, {options}) Number create a popup window used as a menu
2611popup_move({id}, {options}) none set position of popup window {id}
2612popup_notification({what}, {options})
2613 Number create a notification popup window
2614popup_show({id}) none unhide popup window {id}
2615popup_setoptions({id}, {options})
2616 none set options for popup window {id}
2617popup_settext({id}, {text}) none set the text of popup window {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002618pow({x}, {y}) Float {x} to the power of {y}
2619prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2620printf({fmt}, {expr1}...) String format text
Bram Moolenaarf2732452018-06-03 14:47:35 +02002621prompt_setcallback({buf}, {expr}) none set prompt callback function
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02002622prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2623prompt_setprompt({buf}, {text}) none set prompt text
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002624prop_add({lnum}, {col}, {props}) none add a text property
Bram Moolenaare3d31b02018-12-24 23:07:04 +01002625prop_clear({lnum} [, {lnum-end} [, {props}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002626 none remove all text properties
2627prop_find({props} [, {direction}])
2628 Dict search for a text property
Bram Moolenaar5b69c222019-01-11 14:50:06 +01002629prop_list({lnum} [, {props}) List text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +01002630prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002631 Number remove a text property
2632prop_type_add({name}, {props}) none define a new property type
2633prop_type_change({name}, {props})
2634 none change an existing property type
2635prop_type_delete({name} [, {props}])
2636 none delete a property type
2637prop_type_get([{name} [, {props}])
2638 Dict get property type values
2639prop_type_list([{props}]) List get list of property types
Bram Moolenaare9bd5722019-08-17 19:36:06 +02002640pum_getpos() Dict position and size of pum if visible
Bram Moolenaar446cb832008-06-24 21:56:24 +00002641pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002642pyeval({expr}) any evaluate |Python| expression
2643py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002644pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002645range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002646 List items from {expr} to {max}
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02002647readdir({dir} [, {expr}]) List file names in {dir} selected by {expr}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002648readfile({fname} [, {type} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002649 List get list of lines from file {fname}
Bram Moolenaarf2732452018-06-03 14:47:35 +02002650reg_executing() String get the executing register name
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02002651reg_recording() String get the recording register name
Bram Moolenaar81edd172016-04-14 13:51:37 +02002652reltime([{start} [, {end}]]) List get time value
2653reltimefloat({time}) Float turn the time value into a Float
2654reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002655remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002656 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002657remote_foreground({server}) Number bring Vim server to the foreground
2658remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002659 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002660remote_read({serverid} [, {timeout}])
2661 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002662remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002663 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002664remote_startserver({name}) none become server {name}
Bram Moolenaar39536dd2019-01-29 22:58:21 +01002665remove({list}, {idx} [, {end}]) any/List
2666 remove items {idx}-{end} from {list}
2667remove({blob}, {idx} [, {end}]) Number/Blob
2668 remove bytes {idx}-{end} from {blob}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002669remove({dict}, {key}) any remove entry {key} from {dict}
2670rename({from}, {to}) Number rename (move) file from {from} to {to}
2671repeat({expr}, {count}) String repeat {expr} {count} times
2672resolve({filename}) String get filename a shortcut points to
2673reverse({list}) List reverse {list} in-place
2674round({expr}) Float round off {expr}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01002675rubyeval({expr}) any evaluate |Ruby| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002676screenattr({row}, {col}) Number attribute at screen position
2677screenchar({row}, {col}) Number character at screen position
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002678screenchars({row}, {col}) List List of characters at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002679screencol() Number current cursor column
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02002680screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002681screenrow() Number current cursor row
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002682screenstring({row}, {col}) String characters at screen position
Bram Moolenaar81edd172016-04-14 13:51:37 +02002683search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002684 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002685searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002686 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002687searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002688 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002689searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002690 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002691searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002692 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002693server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002694 Number send reply string
2695serverlist() String get a list of available servers
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002696setbufline({expr}, {lnum}, {text})
2697 Number set line {lnum} to {text} in buffer
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002698 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002699setbufvar({expr}, {varname}, {val})
2700 none set {varname} in buffer {expr} to {val}
2701setcharsearch({dict}) Dict set character search from {dict}
2702setcmdpos({pos}) Number set cursor position in command-line
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002703setenv({name}, {val}) none set environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002704setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2705setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002706setloclist({nr}, {list} [, {action} [, {what}]])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002707 Number modify location list using {list}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002708setmatches({list} [, {win}]) Number restore a list of matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002709setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002710setqflist({list} [, {action} [, {what}]])
Bram Moolenaard823fa92016-08-12 16:29:27 +02002711 Number modify quickfix list using {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002712setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002713settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2714settabwinvar({tabnr}, {winnr}, {varname}, {val})
2715 none set {varname} in window {winnr} in tab
2716 page {tabnr} to {val}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002717settagstack({nr}, {dict} [, {action}])
2718 Number modify tag stack using {dict}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002719setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2720sha256({string}) String SHA256 checksum of {string}
2721shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002722 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002723 command argument
Bram Moolenaarf9514162018-11-22 03:08:29 +01002724shiftwidth([{col}]) Number effective value of 'shiftwidth'
Bram Moolenaar162b7142018-12-21 15:17:36 +01002725sign_define({name} [, {dict}]) Number define or update a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002726sign_define({list}) List define or update a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002727sign_getdefined([{name}]) List get a list of defined signs
2728sign_getplaced([{expr} [, {dict}]])
2729 List get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01002730sign_jump({id}, {group}, {expr})
2731 Number jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01002732sign_place({id}, {group}, {name}, {expr} [, {dict}])
2733 Number place a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002734sign_placelist({list}) List place a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002735sign_undefine([{name}]) Number undefine a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002736sign_undefine({list}) List undefine a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002737sign_unplace({group} [, {dict}])
2738 Number unplace a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002739sign_unplacelist({list}) List unplace a list of signs
Bram Moolenaar81edd172016-04-14 13:51:37 +02002740simplify({filename}) String simplify filename as much as possible
2741sin({expr}) Float sine of {expr}
2742sinh({expr}) Float hyperbolic sine of {expr}
2743sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002744 List sort {list}, using {func} to compare
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02002745sound_clear() none stop playing all sounds
Bram Moolenaar427f5b62019-06-09 13:43:51 +02002746sound_playevent({name} [, {callback}])
2747 Number play an event sound
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02002748sound_playfile({path} [, {callback}])
2749 Number play sound file {path}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02002750sound_stop({id}) none stop playing sound {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002751soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002752spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002753spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002754 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002755split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002756 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002757sqrt({expr}) Float square root of {expr}
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02002758state([{what}]) String current state of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002759str2float({expr}) Float convert String to Float
Bram Moolenaar9d401282019-04-06 13:18:12 +02002760str2list({expr} [, {utf8}]) List convert each character of {expr} to
2761 ASCII/UTF8 value
Bram Moolenaar60a8de22019-09-15 14:33:22 +02002762str2nr({expr} [, {base} [, {quoted}]])
2763 Number convert String to Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002764strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002765strcharpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002766 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002767strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002768strftime({format} [, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002769strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002770stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002771 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002772string({expr}) String String representation of {expr} value
2773strlen({expr}) Number length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002774strpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002775 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002776strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002777 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002778strtrans({expr}) String translate string to make it printable
2779strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002780submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002781 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002782substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002783 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar00f123a2018-08-21 20:28:54 +02002784swapinfo({fname}) Dict information about swap file {fname}
Bram Moolenaar110bd602018-09-16 18:46:59 +02002785swapname({expr}) String swap file of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002786synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2787synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002788 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002789synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002790synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002791synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2792system({expr} [, {input}]) String output of shell command/filter {expr}
2793systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002794tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002795tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002796tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
2797taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002798tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002799tan({expr}) Float tangent of {expr}
2800tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002801tempname() String name for a temporary file
Bram Moolenaard96ff162018-02-18 22:13:29 +01002802term_dumpdiff({filename}, {filename} [, {options}])
2803 Number display difference between two dumps
2804term_dumpload({filename} [, {options}])
2805 Number displaying a screen dump
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01002806term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01002807 none dump terminal window contents
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002808term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002809term_getansicolors({buf}) List get ANSI palette in GUI color mode
Bram Moolenaar45356542017-08-06 17:53:31 +02002810term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002811term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002812term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002813term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002814term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002815term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002816term_getstatus({buf}) String get the status of a terminal
2817term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002818term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002819term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002820term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002821term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
Bram Moolenaard2842ea2019-09-26 23:08:54 +02002822term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002823term_setansicolors({buf}, {colors})
2824 none set ANSI palette in GUI color mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002825term_setkill({buf}, {how}) none set signal to stop job in terminal
Bram Moolenaarb5b75622018-03-09 22:22:21 +01002826term_setrestore({buf}, {command}) none set command to restore terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002827term_setsize({buf}, {rows}, {cols})
2828 none set the size of a terminal
Bram Moolenaar911ead12019-04-21 00:03:35 +02002829term_start({cmd} [, {options}]) Number open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002830term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002831test_alloc_fail({id}, {countdown}, {repeat})
2832 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02002833test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002834test_feedinput({string}) none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02002835test_garbagecollect_now() none free memory right now for testing
Bram Moolenaaradc67142019-06-22 01:40:42 +02002836test_garbagecollect_soon() none free memory soon for testing
Bram Moolenaareda65222019-05-16 20:29:44 +02002837test_getvalue({string}) any get value of an internal variable
Bram Moolenaare0c31f62017-03-01 15:07:05 +01002838test_ignore_error({expr}) none ignore a specific error
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01002839test_null_blob() Blob null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02002840test_null_channel() Channel null value for testing
2841test_null_dict() Dict null value for testing
2842test_null_job() Job null value for testing
2843test_null_list() List null value for testing
2844test_null_partial() Funcref null value for testing
2845test_null_string() String null value for testing
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002846test_option_not_set({name}) none reset flag indicating option was set
2847test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01002848test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaarab186732018-09-14 21:27:06 +02002849test_scrollbar({which}, {value}, {dragging})
2850 none scroll in the GUI for testing
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02002851test_setmouse({row}, {col}) none set the mouse position for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002852test_settime({expr}) none set current time for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02002853timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002854timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002855timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002856 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002857timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002858timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002859tolower({expr}) String the String {expr} switched to lowercase
2860toupper({expr}) String the String {expr} switched to uppercase
2861tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002862 to chars in {tostr}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002863trim({text} [, {mask}]) String trim characters in {mask} from {text}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002864trunc({expr}) Float truncate Float {expr}
2865type({name}) Number type of variable {name}
2866undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002867undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002868uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002869 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002870values({dict}) List values in {dict}
2871virtcol({expr}) Number screen column of cursor or mark
2872visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002873wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar868b7b62019-05-29 21:44:40 +02002874win_execute({id}, {command} [, {silent}])
2875 String execute {command} in window {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002876win_findbuf({bufnr}) List find windows containing {bufnr}
2877win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2878win_gotoid({expr}) Number go to window with ID {expr}
2879win_id2tabwin({expr}) List get tab and window nr from window ID
2880win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01002881win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaard20dcb32019-09-10 21:22:58 +02002882win_splitmove({nr}, {target} [, {options}])
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002883 Number move window {nr} to split of {target}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002884winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002885wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002886winheight({nr}) Number height of window {nr}
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02002887winlayout([{tabnr}]) List layout of windows in tab {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002888winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002889winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002890winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002891winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002892winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002893winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002894wordcount() Dict get byte/char/word statistics
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002895writefile({object}, {fname} [, {flags}])
2896 Number write |Blob| or |List| of lines to file
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002897xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002898
Bram Moolenaar03413f42016-04-12 21:07:15 +02002899
Bram Moolenaar446cb832008-06-24 21:56:24 +00002900abs({expr}) *abs()*
2901 Return the absolute value of {expr}. When {expr} evaluates to
2902 a |Float| abs() returns a |Float|. When {expr} can be
2903 converted to a |Number| abs() returns a |Number|. Otherwise
2904 abs() gives an error message and returns -1.
2905 Examples: >
2906 echo abs(1.456)
2907< 1.456 >
2908 echo abs(-5.456)
2909< 5.456 >
2910 echo abs(-4)
2911< 4
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02002912
2913 Can also be used as a |method|: >
2914 Compute()->abs()
2915
2916< {only available when compiled with the |+float| feature}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002917
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002918
2919acos({expr}) *acos()*
2920 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002921 |Float| in the range of [0, pi].
2922 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002923 [-1, 1].
2924 Examples: >
2925 :echo acos(0)
2926< 1.570796 >
2927 :echo acos(-0.5)
2928< 2.094395
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02002929
2930 Can also be used as a |method|: >
2931 Compute()->acos()
2932
2933< {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002934
2935
Bram Moolenaard8968242019-01-15 22:51:57 +01002936add({object}, {expr}) *add()*
2937 Append the item {expr} to |List| or |Blob| {object}. Returns
2938 the resulting |List| or |Blob|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002939 :let alist = add([1, 2, 3], item)
2940 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002941< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002942 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard8968242019-01-15 22:51:57 +01002943 When {object} is a |Blob| then {expr} must be a number.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002944 Use |insert()| to add an item at another position.
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02002945
Bram Moolenaarac92e252019-08-03 21:58:38 +02002946 Can also be used as a |method|: >
2947 mylist->add(val1)->add(val2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002948
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002949
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002950and({expr}, {expr}) *and()*
2951 Bitwise AND on the two arguments. The arguments are converted
2952 to a number. A List, Dict or Float argument causes an error.
2953 Example: >
2954 :let flag = and(bits, 0x80)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02002955< Can also be used as a |method|: >
2956 :let flag = bits->and(0x80)
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002957
2958
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002959append({lnum}, {text}) *append()*
2960 When {text} is a |List|: Append each item of the |List| as a
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002961 text line below line {lnum} in the current buffer.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002962 Otherwise append {text} as one text line below line {lnum} in
Bram Moolenaar748bf032005-02-02 23:04:36 +00002963 the current buffer.
2964 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002965 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02002966 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002967 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002968 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaarca851592018-06-06 21:04:07 +02002969
Bram Moolenaar25e42232019-08-04 15:04:10 +02002970< Can also be used as a |method| after a List: >
2971 mylist->append(lnum)
2972
2973
Bram Moolenaarca851592018-06-06 21:04:07 +02002974appendbufline({expr}, {lnum}, {text}) *appendbufline()*
2975 Like |append()| but append the text in buffer {expr}.
2976
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002977 This function works only for loaded buffers. First call
2978 |bufload()| if needed.
2979
Bram Moolenaarca851592018-06-06 21:04:07 +02002980 For the use of {expr}, see |bufname()|.
2981
2982 {lnum} is used like with |append()|. Note that using |line()|
2983 would use the current buffer, not the one appending to.
2984 Use "$" to append at the end of the buffer.
2985
2986 On success 0 is returned, on failure 1 is returned.
2987
2988 If {expr} is not a valid buffer or {lnum} is not valid, an
2989 error message is given. Example: >
2990 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002991<
Bram Moolenaar25e42232019-08-04 15:04:10 +02002992 Can also be used as a |method| after a List: >
2993 mylist->appendbufline(buf, lnum)
2994
2995
2996argc([{winid}]) *argc()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002997 The result is the number of files in the argument list. See
2998 |arglist|.
2999 If {winid} is not supplied, the argument list of the current
3000 window is used.
3001 If {winid} is -1, the global argument list is used.
3002 Otherwise {winid} specifies the window of which the argument
3003 list is used: either the window number or the window ID.
3004 Returns -1 if the {winid} argument is invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003005
3006 *argidx()*
3007argidx() The result is the current index in the argument list. 0 is
3008 the first file. argc() - 1 is the last one. See |arglist|.
3009
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003010 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003011arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003012 Return the argument list ID. This is a number which
3013 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02003014 global argument list. See |arglist|.
Bram Moolenaare6e39892018-10-25 12:32:11 +02003015 Returns -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003016
3017 Without arguments use the current window.
3018 With {winnr} only use this window in the current tab page.
3019 With {winnr} and {tabnr} use the window in the specified tab
3020 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02003021 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003022
Bram Moolenaar071d4272004-06-13 20:20:40 +00003023 *argv()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02003024argv([{nr} [, {winid}])
3025 The result is the {nr}th file in the argument list. See
3026 |arglist|. "argv(0)" is the first one. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003027 :let i = 0
3028 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003029 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00003030 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
3031 : let i = i + 1
3032 :endwhile
Bram Moolenaare6e39892018-10-25 12:32:11 +02003033< Without the {nr} argument, or when {nr} is -1, a |List| with
3034 the whole |arglist| is returned.
3035
3036 The {winid} argument specifies the window ID, see |argc()|.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00003037
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01003038
Bram Moolenaar54775062019-07-31 21:07:14 +02003039assert_ functions are documented here: |assert-functions-details|
Bram Moolenaar43345542015-11-29 17:35:35 +01003040
Bram Moolenaar43345542015-11-29 17:35:35 +01003041
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003042asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003043 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003044 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003045 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003046 [-1, 1].
3047 Examples: >
3048 :echo asin(0.8)
3049< 0.927295 >
3050 :echo asin(-0.5)
3051< -0.523599
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003052
3053 Can also be used as a |method|: >
3054 Compute()->asin()
3055<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003056 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003057
3058
Bram Moolenaar446cb832008-06-24 21:56:24 +00003059atan({expr}) *atan()*
3060 Return the principal value of the arc tangent of {expr}, in
3061 the range [-pi/2, +pi/2] radians, as a |Float|.
3062 {expr} must evaluate to a |Float| or a |Number|.
3063 Examples: >
3064 :echo atan(100)
3065< 1.560797 >
3066 :echo atan(-4.01)
3067< -1.326405
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003068
3069 Can also be used as a |method|: >
3070 Compute()->atan()
3071<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003072 {only available when compiled with the |+float| feature}
3073
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003074
3075atan2({expr1}, {expr2}) *atan2()*
3076 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003077 radians, as a |Float| in the range [-pi, pi].
3078 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003079 Examples: >
3080 :echo atan2(-1, 1)
3081< -0.785398 >
3082 :echo atan2(1, -1)
3083< 2.356194
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003084
3085 Can also be used as a |method|: >
3086 Compute()->atan(1)
3087<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003088 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003089
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003090balloon_gettext() *balloon_gettext()*
3091 Return the current text in the balloon. Only for the string,
3092 not used for the List.
3093
Bram Moolenaar246fe032017-11-19 19:56:27 +01003094balloon_show({expr}) *balloon_show()*
3095 Show {expr} inside the balloon. For the GUI {expr} is used as
3096 a string. For a terminal {expr} can be a list, which contains
3097 the lines of the balloon. If {expr} is not a list it will be
3098 split with |balloon_split()|.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003099 If {expr} is an empty string any existing balloon is removed.
Bram Moolenaar246fe032017-11-19 19:56:27 +01003100
Bram Moolenaar214641f2017-03-05 17:04:09 +01003101 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01003102 func GetBalloonContent()
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003103 " ... initiate getting the content
Bram Moolenaar59716a22017-03-01 20:32:44 +01003104 return ''
3105 endfunc
3106 set balloonexpr=GetBalloonContent()
3107
3108 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01003109 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01003110 endfunc
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003111< Can also be used as a |method|: >
3112 GetText()->balloon_show()
Bram Moolenaar59716a22017-03-01 20:32:44 +01003113<
3114 The intended use is that fetching the content of the balloon
3115 is initiated from 'balloonexpr'. It will invoke an
3116 asynchronous method, in which a callback invokes
3117 balloon_show(). The 'balloonexpr' itself can return an
3118 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003119
3120 When showing a balloon is not possible nothing happens, no
3121 error message.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003122 {only available when compiled with the |+balloon_eval| or
3123 |+balloon_eval_term| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003124
Bram Moolenaar246fe032017-11-19 19:56:27 +01003125balloon_split({msg}) *balloon_split()*
3126 Split {msg} into lines to be displayed in a balloon. The
3127 splits are made for the current window size and optimize to
3128 show debugger output.
3129 Returns a |List| with the split lines.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003130 Can also be used as a |method|: >
3131 GetText()->balloon_split()->balloon_show()
3132
3133< {only available when compiled with the |+balloon_eval_term|
Bram Moolenaar669a8282017-11-19 20:13:05 +01003134 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01003135
Bram Moolenaar071d4272004-06-13 20:20:40 +00003136 *browse()*
3137browse({save}, {title}, {initdir}, {default})
3138 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003139 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003140 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003141 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00003142 {title} title for the requester
3143 {initdir} directory to start browsing in
3144 {default} default file name
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003145 An empty string is returned when the "Cancel" button is hit,
3146 something went wrong, or browsing is not possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003147
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003148 *browsedir()*
3149browsedir({title}, {initdir})
3150 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003151 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003152 On systems where a directory browser is not supported a file
3153 browser is used. In that case: select a file in the directory
3154 to be used.
3155 The input fields are:
3156 {title} title for the requester
3157 {initdir} directory to start browsing in
3158 When the "Cancel" button is hit, something went wrong, or
3159 browsing is not possible, an empty string is returned.
3160
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003161bufadd({name}) *bufadd()*
3162 Add a buffer to the buffer list with {name}.
3163 If a buffer for file {name} already exists, return that buffer
3164 number. Otherwise return the buffer number of the newly
3165 created buffer. When {name} is an empty string then a new
3166 buffer is always created.
Bram Moolenaaraad222c2019-09-06 22:46:09 +02003167 The buffer will not have 'buflisted' set and not be loaded
Bram Moolenaar5ca1ac32019-07-04 15:39:28 +02003168 yet. To add some text to the buffer use this: >
3169 let bufnr = bufadd('someName')
3170 call bufload(bufnr)
3171 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003172< Can also be used as a |method|: >
3173 let bufnr = 'somename'->bufadd()
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003174
Bram Moolenaar071d4272004-06-13 20:20:40 +00003175bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003176 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003177 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003178 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01003179 Number zero is the alternate buffer for the current window.
3180
Bram Moolenaar071d4272004-06-13 20:20:40 +00003181 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003182 exactly. The name can be:
3183 - Relative to the current directory.
3184 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003185 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003186 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003187 Unlisted buffers will be found.
3188 Note that help files are listed by their short name in the
3189 output of |:buffers|, but bufexists() requires using their
3190 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003191 bufexists() may report a buffer exists, but to use the name
3192 with a |:buffer| command you may need to use |expand()|. Esp
3193 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003194 Use "bufexists(0)" to test for the existence of an alternate
3195 file name.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003196
3197 Can also be used as a |method|: >
3198 let exists = 'somename'->bufexists()
3199<
3200 Obsolete name: buffer_exists(). *buffer_exists()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003201
3202buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003203 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003204 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003205 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003206
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003207 Can also be used as a |method|: >
3208 let listed = 'somename'->buflisted()
3209
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003210bufload({expr}) *bufload()*
3211 Ensure the buffer {expr} is loaded. When the buffer name
3212 refers to an existing file then the file is read. Otherwise
3213 the buffer will be empty. If the buffer was already loaded
3214 then there is no change.
3215 If there is an existing swap file for the file of the buffer,
3216 there will be no dialog, the buffer will be loaded anyway.
3217 The {expr} argument is used like with |bufexists()|.
3218
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003219 Can also be used as a |method|: >
3220 eval 'somename'->bufload()
3221
Bram Moolenaar071d4272004-06-13 20:20:40 +00003222bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003223 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003224 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003225 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003226
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003227 Can also be used as a |method|: >
3228 let loaded = 'somename'->bufloaded()
3229
Bram Moolenaara8eee212019-08-24 22:14:58 +02003230bufname([{expr}]) *bufname()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003231 The result is the name of a buffer, as it is displayed by the
3232 ":ls" command.
Bram Moolenaara8eee212019-08-24 22:14:58 +02003233 If {expr} is omitted the current buffer is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003234 If {expr} is a Number, that buffer number's name is given.
3235 Number zero is the alternate buffer for the current window.
3236 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02003237 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003238 set and 'cpoptions' is empty. When there is more than one
3239 match an empty string is returned.
3240 "" or "%" can be used for the current buffer, "#" for the
3241 alternate buffer.
3242 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003243 or middle of the buffer name is accepted. If you only want a
3244 full match then put "^" at the start and "$" at the end of the
3245 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003246 Listed buffers are found first. If there is a single match
3247 with a listed buffer, that one is returned. Next unlisted
3248 buffers are searched for.
3249 If the {expr} is a String, but you want to use it as a buffer
3250 number, force it to be a Number by adding zero to it: >
3251 :echo bufname("3" + 0)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003252< Can also be used as a |method|: >
3253 echo bufnr->bufname()
3254
Bram Moolenaar071d4272004-06-13 20:20:40 +00003255< If the buffer doesn't exist, or doesn't have a name, an empty
3256 string is returned. >
3257 bufname("#") alternate buffer name
3258 bufname(3) name of buffer 3
3259 bufname("%") name of current buffer
3260 bufname("file2") name of buffer where "file2" matches.
3261< *buffer_name()*
3262 Obsolete name: buffer_name().
3263
3264 *bufnr()*
Bram Moolenaara8eee212019-08-24 22:14:58 +02003265bufnr([{expr} [, {create}]])
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003266 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00003267 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003268 above.
Bram Moolenaard2842ea2019-09-26 23:08:54 +02003269
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003270 If the buffer doesn't exist, -1 is returned. Or, if the
3271 {create} argument is present and not zero, a new, unlisted,
Bram Moolenaard2842ea2019-09-26 23:08:54 +02003272 buffer is created and its number is returned. Example: >
3273 let newbuf = bufnr('Scratch001', 1)
3274< Using an empty name uses the current buffer. To create a new
3275 buffer with an empty name use |bufadd()|.
3276
Bram Moolenaar071d4272004-06-13 20:20:40 +00003277 bufnr("$") is the last buffer: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02003278 :let last_buffer = bufnr("$")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003279< The result is a Number, which is the highest buffer number
3280 of existing buffers. Note that not all buffers with a smaller
3281 number necessarily exist, because ":bwipeout" may have removed
3282 them. Use bufexists() to test for the existence of a buffer.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003283
3284 Can also be used as a |method|: >
3285 echo bufref->bufnr()
3286<
3287 Obsolete name: buffer_number(). *buffer_number()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003288 *last_buffer_nr()*
3289 Obsolete name for bufnr("$"): last_buffer_nr().
3290
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003291bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02003292 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003293 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003294 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003295 there is no such window, -1 is returned. Example: >
3296
3297 echo "A window containing buffer 1 is " . (bufwinid(1))
3298<
3299 Only deals with the current tab page.
3300
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003301 Can also be used as a |method|: >
3302 FindBuffer()->bufwinid()
3303
Bram Moolenaar071d4272004-06-13 20:20:40 +00003304bufwinnr({expr}) *bufwinnr()*
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003305 Like |bufwinid()| but return the window number instead of the
3306 |window-ID|.
3307 If buffer {expr} doesn't exist or there is no such window, -1
3308 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003309
3310 echo "A window containing buffer 1 is " . (bufwinnr(1))
3311
3312< The number can be used with |CTRL-W_w| and ":wincmd w"
3313 |:wincmd|.
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003314
3315 Can also be used as a |method|: >
3316 FindBuffer()->bufwinnr()
Bram Moolenaar071d4272004-06-13 20:20:40 +00003317
Bram Moolenaar071d4272004-06-13 20:20:40 +00003318byte2line({byte}) *byte2line()*
3319 Return the line number that contains the character at byte
3320 count {byte} in the current buffer. This includes the
3321 end-of-line character, depending on the 'fileformat' option
3322 for the current buffer. The first character has byte count
3323 one.
3324 Also see |line2byte()|, |go| and |:goto|.
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003325
3326 Can also be used as a |method|: >
3327 GetOffset()->byte2line()
3328
3329< {not available when compiled without the |+byte_offset|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003330 feature}
3331
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003332byteidx({expr}, {nr}) *byteidx()*
3333 Return byte index of the {nr}'th character in the string
3334 {expr}. Use zero for the first character, it returns zero.
3335 This function is only useful when there are multibyte
3336 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003337 Composing characters are not counted separately, their byte
3338 length is added to the preceding base character. See
3339 |byteidxcomp()| below for counting composing characters
3340 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003341 Example : >
3342 echo matchstr(str, ".", byteidx(str, 3))
3343< will display the fourth character. Another way to do the
3344 same: >
3345 let s = strpart(str, byteidx(str, 3))
3346 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003347< Also see |strgetchar()| and |strcharpart()|.
3348
3349 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003350 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003351 in bytes is returned.
3352
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003353 Can also be used as a |method|: >
3354 GetName()->byteidx(idx)
3355
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003356byteidxcomp({expr}, {nr}) *byteidxcomp()*
3357 Like byteidx(), except that a composing character is counted
3358 as a separate character. Example: >
3359 let s = 'e' . nr2char(0x301)
3360 echo byteidx(s, 1)
3361 echo byteidxcomp(s, 1)
3362 echo byteidxcomp(s, 2)
3363< The first and third echo result in 3 ('e' plus composing
3364 character is 3 bytes), the second echo results in 1 ('e' is
3365 one byte).
3366 Only works different from byteidx() when 'encoding' is set to
3367 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003368
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003369 Can also be used as a |method|: >
3370 GetName()->byteidxcomp(idx)
3371
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003372call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003373 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003374 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003375 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003376 a:firstline and a:lastline are set to the cursor line.
3377 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003378 {dict} is for functions with the "dict" attribute. It will be
3379 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003380
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003381 Can also be used as a |method|: >
3382 GetFunc()->call([arg, arg], dict)
3383
Bram Moolenaar446cb832008-06-24 21:56:24 +00003384ceil({expr}) *ceil()*
3385 Return the smallest integral value greater than or equal to
3386 {expr} as a |Float| (round up).
3387 {expr} must evaluate to a |Float| or a |Number|.
3388 Examples: >
3389 echo ceil(1.456)
3390< 2.0 >
3391 echo ceil(-5.456)
3392< -5.0 >
3393 echo ceil(4.0)
3394< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003395
3396 Can also be used as a |method|: >
3397 Compute()->ceil()
3398<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003399 {only available when compiled with the |+float| feature}
3400
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003401
Bram Moolenaared997ad2019-07-21 16:42:00 +02003402ch_ functions are documented here: |channel-functions-details|
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003403
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003404
Bram Moolenaar214641f2017-03-05 17:04:09 +01003405changenr() *changenr()*
3406 Return the number of the most recent change. This is the same
3407 number as what is displayed with |:undolist| and can be used
3408 with the |:undo| command.
3409 When a change was made it is the number of that change. After
3410 redo it is the number of the redone change. After undo it is
3411 one less than the number of the undone change.
3412
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003413char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003414 Return number value of the first char in {expr}. Examples: >
3415 char2nr(" ") returns 32
3416 char2nr("ABC") returns 65
3417< When {utf8} is omitted or zero, the current 'encoding' is used.
3418 Example for "utf-8": >
Bram Moolenaar98ef2332018-03-18 14:44:37 +01003419 char2nr("á") returns 225
3420 char2nr("á"[0]) returns 195
Bram Moolenaar214641f2017-03-05 17:04:09 +01003421< With {utf8} set to 1, always treat as utf-8 characters.
3422 A combining character is a separate character.
3423 |nr2char()| does the opposite.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003424 To turn a string into a list of character numbers: >
3425 let str = "ABC"
3426 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
3427< Result: [65, 66, 67]
Bram Moolenaar214641f2017-03-05 17:04:09 +01003428
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003429 Can also be used as a |method|: >
3430 GetChar()->char2nr()
3431
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003432chdir({dir}) *chdir()*
3433 Change the current working directory to {dir}. The scope of
3434 the directory change depends on the directory of the current
3435 window:
3436 - If the current window has a window-local directory
3437 (|:lcd|), then changes the window local directory.
3438 - Otherwise, if the current tabpage has a local
3439 directory (|:tcd|) then changes the tabpage local
3440 directory.
3441 - Otherwise, changes the global directory.
3442 If successful, returns the previous working directory. Pass
3443 this to another chdir() to restore the directory.
3444 On failure, returns an empty string.
3445
3446 Example: >
3447 let save_dir = chdir(newdir)
Bram Moolenaar68e65602019-05-26 21:33:31 +02003448 if save_dir != ""
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003449 " ... do some work
3450 call chdir(save_dir)
3451 endif
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003452
3453< Can also be used as a |method|: >
3454 GetDir()->chdir()
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003455<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003456cindent({lnum}) *cindent()*
3457 Get the amount of indent for line {lnum} according the C
3458 indenting rules, as with 'cindent'.
3459 The indent is counted in spaces, the value of 'tabstop' is
3460 relevant. {lnum} is used just like in |getline()|.
3461 When {lnum} is invalid or Vim was not compiled the |+cindent|
3462 feature, -1 is returned.
3463 See |C-indenting|.
3464
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003465 Can also be used as a |method|: >
3466 GetLnum()->cindent()
3467
Bram Moolenaaraff74912019-03-30 18:11:49 +01003468clearmatches([{win}]) *clearmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01003469 Clears all matches previously defined for the current window
3470 by |matchadd()| and the |:match| commands.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003471 If {win} is specified, use the window with this number or
3472 window ID instead of the current window.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003473
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003474 Can also be used as a |method|: >
3475 GetWin()->clearmatches()
3476<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003477 *col()*
3478col({expr}) The result is a Number, which is the byte index of the column
3479 position given with {expr}. The accepted positions are:
3480 . the cursor position
3481 $ the end of the cursor line (the result is the
3482 number of bytes in the cursor line plus one)
3483 'x position of mark x (if the mark is not set, 0 is
3484 returned)
3485 v In Visual mode: the start of the Visual area (the
3486 cursor is the end). When not in Visual mode
3487 returns the cursor position. Differs from |'<| in
3488 that it's updated right away.
3489 Additionally {expr} can be [lnum, col]: a |List| with the line
3490 and column number. Most useful when the column is "$", to get
3491 the last column of a specific line. When "lnum" or "col" is
3492 out of range then col() returns zero.
3493 To get the line number use |line()|. To get both use
3494 |getpos()|.
3495 For the screen column position use |virtcol()|.
3496 Note that only marks in the current file can be used.
3497 Examples: >
3498 col(".") column of cursor
3499 col("$") length of cursor line plus one
3500 col("'t") column of mark t
3501 col("'" . markname) column of mark markname
3502< The first column is 1. 0 is returned for an error.
3503 For an uppercase mark the column may actually be in another
3504 buffer.
3505 For the cursor position, when 'virtualedit' is active, the
3506 column is one higher if the cursor is after the end of the
3507 line. This can be used to obtain the column in Insert mode: >
3508 :imap <F2> <C-O>:let save_ve = &ve<CR>
3509 \<C-O>:set ve=all<CR>
3510 \<C-O>:echo col(".") . "\n" <Bar>
3511 \let &ve = save_ve<CR>
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003512
3513< Can also be used as a |method|: >
3514 GetPos()->col()
Bram Moolenaar214641f2017-03-05 17:04:09 +01003515<
3516
3517complete({startcol}, {matches}) *complete()* *E785*
3518 Set the matches for Insert mode completion.
3519 Can only be used in Insert mode. You need to use a mapping
3520 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3521 or with an expression mapping.
3522 {startcol} is the byte offset in the line where the completed
3523 text start. The text up to the cursor is the original text
3524 that will be replaced by the matches. Use col('.') for an
3525 empty string. "col('.') - 1" will replace one character by a
3526 match.
3527 {matches} must be a |List|. Each |List| item is one match.
3528 See |complete-items| for the kind of items that are possible.
3529 Note that the after calling this function you need to avoid
3530 inserting anything that would cause completion to stop.
3531 The match can be selected with CTRL-N and CTRL-P as usual with
3532 Insert mode completion. The popup menu will appear if
3533 specified, see |ins-completion-menu|.
3534 Example: >
3535 inoremap <F5> <C-R>=ListMonths()<CR>
3536
3537 func! ListMonths()
3538 call complete(col('.'), ['January', 'February', 'March',
3539 \ 'April', 'May', 'June', 'July', 'August', 'September',
3540 \ 'October', 'November', 'December'])
3541 return ''
3542 endfunc
3543< This isn't very useful, but it shows how it works. Note that
3544 an empty string is returned to avoid a zero being inserted.
3545
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003546 Can also be used as a |method|, the base is passed as the
3547 second argument: >
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003548 GetMatches()->complete(col('.'))
3549
Bram Moolenaar214641f2017-03-05 17:04:09 +01003550complete_add({expr}) *complete_add()*
3551 Add {expr} to the list of matches. Only to be used by the
3552 function specified with the 'completefunc' option.
3553 Returns 0 for failure (empty string or out of memory),
3554 1 when the match was added, 2 when the match was already in
3555 the list.
3556 See |complete-functions| for an explanation of {expr}. It is
3557 the same as one item in the list that 'omnifunc' would return.
3558
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003559 Can also be used as a |method|: >
3560 GetMoreMatches()->complete_add()
3561
Bram Moolenaar214641f2017-03-05 17:04:09 +01003562complete_check() *complete_check()*
3563 Check for a key typed while looking for completion matches.
3564 This is to be used when looking for matches takes some time.
3565 Returns |TRUE| when searching for matches is to be aborted,
3566 zero otherwise.
3567 Only to be used by the function specified with the
3568 'completefunc' option.
3569
Bram Moolenaarfd133322019-03-29 12:20:27 +01003570 *complete_info()*
3571complete_info([{what}])
3572 Returns a Dictionary with information about Insert mode
3573 completion. See |ins-completion|.
3574 The items are:
3575 mode Current completion mode name string.
Bram Moolenaar723dd942019-04-04 13:11:03 +02003576 See |complete_info_mode| for the values.
Bram Moolenaarfd133322019-03-29 12:20:27 +01003577 pum_visible |TRUE| if popup menu is visible.
3578 See |pumvisible()|.
3579 items List of completion matches. Each item is a
3580 dictionary containing the entries "word",
3581 "abbr", "menu", "kind", "info" and "user_data".
3582 See |complete-items|.
3583 selected Selected item index. First index is zero.
3584 Index is -1 if no item is selected (showing
3585 typed text only)
3586 inserted Inserted string. [NOT IMPLEMENT YET]
3587
3588 *complete_info_mode*
3589 mode values are:
3590 "" Not in completion mode
3591 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
3592 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
3593 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
3594 "files" File names |i_CTRL-X_CTRL-F|
3595 "tags" Tags |i_CTRL-X_CTRL-]|
3596 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
3597 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
3598 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
3599 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
3600 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
3601 "function" User defined completion |i_CTRL-X_CTRL-U|
3602 "omni" Omni completion |i_CTRL-X_CTRL-O|
3603 "spell" Spelling suggestions |i_CTRL-X_s|
3604 "eval" |complete()| completion
3605 "unknown" Other internal modes
3606
3607 If the optional {what} list argument is supplied, then only
3608 the items listed in {what} are returned. Unsupported items in
3609 {what} are silently ignored.
3610
Bram Moolenaare9bd5722019-08-17 19:36:06 +02003611 To get the position and size of the popup menu, see
3612 |pum_getpos()|. It's also available in |v:event| during the
3613 |CompleteChanged| event.
3614
Bram Moolenaarfd133322019-03-29 12:20:27 +01003615 Examples: >
3616 " Get all items
3617 call complete_info()
3618 " Get only 'mode'
3619 call complete_info(['mode'])
3620 " Get only 'mode' and 'pum_visible'
3621 call complete_info(['mode', 'pum_visible'])
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003622
3623< Can also be used as a |method|: >
3624 GetItems()->complete_info()
Bram Moolenaarfd133322019-03-29 12:20:27 +01003625<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003626 *confirm()*
3627confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003628 confirm() offers the user a dialog, from which a choice can be
Bram Moolenaar214641f2017-03-05 17:04:09 +01003629 made. It returns the number of the choice. For the first
3630 choice this is 1.
3631 Note: confirm() is only supported when compiled with dialog
3632 support, see |+dialog_con| and |+dialog_gui|.
3633
3634 {msg} is displayed in a |dialog| with {choices} as the
3635 alternatives. When {choices} is missing or empty, "&OK" is
3636 used (and translated).
3637 {msg} is a String, use '\n' to include a newline. Only on
3638 some systems the string is wrapped when it doesn't fit.
3639
3640 {choices} is a String, with the individual choices separated
3641 by '\n', e.g. >
3642 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3643< The letter after the '&' is the shortcut key for that choice.
3644 Thus you can type 'c' to select "Cancel". The shortcut does
3645 not need to be the first letter: >
3646 confirm("file has been modified", "&Save\nSave &All")
3647< For the console, the first letter of each choice is used as
3648 the default shortcut key.
3649
3650 The optional {default} argument is the number of the choice
3651 that is made if the user hits <CR>. Use 1 to make the first
3652 choice the default one. Use 0 to not set a default. If
3653 {default} is omitted, 1 is used.
3654
3655 The optional {type} argument gives the type of dialog. This
3656 is only used for the icon of the GTK, Mac, Motif and Win32
3657 GUI. It can be one of these values: "Error", "Question",
3658 "Info", "Warning" or "Generic". Only the first character is
3659 relevant. When {type} is omitted, "Generic" is used.
3660
3661 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3662 or another valid interrupt key, confirm() returns 0.
3663
3664 An example: >
3665 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3666 :if choice == 0
3667 : echo "make up your mind!"
3668 :elseif choice == 3
3669 : echo "tasteful"
3670 :else
3671 : echo "I prefer bananas myself."
3672 :endif
3673< In a GUI dialog, buttons are used. The layout of the buttons
3674 depends on the 'v' flag in 'guioptions'. If it is included,
3675 the buttons are always put vertically. Otherwise, confirm()
3676 tries to put the buttons in one horizontal line. If they
3677 don't fit, a vertical layout is used anyway. For some systems
3678 the horizontal layout is always used.
3679
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003680 Can also be used as a |method|in: >
3681 BuildMessage()->confirm("&Yes\n&No")
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003682<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003683 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003684copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003685 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003686 When {expr} is a |List| a shallow copy is created. This means
3687 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003688 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003689 changing an item changes the contents of both |Lists|.
3690 A |Dictionary| is copied in a similar way as a |List|.
3691 Also see |deepcopy()|.
Bram Moolenaarac92e252019-08-03 21:58:38 +02003692 Can also be used as a |method|: >
3693 mylist->copy()
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003694
Bram Moolenaar446cb832008-06-24 21:56:24 +00003695cos({expr}) *cos()*
3696 Return the cosine of {expr}, measured in radians, as a |Float|.
3697 {expr} must evaluate to a |Float| or a |Number|.
3698 Examples: >
3699 :echo cos(100)
3700< 0.862319 >
3701 :echo cos(-4.01)
3702< -0.646043
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003703
3704 Can also be used as a |method|: >
3705 Compute()->cos()
3706<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003707 {only available when compiled with the |+float| feature}
3708
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003709
3710cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003711 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003712 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003713 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003714 Examples: >
3715 :echo cosh(0.5)
3716< 1.127626 >
3717 :echo cosh(-0.5)
3718< -1.127626
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003719
3720 Can also be used as a |method|: >
3721 Compute()->cosh()
3722<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003723 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003724
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003725
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003726count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003727 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003728 in |String|, |List| or |Dictionary| {comp}.
3729
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003730 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003731 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003732
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003733 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003734
Bram Moolenaar9966b212017-07-28 16:46:57 +02003735 When {comp} is a string then the number of not overlapping
Bram Moolenaar338e47f2017-12-19 11:55:26 +01003736 occurrences of {expr} is returned. Zero is returned when
3737 {expr} is an empty string.
Bram Moolenaara74e4942019-08-04 17:35:53 +02003738
Bram Moolenaarac92e252019-08-03 21:58:38 +02003739 Can also be used as a |method|: >
3740 mylist->count(val)
Bram Moolenaara74e4942019-08-04 17:35:53 +02003741<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003742 *cscope_connection()*
3743cscope_connection([{num} , {dbpath} [, {prepend}]])
3744 Checks for the existence of a |cscope| connection. If no
3745 parameters are specified, then the function returns:
3746 0, if cscope was not available (not compiled in), or
3747 if there are no cscope connections;
3748 1, if there is at least one cscope connection.
3749
3750 If parameters are specified, then the value of {num}
3751 determines how existence of a cscope connection is checked:
3752
3753 {num} Description of existence check
3754 ----- ------------------------------
3755 0 Same as no parameters (e.g., "cscope_connection()").
3756 1 Ignore {prepend}, and use partial string matches for
3757 {dbpath}.
3758 2 Ignore {prepend}, and use exact string matches for
3759 {dbpath}.
3760 3 Use {prepend}, use partial string matches for both
3761 {dbpath} and {prepend}.
3762 4 Use {prepend}, use exact string matches for both
3763 {dbpath} and {prepend}.
3764
3765 Note: All string comparisons are case sensitive!
3766
3767 Examples. Suppose we had the following (from ":cs show"): >
3768
3769 # pid database name prepend path
3770 0 27664 cscope.out /usr/local
3771<
3772 Invocation Return Val ~
3773 ---------- ---------- >
3774 cscope_connection() 1
3775 cscope_connection(1, "out") 1
3776 cscope_connection(2, "out") 0
3777 cscope_connection(3, "out") 0
3778 cscope_connection(3, "out", "local") 1
3779 cscope_connection(4, "out") 0
3780 cscope_connection(4, "out", "local") 0
3781 cscope_connection(4, "cscope.out", "/usr/local") 1
3782<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003783cursor({lnum}, {col} [, {off}]) *cursor()*
3784cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003785 Positions the cursor at the column (byte count) {col} in the
3786 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003787
Bram Moolenaar0b238792006-03-02 22:49:12 +00003788 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003789 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003790 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003791 [{lnum}, {col}, {off}]
3792 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003793 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003794 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003795
Bram Moolenaar071d4272004-06-13 20:20:40 +00003796 Does not change the jumplist.
3797 If {lnum} is greater than the number of lines in the buffer,
3798 the cursor will be positioned at the last line in the buffer.
3799 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003800 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003801 the cursor will be positioned at the last character in the
3802 line.
3803 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003804 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003805 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003806
Bram Moolenaar0b238792006-03-02 22:49:12 +00003807 When 'virtualedit' is used {off} specifies the offset in
3808 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003809 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003810 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003811
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003812 Can also be used as a |method|: >
3813 GetCursorPos()->cursor()
3814
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02003815debugbreak({pid}) *debugbreak()*
3816 Specifically used to interrupt a program being debugged. It
3817 will cause process {pid} to get a SIGTRAP. Behavior for other
3818 processes is undefined. See |terminal-debugger|.
3819 {only available on MS-Windows}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003820
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003821 Can also be used as a |method|: >
3822 GetPid()->debugbreak()
3823
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003824deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003825 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003826 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003827 When {expr} is a |List| a full copy is created. This means
3828 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003829 copy, and vice versa. When an item is a |List| or
3830 |Dictionary|, a copy for it is made, recursively. Thus
3831 changing an item in the copy does not change the contents of
3832 the original |List|.
3833 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003834 When {noref} is omitted or zero a contained |List| or
3835 |Dictionary| is only copied once. All references point to
3836 this single copy. With {noref} set to 1 every occurrence of a
3837 |List| or |Dictionary| results in a new copy. This also means
3838 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003839 *E724*
3840 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003841 that refers back to a higher level making a deep copy with
3842 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003843 Also see |copy()|.
3844
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003845 Can also be used as a |method|: >
3846 GetObject()->deepcopy()
3847
Bram Moolenaarda440d22016-01-16 21:27:23 +01003848delete({fname} [, {flags}]) *delete()*
3849 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003850 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003851
3852 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003853 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003854
Bram Moolenaarda440d22016-01-16 21:27:23 +01003855 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003856 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003857 Note: on MS-Windows it is not possible to delete a directory
3858 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02003859
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003860 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003861
Bram Moolenaarda440d22016-01-16 21:27:23 +01003862 The result is a Number, which is 0 if the delete operation was
3863 successful and -1 when the deletion failed or partly failed.
3864
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003865 Use |remove()| to delete an item from a |List|.
Bram Moolenaard79a2622018-06-07 18:17:46 +02003866 To delete a line from the buffer use |:delete| or
3867 |deletebufline()|.
3868
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003869 Can also be used as a |method|: >
3870 GetName()->delete()
3871
Bram Moolenaard473c8c2018-08-11 18:00:22 +02003872deletebufline({expr}, {first} [, {last}]) *deletebufline()*
Bram Moolenaard79a2622018-06-07 18:17:46 +02003873 Delete lines {first} to {last} (inclusive) from buffer {expr}.
3874 If {last} is omitted then delete line {first} only.
3875 On success 0 is returned, on failure 1 is returned.
3876
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003877 This function works only for loaded buffers. First call
3878 |bufload()| if needed.
3879
Bram Moolenaard79a2622018-06-07 18:17:46 +02003880 For the use of {expr}, see |bufname()| above.
3881
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003882 {first} and {last} are used like with |getline()|. Note that
Bram Moolenaard79a2622018-06-07 18:17:46 +02003883 when using |line()| this refers to the current buffer. Use "$"
3884 to refer to the last line in buffer {expr}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003885
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003886 Can also be used as a |method|: >
3887 GetBuffer()->deletebufline(1)
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003888<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003889 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003890did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003891 FileType event has been triggered at least once. Can be used
3892 to avoid triggering the FileType event again in the scripts
3893 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02003894 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003895 When editing another file, the counter is reset, thus this
3896 really checks if the FileType event has been triggered for the
3897 current buffer. This allows an autocommand that starts
3898 editing another buffer to set 'filetype' and load a syntax
3899 file.
3900
Bram Moolenaar47136d72004-10-12 20:02:24 +00003901diff_filler({lnum}) *diff_filler()*
3902 Returns the number of filler lines above line {lnum}.
3903 These are the lines that were inserted at this point in
3904 another diff'ed window. These filler lines are shown in the
3905 display but don't exist in the buffer.
3906 {lnum} is used like with |getline()|. Thus "." is the current
3907 line, "'m" mark m, etc.
3908 Returns 0 if the current window is not in diff mode.
3909
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003910 Can also be used as a |method|: >
3911 GetLnum()->diff_filler()
3912
Bram Moolenaar47136d72004-10-12 20:02:24 +00003913diff_hlID({lnum}, {col}) *diff_hlID()*
3914 Returns the highlight ID for diff mode at line {lnum} column
3915 {col} (byte index). When the current line does not have a
3916 diff change zero is returned.
3917 {lnum} is used like with |getline()|. Thus "." is the current
3918 line, "'m" mark m, etc.
3919 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3920 line.
3921 The highlight ID can be used with |synIDattr()| to obtain
3922 syntax information about the highlighting.
3923
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003924 Can also be used as a |method|: >
3925 GetLnum()->diff_hlID(col)
Bram Moolenaar691ddee2019-05-09 14:52:41 +02003926environ() *environ()*
3927 Return all of environment variables as dictionary. You can
3928 check if an environment variable exists like this: >
3929 :echo has_key(environ(), 'HOME')
3930< Note that the variable name may be CamelCase; to ignore case
3931 use this: >
3932 :echo index(keys(environ()), 'HOME', 0, 1) != -1
3933
Bram Moolenaar13065c42005-01-08 16:08:21 +00003934empty({expr}) *empty()*
3935 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003936 - A |List| or |Dictionary| is empty when it does not have any
3937 items.
Bram Moolenaard8968242019-01-15 22:51:57 +01003938 - A |String| is empty when its length is zero.
3939 - A |Number| and |Float| are empty when their value is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003940 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
Bram Moolenaard8968242019-01-15 22:51:57 +01003941 - A |Job| is empty when it failed to start.
3942 - A |Channel| is empty when it is closed.
Bram Moolenaard09091d2019-01-17 16:07:22 +01003943 - A |Blob| is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003944
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003945 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003946 length with zero.
Bram Moolenaara4208962019-08-24 20:50:19 +02003947
Bram Moolenaarac92e252019-08-03 21:58:38 +02003948 Can also be used as a |method|: >
3949 mylist->empty()
Bram Moolenaar13065c42005-01-08 16:08:21 +00003950
Bram Moolenaar071d4272004-06-13 20:20:40 +00003951escape({string}, {chars}) *escape()*
3952 Escape the characters in {chars} that occur in {string} with a
3953 backslash. Example: >
3954 :echo escape('c:\program files\vim', ' \')
3955< results in: >
3956 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003957< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003958
Bram Moolenaara4208962019-08-24 20:50:19 +02003959 Can also be used as a |method|: >
3960 GetText()->escape(' \')
3961<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003962 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003963eval({string}) Evaluate {string} and return the result. Especially useful to
3964 turn the result of |string()| back into the original value.
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01003965 This works for Numbers, Floats, Strings, Blobs and composites
3966 of them. Also works for |Funcref|s that refer to existing
Bram Moolenaar446cb832008-06-24 21:56:24 +00003967 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003968
Bram Moolenaar25e42232019-08-04 15:04:10 +02003969 Can also be used as a |method|: >
3970 argv->join()->eval()
3971
Bram Moolenaar071d4272004-06-13 20:20:40 +00003972eventhandler() *eventhandler()*
3973 Returns 1 when inside an event handler. That is that Vim got
3974 interrupted while waiting for the user to type a character,
3975 e.g., when dropping a file on Vim. This means interactive
3976 commands cannot be used. Otherwise zero is returned.
3977
3978executable({expr}) *executable()*
3979 This function checks if an executable with the name {expr}
3980 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003981 arguments.
3982 executable() uses the value of $PATH and/or the normal
3983 searchpath for programs. *PATHEXT*
3984 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3985 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar58b85342016-08-14 19:54:54 +02003986 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3987 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003988 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar58b85342016-08-14 19:54:54 +02003989 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003990 Unix shell, then the name is also tried without adding an
3991 extension.
3992 On MS-DOS and MS-Windows it only checks if the file exists and
3993 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003994 On MS-Windows an executable in the same directory as Vim is
3995 always found. Since this directory is added to $PATH it
3996 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003997 The result is a Number:
3998 1 exists
3999 0 does not exist
4000 -1 not implemented on this system
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02004001 |exepath()| can be used to get the full path of an executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004002
Bram Moolenaara4208962019-08-24 20:50:19 +02004003 Can also be used as a |method|: >
4004 GetCommand()->executable()
4005
Bram Moolenaar79815f12016-07-09 17:07:29 +02004006execute({command} [, {silent}]) *execute()*
4007 Execute an Ex command or commands and return the output as a
4008 string.
4009 {command} can be a string or a List. In case of a List the
4010 lines are executed one by one.
4011 This is equivalent to: >
4012 redir => var
4013 {command}
4014 redir END
4015<
4016 The optional {silent} argument can have these values:
4017 "" no `:silent` used
4018 "silent" `:silent` used
4019 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01004020 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02004021 `:redir`, error messages are dropped. When using an external
4022 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02004023 *E930*
4024 It is not possible to use `:redir` anywhere in {command}.
4025
4026 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02004027 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02004028
Bram Moolenaar868b7b62019-05-29 21:44:40 +02004029< To execute a command in another window than the current one
4030 use `win_execute()`.
4031
4032 When used recursively the output of the recursive call is not
Bram Moolenaar79815f12016-07-09 17:07:29 +02004033 included in the output of the higher level call.
4034
Bram Moolenaara4208962019-08-24 20:50:19 +02004035 Can also be used as a |method|: >
4036 GetCommand()->execute()
4037
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004038exepath({expr}) *exepath()*
4039 If {expr} is an executable and is either an absolute path, a
4040 relative path or found in $PATH, return the full path.
4041 Note that the current directory is used when {expr} starts
4042 with "./", which may be a problem for Vim: >
4043 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02004044< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004045 an empty string is returned.
4046
Bram Moolenaara4208962019-08-24 20:50:19 +02004047 Can also be used as a |method|: >
4048 GetCommand()->exepath()
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004049<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004050 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02004051exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
4052 zero otherwise.
4053
4054 For checking for a supported feature use |has()|.
4055 For checking if a file exists use |filereadable()|.
4056
4057 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004058 &option-name Vim option (only checks if it exists,
4059 not if it really works)
4060 +option-name Vim option that works.
4061 $ENVNAME environment variable (could also be
4062 done by comparing with an empty
4063 string)
4064 *funcname built-in function (see |functions|)
4065 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02004066 |user-functions|). Also works for a
4067 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004068 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02004069 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004070 for |curly-braces-names|, |Dictionary|
4071 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00004072 that evaluating an index may cause an
4073 error message for an invalid
4074 expression. E.g.: >
4075 :let l = [1, 2, 3]
4076 :echo exists("l[5]")
4077< 0 >
4078 :echo exists("l[xx]")
4079< E121: Undefined variable: xx
4080 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00004081 :cmdname Ex command: built-in command, user
4082 command or command modifier |:command|.
4083 Returns:
4084 1 for match with start of a command
4085 2 full match with a command
4086 3 matches several user commands
4087 To check for a supported command
4088 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00004089 :2match The |:2match| command.
4090 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004091 #event autocommand defined for this event
4092 #event#pattern autocommand defined for this event and
4093 pattern (the pattern is taken
4094 literally and compared to the
4095 autocommand patterns character by
4096 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004097 #group autocommand group exists
4098 #group#event autocommand defined for this group and
4099 event.
4100 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004101 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004102 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004103 ##event autocommand for this event is
4104 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004105
4106 Examples: >
4107 exists("&shortname")
4108 exists("$HOSTNAME")
4109 exists("*strftime")
4110 exists("*s:MyFunc")
4111 exists("bufcount")
4112 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004113 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004114 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004115 exists("#filetypeindent")
4116 exists("#filetypeindent#FileType")
4117 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004118 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004119< There must be no space between the symbol (&/$/*/#) and the
4120 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004121 There must be no extra characters after the name, although in
4122 a few cases this is ignored. That may become more strict in
4123 the future, thus don't count on it!
4124 Working example: >
4125 exists(":make")
4126< NOT working example: >
4127 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00004128
4129< Note that the argument must be a string, not the name of the
4130 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004131 exists(bufcount)
4132< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00004133 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004134
Bram Moolenaara4208962019-08-24 20:50:19 +02004135 Can also be used as a |method|: >
4136 Varname()->exists()
4137
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004138exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004139 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004140 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004141 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004142 Examples: >
4143 :echo exp(2)
4144< 7.389056 >
4145 :echo exp(-1)
4146< 0.367879
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004147
4148 Can also be used as a |method|: >
4149 Compute()->exp()
4150<
Bram Moolenaardb84e452010-08-15 13:50:43 +02004151 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004152
4153
Bram Moolenaar84f72352012-03-11 15:57:40 +01004154expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004155 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004156 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004157
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004158 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004159 Otherwise the result is a String and when there are several
4160 matches, they are separated by <NL> characters. [Note: in
4161 version 5.0 a space was used, which caused problems when a
4162 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004163
Bram Moolenaar58b85342016-08-14 19:54:54 +02004164 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02004165 for a non-existing file is not included, unless {expr} does
4166 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004167
4168 When {expr} starts with '%', '#' or '<', the expansion is done
4169 like for the |cmdline-special| variables with their associated
4170 modifiers. Here is a short overview:
4171
4172 % current file name
4173 # alternate file name
4174 #n alternate file name n
4175 <cfile> file name under the cursor
4176 <afile> autocmd file name
4177 <abuf> autocmd buffer number (as a String!)
4178 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01004179 <sfile> sourced script file or function name
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02004180 <slnum> sourced script line number or function
4181 line number
4182 <sflnum> script file line number, also when in
4183 a function
Bram Moolenaar071d4272004-06-13 20:20:40 +00004184 <cword> word under the cursor
4185 <cWORD> WORD under the cursor
4186 <client> the {clientid} of the last received
4187 message |server2client()|
4188 Modifiers:
4189 :p expand to full path
4190 :h head (last path component removed)
4191 :t tail (last path component only)
4192 :r root (one extension removed)
4193 :e extension only
4194
4195 Example: >
4196 :let &tags = expand("%:p:h") . "/tags"
4197< Note that when expanding a string that starts with '%', '#' or
4198 '<', any following text is ignored. This does NOT work: >
4199 :let doesntwork = expand("%:h.bak")
4200< Use this: >
4201 :let doeswork = expand("%:h") . ".bak"
4202< Also note that expanding "<cfile>" and others only returns the
4203 referenced file name without further expansion. If "<cfile>"
4204 is "~/.cshrc", you need to do another expand() to have the
4205 "~/" expanded into the path of the home directory: >
4206 :echo expand(expand("<cfile>"))
4207<
4208 There cannot be white space between the variables and the
4209 following modifier. The |fnamemodify()| function can be used
4210 to modify normal file names.
4211
4212 When using '%' or '#', and the current or alternate file name
4213 is not defined, an empty string is used. Using "%:p" in a
4214 buffer with no name, results in the current directory, with a
4215 '/' added.
4216
4217 When {expr} does not start with '%', '#' or '<', it is
4218 expanded like a file name is expanded on the command line.
4219 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004220 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01004221 Names for non-existing files are included. The "**" item can
4222 be used to search in a directory tree. For example, to find
4223 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00004224 :echo expand("**/README")
4225<
Bram Moolenaar647e24b2019-03-17 16:39:46 +01004226 expand() can also be used to expand variables and environment
Bram Moolenaar071d4272004-06-13 20:20:40 +00004227 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004228 slow, because a shell may be used to do the expansion. See
4229 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004230 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004231 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004232 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4233 "$FOOBAR".
4234
4235 See |glob()| for finding existing files. See |system()| for
4236 getting the raw output of an external command.
4237
Bram Moolenaara4208962019-08-24 20:50:19 +02004238 Can also be used as a |method|: >
4239 Getpattern()->expand()
4240
Bram Moolenaar80dad482019-06-09 17:22:31 +02004241expandcmd({expr}) *expandcmd()*
4242 Expand special items in {expr} like what is done for an Ex
4243 command such as `:edit`. This expands special keywords, like
4244 with |expand()|, and environment variables, anywhere in
Bram Moolenaar96f45c02019-10-26 19:53:45 +02004245 {expr}. "~user" and "~/path" are only expanded at the start.
4246 Returns the expanded string. Example: >
Bram Moolenaar80dad482019-06-09 17:22:31 +02004247 :echo expandcmd('make %<.o')
Bram Moolenaara4208962019-08-24 20:50:19 +02004248
4249< Can also be used as a |method|: >
4250 GetCommand()->expandcmd()
Bram Moolenaar80dad482019-06-09 17:22:31 +02004251<
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004252extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004253 {expr1} and {expr2} must be both |Lists| or both
4254 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004255
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004256 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004257 If {expr3} is given insert the items of {expr2} before item
4258 {expr3} in {expr1}. When {expr3} is zero insert before the
4259 first item. When {expr3} is equal to len({expr1}) then
4260 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004261 Examples: >
4262 :echo sort(extend(mylist, [7, 5]))
4263 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00004264< When {expr1} is the same List as {expr2} then the number of
4265 items copied is equal to the original length of the List.
4266 E.g., when {expr3} is 1 you get N new copies of the first item
4267 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02004268 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004269 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004270 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004271<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004272 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004273 Add all entries from {expr2} to {expr1}.
4274 If a key exists in both {expr1} and {expr2} then {expr3} is
4275 used to decide what to do:
4276 {expr3} = "keep": keep the value of {expr1}
4277 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004278 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004279 When {expr3} is omitted then "force" is assumed.
4280
4281 {expr1} is changed when {expr2} is not empty. If necessary
4282 make a copy of {expr1} first.
4283 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02004284 When {expr1} is locked and {expr2} is not empty the operation
4285 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004286 Returns {expr1}.
4287
Bram Moolenaarac92e252019-08-03 21:58:38 +02004288 Can also be used as a |method|: >
4289 mylist->extend(otherlist)
4290
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004291
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004292feedkeys({string} [, {mode}]) *feedkeys()*
4293 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004294 come from a mapping or were typed by the user.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004295
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004296 By default the string is added to the end of the typeahead
4297 buffer, thus if a mapping is still being executed the
4298 characters come after them. Use the 'i' flag to insert before
4299 other characters, they will be executed next, before any
4300 characters from a mapping.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004301
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004302 The function does not wait for processing of keys contained in
4303 {string}.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004304
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004305 To include special keys into {string}, use double-quotes
4306 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00004307 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004308 feedkeys('\<CR>') pushes 5 characters.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02004309 A special code that might be useful is <Ignore>, it exits the
4310 wait for a character without doing anything. *<Ignore>*
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004311
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004312 {mode} is a String, which can contain these character flags:
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004313 'm' Remap keys. This is default. If {mode} is absent,
4314 keys are remapped.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004315 'n' Do not remap keys.
4316 't' Handle keys as if typed; otherwise they are handled as
4317 if coming from a mapping. This matters for undo,
4318 opening folds, etc.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01004319 'L' Lowlevel input. Only works for Unix or when using the
4320 GUI. Keys are used as if they were coming from the
4321 terminal. Other flags are not used. *E980*
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004322 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01004323 'x' Execute commands until typeahead is empty. This is
4324 similar to using ":normal!". You can call feedkeys()
4325 several times without 'x' and then one time with 'x'
4326 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02004327 typeahead. Note that when Vim ends in Insert mode it
4328 will behave as if <Esc> is typed, to avoid getting
4329 stuck, waiting for a character to be typed before the
4330 script continues.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004331 Note that if you manage to call feedkeys() while
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004332 executing commands, thus calling it recursively, then
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004333 all typehead will be consumed by the last call.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004334 '!' When used with 'x' will not end Insert mode. Can be
4335 used in a test when a timer is set to exit Insert mode
4336 a little later. Useful for testing CursorHoldI.
4337
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004338 Return value is always 0.
4339
Bram Moolenaara4208962019-08-24 20:50:19 +02004340 Can also be used as a |method|: >
4341 GetInput()->feedkeys()
4342
Bram Moolenaar071d4272004-06-13 20:20:40 +00004343filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004344 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004345 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004346 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00004347 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004348 If you don't care about the file being readable you can use
4349 |glob()|.
Bram Moolenaar25e42232019-08-04 15:04:10 +02004350 {file} is used as-is, you may want to expand wildcards first: >
4351 echo filereadable('~/.vimrc')
4352 0
4353 echo filereadable(expand('~/.vimrc'))
4354 1
Bram Moolenaara4208962019-08-24 20:50:19 +02004355
4356< Can also be used as a |method|: >
4357 GetName()->filereadable()
Bram Moolenaar25e42232019-08-04 15:04:10 +02004358< *file_readable()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004359 Obsolete name: file_readable().
4360
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004361
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004362filewritable({file}) *filewritable()*
4363 The result is a Number, which is 1 when a file with the
4364 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00004365 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004366 directory, and we can write to it, the result is 2.
4367
Bram Moolenaara4208962019-08-24 20:50:19 +02004368 Can also be used as a |method|: >
4369 GetName()->filewriteable()
4370
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004371
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004372filter({expr1}, {expr2}) *filter()*
4373 {expr1} must be a |List| or a |Dictionary|.
4374 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004375 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004376 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004377
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004378 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004379 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004380 of the current item and for a |List| |v:key| has the index of
4381 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004382 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004383 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004384< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004385 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004386< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004387 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004388< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004389
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004390 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004391 used as an expression again. Often it is good to use a
4392 |literal-string| to avoid having to double backslashes.
4393
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004394 If {expr2} is a |Funcref| it must take two arguments:
4395 1. the key or the index of the current item.
4396 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004397 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004398 Example that keeps the odd items of a list: >
4399 func Odd(idx, val)
4400 return a:idx % 2 == 1
4401 endfunc
4402 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004403< It is shorter when using a |lambda|: >
4404 call filter(myList, {idx, val -> idx * val <= 42})
4405< If you do not use "val" you can leave it out: >
4406 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004407<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004408 The operation is done in-place. If you want a |List| or
4409 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00004410 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004411
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004412< Returns {expr1}, the |List| or |Dictionary| that was filtered.
4413 When an error is encountered while evaluating {expr2} no
4414 further items in {expr1} are processed. When {expr2} is a
4415 Funcref errors inside a function are ignored, unless it was
4416 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004417
Bram Moolenaarac92e252019-08-03 21:58:38 +02004418 Can also be used as a |method|: >
4419 mylist->filter(expr2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004420
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004421finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00004422 Find directory {name} in {path}. Supports both downwards and
4423 upwards recursive directory searches. See |file-searching|
4424 for the syntax of {path}.
4425 Returns the path of the first found match. When the found
4426 directory is below the current directory a relative path is
4427 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004428 If {path} is omitted or empty then 'path' is used.
4429 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004430 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00004431 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004432 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004433 {only available when compiled with the |+file_in_path|
4434 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004435
Bram Moolenaara4208962019-08-24 20:50:19 +02004436 Can also be used as a |method|: >
4437 GetName()->finddir()
4438
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004439findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004440 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004441 Uses 'suffixesadd'.
4442 Example: >
4443 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004444< Searches from the directory of the current file upwards until
4445 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004446
Bram Moolenaara4208962019-08-24 20:50:19 +02004447 Can also be used as a |method|: >
4448 GetName()->findfile()
4449
Bram Moolenaar446cb832008-06-24 21:56:24 +00004450float2nr({expr}) *float2nr()*
4451 Convert {expr} to a Number by omitting the part after the
4452 decimal point.
4453 {expr} must evaluate to a |Float| or a Number.
4454 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004455 result is truncated to 0x7fffffff or -0x7fffffff (or when
4456 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004457 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004458 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00004459 Examples: >
4460 echo float2nr(3.95)
4461< 3 >
4462 echo float2nr(-23.45)
4463< -23 >
4464 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004465< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004466 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004467< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004468 echo float2nr(1.0e-100)
4469< 0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004470
4471 Can also be used as a |method|: >
4472 Compute()->float2nr()
4473<
Bram Moolenaar446cb832008-06-24 21:56:24 +00004474 {only available when compiled with the |+float| feature}
4475
4476
4477floor({expr}) *floor()*
4478 Return the largest integral value less than or equal to
4479 {expr} as a |Float| (round down).
4480 {expr} must evaluate to a |Float| or a |Number|.
4481 Examples: >
4482 echo floor(1.856)
4483< 1.0 >
4484 echo floor(-5.456)
4485< -6.0 >
4486 echo floor(4.0)
4487< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004488
4489 Can also be used as a |method|: >
4490 Compute()->floor()
4491<
Bram Moolenaar446cb832008-06-24 21:56:24 +00004492 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004493
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004494
4495fmod({expr1}, {expr2}) *fmod()*
4496 Return the remainder of {expr1} / {expr2}, even if the
4497 division is not representable. Returns {expr1} - i * {expr2}
4498 for some integer i such that if {expr2} is non-zero, the
4499 result has the same sign as {expr1} and magnitude less than
4500 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004501 returned is zero. The value returned is a |Float|.
4502 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004503 Examples: >
4504 :echo fmod(12.33, 1.22)
4505< 0.13 >
4506 :echo fmod(-12.33, 1.22)
4507< -0.13
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004508
4509 Can also be used as a |method|: >
4510 Compute()->fmod(1.22)
4511<
Bram Moolenaardb84e452010-08-15 13:50:43 +02004512 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004513
4514
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004515fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004516 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004517 characters that have a special meaning, such as '%' and '|'
4518 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004519 For most systems the characters escaped are
4520 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
4521 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004522 A leading '+' and '>' is also escaped (special after |:edit|
4523 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004524 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004525 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004526 :exe "edit " . fnameescape(fname)
4527< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004528 edit \+some\ str\%nge\|name
Bram Moolenaara4208962019-08-24 20:50:19 +02004529<
4530 Can also be used as a |method|: >
4531 GetName()->fnameescape()
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004532
Bram Moolenaar071d4272004-06-13 20:20:40 +00004533fnamemodify({fname}, {mods}) *fnamemodify()*
4534 Modify file name {fname} according to {mods}. {mods} is a
4535 string of characters like it is used for file names on the
4536 command line. See |filename-modifiers|.
4537 Example: >
4538 :echo fnamemodify("main.c", ":p:h")
4539< results in: >
4540 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00004541< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00004542 |expand()| first then.
4543
Bram Moolenaara4208962019-08-24 20:50:19 +02004544 Can also be used as a |method|: >
4545 GetName()->fnamemodify(':p:h')
4546
Bram Moolenaar071d4272004-06-13 20:20:40 +00004547foldclosed({lnum}) *foldclosed()*
4548 The result is a Number. If the line {lnum} is in a closed
4549 fold, the result is the number of the first line in that fold.
4550 If the line {lnum} is not in a closed fold, -1 is returned.
4551
Bram Moolenaara4208962019-08-24 20:50:19 +02004552 Can also be used as a |method|: >
4553 GetLnum()->foldclosed()
4554
Bram Moolenaar071d4272004-06-13 20:20:40 +00004555foldclosedend({lnum}) *foldclosedend()*
4556 The result is a Number. If the line {lnum} is in a closed
4557 fold, the result is the number of the last line in that fold.
4558 If the line {lnum} is not in a closed fold, -1 is returned.
4559
Bram Moolenaara4208962019-08-24 20:50:19 +02004560 Can also be used as a |method|: >
4561 GetLnum()->foldclosedend()
4562
Bram Moolenaar071d4272004-06-13 20:20:40 +00004563foldlevel({lnum}) *foldlevel()*
4564 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004565 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004566 returned. If there is no fold at line {lnum}, zero is
4567 returned. It doesn't matter if the folds are open or closed.
4568 When used while updating folds (from 'foldexpr') -1 is
4569 returned for lines where folds are still to be updated and the
4570 foldlevel is unknown. As a special case the level of the
4571 previous line is usually available.
4572
Bram Moolenaara4208962019-08-24 20:50:19 +02004573 Can also be used as a |method|: >
4574 GetLnum()->foldlevel()
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004575<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004576 *foldtext()*
4577foldtext() Returns a String, to be displayed for a closed fold. This is
4578 the default function used for the 'foldtext' option and should
4579 only be called from evaluating 'foldtext'. It uses the
4580 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4581 The returned string looks like this: >
4582 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004583< The number of leading dashes depends on the foldlevel. The
4584 "45" is the number of lines in the fold. "abcdef" is the text
4585 in the first non-blank line of the fold. Leading white space,
4586 "//" or "/*" and the text from the 'foldmarker' and
4587 'commentstring' options is removed.
4588 When used to draw the actual foldtext, the rest of the line
4589 will be filled with the fold char from the 'fillchars'
4590 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004591 {not available when compiled without the |+folding| feature}
4592
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004593foldtextresult({lnum}) *foldtextresult()*
4594 Returns the text that is displayed for the closed fold at line
4595 {lnum}. Evaluates 'foldtext' in the appropriate context.
4596 When there is no closed fold at {lnum} an empty string is
4597 returned.
4598 {lnum} is used like with |getline()|. Thus "." is the current
4599 line, "'m" mark m, etc.
4600 Useful when exporting folded text, e.g., to HTML.
4601 {not available when compiled without the |+folding| feature}
4602
Bram Moolenaara4208962019-08-24 20:50:19 +02004603
4604 Can also be used as a |method|: >
4605 GetLnum()->foldtextresult()
4606<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004607 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004608foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004609 a client to a Vim server. |remote_send()|
4610 On Win32 systems this might not work, the OS does not always
4611 allow a window to bring itself to the foreground. Use
4612 |remote_foreground()| instead.
4613 {only in the Win32, Athena, Motif and GTK GUI versions and the
4614 Win32 console version}
4615
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004616 *funcref()*
4617funcref({name} [, {arglist}] [, {dict}])
4618 Just like |function()|, but the returned Funcref will lookup
4619 the function by reference, not by name. This matters when the
4620 function {name} is redefined later.
4621
4622 Unlike |function()|, {name} must be an existing user function.
4623 Also for autoloaded functions. {name} cannot be a builtin
4624 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004625
Bram Moolenaara4208962019-08-24 20:50:19 +02004626 Can also be used as a |method|: >
4627 GetFuncname()->funcref([arg])
4628<
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004629 *function()* *E700* *E922* *E923*
4630function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004631 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004632 {name} can be the name of a user defined function or an
4633 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004634
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004635 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004636 partial the dict stored in it will be used and the {dict}
4637 argument is not allowed. E.g.: >
4638 let FuncWithArg = function(dict.Func, [arg])
4639 let Broken = function(dict.Func, [arg], dict)
4640<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004641 When using the Funcref the function will be found by {name},
4642 also when it was redefined later. Use |funcref()| to keep the
4643 same function.
4644
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004645 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004646 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004647 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004648
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004649 The arguments are passed to the function in front of other
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004650 arguments, but after any argument from |method|. Example: >
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004651 func Callback(arg1, arg2, name)
4652 ...
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004653 let Partial = function('Callback', ['one', 'two'])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004654 ...
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004655 call Partial('name')
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004656< Invokes the function as with: >
4657 call Callback('one', 'two', 'name')
4658
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004659< With a |method|: >
4660 func Callback(one, two, three)
4661 ...
4662 let Partial = function('Callback', ['two'])
4663 ...
4664 eval 'one'->Partial('three')
4665< Invokes the function as with: >
4666 call Callback('one', 'two', 'three')
4667
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004668< The function() call can be nested to add more arguments to the
4669 Funcref. The extra arguments are appended to the list of
4670 arguments. Example: >
4671 func Callback(arg1, arg2, name)
4672 ...
4673 let Func = function('Callback', ['one'])
4674 let Func2 = function(Func, ['two'])
4675 ...
4676 call Func2('name')
4677< Invokes the function as with: >
4678 call Callback('one', 'two', 'name')
4679
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004680< The Dictionary is only useful when calling a "dict" function.
4681 In that case the {dict} is passed in as "self". Example: >
4682 function Callback() dict
4683 echo "called for " . self.name
4684 endfunction
4685 ...
4686 let context = {"name": "example"}
4687 let Func = function('Callback', context)
4688 ...
4689 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004690< The use of function() is not needed when there are no extra
4691 arguments, these two are equivalent: >
4692 let Func = function('Callback', context)
4693 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004694
4695< The argument list and the Dictionary can be combined: >
4696 function Callback(arg1, count) dict
4697 ...
4698 let context = {"name": "example"}
4699 let Func = function('Callback', ['one'], context)
4700 ...
4701 call Func(500)
4702< Invokes the function as with: >
4703 call context.Callback('one', 500)
Bram Moolenaara4208962019-08-24 20:50:19 +02004704<
4705 Can also be used as a |method|: >
4706 GetFuncname()->function([arg])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004707
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004708
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004709garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004710 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
4711 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004712
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004713 There is hardly ever a need to invoke this function, as it is
4714 automatically done when Vim runs out of memory or is waiting
4715 for the user to press a key after 'updatetime'. Items without
4716 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004717 This is useful if you have deleted a very big |List| and/or
4718 |Dictionary| with circular references in a script that runs
4719 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004720
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004721 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00004722 collection will also be done when exiting Vim, if it wasn't
4723 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00004724
Bram Moolenaar574860b2016-05-24 17:33:34 +02004725 The garbage collection is not done immediately but only when
4726 it's safe to perform. This is when waiting for the user to
4727 type a character. To force garbage collection immediately use
4728 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004729
Bram Moolenaar677ee682005-01-27 14:41:15 +00004730get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004731 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004732 available return {default}. Return zero when {default} is
4733 omitted.
Bram Moolenaarac92e252019-08-03 21:58:38 +02004734 Can also be used as a |method|: >
4735 mylist->get(idx)
Bram Moolenaard8968242019-01-15 22:51:57 +01004736get({blob}, {idx} [, {default}])
4737 Get byte {idx} from |Blob| {blob}. When this byte is not
4738 available return {default}. Return -1 when {default} is
4739 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004740get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004741 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004742 item is not available return {default}. Return zero when
Bram Moolenaar54775062019-07-31 21:07:14 +02004743 {default} is omitted. Useful example: >
4744 let val = get(g:, 'var_name', 'default')
4745< This gets the value of g:var_name if it exists, and uses
4746 'default' when it does not exist.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02004747get({func}, {what})
4748 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02004749 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01004750 "name" The function name
4751 "func" The function
4752 "dict" The dictionary
4753 "args" The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004754
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004755 *getbufinfo()*
4756getbufinfo([{expr}])
4757getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02004758 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004759
4760 Without an argument information about all the buffers is
4761 returned.
4762
4763 When the argument is a Dictionary only the buffers matching
4764 the specified criteria are returned. The following keys can
4765 be specified in {dict}:
4766 buflisted include only listed buffers.
4767 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01004768 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004769
4770 Otherwise, {expr} specifies a particular buffer to return
4771 information for. For the use of {expr}, see |bufname()|
4772 above. If the buffer is found the returned List has one item.
4773 Otherwise the result is an empty list.
4774
4775 Each returned List item is a dictionary with the following
4776 entries:
Bram Moolenaar33928832016-08-18 21:22:04 +02004777 bufnr buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004778 changed TRUE if the buffer is modified.
4779 changedtick number of changes made to the buffer.
4780 hidden TRUE if the buffer is hidden.
Bram Moolenaar52410572019-10-27 05:12:45 +01004781 lastused timestamp in seconds, like
4782 |localtime()|, when the buffer was
4783 last used.
4784 {only with the |+viminfo| feature}
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004785 listed TRUE if the buffer is listed.
4786 lnum current line number in buffer.
4787 loaded TRUE if the buffer is loaded.
4788 name full path to the file in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004789 signs list of signs placed in the buffer.
4790 Each list item is a dictionary with
4791 the following fields:
4792 id sign identifier
4793 lnum line number
4794 name sign name
Bram Moolenaar30567352016-08-27 21:25:44 +02004795 variables a reference to the dictionary with
4796 buffer-local variables.
4797 windows list of |window-ID|s that display this
4798 buffer
Bram Moolenaar5ca1ac32019-07-04 15:39:28 +02004799 popups list of popup |window-ID|s that
4800 display this buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004801
4802 Examples: >
4803 for buf in getbufinfo()
4804 echo buf.name
4805 endfor
4806 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02004807 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004808 ....
4809 endif
4810 endfor
4811<
Bram Moolenaar30567352016-08-27 21:25:44 +02004812 To get buffer-local options use: >
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004813 getbufvar({bufnr}, '&option_name')
Bram Moolenaar30567352016-08-27 21:25:44 +02004814
4815<
Bram Moolenaar45360022005-07-21 21:08:21 +00004816 *getbufline()*
4817getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004818 Return a |List| with the lines starting from {lnum} to {end}
4819 (inclusive) in the buffer {expr}. If {end} is omitted, a
4820 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004821
4822 For the use of {expr}, see |bufname()| above.
4823
Bram Moolenaar661b1822005-07-28 22:36:45 +00004824 For {lnum} and {end} "$" can be used for the last line of the
4825 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00004826
4827 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004828 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004829
4830 When {end} is greater than the number of lines in the buffer,
4831 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004832 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00004833 returned.
4834
Bram Moolenaar661b1822005-07-28 22:36:45 +00004835 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004836 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004837
4838 Example: >
4839 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004840
Bram Moolenaar4c313b12019-08-24 22:58:31 +02004841< Can also be used as a |method|: >
4842 GetBufnr()->getbufline(lnum)
4843
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004844getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004845 The result is the value of option or local buffer variable
4846 {varname} in buffer {expr}. Note that the name without "b:"
4847 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004848 When {varname} is empty returns a dictionary with all the
4849 buffer-local variables.
Bram Moolenaar30567352016-08-27 21:25:44 +02004850 When {varname} is equal to "&" returns a dictionary with all
4851 the buffer-local options.
4852 Otherwise, when {varname} starts with "&" returns the value of
4853 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004854 This also works for a global or buffer-local option, but it
4855 doesn't work for a global variable, window-local variable or
4856 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004857 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004858 When the buffer or variable doesn't exist {def} or an empty
4859 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004860 Examples: >
4861 :let bufmodified = getbufvar(1, "&mod")
4862 :echo "todo myvar = " . getbufvar("todo", "myvar")
Bram Moolenaar4c313b12019-08-24 22:58:31 +02004863
4864< Can also be used as a |method|: >
4865 GetBufnr()->getbufvar(varname)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004866<
Bram Moolenaar4c313b12019-08-24 22:58:31 +02004867getchangelist([{expr}]) *getchangelist()*
Bram Moolenaar07ad8162018-02-13 13:59:59 +01004868 Returns the |changelist| for the buffer {expr}. For the use
4869 of {expr}, see |bufname()| above. If buffer {expr} doesn't
4870 exist, an empty list is returned.
4871
4872 The returned list contains two entries: a list with the change
4873 locations and the current position in the list. Each
4874 entry in the change list is a dictionary with the following
4875 entries:
4876 col column number
4877 coladd column offset for 'virtualedit'
4878 lnum line number
4879 If buffer {expr} is the current buffer, then the current
4880 position refers to the position in the list. For other
4881 buffers, it is set to the length of the list.
4882
Bram Moolenaar4c313b12019-08-24 22:58:31 +02004883 Can also be used as a |method|: >
4884 GetBufnr()->getchangelist()
4885
Bram Moolenaar071d4272004-06-13 20:20:40 +00004886getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00004887 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004888 If [expr] is omitted, wait until a character is available.
4889 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004890 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004891 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00004892 not consumed. Return zero if no character available.
4893
Bram Moolenaardfb18412013-12-11 18:53:29 +01004894 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02004895 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00004896 result is a number. Use nr2char() to convert it to a String.
4897 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02004898 For a special key it's a String with a sequence of bytes
4899 starting with 0x80 (decimal: 128). This is the same value as
4900 the String "\<Key>", e.g., "\<Left>". The returned value is
4901 also a String when a modifier (shift, control, alt) was used
4902 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004903
Bram Moolenaar822ff862014-06-12 21:46:14 +02004904 When [expr] is 0 and Esc is typed, there will be a short delay
4905 while Vim waits to see if this is the start of an escape
4906 sequence.
4907
Bram Moolenaardfb18412013-12-11 18:53:29 +01004908 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004909 one-byte character it is the character itself as a number.
4910 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004911
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004912 Use getcharmod() to obtain any additional modifiers.
4913
Bram Moolenaar219b8702006-11-01 14:32:36 +00004914 When the user clicks a mouse button, the mouse event will be
4915 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02004916 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
4917 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00004918 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00004919 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00004920 exe v:mouse_win . "wincmd w"
4921 exe v:mouse_lnum
4922 exe "normal " . v:mouse_col . "|"
4923 endif
4924<
Bram Moolenaar690afe12017-01-28 18:34:47 +01004925 When using bracketed paste only the first character is
4926 returned, the rest of the pasted text is dropped.
4927 |xterm-bracketed-paste|.
4928
Bram Moolenaar071d4272004-06-13 20:20:40 +00004929 There is no prompt, you will somehow have to make clear to the
4930 user that a character has to be typed.
4931 There is no mapping for the character.
4932 Key codes are replaced, thus when the user presses the <Del>
4933 key you get the code for the <Del> key, not the raw character
4934 sequence. Examples: >
4935 getchar() == "\<Del>"
4936 getchar() == "\<S-Left>"
4937< This example redefines "f" to ignore case: >
4938 :nmap f :call FindChar()<CR>
4939 :function FindChar()
4940 : let c = nr2char(getchar())
4941 : while col('.') < col('$') - 1
4942 : normal l
4943 : if getline('.')[col('.') - 1] ==? c
4944 : break
4945 : endif
4946 : endwhile
4947 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01004948<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004949 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01004950 |<CursorHold>|. Often you will want to ignore this and get
4951 another character: >
4952 :function GetKey()
4953 : let c = getchar()
4954 : while c == "\<CursorHold>"
4955 : let c = getchar()
4956 : endwhile
4957 : return c
4958 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00004959
4960getcharmod() *getcharmod()*
4961 The result is a Number which is the state of the modifiers for
4962 the last obtained character with getchar() or in another way.
4963 These values are added together:
4964 2 shift
4965 4 control
4966 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004967 16 meta (when it's different from ALT)
4968 32 mouse double click
4969 64 mouse triple click
4970 96 mouse quadruple click (== 32 + 64)
4971 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004972 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02004973 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004974 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004975
Bram Moolenaardbd24b52015-08-11 14:26:19 +02004976getcharsearch() *getcharsearch()*
4977 Return the current character search information as a {dict}
4978 with the following entries:
4979
4980 char character previously used for a character
4981 search (|t|, |f|, |T|, or |F|); empty string
4982 if no character search has been performed
4983 forward direction of character search; 1 for forward,
4984 0 for backward
4985 until type of character search; 1 for a |t| or |T|
4986 character search, 0 for an |f| or |F|
4987 character search
4988
4989 This can be useful to always have |;| and |,| search
4990 forward/backward regardless of the direction of the previous
4991 character search: >
4992 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4993 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4994< Also see |setcharsearch()|.
4995
Bram Moolenaar071d4272004-06-13 20:20:40 +00004996getcmdline() *getcmdline()*
4997 Return the current command-line. Only works when the command
4998 line is being edited, thus requires use of |c_CTRL-\_e| or
4999 |c_CTRL-R_=|.
5000 Example: >
5001 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005002< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005003 Returns an empty string when entering a password or using
5004 |inputsecret()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005005
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005006getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005007 Return the position of the cursor in the command line as a
5008 byte count. The first column is 1.
5009 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02005010 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5011 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005012 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
5013
5014getcmdtype() *getcmdtype()*
5015 Return the current command-line type. Possible return values
5016 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00005017 : normal Ex command
5018 > debug mode command |debug-mode|
5019 / forward search command
5020 ? backward search command
5021 @ |input()| command
5022 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02005023 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005024 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02005025 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5026 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005027 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005028
Bram Moolenaarfb539272014-08-22 19:21:47 +02005029getcmdwintype() *getcmdwintype()*
5030 Return the current |command-line-window| type. Possible return
5031 values are the same as |getcmdtype()|. Returns an empty string
5032 when not in the command-line window.
5033
Bram Moolenaare9d58a62016-08-13 15:07:41 +02005034getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005035 Return a list of command-line completion matches. {type}
5036 specifies what for. The following completion types are
5037 supported:
5038
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02005039 arglist file names in argument list
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005040 augroup autocmd groups
5041 buffer buffer names
5042 behave :behave suboptions
5043 color color schemes
5044 command Ex command (and arguments)
5045 compiler compilers
5046 cscope |:cscope| suboptions
5047 dir directory names
5048 environment environment variable names
5049 event autocommand events
5050 expression Vim expression
5051 file file and directory names
5052 file_in_path file and directory names in |'path'|
5053 filetype filetype names |'filetype'|
5054 function function name
5055 help help subjects
5056 highlight highlight groups
5057 history :history suboptions
5058 locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02005059 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005060 mapping mapping name
5061 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02005062 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005063 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02005064 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005065 shellcmd Shell command
5066 sign |:sign| suboptions
5067 syntax syntax file names |'syntax'|
5068 syntime |:syntime| suboptions
5069 tag tags
5070 tag_listfiles tags, file names
5071 user user names
5072 var user variables
5073
5074 If {pat} is an empty string, then all the matches are returned.
5075 Otherwise only items matching {pat} are returned. See
5076 |wildcards| for the use of special characters in {pat}.
5077
Bram Moolenaare9d58a62016-08-13 15:07:41 +02005078 If the optional {filtered} flag is set to 1, then 'wildignore'
5079 is applied to filter the results. Otherwise all the matches
5080 are returned. The 'wildignorecase' option always applies.
5081
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005082 If there are no matches, an empty list is returned. An
5083 invalid value for {type} produces an error.
5084
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005085 Can also be used as a |method|: >
5086 GetPattern()->getcompletion('color')
5087<
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005088 *getcurpos()*
5089getcurpos() Get the position of the cursor. This is like getpos('.'), but
5090 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01005091 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005092 The "curswant" number is the preferred column when moving the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005093 cursor vertically. Also see |getpos()|.
5094
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005095 This can be used to save and restore the cursor position: >
5096 let save_cursor = getcurpos()
5097 MoveTheCursorAround
5098 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005099< Note that this only works within the window. See
5100 |winrestview()| for restoring more state.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005101 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01005102getcwd([{winnr} [, {tabnr}]])
5103 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00005104 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005105
5106 With {winnr} return the local current directory of this window
Bram Moolenaar54591292018-02-09 20:53:59 +01005107 in the current tab page. {winnr} can be the window number or
5108 the |window-ID|.
5109 If {winnr} is -1 return the name of the global working
5110 directory. See also |haslocaldir()|.
5111
Bram Moolenaarc9703302016-01-17 21:49:33 +01005112 With {winnr} and {tabnr} return the local current directory of
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005113 the window in the specified tab page. If {winnr} is -1 return
5114 the working directory of the tabpage.
5115 If {winnr} is zero use the current window, if {tabnr} is zero
5116 use the current tabpage.
5117 Without any arguments, return the working directory of the
5118 current window.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005119 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005120
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005121 Examples: >
5122 " Get the working directory of the current window
5123 :echo getcwd()
5124 :echo getcwd(0)
5125 :echo getcwd(0, 0)
5126 " Get the working directory of window 3 in tabpage 2
5127 :echo getcwd(3, 2)
5128 " Get the global working directory
5129 :echo getcwd(-1)
5130 " Get the working directory of tabpage 3
5131 :echo getcwd(-1, 3)
5132 " Get the working directory of current tabpage
5133 :echo getcwd(-1, 0)
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005134
5135< Can also be used as a |method|: >
5136 GetWinnr()->getcwd()
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005137<
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005138getenv({name}) *getenv()*
5139 Return the value of environment variable {name}.
5140 When the variable does not exist |v:null| is returned. That
Bram Moolenaar54775062019-07-31 21:07:14 +02005141 is different from a variable set to an empty string, although
5142 some systems interpret the empty value as the variable being
5143 deleted. See also |expr-env|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005144
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005145 Can also be used as a |method|: >
5146 GetVarname()->getenv()
5147
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005148getfontname([{name}]) *getfontname()*
5149 Without an argument returns the name of the normal font being
5150 used. Like what is used for the Normal highlight group
5151 |hl-Normal|.
5152 With an argument a check is done whether {name} is a valid
5153 font name. If not then an empty string is returned.
5154 Otherwise the actual font name is returned, or {name} if the
5155 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00005156 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005157 gvimrc file. Use the |GUIEnter| autocommand to use this
5158 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01005159 Note that the GTK GUI accepts any font name, thus checking for
5160 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005161
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005162getfperm({fname}) *getfperm()*
5163 The result is a String, which is the read, write, and execute
5164 permissions of the given file {fname}.
5165 If {fname} does not exist or its directory cannot be read, an
5166 empty string is returned.
5167 The result is of the form "rwxrwxrwx", where each group of
5168 "rwx" flags represent, in turn, the permissions of the owner
5169 of the file, the group the file belongs to, and other users.
5170 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02005171 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005172 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02005173 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005174< This will hopefully (from a security point of view) display
5175 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005176
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005177 Can also be used as a |method|: >
5178 GetFilename()->getfperm()
5179<
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02005180 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01005181
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005182getfsize({fname}) *getfsize()*
5183 The result is a Number, which is the size in bytes of the
5184 given file {fname}.
5185 If {fname} is a directory, 0 is returned.
5186 If the file {fname} can't be found, -1 is returned.
5187 If the size of {fname} is too big to fit in a Number then -2
5188 is returned.
5189
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005190 Can also be used as a |method|: >
5191 GetFilename()->getfsize()
5192
Bram Moolenaar071d4272004-06-13 20:20:40 +00005193getftime({fname}) *getftime()*
5194 The result is a Number, which is the last modification time of
5195 the given file {fname}. The value is measured as seconds
5196 since 1st Jan 1970, and may be passed to strftime(). See also
5197 |localtime()| and |strftime()|.
5198 If the file {fname} can't be found -1 is returned.
5199
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005200 Can also be used as a |method|: >
5201 GetFilename()->getftime()
5202
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005203getftype({fname}) *getftype()*
5204 The result is a String, which is a description of the kind of
5205 file of the given file {fname}.
5206 If {fname} does not exist an empty string is returned.
5207 Here is a table over different kinds of files and their
5208 results:
5209 Normal file "file"
5210 Directory "dir"
5211 Symbolic link "link"
5212 Block device "bdev"
5213 Character device "cdev"
5214 Socket "socket"
5215 FIFO "fifo"
5216 All other "other"
5217 Example: >
5218 getftype("/home")
5219< Note that a type such as "link" will only be returned on
5220 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01005221 "file" are returned. On MS-Windows a symbolic link to a
5222 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005223
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005224 Can also be used as a |method|: >
5225 GetFilename()->getftype()
5226
Bram Moolenaara3a12462019-09-07 15:08:38 +02005227getimstatus() *getimstatus()*
5228 The result is a Number, which is |TRUE| when the IME status is
5229 active.
5230 See 'imstatusfunc'.
5231
Bram Moolenaard96ff162018-02-18 22:13:29 +01005232getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Bram Moolenaar4f505882018-02-10 21:06:32 +01005233 Returns the |jumplist| for the specified window.
5234
5235 Without arguments use the current window.
5236 With {winnr} only use this window in the current tab page.
5237 {winnr} can also be a |window-ID|.
5238 With {winnr} and {tabnr} use the window in the specified tab
5239 page.
5240
5241 The returned list contains two entries: a list with the jump
5242 locations and the last used jump position number in the list.
5243 Each entry in the jump location list is a dictionary with
5244 the following entries:
5245 bufnr buffer number
5246 col column number
5247 coladd column offset for 'virtualedit'
5248 filename filename if available
5249 lnum line number
5250
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005251 Can also be used as a |method|: >
5252 GetWinnr()->getjumplist()
5253
5254< *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005255getline({lnum} [, {end}])
5256 Without {end} the result is a String, which is line {lnum}
5257 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005258 getline(1)
5259< When {lnum} is a String that doesn't start with a
Bram Moolenaarf2732452018-06-03 14:47:35 +02005260 digit, |line()| is called to translate the String into a Number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005261 To get the line under the cursor: >
5262 getline(".")
5263< When {lnum} is smaller than 1 or bigger than the number of
5264 lines in the buffer, an empty string is returned.
5265
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005266 When {end} is given the result is a |List| where each item is
5267 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005268 including line {end}.
5269 {end} is used in the same way as {lnum}.
5270 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005271 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005272 Example: >
5273 :let start = line('.')
5274 :let end = search("^$") - 1
5275 :let lines = getline(start, end)
5276
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005277< Can also be used as a |method|: >
5278 ComputeLnum()->getline()
5279
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005280< To get lines from another buffer see |getbufline()|
5281
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005282getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005283 Returns a list with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02005284 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02005285 When {nr} is zero the current window is used.
5286
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005287 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00005288 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005289 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005290
Bram Moolenaard823fa92016-08-12 16:29:27 +02005291 If the optional {what} dictionary argument is supplied, then
5292 returns the items listed in {what} as a dictionary. Refer to
5293 |getqflist()| for the supported items in {what}.
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005294
5295 In addition to the items supported by |getqflist()| in {what},
5296 the following item is supported by |getloclist()|:
5297
Bram Moolenaar68e65602019-05-26 21:33:31 +02005298 filewinid id of the window used to display files
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005299 from the location list. This field is
5300 applicable only when called from a
5301 location list window. See
5302 |location-list-file-window| for more
5303 details.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005304
Bram Moolenaaraff74912019-03-30 18:11:49 +01005305getmatches([{win}]) *getmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01005306 Returns a |List| with all matches previously defined for the
5307 current window by |matchadd()| and the |:match| commands.
5308 |getmatches()| is useful in combination with |setmatches()|,
5309 as |setmatches()| can restore a list of matches saved by
5310 |getmatches()|.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005311 Example: >
5312 :echo getmatches()
5313< [{'group': 'MyGroup1', 'pattern': 'TODO',
5314 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5315 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5316 :let m = getmatches()
5317 :call clearmatches()
5318 :echo getmatches()
5319< [] >
5320 :call setmatches(m)
5321 :echo getmatches()
5322< [{'group': 'MyGroup1', 'pattern': 'TODO',
5323 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5324 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5325 :unlet m
5326<
Bram Moolenaar822ff862014-06-12 21:46:14 +02005327 *getpid()*
5328getpid() Return a Number which is the process ID of the Vim process.
5329 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar58b85342016-08-14 19:54:54 +02005330 exits. On MS-DOS it's always zero.
Bram Moolenaar822ff862014-06-12 21:46:14 +02005331
5332 *getpos()*
5333getpos({expr}) Get the position for {expr}. For possible values of {expr}
5334 see |line()|. For getting the cursor position see
5335 |getcurpos()|.
5336 The result is a |List| with four numbers:
5337 [bufnum, lnum, col, off]
5338 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
5339 is the buffer number of the mark.
5340 "lnum" and "col" are the position in the buffer. The first
5341 column is 1.
5342 The "off" number is zero, unless 'virtualedit' is used. Then
5343 it is the offset in screen columns from the start of the
5344 character. E.g., a position within a <Tab> or after the last
5345 character.
5346 Note that for '< and '> Visual mode matters: when it is "V"
5347 (visual line mode) the column of '< is zero and the column of
5348 '> is a large number.
5349 This can be used to save and restore the position of a mark: >
5350 let save_a_mark = getpos("'a")
5351 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01005352 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02005353< Also see |getcurpos()| and |setpos()|.
5354
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005355 Can also be used as a |method|: >
5356 GetMark()->getpos()
5357
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005358
Bram Moolenaard823fa92016-08-12 16:29:27 +02005359getqflist([{what}]) *getqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005360 Returns a list with all the current quickfix errors. Each
5361 list item is a dictionary with these entries:
5362 bufnr number of buffer that has the file name, use
5363 bufname() to get the name
Bram Moolenaard76ce852018-05-01 15:02:04 +02005364 module module name
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005365 lnum line number in the buffer (first line is 1)
5366 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005367 vcol |TRUE|: "col" is visual column
5368 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005369 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005370 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005371 text description of the error
5372 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005373 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005374
Bram Moolenaar7571d552016-08-18 22:54:46 +02005375 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005376 returned. Quickfix list entries with non-existing buffer
5377 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00005378
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005379 Useful application: Find pattern matches in multiple files and
5380 do something with them: >
5381 :vimgrep /theword/jg *.c
5382 :for d in getqflist()
5383 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
5384 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02005385<
5386 If the optional {what} dictionary argument is supplied, then
5387 returns only the items listed in {what} as a dictionary. The
5388 following string items are supported in {what}:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005389 changedtick get the total number of changes made
Bram Moolenaar15142e22018-04-30 22:19:58 +02005390 to the list |quickfix-changedtick|
5391 context get the |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02005392 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01005393 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02005394 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005395 id get information for the quickfix list with
5396 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01005397 current list or the list specified by "nr"
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005398 idx index of the current entry in the quickfix
5399 list specified by 'id' or 'nr'.
5400 See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02005401 items quickfix list entries
Bram Moolenaar15142e22018-04-30 22:19:58 +02005402 lines parse a list of lines using 'efm' and return
5403 the resulting entries. Only a |List| type is
5404 accepted. The current quickfix list is not
5405 modified. See |quickfix-parse|.
Bram Moolenaar890680c2016-09-27 21:28:56 +02005406 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02005407 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02005408 the last quickfix list
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005409 qfbufnr number of the buffer displayed in the quickfix
5410 window. Returns 0 if the quickfix buffer is
5411 not present. See |quickfix-buffer|.
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02005412 size number of entries in the quickfix list
Bram Moolenaar15142e22018-04-30 22:19:58 +02005413 title get the list title |quickfix-title|
Bram Moolenaar74240d32017-12-10 15:26:15 +01005414 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02005415 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01005416 Non-string items in {what} are ignored. To get the value of a
Bram Moolenaara6d48492017-12-12 22:45:31 +01005417 particular item, set it to zero.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005418 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005419 If both "nr" and a non-zero "id" are specified, then the list
5420 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005421 To get the number of lists in the quickfix stack, set "nr" to
5422 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02005423 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005424 When "lines" is specified, all the other items except "efm"
5425 are ignored. The returned dictionary contains the entry
5426 "items" with the list of entries.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005427
Bram Moolenaard823fa92016-08-12 16:29:27 +02005428 The returned dictionary contains the following entries:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005429 changedtick total number of changes made to the
5430 list |quickfix-changedtick|
Bram Moolenaar15142e22018-04-30 22:19:58 +02005431 context quickfix list context. See |quickfix-context|
Bram Moolenaara6d48492017-12-12 22:45:31 +01005432 If not present, set to "".
5433 id quickfix list ID |quickfix-ID|. If not
5434 present, set to 0.
5435 idx index of the current entry in the list. If not
5436 present, set to 0.
5437 items quickfix list entries. If not present, set to
5438 an empty list.
5439 nr quickfix list number. If not present, set to 0
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005440 qfbufnr number of the buffer displayed in the quickfix
5441 window. If not present, set to 0.
Bram Moolenaara6d48492017-12-12 22:45:31 +01005442 size number of entries in the quickfix list. If not
5443 present, set to 0.
5444 title quickfix list title text. If not present, set
5445 to "".
Bram Moolenaar74240d32017-12-10 15:26:15 +01005446 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02005447
Bram Moolenaar15142e22018-04-30 22:19:58 +02005448 Examples (See also |getqflist-examples|): >
Bram Moolenaard823fa92016-08-12 16:29:27 +02005449 :echo getqflist({'all': 1})
5450 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02005451 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02005452<
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005453getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005454 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005455 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005456 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005457< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005458
5459 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005460 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005461 getreg('=', 1) returns the expression itself, so that it can
5462 be restored with |setreg()|. For other registers the extra
5463 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005464
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005465 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005466 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005467 about zero bytes possibly present inside register: without
5468 third argument both NLs and zero bytes are represented as NLs
5469 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005470 When the register was not set an empty list is returned.
5471
Bram Moolenaar071d4272004-06-13 20:20:40 +00005472 If {regname} is not specified, |v:register| is used.
5473
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005474 Can also be used as a |method|: >
5475 GetRegname()->getreg()
5476
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005477
Bram Moolenaar071d4272004-06-13 20:20:40 +00005478getregtype([{regname}]) *getregtype()*
5479 The result is a String, which is type of register {regname}.
5480 The value will be one of:
5481 "v" for |characterwise| text
5482 "V" for |linewise| text
5483 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01005484 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00005485 <CTRL-V> is one character with value 0x16.
5486 If {regname} is not specified, |v:register| is used.
5487
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005488 Can also be used as a |method|: >
5489 GetRegname()->getregtype()
5490
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005491gettabinfo([{arg}]) *gettabinfo()*
5492 If {arg} is not specified, then information about all the tab
5493 pages is returned as a List. Each List item is a Dictionary.
5494 Otherwise, {arg} specifies the tab page number and information
5495 about that one is returned. If the tab page does not exist an
5496 empty List is returned.
5497
5498 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02005499 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02005500 variables a reference to the dictionary with
5501 tabpage-local variables
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005502 windows List of |window-ID|s in the tab page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005503
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005504 Can also be used as a |method|: >
5505 GetTabnr()->gettabinfo()
5506
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005507gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005508 Get the value of a tab-local variable {varname} in tab page
5509 {tabnr}. |t:var|
5510 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02005511 When {varname} is empty a dictionary with all tab-local
5512 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005513 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005514 When the tab or variable doesn't exist {def} or an empty
5515 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005516
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005517 Can also be used as a |method|: >
5518 GetTabnr()->gettabvar(varname)
5519
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005520gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005521 Get the value of window-local variable {varname} in window
5522 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005523 When {varname} is empty a dictionary with all window-local
5524 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02005525 When {varname} is equal to "&" get the values of all
5526 window-local options in a Dictionary.
5527 Otherwise, when {varname} starts with "&" get the value of a
5528 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005529 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005530 Tabs are numbered starting with one. For the current tabpage
5531 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005532 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005533 When {winnr} is zero the current window is used.
5534 This also works for a global option, buffer-local option and
5535 window-local option, but it doesn't work for a global variable
5536 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005537 When the tab, window or variable doesn't exist {def} or an
5538 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005539 Examples: >
5540 :let list_is_on = gettabwinvar(1, 2, '&list')
5541 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005542<
Bram Moolenaarb477af22018-07-15 20:20:18 +02005543 To obtain all window-local variables use: >
5544 gettabwinvar({tabnr}, {winnr}, '&')
5545
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005546< Can also be used as a |method|: >
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005547 GetTabnr()->gettabwinvar(winnr, varname)
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005548
Bram Moolenaarf49cc602018-11-11 15:21:05 +01005549gettagstack([{nr}]) *gettagstack()*
5550 The result is a Dict, which is the tag stack of window {nr}.
5551 {nr} can be the window number or the |window-ID|.
5552 When {nr} is not specified, the current window is used.
5553 When window {nr} doesn't exist, an empty Dict is returned.
5554
5555 The returned dictionary contains the following entries:
5556 curidx Current index in the stack. When at
5557 top of the stack, set to (length + 1).
5558 Index of bottom of the stack is 1.
5559 items List of items in the stack. Each item
5560 is a dictionary containing the
5561 entries described below.
5562 length Number of entries in the stack.
5563
5564 Each item in the stack is a dictionary with the following
5565 entries:
5566 bufnr buffer number of the current jump
5567 from cursor position before the tag jump.
5568 See |getpos()| for the format of the
5569 returned list.
5570 matchnr current matching tag number. Used when
5571 multiple matching tags are found for a
5572 name.
5573 tagname name of the tag
5574
5575 See |tagstack| for more information about the tag stack.
5576
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005577 Can also be used as a |method|: >
5578 GetWinnr()->gettagstack()
5579
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005580getwininfo([{winid}]) *getwininfo()*
5581 Returns information about windows as a List with Dictionaries.
5582
5583 If {winid} is given Information about the window with that ID
5584 is returned. If the window does not exist the result is an
5585 empty list.
5586
5587 Without {winid} information about all the windows in all the
5588 tab pages is returned.
5589
5590 Each List item is a Dictionary with the following entries:
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005591 botline last displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005592 bufnr number of buffer in the window
5593 height window height (excluding winbar)
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005594 loclist 1 if showing a location list
5595 {only with the +quickfix feature}
5596 quickfix 1 if quickfix or location list window
5597 {only with the +quickfix feature}
5598 terminal 1 if a terminal window
5599 {only with the +terminal feature}
5600 tabnr tab page number
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005601 topline first displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005602 variables a reference to the dictionary with
5603 window-local variables
5604 width window width
Bram Moolenaarb477af22018-07-15 20:20:18 +02005605 winbar 1 if the window has a toolbar, 0
5606 otherwise
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005607 wincol leftmost screen column of the window,
5608 col from |win_screenpos()|
5609 winid |window-ID|
5610 winnr window number
5611 winrow topmost screen column of the window,
5612 row from |win_screenpos()|
5613
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005614 Can also be used as a |method|: >
5615 GetWinnr()->getwininfo()
5616
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005617getwinpos([{timeout}]) *getwinpos()*
5618 The result is a list with two numbers, the result of
Bram Moolenaar9d87a372018-12-18 21:41:50 +01005619 getwinposx() and getwinposy() combined:
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005620 [x-pos, y-pos]
5621 {timeout} can be used to specify how long to wait in msec for
5622 a response from the terminal. When omitted 100 msec is used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005623 Use a longer time for a remote terminal.
5624 When using a value less than 10 and no response is received
5625 within that time, a previously reported position is returned,
5626 if available. This can be used to poll for the position and
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005627 do some work in the meantime: >
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005628 while 1
5629 let res = getwinpos(1)
5630 if res[0] >= 0
5631 break
5632 endif
5633 " Do some work here
5634 endwhile
5635<
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005636
5637 Can also be used as a |method|: >
5638 GetTimeout()->getwinpos()
5639<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005640 *getwinposx()*
5641getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005642 the left hand side of the GUI Vim window. Also works for an
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005643 xterm (uses a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005644 The result will be -1 if the information is not available.
5645 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005646
5647 *getwinposy()*
5648getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005649 the top of the GUI Vim window. Also works for an xterm (uses
5650 a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005651 The result will be -1 if the information is not available.
5652 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005653
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005654getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005655 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005656 Examples: >
5657 :let list_is_on = getwinvar(2, '&list')
5658 :echo "myvar = " . getwinvar(1, 'myvar')
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005659
5660< Can also be used as a |method|: >
5661 GetWinnr()->getwinvar(varname)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005662<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005663glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005664 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005665 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005666
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005667 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005668 the 'suffixes' and 'wildignore' options apply: Names matching
5669 one of the patterns in 'wildignore' will be skipped and
5670 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01005671 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005672
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005673 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar84f72352012-03-11 15:57:40 +01005674 with all matching files. The advantage of using a List is,
5675 you also get filenames containing newlines correctly.
5676 Otherwise the result is a String and when there are several
5677 matches, they are separated by <NL> characters.
5678
5679 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005680
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02005681 You can also use |readdir()| if you need to do complicated
5682 things, such as limiting the number of matches.
5683
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005684 A name for a non-existing file is not included. A symbolic
5685 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005686 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005687 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005688
5689 For most systems backticks can be used to get files names from
5690 any external command. Example: >
5691 :let tagfiles = glob("`find . -name tags -print`")
5692 :let &tags = substitute(tagfiles, "\n", ",", "g")
5693< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02005694 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005695
5696 See |expand()| for expanding special Vim variables. See
5697 |system()| for getting the raw output of an external command.
5698
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005699 Can also be used as a |method|: >
5700 GetExpr()->glob()
5701
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01005702glob2regpat({expr}) *glob2regpat()*
5703 Convert a file pattern, as used by glob(), into a search
5704 pattern. The result can be used to match with a string that
5705 is a file name. E.g. >
5706 if filename =~ glob2regpat('Make*.mak')
5707< This is equivalent to: >
5708 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005709< When {expr} is an empty string the result is "^$", match an
5710 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005711 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02005712 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005713
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005714 Can also be used as a |method|: >
5715 GetExpr()->glob2regpat()
5716< *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005717globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02005718 Perform glob() for {expr} on all directories in {path} and
5719 concatenate the results. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005720 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005721<
5722 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00005723 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005724 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005725 To add a comma inside a directory name escape it with a
5726 backslash. Note that on MS-Windows a directory may have a
5727 trailing backslash, remove it if you put a comma after it.
5728 If the expansion fails for one of the directories, there is no
5729 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005730
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005731 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005732 the 'suffixes' and 'wildignore' options apply: Names matching
5733 one of the patterns in 'wildignore' will be skipped and
5734 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005735
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005736 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005737 with all matching files. The advantage of using a List is, you
5738 also get filenames containing newlines correctly. Otherwise
5739 the result is a String and when there are several matches,
5740 they are separated by <NL> characters. Example: >
5741 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5742<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005743 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005744
Bram Moolenaar02743632005-07-25 20:42:36 +00005745 The "**" item can be used to search in a directory tree.
5746 For example, to find all "README.txt" files in the directories
5747 in 'runtimepath' and below: >
5748 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00005749< Upwards search and limiting the depth of "**" is not
5750 supported, thus using 'path' will not always work properly.
5751
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02005752 Can also be used as a |method|, the base is passed as the
5753 second argument: >
5754 GetExpr()->globpath(&rtp)
5755<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005756 *has()*
5757has({feature}) The result is a Number, which is 1 if the feature {feature} is
5758 supported, zero otherwise. The {feature} argument is a
5759 string. See |feature-list| below.
5760 Also see |exists()|.
5761
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005762
5763has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005764 The result is a Number, which is 1 if |Dictionary| {dict} has
5765 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005766
Bram Moolenaara74e4942019-08-04 17:35:53 +02005767 Can also be used as a |method|: >
5768 mydict->has_key(key)
5769
Bram Moolenaarc9703302016-01-17 21:49:33 +01005770haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005771 The result is a Number:
5772 1 when the window has set a local directory via |:lcd|
5773 2 when the tab-page has set a local directory via |:tcd|
5774 0 otherwise.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005775
5776 Without arguments use the current window.
5777 With {winnr} use this window in the current tab page.
5778 With {winnr} and {tabnr} use the window in the specified tab
5779 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005780 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005781 If {winnr} is -1 it is ignored and only the tabpage is used.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005782 Return 0 if the arguments are invalid.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005783 Examples: >
5784 if haslocaldir() == 1
5785 " window local directory case
5786 elseif haslocaldir() == 2
5787 " tab-local directory case
5788 else
5789 " global directory case
5790 endif
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005791
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005792 " current window
5793 :echo haslocaldir()
5794 :echo haslocaldir(0)
5795 :echo haslocaldir(0, 0)
5796 " window n in current tab page
5797 :echo haslocaldir(n)
5798 :echo haslocaldir(n, 0)
5799 " window n in tab page m
5800 :echo haslocaldir(n, m)
5801 " tab page m
5802 :echo haslocaldir(-1, m)
5803<
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005804 Can also be used as a |method|: >
5805 GetWinnr()->haslocaldir()
5806
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005807hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005808 The result is a Number, which is 1 if there is a mapping that
5809 contains {what} in somewhere in the rhs (what it is mapped to)
5810 and this mapping exists in one of the modes indicated by
5811 {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005812 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00005813 instead of mappings. Don't forget to specify Insert and/or
5814 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005815 Both the global mappings and the mappings local to the current
5816 buffer are checked for a match.
5817 If no matching mapping is found 0 is returned.
5818 The following characters are recognized in {mode}:
5819 n Normal mode
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02005820 v Visual and Select mode
5821 x Visual mode
5822 s Select mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00005823 o Operator-pending mode
5824 i Insert mode
5825 l Language-Argument ("r", "f", "t", etc.)
5826 c Command-line mode
5827 When {mode} is omitted, "nvo" is used.
5828
5829 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02005830 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005831 :if !hasmapto('\ABCdoit')
5832 : map <Leader>d \ABCdoit
5833 :endif
5834< This installs the mapping to "\ABCdoit" only if there isn't
5835 already a mapping to "\ABCdoit".
5836
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005837 Can also be used as a |method|: >
5838 GetRHS()->hasmapto()
5839
Bram Moolenaar071d4272004-06-13 20:20:40 +00005840histadd({history}, {item}) *histadd()*
5841 Add the String {item} to the history {history} which can be
5842 one of: *hist-names*
5843 "cmd" or ":" command line history
5844 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00005845 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00005846 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005847 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02005848 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005849 The {history} string does not need to be the whole name, one
5850 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005851 If {item} does already exist in the history, it will be
5852 shifted to become the newest entry.
5853 The result is a Number: 1 if the operation was successful,
5854 otherwise 0 is returned.
5855
5856 Example: >
5857 :call histadd("input", strftime("%Y %b %d"))
5858 :let date=input("Enter date: ")
5859< This function is not available in the |sandbox|.
5860
Bram Moolenaar2e693a82019-10-16 22:35:02 +02005861 Can also be used as a |method|, the base is passed as the
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005862 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02005863 GetHistory()->histadd('search')
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005864
Bram Moolenaar071d4272004-06-13 20:20:40 +00005865histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005866 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005867 for the possible values of {history}.
5868
Bram Moolenaarc236c162008-07-13 17:41:49 +00005869 If the parameter {item} evaluates to a String, it is used as a
5870 regular expression. All entries matching that expression will
5871 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005872 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005873 If {item} evaluates to a Number, it will be interpreted as
5874 an index, see |:history-indexing|. The respective entry will
5875 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005876
5877 The result is a Number: 1 for a successful operation,
5878 otherwise 0 is returned.
5879
5880 Examples:
5881 Clear expression register history: >
5882 :call histdel("expr")
5883<
5884 Remove all entries starting with "*" from the search history: >
5885 :call histdel("/", '^\*')
5886<
5887 The following three are equivalent: >
5888 :call histdel("search", histnr("search"))
5889 :call histdel("search", -1)
5890 :call histdel("search", '^'.histget("search", -1).'$')
5891<
5892 To delete the last search pattern and use the last-but-one for
5893 the "n" command and 'hlsearch': >
5894 :call histdel("search", -1)
5895 :let @/ = histget("search", -1)
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005896<
5897 Can also be used as a |method|: >
5898 GetHistory()->histdel()
Bram Moolenaar071d4272004-06-13 20:20:40 +00005899
5900histget({history} [, {index}]) *histget()*
5901 The result is a String, the entry with Number {index} from
5902 {history}. See |hist-names| for the possible values of
5903 {history}, and |:history-indexing| for {index}. If there is
5904 no such entry, an empty String is returned. When {index} is
5905 omitted, the most recent item from the history is used.
5906
5907 Examples:
5908 Redo the second last search from history. >
5909 :execute '/' . histget("search", -2)
5910
5911< Define an Ex command ":H {num}" that supports re-execution of
5912 the {num}th entry from the output of |:history|. >
5913 :command -nargs=1 H execute histget("cmd", 0+<args>)
5914<
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005915 Can also be used as a |method|: >
5916 GetHistory()->histget()
5917
Bram Moolenaar071d4272004-06-13 20:20:40 +00005918histnr({history}) *histnr()*
5919 The result is the Number of the current entry in {history}.
5920 See |hist-names| for the possible values of {history}.
5921 If an error occurred, -1 is returned.
5922
5923 Example: >
5924 :let inp_index = histnr("expr")
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005925
5926< Can also be used as a |method|: >
5927 GetHistory()->histnr()
Bram Moolenaar071d4272004-06-13 20:20:40 +00005928<
5929hlexists({name}) *hlexists()*
5930 The result is a Number, which is non-zero if a highlight group
5931 called {name} exists. This is when the group has been
5932 defined in some way. Not necessarily when highlighting has
5933 been defined for it, it may also have been used for a syntax
5934 item.
5935 *highlight_exists()*
5936 Obsolete name: highlight_exists().
5937
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005938 Can also be used as a |method|: >
5939 GetName()->hlexists()
5940<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005941 *hlID()*
5942hlID({name}) The result is a Number, which is the ID of the highlight group
5943 with name {name}. When the highlight group doesn't exist,
5944 zero is returned.
5945 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02005946 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005947 "Comment" group: >
5948 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5949< *highlightID()*
5950 Obsolete name: highlightID().
5951
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005952 Can also be used as a |method|: >
5953 GetName()->hlID()
5954
Bram Moolenaar071d4272004-06-13 20:20:40 +00005955hostname() *hostname()*
5956 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005957 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00005958 256 characters long are truncated.
5959
5960iconv({expr}, {from}, {to}) *iconv()*
5961 The result is a String, which is the text {expr} converted
5962 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005963 When the conversion completely fails an empty string is
5964 returned. When some characters could not be converted they
5965 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005966 The encoding names are whatever the iconv() library function
5967 can accept, see ":!man 3 iconv".
5968 Most conversions require Vim to be compiled with the |+iconv|
5969 feature. Otherwise only UTF-8 to latin1 conversion and back
5970 can be done.
5971 This can be used to display messages with special characters,
5972 no matter what 'encoding' is set to. Write the message in
5973 UTF-8 and use: >
5974 echo iconv(utf8_str, "utf-8", &enc)
5975< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5976 from/to UCS-2 is automatically changed to use UTF-8. You
5977 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005978
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005979 Can also be used as a |method|: >
5980 GetText()->iconv('latin1', 'utf-8')
5981<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005982 *indent()*
5983indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5984 current buffer. The indent is counted in spaces, the value
5985 of 'tabstop' is relevant. {lnum} is used just like in
5986 |getline()|.
5987 When {lnum} is invalid -1 is returned.
5988
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02005989 Can also be used as a |method|: >
5990 GetLnum()->indent()
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005991
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005992index({object}, {expr} [, {start} [, {ic}]]) *index()*
5993 If {object} is a |List| return the lowest index where the item
5994 has a value equal to {expr}. There is no automatic
5995 conversion, so the String "4" is different from the Number 4.
5996 And the number 4 is different from the Float 4.0. The value
5997 of 'ignorecase' is not used here, case always matters.
5998
5999 If {object} is |Blob| return the lowest index where the byte
6000 value is equal to {expr}.
6001
Bram Moolenaar748bf032005-02-02 23:04:36 +00006002 If {start} is given then start looking at the item with index
6003 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006004 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006005 case must match.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006006 -1 is returned when {expr} is not found in {object}.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006007 Example: >
6008 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006009 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006010
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006011< Can also be used as a |method|: >
6012 GetObject()->index(what)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006013
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006014input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006015 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006016 the command-line. The {prompt} argument is either a prompt
6017 string, or a blank string (for no prompt). A '\n' can be used
6018 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006019 The highlighting set with |:echohl| is used for the prompt.
6020 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02006021 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006022 for lines typed for input().
6023 Example: >
6024 :if input("Coffee or beer? ") == "beer"
6025 : echo "Cheers!"
6026 :endif
6027<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006028 If the optional {text} argument is present and not empty, this
6029 is used for the default reply, as if the user typed this.
6030 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006031 :let color = input("Color? ", "white")
6032
6033< The optional {completion} argument specifies the type of
6034 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02006035 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006036 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006037 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006038 more information. Example: >
6039 let fname = input("File: ", "", "file")
6040<
6041 NOTE: This function must not be used in a startup file, for
6042 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006043 Note: When input() is called from within a mapping it will
6044 consume remaining characters from that mapping, because a
6045 mapping is handled like the characters were typed.
6046 Use |inputsave()| before input() and |inputrestore()|
6047 after input() to avoid that. Another solution is to avoid
6048 that further characters follow in the mapping, e.g., by using
6049 |:execute| or |:normal|.
6050
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006051 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006052 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
6053 :function GetFoo()
6054 : call inputsave()
6055 : let g:Foo = input("enter search pattern: ")
6056 : call inputrestore()
6057 :endfunction
6058
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006059< Can also be used as a |method|: >
6060 GetPrompt()->input()
6061
Bram Moolenaar071d4272004-06-13 20:20:40 +00006062inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006063 Like |input()|, but when the GUI is running and text dialogs
6064 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006065 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006066 :let n = inputdialog("value for shiftwidth", shiftwidth())
6067 :if n != ""
6068 : let &sw = n
6069 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00006070< When the dialog is cancelled {cancelreturn} is returned. When
6071 omitted an empty string is returned.
6072 Hitting <Enter> works like pressing the OK button. Hitting
6073 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006074 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006075
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006076 Can also be used as a |method|: >
6077 GetPrompt()->inputdialog()
6078
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006079inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006080 {textlist} must be a |List| of strings. This |List| is
6081 displayed, one string per line. The user will be prompted to
6082 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006083 The user can also select an item by clicking on it with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006084 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006085 above the first item a negative number is returned. When
6086 clicking on the prompt one more than the length of {textlist}
6087 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006088 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02006089 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006090 the start of the string. And put a prompt in the first item.
6091 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006092 let color = inputlist(['Select color:', '1. red',
6093 \ '2. green', '3. blue'])
6094
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006095< Can also be used as a |method|: >
6096 GetChoices()->inputlist()
6097
Bram Moolenaar071d4272004-06-13 20:20:40 +00006098inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006099 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006100 Should be called the same number of times inputsave() is
6101 called. Calling it more often is harmless though.
6102 Returns 1 when there is nothing to restore, 0 otherwise.
6103
6104inputsave() *inputsave()*
6105 Preserve typeahead (also from mappings) and clear it, so that
6106 a following prompt gets input from the user. Should be
6107 followed by a matching inputrestore() after the prompt. Can
6108 be used several times, in which case there must be just as
6109 many inputrestore() calls.
6110 Returns 1 when out of memory, 0 otherwise.
6111
6112inputsecret({prompt} [, {text}]) *inputsecret()*
6113 This function acts much like the |input()| function with but
6114 two exceptions:
6115 a) the user's response will be displayed as a sequence of
6116 asterisks ("*") thereby keeping the entry secret, and
6117 b) the user's response will not be recorded on the input
6118 |history| stack.
6119 The result is a String, which is whatever the user actually
6120 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006121 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006122
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006123 Can also be used as a |method|: >
6124 GetPrompt()->inputsecret()
6125
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006126insert({object}, {item} [, {idx}]) *insert()*
6127 When {object} is a |List| or a |Blob| insert {item} at the start
6128 of it.
6129
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006130 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02006131 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006132 like omitting {idx}. A negative {idx} is also possible, see
6133 |list-index|. -1 inserts just before the last item.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006134
6135 Returns the resulting |List| or |Blob|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006136 :let mylist = insert([2, 3, 5], 1)
6137 :call insert(mylist, 4, -1)
6138 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006139< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006140 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006141 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006142
Bram Moolenaarac92e252019-08-03 21:58:38 +02006143 Can also be used as a |method|: >
6144 mylist->insert(item)
6145
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006146invert({expr}) *invert()*
6147 Bitwise invert. The argument is converted to a number. A
6148 List, Dict or Float argument causes an error. Example: >
6149 :let bits = invert(bits)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02006150< Can also be used as a |method|: >
6151 :let bits = bits->invert()
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006152
Bram Moolenaar071d4272004-06-13 20:20:40 +00006153isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006154 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00006155 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006156 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006157 is any expression, which is used as a String.
6158
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006159 Can also be used as a |method|: >
6160 GetName()->isdirectory()
6161
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02006162isinf({expr}) *isinf()*
6163 Return 1 if {expr} is a positive infinity, or -1 a negative
6164 infinity, otherwise 0. >
6165 :echo isinf(1.0 / 0.0)
6166< 1 >
6167 :echo isinf(-1.0 / 0.0)
6168< -1
6169
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006170 Can also be used as a |method|: >
6171 Compute()->isinf()
6172<
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02006173 {only available when compiled with the |+float| feature}
6174
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006175islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006176 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006177 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006178 {expr} must be the name of a variable, |List| item or
6179 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006180 :let alist = [0, ['a', 'b'], 2, 3]
6181 :lockvar 1 alist
6182 :echo islocked('alist') " 1
6183 :echo islocked('alist[1]') " 0
6184
6185< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006186 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006187
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006188 Can also be used as a |method|: >
6189 GetName()->islocked()
6190
Bram Moolenaarf3913272016-02-25 00:00:01 +01006191isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006192 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01006193 echo isnan(0.0 / 0.0)
Bram Moolenaar0f248b02019-04-04 15:36:05 +02006194< 1
Bram Moolenaarf3913272016-02-25 00:00:01 +01006195
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006196 Can also be used as a |method|: >
6197 Compute()->isnan()
6198<
Bram Moolenaarf3913272016-02-25 00:00:01 +01006199 {only available when compiled with the |+float| feature}
6200
Bram Moolenaar677ee682005-01-27 14:41:15 +00006201items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006202 Return a |List| with all the key-value pairs of {dict}. Each
6203 |List| item is a list with two items: the key of a {dict}
6204 entry and the value of this entry. The |List| is in arbitrary
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006205 order. Also see |keys()| and |values()|.
6206 Example: >
6207 for [key, value] in items(mydict)
6208 echo key . ': ' . value
6209 endfor
Bram Moolenaar677ee682005-01-27 14:41:15 +00006210
Bram Moolenaarac92e252019-08-03 21:58:38 +02006211< Can also be used as a |method|: >
6212 mydict->items()
Bram Moolenaar38a55632016-02-15 22:07:32 +01006213
Bram Moolenaared997ad2019-07-21 16:42:00 +02006214job_ functions are documented here: |job-functions-details|
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01006215
Bram Moolenaar835dc632016-02-07 14:27:38 +01006216
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006217join({list} [, {sep}]) *join()*
6218 Join the items in {list} together into one String.
6219 When {sep} is specified it is put in between the items. If
6220 {sep} is omitted a single space is used.
6221 Note that {sep} is not added at the end. You might want to
6222 add it there too: >
6223 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006224< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006225 converted into a string like with |string()|.
6226 The opposite function is |split()|.
6227
Bram Moolenaarac92e252019-08-03 21:58:38 +02006228 Can also be used as a |method|: >
6229 mylist->join()
6230
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006231js_decode({string}) *js_decode()*
6232 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006233 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01006234 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006235 - Empty items in an array (between two commas) are allowed and
6236 result in v:none items.
6237
Bram Moolenaar02b31112019-08-31 22:16:38 +02006238 Can also be used as a |method|: >
6239 ReadObject()->js_decode()
6240
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006241js_encode({expr}) *js_encode()*
6242 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006243 - Object key names are not in quotes.
6244 - v:none items in an array result in an empty item between
6245 commas.
6246 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006247 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006248 Will be encoded as:
6249 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006250 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006251 [1,null,{"one":1},null] ~
6252 This encoding is valid for JavaScript. It is more efficient
6253 than JSON, especially when using an array with optional items.
6254
Bram Moolenaar02b31112019-08-31 22:16:38 +02006255 Can also be used as a |method|: >
6256 GetObject()->js_encode()
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006257
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006258json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006259 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006260 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01006261 JSON and Vim values.
6262 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006263 - A trailing comma in an array and object is ignored, e.g.
6264 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaard09091d2019-01-17 16:07:22 +01006265 - Integer keys are accepted in objects, e.g. {1:2} is the
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006266 same as {"1":2}.
Bram Moolenaar705ada12016-01-24 17:56:50 +01006267 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006268 "1.0", or "001.2" for "1.2". Special floating point values
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006269 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6270 are accepted.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006271 - Leading zeroes in integer numbers are ignored, e.g. "012"
6272 for "12" or "-012" for "-12".
6273 - Capitalization is ignored in literal names null, true or
6274 false, e.g. "NULL" for "null", "True" for "true".
6275 - Control characters U+0000 through U+001F which are not
6276 escaped in strings are accepted, e.g. " " (tab
6277 character in string) for "\t".
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006278 - An empty JSON expression or made of only spaces is accepted
6279 and results in v:none.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006280 - Backslash in an invalid 2-character sequence escape is
6281 ignored, e.g. "\a" is decoded as "a".
6282 - A correct surrogate pair in JSON strings should normally be
6283 a 12 character sequence such as "\uD834\uDD1E", but
6284 json_decode() silently accepts truncated surrogate pairs
6285 such as "\uD834" or "\uD834\u"
6286 *E938*
6287 A duplicate key in an object, valid in rfc7159, is not
6288 accepted by json_decode() as the result must be a valid Vim
6289 type, e.g. this fails: {"a":"b", "a":"c"}
6290
Bram Moolenaar02b31112019-08-31 22:16:38 +02006291 Can also be used as a |method|: >
6292 ReadObject()->json_decode()
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006293
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006294json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006295 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006296 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006297 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006298 Vim values are converted as follows:
Bram Moolenaard09091d2019-01-17 16:07:22 +01006299 |Number| decimal number
6300 |Float| floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006301 Float nan "NaN"
6302 Float inf "Infinity"
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006303 Float -inf "-Infinity"
Bram Moolenaard09091d2019-01-17 16:07:22 +01006304 |String| in double quotes (possibly null)
6305 |Funcref| not possible, error
6306 |List| as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006307 used recursively: []
Bram Moolenaard09091d2019-01-17 16:07:22 +01006308 |Dict| as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006309 used recursively: {}
Bram Moolenaard09091d2019-01-17 16:07:22 +01006310 |Blob| as an array of the individual bytes
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006311 v:false "false"
6312 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006313 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006314 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006315 Note that NaN and Infinity are passed on as values. This is
6316 missing in the JSON standard, but several implementations do
6317 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006318
Bram Moolenaar02b31112019-08-31 22:16:38 +02006319 Can also be used as a |method|: >
6320 GetObject()->json_encode()
6321
Bram Moolenaard8b02732005-01-14 21:48:43 +00006322keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006323 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006324 arbitrary order. Also see |items()| and |values()|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00006325
Bram Moolenaarac92e252019-08-03 21:58:38 +02006326 Can also be used as a |method|: >
6327 mydict->keys()
6328
6329< *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006330len({expr}) The result is a Number, which is the length of the argument.
6331 When {expr} is a String or a Number the length in bytes is
6332 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006333 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006334 returned.
Bram Moolenaard09091d2019-01-17 16:07:22 +01006335 When {expr} is a |Blob| the number of bytes is returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006336 When {expr} is a |Dictionary| the number of entries in the
6337 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006338 Otherwise an error is given.
6339
Bram Moolenaarac92e252019-08-03 21:58:38 +02006340 Can also be used as a |method|: >
6341 mylist->len()
6342
6343< *libcall()* *E364* *E368*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006344libcall({libname}, {funcname}, {argument})
6345 Call function {funcname} in the run-time library {libname}
6346 with single argument {argument}.
6347 This is useful to call functions in a library that you
6348 especially made to be used with Vim. Since only one argument
6349 is possible, calling standard library functions is rather
6350 limited.
6351 The result is the String returned by the function. If the
6352 function returns NULL, this will appear as an empty string ""
6353 to Vim.
6354 If the function returns a number, use libcallnr()!
6355 If {argument} is a number, it is passed to the function as an
6356 int; if {argument} is a string, it is passed as a
6357 null-terminated string.
6358 This function will fail in |restricted-mode|.
6359
6360 libcall() allows you to write your own 'plug-in' extensions to
6361 Vim without having to recompile the program. It is NOT a
6362 means to call system functions! If you try to do so Vim will
6363 very probably crash.
6364
6365 For Win32, the functions you write must be placed in a DLL
6366 and use the normal C calling convention (NOT Pascal which is
6367 used in Windows System DLLs). The function must take exactly
6368 one parameter, either a character pointer or a long integer,
6369 and must return a character pointer or NULL. The character
6370 pointer returned must point to memory that will remain valid
6371 after the function has returned (e.g. in static data in the
6372 DLL). If it points to allocated memory, that memory will
6373 leak away. Using a static buffer in the function should work,
6374 it's then freed when the DLL is unloaded.
6375
6376 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00006377 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006378 because Vim thinks it's a pointer.
6379 For Win32 systems, {libname} should be the filename of the DLL
6380 without the ".DLL" suffix. A full path is only required if
6381 the DLL is not in the usual places.
6382 For Unix: When compiling your own plugins, remember that the
6383 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006384 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006385 feature is present}
6386 Examples: >
6387 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar02b31112019-08-31 22:16:38 +02006388
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006389< Can also be used as a |method|, the base is passed as the
6390 third argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02006391 GetValue()->libcall("libc.so", "getenv")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006392<
6393 *libcallnr()*
6394libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006395 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006396 int instead of a string.
6397 {only in Win32 on some Unix versions, when the |+libcall|
6398 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006399 Examples: >
6400 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006401 :call libcallnr("libc.so", "printf", "Hello World!\n")
6402 :call libcallnr("libc.so", "sleep", 10)
6403<
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006404 Can also be used as a |method|, the base is passed as the
6405 third argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02006406 GetValue()->libcallnr("libc.so", "printf")
6407<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006408
6409line({expr} [, {winid}]) *line()*
6410 The result is a Number, which is the line number of the file
Bram Moolenaar071d4272004-06-13 20:20:40 +00006411 position given with {expr}. The accepted positions are:
6412 . the cursor position
6413 $ the last line in the current buffer
6414 'x position of mark x (if the mark is not set, 0 is
6415 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02006416 w0 first line visible in current window (one if the
6417 display isn't updated, e.g. in silent Ex mode)
6418 w$ last line visible in current window (this is one
6419 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00006420 v In Visual mode: the start of the Visual area (the
6421 cursor is the end). When not in Visual mode
6422 returns the cursor position. Differs from |'<| in
6423 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006424 Note that a mark in another file can be used. The line number
6425 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006426 To get the column number use |col()|. To get both use
6427 |getpos()|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006428 With the optional {winid} argument the values are obtained for
6429 that window instead of the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006430 Examples: >
6431 line(".") line number of the cursor
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006432 line(".", winid) idem, in window "winid"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006433 line("'t") line number of mark t
6434 line("'" . marker) line number of mark marker
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006435<
6436 To jump to the last known position when opening a file see
6437 |last-position-jump|.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006438
Bram Moolenaar02b31112019-08-31 22:16:38 +02006439 Can also be used as a |method|: >
6440 GetValue()->line()
6441
Bram Moolenaar071d4272004-06-13 20:20:40 +00006442line2byte({lnum}) *line2byte()*
6443 Return the byte count from the start of the buffer for line
6444 {lnum}. This includes the end-of-line character, depending on
6445 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006446 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006447 This can also be used to get the byte count for the line just
6448 below the last line: >
6449 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006450< This is the buffer size plus one. If 'fileencoding' is empty
6451 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006452 When {lnum} is invalid, or the |+byte_offset| feature has been
6453 disabled at compile time, -1 is returned.
6454 Also see |byte2line()|, |go| and |:goto|.
6455
Bram Moolenaar02b31112019-08-31 22:16:38 +02006456 Can also be used as a |method|: >
6457 GetLnum()->line2byte()
6458
Bram Moolenaar071d4272004-06-13 20:20:40 +00006459lispindent({lnum}) *lispindent()*
6460 Get the amount of indent for line {lnum} according the lisp
6461 indenting rules, as with 'lisp'.
6462 The indent is counted in spaces, the value of 'tabstop' is
6463 relevant. {lnum} is used just like in |getline()|.
6464 When {lnum} is invalid or Vim was not compiled the
6465 |+lispindent| feature, -1 is returned.
6466
Bram Moolenaar02b31112019-08-31 22:16:38 +02006467 Can also be used as a |method|: >
6468 GetLnum()->lispindent()
6469
Bram Moolenaar9d401282019-04-06 13:18:12 +02006470list2str({list} [, {utf8}]) *list2str()*
6471 Convert each number in {list} to a character string can
6472 concatenate them all. Examples: >
6473 list2str([32]) returns " "
6474 list2str([65, 66, 67]) returns "ABC"
6475< The same can be done (slowly) with: >
6476 join(map(list, {nr, val -> nr2char(val)}), '')
6477< |str2list()| does the opposite.
6478
6479 When {utf8} is omitted or zero, the current 'encoding' is used.
6480 With {utf8} is 1, always return utf-8 characters.
6481 With utf-8 composing characters work as expected: >
6482 list2str([97, 769]) returns "á"
6483<
Bram Moolenaar02b31112019-08-31 22:16:38 +02006484 Can also be used as a |method|: >
6485 GetList()->list2str()
6486
Bram Moolenaara3347722019-05-11 21:14:24 +02006487listener_add({callback} [, {buf}]) *listener_add()*
6488 Add a callback function that will be invoked when changes have
6489 been made to buffer {buf}.
6490 {buf} refers to a buffer name or number. For the accepted
6491 values, see |bufname()|. When {buf} is omitted the current
6492 buffer is used.
6493 Returns a unique ID that can be passed to |listener_remove()|.
6494
Bram Moolenaaraad222c2019-09-06 22:46:09 +02006495 The {callback} is invoked with five arguments:
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006496 a:bufnr the buffer that was changed
6497 a:start first changed line number
6498 a:end first line number below the change
Bram Moolenaar96f45c02019-10-26 19:53:45 +02006499 a:added number of lines added, negative if lines were
6500 deleted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006501 a:changes a List of items with details about the changes
6502
6503 Example: >
6504 func Listener(bufnr, start, end, added, changes)
6505 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6506 endfunc
6507 call listener_add('Listener', bufnr)
6508
6509< The List cannot be changed. Each item in a:changes is a
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006510 dictionary with these entries:
Bram Moolenaara3347722019-05-11 21:14:24 +02006511 lnum the first line number of the change
6512 end the first line below the change
6513 added number of lines added; negative if lines were
6514 deleted
6515 col first column in "lnum" that was affected by
6516 the change; one if unknown or the whole line
6517 was affected; this is a byte index, first
6518 character has a value of one.
6519 When lines are inserted the values are:
Bram Moolenaar68e65602019-05-26 21:33:31 +02006520 lnum line above which the new line is added
Bram Moolenaara3347722019-05-11 21:14:24 +02006521 end equal to "lnum"
6522 added number of lines inserted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006523 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006524 When lines are deleted the values are:
6525 lnum the first deleted line
6526 end the line below the first deleted line, before
6527 the deletion was done
6528 added negative, number of lines deleted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006529 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006530 When lines are changed:
6531 lnum the first changed line
6532 end the line below the last changed line
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006533 added 0
6534 col first column with a change or 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006535
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006536 The entries are in the order the changes were made, thus the
6537 most recent change is at the end. The line numbers are valid
6538 when the callback is invoked, but later changes may make them
6539 invalid, thus keeping a copy for later might not work.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006540
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006541 The {callback} is invoked just before the screen is updated,
6542 when |listener_flush()| is called or when a change is being
6543 made that changes the line count in a way it causes a line
6544 number in the list of changes to become invalid.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006545
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006546 The {callback} is invoked with the text locked, see
6547 |textlock|. If you do need to make changes to the buffer, use
6548 a timer to do this later |timer_start()|.
Bram Moolenaara3347722019-05-11 21:14:24 +02006549
6550 The {callback} is not invoked when the buffer is first loaded.
6551 Use the |BufReadPost| autocmd event to handle the initial text
6552 of a buffer.
6553 The {callback} is also not invoked when the buffer is
6554 unloaded, use the |BufUnload| autocmd event for that.
6555
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006556 Can also be used as a |method|, the base is passed as the
6557 second argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02006558 GetBuffer()->listener_add(callback)
6559
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006560listener_flush([{buf}]) *listener_flush()*
6561 Invoke listener callbacks for buffer {buf}. If there are no
6562 pending changes then no callbacks are invoked.
6563
6564 {buf} refers to a buffer name or number. For the accepted
6565 values, see |bufname()|. When {buf} is omitted the current
6566 buffer is used.
6567
Bram Moolenaar02b31112019-08-31 22:16:38 +02006568 Can also be used as a |method|: >
6569 GetBuffer()->listener_flush()
6570
Bram Moolenaara3347722019-05-11 21:14:24 +02006571listener_remove({id}) *listener_remove()*
6572 Remove a listener previously added with listener_add().
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02006573 Returns zero when {id} could not be found, one when {id} was
6574 removed.
Bram Moolenaara3347722019-05-11 21:14:24 +02006575
Bram Moolenaar02b31112019-08-31 22:16:38 +02006576 Can also be used as a |method|: >
6577 GetListenerId()->listener_remove()
6578
Bram Moolenaar071d4272004-06-13 20:20:40 +00006579localtime() *localtime()*
6580 Return the current time, measured as seconds since 1st Jan
6581 1970. See also |strftime()| and |getftime()|.
6582
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006583
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006584log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006585 Return the natural logarithm (base e) of {expr} as a |Float|.
6586 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006587 (0, inf].
6588 Examples: >
6589 :echo log(10)
6590< 2.302585 >
6591 :echo log(exp(5))
6592< 5.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006593
6594 Can also be used as a |method|: >
6595 Compute()->log()
6596<
Bram Moolenaardb84e452010-08-15 13:50:43 +02006597 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006598
6599
Bram Moolenaar446cb832008-06-24 21:56:24 +00006600log10({expr}) *log10()*
6601 Return the logarithm of Float {expr} to base 10 as a |Float|.
6602 {expr} must evaluate to a |Float| or a |Number|.
6603 Examples: >
6604 :echo log10(1000)
6605< 3.0 >
6606 :echo log10(0.01)
6607< -2.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006608
6609 Can also be used as a |method|: >
6610 Compute()->log10()
6611<
Bram Moolenaar446cb832008-06-24 21:56:24 +00006612 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006613
6614luaeval({expr} [, {expr}]) *luaeval()*
6615 Evaluate Lua expression {expr} and return its result converted
6616 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02006617 argument accessible as _A inside first {expr}.
6618 Strings are returned as they are.
6619 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006620 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02006621 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006622 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02006623 as-is.
6624 Other objects are returned as zero without any errors.
6625 See |lua-luaeval| for more details.
Bram Moolenaar02b31112019-08-31 22:16:38 +02006626
6627 Can also be used as a |method|: >
6628 GetExpr()->luaeval()
6629
6630< {only available when compiled with the |+lua| feature}
Bram Moolenaard38b0552012-04-25 19:07:41 +02006631
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006632map({expr1}, {expr2}) *map()*
6633 {expr1} must be a |List| or a |Dictionary|.
6634 Replace each item in {expr1} with the result of evaluating
6635 {expr2}. {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006636
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006637 If {expr2} is a |string|, inside {expr2} |v:val| has the value
6638 of the current item. For a |Dictionary| |v:key| has the key
6639 of the current item and for a |List| |v:key| has the index of
6640 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006641 Example: >
6642 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006643< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006644
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006645 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006646 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006647 |literal-string| to avoid having to double backslashes. You
6648 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006649
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006650 If {expr2} is a |Funcref| it is called with two arguments:
6651 1. The key or the index of the current item.
6652 2. the value of the current item.
6653 The function must return the new value of the item. Example
6654 that changes each value by "key-value": >
6655 func KeyValue(key, val)
6656 return a:key . '-' . a:val
6657 endfunc
6658 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006659< It is shorter when using a |lambda|: >
6660 call map(myDict, {key, val -> key . '-' . val})
6661< If you do not use "val" you can leave it out: >
6662 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaar088e8e32019-08-08 22:15:18 +02006663< If you do not use "key" you can use a short name: >
6664 call map(myDict, {_, val -> 'item: ' . val})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006665<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006666 The operation is done in-place. If you want a |List| or
6667 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02006668 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006669
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006670< Returns {expr1}, the |List| or |Dictionary| that was filtered.
6671 When an error is encountered while evaluating {expr2} no
6672 further items in {expr1} are processed. When {expr2} is a
6673 Funcref errors inside a function are ignored, unless it was
6674 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006675
Bram Moolenaarac92e252019-08-03 21:58:38 +02006676 Can also be used as a |method|: >
6677 mylist->map(expr2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006678
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006679maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02006680 When {dict} is omitted or zero: Return the rhs of mapping
6681 {name} in mode {mode}. The returned String has special
6682 characters translated like in the output of the ":map" command
6683 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006684
Bram Moolenaarbd743252010-10-20 21:23:33 +02006685 When there is no mapping for {name}, an empty String is
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006686 returned. When the mapping for {name} is empty, then "<Nop>"
6687 is returned.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006688
6689 The {name} can have special key names, like in the ":map"
6690 command.
6691
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006692 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006693 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02006694 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006695 "o" Operator-pending
6696 "i" Insert
6697 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02006698 "s" Select
6699 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00006700 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006701 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00006702 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006703 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006704
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006705 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006706 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006707
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006708 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02006709 containing all the information of the mapping with the
6710 following items:
6711 "lhs" The {lhs} of the mapping.
6712 "rhs" The {rhs} of the mapping as typed.
6713 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02006714 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006715 "expr" 1 for an expression mapping (|:map-<expr>|).
6716 "buffer" 1 for a buffer local mapping (|:map-local|).
6717 "mode" Modes for which the mapping is defined. In
6718 addition to the modes mentioned above, these
6719 characters will be used:
6720 " " Normal, Visual and Operator-pending
6721 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01006722 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02006723 "sid" The script local ID, used for <sid> mappings
6724 (|<SID>|).
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02006725 "lnum" The line number in "sid", zero if unknown.
Bram Moolenaardfb18412013-12-11 18:53:29 +01006726 "nowait" Do not wait for other, longer mappings.
6727 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02006728
Bram Moolenaar071d4272004-06-13 20:20:40 +00006729 The mappings local to the current buffer are checked first,
6730 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00006731 This function can be used to map a key even when it's already
6732 mapped, and have it do the original mapping too. Sketch: >
6733 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
6734
Bram Moolenaara1449832019-09-01 20:16:52 +02006735< Can also be used as a |method|: >
6736 GetKey()->maparg('n')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006737
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006738mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006739 Check if there is a mapping that matches with {name} in mode
6740 {mode}. See |maparg()| for {mode} and special names in
6741 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006742 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006743 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006744 A match happens with a mapping that starts with {name} and
6745 with a mapping which is equal to the start of {name}.
6746
Bram Moolenaar446cb832008-06-24 21:56:24 +00006747 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006748 mapcheck("a") yes yes yes
6749 mapcheck("abc") yes yes yes
6750 mapcheck("ax") yes no no
6751 mapcheck("b") no no no
6752
6753 The difference with maparg() is that mapcheck() finds a
6754 mapping that matches with {name}, while maparg() only finds a
6755 mapping for {name} exactly.
6756 When there is no mapping that starts with {name}, an empty
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006757 String is returned. If there is one, the RHS of that mapping
Bram Moolenaar071d4272004-06-13 20:20:40 +00006758 is returned. If there are several mappings that start with
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006759 {name}, the RHS of one of them is returned. This will be
6760 "<Nop>" if the RHS is empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006761 The mappings local to the current buffer are checked first,
6762 then the global mappings.
6763 This function can be used to check if a mapping can be added
6764 without being ambiguous. Example: >
6765 :if mapcheck("_vv") == ""
6766 : map _vv :set guifont=7x13<CR>
6767 :endif
6768< This avoids adding the "_vv" mapping when there already is a
6769 mapping for "_v" or for "_vvv".
6770
Bram Moolenaara1449832019-09-01 20:16:52 +02006771 Can also be used as a |method|: >
6772 GetKey()->mapcheck('n')
6773
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006774match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006775 When {expr} is a |List| then this returns the index of the
6776 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006777 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006778
Bram Moolenaar58b85342016-08-14 19:54:54 +02006779 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006780 Number, which gives the index (byte offset) in {expr} where
6781 {pat} matches.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006782
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006783 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006784 If there is no match -1 is returned.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006785
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006786 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006787 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006788 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006789 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006790< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006791 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02006792 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00006793 :let sepidx = match(line, '[.,;: \t]')
6794< *strcasestr()*
6795 Vim doesn't have a strcasestr() function. But you can add
6796 "\c" to the pattern to ignore case: >
6797 :let idx = match(haystack, '\cneedle')
6798<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006799 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006800 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006801 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006802 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006803 :echo match("testing", "ing", 2)
6804< result is again "4". >
6805 :echo match("testing", "ing", 4)
6806< result is again "4". >
6807 :echo match("testing", "t", 2)
6808< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006809 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00006810 {start} bytes later, thus "^" will match at {start}. Except
6811 when {count} is given, then it's like matches before the
6812 {start} byte are ignored (this is a bit complicated to keep it
6813 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006814 For a String, if {start} < 0, it will be set to 0. For a list
6815 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006816 If {start} is out of range ({start} > strlen({expr}) for a
6817 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006818
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006819 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006820 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006821 character further. Thus this example results in 1: >
6822 echo match("testing", "..", 0, 2)
6823< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006824 Note that when {count} is added the way {start} works changes,
6825 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006826
Bram Moolenaar071d4272004-06-13 20:20:40 +00006827 See |pattern| for the patterns that are accepted.
6828 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02006829 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00006830 done like 'magic' is set and 'cpoptions' is empty.
6831
Bram Moolenaara1449832019-09-01 20:16:52 +02006832 Can also be used as a |method|: >
6833 GetList()->match('word')
6834<
Bram Moolenaar95e51472018-07-28 16:55:56 +02006835 *matchadd()* *E798* *E799* *E801* *E957*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006836matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006837 Defines a pattern to be highlighted in the current window (a
6838 "match"). It will be highlighted with {group}. Returns an
6839 identification number (ID), which can be used to delete the
Bram Moolenaaraff74912019-03-30 18:11:49 +01006840 match using |matchdelete()|. The ID is bound to the window.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01006841 Matching is case sensitive and magic, unless case sensitivity
6842 or magicness are explicitly overridden in {pattern}. The
6843 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02006844 The "Conceal" value is special, it causes the match to be
6845 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006846
6847 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006848 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006849 highlighting overrule that of a match with a lower priority.
6850 A priority is specified as an integer (negative numbers are no
6851 exception). If the {priority} argument is not specified, the
6852 default priority is 10. The priority of 'hlsearch' is zero,
6853 hence all matches with a priority greater than zero will
6854 overrule it. Syntax highlighting (see 'syntax') is a separate
6855 mechanism, and regardless of the chosen priority a match will
6856 always overrule syntax highlighting.
6857
6858 The optional {id} argument allows the request for a specific
6859 match ID. If a specified ID is already taken, an error
6860 message will appear and the match will not be added. An ID
6861 is specified as a positive integer (zero excluded). IDs 1, 2
6862 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02006863 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006864 |matchadd()| automatically chooses a free ID.
6865
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006866 The optional {dict} argument allows for further custom
6867 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02006868 conceal character that will be shown for |hl-Conceal|
6869 highlighted matches. The dict can have the following members:
6870
6871 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006872 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02006873 matches, see |:syn-cchar|)
Bram Moolenaar95e51472018-07-28 16:55:56 +02006874 window Instead of the current window use the
6875 window with this number or window ID.
Bram Moolenaar6561d522015-07-21 15:48:27 +02006876
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006877 The number of matches is not limited, as it is the case with
6878 the |:match| commands.
6879
6880 Example: >
6881 :highlight MyGroup ctermbg=green guibg=green
6882 :let m = matchadd("MyGroup", "TODO")
6883< Deletion of the pattern: >
6884 :call matchdelete(m)
6885
6886< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02006887 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006888 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006889
Bram Moolenaara1449832019-09-01 20:16:52 +02006890 Can also be used as a |method|: >
6891 GetGroup()->matchadd('TODO')
6892<
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02006893 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006894matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02006895 Same as |matchadd()|, but requires a list of positions {pos}
6896 instead of a pattern. This command is faster than |matchadd()|
6897 because it does not require to handle regular expressions and
6898 sets buffer line boundaries to redraw screen. It is supposed
6899 to be used when fast match additions and deletions are
6900 required, for example to highlight matching parentheses.
6901
6902 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006903 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02006904 line has number 1.
6905 - A list with one number, e.g., [23]. The whole line with this
6906 number will be highlighted.
6907 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006908 the line number, the second one is the column number (first
6909 column is 1, the value must correspond to the byte index as
6910 |col()| would return). The character at this position will
6911 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006912 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006913 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006914
Bram Moolenaarb3414592014-06-17 17:48:32 +02006915 The maximum number of positions is 8.
6916
6917 Example: >
6918 :highlight MyGroup ctermbg=green guibg=green
6919 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6920< Deletion of the pattern: >
6921 :call matchdelete(m)
6922
6923< Matches added by |matchaddpos()| are returned by
6924 |getmatches()| with an entry "pos1", "pos2", etc., with the
6925 value a list like the {pos} item.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006926
Bram Moolenaara1449832019-09-01 20:16:52 +02006927 Can also be used as a |method|: >
6928 GetGroup()->matchaddpos([23, 11])
6929
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006930matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006931 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006932 |:2match| or |:3match| command.
6933 Return a |List| with two elements:
6934 The name of the highlight group used
6935 The pattern used.
6936 When {nr} is not 1, 2 or 3 returns an empty |List|.
6937 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006938 This is useful to save and restore a |:match|.
6939 Highlighting matches using the |:match| commands are limited
6940 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006941
Bram Moolenaara1449832019-09-01 20:16:52 +02006942 Can also be used as a |method|: >
6943 GetMatch()->matcharg()
6944
Bram Moolenaaraff74912019-03-30 18:11:49 +01006945matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006946 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00006947 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006948 otherwise -1. See example for |matchadd()|. All matches can
6949 be deleted in one operation by |clearmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01006950 If {win} is specified, use the window with this number or
6951 window ID instead of the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006952
Bram Moolenaara1449832019-09-01 20:16:52 +02006953 Can also be used as a |method|: >
6954 GetMatch()->matchdelete()
6955
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006956matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006957 Same as |match()|, but return the index of first character
6958 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006959 :echo matchend("testing", "ing")
6960< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00006961 *strspn()* *strcspn()*
6962 Vim doesn't have a strspn() or strcspn() function, but you can
6963 do it with matchend(): >
6964 :let span = matchend(line, '[a-zA-Z]')
6965 :let span = matchend(line, '[^a-zA-Z]')
6966< Except that -1 is returned when there are no matches.
6967
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006968 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006969 :echo matchend("testing", "ing", 2)
6970< results in "7". >
6971 :echo matchend("testing", "ing", 5)
6972< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006973 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006974
Bram Moolenaara1449832019-09-01 20:16:52 +02006975 Can also be used as a |method|: >
6976 GetText()->matchend('word')
6977
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006978matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006979 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006980 list is the matched string, same as what matchstr() would
6981 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00006982 in |:substitute|. When an optional submatch didn't match an
6983 empty string is used. Example: >
6984 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6985< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006986 When there is no match an empty list is returned.
6987
Bram Moolenaara1449832019-09-01 20:16:52 +02006988 Can also be used as a |method|: >
6989 GetList()->matchlist('word')
6990
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006991matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006992 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006993 :echo matchstr("testing", "ing")
6994< results in "ing".
6995 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006996 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006997 :echo matchstr("testing", "ing", 2)
6998< results in "ing". >
6999 :echo matchstr("testing", "ing", 5)
7000< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007001 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007002 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007003
Bram Moolenaara1449832019-09-01 20:16:52 +02007004 Can also be used as a |method|: >
7005 GetText()->matchstr('word')
7006
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007007matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02007008 Same as |matchstr()|, but return the matched string, the start
7009 position and the end position of the match. Example: >
7010 :echo matchstrpos("testing", "ing")
7011< results in ["ing", 4, 7].
7012 When there is no match ["", -1, -1] is returned.
7013 The {start}, if given, has the same meaning as for |match()|. >
7014 :echo matchstrpos("testing", "ing", 2)
7015< results in ["ing", 4, 7]. >
7016 :echo matchstrpos("testing", "ing", 5)
7017< result is ["", -1, -1].
7018 When {expr} is a |List| then the matching item, the index
7019 of first item where {pat} matches, the start position and the
7020 end position of the match are returned. >
7021 :echo matchstrpos([1, '__x'], '\a')
7022< result is ["x", 1, 2, 3].
7023 The type isn't changed, it's not necessarily a String.
7024
Bram Moolenaara1449832019-09-01 20:16:52 +02007025 Can also be used as a |method|: >
7026 GetText()->matchstrpos('word')
Bram Moolenaar2e693a82019-10-16 22:35:02 +02007027<
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007028 *max()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01007029max({expr}) Return the maximum value of all items in {expr}.
7030 {expr} can be a list or a dictionary. For a dictionary,
7031 it returns the maximum of all values in the dictionary.
7032 If {expr} is neither a list nor a dictionary, or one of the
7033 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007034 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007035
Bram Moolenaarac92e252019-08-03 21:58:38 +02007036 Can also be used as a |method|: >
7037 mylist->max()
7038
7039< *min()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01007040min({expr}) Return the minimum value of all items in {expr}.
7041 {expr} can be a list or a dictionary. For a dictionary,
7042 it returns the minimum of all values in the dictionary.
7043 If {expr} is neither a list nor a dictionary, or one of the
7044 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007045 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007046
Bram Moolenaarac92e252019-08-03 21:58:38 +02007047 Can also be used as a |method|: >
7048 mylist->min()
7049
7050< *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007051mkdir({name} [, {path} [, {prot}]])
7052 Create directory {name}.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007053
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007054 If {path} is "p" then intermediate directories are created as
7055 necessary. Otherwise it must be "".
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007056
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007057 If {prot} is given it is used to set the protection bits of
7058 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar58b85342016-08-14 19:54:54 +02007059 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00007060 for others. This is only used for the last part of {name}.
7061 Thus if you create /tmp/foo/bar then /tmp/foo will be created
7062 with 0755.
7063 Example: >
7064 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007065
Bram Moolenaared39e1d2008-08-09 17:55:22 +00007066< This function is not available in the |sandbox|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007067
Bram Moolenaar78a16b02018-04-14 13:51:55 +02007068 There is no error if the directory already exists and the "p"
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007069 flag is passed (since patch 8.0.1708). However, without the
7070 "p" option the call will fail.
7071
7072 The function result is a Number, which is 1 if the call was
7073 successful or 0 if the directory creation failed or partly
7074 failed.
7075
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007076 Not available on all systems. To check use: >
7077 :if exists("*mkdir")
Bram Moolenaara1449832019-09-01 20:16:52 +02007078
7079< Can also be used as a |method|: >
7080 GetName()->mkdir()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007081<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007082 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007083mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007084 If [expr] is supplied and it evaluates to a non-zero Number or
7085 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007086 returned, otherwise only the first letter is returned.
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02007087 Also see |state()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007088
Bram Moolenaar612cc382018-07-29 15:34:26 +02007089 n Normal, Terminal-Normal
7090 no Operator-pending
Bram Moolenaar5976f8f2018-12-27 23:44:44 +01007091 nov Operator-pending (forced characterwise |o_v|)
7092 noV Operator-pending (forced linewise |o_V|)
7093 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007094 CTRL-V is one character
Bram Moolenaar612cc382018-07-29 15:34:26 +02007095 niI Normal using |i_CTRL-O| in |Insert-mode|
7096 niR Normal using |i_CTRL-O| in |Replace-mode|
7097 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7098 v Visual by character
7099 V Visual by line
7100 CTRL-V Visual blockwise
7101 s Select by character
7102 S Select by line
7103 CTRL-S Select blockwise
7104 i Insert
7105 ic Insert mode completion |compl-generic|
7106 ix Insert mode |i_CTRL-X| completion
7107 R Replace |R|
7108 Rc Replace mode completion |compl-generic|
7109 Rv Virtual Replace |gR|
7110 Rx Replace mode |i_CTRL-X| completion
7111 c Command-line editing
7112 cv Vim Ex mode |gQ|
7113 ce Normal Ex mode |Q|
7114 r Hit-enter prompt
7115 rm The -- more -- prompt
7116 r? A |:confirm| query of some sort
7117 ! Shell or external command is executing
7118 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00007119 This is useful in the 'statusline' option or when used
7120 with |remote_expr()| In most other places it always returns
7121 "c" or "n".
Bram Moolenaar612cc382018-07-29 15:34:26 +02007122 Note that in the future more modes and more specific modes may
7123 be added. It's better not to compare the whole string but only
7124 the leading character(s).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007125 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007126
Bram Moolenaara1449832019-09-01 20:16:52 +02007127 Can also be used as a |method|: >
7128 DoFull()->mode()
7129
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007130mzeval({expr}) *mzeval()*
7131 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02007132 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007133 Numbers and strings are returned as they are.
7134 Pairs (including lists and improper lists) and vectors are
7135 returned as Vim |Lists|.
7136 Hash tables are represented as Vim |Dictionary| type with keys
7137 converted to strings.
7138 All other types are converted to string with display function.
7139 Examples: >
7140 :mz (define l (list 1 2 3))
7141 :mz (define h (make-hash)) (hash-set! h "list" l)
7142 :echo mzeval("l")
7143 :echo mzeval("h")
7144<
Bram Moolenaara1449832019-09-01 20:16:52 +02007145 Can also be used as a |method|: >
7146 GetExpr()->mzeval()
7147<
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007148 {only available when compiled with the |+mzscheme| feature}
7149
Bram Moolenaar071d4272004-06-13 20:20:40 +00007150nextnonblank({lnum}) *nextnonblank()*
7151 Return the line number of the first line at or below {lnum}
7152 that is not blank. Example: >
7153 if getline(nextnonblank(1)) =~ "Java"
7154< When {lnum} is invalid or there is no non-blank line at or
7155 below it, zero is returned.
7156 See also |prevnonblank()|.
7157
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007158 Can also be used as a |method|: >
7159 GetLnum()->nextnonblank()
7160
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007161nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007162 Return a string with a single character, which has the number
7163 value {expr}. Examples: >
7164 nr2char(64) returns "@"
7165 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01007166< When {utf8} is omitted or zero, the current 'encoding' is used.
7167 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007168 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01007169< With {utf8} set to 1, always return utf-8 characters.
7170 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00007171 nr2char(10), because NULs are represented with newline
7172 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00007173 string, thus results in an empty string.
Bram Moolenaaraff74912019-03-30 18:11:49 +01007174 To turn a list of character numbers into a string: >
7175 let list = [65, 66, 67]
7176 let str = join(map(list, {_, val -> nr2char(val)}), '')
7177< Result: "ABC"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007178
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007179 Can also be used as a |method|: >
7180 GetNumber()->nr2char()
Bram Moolenaar073e4b92019-08-18 23:01:56 +02007181
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007182or({expr}, {expr}) *or()*
7183 Bitwise OR on the two arguments. The arguments are converted
7184 to a number. A List, Dict or Float argument causes an error.
7185 Example: >
7186 :let bits = or(bits, 0x80)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02007187< Can also be used as a |method|: >
7188 :let bits = bits->or(0x80)
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007189
7190
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007191pathshorten({expr}) *pathshorten()*
7192 Shorten directory names in the path {expr} and return the
7193 result. The tail, the file name, is kept as-is. The other
7194 components in the path are reduced to single letters. Leading
7195 '~' and '.' characters are kept. Example: >
7196 :echo pathshorten('~/.vim/autoload/myfile.vim')
7197< ~/.v/a/myfile.vim ~
7198 It doesn't matter if the path exists or not.
7199
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007200 Can also be used as a |method|: >
7201 GetDirectories()->pathshorten()
7202
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007203perleval({expr}) *perleval()*
7204 Evaluate Perl expression {expr} in scalar context and return
7205 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007206 converted, it is returned as a string Perl representation.
7207 Note: If you want an array or hash, {expr} must return a
7208 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007209 Example: >
7210 :echo perleval('[1 .. 4]')
7211< [1, 2, 3, 4]
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007212
7213 Can also be used as a |method|: >
7214 GetExpr()->perleval()
7215
7216< {only available when compiled with the |+perl| feature}
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007217
Bram Moolenaar931a2772019-07-04 16:54:54 +02007218
7219popup_ functions are documented here: |popup-functions|.
7220
7221
Bram Moolenaar446cb832008-06-24 21:56:24 +00007222pow({x}, {y}) *pow()*
7223 Return the power of {x} to the exponent {y} as a |Float|.
7224 {x} and {y} must evaluate to a |Float| or a |Number|.
7225 Examples: >
7226 :echo pow(3, 3)
7227< 27.0 >
7228 :echo pow(2, 16)
7229< 65536.0 >
7230 :echo pow(32, 0.20)
7231< 2.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02007232
7233 Can also be used as a |method|: >
7234 Compute()->pow(3)
7235<
Bram Moolenaar446cb832008-06-24 21:56:24 +00007236 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007237
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007238prevnonblank({lnum}) *prevnonblank()*
7239 Return the line number of the first line at or above {lnum}
7240 that is not blank. Example: >
7241 let ind = indent(prevnonblank(v:lnum - 1))
7242< When {lnum} is invalid or there is no non-blank line at or
7243 above it, zero is returned.
7244 Also see |nextnonblank()|.
7245
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007246 Can also be used as a |method|: >
7247 GetLnum()->prevnonblank()
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007248
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007249printf({fmt}, {expr1} ...) *printf()*
7250 Return a String with {fmt}, where "%" items are replaced by
7251 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007252 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007253< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007254 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007255
Bram Moolenaarfd8ca212019-08-10 00:13:30 +02007256 When used as a |method| the base is passed as the second
7257 argument: >
7258 Compute()->printf("result: %d")
7259
7260< Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007261 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01007262 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00007263 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00007264 %.9s string truncated to 9 bytes
7265 %c single byte
7266 %d decimal number
7267 %5d decimal number padded with spaces to 5 characters
7268 %x hex number
7269 %04x hex number padded with zeros to at least 4 characters
7270 %X hex number using upper case letters
7271 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02007272 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02007273 %f floating point number as 12.23, inf, -inf or nan
7274 %F floating point number as 12.23, INF, -INF or NAN
7275 %e floating point number as 1.23e3, inf, -inf or nan
7276 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00007277 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01007278 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00007279 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007280
7281 Conversion specifications start with '%' and end with the
7282 conversion type. All other characters are copied unchanged to
7283 the result.
7284
7285 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007286 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007287
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007288 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007289
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007290 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007291 Zero or more of the following flags:
7292
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007293 # The value should be converted to an "alternate
7294 form". For c, d, and s conversions, this option
7295 has no effect. For o conversions, the precision
7296 of the number is increased to force the first
7297 character of the output string to a zero (except
7298 if a zero value is printed with an explicit
7299 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02007300 For b and B conversions, a non-zero result has
7301 the string "0b" (or "0B" for B conversions)
7302 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007303 For x and X conversions, a non-zero result has
7304 the string "0x" (or "0X" for X conversions)
7305 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007306
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007307 0 (zero) Zero padding. For all conversions the converted
7308 value is padded on the left with zeros rather
7309 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02007310 numeric conversion (d, b, B, o, x, and X), the 0
7311 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007312
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007313 - A negative field width flag; the converted value
7314 is to be left adjusted on the field boundary.
7315 The converted value is padded on the right with
7316 blanks, rather than on the left with blanks or
7317 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007318
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007319 ' ' (space) A blank should be left before a positive
7320 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007321
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007322 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02007323 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007324 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007325
7326 field-width
7327 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00007328 field width. If the converted value has fewer bytes
7329 than the field width, it will be padded with spaces on
7330 the left (or right, if the left-adjustment flag has
7331 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007332
7333 .precision
7334 An optional precision, in the form of a period '.'
7335 followed by an optional digit string. If the digit
7336 string is omitted, the precision is taken as zero.
7337 This gives the minimum number of digits to appear for
7338 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00007339 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007340 For floating point it is the number of digits after
7341 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007342
7343 type
7344 A character that specifies the type of conversion to
7345 be applied, see below.
7346
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007347 A field width or precision, or both, may be indicated by an
7348 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02007349 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007350 negative field width is treated as a left adjustment flag
7351 followed by a positive field width; a negative precision is
7352 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007353 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007354< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007355 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007356
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007357 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007358
Bram Moolenaar91984b92016-08-16 21:58:41 +02007359 *printf-d* *printf-b* *printf-B* *printf-o*
7360 *printf-x* *printf-X*
7361 dbBoxX The Number argument is converted to signed decimal
7362 (d), unsigned binary (b and B), unsigned octal (o), or
7363 unsigned hexadecimal (x and X) notation. The letters
7364 "abcdef" are used for x conversions; the letters
7365 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007366 The precision, if any, gives the minimum number of
7367 digits that must appear; if the converted value
7368 requires fewer digits, it is padded on the left with
7369 zeros.
7370 In no case does a non-existent or small field width
7371 cause truncation of a numeric field; if the result of
7372 a conversion is wider than the field width, the field
7373 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02007374 The 'h' modifier indicates the argument is 16 bits.
7375 The 'l' modifier indicates the argument is 32 bits.
7376 The 'L' modifier indicates the argument is 64 bits.
7377 Generally, these modifiers are not useful. They are
7378 ignored when type is known from the argument.
7379
7380 i alias for d
7381 D alias for ld
7382 U alias for lu
7383 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007384
Bram Moolenaar446cb832008-06-24 21:56:24 +00007385 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007386 c The Number argument is converted to a byte, and the
7387 resulting character is written.
7388
Bram Moolenaar446cb832008-06-24 21:56:24 +00007389 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007390 s The text of the String argument is used. If a
7391 precision is specified, no more bytes than the number
7392 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02007393 If the argument is not a String type, it is
7394 automatically converted to text with the same format
7395 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01007396 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01007397 S The text of the String argument is used. If a
7398 precision is specified, no more display cells than the
Bram Moolenaar4c92e752019-02-17 21:18:32 +01007399 number specified are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007400
Bram Moolenaar446cb832008-06-24 21:56:24 +00007401 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007402 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007403 form 123.456. The precision specifies the number of
7404 digits after the decimal point. When the precision is
7405 zero the decimal point is omitted. When the precision
7406 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02007407 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007408 or "-inf" with %f (INF or -INF with %F).
7409 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007410 Example: >
7411 echo printf("%.2f", 12.115)
7412< 12.12
7413 Note that roundoff depends on the system libraries.
7414 Use |round()| when in doubt.
7415
7416 *printf-e* *printf-E*
7417 e E The Float argument is converted into a string of the
7418 form 1.234e+03 or 1.234E+03 when using 'E'. The
7419 precision specifies the number of digits after the
7420 decimal point, like with 'f'.
7421
7422 *printf-g* *printf-G*
7423 g G The Float argument is converted like with 'f' if the
7424 value is between 0.001 (inclusive) and 10000000.0
7425 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7426 for 'G'. When no precision is specified superfluous
7427 zeroes and '+' signs are removed, except for the zero
7428 immediately after the decimal point. Thus 10000000.0
7429 results in 1.0e7.
7430
7431 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007432 % A '%' is written. No argument is converted. The
7433 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007434
Bram Moolenaarc236c162008-07-13 17:41:49 +00007435 When a Number argument is expected a String argument is also
7436 accepted and automatically converted.
7437 When a Float or String argument is expected a Number argument
7438 is also accepted and automatically converted.
7439 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007440
Bram Moolenaar83bab712005-08-01 21:58:57 +00007441 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007442 The number of {exprN} arguments must exactly match the number
7443 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007444 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007445
7446
Bram Moolenaarf2732452018-06-03 14:47:35 +02007447prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007448 Set prompt callback for buffer {buf} to {expr}. When {expr}
7449 is an empty string the callback is removed. This has only
Bram Moolenaarf2732452018-06-03 14:47:35 +02007450 effect if {buf} has 'buftype' set to "prompt".
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007451
Bram Moolenaarf2732452018-06-03 14:47:35 +02007452 The callback is invoked when pressing Enter. The current
7453 buffer will always be the prompt buffer. A new line for a
7454 prompt is added before invoking the callback, thus the prompt
7455 for which the callback was invoked will be in the last but one
7456 line.
7457 If the callback wants to add text to the buffer, it must
7458 insert it above the last line, since that is where the current
7459 prompt is. This can also be done asynchronously.
7460 The callback is invoked with one argument, which is the text
7461 that was entered at the prompt. This can be an empty string
7462 if the user only typed Enter.
7463 Example: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02007464 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaarf2732452018-06-03 14:47:35 +02007465 func s:TextEntered(text)
7466 if a:text == 'exit' || a:text == 'quit'
7467 stopinsert
7468 close
7469 else
7470 call append(line('$') - 1, 'Entered: "' . a:text . '"')
7471 " Reset 'modified' to allow the buffer to be closed.
7472 set nomodified
7473 endif
7474 endfunc
7475
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007476< Can also be used as a |method|: >
7477 GetBuffer()->prompt_setcallback(callback)
7478
7479
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007480prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7481 Set a callback for buffer {buf} to {expr}. When {expr} is an
7482 empty string the callback is removed. This has only effect if
7483 {buf} has 'buftype' set to "prompt".
7484
7485 This callback will be invoked when pressing CTRL-C in Insert
7486 mode. Without setting a callback Vim will exit Insert mode,
7487 as in any buffer.
7488
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007489 Can also be used as a |method|: >
7490 GetBuffer()->prompt_setinterrupt(callback)
7491
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007492prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7493 Set prompt for buffer {buf} to {text}. You most likely want
7494 {text} to end in a space.
7495 The result is only visible if {buf} has 'buftype' set to
7496 "prompt". Example: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02007497 call prompt_setprompt(bufnr(), 'command: ')
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007498<
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007499 Can also be used as a |method|: >
7500 GetBuffer()->prompt_setprompt('command: ')
7501
Bram Moolenaared997ad2019-07-21 16:42:00 +02007502prop_ functions are documented here: |text-prop-functions|.
Bram Moolenaarf2732452018-06-03 14:47:35 +02007503
Bram Moolenaare9bd5722019-08-17 19:36:06 +02007504pum_getpos() *pum_getpos()*
7505 If the popup menu (see |ins-completion-menu|) is not visible,
7506 returns an empty |Dictionary|, otherwise, returns a
7507 |Dictionary| with the following keys:
7508 height nr of items visible
7509 width screen cells
7510 row top screen row (0 first row)
7511 col leftmost screen column (0 first col)
7512 size total nr of items
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007513 scrollbar |TRUE| if scrollbar is visible
Bram Moolenaare9bd5722019-08-17 19:36:06 +02007514
7515 The values are the same as in |v:event| during
7516 |CompleteChanged|.
7517
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007518pumvisible() *pumvisible()*
7519 Returns non-zero when the popup menu is visible, zero
7520 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007521 This can be used to avoid some things that would remove the
7522 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007523
Bram Moolenaar30b65812012-07-12 22:01:11 +02007524py3eval({expr}) *py3eval()*
7525 Evaluate Python expression {expr} and return its result
7526 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007527 Numbers and strings are returned as they are (strings are
7528 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02007529 'encoding').
7530 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007531 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02007532 keys converted to strings.
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007533
7534 Can also be used as a |method|: >
7535 GetExpr()->py3eval()
7536
7537< {only available when compiled with the |+python3| feature}
Bram Moolenaar30b65812012-07-12 22:01:11 +02007538
7539 *E858* *E859*
7540pyeval({expr}) *pyeval()*
7541 Evaluate Python expression {expr} and return its result
7542 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007543 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02007544 copied though).
7545 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007546 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02007547 non-string keys result in error.
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007548
7549 Can also be used as a |method|: >
7550 GetExpr()->pyeval()
7551
7552< {only available when compiled with the |+python| feature}
Bram Moolenaar30b65812012-07-12 22:01:11 +02007553
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01007554pyxeval({expr}) *pyxeval()*
7555 Evaluate Python expression {expr} and return its result
7556 converted to Vim data structures.
7557 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7558 See also: |pyeval()|, |py3eval()|
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007559
7560 Can also be used as a |method|: >
7561 GetExpr()->pyxeval()
7562
7563< {only available when compiled with the |+python| or the
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01007564 |+python3| feature}
7565
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007566 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00007567range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007568 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00007569 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7570 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7571 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7572 {max}] (increasing {expr} with {stride} each time, not
7573 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00007574 When the maximum is one before the start the result is an
7575 empty list. When the maximum is more than one before the
7576 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00007577 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007578 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00007579 range(2, 4) " [2, 3, 4]
7580 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007581 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00007582 range(0) " []
7583 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00007584<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007585 Can also be used as a |method|: >
7586 GetExpr()->range()
7587<
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007588 *readdir()*
7589readdir({directory} [, {expr}])
7590 Return a list with file and directory names in {directory}.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007591 You can also use |glob()| if you don't need to do complicated
7592 things, such as limiting the number of matches.
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007593
7594 When {expr} is omitted all entries are included.
7595 When {expr} is given, it is evaluated to check what to do:
7596 If {expr} results in -1 then no further entries will
7597 be handled.
7598 If {expr} results in 0 then this entry will not be
7599 added to the list.
7600 If {expr} results in 1 then this entry will be added
7601 to the list.
7602 Each time {expr} is evaluated |v:val| is set to the entry name.
7603 When {expr} is a function the name is passed as the argument.
7604 For example, to get a list of files ending in ".txt": >
7605 readdir(dirname, {n -> n =~ '.txt$'})
7606< To skip hidden and backup files: >
7607 readdir(dirname, {n -> n !~ '^\.\|\~$'})
7608
7609< If you want to get a directory tree: >
7610 function! s:tree(dir)
7611 return {a:dir : map(readdir(a:dir),
7612 \ {_, x -> isdirectory(x) ?
7613 \ {x : s:tree(a:dir . '/' . x)} : x})}
7614 endfunction
7615 echo s:tree(".")
7616<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007617 Can also be used as a |method|: >
7618 GetDirName()->readdir()
7619<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007620 *readfile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007621readfile({fname} [, {type} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007622 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02007623 as an item. Lines are broken at NL characters. Macintosh
7624 files separated with CR will result in a single long line
7625 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02007626 All NUL characters are replaced with a NL character.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007627 When {type} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007628 - When the last line ends in a NL an extra empty list item is
7629 added.
7630 - No CR characters are removed.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007631 When {type} contains "B" a |Blob| is returned with the binary
7632 data of the file unmodified.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007633 Otherwise:
7634 - CR characters that appear before a NL are removed.
7635 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02007636 - When 'encoding' is Unicode any UTF-8 byte order mark is
7637 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007638 When {max} is given this specifies the maximum number of lines
7639 to be read. Useful if you only want to check the first ten
7640 lines of a file: >
7641 :for line in readfile(fname, '', 10)
7642 : if line =~ 'Date' | echo line | endif
7643 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00007644< When {max} is negative -{max} lines from the end of the file
7645 are returned, or as many as there are.
7646 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007647 Note that without {max} the whole file is read into memory.
7648 Also note that there is no recognition of encoding. Read a
7649 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007650 When the file can't be opened an error message is given and
7651 the result is an empty list.
7652 Also see |writefile()|.
7653
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007654 Can also be used as a |method|: >
7655 GetFileName()->readfile()
7656
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007657reg_executing() *reg_executing()*
7658 Returns the single letter name of the register being executed.
7659 Returns an empty string when no register is being executed.
7660 See |@|.
7661
7662reg_recording() *reg_recording()*
7663 Returns the single letter name of the register being recorded.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007664 Returns an empty string when not recording. See |q|.
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007665
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007666reltime([{start} [, {end}]]) *reltime()*
7667 Return an item that represents a time value. The format of
7668 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02007669 |reltimestr()| to convert it to a string or |reltimefloat()|
7670 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007671 Without an argument it returns the current time.
7672 With one argument is returns the time passed since the time
7673 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007674 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007675 and {end}.
7676 The {start} and {end} arguments must be values returned by
7677 reltime().
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007678
7679 Can also be used as a |method|: >
7680 GetStart()->reltime()
7681<
Bram Moolenaardb84e452010-08-15 13:50:43 +02007682 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007683
Bram Moolenaar03413f42016-04-12 21:07:15 +02007684reltimefloat({time}) *reltimefloat()*
7685 Return a Float that represents the time value of {time}.
7686 Example: >
7687 let start = reltime()
7688 call MyFunction()
7689 let seconds = reltimefloat(reltime(start))
7690< See the note of reltimestr() about overhead.
7691 Also see |profiling|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007692
7693 Can also be used as a |method|: >
7694 reltime(start)->reltimefloat()
7695
7696< {only available when compiled with the |+reltime| feature}
Bram Moolenaar03413f42016-04-12 21:07:15 +02007697
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007698reltimestr({time}) *reltimestr()*
7699 Return a String that represents the time value of {time}.
7700 This is the number of seconds, a dot and the number of
7701 microseconds. Example: >
7702 let start = reltime()
7703 call MyFunction()
7704 echo reltimestr(reltime(start))
7705< Note that overhead for the commands will be added to the time.
7706 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007707 Leading spaces are used to make the string align nicely. You
7708 can use split() to remove it. >
7709 echo split(reltimestr(reltime(start)))[0]
7710< Also see |profiling|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007711
7712 Can also be used as a |method|: >
7713 reltime(start)->reltimestr()
7714
7715< {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007716
Bram Moolenaar071d4272004-06-13 20:20:40 +00007717 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007718remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007719 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00007720 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007721 The result must be a String or a |List|. A |List| is turned
7722 into a String by joining the items with a line break in
7723 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007724 If {idvar} is present and not empty, it is taken as the name
7725 of a variable and a {serverid} for later use with
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01007726 |remote_read()| is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007727 If {timeout} is given the read times out after this many
7728 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007729 See also |clientserver| |RemoteReply|.
7730 This function is not available in the |sandbox|.
7731 {only available when compiled with the |+clientserver| feature}
7732 Note: Any errors will cause a local error message to be issued
7733 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01007734
7735 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007736 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01007737 when in debug mode, then local function variables and
7738 arguments can be evaluated.
7739
Bram Moolenaar071d4272004-06-13 20:20:40 +00007740 Examples: >
7741 :echo remote_expr("gvim", "2+2")
7742 :echo remote_expr("gvim1", "b:current_syntax")
7743<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007744 Can also be used as a |method|: >
7745 ServerName()->remote_expr(expr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007746
7747remote_foreground({server}) *remote_foreground()*
7748 Move the Vim server with the name {server} to the foreground.
7749 This works like: >
7750 remote_expr({server}, "foreground()")
7751< Except that on Win32 systems the client does the work, to work
7752 around the problem that the OS doesn't always allow the server
7753 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00007754 Note: This does not restore the window if it was minimized,
7755 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007756 This function is not available in the |sandbox|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007757
7758 Can also be used as a |method|: >
7759 ServerName()->remote_foreground()
7760
7761< {only in the Win32, Athena, Motif and GTK GUI versions and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007762 Win32 console version}
7763
7764
7765remote_peek({serverid} [, {retvar}]) *remote_peek()*
7766 Returns a positive number if there are available strings
7767 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02007768 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007769 name of a variable.
7770 Returns zero if none are available.
7771 Returns -1 if something is wrong.
7772 See also |clientserver|.
7773 This function is not available in the |sandbox|.
7774 {only available when compiled with the |+clientserver| feature}
7775 Examples: >
7776 :let repl = ""
7777 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
7778
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007779< Can also be used as a |method|: >
7780 ServerId()->remote_peek()
7781
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007782remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007783 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007784 it. Unless a {timeout} in seconds is given, it blocks until a
7785 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007786 See also |clientserver|.
7787 This function is not available in the |sandbox|.
7788 {only available when compiled with the |+clientserver| feature}
7789 Example: >
7790 :echo remote_read(id)
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007791
7792< Can also be used as a |method|: >
7793 ServerId()->remote_read()
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794<
7795 *remote_send()* *E241*
7796remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007797 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007798 keys and the function returns immediately. At the Vim server
7799 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007800 If {idvar} is present, it is taken as the name of a variable
7801 and a {serverid} for later use with remote_read() is stored
7802 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007803 See also |clientserver| |RemoteReply|.
7804 This function is not available in the |sandbox|.
7805 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007806
Bram Moolenaar071d4272004-06-13 20:20:40 +00007807 Note: Any errors will be reported in the server and may mess
7808 up the display.
7809 Examples: >
7810 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
7811 \ remote_read(serverid)
7812
7813 :autocmd NONE RemoteReply *
7814 \ echo remote_read(expand("<amatch>"))
7815 :echo remote_send("gvim", ":sleep 10 | echo ".
7816 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007817<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007818 Can also be used as a |method|: >
7819 ServerName()->remote_send(keys)
7820<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007821 *remote_startserver()* *E941* *E942*
7822remote_startserver({name})
7823 Become the server {name}. This fails if already running as a
7824 server, when |v:servername| is not empty.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007825
7826 Can also be used as a |method|: >
7827 ServerName()->remote_startserver()
7828
7829< {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007830
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007831remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007832 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007833 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007834 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007835 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007836 item as {end} a list with one item is returned. When {end}
7837 points to an item before {idx} this is an error.
7838 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007839 Example: >
7840 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007841 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007842<
7843 Use |delete()| to remove a file.
7844
Bram Moolenaarac92e252019-08-03 21:58:38 +02007845 Can also be used as a |method|: >
7846 mylist->remove(idx)
7847
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007848remove({blob}, {idx} [, {end}])
7849 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7850 return the byte.
7851 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7852 return a |Blob| with these bytes. When {idx} points to the same
7853 byte as {end} a |Blob| with one byte is returned. When {end}
7854 points to a byte before {idx} this is an error.
7855 Example: >
7856 :echo "last byte: " . remove(myblob, -1)
7857 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007858
Bram Moolenaard8b02732005-01-14 21:48:43 +00007859remove({dict}, {key})
Bram Moolenaar54775062019-07-31 21:07:14 +02007860 Remove the entry from {dict} with key {key} and return it.
7861 Example: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00007862 :echo "removed " . remove(dict, "one")
7863< If there is no {key} in {dict} this is an error.
7864
Bram Moolenaar071d4272004-06-13 20:20:40 +00007865rename({from}, {to}) *rename()*
7866 Rename the file by the name {from} to the name {to}. This
7867 should also work to move files across file systems. The
7868 result is a Number, which is 0 if the file was renamed
7869 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00007870 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007871 This function is not available in the |sandbox|.
7872
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007873 Can also be used as a |method|: >
7874 GetOldName()->rename(newname)
7875
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007876repeat({expr}, {count}) *repeat()*
7877 Repeat {expr} {count} times and return the concatenated
7878 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007879 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007880< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007881 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02007882 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007883 :let longlist = repeat(['a', 'b'], 3)
7884< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007885
Bram Moolenaarac92e252019-08-03 21:58:38 +02007886 Can also be used as a |method|: >
7887 mylist->repeat(count)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007888
Bram Moolenaar071d4272004-06-13 20:20:40 +00007889resolve({filename}) *resolve()* *E655*
7890 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7891 returns the path the shortcut points to in a simplified form.
Bram Moolenaardce1e892019-02-10 23:18:53 +01007892 When {filename} is a symbolic link or junction point, return
7893 the full path to the target. If the target of junction is
7894 removed, return {filename}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007895 On Unix, repeat resolving symbolic links in all path
7896 components of {filename} and return the simplified result.
7897 To cope with link cycles, resolving of symbolic links is
7898 stopped after 100 iterations.
7899 On other systems, return the simplified {filename}.
7900 The simplification step is done as by |simplify()|.
7901 resolve() keeps a leading path component specifying the
7902 current directory (provided the result is still a relative
7903 path name) and also keeps a trailing path separator.
7904
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007905 Can also be used as a |method|: >
7906 GetName()->resolve()
Bram Moolenaarac92e252019-08-03 21:58:38 +02007907
7908reverse({object}) *reverse()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007909 Reverse the order of items in {object} in-place.
7910 {object} can be a |List| or a |Blob|.
7911 Returns {object}.
7912 If you want an object to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007913 :let revlist = reverse(copy(mylist))
Bram Moolenaarac92e252019-08-03 21:58:38 +02007914< Can also be used as a |method|: >
7915 mylist->reverse()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007916
Bram Moolenaar446cb832008-06-24 21:56:24 +00007917round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007918 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00007919 as a |Float|. If {expr} lies halfway between two integral
7920 values, then use the larger one (away from zero).
7921 {expr} must evaluate to a |Float| or a |Number|.
7922 Examples: >
7923 echo round(0.456)
7924< 0.0 >
7925 echo round(4.5)
7926< 5.0 >
7927 echo round(-4.5)
7928< -5.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02007929
7930 Can also be used as a |method|: >
7931 Compute()->round()
7932<
Bram Moolenaar446cb832008-06-24 21:56:24 +00007933 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007934
Bram Moolenaare99be0e2019-03-26 22:51:09 +01007935rubyeval({expr}) *rubyeval()*
7936 Evaluate Ruby expression {expr} and return its result
7937 converted to Vim data structures.
7938 Numbers, floats and strings are returned as they are (strings
7939 are copied though).
7940 Arrays are represented as Vim |List| type.
7941 Hashes are represented as Vim |Dictionary| type.
7942 Other objects are represented as strings resulted from their
7943 "Object#to_s" method.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02007944
7945 Can also be used as a |method|: >
7946 GetRubyExpr()->rubyeval()
7947
7948< {only available when compiled with the |+ruby| feature}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01007949
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007950screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02007951 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02007952 arbitrary number that can only be used to compare to the
7953 attribute at other positions.
7954
Bram Moolenaar196b4662019-09-06 21:34:30 +02007955 Can also be used as a |method|: >
7956 GetRow()->screenattr(col)
7957
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007958screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02007959 The result is a Number, which is the character at position
7960 [row, col] on the screen. This works for every possible
7961 screen position, also status lines, window separators and the
7962 command line. The top left position is row one, column one
7963 The character excludes composing characters. For double-byte
7964 encodings it may only be the first byte.
7965 This is mainly to be used for testing.
7966 Returns -1 when row or col is out of range.
7967
Bram Moolenaar196b4662019-09-06 21:34:30 +02007968 Can also be used as a |method|: >
7969 GetRow()->screenchar(col)
7970
Bram Moolenaar2912abb2019-03-29 14:16:42 +01007971screenchars({row}, {col}) *screenchars()*
7972 The result is a List of Numbers. The first number is the same
7973 as what |screenchar()| returns. Further numbers are
7974 composing characters on top of the base character.
7975 This is mainly to be used for testing.
7976 Returns an empty List when row or col is out of range.
7977
Bram Moolenaar196b4662019-09-06 21:34:30 +02007978 Can also be used as a |method|: >
7979 GetRow()->screenchars(col)
7980
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007981screencol() *screencol()*
7982 The result is a Number, which is the current screen column of
7983 the cursor. The leftmost column has number 1.
7984 This function is mainly used for testing.
7985
7986 Note: Always returns the current screen column, thus if used
7987 in a command (e.g. ":echo screencol()") it will return the
7988 column inside the command line, which is 1 when the command is
7989 executed. To get the cursor position in the file use one of
7990 the following mappings: >
7991 nnoremap <expr> GG ":echom ".screencol()."\n"
7992 nnoremap <silent> GG :echom screencol()<CR>
7993<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02007994screenpos({winid}, {lnum}, {col}) *screenpos()*
7995 The result is a Dict with the screen position of the text
7996 character in window {winid} at buffer line {lnum} and column
7997 {col}. {col} is a one-based byte index.
7998 The Dict has these members:
7999 row screen row
8000 col first screen column
8001 endcol last screen column
8002 curscol cursor screen column
8003 If the specified position is not visible, all values are zero.
8004 The "endcol" value differs from "col" when the character
8005 occupies more than one screen cell. E.g. for a Tab "col" can
8006 be 1 and "endcol" can be 8.
8007 The "curscol" value is where the cursor would be placed. For
8008 a Tab it would be the same as "endcol", while for a double
8009 width character it would be the same as "col".
8010
Bram Moolenaar196b4662019-09-06 21:34:30 +02008011 Can also be used as a |method|: >
8012 GetWinid()->screenpos(lnum, col)
8013
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008014screenrow() *screenrow()*
8015 The result is a Number, which is the current screen row of the
8016 cursor. The top line has number one.
8017 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02008018 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008019
8020 Note: Same restrictions as with |screencol()|.
8021
Bram Moolenaar2912abb2019-03-29 14:16:42 +01008022screenstring({row}, {col}) *screenstring()*
8023 The result is a String that contains the base character and
8024 any composing characters at position [row, col] on the screen.
8025 This is like |screenchars()| but returning a String with the
8026 characters.
8027 This is mainly to be used for testing.
8028 Returns an empty String when row or col is out of range.
8029
Bram Moolenaar196b4662019-09-06 21:34:30 +02008030 Can also be used as a |method|: >
8031 GetRow()->screenstring(col)
8032
Bram Moolenaar76929292008-01-06 19:07:36 +00008033search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008034 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00008035 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008036
Bram Moolenaar2df58b42012-11-28 18:21:11 +01008037 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008038 If there is no match a 0 is returned and the cursor doesn't
8039 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008040
Bram Moolenaar071d4272004-06-13 20:20:40 +00008041 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01008042 'b' search Backward instead of forward
8043 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008044 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00008045 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01008046 'p' return number of matching sub-Pattern (see below)
8047 's' Set the ' mark at the previous location of the cursor
8048 'w' Wrap around the end of the file
8049 'W' don't Wrap around the end of the file
8050 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00008051 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
8052
Bram Moolenaar02743632005-07-25 20:42:36 +00008053 If the 's' flag is supplied, the ' mark is set, only if the
8054 cursor is moved. The 's' flag cannot be combined with the 'n'
8055 flag.
8056
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008057 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008058
Bram Moolenaar85084ef2016-01-17 22:26:33 +01008059 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01008060 column zero and then matches before the cursor are skipped.
8061 When the 'c' flag is present in 'cpo' the next search starts
8062 after the match. Without the 'c' flag the next search starts
8063 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008064
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008065 When the {stopline} argument is given then the search stops
8066 after searching this line. This is useful to restrict the
8067 search to a range of lines. Examples: >
8068 let match = search('(', 'b', line("w0"))
8069 let end = search('END', '', line("w$"))
8070< When {stopline} is used and it is not zero this also implies
8071 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00008072 A zero value is equal to not giving the argument.
8073
8074 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02008075 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00008076 {timeout} is 500 the search stops after half a second.
8077 The value must not be negative. A zero value is like not
8078 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02008079 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008080
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008081 *search()-sub-match*
8082 With the 'p' flag the returned value is one more than the
8083 first sub-match in \(\). One if none of them matched but the
8084 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008085 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008086
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008087 The cursor will be positioned at the match, unless the 'n'
8088 flag is used.
8089
Bram Moolenaar071d4272004-06-13 20:20:40 +00008090 Example (goes over all files in the argument list): >
8091 :let n = 1
8092 :while n <= argc() " loop over all files in arglist
8093 : exe "argument " . n
8094 : " start at the last char in the file and wrap for the
8095 : " first search to find match at start of file
8096 : normal G$
8097 : let flags = "w"
8098 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00008099 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00008100 : let flags = "W"
8101 : endwhile
8102 : update " write the file if modified
8103 : let n = n + 1
8104 :endwhile
8105<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008106 Example for using some flags: >
8107 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
8108< This will search for the keywords "if", "else", and "endif"
8109 under or after the cursor. Because of the 'p' flag, it
8110 returns 1, 2, or 3 depending on which keyword is found, or 0
8111 if the search fails. With the cursor on the first word of the
8112 line:
8113 if (foo == 0) | let foo = foo + 1 | endif ~
8114 the function returns 1. Without the 'c' flag, the function
8115 finds the "endif" and returns 3. The same thing happens
8116 without the 'e' flag if the cursor is on the "f" of "if".
8117 The 'n' flag tells the function not to move the cursor.
8118
Bram Moolenaar196b4662019-09-06 21:34:30 +02008119 Can also be used as a |method|: >
8120 GetPattern()->search()
Bram Moolenaar92d640f2005-09-05 22:11:52 +00008121
Bram Moolenaarf75a9632005-09-13 21:20:47 +00008122searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
8123 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008124
Bram Moolenaarf75a9632005-09-13 21:20:47 +00008125 With a non-zero {global} argument it works like |gD|, find
8126 first match in the file. Otherwise it works like |gd|, find
8127 first match in the function.
8128
8129 With a non-zero {thisblock} argument matches in a {} block
8130 that ends before the cursor position are ignored. Avoids
8131 finding variable declarations only valid in another scope.
8132
Bram Moolenaar92d640f2005-09-05 22:11:52 +00008133 Moves the cursor to the found match.
8134 Returns zero for success, non-zero for failure.
8135 Example: >
8136 if searchdecl('myvar') == 0
8137 echo getline('.')
8138 endif
8139<
Bram Moolenaar196b4662019-09-06 21:34:30 +02008140 Can also be used as a |method|: >
8141 GetName()->searchdecl()
8142<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008143 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00008144searchpair({start}, {middle}, {end} [, {flags} [, {skip}
8145 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00008146 Search for the match of a nested start-end pair. This can be
8147 used to find the "endif" that matches an "if", while other
8148 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008149 The search starts at the cursor. The default is to search
8150 forward, include 'b' in {flags} to search backward.
8151 If a match is found, the cursor is positioned at it and the
8152 line number is returned. If no match is found 0 or -1 is
8153 returned and the cursor doesn't move. No error message is
8154 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008155
8156 {start}, {middle} and {end} are patterns, see |pattern|. They
8157 must not contain \( \) pairs. Use of \%( \) is allowed. When
8158 {middle} is not empty, it is found when searching from either
8159 direction, but only when not in a nested start-end pair. A
8160 typical use is: >
8161 searchpair('\<if\>', '\<else\>', '\<endif\>')
8162< By leaving {middle} empty the "else" is skipped.
8163
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008164 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
8165 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008166 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008167 outer pair. Implies the 'W' flag.
8168 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008169 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008170 Note: it's nearly always a good idea to use the 'W' flag, to
8171 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008172
8173 When a match for {start}, {middle} or {end} is found, the
8174 {skip} expression is evaluated with the cursor positioned on
8175 the start of the match. It should return non-zero if this
8176 match is to be skipped. E.g., because it is inside a comment
8177 or a string.
8178 When {skip} is omitted or empty, every match is accepted.
8179 When evaluating {skip} causes an error the search is aborted
8180 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01008181 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar675e8d62018-06-24 20:42:01 +02008182 Anything else makes the function fail.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008183
Bram Moolenaar76929292008-01-06 19:07:36 +00008184 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008185
Bram Moolenaar071d4272004-06-13 20:20:40 +00008186 The value of 'ignorecase' is used. 'magic' is ignored, the
8187 patterns are used like it's on.
8188
8189 The search starts exactly at the cursor. A match with
8190 {start}, {middle} or {end} at the next character, in the
8191 direction of searching, is the first one found. Example: >
8192 if 1
8193 if 2
8194 endif 2
8195 endif 1
8196< When starting at the "if 2", with the cursor on the "i", and
8197 searching forwards, the "endif 2" is found. When starting on
8198 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02008199 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008200 then this is considered to be a nested if/endif from "if 2" to
8201 "endif 2".
8202 When searching backwards and {end} is more than one character,
8203 it may be useful to put "\zs" at the end of the pattern, so
8204 that when the cursor is inside a match with the end it finds
8205 the matching start.
8206
8207 Example, to find the "endif" command in a Vim script: >
8208
8209 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
8210 \ 'getline(".") =~ "^\\s*\""')
8211
8212< The cursor must be at or after the "if" for which a match is
8213 to be found. Note that single-quote strings are used to avoid
8214 having to double the backslashes. The skip expression only
8215 catches comments at the start of a line, not after a command.
8216 Also, a word "en" or "if" halfway a line is considered a
8217 match.
8218 Another example, to search for the matching "{" of a "}": >
8219
8220 :echo searchpair('{', '', '}', 'bW')
8221
8222< This works when the cursor is at or before the "}" for which a
8223 match is to be found. To reject matches that syntax
8224 highlighting recognized as strings: >
8225
8226 :echo searchpair('{', '', '}', 'bW',
8227 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
8228<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008229 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00008230searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
8231 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008232 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008233 column position of the match. The first element of the |List|
8234 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008235 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008236 returns [0, 0]. >
8237
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008238 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
8239<
8240 See |match-parens| for a bigger and more useful example.
8241
Bram Moolenaar76929292008-01-06 19:07:36 +00008242searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008243 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008244 column position of the match. The first element of the |List|
8245 is the line number and the second element is the byte index of
8246 the column position of the match. If no match is found,
8247 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008248 Example: >
8249 :let [lnum, col] = searchpos('mypattern', 'n')
8250
8251< When the 'p' flag is given then there is an extra item with
8252 the sub-pattern match number |search()-sub-match|. Example: >
8253 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
8254< In this example "submatch" is 2 when a lowercase letter is
8255 found |/\l|, 3 when an uppercase letter is found |/\u|.
8256
Bram Moolenaar196b4662019-09-06 21:34:30 +02008257 Can also be used as a |method|: >
8258 GetPattern()->searchpos()
8259
Bram Moolenaar81edd172016-04-14 13:51:37 +02008260server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008261 Send a reply string to {clientid}. The most recent {clientid}
8262 that sent a string can be retrieved with expand("<client>").
8263 {only available when compiled with the |+clientserver| feature}
8264 Note:
8265 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008266 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008267 before calling any commands that waits for input.
8268 See also |clientserver|.
8269 Example: >
8270 :echo server2client(expand("<client>"), "HELLO")
Bram Moolenaar196b4662019-09-06 21:34:30 +02008271
8272< Can also be used as a |method|: >
8273 GetClientId()->server2client(string)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008274<
8275serverlist() *serverlist()*
8276 Return a list of available server names, one per line.
8277 When there are no servers or the information is not available
8278 an empty string is returned. See also |clientserver|.
8279 {only available when compiled with the |+clientserver| feature}
8280 Example: >
8281 :echo serverlist()
8282<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008283setbufline({expr}, {lnum}, {text}) *setbufline()*
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008284 Set line {lnum} to {text} in buffer {expr}. This works like
8285 |setline()| for the specified buffer.
8286
8287 This function works only for loaded buffers. First call
8288 |bufload()| if needed.
8289
8290 To insert lines use |appendbufline()|.
8291 Any text properties in {lnum} are cleared.
8292
8293 {text} can be a string to set one line, or a list of strings
8294 to set multiple lines. If the list extends below the last
8295 line then those lines are added.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008296
8297 For the use of {expr}, see |bufname()| above.
8298
8299 {lnum} is used like with |setline()|.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008300 When {lnum} is just below the last line the {text} will be
8301 added below the last line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008302
Bram Moolenaar6bf2c622019-07-04 17:12:09 +02008303 When {expr} is not a valid buffer, the buffer is not loaded or
8304 {lnum} is not valid then 1 is returned. On success 0 is
8305 returned.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008306
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008307 Can also be used as a |method|, the base is passed as the
8308 third argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02008309 GetText()->setbufline(buf, lnum)
8310
Bram Moolenaar071d4272004-06-13 20:20:40 +00008311setbufvar({expr}, {varname}, {val}) *setbufvar()*
8312 Set option or local variable {varname} in buffer {expr} to
8313 {val}.
8314 This also works for a global or local window option, but it
8315 doesn't work for a global or local window variable.
8316 For a local window option the global value is unchanged.
8317 For the use of {expr}, see |bufname()| above.
8318 Note that the variable name without "b:" must be used.
8319 Examples: >
8320 :call setbufvar(1, "&mod", 1)
8321 :call setbufvar("todo", "myvar", "foobar")
8322< This function is not available in the |sandbox|.
8323
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008324 Can also be used as a |method|, the base is passed as the
8325 third argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02008326 GetValue()->setbufvar(buf, varname)
8327
Bram Moolenaar12969c02015-09-08 23:36:10 +02008328setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02008329 Set the current character search information to {dict},
8330 which contains one or more of the following entries:
8331
8332 char character which will be used for a subsequent
8333 |,| or |;| command; an empty string clears the
8334 character search
8335 forward direction of character search; 1 for forward,
8336 0 for backward
8337 until type of character search; 1 for a |t| or |T|
8338 character search, 0 for an |f| or |F|
8339 character search
8340
8341 This can be useful to save/restore a user's character search
8342 from a script: >
8343 :let prevsearch = getcharsearch()
8344 :" Perform a command which clobbers user's search
8345 :call setcharsearch(prevsearch)
8346< Also see |getcharsearch()|.
8347
Bram Moolenaar196b4662019-09-06 21:34:30 +02008348 Can also be used as a |method|: >
8349 SavedSearch()->setcharsearch()
8350
Bram Moolenaar071d4272004-06-13 20:20:40 +00008351setcmdpos({pos}) *setcmdpos()*
8352 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02008353 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008354 Use |getcmdpos()| to obtain the current position.
8355 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00008356 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
8357 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
8358 set after the command line is set to the expression. For
8359 |c_CTRL-R_=| it is set after evaluating the expression but
8360 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008361 When the number is too big the cursor is put at the end of the
8362 line. A number smaller than one has undefined results.
8363 Returns 0 when successful, 1 when not editing the command
8364 line.
8365
Bram Moolenaar196b4662019-09-06 21:34:30 +02008366 Can also be used as a |method|: >
8367 GetPos()->setcmdpos()
8368
Bram Moolenaar691ddee2019-05-09 14:52:41 +02008369setenv({name}, {val}) *setenv()*
8370 Set environment variable {name} to {val}.
8371 When {val} is |v:null| the environment variable is deleted.
8372 See also |expr-env|.
8373
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008374 Can also be used as a |method|, the base is passed as the
8375 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02008376 GetPath()->setenv('PATH')
8377
Bram Moolenaar80492532016-03-08 17:08:53 +01008378setfperm({fname}, {mode}) *setfperm()* *chmod*
8379 Set the file permissions for {fname} to {mode}.
8380 {mode} must be a string with 9 characters. It is of the form
8381 "rwxrwxrwx", where each group of "rwx" flags represent, in
8382 turn, the permissions of the owner of the file, the group the
8383 file belongs to, and other users. A '-' character means the
8384 permission is off, any other character means on. Multi-byte
8385 characters are not supported.
8386
8387 For example "rw-r-----" means read-write for the user,
8388 readable by the group, not accessible by others. "xx-x-----"
8389 would do the same thing.
8390
8391 Returns non-zero for success, zero for failure.
8392
Bram Moolenaar4c313b12019-08-24 22:58:31 +02008393 Can also be used as a |method|: >
8394 GetFilename()->setfperm(mode)
8395<
Bram Moolenaar80492532016-03-08 17:08:53 +01008396 To read permissions see |getfperm()|.
8397
8398
Bram Moolenaar446cb832008-06-24 21:56:24 +00008399setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008400 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008401 lines use |append()|. To set lines in another buffer use
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008402 |setbufline()|. Any text properties in {lnum} are cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008403
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008404 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008405 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008406 added below the last line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008407
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008408 If this succeeds, 0 is returned. If this fails (most likely
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008409 because {lnum} is invalid) 1 is returned.
8410
8411 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008412 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008413
Bram Moolenaar446cb832008-06-24 21:56:24 +00008414< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008415 will be set to the items in the list. Example: >
8416 :call setline(5, ['aaa', 'bbb', 'ccc'])
8417< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02008418 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008419 : call setline(n, l)
8420 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008421
Bram Moolenaar071d4272004-06-13 20:20:40 +00008422< Note: The '[ and '] marks are not set.
8423
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008424 Can also be used as a |method|, the base is passed as the
8425 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02008426 GetText()->setline(lnum)
8427
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008428setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00008429 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008430 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02008431 When {nr} is zero the current window is used.
8432
8433 For a location list window, the displayed location list is
8434 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00008435 Otherwise, same as |setqflist()|.
8436 Also see |location-list|.
8437
Bram Moolenaard823fa92016-08-12 16:29:27 +02008438 If the optional {what} dictionary argument is supplied, then
8439 only the items listed in {what} are set. Refer to |setqflist()|
8440 for the list of supported keys in {what}.
8441
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008442 Can also be used as a |method|, the base is passed as the
8443 second argument: >
8444 GetLoclist()->setloclist(winnr)
8445
Bram Moolenaaraff74912019-03-30 18:11:49 +01008446setmatches({list} [, {win}]) *setmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01008447 Restores a list of matches saved by |getmatches() for the
8448 current window|. Returns 0 if successful, otherwise -1. All
8449 current matches are cleared before the list is restored. See
8450 example for |getmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01008451 If {win} is specified, use the window with this number or
8452 window ID instead of the current window.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008453
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008454 Can also be used as a |method|: >
8455 GetMatches()->setmatches()
8456<
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008457 *setpos()*
8458setpos({expr}, {list})
8459 Set the position for {expr}. Possible values:
8460 . the cursor
8461 'x mark x
8462
Bram Moolenaar493c1782014-05-28 14:34:46 +02008463 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008464 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02008465 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008466
Bram Moolenaar58b85342016-08-14 19:54:54 +02008467 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01008468 current buffer. When setting an uppercase mark "bufnum" is
8469 used for the mark position. For other marks it specifies the
8470 buffer to set the mark in. You can use the |bufnr()| function
8471 to turn a file name into a buffer number.
8472 For setting the cursor and the ' mark "bufnum" is ignored,
8473 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00008474 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008475
8476 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008477 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8478 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008479
8480 The "off" number is only used when 'virtualedit' is set. Then
8481 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008482 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008483 character.
8484
Bram Moolenaar493c1782014-05-28 14:34:46 +02008485 The "curswant" number is only used when setting the cursor
8486 position. It sets the preferred column for when moving the
8487 cursor vertically. When the "curswant" number is missing the
8488 preferred column is not set. When it is present and setting a
8489 mark position it is not used.
8490
Bram Moolenaardfb18412013-12-11 18:53:29 +01008491 Note that for '< and '> changing the line number may result in
8492 the marks to be effectively be swapped, so that '< is always
8493 before '>.
8494
Bram Moolenaar08250432008-02-13 11:42:46 +00008495 Returns 0 when the position could be set, -1 otherwise.
8496 An error message is given if {expr} is invalid.
8497
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02008498 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008499
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008500 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02008501 vertically; if you set the cursor position with this, |j| and
8502 |k| motions will jump to previous columns! Use |cursor()| to
8503 also set the preferred column. Also see the "curswant" key in
8504 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008505
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008506 Can also be used as a |method|: >
8507 GetPosition()->setpos('.')
8508
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008509setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02008510 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008511
Bram Moolenaarae338332017-08-11 20:25:26 +02008512 When {what} is not present, use the items in {list}. Each
8513 item must be a dictionary. Non-dictionary items in {list} are
8514 ignored. Each dictionary item can contain the following
8515 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008516
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008517 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00008518 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008519 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00008520 present or it is invalid.
Bram Moolenaard76ce852018-05-01 15:02:04 +02008521 module name of a module; if given it will be used in
8522 quickfix error window instead of the filename.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008523 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008524 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008525 col column number
8526 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008527 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00008528 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008529 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008530 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008531 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008532
Bram Moolenaar582fd852005-03-28 20:58:01 +00008533 The "col", "vcol", "nr", "type" and "text" entries are
8534 optional. Either "lnum" or "pattern" entry can be used to
8535 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008536 If the "filename" and "bufnr" entries are not present or
8537 neither the "lnum" or "pattern" entries are present, then the
8538 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008539 If both "pattern" and "lnum" are present then "pattern" will
8540 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008541 If the "valid" entry is not supplied, then the valid flag is
8542 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008543 If you supply an empty {list}, the quickfix list will be
8544 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008545 Note that the list is not exactly the same as what
8546 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008547
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008548 {action} values: *E927*
8549 'a' The items from {list} are added to the existing
8550 quickfix list. If there is no existing list, then a
8551 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008552
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008553 'r' The items from the current quickfix list are replaced
8554 with the items from {list}. This can also be used to
8555 clear the list: >
8556 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008557<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008558 'f' All the quickfix lists in the quickfix stack are
8559 freed.
8560
Bram Moolenaar511972d2016-06-04 18:09:59 +02008561 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02008562 is created. The new quickfix list is added after the current
8563 quickfix list in the stack and all the following lists are
8564 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02008565 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00008566
Bram Moolenaard823fa92016-08-12 16:29:27 +02008567 If the optional {what} dictionary argument is supplied, then
8568 only the items listed in {what} are set. The first {list}
8569 argument is ignored. The following items can be specified in
8570 {what}:
Bram Moolenaar15142e22018-04-30 22:19:58 +02008571 context quickfix list context. See |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02008572 efm errorformat to use when parsing text from
8573 "lines". If this is not present, then the
8574 'errorformat' option value is used.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008575 See |quickfix-parse|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008576 id quickfix list identifier |quickfix-ID|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008577 idx index of the current entry in the quickfix
8578 list specified by 'id' or 'nr'. If set to '$',
8579 then the last entry in the list is set as the
8580 current entry. See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02008581 items list of quickfix entries. Same as the {list}
8582 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008583 lines use 'errorformat' to parse a list of lines and
8584 add the resulting entries to the quickfix list
8585 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008586 See |quickfix-parse|
Bram Moolenaar875feea2017-06-11 16:07:51 +02008587 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02008588 means the current quickfix list and "$" means
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008589 the last quickfix list.
8590 title quickfix list title text. See |quickfix-title|
Bram Moolenaard823fa92016-08-12 16:29:27 +02008591 Unsupported keys in {what} are ignored.
8592 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02008593 is modified. When creating a new quickfix list, "nr" can be
8594 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008595 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02008596 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008597 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02008598
Bram Moolenaar15142e22018-04-30 22:19:58 +02008599 Examples (See also |setqflist-examples|): >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008600 :call setqflist([], 'r', {'title': 'My search'})
8601 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
Bram Moolenaar15142e22018-04-30 22:19:58 +02008602 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02008603<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008604 Returns zero for success, -1 for failure.
8605
8606 This function can be used to create a quickfix list
8607 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02008608 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008609
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008610 Can also be used as a |method|, the base is passed as the
8611 second argument: >
8612 GetErrorlist()->setqflist()
8613<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008614 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01008615setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00008616 Set the register {regname} to {value}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008617 {value} may be any value returned by |getreg()|, including
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008618 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008619 If {options} contains "a" or {regname} is upper case,
8620 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02008621 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008622 "c" or "v" |characterwise| mode
8623 "l" or "V" |linewise| mode
8624 "b" or "<CTRL-V>" |blockwise-visual| mode
8625 If a number immediately follows "b" or "<CTRL-V>" then this is
8626 used as the width of the selection - if it is not specified
8627 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008628 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008629
8630 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008631 is to use character mode unless {value} ends in a <NL> for
8632 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008633 mode is never selected automatically.
8634 Returns zero for success, non-zero for failure.
8635
8636 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008637 Note: you may not use |List| containing more than one item to
8638 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008639 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008640
8641 Examples: >
8642 :call setreg(v:register, @*)
8643 :call setreg('*', @%, 'ac')
8644 :call setreg('a', "1\n2\n3", 'b5')
8645
8646< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008647 register: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008648 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008649 :let var_amode = getregtype('a')
8650 ....
8651 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008652< Note: you may not reliably restore register value
8653 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008654 newlines are represented as newlines AND Nul bytes are
8655 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008656
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008657 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00008658 nothing: >
8659 :call setreg('a', '', 'al')
8660
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008661< Can also be used as a |method|, the base is passed as the
8662 second argument: >
8663 GetText()->setreg('a')
8664
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008665settabvar({tabnr}, {varname}, {val}) *settabvar()*
8666 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8667 |t:var|
Bram Moolenaarb4230122019-05-30 18:40:53 +02008668 Note that autocommands are blocked, side effects may not be
8669 triggered, e.g. when setting 'filetype'.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008670 Note that the variable name without "t:" must be used.
8671 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008672 This function is not available in the |sandbox|.
8673
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008674 Can also be used as a |method|, the base is passed as the
8675 third argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008676 GetValue()->settabvar(tab, name)
8677
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008678settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8679 Set option or local variable {varname} in window {winnr} to
8680 {val}.
8681 Tabs are numbered starting with one. For the current tabpage
8682 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008683 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008684 When {winnr} is zero the current window is used.
Bram Moolenaarb4230122019-05-30 18:40:53 +02008685 Note that autocommands are blocked, side effects may not be
8686 triggered, e.g. when setting 'filetype' or 'syntax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008687 This also works for a global or local buffer option, but it
8688 doesn't work for a global or local buffer variable.
8689 For a local buffer option the global value is unchanged.
8690 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008691 Examples: >
8692 :call settabwinvar(1, 1, "&list", 0)
8693 :call settabwinvar(3, 2, "myvar", "foobar")
8694< This function is not available in the |sandbox|.
8695
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008696 Can also be used as a |method|, the base is passed as the
8697 fourth argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008698 GetValue()->settabvar(tab, winnr, name)
8699
Bram Moolenaarf49cc602018-11-11 15:21:05 +01008700settagstack({nr}, {dict} [, {action}]) *settagstack()*
8701 Modify the tag stack of the window {nr} using {dict}.
8702 {nr} can be the window number or the |window-ID|.
8703
8704 For a list of supported items in {dict}, refer to
8705 |gettagstack()|
8706 *E962*
8707 If {action} is not present or is set to 'r', then the tag
8708 stack is replaced. If {action} is set to 'a', then new entries
8709 from {dict} are pushed onto the tag stack.
8710
8711 Returns zero for success, -1 for failure.
8712
8713 Examples:
8714 Set current index of the tag stack to 4: >
8715 call settagstack(1005, {'curidx' : 4})
8716
8717< Empty the tag stack of window 3: >
8718 call settagstack(3, {'items' : []})
8719
8720< Push a new item onto the tag stack: >
8721 let pos = [bufnr('myfile.txt'), 10, 1, 0]
8722 let newtag = [{'tagname' : 'mytag', 'from' : pos}]
8723 call settagstack(2, {'items' : newtag}, 'a')
8724
8725< Save and restore the tag stack: >
8726 let stack = gettagstack(1003)
8727 " do something else
8728 call settagstack(1003, stack)
8729 unlet stack
8730<
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008731 Can also be used as a |method|, the base is passed as the
8732 second argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008733 GetStack()->settagstack(winnr)
8734
8735setwinvar({winnr}, {varname}, {val}) *setwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008736 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008737 Examples: >
8738 :call setwinvar(1, "&list", 0)
8739 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008740
Bram Moolenaar2e693a82019-10-16 22:35:02 +02008741< Can also be used as a |method|, the base is passed as the
8742 third argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008743 GetValue()->setwinvar(winnr, name)
8744
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008745sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01008746 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008747 checksum of {string}.
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008748
8749 Can also be used as a |method|: >
8750 GetText()->sha256()
8751
8752< {only available when compiled with the |+cryptv| feature}
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008753
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008754shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008755 Escape {string} for use as a shell command argument.
Bram Moolenaar25e42232019-08-04 15:04:10 +02008756 On MS-Windows, when 'shellslash' is not set, it will enclose
8757 {string} in double quotes and double all double quotes within
8758 {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008759 Otherwise it will enclose {string} in single quotes and
8760 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02008761
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008762 When the {special} argument is present and it's a non-zero
8763 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008764 items such as "!", "%", "#" and "<cword>" will be preceded by
8765 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008766 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008767
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008768 The "!" character will be escaped (again with a |non-zero-arg|
8769 {special}) when 'shell' contains "csh" in the tail. That is
8770 because for csh and tcsh "!" is used for history replacement
8771 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008772
8773 With a |non-zero-arg| {special} the <NL> character is also
8774 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008775 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008776
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008777 Example of use with a |:!| command: >
8778 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
8779< This results in a directory listing for the file under the
8780 cursor. Example of use with |system()|: >
8781 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01008782< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008783
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008784 Can also be used as a |method|: >
8785 GetCommand()->shellescape()
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008786
Bram Moolenaarf9514162018-11-22 03:08:29 +01008787shiftwidth([{col}]) *shiftwidth()*
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008788 Returns the effective value of 'shiftwidth'. This is the
8789 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01008790 'tabstop' value. This function was introduced with patch
Bram Moolenaarf9514162018-11-22 03:08:29 +01008791 7.3.694 in 2012, everybody should have it by now (however it
8792 did not allow for the optional {col} argument until 8.1.542).
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008793
Bram Moolenaarf9514162018-11-22 03:08:29 +01008794 When there is one argument {col} this is used as column number
8795 for which to return the 'shiftwidth' value. This matters for the
8796 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8797 no {col} argument is given, column 1 will be assumed.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008798
Bram Moolenaaraad222c2019-09-06 22:46:09 +02008799 Can also be used as a |method|: >
8800 GetColumn()->shiftwidth()
8801
Bram Moolenaared997ad2019-07-21 16:42:00 +02008802sign_ functions are documented here: |sign-functions-details|
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008803
Bram Moolenaar162b7142018-12-21 15:17:36 +01008804
Bram Moolenaar071d4272004-06-13 20:20:40 +00008805simplify({filename}) *simplify()*
8806 Simplify the file name as much as possible without changing
8807 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8808 Unix) are not resolved. If the first path component in
8809 {filename} designates the current directory, this will be
8810 valid for the result as well. A trailing path separator is
8811 not removed either.
8812 Example: >
8813 simplify("./dir/.././/file/") == "./file/"
8814< Note: The combination "dir/.." is only removed if "dir" is
8815 a searchable directory or does not exist. On Unix, it is also
8816 removed when "dir" is a symbolic link within the same
8817 directory. In order to resolve all the involved symbolic
8818 links before simplifying the path name, use |resolve()|.
8819
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008820
Bram Moolenaar446cb832008-06-24 21:56:24 +00008821sin({expr}) *sin()*
8822 Return the sine of {expr}, measured in radians, as a |Float|.
8823 {expr} must evaluate to a |Float| or a |Number|.
8824 Examples: >
8825 :echo sin(100)
8826< -0.506366 >
8827 :echo sin(-4.01)
8828< 0.763301
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02008829
8830 Can also be used as a |method|: >
8831 Compute()->sin()
8832<
Bram Moolenaar446cb832008-06-24 21:56:24 +00008833 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008834
Bram Moolenaar446cb832008-06-24 21:56:24 +00008835
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008836sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008837 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008838 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008839 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008840 Examples: >
8841 :echo sinh(0.5)
8842< 0.521095 >
8843 :echo sinh(-0.9)
8844< -1.026517
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02008845
8846 Can also be used as a |method|: >
8847 Compute()->sinh()
8848<
Bram Moolenaardb84e452010-08-15 13:50:43 +02008849 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008850
8851
Bram Moolenaar5f894962011-06-19 02:55:37 +02008852sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01008853 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008854
Bram Moolenaar327aa022014-03-25 18:24:23 +01008855 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008856 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02008857
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008858< When {func} is omitted, is empty or zero, then sort() uses the
8859 string representation of each item to sort on. Numbers sort
8860 after Strings, |Lists| after Numbers. For sorting text in the
8861 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008862
Bram Moolenaar34401cc2014-08-29 15:12:19 +02008863 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008864 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008865
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008866 When {func} is given and it is 'n' then all items will be
8867 sorted numerical (Implementation detail: This uses the
8868 strtod() function to parse numbers, Strings, Lists, Dicts and
8869 Funcrefs will be considered as being 0).
8870
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01008871 When {func} is given and it is 'N' then all items will be
8872 sorted numerical. This is like 'n' but a string containing
8873 digits will be used as the number they represent.
8874
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01008875 When {func} is given and it is 'f' then all items will be
8876 sorted numerical. All values must be a Number or a Float.
8877
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008878 When {func} is a |Funcref| or a function name, this function
8879 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008880 items as argument and must return zero if they are equal, 1 or
8881 bigger if the first one sorts after the second one, -1 or
8882 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008883
8884 {dict} is for functions with the "dict" attribute. It will be
8885 used to set the local variable "self". |Dictionary-function|
8886
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008887 The sort is stable, items which compare equal (as number or as
8888 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02008889 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008890 same order as they were originally.
8891
Bram Moolenaarac92e252019-08-03 21:58:38 +02008892 Can also be used as a |method|: >
8893 mylist->sort()
8894
8895< Also see |uniq()|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008896
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008897 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008898 func MyCompare(i1, i2)
8899 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8900 endfunc
8901 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008902< A shorter compare version for this specific simple case, which
8903 ignores overflow: >
8904 func MyCompare(i1, i2)
8905 return a:i1 - a:i2
8906 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008907<
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02008908sound_clear() *sound_clear()*
8909 Stop playing all sounds.
Bram Moolenaar9b283522019-06-17 22:19:33 +02008910 {only available when compiled with the |+sound| feature}
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02008911
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008912 *sound_playevent()*
8913sound_playevent({name} [, {callback}])
8914 Play a sound identified by {name}. Which event names are
8915 supported depends on the system. Often the XDG sound names
8916 are used. On Ubuntu they may be found in
8917 /usr/share/sounds/freedesktop/stereo. Example: >
8918 call sound_playevent('bell')
Bram Moolenaar9b283522019-06-17 22:19:33 +02008919< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
8920 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
8921 SystemStart, SystemWelcome, etc.
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008922
Bram Moolenaar9b283522019-06-17 22:19:33 +02008923 When {callback} is specified it is invoked when the sound is
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008924 finished. The first argument is the sound ID, the second
8925 argument is the status:
8926 0 sound was played to the end
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +02008927 1 sound was interrupted
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02008928 2 error occurred after sound started
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008929 Example: >
8930 func Callback(id, status)
8931 echomsg "sound " .. a:id .. " finished with " .. a:status
8932 endfunc
8933 call sound_playevent('bell', 'Callback')
8934
Bram Moolenaar9b283522019-06-17 22:19:33 +02008935< MS-Windows: {callback} doesn't work for this function.
8936
8937 Returns the sound ID, which can be passed to `sound_stop()`.
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008938 Returns zero if the sound could not be played.
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02008939
8940 Can also be used as a |method|: >
8941 GetSoundName()->sound_playevent()
8942
8943< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008944
8945 *sound_playfile()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02008946sound_playfile({path} [, {callback}])
8947 Like `sound_playevent()` but play sound file {path}. {path}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008948 must be a full path. On Ubuntu you may find files to play
8949 with this command: >
8950 :!find /usr/share/sounds -type f | grep -v index.theme
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02008951
8952< Can also be used as a |method|: >
8953 GetSoundPath()->sound_playfile()
8954
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +02008955< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008956
8957
8958sound_stop({id}) *sound_stop()*
8959 Stop playing sound {id}. {id} must be previously returned by
8960 `sound_playevent()` or `sound_playfile()`.
Bram Moolenaar9b283522019-06-17 22:19:33 +02008961
8962 On MS-Windows, this does not work for event sound started by
8963 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
8964
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02008965 Can also be used as a |method|: >
8966 soundid->sound_stop()
8967
8968< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02008969
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008970 *soundfold()*
8971soundfold({word})
8972 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00008973 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008974 soundfolding. 'spell' must be set. When no sound folding is
8975 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008976 This can be used for making spelling suggestions. Note that
8977 the method can be quite slow.
8978
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02008979 Can also be used as a |method|: >
8980 GetWord()->soundfold()
8981<
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008982 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00008983spellbadword([{sentence}])
8984 Without argument: The result is the badly spelled word under
8985 or after the cursor. The cursor is moved to the start of the
8986 bad word. When no bad word is found in the cursor line the
8987 result is an empty string and the cursor doesn't move.
8988
8989 With argument: The result is the first word in {sentence} that
8990 is badly spelled. If there are no spelling mistakes the
8991 result is an empty string.
8992
8993 The return value is a list with two items:
8994 - The badly spelled word or an empty string.
8995 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008996 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00008997 "rare" rare word
8998 "local" word only valid in another region
8999 "caps" word should start with Capital
9000 Example: >
9001 echo spellbadword("the quik brown fox")
9002< ['quik', 'bad'] ~
9003
9004 The spelling information for the current window is used. The
9005 'spell' option must be set and the value of 'spelllang' is
9006 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009007
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009008 Can also be used as a |method|: >
9009 GetText()->spellbadword()
9010<
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009011 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00009012spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009013 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009014 When {max} is given up to this number of suggestions are
9015 returned. Otherwise up to 25 suggestions are returned.
9016
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00009017 When the {capital} argument is given and it's non-zero only
9018 suggestions with a leading capital will be given. Use this
9019 after a match with 'spellcapcheck'.
9020
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009021 {word} can be a badly spelled word followed by other text.
9022 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00009023 suggestions also include the following text, thus you can
9024 replace a line.
9025
9026 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00009027 returned. {word} itself is not included in the suggestions,
9028 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009029
9030 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00009031 'spell' option must be set and the values of 'spelllang' and
9032 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00009033
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009034 Can also be used as a |method|: >
9035 GetWord()->spellsuggest()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009036
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009037split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009038 Make a |List| out of {expr}. When {pattern} is omitted or
9039 empty each white-separated sequence of characters becomes an
9040 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009041 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01009042 removing the matched characters. 'ignorecase' is not used
9043 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009044 When the first or last item is empty it is omitted, unless the
9045 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00009046 Other empty items are kept when {pattern} matches at least one
9047 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009048 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009049 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009050< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009051 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02009052< If you want to keep the separator you can also use '\zs' at
9053 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00009054 :echo split('abc:def:ghi', ':\zs')
9055< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009056 Splitting a table where the first element can be empty: >
9057 :let items = split(line, ':', 1)
9058< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009059
Bram Moolenaara74e4942019-08-04 17:35:53 +02009060 Can also be used as a |method|: >
9061 GetString()->split()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009062
Bram Moolenaar446cb832008-06-24 21:56:24 +00009063sqrt({expr}) *sqrt()*
9064 Return the non-negative square root of Float {expr} as a
9065 |Float|.
9066 {expr} must evaluate to a |Float| or a |Number|. When {expr}
9067 is negative the result is NaN (Not a Number).
9068 Examples: >
9069 :echo sqrt(100)
9070< 10.0 >
9071 :echo sqrt(-4.01)
9072< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00009073 "nan" may be different, it depends on system libraries.
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009074
9075 Can also be used as a |method|: >
9076 Compute()->sqrt()
9077<
Bram Moolenaar446cb832008-06-24 21:56:24 +00009078 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009079
Bram Moolenaar446cb832008-06-24 21:56:24 +00009080
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02009081state([{what}]) *state()*
9082 Return a string which contains characters indicating the
9083 current state. Mostly useful in callbacks that want to do
9084 work that may not always be safe. Roughly this works like:
9085 - callback uses state() to check if work is safe to do.
Bram Moolenaar589edb32019-09-20 14:38:13 +02009086 Yes: then do it right away.
9087 No: add to work queue and add a |SafeState| and/or
9088 |SafeStateAgain| autocommand (|SafeState| triggers at
9089 toplevel, |SafeStateAgain| triggers after handling
9090 messages and callbacks).
9091 - When SafeState or SafeStateAgain is triggered and executes
9092 your autocommand, check with `state()` if the work can be
9093 done now, and if yes remove it from the queue and execute.
9094 Remove the autocommand if the queue is now empty.
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02009095 Also see |mode()|.
9096
9097 When {what} is given only characters in this string will be
9098 added. E.g, this checks if the screen has scrolled: >
Bram Moolenaar589edb32019-09-20 14:38:13 +02009099 if state('s') == ''
9100 " screen has not scrolled
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02009101<
Bram Moolenaard103ee72019-09-18 21:15:31 +02009102 These characters indicate the state, generally indicating that
9103 something is busy:
Bram Moolenaar589edb32019-09-20 14:38:13 +02009104 m halfway a mapping, :normal command, feedkeys() or
9105 stuffed command
9106 o operator pending or waiting for a command argument,
9107 e.g. after |f|
9108 a Insert mode autocomplete active
9109 x executing an autocommand
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009110 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
9111 ch_readraw() when reading json.
Bram Moolenaar589edb32019-09-20 14:38:13 +02009112 S not triggering SafeState or SafeStateAgain
9113 c callback invoked, including timer (repeats for
9114 recursiveness up to "ccc")
9115 s screen has scrolled for messages
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02009116
Bram Moolenaar81edd172016-04-14 13:51:37 +02009117str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00009118 Convert String {expr} to a Float. This mostly works the same
9119 as when using a floating point number in an expression, see
9120 |floating-point-format|. But it's a bit more permissive.
9121 E.g., "1e40" is accepted, while in an expression you need to
Bram Moolenaard47d5222018-12-09 20:43:55 +01009122 write "1.0e40". The hexadecimal form "0x123" is also
9123 accepted, but not others, like binary or octal.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009124 Text after the number is silently ignored.
9125 The decimal point is always '.', no matter what the locale is
9126 set to. A comma ends the number: "12,345.67" is converted to
9127 12.0. You can strip out thousands separators with
9128 |substitute()|: >
9129 let f = str2float(substitute(text, ',', '', 'g'))
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009130<
9131 Can also be used as a |method|: >
9132 let f = text->substitute(',', '', 'g')->str2float()
9133<
9134 {only available when compiled with the |+float| feature}
Bram Moolenaar446cb832008-06-24 21:56:24 +00009135
Bram Moolenaar9d401282019-04-06 13:18:12 +02009136str2list({expr} [, {utf8}]) *str2list()*
9137 Return a list containing the number values which represent
9138 each character in String {expr}. Examples: >
9139 str2list(" ") returns [32]
9140 str2list("ABC") returns [65, 66, 67]
9141< |list2str()| does the opposite.
9142
9143 When {utf8} is omitted or zero, the current 'encoding' is used.
9144 With {utf8} set to 1, always treat the String as utf-8
9145 characters. With utf-8 composing characters are handled
9146 properly: >
9147 str2list("á") returns [97, 769]
Bram Moolenaar446cb832008-06-24 21:56:24 +00009148
Bram Moolenaara74e4942019-08-04 17:35:53 +02009149< Can also be used as a |method|: >
9150 GetString()->str2list()
9151
9152
Bram Moolenaar60a8de22019-09-15 14:33:22 +02009153str2nr({expr} [, {base} [, {quoted}]]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009154 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01009155 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar60a8de22019-09-15 14:33:22 +02009156 When {quoted} is present and non-zero then embedded single
9157 quotes are ignored, thus "1'000'000" is a million.
Bram Moolenaara74e4942019-08-04 17:35:53 +02009158
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009159 When {base} is omitted base 10 is used. This also means that
9160 a leading zero doesn't cause octal conversion to be used, as
Bram Moolenaara74e4942019-08-04 17:35:53 +02009161 with the default String to Number conversion. Example: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009162 let nr = str2nr('0123')
Bram Moolenaara74e4942019-08-04 17:35:53 +02009163<
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009164 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01009165 different base the result will be zero. Similarly, when
9166 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
9167 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009168 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009169
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009170 Can also be used as a |method|: >
9171 GetText()->str2nr()
9172
9173strcharpart({src}, {start} [, {len}]) *strcharpart()*
9174 Like |strpart()| but using character index and length instead
9175 of byte index and length.
9176 When a character index is used where a character does not
9177 exist it is assumed to be one character. For example: >
9178 strcharpart('abc', -1, 2)
9179< results in 'a'.
9180
9181 Can also be used as a |method|: >
9182 GetText()->strcharpart(5)
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009183
Bram Moolenaar979243b2015-06-26 19:35:49 +02009184strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02009185 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02009186 in String {expr}.
9187 When {skipcc} is omitted or zero, composing characters are
9188 counted separately.
9189 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02009190 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009191
Bram Moolenaar86ae7202015-07-10 19:31:35 +02009192 {skipcc} is only available after 7.4.755. For backward
9193 compatibility, you can define a wrapper function: >
9194 if has("patch-7.4.755")
9195 function s:strchars(str, skipcc)
9196 return strchars(a:str, a:skipcc)
9197 endfunction
9198 else
9199 function s:strchars(str, skipcc)
9200 if a:skipcc
9201 return strlen(substitute(a:str, ".", "x", "g"))
9202 else
9203 return strchars(a:str)
9204 endif
9205 endfunction
9206 endif
9207<
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009208 Can also be used as a |method|: >
9209 GetText()->strchars()
Bram Moolenaar86ae7202015-07-10 19:31:35 +02009210
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009211strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +02009212 The result is a Number, which is the number of display cells
Bram Moolenaar4c92e752019-02-17 21:18:32 +01009213 String {expr} occupies on the screen when it starts at {col}
9214 (first column is zero). When {col} is omitted zero is used.
9215 Otherwise it is the screen column where to start. This
9216 matters for Tab characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02009217 The option settings of the current window are used. This
9218 matters for anything that's displayed differently, such as
9219 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02009220 When {expr} contains characters with East Asian Width Class
9221 Ambiguous, this function's return value depends on 'ambiwidth'.
9222 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009223
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009224 Can also be used as a |method|: >
9225 GetText()->strdisplaywidth()
9226
Bram Moolenaar071d4272004-06-13 20:20:40 +00009227strftime({format} [, {time}]) *strftime()*
9228 The result is a String, which is a formatted date and time, as
9229 specified by the {format} string. The given {time} is used,
9230 or the current time if no time is given. The accepted
9231 {format} depends on your system, thus this is not portable!
9232 See the manual page of the C function strftime() for the
9233 format. The maximum length of the result is 80 characters.
9234 See also |localtime()| and |getftime()|.
9235 The language can be changed with the |:language| command.
9236 Examples: >
9237 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9238 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9239 :echo strftime("%y%m%d %T") 970427 11:53:55
9240 :echo strftime("%H:%M") 11:55
9241 :echo strftime("%c", getftime("file.c"))
9242 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009243< Not available on all systems. To check use: >
9244 :if exists("*strftime")
9245
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009246< Can also be used as a |method|: >
9247 GetFormat()->strftime()
9248
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009249strgetchar({str}, {index}) *strgetchar()*
9250 Get character {index} from {str}. This uses a character
9251 index, not a byte index. Composing characters are considered
9252 separate characters here.
9253 Also see |strcharpart()| and |strchars()|.
9254
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009255 Can also be used as a |method|: >
9256 GetText()->strgetchar(5)
9257
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009258stridx({haystack}, {needle} [, {start}]) *stridx()*
9259 The result is a Number, which gives the byte index in
9260 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00009261 If {start} is specified, the search starts at index {start}.
9262 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01009263 :let colon1 = stridx(line, ":")
9264 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00009265< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009266 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009267 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00009268 See also |strridx()|.
9269 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009270 :echo stridx("An Example", "Example") 3
9271 :echo stridx("Starting point", "Start") 0
9272 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009273< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00009274 stridx() works similar to the C function strstr(). When used
9275 with a single character it works similar to strchr().
9276
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009277 Can also be used as a |method|: >
9278 GetHaystack()->stridx(needle)
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009279<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009280 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009281string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01009282 Float, String, Blob or a composition of them, then the result
9283 can be parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009284 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01009285 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009286 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00009287 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00009288 Funcref function('name')
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01009289 Blob 0z00112233.44556677.8899
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009290 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00009291 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01009292
9293 When a List or Dictionary has a recursive reference it is
9294 replaced by "[...]" or "{...}". Using eval() on the result
9295 will then fail.
9296
Bram Moolenaarac92e252019-08-03 21:58:38 +02009297 Can also be used as a |method|: >
9298 mylist->string()
9299
9300< Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009301
Bram Moolenaar071d4272004-06-13 20:20:40 +00009302 *strlen()*
9303strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00009304 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009305 If the argument is a Number it is first converted to a String.
9306 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02009307 If you want to count the number of multi-byte characters use
9308 |strchars()|.
9309 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009310
Bram Moolenaara74e4942019-08-04 17:35:53 +02009311 Can also be used as a |method|: >
9312 GetString()->strlen()
9313
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009314strpart({src}, {start} [, {len}]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009315 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00009316 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009317 To count characters instead of bytes use |strcharpart()|.
9318
9319 When bytes are selected which do not exist, this doesn't
9320 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009321 If {len} is missing, the copy continues from {start} till the
9322 end of the {src}. >
9323 strpart("abcdefg", 3, 2) == "de"
9324 strpart("abcdefg", -2, 4) == "ab"
9325 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00009326 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009327
Bram Moolenaar071d4272004-06-13 20:20:40 +00009328< Note: To get the first character, {start} must be 0. For
9329 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00009330 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009331<
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009332 Can also be used as a |method|: >
9333 GetText()->strpart(5)
9334
Bram Moolenaar677ee682005-01-27 14:41:15 +00009335strridx({haystack}, {needle} [, {start}]) *strridx()*
9336 The result is a Number, which gives the byte index in
9337 {haystack} of the last occurrence of the String {needle}.
9338 When {start} is specified, matches beyond this index are
9339 ignored. This can be used to find a match before a previous
9340 match: >
9341 :let lastcomma = strridx(line, ",")
9342 :let comma2 = strridx(line, ",", lastcomma - 1)
9343< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009344 For pattern searches use |match()|.
9345 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00009346 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009347 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009348 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009349< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00009350 When used with a single character it works similar to the C
9351 function strrchr().
9352
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009353 Can also be used as a |method|: >
9354 GetHaystack()->strridx(needle)
9355
Bram Moolenaar071d4272004-06-13 20:20:40 +00009356strtrans({expr}) *strtrans()*
9357 The result is a String, which is {expr} with all unprintable
9358 characters translated into printable characters |'isprint'|.
9359 Like they are shown in a window. Example: >
9360 echo strtrans(@a)
9361< This displays a newline in register a as "^@" instead of
9362 starting a new line.
9363
Bram Moolenaara74e4942019-08-04 17:35:53 +02009364 Can also be used as a |method|: >
9365 GetString()->strtrans()
9366
Bram Moolenaar72597a52010-07-18 15:31:08 +02009367strwidth({expr}) *strwidth()*
9368 The result is a Number, which is the number of display cells
9369 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02009370 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009371 When {expr} contains characters with East Asian Width Class
9372 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02009373 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009374
Bram Moolenaara74e4942019-08-04 17:35:53 +02009375 Can also be used as a |method|: >
9376 GetString()->strwidth()
9377
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009378submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +02009379 Only for an expression in a |:substitute| command or
9380 substitute() function.
9381 Returns the {nr}'th submatch of the matched text. When {nr}
9382 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02009383 Note that a NL in the string can stand for a line break of a
9384 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009385 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02009386
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009387 If {list} is present and non-zero then submatch() returns
9388 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +02009389 NL characters in the text represent NUL characters in the
9390 text.
9391 Only returns more than one item for |:substitute|, inside
9392 |substitute()| this list will always contain one or zero
9393 items, since there are no real line breaks.
9394
Bram Moolenaar6100d022016-10-02 16:51:57 +02009395 When substitute() is used recursively only the submatches in
9396 the current (deepest) call can be obtained.
9397
Bram Moolenaar2f058492017-11-30 20:27:52 +01009398 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009399 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +01009400 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009401< This finds the first number in the line and adds one to it.
9402 A line break is included as a newline character.
9403
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009404 Can also be used as a |method|: >
9405 GetNr()->submatch()
9406
Bram Moolenaar071d4272004-06-13 20:20:40 +00009407substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
9408 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02009409 the first match of {pat} is replaced with {sub}.
9410 When {flags} is "g", all matches of {pat} in {expr} are
9411 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009412
Bram Moolenaar251e1912011-06-19 05:09:16 +02009413 This works like the ":substitute" command (without any flags).
9414 But the matching with {pat} is always done like the 'magic'
9415 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01009416 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9417 if you want to ignore or match case and ignore 'ignorecase'.
9418 'smartcase' is not used. See |string-match| for how {pat} is
9419 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009420
9421 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009422 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +02009423 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00009424 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009425
Bram Moolenaar071d4272004-06-13 20:20:40 +00009426 When {pat} does not match in {expr}, {expr} is returned
9427 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009428
Bram Moolenaar071d4272004-06-13 20:20:40 +00009429 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009430 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009431< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009432 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009433< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02009434
9435 When {sub} starts with "\=", the remainder is interpreted as
9436 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009437 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02009438 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009439
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009440< When {sub} is a Funcref that function is called, with one
9441 optional argument. Example: >
9442 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9443< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +02009444 matched string and up to nine submatches, like what
9445 |submatch()| returns. Example: >
9446 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009447
Bram Moolenaara74e4942019-08-04 17:35:53 +02009448< Can also be used as a |method|: >
9449 GetString()->substitute(pat, sub, flags)
9450
Bram Moolenaar20aac6c2018-09-02 21:07:30 +02009451swapinfo({fname}) *swapinfo()*
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009452 The result is a dictionary, which holds information about the
9453 swapfile {fname}. The available fields are:
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009454 version Vim version
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009455 user user name
9456 host host name
9457 fname original file name
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009458 pid PID of the Vim process that created the swap
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009459 file
9460 mtime last modification time in seconds
9461 inode Optional: INODE number of the file
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009462 dirty 1 if file was modified, 0 if not
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02009463 Note that "user" and "host" are truncated to at most 39 bytes.
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009464 In case of failure an "error" item is added with the reason:
9465 Cannot open file: file not found or in accessible
9466 Cannot read file: cannot read first block
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009467 Not a swap file: does not contain correct block ID
9468 Magic number mismatch: Info in first block is invalid
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009469
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009470 Can also be used as a |method|: >
9471 GetFilename()->swapinfo()
9472
Bram Moolenaar110bd602018-09-16 18:46:59 +02009473swapname({expr}) *swapname()*
9474 The result is the swap file path of the buffer {expr}.
9475 For the use of {expr}, see |bufname()| above.
9476 If buffer {expr} is the current buffer, the result is equal to
9477 |:swapname| (unless no swap file).
9478 If buffer {expr} has no swap file, returns an empty string.
9479
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +02009480 Can also be used as a |method|: >
9481 GetBufname()->swapname()
9482
Bram Moolenaar47136d72004-10-12 20:02:24 +00009483synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009484 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00009485 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009486 The syntax ID can be used with |synIDattr()| and
9487 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009488
Bram Moolenaar47136d72004-10-12 20:02:24 +00009489 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009490 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02009491 Note that when the position is after the last character,
9492 that's where the cursor can be in Insert mode, synID() returns
9493 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009494
Bram Moolenaar79815f12016-07-09 17:07:29 +02009495 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02009496 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +02009497 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +00009498 item is returned. This is useful when wanting to know which
9499 syntax item is effective (e.g. inside parens).
9500 Warning: This function can be very slow. Best speed is
9501 obtained by going through the file in forward direction.
9502
9503 Example (echoes the name of the syntax item under the cursor): >
9504 :echo synIDattr(synID(line("."), col("."), 1), "name")
9505<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02009506
Bram Moolenaar071d4272004-06-13 20:20:40 +00009507synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9508 The result is a String, which is the {what} attribute of
9509 syntax ID {synID}. This can be used to obtain information
9510 about a syntax item.
9511 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +02009512 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00009513 used, the attributes for the currently active highlighting are
9514 used (GUI, cterm or term).
9515 Use synIDtrans() to follow linked highlight groups.
9516 {what} result
9517 "name" the name of the syntax item
9518 "fg" foreground color (GUI: color name used to set
9519 the color, cterm: color number as a string,
9520 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009521 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009522 "font" font name (only available in the GUI)
9523 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009524 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009525 "fg#" like "fg", but for the GUI and the GUI is
9526 running the name in "#RRGGBB" form
9527 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009528 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009529 "bold" "1" if bold
9530 "italic" "1" if italic
9531 "reverse" "1" if reverse
9532 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009533 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00009534 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009535 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02009536 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +00009537
9538 Example (echoes the color of the syntax item under the
9539 cursor): >
9540 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9541<
Bram Moolenaara74e4942019-08-04 17:35:53 +02009542 Can also be used as a |method|: >
9543 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9544
9545
Bram Moolenaar071d4272004-06-13 20:20:40 +00009546synIDtrans({synID}) *synIDtrans()*
9547 The result is a Number, which is the translated syntax ID of
9548 {synID}. This is the syntax group ID of what is being used to
9549 highlight the character. Highlight links given with
9550 ":highlight link" are followed.
9551
Bram Moolenaara74e4942019-08-04 17:35:53 +02009552 Can also be used as a |method|: >
9553 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
9554
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009555synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaar4d785892017-06-22 22:00:50 +02009556 The result is a List with currently three items:
9557 1. The first item in the list is 0 if the character at the
9558 position {lnum} and {col} is not part of a concealable
9559 region, 1 if it is.
9560 2. The second item in the list is a string. If the first item
9561 is 1, the second item contains the text which will be
9562 displayed in place of the concealed text, depending on the
9563 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009564 3. The third and final item in the list is a number
9565 representing the specific syntax region matched in the
9566 line. When the character is not concealed the value is
9567 zero. This allows detection of the beginning of a new
9568 concealable region if there are two consecutive regions
9569 with the same replacement character. For an example, if
9570 the text is "123456" and both "23" and "45" are concealed
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009571 and replaced by the character "X", then:
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009572 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +02009573 synconcealed(lnum, 1) [0, '', 0]
9574 synconcealed(lnum, 2) [1, 'X', 1]
9575 synconcealed(lnum, 3) [1, 'X', 1]
9576 synconcealed(lnum, 4) [1, 'X', 2]
9577 synconcealed(lnum, 5) [1, 'X', 2]
9578 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009579
9580
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009581synstack({lnum}, {col}) *synstack()*
9582 Return a |List|, which is the stack of syntax items at the
9583 position {lnum} and {col} in the current window. Each item in
9584 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009585 The first item in the List is the outer region, following are
9586 items contained in that one. The last one is what |synID()|
9587 returns, unless not the whole item is highlighted or it is a
9588 transparent item.
9589 This function is useful for debugging a syntax file.
9590 Example that shows the syntax stack under the cursor: >
9591 for id in synstack(line("."), col("."))
9592 echo synIDattr(id, "name")
9593 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02009594< When the position specified with {lnum} and {col} is invalid
9595 nothing is returned. The position just after the last
9596 character in a line and the first column in an empty line are
9597 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009598
Bram Moolenaarc0197e22004-09-13 20:26:32 +00009599system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009600 Get the output of the shell command {expr} as a string. See
9601 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009602
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009603 When {input} is given and is a string this string is written
9604 to a file and passed as stdin to the command. The string is
9605 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009606 separators yourself.
9607 If {input} is given and is a |List| it is written to the file
9608 in a way |writefile()| does with {binary} set to "b" (i.e.
9609 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +01009610 list items converted to NULs).
9611 When {input} is given and is a number that is a valid id for
9612 an existing buffer then the content of the buffer is written
9613 to the file line by line, each line terminated by a NL and
9614 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02009615
9616 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009617
Bram Moolenaar04186092016-08-29 21:55:35 +02009618 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +02009619 cooked mode. This is meant to be used for commands that do
9620 not need the user to type. It avoids stray characters showing
9621 up on the screen which require |CTRL-L| to remove. >
9622 :silent let f = system('ls *.vim')
9623<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009624 Note: Use |shellescape()| or |::S| with |expand()| or
9625 |fnamemodify()| to escape special characters in a command
9626 argument. Newlines in {expr} may cause the command to fail.
9627 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +01009628 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009629 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009630
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009631 The result is a String. Example: >
9632 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01009633 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009634
9635< To make the result more system-independent, the shell output
9636 is filtered to replace <CR> with <NL> for Macintosh, and
9637 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02009638 To avoid the string being truncated at a NUL, all NUL
9639 characters are replaced with SOH (0x01).
9640
Bram Moolenaar071d4272004-06-13 20:20:40 +00009641 The command executed is constructed using several options:
9642 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9643 ({tmp} is an automatically generated file name).
9644 For Unix and OS/2 braces are put around {expr} to allow for
9645 concatenated commands.
9646
Bram Moolenaar433f7c82006-03-21 21:29:36 +00009647 The command will be executed in "cooked" mode, so that a
9648 CTRL-C will interrupt the command (on Unix at least).
9649
Bram Moolenaar071d4272004-06-13 20:20:40 +00009650 The resulting error code can be found in |v:shell_error|.
9651 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00009652
9653 Note that any wrong value in the options mentioned above may
9654 make the function fail. It has also been reported to fail
9655 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009656 Unlike ":!cmd" there is no automatic check for changed files.
9657 Use |:checktime| to force a check.
9658
Bram Moolenaara74e4942019-08-04 17:35:53 +02009659 Can also be used as a |method|: >
9660 :echo GetCmd()->system()
9661
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009662
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009663systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009664 Same as |system()|, but returns a |List| with lines (parts of
9665 output separated by NL) with NULs transformed into NLs. Output
9666 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar5be4cee2019-09-27 19:34:08 +02009667 set to "b", except that there is no extra empty item when the
9668 result ends in a NL.
9669 Note that on MS-Windows you may get trailing CR characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009670
Bram Moolenaar5be4cee2019-09-27 19:34:08 +02009671 To see the difference between "echo hello" and "echo -n hello"
9672 use |system()| and |split()|: >
9673 echo system('echo hello')->split('\n', 1)
9674<
Bram Moolenaar975b5272016-03-15 23:10:59 +01009675 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009676
Bram Moolenaara74e4942019-08-04 17:35:53 +02009677 Can also be used as a |method|: >
9678 :echo GetCmd()->systemlist()
9679
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009680
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009681tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009682 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009683 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009684 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009685 omitted the current tab page is used.
9686 When {arg} is invalid the number zero is returned.
9687 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009688 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009689 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009690 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009691 endfor
9692< Note that a buffer may appear in more than one window.
9693
Bram Moolenaarce90e362019-09-08 18:58:44 +02009694 Can also be used as a |method|: >
9695 GetTabpage()->tabpagebuflist()
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009696
9697tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00009698 The result is a Number, which is the number of the current
9699 tab page. The first tab page has number 1.
9700 When the optional argument is "$", the number of the last tab
9701 page is returned (the tab page count).
9702 The number can be used with the |:tab| command.
9703
9704
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01009705tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02009706 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009707 {tabarg} specifies the number of tab page to be used.
9708 {arg} is used like with |winnr()|:
9709 - When omitted the current window number is returned. This is
9710 the window which will be used when going to this tab page.
9711 - When "$" the number of windows is returned.
9712 - When "#" the previous window nr is returned.
9713 Useful examples: >
9714 tabpagewinnr(1) " current window of tab page 1
9715 tabpagewinnr(4, '$') " number of windows in tab page 4
9716< When {tabarg} is invalid zero is returned.
9717
Bram Moolenaarce90e362019-09-08 18:58:44 +02009718 Can also be used as a |method|: >
9719 GetTabpage()->tabpagewinnr()
9720<
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00009721 *tagfiles()*
9722tagfiles() Returns a |List| with the file names used to search for tags
9723 for the current buffer. This is the 'tags' option expanded.
9724
9725
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009726taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009727 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +01009728
9729 If {filename} is passed it is used to prioritize the results
9730 in the same way that |:tselect| does. See |tag-priority|.
9731 {filename} should be the full path of the file.
9732
Bram Moolenaard8c00872005-07-22 21:52:15 +00009733 Each list item is a dictionary with at least the following
9734 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00009735 name Name of the tag.
9736 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009737 defined. It is either relative to the
9738 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009739 cmd Ex command used to locate the tag in
9740 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009741 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009742 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009743 kind values. Only available when
9744 using a tags file generated by
9745 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009746 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009747 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009748 More entries may be present, depending on the content of the
9749 tags file: access, implementation, inherits and signature.
9750 Refer to the ctags documentation for information about these
9751 fields. For C code the fields "struct", "class" and "enum"
9752 may appear, they give the name of the entity the tag is
9753 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00009754
Bram Moolenaar214641f2017-03-05 17:04:09 +01009755 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00009756 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009757
9758 If there are no matching tags, then an empty list is returned.
9759
9760 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01009761 used in {expr}. This also make the function work faster.
9762 Refer to |tag-regexp| for more information about the tag
9763 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009764
9765 Refer to |'tags'| for information about how the tags file is
9766 located by Vim. Refer to |tags-file-format| for the format of
9767 the tags file generated by the different ctags tools.
9768
Bram Moolenaarce90e362019-09-08 18:58:44 +02009769 Can also be used as a |method|: >
9770 GetTagpattern()->taglist()
9771
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009772tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009773 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009774 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009775 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009776 Examples: >
9777 :echo tan(10)
9778< 0.648361 >
9779 :echo tan(-4.01)
9780< -1.181502
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009781
9782 Can also be used as a |method|: >
9783 Compute()->tan()
9784<
Bram Moolenaardb84e452010-08-15 13:50:43 +02009785 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009786
9787
9788tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009789 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009790 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009791 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009792 Examples: >
9793 :echo tanh(0.5)
9794< 0.462117 >
9795 :echo tanh(-1)
9796< -0.761594
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009797
9798 Can also be used as a |method|: >
9799 Compute()->tanh()
9800<
Bram Moolenaardb84e452010-08-15 13:50:43 +02009801 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009802
9803
Bram Moolenaar574860b2016-05-24 17:33:34 +02009804tempname() *tempname()* *temp-file-name*
9805 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +02009806 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +02009807 is different for at least 26 consecutive calls. Example: >
9808 :let tmpfile = tempname()
9809 :exe "redir > " . tmpfile
9810< For Unix, the file will be in a private directory |tempfile|.
9811 For MS-Windows forward slashes are used when the 'shellslash'
9812 option is set or when 'shellcmdflag' starts with '-'.
9813
Bram Moolenaared997ad2019-07-21 16:42:00 +02009814
Bram Moolenaar6bf2c622019-07-04 17:12:09 +02009815term_ functions are documented here: |terminal-function-details|
Bram Moolenaar574860b2016-05-24 17:33:34 +02009816
Bram Moolenaar54775062019-07-31 21:07:14 +02009817test_ functions are documented here: |test-functions-details|
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009818
Bram Moolenaar574860b2016-05-24 17:33:34 +02009819
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009820 *timer_info()*
9821timer_info([{id}])
9822 Return a list with information about timers.
9823 When {id} is given only information about this timer is
9824 returned. When timer {id} does not exist an empty list is
9825 returned.
9826 When {id} is omitted information about all timers is returned.
9827
9828 For each timer the information is stored in a Dictionary with
9829 these items:
9830 "id" the timer ID
9831 "time" time the timer was started with
9832 "remaining" time until the timer fires
9833 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009834 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009835 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009836 "paused" 1 if the timer is paused, 0 otherwise
9837
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009838 Can also be used as a |method|: >
9839 GetTimer()->timer_info()
9840
9841< {only available when compiled with the |+timers| feature}
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009842
9843timer_pause({timer}, {paused}) *timer_pause()*
9844 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009845 callback when its time expires. Unpausing a timer may cause
9846 the callback to be invoked almost immediately if enough time
9847 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009848
9849 Pausing a timer is useful to avoid the callback to be called
9850 for a short time.
9851
9852 If {paused} evaluates to a non-zero Number or a non-empty
9853 String, then the timer is paused, otherwise it is unpaused.
9854 See |non-zero-arg|.
9855
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009856 Can also be used as a |method|: >
9857 GetTimer()->timer_pause(1)
9858
9859< {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009860
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009861 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +01009862timer_start({time}, {callback} [, {options}])
9863 Create a timer and return the timer ID.
9864
9865 {time} is the waiting time in milliseconds. This is the
9866 minimum time before invoking the callback. When the system is
9867 busy or Vim is not waiting for input the time will be longer.
9868
9869 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +02009870 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +01009871 is the timer ID. The callback is only invoked when Vim is
9872 waiting for input.
9873
9874 {options} is a dictionary. Supported entries:
9875 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +02009876 callback. -1 means forever. When not present
9877 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +02009878 If the timer causes an error three times in a
9879 row the repeat is cancelled. This avoids that
9880 Vim becomes unusable because of all the error
9881 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +01009882
9883 Example: >
9884 func MyHandler(timer)
9885 echo 'Handler called'
9886 endfunc
9887 let timer = timer_start(500, 'MyHandler',
9888 \ {'repeat': 3})
9889< This will invoke MyHandler() three times at 500 msec
9890 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009891
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009892 Can also be used as a |method|: >
9893 GetMsec()->timer_start(callback)
9894
9895< Not available in the |sandbox|.
Bram Moolenaar975b5272016-03-15 23:10:59 +01009896 {only available when compiled with the |+timers| feature}
9897
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009898timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +02009899 Stop a timer. The timer callback will no longer be invoked.
9900 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009901 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009902
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009903 Can also be used as a |method|: >
9904 GetTimer()->timer_stop()
9905
9906< {only available when compiled with the |+timers| feature}
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009907
9908timer_stopall() *timer_stopall()*
9909 Stop all timers. The timer callbacks will no longer be
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02009910 invoked. Useful if a timer is misbehaving. If there are no
9911 timers there is no error.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009912
9913 {only available when compiled with the |+timers| feature}
9914
Bram Moolenaar071d4272004-06-13 20:20:40 +00009915tolower({expr}) *tolower()*
9916 The result is a copy of the String given, with all uppercase
9917 characters turned into lowercase (just like applying |gu| to
9918 the string).
9919
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009920 Can also be used as a |method|: >
9921 GetText()->tolower()
9922
Bram Moolenaar071d4272004-06-13 20:20:40 +00009923toupper({expr}) *toupper()*
9924 The result is a copy of the String given, with all lowercase
9925 characters turned into uppercase (just like applying |gU| to
9926 the string).
9927
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009928 Can also be used as a |method|: >
9929 GetText()->toupper()
9930
Bram Moolenaar8299df92004-07-10 09:47:34 +00009931tr({src}, {fromstr}, {tostr}) *tr()*
9932 The result is a copy of the {src} string with all characters
9933 which appear in {fromstr} replaced by the character in that
9934 position in the {tostr} string. Thus the first character in
9935 {fromstr} is translated into the first character in {tostr}
9936 and so on. Exactly like the unix "tr" command.
9937 This code also deals with multibyte characters properly.
9938
9939 Examples: >
9940 echo tr("hello there", "ht", "HT")
9941< returns "Hello THere" >
9942 echo tr("<blob>", "<>", "{}")
9943< returns "{blob}"
9944
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009945 Can also be used as a |method|: >
9946 GetText()->tr(from, to)
9947
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009948trim({text} [, {mask}]) *trim()*
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009949 Return {text} as a String where any character in {mask} is
9950 removed from the beginning and end of {text}.
9951 If {mask} is not given, {mask} is all characters up to 0x20,
9952 which includes Tab, space, NL and CR, plus the non-breaking
9953 space character 0xa0.
9954 This code deals with multibyte characters properly.
9955
9956 Examples: >
Bram Moolenaarab943432018-03-29 18:27:07 +02009957 echo trim(" some text ")
9958< returns "some text" >
9959 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009960< returns "RESERVE_TAIL" >
Bram Moolenaarab943432018-03-29 18:27:07 +02009961 echo trim("rm<Xrm<>X>rrm", "rm<>")
9962< returns "Xrm<>X" (characters in the middle are not removed)
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009963
Bram Moolenaarf92e58c2019-09-08 21:51:41 +02009964 Can also be used as a |method|: >
9965 GetText()->trim()
9966
Bram Moolenaar446cb832008-06-24 21:56:24 +00009967trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00009968 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00009969 equal to {expr} as a |Float| (truncate towards zero).
9970 {expr} must evaluate to a |Float| or a |Number|.
9971 Examples: >
9972 echo trunc(1.456)
9973< 1.0 >
9974 echo trunc(-5.456)
9975< -5.0 >
9976 echo trunc(4.0)
9977< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009978
9979 Can also be used as a |method|: >
9980 Compute()->trunc()
9981<
Bram Moolenaar446cb832008-06-24 21:56:24 +00009982 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009983
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009984 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009985type({expr}) The result is a Number representing the type of {expr}.
9986 Instead of using the number directly, it is better to use the
9987 v:t_ variable that has the value:
9988 Number: 0 |v:t_number|
9989 String: 1 |v:t_string|
9990 Funcref: 2 |v:t_func|
9991 List: 3 |v:t_list|
9992 Dictionary: 4 |v:t_dict|
9993 Float: 5 |v:t_float|
9994 Boolean: 6 |v:t_bool| (v:false and v:true)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01009995 None: 7 |v:t_none| (v:null and v:none)
9996 Job: 8 |v:t_job|
9997 Channel: 9 |v:t_channel|
9998 Blob: 10 |v:t_blob|
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009999 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000010000 :if type(myvar) == type(0)
10001 :if type(myvar) == type("")
10002 :if type(myvar) == type(function("tr"))
10003 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +000010004 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +000010005 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +010010006 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +010010007 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010008< To check if the v:t_ variables exist use this: >
10009 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +000010010
Bram Moolenaarac92e252019-08-03 21:58:38 +020010011< Can also be used as a |method|: >
10012 mylist->type()
10013
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010014undofile({name}) *undofile()*
10015 Return the name of the undo file that would be used for a file
10016 with name {name} when writing. This uses the 'undodir'
10017 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +020010018 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +020010019 {name} is always expanded to the full path, since that is what
10020 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +020010021 If {name} is empty undofile() returns an empty string, since a
10022 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010023 Useful in combination with |:wundo| and |:rundo|.
Bram Moolenaarb328cca2019-01-06 16:24:01 +010010024 When compiled without the |+persistent_undo| option this always
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010025 returns an empty string.
10026
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010027 Can also be used as a |method|: >
10028 GetFilename()->undofile()
10029
Bram Moolenaara800b422010-06-27 01:15:55 +020010030undotree() *undotree()*
10031 Return the current state of the undo tree in a dictionary with
10032 the following items:
10033 "seq_last" The highest undo sequence number used.
10034 "seq_cur" The sequence number of the current position in
10035 the undo tree. This differs from "seq_last"
10036 when some changes were undone.
10037 "time_cur" Time last used for |:earlier| and related
10038 commands. Use |strftime()| to convert to
10039 something readable.
10040 "save_last" Number of the last file write. Zero when no
10041 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +020010042 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010043 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +020010044 "synced" Non-zero when the last undo block was synced.
10045 This happens when waiting from input from the
10046 user. See |undo-blocks|.
10047 "entries" A list of dictionaries with information about
10048 undo blocks.
10049
10050 The first item in the "entries" list is the oldest undo item.
10051 Each List item is a Dictionary with these items:
10052 "seq" Undo sequence number. Same as what appears in
10053 |:undolist|.
10054 "time" Timestamp when the change happened. Use
10055 |strftime()| to convert to something readable.
10056 "newhead" Only appears in the item that is the last one
10057 that was added. This marks the last change
10058 and where further changes will be added.
10059 "curhead" Only appears in the item that is the last one
10060 that was undone. This marks the current
10061 position in the undo tree, the block that will
10062 be used by a redo command. When nothing was
10063 undone after the last change this item will
10064 not appear anywhere.
10065 "save" Only appears on the last block before a file
10066 write. The number is the write count. The
10067 first write has number 1, the last one the
10068 "save_last" mentioned above.
10069 "alt" Alternate entry. This is again a List of undo
10070 blocks. Each item may again have an "alt"
10071 item.
10072
Bram Moolenaar327aa022014-03-25 18:24:23 +010010073uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10074 Remove second and succeeding copies of repeated adjacent
10075 {list} items in-place. Returns {list}. If you want a list
10076 to remain unmodified make a copy first: >
10077 :let newlist = uniq(copy(mylist))
10078< The default compare function uses the string representation of
10079 each item. For the use of {func} and {dict} see |sort()|.
10080
Bram Moolenaarac92e252019-08-03 21:58:38 +020010081 Can also be used as a |method|: >
10082 mylist->uniq()
10083
Bram Moolenaar677ee682005-01-27 14:41:15 +000010084values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010085 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010010086 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaar677ee682005-01-27 14:41:15 +000010087
Bram Moolenaarac92e252019-08-03 21:58:38 +020010088 Can also be used as a |method|: >
10089 mydict->values()
Bram Moolenaar677ee682005-01-27 14:41:15 +000010090
Bram Moolenaar071d4272004-06-13 20:20:40 +000010091virtcol({expr}) *virtcol()*
10092 The result is a Number, which is the screen column of the file
10093 position given with {expr}. That is, the last screen position
10094 occupied by the character at that position, when the screen
10095 would be of unlimited width. When there is a <Tab> at the
10096 position, the returned Number will be the column at the end of
10097 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020010098 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +000010099 For the byte position use |col()|.
10100 For the use of {expr} see |col()|.
10101 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +000010102 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +000010103 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +020010104 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010105 When Virtual editing is active in the current mode, a position
10106 beyond the end of the line can be returned. |'virtualedit'|
10107 The accepted positions are:
10108 . the cursor position
10109 $ the end of the cursor line (the result is the
10110 number of displayed characters in the cursor line
10111 plus one)
10112 'x position of mark x (if the mark is not set, 0 is
10113 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +010010114 v In Visual mode: the start of the Visual area (the
10115 cursor is the end). When not in Visual mode
10116 returns the cursor position. Differs from |'<| in
10117 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010118 Note that only marks in the current file can be used.
10119 Examples: >
10120 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
10121 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +000010122 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +020010123< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010124 A more advanced example that echoes the maximum length of
10125 all lines: >
10126 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10127
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010128< Can also be used as a |method|: >
10129 GetPos()->virtcol()
Bram Moolenaar071d4272004-06-13 20:20:40 +000010130
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010131
10132visualmode([{expr}]) *visualmode()*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010133 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010134 used in the current buffer. Initially it returns an empty
10135 string, but once Visual mode has been used, it returns "v",
10136 "V", or "<CTRL-V>" (a single CTRL-V character) for
10137 character-wise, line-wise, or block-wise Visual mode
10138 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010139 Example: >
10140 :exe "normal " . visualmode()
10141< This enters the same Visual mode as before. It is also useful
10142 in scripts if you wish to act differently depending on the
10143 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010144 If Visual mode is active, use |mode()| to get the Visual mode
10145 (e.g., in a |:vmap|).
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010146 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar05bb9532008-07-04 09:44:11 +000010147 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010148 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010149
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010150wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010151 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010152 otherwise. See 'wildmenu' and 'wildmode'.
10153 This can be used in mappings to handle the 'wildcharm' option
10154 gracefully. (Makes only sense with |mapmode-c| mappings).
10155
10156 For example to make <c-j> work like <down> in wildmode, use: >
10157 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10158<
10159 (Note, this needs the 'wildcharm' option set appropriately).
10160
Bram Moolenaar868b7b62019-05-29 21:44:40 +020010161win_execute({id}, {command} [, {silent}]) *win_execute()*
10162 Like `execute()` but in the context of window {id}.
10163 The window will temporarily be made the current window,
Bram Moolenaarb4230122019-05-30 18:40:53 +020010164 without triggering autocommands. When executing {command}
10165 autocommands will be triggered, this may have unexpected side
10166 effects. Use |:noautocmd| if needed.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020010167 Example: >
Bram Moolenaarb4230122019-05-30 18:40:53 +020010168 call win_execute(winid, 'set syntax=python')
10169< Doing the same with `setwinvar()` would not trigger
10170 autocommands and not actually show syntax highlighting.
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020010171 *E994*
10172 Not all commands are allowed in popup windows.
Bram Moolenaar56c860c2019-08-17 20:09:31 +020010173 When window {id} does not exist then no error is given.
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010174
Bram Moolenaar2e693a82019-10-16 22:35:02 +020010175 Can also be used as a |method|, the base is passed as the
10176 second argument: >
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010177 GetCommand()->win_execute(winid)
10178
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010179win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010180 Returns a list with |window-ID|s for windows that contain
10181 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010182
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010183 Can also be used as a |method|: >
10184 GetBufnr()->win_findbuf()
10185
Bram Moolenaar86edef62016-03-13 18:07:30 +010010186win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010187 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010188 When {win} is missing use the current window.
10189 With {win} this is the window number. The top window has
Bram Moolenaarba3ff532018-11-04 14:45:49 +010010190 number 1.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010191 Without {tab} use the current tab, otherwise the tab with
10192 number {tab}. The first tab has number one.
10193 Return zero if the window cannot be found.
10194
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010195 Can also be used as a |method|: >
10196 GetWinnr()->win_getid()
10197
Bram Moolenaar86edef62016-03-13 18:07:30 +010010198win_gotoid({expr}) *win_gotoid()*
10199 Go to window with ID {expr}. This may also change the current
10200 tabpage.
10201 Return 1 if successful, 0 if the window cannot be found.
10202
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010203 Can also be used as a |method|: >
10204 GetWinid()->win_gotoid()
10205
Bram Moolenaar03413f42016-04-12 21:07:15 +020010206win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +010010207 Return a list with the tab number and window number of window
10208 with ID {expr}: [tabnr, winnr].
10209 Return [0, 0] if the window cannot be found.
10210
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010211 Can also be used as a |method|: >
10212 GetWinid()->win_id2tabwin()
10213
Bram Moolenaar86edef62016-03-13 18:07:30 +010010214win_id2win({expr}) *win_id2win()*
10215 Return the window number of window with ID {expr}.
10216 Return 0 if the window cannot be found in the current tabpage.
10217
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010218 Can also be used as a |method|: >
10219 GetWinid()->win_id2win()
10220
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010221win_screenpos({nr}) *win_screenpos()*
10222 Return the screen position of window {nr} as a list with two
10223 numbers: [row, col]. The first window always has position
Bram Moolenaar7132ddc2018-07-15 17:01:11 +020010224 [1, 1], unless there is a tabline, then it is [2, 1].
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010225 {nr} can be the window number or the |window-ID|.
10226 Return [0, 0] if the window cannot be found in the current
10227 tabpage.
10228
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010229 Can also be used as a |method|: >
10230 GetWinid()->win_screenpos()
10231<
Bram Moolenaard20dcb32019-09-10 21:22:58 +020010232win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
10233 Move the window {nr} to a new split of the window {target}.
10234 This is similar to moving to {target}, creating a new window
10235 using |:split| but having the same contents as window {nr}, and
10236 then closing {nr}.
10237
10238 Both {nr} and {target} can be window numbers or |window-ID|s.
10239
10240 Returns zero for success, non-zero for failure.
10241
10242 {options} is a Dictionary with the following optional entries:
10243 "vertical" When TRUE, the split is created vertically,
10244 like with |:vsplit|.
10245 "rightbelow" When TRUE, the split is made below or to the
10246 right (if vertical). When FALSE, it is done
10247 above or to the left (if vertical). When not
10248 present, the values of 'splitbelow' and
10249 'splitright' are used.
10250
10251 Can also be used as a |method|: >
10252 GetWinid()->win_splitmove(target)
10253<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010254 *winbufnr()*
10255winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010256 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +020010257 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010258 When {nr} is zero, the number of the buffer in the current
10259 window is returned.
10260 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010261 Example: >
10262 :echo "The file in the current window is " . bufname(winbufnr(0))
10263<
Bram Moolenaare49fbff2019-08-21 22:50:07 +020010264 Can also be used as a |method|: >
10265 FindWindow()->winbufnr()->bufname()
10266<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010267 *wincol()*
10268wincol() The result is a Number, which is the virtual column of the
10269 cursor in the window. This is counting screen cells from the
10270 left side of the window. The leftmost column is one.
10271
10272winheight({nr}) *winheight()*
10273 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010274 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010275 When {nr} is zero, the height of the current window is
10276 returned. When window {nr} doesn't exist, -1 is returned.
10277 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010278 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010279 Examples: >
10280 :echo "The current window has " . winheight(0) . " lines."
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010281
10282< Can also be used as a |method|: >
10283 GetWinid()->winheight()
Bram Moolenaar071d4272004-06-13 20:20:40 +000010284<
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020010285winlayout([{tabnr}]) *winlayout()*
10286 The result is a nested List containing the layout of windows
10287 in a tabpage.
10288
10289 Without {tabnr} use the current tabpage, otherwise the tabpage
10290 with number {tabnr}. If the tabpage {tabnr} is not found,
10291 returns an empty list.
10292
10293 For a leaf window, it returns:
10294 ['leaf', {winid}]
10295 For horizontally split windows, which form a column, it
10296 returns:
10297 ['col', [{nested list of windows}]]
10298 For vertically split windows, which form a row, it returns:
10299 ['row', [{nested list of windows}]]
10300
10301 Example: >
10302 " Only one window in the tab page
10303 :echo winlayout()
10304 ['leaf', 1000]
10305 " Two horizontally split windows
10306 :echo winlayout()
10307 ['col', [['leaf', 1000], ['leaf', 1001]]]
10308 " Three horizontally split windows, with two
10309 " vertically split windows in the middle window
10310 :echo winlayout(2)
10311 ['col', [['leaf', 1002], ['row', ['leaf', 1003],
10312 ['leaf', 1001]]], ['leaf', 1000]]
10313<
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010314 Can also be used as a |method|: >
10315 GetTabnr()->winlayout()
10316<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010317 *winline()*
10318winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +020010319 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +000010320 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +000010321 If the cursor was moved the view on the file will be updated
10322 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010323
10324 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010325winnr([{arg}]) The result is a Number, which is the number of the current
10326 window. The top window has number 1.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010327
10328 The optional argument {arg} supports the following values:
10329 $ the number of the last window (the window
10330 count).
10331 # the number of the last accessed window (where
10332 |CTRL-W_p| goes to). If there is no previous
10333 window or it is in another tab page 0 is
10334 returned.
10335 {N}j the number of the Nth window below the
10336 current window (where |CTRL-W_j| goes to).
10337 {N}k the number of the Nth window above the current
10338 window (where |CTRL-W_k| goes to).
10339 {N}h the number of the Nth window left of the
10340 current window (where |CTRL-W_h| goes to).
10341 {N}l the number of the Nth window right of the
10342 current window (where |CTRL-W_l| goes to).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010343 The number can be used with |CTRL-W_w| and ":wincmd w"
10344 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +010010345 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010346 Examples: >
10347 let window_count = winnr('$')
10348 let prev_window = winnr('#')
10349 let wnum = winnr('3k')
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010350
10351< Can also be used as a |method|: >
10352 GetWinval()->winnr()
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010353<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010354 *winrestcmd()*
10355winrestcmd() Returns a sequence of |:resize| commands that should restore
10356 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010357 are opened or closed and the current window and tab page is
10358 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010359 Example: >
10360 :let cmd = winrestcmd()
10361 :call MessWithWindowSizes()
10362 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010363<
10364 *winrestview()*
10365winrestview({dict})
10366 Uses the |Dictionary| returned by |winsaveview()| to restore
10367 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +020010368 Note: The {dict} does not have to contain all values, that are
10369 returned by |winsaveview()|. If values are missing, those
10370 settings won't be restored. So you can use: >
10371 :call winrestview({'curswant': 4})
10372<
10373 This will only set the curswant value (the column the cursor
10374 wants to move on vertical movements) of the cursor to column 5
10375 (yes, that is 5), while all other settings will remain the
10376 same. This is useful, if you set the cursor position manually.
10377
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010378 If you have changed the values the result is unpredictable.
10379 If the window size changed the result won't be the same.
10380
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010381 Can also be used as a |method|: >
10382 GetView()->winrestview()
10383<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010384 *winsaveview()*
10385winsaveview() Returns a |Dictionary| that contains information to restore
10386 the view of the current window. Use |winrestview()| to
10387 restore the view.
10388 This is useful if you have a mapping that jumps around in the
10389 buffer and you want to go back to the original view.
10390 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +000010391 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +020010392 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010393 The return value includes:
10394 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +020010395 col cursor column (Note: the first column
10396 zero, as opposed to what getpos()
10397 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010398 coladd cursor column offset for 'virtualedit'
10399 curswant column for vertical movement
10400 topline first line in the window
10401 topfill filler lines, only in diff mode
10402 leftcol first column displayed
10403 skipcol columns skipped
10404 Note that no option values are saved.
10405
Bram Moolenaar071d4272004-06-13 20:20:40 +000010406
10407winwidth({nr}) *winwidth()*
10408 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010409 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010410 When {nr} is zero, the width of the current window is
10411 returned. When window {nr} doesn't exist, -1 is returned.
10412 An existing window always has a width of zero or more.
10413 Examples: >
10414 :echo "The current window has " . winwidth(0) . " columns."
10415 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010416 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +000010417 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010418< For getting the terminal or screen size, see the 'columns'
10419 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010420
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010421 Can also be used as a |method|: >
10422 GetWinid()->winwidth()
10423
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010424
Bram Moolenaared767a22016-01-03 22:49:16 +010010425wordcount() *wordcount()*
10426 The result is a dictionary of byte/chars/word statistics for
10427 the current buffer. This is the same info as provided by
10428 |g_CTRL-G|
10429 The return value includes:
10430 bytes Number of bytes in the buffer
10431 chars Number of chars in the buffer
10432 words Number of words in the buffer
10433 cursor_bytes Number of bytes before cursor position
10434 (not in Visual mode)
10435 cursor_chars Number of chars before cursor position
10436 (not in Visual mode)
10437 cursor_words Number of words before cursor position
10438 (not in Visual mode)
10439 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010440 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010441 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010442 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +020010443 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010444 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010445
10446
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010447 *writefile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010448writefile({object}, {fname} [, {flags}])
10449 When {object} is a |List| write it to file {fname}. Each list
10450 item is separated with a NL. Each list item must be a String
10451 or Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010452 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010453 not be a NL after the last list item. An empty item at the
10454 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010455
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010456 When {object} is a |Blob| write the bytes to file {fname}
10457 unmodified.
10458
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010459 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020010460 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010461 :call writefile(["foo"], "event.log", "a")
10462 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010463<
10464 When {flags} contains "s" then fsync() is called after writing
10465 the file. This flushes the file to disk, if possible. This
10466 takes more time but avoids losing the file if the system
10467 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +010010468 When {flags} does not contain "S" or "s" then fsync() is
10469 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010470 When {flags} contains "S" then fsync() is not called, even
10471 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010472
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010473 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010474 Inserting CR characters needs to be done before passing {list}
10475 to writefile().
10476 An existing file is overwritten, if possible.
10477 When the write fails -1 is returned, otherwise 0. There is an
10478 error message if the file can't be created or when writing
10479 fails.
10480 Also see |readfile()|.
10481 To copy a file byte for byte: >
10482 :let fl = readfile("foo", "b")
10483 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010484
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020010485< Can also be used as a |method|: >
10486 GetText()->writefile("thefile")
10487
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010488
10489xor({expr}, {expr}) *xor()*
10490 Bitwise XOR on the two arguments. The arguments are converted
10491 to a number. A List, Dict or Float argument causes an error.
10492 Example: >
10493 :let bits = xor(bits, 0x80)
Bram Moolenaar2e693a82019-10-16 22:35:02 +020010494<
10495 Can also be used as a |method|: >
Bram Moolenaar073e4b92019-08-18 23:01:56 +020010496 :let bits = bits->xor(0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +010010497<
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010498
Bram Moolenaar071d4272004-06-13 20:20:40 +000010499 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +020010500There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000105011. Features that are only supported when they have been enabled when Vim
10502 was compiled |+feature-list|. Example: >
10503 :if has("cindent")
105042. Features that are only supported when certain conditions have been met.
10505 Example: >
10506 :if has("gui_running")
10507< *has-patch*
Bram Moolenaar2f018892018-05-18 18:12:06 +0200105083. Beyond a certain version or at a certain version and including a specific
10509 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10510 later, or it is version 7.4 and patch 248 was included. Example: >
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010511 :if has("patch-7.4.248")
Bram Moolenaar2f018892018-05-18 18:12:06 +020010512< Note that it's possible for patch 248 to be omitted even though 249 is
10513 included. Only happens when cherry-picking patches.
10514 Note that this form only works for patch 7.4.237 and later, before that
10515 you need to check for the patch and the v:version. Example (checking
10516 version 6.2.148 or later): >
10517 :if v:version > 602 || (v:version == 602 && has("patch148"))
Bram Moolenaar071d4272004-06-13 20:20:40 +000010518
Bram Moolenaard823fa92016-08-12 16:29:27 +020010519Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10520use: `if exists('+shellslash')`
10521
10522
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010523acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010524all_builtin_terms Compiled with all builtin terminals enabled.
10525amiga Amiga version of Vim.
10526arabic Compiled with Arabic support |Arabic|.
10527arp Compiled with ARP support (Amiga).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010528autocmd Compiled with autocommand support. (always true)
Bram Moolenaar91f84f62018-07-29 15:07:52 +020010529autochdir Compiled with support for 'autochdir'
Bram Moolenaare42a6d22017-11-12 19:21:51 +010010530autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010531balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +000010532balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010533beos BeOS version of Vim.
10534browse Compiled with |:browse| support, and browse() will
10535 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +020010536browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010537bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010538builtin_terms Compiled with some builtin terminals.
10539byte_offset Compiled with support for 'o' in 'statusline'
10540cindent Compiled with 'cindent' support.
10541clientserver Compiled with remote invocation support |clientserver|.
10542clipboard Compiled with 'clipboard' support.
Bram Moolenaar4999a7f2019-08-10 22:21:48 +020010543clipboard_working Compiled with 'clipboard' support and it can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010544cmdline_compl Compiled with |cmdline-completion| support.
10545cmdline_hist Compiled with |cmdline-history| support.
10546cmdline_info Compiled with 'showcmd' and 'ruler' support.
10547comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010548compatible Compiled to be very Vi compatible.
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +010010549conpty Platform where |ConPTY| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010550cryptv Compiled with encryption support |encryption|.
10551cscope Compiled with |cscope| support.
Bram Moolenaar314dd792019-02-03 15:27:20 +010010552cursorbind Compiled with |'cursorbind'| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010553debug Compiled with "DEBUG" defined.
10554dialog_con Compiled with console dialog support.
10555dialog_gui Compiled with GUI dialog support.
10556diff Compiled with |vimdiff| and 'diff' support.
10557digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010558directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010559dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010560ebcdic Compiled on a machine with ebcdic character set.
10561emacs_tags Compiled with support for Emacs tags.
10562eval Compiled with expression evaluation support. Always
10563 true, of course!
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010564ex_extra |+ex_extra| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010565extra_search Compiled with support for |'incsearch'| and
10566 |'hlsearch'|
10567farsi Compiled with Farsi support |farsi|.
10568file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010569filterpipe When 'shelltemp' is off pipes are used for shell
10570 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000010571find_in_path Compiled with support for include file searches
10572 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010573float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010574fname_case Case in file names matters (for Amiga, MS-DOS, and
10575 Windows this is not present).
10576folding Compiled with |folding| support.
10577footer Compiled with GUI footer support. |gui-footer|
10578fork Compiled to use fork()/exec() instead of system().
10579gettext Compiled with message translation |multi-lang|
10580gui Compiled with GUI enabled.
10581gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010582gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010583gui_gtk Compiled with GTK+ GUI (any version).
10584gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +010010585gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010586gui_mac Compiled with Macintosh GUI.
10587gui_motif Compiled with Motif GUI.
10588gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010589gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010590gui_win32 Compiled with MS Windows Win32 GUI.
10591gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010592hangul_input Compiled with Hangul input support. |hangul|
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010593hpux HP-UX version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010594iconv Can use iconv() for conversion.
10595insert_expand Compiled with support for CTRL-X expansion commands in
Bram Moolenaare49fbff2019-08-21 22:50:07 +020010596 Insert mode. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010597jumplist Compiled with |jumplist| support.
10598keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010599lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010600langmap Compiled with 'langmap' support.
10601libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +020010602linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10603 'breakindent' support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010604linux Linux version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010605lispindent Compiled with support for lisp indenting.
10606listcmds Compiled with commands for the buffer list |:files|
10607 and the argument list |arglist|.
10608localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +020010609lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +020010610mac Any Macintosh version of Vim cf. osx
10611macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +000010612menu Compiled with support for |:menu|.
10613mksession Compiled with support for |:mksession|.
10614modify_fname Compiled with file name modifiers. |filename-modifiers|
Bram Moolenaara0d1fef2019-09-04 22:29:14 +020010615 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010616mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010617mouse_dec Compiled with support for Dec terminal mouse.
10618mouse_gpm Compiled with support for gpm (Linux console mouse)
Bram Moolenaar4b8366b2019-05-04 17:34:34 +020010619mouse_gpm_enabled GPM mouse is working
Bram Moolenaar071d4272004-06-13 20:20:40 +000010620mouse_netterm Compiled with support for netterm mouse.
10621mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010622mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +020010623mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +010010624mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010625mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010626mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar4c92e752019-02-17 21:18:32 +010010627multi_byte Compiled with support for 'encoding' (always true)
Bram Moolenaar42022d52008-12-09 09:57:49 +000010628multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010629multi_byte_ime Compiled with support for IME input method.
10630multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000010631mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +020010632netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010633netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010634num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010635ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +020010636osx Compiled for macOS cf. mac
10637osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +020010638packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010639path_extra Compiled with up/downwards search in 'path' and 'tags'
10640perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +020010641persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010642postscript Compiled with PostScript file printing.
10643printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +000010644profile Compiled with |:profile| support.
Bram Moolenaar84b242c2018-01-28 17:45:49 +010010645python Python 2.x interface available. |has-python|
10646python_compiled Compiled with Python 2.x interface. |has-python|
10647python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10648python3 Python 3.x interface available. |has-python|
10649python3_compiled Compiled with Python 3.x interface. |has-python|
10650python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +010010651pythonx Compiled with |python_x| interface. |has-pythonx|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010652qnx QNX version of Vim.
10653quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +000010654reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010655rightleft Compiled with 'rightleft' support.
10656ruby Compiled with Ruby interface |ruby|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010657scrollbind Compiled with 'scrollbind' support. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010658showcmd Compiled with 'showcmd' support.
10659signs Compiled with |:sign| support.
10660smartindent Compiled with 'smartindent' support.
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010661sound Compiled with sound support, e.g. `sound_playevent()`
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010662spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +000010663startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010664statusline Compiled with support for 'statusline', 'rulerformat'
10665 and special formats of 'titlestring' and 'iconstring'.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010666sun SunOS version of Vim.
Bram Moolenaard09091d2019-01-17 16:07:22 +010010667sun_workshop Support for Sun |workshop| has been removed.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +000010668syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010669syntax_items There are active syntax highlighting items for the
10670 current buffer.
10671system Compiled to use system() instead of fork()/exec().
10672tag_binary Compiled with binary searching in tags files
10673 |tag-binary-search|.
Bram Moolenaar723dd942019-04-04 13:11:03 +020010674tag_old_static Support for old static tags was removed, see
Bram Moolenaar071d4272004-06-13 20:20:40 +000010675 |tag-old-static|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010676tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +020010677termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +020010678terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010679terminfo Compiled with terminfo instead of termcap.
10680termresponse Compiled with support for |t_RV| and |v:termresponse|.
10681textobjects Compiled with support for |text-objects|.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010010682textprop Compiled with support for |text-properties|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010683tgetent Compiled with tgetent support, able to use a termcap
10684 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010685timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010686title Compiled with window title support |'title'|.
10687toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +010010688ttyin input is a terminal (tty)
10689ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010690unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +010010691unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaarac9fb182019-04-27 13:04:13 +020010692user_commands User-defined commands. (always true)
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010010693vcon Win32: Virtual console support is working, can use
10694 'termguicolors'. Also see |+vtp|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010695vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010696 (always true)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010697vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010698 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010699viminfo Compiled with viminfo support.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020010700vimscript-1 Compiled Vim script version 1 support
10701vimscript-2 Compiled Vim script version 2 support
Bram Moolenaar911ead12019-04-21 00:03:35 +020010702vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010703virtualedit Compiled with 'virtualedit' option. (always true)
Bram Moolenaar5b69c222019-01-11 14:50:06 +010010704visual Compiled with Visual mode. (always true)
10705visualextra Compiled with extra Visual mode commands. (always
10706 true) |blockwise-operators|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010707vms VMS version of Vim.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010708vreplace Compiled with |gR| and |gr| commands. (always true)
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010709vtp Compiled for vcon support |+vtp| (check vcon to find
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +010010710 out if it works in the current console).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010711wildignore Compiled with 'wildignore' option.
10712wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010713win16 old version for MS-Windows 3.1 (always false)
Bram Moolenaard58e9292011-02-09 17:07:58 +010010714win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10715 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010716win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010717win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010718win95 Win32 version for MS-Windows 95/98/ME (always false)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010719winaltkeys Compiled with 'winaltkeys' option.
10720windows Compiled with support for more than one window.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010721 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010722writebackup Compiled with 'writebackup' default on.
10723xfontset Compiled with X fontset support |xfontset|.
10724xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010725xpm Compiled with pixmap support.
10726xpm_w32 Compiled with pixmap support for Win32. (Only for
10727 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010728xsmp Compiled with X session management support.
10729xsmp_interact Compiled with interactive X session management support.
10730xterm_clipboard Compiled with support for xterm clipboard.
10731xterm_save Compiled with support for saving and restoring the
10732 xterm screen.
10733x11 Compiled with X11 support.
10734
10735 *string-match*
10736Matching a pattern in a String
10737
10738A regexp pattern as explained at |pattern| is normally used to find a match in
10739the buffer lines. When a pattern is used to find a match in a String, almost
10740everything works in the same way. The difference is that a String is handled
10741like it is one line. When it contains a "\n" character, this is not seen as a
10742line break for the pattern. It can be matched with a "\n" in the pattern, or
10743with ".". Example: >
10744 :let a = "aaaa\nxxxx"
10745 :echo matchstr(a, "..\n..")
10746 aa
10747 xx
10748 :echo matchstr(a, "a.x")
10749 a
10750 x
10751
10752Don't forget that "^" will only match at the first character of the String and
10753"$" at the last character of the string. They don't match after or before a
10754"\n".
10755
10756==============================================================================
107575. Defining functions *user-functions*
10758
10759New functions can be defined. These can be called just like builtin
10760functions. The function executes a sequence of Ex commands. Normal mode
10761commands can be executed with the |:normal| command.
10762
10763The function name must start with an uppercase letter, to avoid confusion with
10764builtin functions. To prevent from using the same name in different scripts
10765avoid obvious, short names. A good habit is to start the function name with
10766the name of the script, e.g., "HTMLcolor()".
10767
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010768It's also possible to use curly braces, see |curly-braces-names|. And the
10769|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010770
10771 *local-function*
10772A function local to a script must start with "s:". A local script function
10773can only be called from within the script and from functions, user commands
10774and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +000010775function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +000010776instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010777There are only script-local functions, no buffer-local or window-local
10778functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010779
10780 *:fu* *:function* *E128* *E129* *E123*
10781:fu[nction] List all functions and their arguments.
10782
10783:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010784 {name} can also be a |Dictionary| entry that is a
10785 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010786 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010787
10788:fu[nction] /{pattern} List functions with a name matching {pattern}.
10789 Example that lists all functions ending with "File": >
10790 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010791<
10792 *:function-verbose*
10793When 'verbose' is non-zero, listing a function will also display where it was
10794last defined. Example: >
10795
10796 :verbose function SetFileTypeSH
10797 function SetFileTypeSH(name)
10798 Last set from /usr/share/vim/vim-7.0/filetype.vim
10799<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +000010800See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010801
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010802 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010803:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +010010804 Define a new function by the name {name}. The body of
10805 the function follows in the next lines, until the
10806 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010807
Bram Moolenaar01164a62017-11-02 22:58:42 +010010808 The name must be made of alphanumeric characters and
10809 '_', and must start with a capital or "s:" (see
10810 above). Note that using "b:" or "g:" is not allowed.
10811 (since patch 7.4.260 E884 is given if the function
10812 name has a colon in the name, e.g. for "foo:bar()".
10813 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010814
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010815 {name} can also be a |Dictionary| entry that is a
10816 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010817 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +020010818< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010819 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +020010820 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010821 result is a |Funcref| to a numbered function. The
10822 function can only be used with a |Funcref| and will be
10823 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010824 *E127* *E122*
10825 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +010010826 not used an error message is given. There is one
10827 exception: When sourcing a script again, a function
10828 that was previously defined in that script will be
10829 silently replaced.
10830 When [!] is used, an existing function is silently
10831 replaced. Unless it is currently being executed, that
10832 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010833 NOTE: Use ! wisely. If used without care it can cause
10834 an existing function to be replaced unexpectedly,
10835 which is hard to debug.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010836
10837 For the {arguments} see |function-argument|.
10838
Bram Moolenaar8d043172014-01-23 14:24:41 +010010839 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010840 When the [range] argument is added, the function is
10841 expected to take care of a range itself. The range is
10842 passed as "a:firstline" and "a:lastline". If [range]
10843 is excluded, ":{range}call" will call the function for
10844 each line in the range, with the cursor on the start
10845 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010846 The cursor is still moved to the first line of the
10847 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010848 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010849 When the [abort] argument is added, the function will
10850 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010851 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010852 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +020010853 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010854 local variable "self" will then be set to the
10855 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010856 *:func-closure* *E932*
10857 When the [closure] argument is added, the function
10858 can access variables and arguments from the outer
10859 scope. This is usually called a closure. In this
10860 example Bar() uses "x" from the scope of Foo(). It
10861 remains referenced even after Foo() returns: >
10862 :function! Foo()
10863 : let x = 0
10864 : function! Bar() closure
10865 : let x += 1
10866 : return x
10867 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +020010868 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010869 :endfunction
10870
10871 :let F = Foo()
10872 :echo F()
10873< 1 >
10874 :echo F()
10875< 2 >
10876 :echo F()
10877< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +000010878
Bram Moolenaar446cb832008-06-24 21:56:24 +000010879 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +000010880 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +000010881 will not be changed by the function. This also
10882 implies that the effect of |:nohlsearch| is undone
10883 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +000010884
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010885 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010886:endf[unction] [argument]
10887 The end of a function definition. Best is to put it
10888 on a line by its own, without [argument].
10889
10890 [argument] can be:
10891 | command command to execute next
10892 \n command command to execute next
10893 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010894 anything else ignored, warning given when
10895 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +020010896 The support for a following command was added in Vim
10897 8.0.0654, before that any argument was silently
10898 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010899
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010900 To be able to define a function inside an `:execute`
10901 command, use line breaks instead of |:bar|: >
10902 :exe "func Foo()\necho 'foo'\nendfunc"
10903<
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010904 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010905:delf[unction][!] {name}
10906 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010907 {name} can also be a |Dictionary| entry that is a
10908 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010909 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +020010910< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010911 function is deleted if there are no more references to
10912 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +020010913 With the ! there is no error if the function does not
10914 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010915 *:retu* *:return* *E133*
10916:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
10917 evaluated and returned as the result of the function.
10918 If "[expr]" is not given, the number 0 is returned.
10919 When a function ends without an explicit ":return",
10920 the number 0 is returned.
10921 Note that there is no check for unreachable lines,
10922 thus there is no warning if commands follow ":return".
10923
10924 If the ":return" is used after a |:try| but before the
10925 matching |:finally| (if present), the commands
10926 following the ":finally" up to the matching |:endtry|
10927 are executed first. This process applies to all
10928 nested ":try"s inside the function. The function
10929 returns at the outermost ":endtry".
10930
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010931 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010932An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010933be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010934 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010935Up to 20 arguments can be given, separated by commas. After the named
10936arguments an argument "..." can be specified, which means that more arguments
10937may optionally be following. In the function the extra arguments can be used
10938as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010939can be 0). "a:000" is set to a |List| that contains these arguments. Note
10940that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010941 *E742*
10942The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010943However, if a composite type is used, such as |List| or |Dictionary| , you can
10944change their contents. Thus you can pass a |List| to a function and have the
10945function add an item to it. If you want to make sure the function cannot
10946change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010947
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010948It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +010010949still supply the () then.
10950
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010951It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010952
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020010953 *optional-function-argument*
10954You can provide default values for positional named arguments. This makes
10955them optional for function calls. When a positional argument is not
10956specified at a call, the default expression is used to initialize it.
Bram Moolenaar68e65602019-05-26 21:33:31 +020010957This only works for functions declared with `:function`, not for lambda
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020010958expressions |expr-lambda|.
10959
10960Example: >
10961 function Something(key, value = 10)
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020010962 echo a:key .. ": " .. a:value
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020010963 endfunction
10964 call Something('empty') "empty: 10"
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020010965 call Something('key', 20) "key: 20"
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020010966
10967The argument default expressions are evaluated at the time of the function
10968call, not definition. Thus it is possible to use an expression which is
Bram Moolenaar68e65602019-05-26 21:33:31 +020010969invalid the moment the function is defined. The expressions are also only
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020010970evaluated when arguments are not specified during a call.
10971
10972You can pass |v:none| to use the default expression. Note that this means you
10973cannot pass v:none as an ordinary value when an argument has a default
10974expression.
10975
10976Example: >
10977 function Something(a = 10, b = 20, c = 30)
10978 endfunction
10979 call Something(1, v:none, 3) " b = 20
10980<
10981 *E989*
10982Optional arguments with default expressions must occur after any mandatory
10983arguments. You can use "..." after all optional named arguments.
10984
10985It is possible for later argument defaults to refer to prior arguments,
10986but not the other way around. They must be prefixed with "a:", as with all
10987arguments.
10988
10989Example that works: >
10990 :function Okay(mandatory, optional = a:mandatory)
10991 :endfunction
10992Example that does NOT work: >
10993 :function NoGood(first = a:second, second = 10)
10994 :endfunction
10995<
10996When not using "...", the number of arguments in a function call must be equal
10997to the number of mandatory named arguments. When using "...", the number of
10998arguments may be larger.
10999
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011000 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +020011001Inside a function local variables can be used. These will disappear when the
11002function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +000011003
11004Example: >
11005 :function Table(title, ...)
11006 : echohl Title
11007 : echo a:title
11008 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +000011009 : echo a:0 . " items:"
11010 : for s in a:000
11011 : echon ' ' . s
11012 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +000011013 :endfunction
11014
11015This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +000011016 call Table("Table", "line1", "line2")
11017 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +000011018
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011019To return more than one value, return a |List|: >
11020 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011021 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011022 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +000011023 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011024 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +000011025 :endfunction
11026
11027This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011028 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011029 :if success == "ok"
11030 : echo div
11031 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011032<
Bram Moolenaar39f05632006-03-19 22:15:26 +000011033 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011034:[range]cal[l] {name}([arguments])
11035 Call a function. The name of the function and its arguments
Bram Moolenaar68e65602019-05-26 21:33:31 +020011036 are as specified with `:function`. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011037 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011038 Without a range and for functions that accept a range, the
11039 function is called once. When a range is given the cursor is
11040 positioned at the start of the first line before executing the
11041 function.
11042 When a range is given and the function doesn't handle it
11043 itself, the function is executed for each line in the range,
11044 with the cursor in the first column of that line. The cursor
11045 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +020011046 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +000011047 this works:
11048 *function-range-example* >
11049 :function Mynumber(arg)
11050 : echo line(".") . " " . a:arg
11051 :endfunction
11052 :1,5call Mynumber(getline("."))
11053<
11054 The "a:firstline" and "a:lastline" are defined anyway, they
11055 can be used to do something different at the start or end of
11056 the range.
11057
11058 Example of a function that handles the range itself: >
11059
11060 :function Cont() range
11061 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
11062 :endfunction
11063 :4,8call Cont()
11064<
11065 This function inserts the continuation character "\" in front
11066 of all the lines in the range, except the first one.
11067
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011068 When the function returns a composite value it can be further
11069 dereferenced, but the range will not be used then. Example: >
11070 :4,8call GetDict().method()
11071< Here GetDict() gets the range but method() does not.
11072
Bram Moolenaar071d4272004-06-13 20:20:40 +000011073 *E132*
11074The recursiveness of user functions is restricted with the |'maxfuncdepth'|
11075option.
11076
Bram Moolenaar25e42232019-08-04 15:04:10 +020011077It is also possible to use `:eval`. It does not support a range, but does
11078allow for method chaining, e.g.: >
11079 eval GetList()->Filter()->append('$')
11080
Bram Moolenaar088e8e32019-08-08 22:15:18 +020011081A function can also be called as part of evaluating an expression or when it
11082is used as a method: >
11083 let x = GetList()
11084 let y = GetList()->Filter()
11085
Bram Moolenaar7c626922005-02-07 22:01:03 +000011086
11087AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011088 *autoload-functions*
11089When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +000011090only when they are used. There are two methods: with an autocommand and with
11091the "autoload" directory in 'runtimepath'.
11092
11093
11094Using an autocommand ~
11095
Bram Moolenaar05159a02005-02-26 23:04:13 +000011096This is introduced in the user manual, section |41.14|.
11097
Bram Moolenaar7c626922005-02-07 22:01:03 +000011098The autocommand is useful if you have a plugin that is a long Vim script file.
Bram Moolenaar68e65602019-05-26 21:33:31 +020011099You can define the autocommand and quickly quit the script with `:finish`.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011100That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar68e65602019-05-26 21:33:31 +020011101again, setting a variable to skip the `:finish` command.
Bram Moolenaar7c626922005-02-07 22:01:03 +000011102
11103Use the FuncUndefined autocommand event with a pattern that matches the
11104function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011105
11106 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
11107
11108The file "~/vim/bufnetfuncs.vim" should then define functions that start with
11109"BufNet". Also see |FuncUndefined|.
11110
Bram Moolenaar7c626922005-02-07 22:01:03 +000011111
11112Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011113 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +000011114This is introduced in the user manual, section |41.15|.
11115
Bram Moolenaar7c626922005-02-07 22:01:03 +000011116Using a script in the "autoload" directory is simpler, but requires using
11117exactly the right file name. A function that can be autoloaded has a name
11118like this: >
11119
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011120 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011121
11122When such a function is called, and it is not defined yet, Vim will search the
11123"autoload" directories in 'runtimepath' for a script file called
11124"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
11125then define the function like this: >
11126
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011127 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011128 echo "Done!"
11129 endfunction
11130
Bram Moolenaar60a795a2005-09-16 21:55:43 +000011131The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +000011132exactly, and the defined function must have the name exactly as it will be
11133called.
11134
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011135It is possible to use subdirectories. Every # in the function name works like
11136a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +000011137
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011138 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011139
11140Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
11141
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011142This also works when reading a variable that has not been set yet: >
11143
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011144 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011145
Bram Moolenaara5792f52005-11-23 21:25:05 +000011146However, when the autoload script was already loaded it won't be loaded again
11147for an unknown variable.
11148
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011149When assigning a value to such a variable nothing special happens. This can
11150be used to pass settings to the autoload script before it's loaded: >
11151
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011152 :let foo#bar#toggle = 1
11153 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011154
Bram Moolenaar4399ef42005-02-12 14:29:27 +000011155Note that when you make a mistake and call a function that is supposed to be
11156defined in an autoload script, but the script doesn't actually define the
11157function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011158And you will get an error message every time.
11159
11160Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +000011161other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011162Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +000011163
Bram Moolenaar433f7c82006-03-21 21:29:36 +000011164Hint: If you distribute a bunch of scripts you can pack them together with the
11165|vimball| utility. Also read the user manual |distribute-script|.
11166
Bram Moolenaar071d4272004-06-13 20:20:40 +000011167==============================================================================
111686. Curly braces names *curly-braces-names*
11169
Bram Moolenaar84f72352012-03-11 15:57:40 +010011170In most places where you can use a variable, you can use a "curly braces name"
11171variable. This is a regular variable name with one or more expressions
11172wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011173 my_{adjective}_variable
11174
11175When Vim encounters this, it evaluates the expression inside the braces, puts
11176that in place of the expression, and re-interprets the whole as a variable
11177name. So in the above example, if the variable "adjective" was set to
11178"noisy", then the reference would be to "my_noisy_variable", whereas if
11179"adjective" was set to "quiet", then it would be to "my_quiet_variable".
11180
11181One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +020011182value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011183 echo my_{&background}_message
11184
11185would output the contents of "my_dark_message" or "my_light_message" depending
11186on the current value of 'background'.
11187
11188You can use multiple brace pairs: >
11189 echo my_{adverb}_{adjective}_message
11190..or even nest them: >
11191 echo my_{ad{end_of_word}}_message
11192where "end_of_word" is either "verb" or "jective".
11193
11194However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000011195variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011196 :let foo='a + b'
11197 :echo c{foo}d
11198.. since the result of expansion is "ca + bd", which is not a variable name.
11199
11200 *curly-braces-function-names*
11201You can call and define functions by an evaluated name in a similar way.
11202Example: >
11203 :let func_end='whizz'
11204 :call my_func_{func_end}(parameter)
11205
11206This would call the function "my_func_whizz(parameter)".
11207
Bram Moolenaar84f72352012-03-11 15:57:40 +010011208This does NOT work: >
11209 :let i = 3
11210 :let @{i} = '' " error
11211 :echo @{i} " error
11212
Bram Moolenaar071d4272004-06-13 20:20:40 +000011213==============================================================================
112147. Commands *expression-commands*
11215
11216:let {var-name} = {expr1} *:let* *E18*
11217 Set internal variable {var-name} to the result of the
11218 expression {expr1}. The variable will get the type
11219 from the {expr}. If {var-name} didn't exist yet, it
11220 is created.
11221
Bram Moolenaar13065c42005-01-08 16:08:21 +000011222:let {var-name}[{idx}] = {expr1} *E689*
11223 Set a list item to the result of the expression
11224 {expr1}. {var-name} must refer to a list and {idx}
11225 must be a valid index in that list. For nested list
11226 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011227 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011228 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +000011229 can do that like this: >
11230 :let var = var[0:2] . 'X' . var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010011231< When {var-name} is a |Blob| then {idx} can be the
11232 length of the blob, in which case one byte is
11233 appended.
11234
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011235 *E711* *E719*
11236:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011237 Set a sequence of items in a |List| to the result of
11238 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011239 correct number of items.
11240 {idx1} can be omitted, zero is used instead.
11241 {idx2} can be omitted, meaning the end of the list.
11242 When the selected range of items is partly past the
11243 end of the list, items will be added.
11244
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011245 *:let+=* *:let-=* *:letstar=*
11246 *:let/=* *:let%=* *:let.=* *:let..=* *E734* *E985*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011247:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
11248:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +010011249:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
11250:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
11251:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011252:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011253:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011254 These fail if {var} was not set yet and when the type
11255 of {var} and {expr1} don't fit the operator.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011256 `.=` is not supported with Vim script version 2 and
11257 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011258
11259
Bram Moolenaar071d4272004-06-13 20:20:40 +000011260:let ${env-name} = {expr1} *:let-environment* *:let-$*
11261 Set environment variable {env-name} to the result of
11262 the expression {expr1}. The type is always String.
Bram Moolenaar56c860c2019-08-17 20:09:31 +020011263
11264 On some systems making an environment variable empty
11265 causes it to be deleted. Many systems do not make a
11266 difference between an environment variable that is not
11267 set and an environment variable that is empty.
11268
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011269:let ${env-name} .= {expr1}
11270 Append {expr1} to the environment variable {env-name}.
11271 If the environment variable didn't exist yet this
11272 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +000011273
11274:let @{reg-name} = {expr1} *:let-register* *:let-@*
11275 Write the result of the expression {expr1} in register
11276 {reg-name}. {reg-name} must be a single letter, and
11277 must be the name of a writable register (see
11278 |registers|). "@@" can be used for the unnamed
11279 register, "@/" for the search pattern.
11280 If the result of {expr1} ends in a <CR> or <NL>, the
11281 register will be linewise, otherwise it will be set to
11282 characterwise.
11283 This can be used to clear the last search pattern: >
11284 :let @/ = ""
11285< This is different from searching for an empty string,
11286 that would match everywhere.
11287
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011288:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +020011289 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011290 register was empty it's like setting it to {expr1}.
11291
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011292:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011293 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011294 expression {expr1}. A String or Number value is
11295 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011296 For an option local to a window or buffer the effect
11297 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +000011298 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011299 Example: >
11300 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +010011301< This also works for terminal codes in the form t_xx.
11302 But only for alphanumerical names. Example: >
11303 :let &t_k1 = "\<Esc>[234;"
11304< When the code does not exist yet it will be created as
11305 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011306
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011307:let &{option-name} .= {expr1}
11308 For a string option: Append {expr1} to the value.
11309 Does not insert a comma like |:set+=|.
11310
11311:let &{option-name} += {expr1}
11312:let &{option-name} -= {expr1}
11313 For a number or boolean option: Add or subtract
11314 {expr1}.
11315
Bram Moolenaar071d4272004-06-13 20:20:40 +000011316:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011317:let &l:{option-name} .= {expr1}
11318:let &l:{option-name} += {expr1}
11319:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011320 Like above, but only set the local value of an option
11321 (if there is one). Works like |:setlocal|.
11322
11323:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011324:let &g:{option-name} .= {expr1}
11325:let &g:{option-name} += {expr1}
11326:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011327 Like above, but only set the global value of an option
11328 (if there is one). Works like |:setglobal|.
11329
Bram Moolenaar13065c42005-01-08 16:08:21 +000011330:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011331 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011332 the list is assigned to {name1}, the second item to
11333 {name2}, etc.
11334 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011335 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011336 Each name can be one of the items of the ":let"
11337 command as mentioned above.
11338 Example: >
11339 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011340< Detail: {expr1} is evaluated first, then the
11341 assignments are done in sequence. This matters if
11342 {name2} depends on {name1}. Example: >
11343 :let x = [0, 1]
11344 :let i = 0
11345 :let [i, x[i]] = [1, 2]
11346 :echo x
11347< The result is [0, 2].
11348
11349:let [{name1}, {name2}, ...] .= {expr1}
11350:let [{name1}, {name2}, ...] += {expr1}
11351:let [{name1}, {name2}, ...] -= {expr1}
11352 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011353 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011354
11355:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011356 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011357 items than there are names. A list of the remaining
11358 items is assigned to {lastname}. If there are no
11359 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011360 Example: >
11361 :let [a, b; rest] = ["aval", "bval", 3, 4]
11362<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011363:let [{name}, ..., ; {lastname}] .= {expr1}
11364:let [{name}, ..., ; {lastname}] += {expr1}
11365:let [{name}, ..., ; {lastname}] -= {expr1}
11366 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011367 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +020011368
Bram Moolenaar24582002019-07-21 14:14:26 +020011369 *:let=<<* *:let-heredoc*
11370 *E990* *E991* *E172* *E221*
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011371:let {var-name} =<< [trim] {endmarker}
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011372text...
11373text...
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011374{endmarker}
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011375 Set internal variable {var-name} to a List containing
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011376 the lines of text bounded by the string {endmarker}.
11377 {endmarker} must not contain white space.
11378 {endmarker} cannot start with a lower case character.
11379 The last line should end only with the {endmarker}
11380 string without any other character. Watch out for
11381 white space after {endmarker}!
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011382
Bram Moolenaare7eb9272019-06-24 00:58:07 +020011383 Without "trim" any white space characters in the lines
11384 of text are preserved. If "trim" is specified before
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011385 {endmarker}, then indentation is stripped so you can
11386 do: >
Bram Moolenaare7eb9272019-06-24 00:58:07 +020011387 let text =<< trim END
11388 if ok
11389 echo 'done'
11390 endif
11391 END
11392< Results in: ["if ok", " echo 'done'", "endif"]
11393 The marker must line up with "let" and the indentation
11394 of the first line is removed from all the text lines.
11395 Specifically: all the leading indentation exactly
11396 matching the leading indentation of the first
11397 non-empty text line is stripped from the input lines.
11398 All leading indentation exactly matching the leading
11399 indentation before `let` is stripped from the line
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011400 containing {endmarker}. Note that the difference
11401 between space and tab matters here.
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011402
11403 If {var-name} didn't exist yet, it is created.
11404 Cannot be followed by another command, but can be
11405 followed by a comment.
11406
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011407 To avoid line continuation to be applied, consider
11408 adding 'C' to 'cpoptions': >
11409 set cpo+=C
11410 let var =<< END
11411 \ leading backslash
11412 END
11413 set cpo-=C
11414<
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011415 Examples: >
11416 let var1 =<< END
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011417 Sample text 1
11418 Sample text 2
11419 Sample text 3
11420 END
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011421
11422 let data =<< trim DATA
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011423 1 2 3 4
11424 5 6 7 8
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011425 DATA
11426<
Bram Moolenaar4a748032010-09-30 21:47:56 +020011427 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +020011428:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011429 variable names may be given. Special names recognized
11430 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +000011431 g: global variables
11432 b: local buffer variables
11433 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011434 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +000011435 s: script-local variables
11436 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011437 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011438
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000011439:let List the values of all variables. The type of the
11440 variable is indicated before the value:
11441 <nothing> String
11442 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000011443 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +000011444
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011445:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011446 Remove the internal variable {name}. Several variable
11447 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011448 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011449 With [!] no error message is given for non-existing
11450 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011451 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011452 :unlet list[3] " remove fourth item
11453 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011454< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011455 :unlet dict['two']
11456 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +000011457< This is especially useful to clean up used global
11458 variables and script-local variables (these are not
11459 deleted when the script ends). Function-local
11460 variables are automatically deleted when the function
11461 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011462
Bram Moolenaar137374f2018-05-13 15:59:50 +020011463:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
11464 Remove environment variable {env-name}.
11465 Can mix {name} and ${env-name} in one :unlet command.
11466 No error message is given for a non-existing
11467 variable, also without !.
11468 If the system does not support deleting an environment
Bram Moolenaar9937a052019-06-15 15:45:06 +020011469 variable, it is made empty.
Bram Moolenaar137374f2018-05-13 15:59:50 +020011470
Bram Moolenaar1c196e72019-06-16 15:41:58 +020011471 *:cons* *:const*
Bram Moolenaar9937a052019-06-15 15:45:06 +020011472:cons[t] {var-name} = {expr1}
11473:cons[t] [{name1}, {name2}, ...] = {expr1}
Bram Moolenaar9937a052019-06-15 15:45:06 +020011474:cons[t] [{name}, ..., ; {lastname}] = {expr1}
11475:cons[t] {var-name} =<< [trim] {marker}
11476text...
11477text...
11478{marker}
11479 Similar to |:let|, but additionally lock the variable
11480 after setting the value. This is the same as locking
11481 the variable with |:lockvar| just after |:let|, thus: >
11482 :const x = 1
11483< is equivalent to: >
11484 :let x = 1
11485 :lockvar 1 x
11486< This is useful if you want to make sure the variable
11487 is not modified.
11488 *E995*
Bram Moolenaar9b283522019-06-17 22:19:33 +020011489 |:const| does not allow to for changing a variable: >
Bram Moolenaar9937a052019-06-15 15:45:06 +020011490 :let x = 1
11491 :const x = 2 " Error!
Bram Moolenaar1c196e72019-06-16 15:41:58 +020011492< *E996*
11493 Note that environment variables, option values and
11494 register values cannot be used here, since they cannot
11495 be locked.
11496
Bram Moolenaar85850f32019-07-19 22:05:51 +020011497:cons[t]
11498:cons[t] {var-name}
11499 If no argument is given or only {var-name} is given,
11500 the behavior is the same as |:let|.
11501
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011502:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
11503 Lock the internal variable {name}. Locking means that
11504 it can no longer be changed (until it is unlocked).
11505 A locked variable can be deleted: >
11506 :lockvar v
11507 :let v = 'asdf' " fails!
11508 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011509< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011510 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011511 error message: "E741: Value is locked: {name}".
11512 If you try to lock or unlock a built-in variable you
11513 get an error message: "E940: Cannot lock or unlock
11514 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011515
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011516 [depth] is relevant when locking a |List| or
11517 |Dictionary|. It specifies how deep the locking goes:
11518 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011519 cannot add or remove items, but can
11520 still change their values.
11521 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011522 the items. If an item is a |List| or
11523 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011524 items, but can still change the
11525 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011526 3 Like 2 but for the |List| /
11527 |Dictionary| in the |List| /
11528 |Dictionary|, one level deeper.
11529 The default [depth] is 2, thus when {name} is a |List|
11530 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011531 *E743*
11532 For unlimited depth use [!] and omit [depth].
11533 However, there is a maximum depth of 100 to catch
11534 loops.
11535
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011536 Note that when two variables refer to the same |List|
11537 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011538 locked when used through the other variable.
11539 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011540 :let l = [0, 1, 2, 3]
11541 :let cl = l
11542 :lockvar l
11543 :let cl[1] = 99 " won't work!
11544< You may want to make a copy of a list to avoid this.
11545 See |deepcopy()|.
11546
11547
11548:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
11549 Unlock the internal variable {name}. Does the
11550 opposite of |:lockvar|.
11551
Bram Moolenaar25e42232019-08-04 15:04:10 +020011552 *:eval*
11553:eval {expr} Evaluate {expr} and discard the result. Example: >
11554 :eval Getlist()->Filter()->append('$')
11555
11556< The expression is supposed to have a side effect,
11557 since the resulting value is not used. In the example
11558 the `append()` call appends the List with text to the
11559 buffer. This is similar to `:call` but works with any
11560 expression.
11561
11562 The command can be shortened to `:ev` or `:eva`, but
11563 these are hard to recognize and therefore not to be
11564 used.
11565
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011566
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020011567:if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011568:en[dif] Execute the commands until the next matching ":else"
11569 or ":endif" if {expr1} evaluates to non-zero.
11570
11571 From Vim version 4.5 until 5.0, every Ex command in
11572 between the ":if" and ":endif" is ignored. These two
11573 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +010011574 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +000011575 that any ":else" or ":elseif" was ignored, the "else"
11576 part was not executed either.
11577
11578 You can use this to remain compatible with older
11579 versions: >
11580 :if version >= 500
11581 : version-5-specific-commands
11582 :endif
11583< The commands still need to be parsed to find the
11584 "endif". Sometimes an older Vim has a problem with a
11585 new command. For example, ":silent" is recognized as
11586 a ":substitute" command. In that case ":execute" can
11587 avoid problems: >
11588 :if version >= 600
11589 : execute "silent 1,$delete"
11590 :endif
11591<
11592 NOTE: The ":append" and ":insert" commands don't work
11593 properly in between ":if" and ":endif".
11594
11595 *:else* *:el* *E581* *E583*
11596:el[se] Execute the commands until the next matching ":else"
11597 or ":endif" if they previously were not being
11598 executed.
11599
11600 *:elseif* *:elsei* *E582* *E584*
11601:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
11602 is no extra ":endif".
11603
11604:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011605 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011606:endw[hile] Repeat the commands between ":while" and ":endwhile",
11607 as long as {expr1} evaluates to non-zero.
11608 When an error is detected from a command inside the
11609 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +000011610 Example: >
11611 :let lnum = 1
11612 :while lnum <= line("$")
11613 :call FixLine(lnum)
11614 :let lnum = lnum + 1
11615 :endwhile
11616<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011617 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +000011618 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011619
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011620:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +000011621:endfo[r] *:endfo* *:endfor*
11622 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011623 each item in {object}. {object} can be a |List| or
11624 a |Blob|. Variable {var} is set to the value of each
11625 item. When an error is detected for a command inside
11626 the loop, execution continues after the "endfor".
11627 Changing {object} inside the loop affects what items
11628 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +000011629 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011630<
11631 When {object} is a |List| and not making a copy, Vim
11632 stores a reference to the next item in the |List|
11633 before executing the commands with the current item.
11634 Thus the current item can be removed without effect.
11635 Removing any later item means it will not be found.
11636 Thus the following example works (an inefficient way
11637 to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011638 for item in mylist
11639 call remove(mylist, 0)
11640 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011641< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011642 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +000011643
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011644 When {object} is a |Blob|, Vim always makes a copy to
11645 iterate over. Unlike with |List|, modifying the
11646 |Blob| does not affect the iteration.
11647
Bram Moolenaar12805862005-01-05 22:16:17 +000011648:for [{var1}, {var2}, ...] in {listlist}
11649:endfo[r]
11650 Like ":for" above, but each item in {listlist} must be
11651 a list, of which each item is assigned to {var1},
11652 {var2}, etc. Example: >
11653 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
11654 :echo getline(lnum)[col]
11655 :endfor
11656<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011657 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +000011658:con[tinue] When used inside a ":while" or ":for" loop, jumps back
11659 to the start of the loop.
11660 If it is used after a |:try| inside the loop but
11661 before the matching |:finally| (if present), the
11662 commands following the ":finally" up to the matching
11663 |:endtry| are executed first. This process applies to
11664 all nested ":try"s inside the loop. The outermost
11665 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011666
11667 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +000011668:brea[k] When used inside a ":while" or ":for" loop, skips to
11669 the command after the matching ":endwhile" or
11670 ":endfor".
11671 If it is used after a |:try| inside the loop but
11672 before the matching |:finally| (if present), the
11673 commands following the ":finally" up to the matching
11674 |:endtry| are executed first. This process applies to
11675 all nested ":try"s inside the loop. The outermost
11676 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011677
11678:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
11679:endt[ry] Change the error handling for the commands between
11680 ":try" and ":endtry" including everything being
11681 executed across ":source" commands, function calls,
11682 or autocommand invocations.
11683
11684 When an error or interrupt is detected and there is
11685 a |:finally| command following, execution continues
11686 after the ":finally". Otherwise, or when the
11687 ":endtry" is reached thereafter, the next
11688 (dynamically) surrounding ":try" is checked for
11689 a corresponding ":finally" etc. Then the script
11690 processing is terminated. (Whether a function
11691 definition has an "abort" argument does not matter.)
11692 Example: >
11693 :try | edit too much | finally | echo "cleanup" | endtry
11694 :echo "impossible" " not reached, script terminated above
11695<
11696 Moreover, an error or interrupt (dynamically) inside
11697 ":try" and ":endtry" is converted to an exception. It
11698 can be caught as if it were thrown by a |:throw|
11699 command (see |:catch|). In this case, the script
11700 processing is not terminated.
11701
11702 The value "Vim:Interrupt" is used for an interrupt
11703 exception. An error in a Vim command is converted
11704 to a value of the form "Vim({command}):{errmsg}",
11705 other errors are converted to a value of the form
11706 "Vim:{errmsg}". {command} is the full command name,
11707 and {errmsg} is the message that is displayed if the
11708 error exception is not caught, always beginning with
11709 the error number.
11710 Examples: >
11711 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
11712 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
11713<
11714 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011715:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011716 |:finally|, or |:endtry| that belongs to the same
11717 |:try| as the ":catch" are executed when an exception
11718 matching {pattern} is being thrown and has not yet
11719 been caught by a previous ":catch". Otherwise, these
11720 commands are skipped.
11721 When {pattern} is omitted all errors are caught.
11722 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +010011723 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
11724 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
11725 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
11726 :catch /^Vim(write):/ " catch all errors in :write
11727 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
11728 :catch /my-exception/ " catch user exception
11729 :catch /.*/ " catch everything
11730 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +000011731<
11732 Another character can be used instead of / around the
11733 {pattern}, so long as it does not have a special
11734 meaning (e.g., '|' or '"') and doesn't occur inside
11735 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020011736 Information about the exception is available in
11737 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011738 NOTE: It is not reliable to ":catch" the TEXT of
11739 an error message because it may vary in different
11740 locales.
11741
11742 *:fina* *:finally* *E606* *E607*
11743:fina[lly] The following commands until the matching |:endtry|
11744 are executed whenever the part between the matching
11745 |:try| and the ":finally" is left: either by falling
11746 through to the ":finally" or by a |:continue|,
11747 |:break|, |:finish|, or |:return|, or by an error or
11748 interrupt or exception (see |:throw|).
11749
11750 *:th* *:throw* *E608*
11751:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
11752 If the ":throw" is used after a |:try| but before the
11753 first corresponding |:catch|, commands are skipped
11754 until the first ":catch" matching {expr1} is reached.
11755 If there is no such ":catch" or if the ":throw" is
11756 used after a ":catch" but before the |:finally|, the
11757 commands following the ":finally" (if present) up to
11758 the matching |:endtry| are executed. If the ":throw"
11759 is after the ":finally", commands up to the ":endtry"
11760 are skipped. At the ":endtry", this process applies
11761 again for the next dynamically surrounding ":try"
11762 (which may be found in a calling function or sourcing
11763 script), until a matching ":catch" has been found.
11764 If the exception is not caught, the command processing
11765 is terminated.
11766 Example: >
11767 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +010011768< Note that "catch" may need to be on a separate line
11769 for when an error causes the parsing to skip the whole
11770 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011771
11772 *:ec* *:echo*
11773:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
11774 first {expr1} starts on a new line.
11775 Also see |:comment|.
11776 Use "\n" to start a new line. Use "\r" to move the
11777 cursor to the first column.
11778 Uses the highlighting set by the |:echohl| command.
11779 Cannot be followed by a comment.
11780 Example: >
11781 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011782< *:echo-redraw*
11783 A later redraw may make the message disappear again.
11784 And since Vim mostly postpones redrawing until it's
11785 finished with a sequence of commands this happens
11786 quite often. To avoid that a command from before the
11787 ":echo" causes a redraw afterwards (redraws are often
11788 postponed until you type something), force a redraw
11789 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011790 :new | redraw | echo "there is a new window"
11791<
11792 *:echon*
11793:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
11794 |:comment|.
11795 Uses the highlighting set by the |:echohl| command.
11796 Cannot be followed by a comment.
11797 Example: >
11798 :echon "the value of 'shell' is " &shell
11799<
11800 Note the difference between using ":echo", which is a
11801 Vim command, and ":!echo", which is an external shell
11802 command: >
11803 :!echo % --> filename
11804< The arguments of ":!" are expanded, see |:_%|. >
11805 :!echo "%" --> filename or "filename"
11806< Like the previous example. Whether you see the double
11807 quotes or not depends on your 'shell'. >
11808 :echo % --> nothing
11809< The '%' is an illegal character in an expression. >
11810 :echo "%" --> %
11811< This just echoes the '%' character. >
11812 :echo expand("%") --> filename
11813< This calls the expand() function to expand the '%'.
11814
11815 *:echoh* *:echohl*
11816:echoh[l] {name} Use the highlight group {name} for the following
11817 |:echo|, |:echon| and |:echomsg| commands. Also used
11818 for the |input()| prompt. Example: >
11819 :echohl WarningMsg | echo "Don't panic!" | echohl None
11820< Don't forget to set the group back to "None",
11821 otherwise all following echo's will be highlighted.
11822
11823 *:echom* *:echomsg*
11824:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
11825 message in the |message-history|.
11826 Spaces are placed between the arguments as with the
11827 |:echo| command. But unprintable characters are
11828 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011829 The parsing works slightly different from |:echo|,
11830 more like |:execute|. All the expressions are first
11831 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011832 If expressions does not evaluate to a Number or
11833 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011834 Uses the highlighting set by the |:echohl| command.
11835 Example: >
11836 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011837< See |:echo-redraw| to avoid the message disappearing
11838 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011839 *:echoe* *:echoerr*
11840:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
11841 message in the |message-history|. When used in a
11842 script or function the line number will be added.
11843 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011844 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011845 the message is raised as an error exception instead
11846 (see |try-echoerr|).
11847 Example: >
11848 :echoerr "This script just failed!"
11849< If you just want a highlighted message use |:echohl|.
11850 And to get a beep: >
11851 :exe "normal \<Esc>"
11852<
11853 *:exe* *:execute*
11854:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011855 of {expr1} as an Ex command.
11856 Multiple arguments are concatenated, with a space in
11857 between. To avoid the extra space use the "."
11858 operator to concatenate strings into one argument.
11859 {expr1} is used as the processed command, command line
11860 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011861 Cannot be followed by a comment.
11862 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011863 :execute "buffer" nextbuf
11864 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +000011865<
11866 ":execute" can be used to append a command to commands
11867 that don't accept a '|'. Example: >
11868 :execute '!ls' | echo "theend"
11869
11870< ":execute" is also a nice way to avoid having to type
11871 control characters in a Vim script for a ":normal"
11872 command: >
11873 :execute "normal ixxx\<Esc>"
11874< This has an <Esc> character, see |expr-string|.
11875
Bram Moolenaar446cb832008-06-24 21:56:24 +000011876 Be careful to correctly escape special characters in
11877 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000011878 for Vim commands, |shellescape()| for |:!| commands.
11879 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +000011880 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +010011881 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000011882<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011883 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010011884 starting or ending "if", "while" and "for" does not
11885 always work, because when commands are skipped the
11886 ":execute" is not evaluated and Vim loses track of
11887 where blocks start and end. Also "break" and
11888 "continue" should not be inside ":execute".
11889 This example does not work, because the ":execute" is
11890 not evaluated and Vim does not see the "while", and
11891 gives an error for finding an ":endwhile": >
11892 :if 0
11893 : execute 'while i > 5'
11894 : echo "test"
11895 : endwhile
11896 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000011897<
11898 It is allowed to have a "while" or "if" command
11899 completely in the executed string: >
11900 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
11901<
11902
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011903 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011904 ":execute", ":echo" and ":echon" cannot be followed by
11905 a comment directly, because they see the '"' as the
11906 start of a string. But, you can use '|' followed by a
11907 comment. Example: >
11908 :echo "foo" | "this is a comment
11909
11910==============================================================================
119118. Exception handling *exception-handling*
11912
11913The Vim script language comprises an exception handling feature. This section
11914explains how it can be used in a Vim script.
11915
11916Exceptions may be raised by Vim on an error or on interrupt, see
11917|catch-errors| and |catch-interrupt|. You can also explicitly throw an
11918exception by using the ":throw" command, see |throw-catch|.
11919
11920
11921TRY CONDITIONALS *try-conditionals*
11922
11923Exceptions can be caught or can cause cleanup code to be executed. You can
11924use a try conditional to specify catch clauses (that catch exceptions) and/or
11925a finally clause (to be executed for cleanup).
11926 A try conditional begins with a |:try| command and ends at the matching
11927|:endtry| command. In between, you can use a |:catch| command to start
11928a catch clause, or a |:finally| command to start a finally clause. There may
11929be none or multiple catch clauses, but there is at most one finally clause,
11930which must not be followed by any catch clauses. The lines before the catch
11931clauses and the finally clause is called a try block. >
11932
11933 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000011934 : ...
11935 : ... TRY BLOCK
11936 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011937 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011938 : ...
11939 : ... CATCH CLAUSE
11940 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011941 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011942 : ...
11943 : ... CATCH CLAUSE
11944 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011945 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000011946 : ...
11947 : ... FINALLY CLAUSE
11948 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011949 :endtry
11950
11951The try conditional allows to watch code for exceptions and to take the
11952appropriate actions. Exceptions from the try block may be caught. Exceptions
11953from the try block and also the catch clauses may cause cleanup actions.
11954 When no exception is thrown during execution of the try block, the control
11955is transferred to the finally clause, if present. After its execution, the
11956script continues with the line following the ":endtry".
11957 When an exception occurs during execution of the try block, the remaining
11958lines in the try block are skipped. The exception is matched against the
11959patterns specified as arguments to the ":catch" commands. The catch clause
11960after the first matching ":catch" is taken, other catch clauses are not
11961executed. The catch clause ends when the next ":catch", ":finally", or
11962":endtry" command is reached - whatever is first. Then, the finally clause
11963(if present) is executed. When the ":endtry" is reached, the script execution
11964continues in the following line as usual.
11965 When an exception that does not match any of the patterns specified by the
11966":catch" commands is thrown in the try block, the exception is not caught by
11967that try conditional and none of the catch clauses is executed. Only the
11968finally clause, if present, is taken. The exception pends during execution of
11969the finally clause. It is resumed at the ":endtry", so that commands after
11970the ":endtry" are not executed and the exception might be caught elsewhere,
11971see |try-nesting|.
11972 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020011973remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000011974not matched against the patterns in any of the ":catch" commands of the same
11975try conditional and none of its catch clauses is taken. If there is, however,
11976a finally clause, it is executed, and the exception pends during its
11977execution. The commands following the ":endtry" are not executed. The new
11978exception might, however, be caught elsewhere, see |try-nesting|.
11979 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020011980thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000011981clause has been taken because of an exception from the try block or one of the
11982catch clauses, the original (pending) exception is discarded. The commands
11983following the ":endtry" are not executed, and the exception from the finally
11984clause is propagated and can be caught elsewhere, see |try-nesting|.
11985
11986The finally clause is also executed, when a ":break" or ":continue" for
11987a ":while" loop enclosing the complete try conditional is executed from the
11988try block or a catch clause. Or when a ":return" or ":finish" is executed
11989from the try block or a catch clause of a try conditional in a function or
11990sourced script, respectively. The ":break", ":continue", ":return", or
11991":finish" pends during execution of the finally clause and is resumed when the
11992":endtry" is reached. It is, however, discarded when an exception is thrown
11993from the finally clause.
11994 When a ":break" or ":continue" for a ":while" loop enclosing the complete
11995try conditional or when a ":return" or ":finish" is encountered in the finally
11996clause, the rest of the finally clause is skipped, and the ":break",
11997":continue", ":return" or ":finish" is executed as usual. If the finally
11998clause has been taken because of an exception or an earlier ":break",
11999":continue", ":return", or ":finish" from the try block or a catch clause,
12000this pending exception or command is discarded.
12001
12002For examples see |throw-catch| and |try-finally|.
12003
12004
12005NESTING OF TRY CONDITIONALS *try-nesting*
12006
12007Try conditionals can be nested arbitrarily. That is, a complete try
12008conditional can be put into the try block, a catch clause, or the finally
12009clause of another try conditional. If the inner try conditional does not
12010catch an exception thrown in its try block or throws a new exception from one
12011of its catch clauses or its finally clause, the outer try conditional is
12012checked according to the rules above. If the inner try conditional is in the
12013try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020012014otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000012015nesting, whether the inner try conditional is directly contained in the outer
12016one, or whether the outer one sources a script or calls a function containing
12017the inner try conditional.
12018
12019When none of the active try conditionals catches an exception, just their
12020finally clauses are executed. Thereafter, the script processing terminates.
12021An error message is displayed in case of an uncaught exception explicitly
12022thrown by a ":throw" command. For uncaught error and interrupt exceptions
12023implicitly raised by Vim, the error message(s) or interrupt message are shown
12024as usual.
12025
12026For examples see |throw-catch|.
12027
12028
12029EXAMINING EXCEPTION HANDLING CODE *except-examine*
12030
12031Exception handling code can get tricky. If you are in doubt what happens, set
12032'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
12033script file. Then you see when an exception is thrown, discarded, caught, or
12034finished. When using a verbosity level of at least 14, things pending in
12035a finally clause are also shown. This information is also given in debug mode
12036(see |debug-scripts|).
12037
12038
12039THROWING AND CATCHING EXCEPTIONS *throw-catch*
12040
12041You can throw any number or string as an exception. Use the |:throw| command
12042and pass the value to be thrown as argument: >
12043 :throw 4711
12044 :throw "string"
12045< *throw-expression*
12046You can also specify an expression argument. The expression is then evaluated
12047first, and the result is thrown: >
12048 :throw 4705 + strlen("string")
12049 :throw strpart("strings", 0, 6)
12050
12051An exception might be thrown during evaluation of the argument of the ":throw"
12052command. Unless it is caught there, the expression evaluation is abandoned.
12053The ":throw" command then does not throw a new exception.
12054 Example: >
12055
12056 :function! Foo(arg)
12057 : try
12058 : throw a:arg
12059 : catch /foo/
12060 : endtry
12061 : return 1
12062 :endfunction
12063 :
12064 :function! Bar()
12065 : echo "in Bar"
12066 : return 4710
12067 :endfunction
12068 :
12069 :throw Foo("arrgh") + Bar()
12070
12071This throws "arrgh", and "in Bar" is not displayed since Bar() is not
12072executed. >
12073 :throw Foo("foo") + Bar()
12074however displays "in Bar" and throws 4711.
12075
12076Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020012077abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000012078exception is then propagated to the caller of the command.
12079 Example: >
12080
12081 :if Foo("arrgh")
12082 : echo "then"
12083 :else
12084 : echo "else"
12085 :endif
12086
12087Here neither of "then" or "else" is displayed.
12088
12089 *catch-order*
12090Exceptions can be caught by a try conditional with one or more |:catch|
12091commands, see |try-conditionals|. The values to be caught by each ":catch"
12092command can be specified as a pattern argument. The subsequent catch clause
12093gets executed when a matching exception is caught.
12094 Example: >
12095
12096 :function! Foo(value)
12097 : try
12098 : throw a:value
12099 : catch /^\d\+$/
12100 : echo "Number thrown"
12101 : catch /.*/
12102 : echo "String thrown"
12103 : endtry
12104 :endfunction
12105 :
12106 :call Foo(0x1267)
12107 :call Foo('string')
12108
12109The first call to Foo() displays "Number thrown", the second "String thrown".
12110An exception is matched against the ":catch" commands in the order they are
12111specified. Only the first match counts. So you should place the more
12112specific ":catch" first. The following order does not make sense: >
12113
12114 : catch /.*/
12115 : echo "String thrown"
12116 : catch /^\d\+$/
12117 : echo "Number thrown"
12118
12119The first ":catch" here matches always, so that the second catch clause is
12120never taken.
12121
12122 *throw-variables*
12123If you catch an exception by a general pattern, you may access the exact value
12124in the variable |v:exception|: >
12125
12126 : catch /^\d\+$/
12127 : echo "Number thrown. Value is" v:exception
12128
12129You may also be interested where an exception was thrown. This is stored in
12130|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
12131exception most recently caught as long it is not finished.
12132 Example: >
12133
12134 :function! Caught()
12135 : if v:exception != ""
12136 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
12137 : else
12138 : echo 'Nothing caught'
12139 : endif
12140 :endfunction
12141 :
12142 :function! Foo()
12143 : try
12144 : try
12145 : try
12146 : throw 4711
12147 : finally
12148 : call Caught()
12149 : endtry
12150 : catch /.*/
12151 : call Caught()
12152 : throw "oops"
12153 : endtry
12154 : catch /.*/
12155 : call Caught()
12156 : finally
12157 : call Caught()
12158 : endtry
12159 :endfunction
12160 :
12161 :call Foo()
12162
12163This displays >
12164
12165 Nothing caught
12166 Caught "4711" in function Foo, line 4
12167 Caught "oops" in function Foo, line 10
12168 Nothing caught
12169
12170A practical example: The following command ":LineNumber" displays the line
12171number in the script or function where it has been used: >
12172
12173 :function! LineNumber()
12174 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
12175 :endfunction
12176 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
12177<
12178 *try-nested*
12179An exception that is not caught by a try conditional can be caught by
12180a surrounding try conditional: >
12181
12182 :try
12183 : try
12184 : throw "foo"
12185 : catch /foobar/
12186 : echo "foobar"
12187 : finally
12188 : echo "inner finally"
12189 : endtry
12190 :catch /foo/
12191 : echo "foo"
12192 :endtry
12193
12194The inner try conditional does not catch the exception, just its finally
12195clause is executed. The exception is then caught by the outer try
12196conditional. The example displays "inner finally" and then "foo".
12197
12198 *throw-from-catch*
12199You can catch an exception and throw a new one to be caught elsewhere from the
12200catch clause: >
12201
12202 :function! Foo()
12203 : throw "foo"
12204 :endfunction
12205 :
12206 :function! Bar()
12207 : try
12208 : call Foo()
12209 : catch /foo/
12210 : echo "Caught foo, throw bar"
12211 : throw "bar"
12212 : endtry
12213 :endfunction
12214 :
12215 :try
12216 : call Bar()
12217 :catch /.*/
12218 : echo "Caught" v:exception
12219 :endtry
12220
12221This displays "Caught foo, throw bar" and then "Caught bar".
12222
12223 *rethrow*
12224There is no real rethrow in the Vim script language, but you may throw
12225"v:exception" instead: >
12226
12227 :function! Bar()
12228 : try
12229 : call Foo()
12230 : catch /.*/
12231 : echo "Rethrow" v:exception
12232 : throw v:exception
12233 : endtry
12234 :endfunction
12235< *try-echoerr*
12236Note that this method cannot be used to "rethrow" Vim error or interrupt
12237exceptions, because it is not possible to fake Vim internal exceptions.
12238Trying so causes an error exception. You should throw your own exception
12239denoting the situation. If you want to cause a Vim error exception containing
12240the original error exception value, you can use the |:echoerr| command: >
12241
12242 :try
12243 : try
12244 : asdf
12245 : catch /.*/
12246 : echoerr v:exception
12247 : endtry
12248 :catch /.*/
12249 : echo v:exception
12250 :endtry
12251
12252This code displays
12253
Bram Moolenaar446cb832008-06-24 21:56:24 +000012254 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012255
12256
12257CLEANUP CODE *try-finally*
12258
12259Scripts often change global settings and restore them at their end. If the
12260user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020012261an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000012262a script when an error occurs or you explicitly throw an exception without
12263catching it. You can solve these problems by using a try conditional with
12264a finally clause for restoring the settings. Its execution is guaranteed on
12265normal control flow, on error, on an explicit ":throw", and on interrupt.
12266(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020012267to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000012268clause has been executed.)
12269Example: >
12270
12271 :try
12272 : let s:saved_ts = &ts
12273 : set ts=17
12274 :
12275 : " Do the hard work here.
12276 :
12277 :finally
12278 : let &ts = s:saved_ts
12279 : unlet s:saved_ts
12280 :endtry
12281
12282This method should be used locally whenever a function or part of a script
12283changes global settings which need to be restored on failure or normal exit of
12284that function or script part.
12285
12286 *break-finally*
12287Cleanup code works also when the try block or a catch clause is left by
12288a ":continue", ":break", ":return", or ":finish".
12289 Example: >
12290
12291 :let first = 1
12292 :while 1
12293 : try
12294 : if first
12295 : echo "first"
12296 : let first = 0
12297 : continue
12298 : else
12299 : throw "second"
12300 : endif
12301 : catch /.*/
12302 : echo v:exception
12303 : break
12304 : finally
12305 : echo "cleanup"
12306 : endtry
12307 : echo "still in while"
12308 :endwhile
12309 :echo "end"
12310
12311This displays "first", "cleanup", "second", "cleanup", and "end". >
12312
12313 :function! Foo()
12314 : try
12315 : return 4711
12316 : finally
12317 : echo "cleanup\n"
12318 : endtry
12319 : echo "Foo still active"
12320 :endfunction
12321 :
12322 :echo Foo() "returned by Foo"
12323
12324This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020012325extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000012326return value.)
12327
12328 *except-from-finally*
12329Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
12330a finally clause is possible, but not recommended since it abandons the
12331cleanup actions for the try conditional. But, of course, interrupt and error
12332exceptions might get raised from a finally clause.
12333 Example where an error in the finally clause stops an interrupt from
12334working correctly: >
12335
12336 :try
12337 : try
12338 : echo "Press CTRL-C for interrupt"
12339 : while 1
12340 : endwhile
12341 : finally
12342 : unlet novar
12343 : endtry
12344 :catch /novar/
12345 :endtry
12346 :echo "Script still running"
12347 :sleep 1
12348
12349If you need to put commands that could fail into a finally clause, you should
12350think about catching or ignoring the errors in these commands, see
12351|catch-errors| and |ignore-errors|.
12352
12353
12354CATCHING ERRORS *catch-errors*
12355
12356If you want to catch specific errors, you just have to put the code to be
12357watched in a try block and add a catch clause for the error message. The
12358presence of the try conditional causes all errors to be converted to an
12359exception. No message is displayed and |v:errmsg| is not set then. To find
12360the right pattern for the ":catch" command, you have to know how the format of
12361the error exception is.
12362 Error exceptions have the following format: >
12363
12364 Vim({cmdname}):{errmsg}
12365or >
12366 Vim:{errmsg}
12367
12368{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020012369the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000012370when the error occurs outside try conditionals. It always begins with
12371a capital "E", followed by a two or three-digit error number, a colon, and
12372a space.
12373
12374Examples:
12375
12376The command >
12377 :unlet novar
12378normally produces the error message >
12379 E108: No such variable: "novar"
12380which is converted inside try conditionals to an exception >
12381 Vim(unlet):E108: No such variable: "novar"
12382
12383The command >
12384 :dwim
12385normally produces the error message >
12386 E492: Not an editor command: dwim
12387which is converted inside try conditionals to an exception >
12388 Vim:E492: Not an editor command: dwim
12389
12390You can catch all ":unlet" errors by a >
12391 :catch /^Vim(unlet):/
12392or all errors for misspelled command names by a >
12393 :catch /^Vim:E492:/
12394
12395Some error messages may be produced by different commands: >
12396 :function nofunc
12397and >
12398 :delfunction nofunc
12399both produce the error message >
12400 E128: Function name must start with a capital: nofunc
12401which is converted inside try conditionals to an exception >
12402 Vim(function):E128: Function name must start with a capital: nofunc
12403or >
12404 Vim(delfunction):E128: Function name must start with a capital: nofunc
12405respectively. You can catch the error by its number independently on the
12406command that caused it if you use the following pattern: >
12407 :catch /^Vim(\a\+):E128:/
12408
12409Some commands like >
12410 :let x = novar
12411produce multiple error messages, here: >
12412 E121: Undefined variable: novar
12413 E15: Invalid expression: novar
12414Only the first is used for the exception value, since it is the most specific
12415one (see |except-several-errors|). So you can catch it by >
12416 :catch /^Vim(\a\+):E121:/
12417
12418You can catch all errors related to the name "nofunc" by >
12419 :catch /\<nofunc\>/
12420
12421You can catch all Vim errors in the ":write" and ":read" commands by >
12422 :catch /^Vim(\(write\|read\)):E\d\+:/
12423
12424You can catch all Vim errors by the pattern >
12425 :catch /^Vim\((\a\+)\)\=:E\d\+:/
12426<
12427 *catch-text*
12428NOTE: You should never catch the error message text itself: >
12429 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010012430only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000012431a different language by the |:language| command. It is however helpful to
12432cite the message text in a comment: >
12433 :catch /^Vim(\a\+):E108:/ " No such variable
12434
12435
12436IGNORING ERRORS *ignore-errors*
12437
12438You can ignore errors in a specific Vim command by catching them locally: >
12439
12440 :try
12441 : write
12442 :catch
12443 :endtry
12444
12445But you are strongly recommended NOT to use this simple form, since it could
12446catch more than you want. With the ":write" command, some autocommands could
12447be executed and cause errors not related to writing, for instance: >
12448
12449 :au BufWritePre * unlet novar
12450
12451There could even be such errors you are not responsible for as a script
12452writer: a user of your script might have defined such autocommands. You would
12453then hide the error from the user.
12454 It is much better to use >
12455
12456 :try
12457 : write
12458 :catch /^Vim(write):/
12459 :endtry
12460
12461which only catches real write errors. So catch only what you'd like to ignore
12462intentionally.
12463
12464For a single command that does not cause execution of autocommands, you could
12465even suppress the conversion of errors to exceptions by the ":silent!"
12466command: >
12467 :silent! nunmap k
12468This works also when a try conditional is active.
12469
12470
12471CATCHING INTERRUPTS *catch-interrupt*
12472
12473When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020012474the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000012475script is not terminated, then.
12476 Example: >
12477
12478 :function! TASK1()
12479 : sleep 10
12480 :endfunction
12481
12482 :function! TASK2()
12483 : sleep 20
12484 :endfunction
12485
12486 :while 1
12487 : let command = input("Type a command: ")
12488 : try
12489 : if command == ""
12490 : continue
12491 : elseif command == "END"
12492 : break
12493 : elseif command == "TASK1"
12494 : call TASK1()
12495 : elseif command == "TASK2"
12496 : call TASK2()
12497 : else
12498 : echo "\nIllegal command:" command
12499 : continue
12500 : endif
12501 : catch /^Vim:Interrupt$/
12502 : echo "\nCommand interrupted"
12503 : " Caught the interrupt. Continue with next prompt.
12504 : endtry
12505 :endwhile
12506
12507You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020012508a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012509
12510For testing what happens when CTRL-C would be pressed on a specific line in
12511your script, use the debug mode and execute the |>quit| or |>interrupt|
12512command on that line. See |debug-scripts|.
12513
12514
12515CATCHING ALL *catch-all*
12516
12517The commands >
12518
12519 :catch /.*/
12520 :catch //
12521 :catch
12522
12523catch everything, error exceptions, interrupt exceptions and exceptions
12524explicitly thrown by the |:throw| command. This is useful at the top level of
12525a script in order to catch unexpected things.
12526 Example: >
12527
12528 :try
12529 :
12530 : " do the hard work here
12531 :
12532 :catch /MyException/
12533 :
12534 : " handle known problem
12535 :
12536 :catch /^Vim:Interrupt$/
12537 : echo "Script interrupted"
12538 :catch /.*/
12539 : echo "Internal error (" . v:exception . ")"
12540 : echo " - occurred at " . v:throwpoint
12541 :endtry
12542 :" end of script
12543
12544Note: Catching all might catch more things than you want. Thus, you are
12545strongly encouraged to catch only for problems that you can really handle by
12546specifying a pattern argument to the ":catch".
12547 Example: Catching all could make it nearly impossible to interrupt a script
12548by pressing CTRL-C: >
12549
12550 :while 1
12551 : try
12552 : sleep 1
12553 : catch
12554 : endtry
12555 :endwhile
12556
12557
12558EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
12559
12560Exceptions may be used during execution of autocommands. Example: >
12561
12562 :autocmd User x try
12563 :autocmd User x throw "Oops!"
12564 :autocmd User x catch
12565 :autocmd User x echo v:exception
12566 :autocmd User x endtry
12567 :autocmd User x throw "Arrgh!"
12568 :autocmd User x echo "Should not be displayed"
12569 :
12570 :try
12571 : doautocmd User x
12572 :catch
12573 : echo v:exception
12574 :endtry
12575
12576This displays "Oops!" and "Arrgh!".
12577
12578 *except-autocmd-Pre*
12579For some commands, autocommands get executed before the main action of the
12580command takes place. If an exception is thrown and not caught in the sequence
12581of autocommands, the sequence and the command that caused its execution are
12582abandoned and the exception is propagated to the caller of the command.
12583 Example: >
12584
12585 :autocmd BufWritePre * throw "FAIL"
12586 :autocmd BufWritePre * echo "Should not be displayed"
12587 :
12588 :try
12589 : write
12590 :catch
12591 : echo "Caught:" v:exception "from" v:throwpoint
12592 :endtry
12593
12594Here, the ":write" command does not write the file currently being edited (as
12595you can see by checking 'modified'), since the exception from the BufWritePre
12596autocommand abandons the ":write". The exception is then caught and the
12597script displays: >
12598
12599 Caught: FAIL from BufWrite Auto commands for "*"
12600<
12601 *except-autocmd-Post*
12602For some commands, autocommands get executed after the main action of the
12603command has taken place. If this main action fails and the command is inside
12604an active try conditional, the autocommands are skipped and an error exception
12605is thrown that can be caught by the caller of the command.
12606 Example: >
12607
12608 :autocmd BufWritePost * echo "File successfully written!"
12609 :
12610 :try
12611 : write /i/m/p/o/s/s/i/b/l/e
12612 :catch
12613 : echo v:exception
12614 :endtry
12615
12616This just displays: >
12617
12618 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
12619
12620If you really need to execute the autocommands even when the main action
12621fails, trigger the event from the catch clause.
12622 Example: >
12623
12624 :autocmd BufWritePre * set noreadonly
12625 :autocmd BufWritePost * set readonly
12626 :
12627 :try
12628 : write /i/m/p/o/s/s/i/b/l/e
12629 :catch
12630 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
12631 :endtry
12632<
12633You can also use ":silent!": >
12634
12635 :let x = "ok"
12636 :let v:errmsg = ""
12637 :autocmd BufWritePost * if v:errmsg != ""
12638 :autocmd BufWritePost * let x = "after fail"
12639 :autocmd BufWritePost * endif
12640 :try
12641 : silent! write /i/m/p/o/s/s/i/b/l/e
12642 :catch
12643 :endtry
12644 :echo x
12645
12646This displays "after fail".
12647
12648If the main action of the command does not fail, exceptions from the
12649autocommands will be catchable by the caller of the command: >
12650
12651 :autocmd BufWritePost * throw ":-("
12652 :autocmd BufWritePost * echo "Should not be displayed"
12653 :
12654 :try
12655 : write
12656 :catch
12657 : echo v:exception
12658 :endtry
12659<
12660 *except-autocmd-Cmd*
12661For some commands, the normal action can be replaced by a sequence of
12662autocommands. Exceptions from that sequence will be catchable by the caller
12663of the command.
12664 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020012665had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000012666some way. >
12667
12668 :if !exists("cnt")
12669 : let cnt = 0
12670 :
12671 : autocmd BufWriteCmd * if &modified
12672 : autocmd BufWriteCmd * let cnt = cnt + 1
12673 : autocmd BufWriteCmd * if cnt % 3 == 2
12674 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12675 : autocmd BufWriteCmd * endif
12676 : autocmd BufWriteCmd * write | set nomodified
12677 : autocmd BufWriteCmd * if cnt % 3 == 0
12678 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12679 : autocmd BufWriteCmd * endif
12680 : autocmd BufWriteCmd * echo "File successfully written!"
12681 : autocmd BufWriteCmd * endif
12682 :endif
12683 :
12684 :try
12685 : write
12686 :catch /^BufWriteCmdError$/
12687 : if &modified
12688 : echo "Error on writing (file contents not changed)"
12689 : else
12690 : echo "Error after writing"
12691 : endif
12692 :catch /^Vim(write):/
12693 : echo "Error on writing"
12694 :endtry
12695
12696When this script is sourced several times after making changes, it displays
12697first >
12698 File successfully written!
12699then >
12700 Error on writing (file contents not changed)
12701then >
12702 Error after writing
12703etc.
12704
12705 *except-autocmd-ill*
12706You cannot spread a try conditional over autocommands for different events.
12707The following code is ill-formed: >
12708
12709 :autocmd BufWritePre * try
12710 :
12711 :autocmd BufWritePost * catch
12712 :autocmd BufWritePost * echo v:exception
12713 :autocmd BufWritePost * endtry
12714 :
12715 :write
12716
12717
12718EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
12719
12720Some programming languages allow to use hierarchies of exception classes or to
12721pass additional information with the object of an exception class. You can do
12722similar things in Vim.
12723 In order to throw an exception from a hierarchy, just throw the complete
12724class name with the components separated by a colon, for instance throw the
12725string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
12726 When you want to pass additional information with your exception class, add
12727it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
12728for an error when writing "myfile".
12729 With the appropriate patterns in the ":catch" command, you can catch for
12730base classes or derived classes of your hierarchy. Additional information in
12731parentheses can be cut out from |v:exception| with the ":substitute" command.
12732 Example: >
12733
12734 :function! CheckRange(a, func)
12735 : if a:a < 0
12736 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
12737 : endif
12738 :endfunction
12739 :
12740 :function! Add(a, b)
12741 : call CheckRange(a:a, "Add")
12742 : call CheckRange(a:b, "Add")
12743 : let c = a:a + a:b
12744 : if c < 0
12745 : throw "EXCEPT:MATHERR:OVERFLOW"
12746 : endif
12747 : return c
12748 :endfunction
12749 :
12750 :function! Div(a, b)
12751 : call CheckRange(a:a, "Div")
12752 : call CheckRange(a:b, "Div")
12753 : if (a:b == 0)
12754 : throw "EXCEPT:MATHERR:ZERODIV"
12755 : endif
12756 : return a:a / a:b
12757 :endfunction
12758 :
12759 :function! Write(file)
12760 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000012761 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012762 : catch /^Vim(write):/
12763 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
12764 : endtry
12765 :endfunction
12766 :
12767 :try
12768 :
12769 : " something with arithmetics and I/O
12770 :
12771 :catch /^EXCEPT:MATHERR:RANGE/
12772 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
12773 : echo "Range error in" function
12774 :
12775 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
12776 : echo "Math error"
12777 :
12778 :catch /^EXCEPT:IO/
12779 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
12780 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
12781 : if file !~ '^/'
12782 : let file = dir . "/" . file
12783 : endif
12784 : echo 'I/O error for "' . file . '"'
12785 :
12786 :catch /^EXCEPT/
12787 : echo "Unspecified error"
12788 :
12789 :endtry
12790
12791The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
12792a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
12793exceptions with the "Vim" prefix; they are reserved for Vim.
12794 Vim error exceptions are parameterized with the name of the command that
12795failed, if known. See |catch-errors|.
12796
12797
12798PECULIARITIES
12799 *except-compat*
12800The exception handling concept requires that the command sequence causing the
12801exception is aborted immediately and control is transferred to finally clauses
12802and/or a catch clause.
12803
12804In the Vim script language there are cases where scripts and functions
12805continue after an error: in functions without the "abort" flag or in a command
12806after ":silent!", control flow goes to the following line, and outside
12807functions, control flow goes to the line following the outermost ":endwhile"
12808or ":endif". On the other hand, errors should be catchable as exceptions
12809(thus, requiring the immediate abortion).
12810
12811This problem has been solved by converting errors to exceptions and using
12812immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020012813conditional is active. This is no restriction since an (error) exception can
12814be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000012815termination without catching the error, just use a try conditional without
12816catch clause. (You can cause cleanup code being executed before termination
12817by specifying a finally clause.)
12818
12819When no try conditional is active, the usual abortion and continuation
12820behavior is used instead of immediate abortion. This ensures compatibility of
12821scripts written for Vim 6.1 and earlier.
12822
12823However, when sourcing an existing script that does not use exception handling
12824commands (or when calling one of its functions) from inside an active try
12825conditional of a new script, you might change the control flow of the existing
12826script on error. You get the immediate abortion on error and can catch the
12827error in the new script. If however the sourced script suppresses error
12828messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020012829|v:errmsg| if appropriate), its execution path is not changed. The error is
12830not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000012831where this happens is for scripts that don't care about errors and produce
12832error messages. You probably won't want to use such code from your new
12833scripts.
12834
12835 *except-syntax-err*
12836Syntax errors in the exception handling commands are never caught by any of
12837the ":catch" commands of the try conditional they belong to. Its finally
12838clauses, however, is executed.
12839 Example: >
12840
12841 :try
12842 : try
12843 : throw 4711
12844 : catch /\(/
12845 : echo "in catch with syntax error"
12846 : catch
12847 : echo "inner catch-all"
12848 : finally
12849 : echo "inner finally"
12850 : endtry
12851 :catch
12852 : echo 'outer catch-all caught "' . v:exception . '"'
12853 : finally
12854 : echo "outer finally"
12855 :endtry
12856
12857This displays: >
12858 inner finally
12859 outer catch-all caught "Vim(catch):E54: Unmatched \("
12860 outer finally
12861The original exception is discarded and an error exception is raised, instead.
12862
12863 *except-single-line*
12864The ":try", ":catch", ":finally", and ":endtry" commands can be put on
12865a single line, but then syntax errors may make it difficult to recognize the
12866"catch" line, thus you better avoid this.
12867 Example: >
12868 :try | unlet! foo # | catch | endtry
12869raises an error exception for the trailing characters after the ":unlet!"
12870argument, but does not see the ":catch" and ":endtry" commands, so that the
12871error exception is discarded and the "E488: Trailing characters" message gets
12872displayed.
12873
12874 *except-several-errors*
12875When several errors appear in a single command, the first error message is
12876usually the most specific one and therefor converted to the error exception.
12877 Example: >
12878 echo novar
12879causes >
12880 E121: Undefined variable: novar
12881 E15: Invalid expression: novar
12882The value of the error exception inside try conditionals is: >
12883 Vim(echo):E121: Undefined variable: novar
12884< *except-syntax-error*
12885But when a syntax error is detected after a normal error in the same command,
12886the syntax error is used for the exception being thrown.
12887 Example: >
12888 unlet novar #
12889causes >
12890 E108: No such variable: "novar"
12891 E488: Trailing characters
12892The value of the error exception inside try conditionals is: >
12893 Vim(unlet):E488: Trailing characters
12894This is done because the syntax error might change the execution path in a way
12895not intended by the user. Example: >
12896 try
12897 try | unlet novar # | catch | echo v:exception | endtry
12898 catch /.*/
12899 echo "outer catch:" v:exception
12900 endtry
12901This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
12902a "E600: Missing :endtry" error message is given, see |except-single-line|.
12903
12904==============================================================================
129059. Examples *eval-examples*
12906
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012907Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012908>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010012909 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012910 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012911 : let n = a:nr
12912 : let r = ""
12913 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012914 : let r = '01'[n % 2] . r
12915 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000012916 : endwhile
12917 : return r
12918 :endfunc
12919
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012920 :" The function String2Bin() converts each character in a string to a
12921 :" binary string, separated with dashes.
12922 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012923 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012924 : for ix in range(strlen(a:str))
12925 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
12926 : endfor
12927 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012928 :endfunc
12929
12930Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012931 :echo Nr2Bin(32)
12932result: "100000" >
12933 :echo String2Bin("32")
12934result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000012935
12936
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012937Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012938
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012939This example sorts lines with a specific compare function. >
12940
12941 :func SortBuffer()
12942 : let lines = getline(1, '$')
12943 : call sort(lines, function("Strcmp"))
12944 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012945 :endfunction
12946
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012947As a one-liner: >
12948 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000012949
Bram Moolenaar071d4272004-06-13 20:20:40 +000012950
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012951scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012952 *sscanf*
12953There is no sscanf() function in Vim. If you need to extract parts from a
12954line, you can use matchstr() and substitute() to do it. This example shows
12955how to get the file name, line number and column number out of a line like
12956"foobar.txt, 123, 45". >
12957 :" Set up the match bit
12958 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
12959 :"get the part matching the whole expression
12960 :let l = matchstr(line, mx)
12961 :"get each item out of the match
12962 :let file = substitute(l, mx, '\1', '')
12963 :let lnum = substitute(l, mx, '\2', '')
12964 :let col = substitute(l, mx, '\3', '')
12965
12966The input is in the variable "line", the results in the variables "file",
12967"lnum" and "col". (idea from Michael Geddes)
12968
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012969
12970getting the scriptnames in a Dictionary ~
12971 *scriptnames-dictionary*
12972The |:scriptnames| command can be used to get a list of all script files that
12973have been sourced. There is no equivalent function or variable for this
12974(because it's rarely needed). In case you need to manipulate the list this
12975code can be used: >
12976 " Get the output of ":scriptnames" in the scriptnames_output variable.
12977 let scriptnames_output = ''
12978 redir => scriptnames_output
12979 silent scriptnames
12980 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010012981
Bram Moolenaar446cb832008-06-24 21:56:24 +000012982 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012983 " "scripts" dictionary.
12984 let scripts = {}
12985 for line in split(scriptnames_output, "\n")
12986 " Only do non-blank lines.
12987 if line =~ '\S'
12988 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000012989 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012990 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000012991 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012992 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000012993 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012994 endif
12995 endfor
12996 unlet scriptnames_output
12997
Bram Moolenaar071d4272004-06-13 20:20:40 +000012998==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001299910. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +020013000 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013001Over time many features have been added to Vim script. This includes Ex
13002commands, functions, variable types, etc. Each individual feature can be
13003checked with the |has()| and |exists()| functions.
13004
13005Sometimes old syntax of functionality gets in the way of making Vim better.
13006When support is taken away this will break older Vim scripts. To make this
13007explicit the |:scriptversion| command can be used. When a Vim script is not
13008compatible with older versions of Vim this will give an explicit error,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020013009instead of failing in mysterious ways.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013010
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020013011 *scriptversion-1* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013012 :scriptversion 1
13013< This is the original Vim script, same as not using a |:scriptversion|
13014 command. Can be used to go back to old syntax for a range of lines.
13015 Test for support with: >
13016 has('vimscript-1')
13017
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020013018< *scriptversion-2* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013019 :scriptversion 2
Bram Moolenaar68e65602019-05-26 21:33:31 +020013020< String concatenation with "." is not supported, use ".." instead.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013021 This avoids the ambiguity using "." for Dict member access and
13022 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020013023
13024 *scriptversion-3* >
Bram Moolenaar911ead12019-04-21 00:03:35 +020013025 :scriptversion 3
13026< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
13027 work as |v:version| anymore, it can be used as a normal variable.
13028 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013029
Bram Moolenaar911ead12019-04-21 00:03:35 +020013030 Test for support with: >
13031 has('vimscript-3')
Bram Moolenaar60a8de22019-09-15 14:33:22 +020013032<
13033 *scriptversion-4* >
13034 :scriptversion 4
13035< Numbers with a leading zero are not recognized as octal. With the
13036 previous version you get: >
13037 echo 017 " displays 15
13038 echo 018 " displays 18
13039< with script version 4: >
13040 echo 017 " displays 17
13041 echo 018 " displays 18
13042< Also, it is possible to use single quotes inside numbers to make them
13043 easier to read: >
13044 echo 1'000'000
13045< The quotes must be surrounded by digits.
13046
13047 Test for support with: >
13048 has('vimscript-4')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013049
13050==============================================================================
1305111. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013052
13053When the |+eval| feature was disabled at compile time, none of the expression
13054evaluation commands are available. To prevent this from causing Vim scripts
13055to generate all kinds of errors, the ":if" and ":endif" commands are still
13056recognized, though the argument of the ":if" and everything between the ":if"
13057and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
13058only if the commands are at the start of the line. The ":else" command is not
13059recognized.
13060
13061Example of how to avoid executing commands when the |+eval| feature is
13062missing: >
13063
13064 :if 1
13065 : echo "Expression evaluation is compiled in"
13066 :else
13067 : echo "You will _never_ see this message"
13068 :endif
13069
Bram Moolenaar773a97c2019-06-06 20:39:55 +020013070To execute a command only when the |+eval| feature is disabled can be done in
13071two ways. The simplest is to exit the script (or Vim) prematurely: >
13072 if 1
13073 echo "commands executed with +eval"
13074 finish
13075 endif
13076 args " command executed without +eval
13077
13078If you do not want to abort loading the script you can use a trick, as this
13079example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020013080
13081 silent! while 0
13082 set history=111
13083 silent! endwhile
13084
13085When the |+eval| feature is available the command is skipped because of the
13086"while 0". Without the |+eval| feature the "while 0" is an error, which is
13087silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020013088
Bram Moolenaar071d4272004-06-13 20:20:40 +000013089==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001309012. The sandbox *eval-sandbox* *sandbox* *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013091
Bram Moolenaar368373e2010-07-19 20:46:22 +020013092The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
13093'foldtext' options may be evaluated in a sandbox. This means that you are
13094protected from these expressions having nasty side effects. This gives some
13095safety for when these options are set from a modeline. It is also used when
13096the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013097The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013098
13099These items are not allowed in the sandbox:
13100 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +020013101 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000013102 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013103 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013104 - executing a shell command
13105 - reading or writing a file
13106 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000013107 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013108This is not guaranteed 100% secure, but it should block most attacks.
13109
13110 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000013111:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013112 option that may have been set from a modeline, e.g.
13113 'foldexpr'.
13114
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013115 *sandbox-option*
13116A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000013117have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013118restrictive, thus this only happens when the option was set from an insecure
13119location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000013120- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013121- while executing in the sandbox
13122- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +020013123- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013124
13125Note that when in the sandbox and saving an option value and restoring it, the
13126option will still be marked as it was set in the sandbox.
13127
13128==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001312913. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013130
13131In a few situations it is not allowed to change the text in the buffer, jump
13132to another window and some other things that might confuse or break what Vim
13133is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020013134actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013135happen any moment the mouse cursor is resting at some position.
13136
13137This is not allowed when the textlock is active:
13138 - changing the buffer text
13139 - jumping to another buffer or window
13140 - editing another file
13141 - closing a window or quitting Vim
13142 - etc.
13143
Bram Moolenaar071d4272004-06-13 20:20:40 +000013144
Bram Moolenaar91f84f62018-07-29 15:07:52 +020013145 vim:tw=78:ts=8:noet:ft=help:norl: