blob: 3afd675518b8a5d75e77fe185e2779385217ec6f [file] [log] [blame]
Bram Moolenaar74240d32017-12-10 15:26:15 +01001*eval.txt* For Vim version 8.0. Last change: 2017 Dec 09
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|
20 1.5 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212. Expression syntax |expression-syntax|
223. Internal variable |internal-variables|
234. Builtin Functions |functions|
245. Defining functions |user-functions|
256. Curly braces names |curly-braces-names|
267. Commands |expression-commands|
278. Exception handling |exception-handling|
289. Examples |eval-examples|
2910. No +eval feature |no-eval-feature|
3011. The sandbox |eval-sandbox|
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003112. Textlock |textlock|
Bram Moolenaardc1f1642016-08-16 18:33:43 +02003213. Testing |testing|
Bram Moolenaar071d4272004-06-13 20:20:40 +000033
34{Vi does not have any of these commands}
35
36==============================================================================
371. Variables *variables*
38
Bram Moolenaar13065c42005-01-08 16:08:21 +0000391.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000040 *E712*
Bram Moolenaar38a55632016-02-15 22:07:32 +010041There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000042
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020043Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020044 64-bit Numbers are available only when compiled with the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020045 |+num64| feature.
Bram Moolenaar7571d552016-08-18 22:54:46 +020046 Examples: -123 0x10 0177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000047
Bram Moolenaar446cb832008-06-24 21:56:24 +000048Float A floating point number. |floating-point-format| *Float*
49 {only when compiled with the |+float| feature}
50 Examples: 123.456 1.15e-6 -1.1e3
51
Bram Moolenaar06481422016-04-30 15:13:38 +020052 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000053String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000054 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000055
Bram Moolenaard8b02732005-01-14 21:48:43 +000056List An ordered sequence of items |List|.
57 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000059Dictionary An associative, unordered array: Each entry has a key and a
60 value. |Dictionary|
61 Example: {'blue': "#0000ff", 'red': "#ff0000"}
62
Bram Moolenaar835dc632016-02-07 14:27:38 +010063Funcref A reference to a function |Funcref|.
64 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020065 It can be bound to a dictionary and arguments, it then works
66 like a Partial.
67 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010068
Bram Moolenaar02e83b42016-02-21 20:10:26 +010069Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010070
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020071Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010072
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020073Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010074
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000075The Number and String types are converted automatically, depending on how they
76are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000077
78Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020079the Number. Examples:
80 Number 123 --> String "123" ~
81 Number 0 --> String "0" ~
82 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020083 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010084Conversion from a String to a Number is done by converting the first digits to
85a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
86recognized. If the String doesn't start with digits, the result is zero.
87Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020088 String "456" --> Number 456 ~
89 String "6bar" --> Number 6 ~
90 String "foo" --> Number 0 ~
91 String "0xf1" --> Number 241 ~
92 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010093 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020094 String "-8" --> Number -8 ~
95 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000096
97To force conversion from String to Number, add zero to it: >
98 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000099< 64 ~
100
101To avoid a leading zero to cause octal conversion, or for using a different
102base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000103
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200104 *TRUE* *FALSE*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000105For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200106You can also use |v:false| and |v:true|. When TRUE is returned from a
107function it is the Number one, FALSE is the number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000108
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200109Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000110 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200111 :" NOT executed
112"foo" is converted to 0, which means FALSE. If the string starts with a
113non-zero number it means TRUE: >
114 :if "8foo"
115 :" executed
116To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200117 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100118<
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200119 *non-zero-arg*
120Function arguments often behave slightly different from |TRUE|: If the
121argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200122non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100123Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
124A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200125
Bram Moolenaar38a55632016-02-15 22:07:32 +0100126 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200127List, Dictionary, Funcref, Job and Channel types are not automatically
128converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000129
Bram Moolenaar446cb832008-06-24 21:56:24 +0000130 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200131When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000132there is no automatic conversion of Float. You can use str2float() for String
133to Float, printf() for Float to String and float2nr() for Float to Number.
134
Bram Moolenaar38a55632016-02-15 22:07:32 +0100135 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100136When expecting a Float a Number can also be used, but nothing else.
137
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100138 *no-type-checking*
139You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000140
Bram Moolenaar13065c42005-01-08 16:08:21 +0000141
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001421.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000143 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200144A Funcref variable is obtained with the |function()| function, the |funcref()|
145function or created with the lambda expression |expr-lambda|. It can be used
146in an expression in the place of a function name, before the parenthesis
147around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000148
149 :let Fn = function("MyFunc")
150 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000151< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000152A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200153can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000154cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000155
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000156A special case is defining a function and directly assigning its Funcref to a
157Dictionary entry. Example: >
158 :function dict.init() dict
159 : let self.val = 0
160 :endfunction
161
162The key of the Dictionary can start with a lower case letter. The actual
163function name is not used here. Also see |numbered-function|.
164
165A Funcref can also be used with the |:call| command: >
166 :call Fn()
167 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000168
169The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000170 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000171
172You can use |call()| to invoke a Funcref and use a list variable for the
173arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000174 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200175<
176 *Partial*
177A Funcref optionally binds a Dictionary and/or arguments. This is also called
178a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200179function() or funcref(). When calling the function the Dictionary and/or
180arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200181
182 let Cb = function('Callback', ['foo'], myDict)
183 call Cb()
184
185This will invoke the function as if using: >
186 call myDict.Callback('foo')
187
188This is very useful when passing a function around, e.g. in the arguments of
189|ch_open()|.
190
191Note that binding a function to a Dictionary also happens when the function is
192a member of the Dictionary: >
193
194 let myDict.myFunction = MyFunction
195 call myDict.myFunction()
196
197Here MyFunction() will get myDict passed as "self". This happens when the
198"myFunction" member is accessed. When making assigning "myFunction" to
199otherDict and calling it, it will be bound to otherDict: >
200
201 let otherDict.myFunction = myDict.myFunction
202 call otherDict.myFunction()
203
204Now "self" will be "otherDict". But when the dictionary was bound explicitly
205this won't happen: >
206
207 let myDict.myFunction = function(MyFunction, myDict)
208 let otherDict.myFunction = myDict.myFunction
209 call otherDict.myFunction()
210
Bram Moolenaard823fa92016-08-12 16:29:27 +0200211Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000212
213
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002141.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200215 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000216A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200217can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000218position in the sequence.
219
Bram Moolenaar13065c42005-01-08 16:08:21 +0000220
221List creation ~
222 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000223A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000224Examples: >
225 :let mylist = [1, two, 3, "four"]
226 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000227
Bram Moolenaar58b85342016-08-14 19:54:54 +0200228An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000229List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000230 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000231
232An extra comma after the last item is ignored.
233
Bram Moolenaar13065c42005-01-08 16:08:21 +0000234
235List index ~
236 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000237An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000238after the List. Indexes are zero-based, thus the first item has index zero. >
239 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000240 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000242When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000243 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000244<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000245A negative index is counted from the end. Index -1 refers to the last item in
246the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000247 :let last = mylist[-1] " get the last item: "four"
248
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000250is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251 :echo get(mylist, idx)
252 :echo get(mylist, idx, "NONE")
253
254
255List concatenation ~
256
257Two lists can be concatenated with the "+" operator: >
258 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000259 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000260
261To prepend or append an item turn the item into a list by putting [] around
262it. To change a list in-place see |list-modification| below.
263
264
265Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200266 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000267A part of the List can be obtained by specifying the first and last index,
268separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000269 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000270
271Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000272similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000273 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
274 :let shortlist = mylist[2:2] " List with one item: [3]
275 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000276
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000277If the first index is beyond the last item of the List or the second item is
278before the first item, the result is an empty list. There is no error
279message.
280
281If the second index is equal to or greater than the length of the list the
282length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000283 :let mylist = [0, 1, 2, 3]
284 :echo mylist[2:8] " result: [2, 3]
285
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000286NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200287using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000288mylist[s : e].
289
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000290
Bram Moolenaar13065c42005-01-08 16:08:21 +0000291List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000292 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000293When variable "aa" is a list and you assign it to another variable "bb", both
294variables refer to the same list. Thus changing the list "aa" will also
295change "bb": >
296 :let aa = [1, 2, 3]
297 :let bb = aa
298 :call add(aa, 4)
299 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000300< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000301
302Making a copy of a list is done with the |copy()| function. Using [:] also
303works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000304a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000305 :let aa = [[1, 'a'], 2, 3]
306 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000307 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000308 :let aa[0][1] = 'aaa'
309 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000310< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000311 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000312< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000313
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000314To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000316
317The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000318List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000319the same value. >
320 :let alist = [1, 2, 3]
321 :let blist = [1, 2, 3]
322 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000324 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000325< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000326
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000327Note about comparing lists: Two lists are considered equal if they have the
328same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000329exception: When comparing a number with a string they are considered
330different. There is no automatic type conversion, as with using "==" on
331variables. Example: >
332 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000333< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000334 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000335< 0
336
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000337Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000338can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000339
340 :let a = 5
341 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000342 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000343< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000344 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000345< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000346
Bram Moolenaar13065c42005-01-08 16:08:21 +0000347
348List unpack ~
349
350To unpack the items in a list to individual variables, put the variables in
351square brackets, like list items: >
352 :let [var1, var2] = mylist
353
354When the number of variables does not match the number of items in the list
355this produces an error. To handle any extra items from the list append ";"
356and a variable name: >
357 :let [var1, var2; rest] = mylist
358
359This works like: >
360 :let var1 = mylist[0]
361 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000362 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000363
364Except that there is no error if there are only two items. "rest" will be an
365empty list then.
366
367
368List modification ~
369 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000370To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000371 :let list[4] = "four"
372 :let listlist[0][3] = item
373
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000374To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000376 :let list[3:5] = [3, 4, 5]
377
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378Adding and removing items from a list is done with functions. Here are a few
379examples: >
380 :call insert(list, 'a') " prepend item 'a'
381 :call insert(list, 'a', 3) " insert item 'a' before list[3]
382 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000383 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000384 :call extend(list, [1, 2]) " extend the list with two more items
385 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000386 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000387 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000388 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000389 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000391Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000392 :call sort(list) " sort a list alphabetically
393 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100394 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000395
Bram Moolenaar13065c42005-01-08 16:08:21 +0000396
397For loop ~
398
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000399The |:for| loop executes commands for each item in a list. A variable is set
400to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000401 :for item in mylist
402 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000403 :endfor
404
405This works like: >
406 :let index = 0
407 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000408 : let item = mylist[index]
409 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000410 : let index = index + 1
411 :endwhile
412
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000413If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000414function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000415
Bram Moolenaar58b85342016-08-14 19:54:54 +0200416Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000417requires the argument to be a list of lists. >
418 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
419 : call Doit(lnum, col)
420 :endfor
421
422This works like a |:let| command is done for each list item. Again, the types
423must remain the same to avoid an error.
424
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000425It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000426 :for [i, j; rest] in listlist
427 : call Doit(i, j)
428 : if !empty(rest)
429 : echo "remainder: " . string(rest)
430 : endif
431 :endfor
432
433
434List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000435 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000436Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000437 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000438 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000439 :let l = len(list) " number of items in list
440 :let big = max(list) " maximum value in list
441 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000442 :let xs = count(list, 'x') " count nr of times 'x' appears in list
443 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000444 :let lines = getline(1, 10) " get ten text lines from buffer
445 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000446 :let list = split("a b c") " create list from items in a string
447 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000448 :let s = string(list) " String representation of list
449 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000450
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000451Don't forget that a combination of features can make things simple. For
452example, to add up all the numbers in a list: >
453 :exe 'let sum = ' . join(nrlist, '+')
454
Bram Moolenaar13065c42005-01-08 16:08:21 +0000455
Bram Moolenaard8b02732005-01-14 21:48:43 +00004561.4 Dictionaries ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200457 *dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000458A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000459entry can be located with the key. The entries are stored without a specific
460ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000461
462
463Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000464 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000465A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000466braces. Each entry has a key and a value, separated by a colon. Each key can
467only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000468 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
469 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000470< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000471A key is always a String. You can use a Number, it will be converted to a
472String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200473entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200474Number will be converted to the String '4'. The empty string can be used as a
475key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000476
Bram Moolenaar58b85342016-08-14 19:54:54 +0200477A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000478nested Dictionary: >
479 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
480
481An extra comma after the last entry is ignored.
482
483
484Accessing entries ~
485
486The normal way to access an entry is by putting the key in square brackets: >
487 :let val = mydict["one"]
488 :let mydict["four"] = 4
489
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000490You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000491
492For keys that consist entirely of letters, digits and underscore the following
493form can be used |expr-entry|: >
494 :let val = mydict.one
495 :let mydict.four = 4
496
497Since an entry can be any type, also a List and a Dictionary, the indexing and
498key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000499 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000500
501
502Dictionary to List conversion ~
503
Bram Moolenaar58b85342016-08-14 19:54:54 +0200504You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000505turn the Dictionary into a List and pass it to |:for|.
506
507Most often you want to loop over the keys, using the |keys()| function: >
508 :for key in keys(mydict)
509 : echo key . ': ' . mydict[key]
510 :endfor
511
512The List of keys is unsorted. You may want to sort them first: >
513 :for key in sort(keys(mydict))
514
515To loop over the values use the |values()| function: >
516 :for v in values(mydict)
517 : echo "value: " . v
518 :endfor
519
520If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000521a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000522 :for [key, value] in items(mydict)
523 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000524 :endfor
525
526
527Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000528 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000529Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
530Dictionary. Otherwise, assignment results in referring to the same
531Dictionary: >
532 :let onedict = {'a': 1, 'b': 2}
533 :let adict = onedict
534 :let adict['a'] = 11
535 :echo onedict['a']
536 11
537
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000538Two Dictionaries compare equal if all the key-value pairs compare equal. For
539more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000540
541
542Dictionary modification ~
543 *dict-modification*
544To change an already existing entry of a Dictionary, or to add a new entry,
545use |:let| this way: >
546 :let dict[4] = "four"
547 :let dict['one'] = item
548
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000549Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
550Three ways to remove the entry with key "aaa" from dict: >
551 :let i = remove(dict, 'aaa')
552 :unlet dict.aaa
553 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000554
555Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000556 :call extend(adict, bdict)
557This extends adict with all entries from bdict. Duplicate keys cause entries
558in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000559Note that the order of entries in a Dictionary is irrelevant, thus don't
560expect ":echo adict" to show the items from bdict after the older entries in
561adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000562
563Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000564 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000565This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000566
567
568Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100569 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000570When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200571special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000572 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000573 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000574 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000575 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
576 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000577
578This is like a method in object oriented programming. The entry in the
579Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
580the function was invoked from.
581
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000582It is also possible to add a function without the "dict" attribute as a
583Funcref to a Dictionary, but the "self" variable is not available then.
584
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000585 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000586To avoid the extra name for the function it can be defined and directly
587assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000588 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200589 :function mydict.len()
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 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000593
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000594The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200595that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000596|Funcref|. It will automatically be deleted when there is no |Funcref|
597remaining that refers to it.
598
599It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000600
Bram Moolenaar1affd722010-08-04 17:49:30 +0200601If you get an error for a numbered function, you can find out what it is with
602a trick. Assuming the function is 42, the command is: >
603 :function {42}
604
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000605
606Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000607 *E715*
608Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000609 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
610 :if empty(dict) " TRUE if dict is empty
611 :let l = len(dict) " number of items in dict
612 :let big = max(dict) " maximum value in dict
613 :let small = min(dict) " minimum value in dict
614 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
615 :let s = string(dict) " String representation of dict
616 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000617
618
6191.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000620 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000621If you need to know the type of a variable or expression, use the |type()|
622function.
623
624When the '!' flag is included in the 'viminfo' option, global variables that
625start with an uppercase letter, and don't contain a lowercase letter, are
626stored in the viminfo file |viminfo-file|.
627
628When the 'sessionoptions' option contains "global", global variables that
629start with an uppercase letter and contain at least one lowercase letter are
630stored in the session file |session-file|.
631
632variable name can be stored where ~
633my_var_6 not
634My_Var_6 session file
635MY_VAR_6 viminfo file
636
637
638It's possible to form a variable name with curly braces, see
639|curly-braces-names|.
640
641==============================================================================
6422. Expression syntax *expression-syntax*
643
644Expression syntax summary, from least to most significant:
645
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200646|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200647 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000648
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200649|expr2| expr3
650 expr3 || expr3 .. logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000651
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200652|expr3| expr4
653 expr4 && expr4 .. logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000654
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200655|expr4| expr5
656 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000657 expr5 != expr5 not equal
658 expr5 > expr5 greater than
659 expr5 >= expr5 greater than or equal
660 expr5 < expr5 smaller than
661 expr5 <= expr5 smaller than or equal
662 expr5 =~ expr5 regexp matches
663 expr5 !~ expr5 regexp doesn't match
664
665 expr5 ==? expr5 equal, ignoring case
666 expr5 ==# expr5 equal, match case
667 etc. As above, append ? for ignoring case, # for
668 matching case
669
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000670 expr5 is expr5 same |List| instance
671 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000672
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200673|expr5| expr6
674 expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000675 expr6 - expr6 .. number subtraction
676 expr6 . expr6 .. string concatenation
677
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200678|expr6| expr7
679 expr7 * expr7 .. number multiplication
Bram Moolenaar071d4272004-06-13 20:20:40 +0000680 expr7 / expr7 .. number division
681 expr7 % expr7 .. number modulo
682
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200683|expr7| expr8
684 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000685 - expr7 unary minus
686 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000687
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200688|expr8| expr9
689 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000690 expr8[expr1 : expr1] substring of a String or sublist of a |List|
691 expr8.name entry in a |Dictionary|
692 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000693
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200694|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000695 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000696 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000697 [expr1, ...] |List|
698 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000699 &option option value
700 (expr1) nested expression
701 variable internal variable
702 va{ria}ble internal variable with curly braces
703 $VAR environment variable
704 @r contents of register 'r'
705 function(expr1, ...) function call
706 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200707 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000708
709
710".." indicates that the operations in this level can be concatenated.
711Example: >
712 &nu || &list && &shell == "csh"
713
714All expressions within one level are parsed from left to right.
715
716
717expr1 *expr1* *E109*
718-----
719
720expr2 ? expr1 : expr1
721
722The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200723|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000724otherwise the result is the value of the expression after the ':'.
725Example: >
726 :echo lnum == 1 ? "top" : lnum
727
728Since the first expression is an "expr2", it cannot contain another ?:. The
729other two expressions can, thus allow for recursive use of ?:.
730Example: >
731 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
732
733To keep this readable, using |line-continuation| is suggested: >
734 :echo lnum == 1
735 :\ ? "top"
736 :\ : lnum == 1000
737 :\ ? "last"
738 :\ : lnum
739
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000740You should always put a space before the ':', otherwise it can be mistaken for
741use in a variable such as "a:1".
742
Bram Moolenaar071d4272004-06-13 20:20:40 +0000743
744expr2 and expr3 *expr2* *expr3*
745---------------
746
Bram Moolenaar04186092016-08-29 21:55:35 +0200747expr3 || expr3 .. logical OR *expr-barbar*
748expr4 && expr4 .. logical AND *expr-&&*
749
Bram Moolenaar071d4272004-06-13 20:20:40 +0000750The "||" and "&&" operators take one argument on each side. The arguments
751are (converted to) Numbers. The result is:
752
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200753 input output ~
754n1 n2 n1 || n2 n1 && n2 ~
755|FALSE| |FALSE| |FALSE| |FALSE|
756|FALSE| |TRUE| |TRUE| |FALSE|
757|TRUE| |FALSE| |TRUE| |FALSE|
758|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000759
760The operators can be concatenated, for example: >
761
762 &nu || &list && &shell == "csh"
763
764Note that "&&" takes precedence over "||", so this has the meaning of: >
765
766 &nu || (&list && &shell == "csh")
767
768Once the result is known, the expression "short-circuits", that is, further
769arguments are not evaluated. This is like what happens in C. For example: >
770
771 let a = 1
772 echo a || b
773
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200774This is valid even if there is no variable called "b" because "a" is |TRUE|,
775so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776
777 echo exists("b") && b == "yes"
778
779This is valid whether "b" has been defined or not. The second clause will
780only be evaluated if "b" has been defined.
781
782
783expr4 *expr4*
784-----
785
786expr5 {cmp} expr5
787
788Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
789if it evaluates to true.
790
Bram Moolenaar446cb832008-06-24 21:56:24 +0000791 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000792 *expr-<* *expr-<=* *expr-=~* *expr-!~*
793 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
794 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
795 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
796 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200797 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
798 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000799 use 'ignorecase' match case ignore case ~
800equal == ==# ==?
801not equal != !=# !=?
802greater than > ># >?
803greater than or equal >= >=# >=?
804smaller than < <# <?
805smaller than or equal <= <=# <=?
806regexp matches =~ =~# =~?
807regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200808same instance is is# is?
809different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000810
811Examples:
812"abc" ==# "Abc" evaluates to 0
813"abc" ==? "Abc" evaluates to 1
814"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
815
Bram Moolenaar13065c42005-01-08 16:08:21 +0000816 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +0100817A |List| can only be compared with a |List| and only "equal", "not equal",
818"is" and "isnot" can be used. This compares the values of the list,
819recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000820
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000821 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000822A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +0100823equal", "is" and "isnot" can be used. This compares the key/values of the
824|Dictionary| recursively. Ignoring case means case is ignored when comparing
825item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000826
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200827 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200828A |Funcref| can only be compared with a |Funcref| and only "equal", "not
829equal", "is" and "isnot" can be used. Case is never ignored. Whether
830arguments or a Dictionary are bound (with a partial) matters. The
831Dictionaries must also be equal (or the same, in case of "is") and the
832arguments must be equal (or the same).
833
834To compare Funcrefs to see if they refer to the same function, ignoring bound
835Dictionary and arguments, use |get()| to get the function name: >
836 if get(Part1, 'name') == get(Part2, 'name')
837 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000838
Bram Moolenaar251e1912011-06-19 05:09:16 +0200839When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
840expressions are referring to the same |List| or |Dictionary| instance. A copy
841of a |List| is different from the original |List|. When using "is" without
842a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
843equivalent to using "not equal". Except that a different type means the
Bram Moolenaar86edef62016-03-13 18:07:30 +0100844values are different: >
845 echo 4 == '4'
846 1
847 echo 4 is '4'
848 0
849 echo 0 is []
850 0
851"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000852
Bram Moolenaar071d4272004-06-13 20:20:40 +0000853When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +0200854and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100855 echo 0 == 'x'
856 1
857because 'x' converted to a Number is zero. However: >
858 echo [0] == ['x']
859 0
860Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861
862When comparing two Strings, this is done with strcmp() or stricmp(). This
863results in the mathematical difference (comparing byte values), not
864necessarily the alphabetical difference in the local language.
865
Bram Moolenaar446cb832008-06-24 21:56:24 +0000866When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000867'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000868
869When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000870'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
871
872'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000873
874The "=~" and "!~" operators match the lefthand argument with the righthand
875argument, which is used as a pattern. See |pattern| for what a pattern is.
876This matching is always done like 'magic' was set and 'cpoptions' is empty, no
877matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
878portable. To avoid backslashes in the regexp pattern to be doubled, use a
879single-quote string, see |literal-string|.
880Since a string is considered to be a single line, a multi-line pattern
881(containing \n, backslash-n) will not match. However, a literal NL character
882can be matched like an ordinary character. Examples:
883 "foo\nbar" =~ "\n" evaluates to 1
884 "foo\nbar" =~ "\\n" evaluates to 0
885
886
887expr5 and expr6 *expr5* *expr6*
888---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000889expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000890expr6 - expr6 .. Number subtraction *expr--*
891expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000892
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000893For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000894result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000895
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100896expr7 * expr7 .. Number multiplication *expr-star*
897expr7 / expr7 .. Number division *expr-/*
898expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000899
900For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100901For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000902
903Note the difference between "+" and ".":
904 "123" + "456" = 579
905 "123" . "456" = "123456"
906
Bram Moolenaar446cb832008-06-24 21:56:24 +0000907Since '.' has the same precedence as '+' and '-', you need to read: >
908 1 . 90 + 90.0
909As: >
910 (1 . 90) + 90.0
911That works, since the String "190" is automatically converted to the Number
912190, which can be added to the Float 90.0. However: >
913 1 . 90 * 90.0
914Should be read as: >
915 1 . (90 * 90.0)
916Since '.' has lower precedence than '*'. This does NOT work, since this
917attempts to concatenate a Float and a String.
918
919When dividing a Number by zero the result depends on the value:
920 0 / 0 = -0x80000000 (like NaN for Float)
921 >0 / 0 = 0x7fffffff (like positive infinity)
922 <0 / 0 = -0x7fffffff (like negative infinity)
923 (before Vim 7.2 it was always 0x7fffffff)
924
Bram Moolenaar22fcfad2016-07-01 18:17:26 +0200925When 64-bit Number support is enabled:
926 0 / 0 = -0x8000000000000000 (like NaN for Float)
927 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
928 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
929
Bram Moolenaar071d4272004-06-13 20:20:40 +0000930When the righthand side of '%' is zero, the result is 0.
931
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000932None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000933
Bram Moolenaar446cb832008-06-24 21:56:24 +0000934. and % do not work for Float. *E804*
935
Bram Moolenaar071d4272004-06-13 20:20:40 +0000936
937expr7 *expr7*
938-----
939! expr7 logical NOT *expr-!*
940- expr7 unary minus *expr-unary--*
941+ expr7 unary plus *expr-unary-+*
942
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200943For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000944For '-' the sign of the number is changed.
945For '+' the number is unchanged.
946
947A String will be converted to a Number first.
948
Bram Moolenaar58b85342016-08-14 19:54:54 +0200949These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000950 !-1 == 0
951 !!8 == 1
952 --9 == 9
953
954
955expr8 *expr8*
956-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000957expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +0200958 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000959If expr8 is a Number or String this results in a String that contains the
960expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200961Number. This doesn't recognize multi-byte encodings, see `byteidx()` for
Bram Moolenaar03413f42016-04-12 21:07:15 +0200962an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000963
Bram Moolenaar256972a2015-12-29 19:10:25 +0100964Index zero gives the first byte. This is like it works in C. Careful:
965text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000966cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000967 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968
969If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +0100970String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000971compatibility). Use [-1:] to get the last byte.
972
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000973If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000974for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +0200975error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000976 :let item = mylist[-1] " get last item
977
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000978Generally, if a |List| index is equal to or higher than the length of the
979|List|, or more negative than the length of the |List|, this results in an
980error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000981
Bram Moolenaard8b02732005-01-14 21:48:43 +0000982
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000983expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000984
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000985If expr8 is a Number or String this results in the substring with the bytes
986from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100987expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
988|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000989
990If expr1a is omitted zero is used. If expr1b is omitted the length of the
991string minus one is used.
992
993A negative number can be used to measure from the end of the string. -1 is
994the last character, -2 the last but one, etc.
995
996If an index goes out of range for the string characters are omitted. If
997expr1b is smaller than expr1a the result is an empty string.
998
999Examples: >
1000 :let c = name[-1:] " last byte of a string
1001 :let c = name[-2:-2] " last but one byte of a string
1002 :let s = line(".")[4:] " from the fifth byte to the end
1003 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001004<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001005 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001006If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001007the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001008just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001009 :let l = mylist[:3] " first four items
1010 :let l = mylist[4:4] " List with one item
1011 :let l = mylist[:] " shallow copy of a List
1012
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001013Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1014error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001015
Bram Moolenaarda440d22016-01-16 21:27:23 +01001016Watch out for confusion between a namespace and a variable followed by a colon
1017for a sublist: >
1018 mylist[n:] " uses variable n
1019 mylist[s:] " uses namespace s:, error!
1020
Bram Moolenaard8b02732005-01-14 21:48:43 +00001021
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001022expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001023
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001024If expr8 is a |Dictionary| and it is followed by a dot, then the following
1025name will be used as a key in the |Dictionary|. This is just like:
1026expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001027
1028The name must consist of alphanumeric characters, just like a variable name,
1029but it may start with a number. Curly braces cannot be used.
1030
1031There must not be white space before or after the dot.
1032
1033Examples: >
1034 :let dict = {"one": 1, 2: "two"}
1035 :echo dict.one
1036 :echo dict .2
1037
1038Note that the dot is also used for String concatenation. To avoid confusion
1039always put spaces around the dot for String concatenation.
1040
1041
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001042expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001043
1044When expr8 is a |Funcref| type variable, invoke the function it refers to.
1045
1046
1047
1048 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001049number
1050------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001051number number constant *expr-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001052 *hex-number* *octal-number* *binary-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001053
Bram Moolenaar7571d552016-08-18 22:54:46 +02001054Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
1055and Octal (starting with 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001056
Bram Moolenaar446cb832008-06-24 21:56:24 +00001057 *floating-point-format*
1058Floating point numbers can be written in two forms:
1059
1060 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001061 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001062
1063{N} and {M} are numbers. Both {N} and {M} must be present and can only
1064contain digits.
1065[-+] means there is an optional plus or minus sign.
1066{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001067Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001068locale is.
1069{only when compiled with the |+float| feature}
1070
1071Examples:
1072 123.456
1073 +0.0001
1074 55.0
1075 -0.123
1076 1.234e03
1077 1.0E-6
1078 -3.1416e+88
1079
1080These are INVALID:
1081 3. empty {M}
1082 1e40 missing .{M}
1083
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001084 *float-pi* *float-e*
1085A few useful values to copy&paste: >
1086 :let pi = 3.14159265359
1087 :let e = 2.71828182846
1088
Bram Moolenaar446cb832008-06-24 21:56:24 +00001089Rationale:
1090Before floating point was introduced, the text "123.456" was interpreted as
1091the two numbers "123" and "456", both converted to a string and concatenated,
1092resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001093could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001094incompatibility was accepted in favor of being able to use the normal notation
1095for floating point numbers.
1096
1097 *floating-point-precision*
1098The precision and range of floating points numbers depends on what "double"
1099means in the library Vim was compiled with. There is no way to change this at
1100runtime.
1101
1102The default for displaying a |Float| is to use 6 decimal places, like using
1103printf("%g", f). You can select something else when using the |printf()|
1104function. Example: >
1105 :echo printf('%.15e', atan(1))
1106< 7.853981633974483e-01
1107
1108
Bram Moolenaar071d4272004-06-13 20:20:40 +00001109
Bram Moolenaar979243b2015-06-26 19:35:49 +02001110string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001111------
1112"string" string constant *expr-quote*
1113
1114Note that double quotes are used.
1115
1116A string constant accepts these special characters:
1117\... three-digit octal number (e.g., "\316")
1118\.. two-digit octal number (must be followed by non-digit)
1119\. one-digit octal number (must be followed by non-digit)
1120\x.. byte specified with two hex numbers (e.g., "\x1f")
1121\x. byte specified with one hex number (must be followed by non-hex char)
1122\X.. same as \x..
1123\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001124\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001125 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001126\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001127\b backspace <BS>
1128\e escape <Esc>
1129\f formfeed <FF>
1130\n newline <NL>
1131\r return <CR>
1132\t tab <Tab>
1133\\ backslash
1134\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001135\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001136 in mappings, the 0x80 byte is escaped.
1137 To use the double quote character it must be escaped: "<M-\">".
1138 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1139 mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001140
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001141Note that "\xff" is stored as the byte 255, which may be invalid in some
1142encodings. Use "\u00ff" to store character 255 according to the current value
1143of 'encoding'.
1144
Bram Moolenaar071d4272004-06-13 20:20:40 +00001145Note that "\000" and "\x00" force the end of the string.
1146
1147
1148literal-string *literal-string* *E115*
1149---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001150'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001151
1152Note that single quotes are used.
1153
Bram Moolenaar58b85342016-08-14 19:54:54 +02001154This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001155meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001156
1157Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001158to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001159 if a =~ "\\s*"
1160 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001161
1162
1163option *expr-option* *E112* *E113*
1164------
1165&option option value, local value if possible
1166&g:option global option value
1167&l:option local option value
1168
1169Examples: >
1170 echo "tabstop is " . &tabstop
1171 if &insertmode
1172
1173Any option name can be used here. See |options|. When using the local value
1174and there is no buffer-local or window-local value, the global value is used
1175anyway.
1176
1177
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001178register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001179--------
1180@r contents of register 'r'
1181
1182The result is the contents of the named register, as a single string.
1183Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001184register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001185registers.
1186
1187When using the '=' register you get the expression itself, not what it
1188evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001189
1190
1191nesting *expr-nesting* *E110*
1192-------
1193(expr1) nested expression
1194
1195
1196environment variable *expr-env*
1197--------------------
1198$VAR environment variable
1199
1200The String value of any environment variable. When it is not defined, the
1201result is an empty string.
1202 *expr-env-expand*
1203Note that there is a difference between using $VAR directly and using
1204expand("$VAR"). Using it directly will only expand environment variables that
1205are known inside the current Vim session. Using expand() will first try using
1206the environment variables known inside the current Vim session. If that
1207fails, a shell will be used to expand the variable. This can be slow, but it
1208does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001209 :echo $shell
1210 :echo expand("$shell")
1211The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001212variable (if your shell supports it).
1213
1214
1215internal variable *expr-variable*
1216-----------------
1217variable internal variable
1218See below |internal-variables|.
1219
1220
Bram Moolenaar05159a02005-02-26 23:04:13 +00001221function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001222-------------
1223function(expr1, ...) function call
1224See below |functions|.
1225
1226
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001227lambda expression *expr-lambda* *lambda*
1228-----------------
1229{args -> expr1} lambda expression
1230
1231A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001232evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001233the following ways:
1234
12351. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1236 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020012372. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001238 :let F = {arg1, arg2 -> arg1 - arg2}
1239 :echo F(5, 2)
1240< 3
1241
1242The arguments are optional. Example: >
1243 :let F = {-> 'error function'}
1244 :echo F()
1245< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001246 *closure*
1247Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001248often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaardc1f1642016-08-16 18:33:43 +02001249while they exist in the function scope. They remain valid even after the
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001250function returns: >
1251 :function Foo(arg)
1252 : let i = 3
1253 : return {x -> x + i - a:arg}
1254 :endfunction
1255 :let Bar = Foo(4)
1256 :echo Bar(6)
1257< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001258
1259See also |:func-closure|. Lambda and closure support can be checked with: >
1260 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001261
1262Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1263 :echo map([1, 2, 3], {idx, val -> val + 1})
1264< [2, 3, 4] >
1265 :echo sort([3,7,2,1,4], {a, b -> a - b})
1266< [1, 2, 3, 4, 7]
1267
1268The lambda expression is also useful for Channel, Job and timer: >
1269 :let timer = timer_start(500,
1270 \ {-> execute("echo 'Handler called'", "")},
1271 \ {'repeat': 3})
1272< Handler called
1273 Handler called
1274 Handler called
1275
1276Note how execute() is used to execute an Ex command. That's ugly though.
1277
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001278
1279Lambda expressions have internal names like '<lambda>42'. If you get an error
1280for a lambda expression, you can find what it is with the following command: >
1281 :function {'<lambda>42'}
1282See also: |numbered-function|
1283
Bram Moolenaar071d4272004-06-13 20:20:40 +00001284==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020012853. Internal variable *internal-variables* *E461*
1286
Bram Moolenaar071d4272004-06-13 20:20:40 +00001287An internal variable name can be made up of letters, digits and '_'. But it
1288cannot start with a digit. It's also possible to use curly braces, see
1289|curly-braces-names|.
1290
1291An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001292An internal variable is explicitly destroyed with the ":unlet" command
1293|:unlet|.
1294Using a name that is not an internal variable or refers to a variable that has
1295been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001296
1297There are several name spaces for variables. Which one is to be used is
1298specified by what is prepended:
1299
1300 (nothing) In a function: local to a function; otherwise: global
1301|buffer-variable| b: Local to the current buffer.
1302|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001303|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001304|global-variable| g: Global.
1305|local-variable| l: Local to a function.
1306|script-variable| s: Local to a |:source|'ed Vim script.
1307|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001308|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001309
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001310The scope name by itself can be used as a |Dictionary|. For example, to
1311delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001312 :for k in keys(s:)
1313 : unlet s:[k]
1314 :endfor
1315<
Bram Moolenaar531da592013-05-06 05:58:55 +02001316 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001317A variable name that is preceded with "b:" is local to the current buffer.
1318Thus you can have several "b:foo" variables, one for each buffer.
1319This kind of variable is deleted when the buffer is wiped out or deleted with
1320|:bdelete|.
1321
1322One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001323 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001324b:changedtick The total number of changes to the current buffer. It is
1325 incremented for each change. An undo command is also a change
1326 in this case. This can be used to perform an action only when
1327 the buffer has changed. Example: >
1328 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001329 : let my_changedtick = b:changedtick
1330 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001331 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001332< You cannot change or delete the b:changedtick variable.
1333
Bram Moolenaar531da592013-05-06 05:58:55 +02001334 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335A variable name that is preceded with "w:" is local to the current window. It
1336is deleted when the window is closed.
1337
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001338 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001339A variable name that is preceded with "t:" is local to the current tab page,
1340It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001341without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001342
Bram Moolenaar531da592013-05-06 05:58:55 +02001343 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001344Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001345access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001346place if you like.
1347
Bram Moolenaar531da592013-05-06 05:58:55 +02001348 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001349Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001350But you can also prepend "l:" if you like. However, without prepending "l:"
1351you may run into reserved variable names. For example "count". By itself it
1352refers to "v:count". Using "l:count" you can have a local variable with the
1353same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001354
1355 *script-variable* *s:var*
1356In a Vim script variables starting with "s:" can be used. They cannot be
1357accessed from outside of the scripts, thus are local to the script.
1358
1359They can be used in:
1360- commands executed while the script is sourced
1361- functions defined in the script
1362- autocommands defined in the script
1363- functions and autocommands defined in functions and autocommands which were
1364 defined in the script (recursively)
1365- user defined commands defined in the script
1366Thus not in:
1367- other scripts sourced from this one
1368- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001369- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001370- etc.
1371
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001372Script variables can be used to avoid conflicts with global variable names.
1373Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001374
1375 let s:counter = 0
1376 function MyCounter()
1377 let s:counter = s:counter + 1
1378 echo s:counter
1379 endfunction
1380 command Tick call MyCounter()
1381
1382You can now invoke "Tick" from any script, and the "s:counter" variable in
1383that script will not be changed, only the "s:counter" in the script where
1384"Tick" was defined is used.
1385
1386Another example that does the same: >
1387
1388 let s:counter = 0
1389 command Tick let s:counter = s:counter + 1 | echo s:counter
1390
1391When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001392script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001393defined.
1394
1395The script variables are also available when a function is defined inside a
1396function that is defined in a script. Example: >
1397
1398 let s:counter = 0
1399 function StartCounting(incr)
1400 if a:incr
1401 function MyCounter()
1402 let s:counter = s:counter + 1
1403 endfunction
1404 else
1405 function MyCounter()
1406 let s:counter = s:counter - 1
1407 endfunction
1408 endif
1409 endfunction
1410
1411This defines the MyCounter() function either for counting up or counting down
1412when calling StartCounting(). It doesn't matter from where StartCounting() is
1413called, the s:counter variable will be accessible in MyCounter().
1414
1415When the same script is sourced again it will use the same script variables.
1416They will remain valid as long as Vim is running. This can be used to
1417maintain a counter: >
1418
1419 if !exists("s:counter")
1420 let s:counter = 1
1421 echo "script executed for the first time"
1422 else
1423 let s:counter = s:counter + 1
1424 echo "script executed " . s:counter . " times now"
1425 endif
1426
1427Note that this means that filetype plugins don't get a different set of script
1428variables for each buffer. Use local buffer variables instead |b:var|.
1429
1430
Bram Moolenaar531da592013-05-06 05:58:55 +02001431Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001432
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001433 *v:beval_col* *beval_col-variable*
1434v:beval_col The number of the column, over which the mouse pointer is.
1435 This is the byte index in the |v:beval_lnum| line.
1436 Only valid while evaluating the 'balloonexpr' option.
1437
1438 *v:beval_bufnr* *beval_bufnr-variable*
1439v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1440 valid while evaluating the 'balloonexpr' option.
1441
1442 *v:beval_lnum* *beval_lnum-variable*
1443v:beval_lnum The number of the line, over which the mouse pointer is. Only
1444 valid while evaluating the 'balloonexpr' option.
1445
1446 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001447v:beval_text The text under or after the mouse pointer. Usually a word as
1448 it is useful for debugging a C program. 'iskeyword' applies,
1449 but a dot and "->" before the position is included. When on a
1450 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001451 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001452 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001453 Only valid while evaluating the 'balloonexpr' option.
1454
1455 *v:beval_winnr* *beval_winnr-variable*
1456v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001457 valid while evaluating the 'balloonexpr' option. The first
1458 window has number zero (unlike most other places where a
1459 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001460
Bram Moolenaar511972d2016-06-04 18:09:59 +02001461 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001462v:beval_winid The |window-ID| of the window, over which the mouse pointer
1463 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001464
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001465 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001466v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001467 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001468 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001469
Bram Moolenaar071d4272004-06-13 20:20:40 +00001470 *v:charconvert_from* *charconvert_from-variable*
1471v:charconvert_from
1472 The name of the character encoding of a file to be converted.
1473 Only valid while evaluating the 'charconvert' option.
1474
1475 *v:charconvert_to* *charconvert_to-variable*
1476v:charconvert_to
1477 The name of the character encoding of a file after conversion.
1478 Only valid while evaluating the 'charconvert' option.
1479
1480 *v:cmdarg* *cmdarg-variable*
1481v:cmdarg This variable is used for two purposes:
1482 1. The extra arguments given to a file read/write command.
1483 Currently these are "++enc=" and "++ff=". This variable is
1484 set before an autocommand event for a file read/write
1485 command is triggered. There is a leading space to make it
1486 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001487 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001488 included here, because it will be executed anyway.
1489 2. When printing a PostScript file with ":hardcopy" this is
1490 the argument for the ":hardcopy" command. This can be used
1491 in 'printexpr'.
1492
1493 *v:cmdbang* *cmdbang-variable*
1494v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1495 was used the value is 1, otherwise it is 0. Note that this
1496 can only be used in autocommands. For user commands |<bang>|
1497 can be used.
1498
Bram Moolenaar42a45122015-07-10 17:56:23 +02001499 *v:completed_item* *completed_item-variable*
1500v:completed_item
1501 |Dictionary| containing the |complete-items| for the most
1502 recently completed word after |CompleteDone|. The
1503 |Dictionary| is empty if the completion failed.
1504
Bram Moolenaar071d4272004-06-13 20:20:40 +00001505 *v:count* *count-variable*
1506v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001507 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001508 :map _x :<C-U>echo "the count is " . v:count<CR>
1509< Note: The <C-U> is required to remove the line range that you
1510 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001511 When there are two counts, as in "3d2w", they are multiplied,
1512 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001513 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001514 "count" also works, for backwards compatibility.
1515
1516 *v:count1* *count1-variable*
1517v:count1 Just like "v:count", but defaults to one when no count is
1518 used.
1519
1520 *v:ctype* *ctype-variable*
1521v:ctype The current locale setting for characters of the runtime
1522 environment. This allows Vim scripts to be aware of the
1523 current locale encoding. Technical: it's the value of
1524 LC_CTYPE. When not using a locale the value is "C".
1525 This variable can not be set directly, use the |:language|
1526 command.
1527 See |multi-lang|.
1528
1529 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001530v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001531 one. When multiple signals are caught the number increases.
1532 Can be used in an autocommand to check if Vim didn't
1533 terminate normally. {only works on Unix}
1534 Example: >
1535 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001536< Note: if another deadly signal is caught when v:dying is one,
1537 VimLeave autocommands will not be executed.
1538
Bram Moolenaar071d4272004-06-13 20:20:40 +00001539 *v:errmsg* *errmsg-variable*
1540v:errmsg Last given error message. It's allowed to set this variable.
1541 Example: >
1542 :let v:errmsg = ""
1543 :silent! next
1544 :if v:errmsg != ""
1545 : ... handle error
1546< "errmsg" also works, for backwards compatibility.
1547
Bram Moolenaar43345542015-11-29 17:35:35 +01001548 *v:errors* *errors-variable*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001549v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001550 This is a list of strings.
1551 The assert functions append an item when an assert fails.
1552 To remove old results make it empty: >
1553 :let v:errors = []
1554< If v:errors is set to anything but a list it is made an empty
1555 list by the assert function.
1556
Bram Moolenaar071d4272004-06-13 20:20:40 +00001557 *v:exception* *exception-variable*
1558v:exception The value of the exception most recently caught and not
1559 finished. See also |v:throwpoint| and |throw-variables|.
1560 Example: >
1561 :try
1562 : throw "oops"
1563 :catch /.*/
1564 : echo "caught" v:exception
1565 :endtry
1566< Output: "caught oops".
1567
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001568 *v:false* *false-variable*
1569v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001570 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001571 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001572 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001573< v:false ~
1574 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001575 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001576
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001577 *v:fcs_reason* *fcs_reason-variable*
1578v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1579 Can be used in an autocommand to decide what to do and/or what
1580 to set v:fcs_choice to. Possible values:
1581 deleted file no longer exists
1582 conflict file contents, mode or timestamp was
1583 changed and buffer is modified
1584 changed file contents has changed
1585 mode mode of file changed
1586 time only file timestamp changed
1587
1588 *v:fcs_choice* *fcs_choice-variable*
1589v:fcs_choice What should happen after a |FileChangedShell| event was
1590 triggered. Can be used in an autocommand to tell Vim what to
1591 do with the affected buffer:
1592 reload Reload the buffer (does not work if
1593 the file was deleted).
1594 ask Ask the user what to do, as if there
1595 was no autocommand. Except that when
1596 only the timestamp changed nothing
1597 will happen.
1598 <empty> Nothing, the autocommand should do
1599 everything that needs to be done.
1600 The default is empty. If another (invalid) value is used then
1601 Vim behaves like it is empty, there is no warning message.
1602
Bram Moolenaar071d4272004-06-13 20:20:40 +00001603 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001604v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001605 option used for ~
1606 'charconvert' file to be converted
1607 'diffexpr' original file
1608 'patchexpr' original file
1609 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001610 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001611
1612 *v:fname_out* *fname_out-variable*
1613v:fname_out The name of the output file. Only valid while
1614 evaluating:
1615 option used for ~
1616 'charconvert' resulting converted file (*)
1617 'diffexpr' output of diff
1618 'patchexpr' resulting patched file
1619 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001620 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001621 for a read command (e.g., ":e file") it will be a temporary
1622 file and different from v:fname_in.
1623
1624 *v:fname_new* *fname_new-variable*
1625v:fname_new The name of the new version of the file. Only valid while
1626 evaluating 'diffexpr'.
1627
1628 *v:fname_diff* *fname_diff-variable*
1629v:fname_diff The name of the diff (patch) file. Only valid while
1630 evaluating 'patchexpr'.
1631
1632 *v:folddashes* *folddashes-variable*
1633v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1634 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001635 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001636
1637 *v:foldlevel* *foldlevel-variable*
1638v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001639 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640
1641 *v:foldend* *foldend-variable*
1642v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001643 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001644
1645 *v:foldstart* *foldstart-variable*
1646v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001647 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001648
Bram Moolenaar817a8802013-11-09 01:44:43 +01001649 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001650v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01001651 Setting it makes sense only if 'hlsearch' is enabled which
1652 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001653 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001654 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001655< Note that the value is restored when returning from a
1656 function. |function-search-undo|.
1657
Bram Moolenaar843ee412004-06-30 16:16:41 +00001658 *v:insertmode* *insertmode-variable*
1659v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1660 events. Values:
1661 i Insert mode
1662 r Replace mode
1663 v Virtual Replace mode
1664
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001665 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001666v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001667 evaluating the expression used with |map()| and |filter()|.
1668 Read-only.
1669
Bram Moolenaar071d4272004-06-13 20:20:40 +00001670 *v:lang* *lang-variable*
1671v:lang The current locale setting for messages of the runtime
1672 environment. This allows Vim scripts to be aware of the
1673 current language. Technical: it's the value of LC_MESSAGES.
1674 The value is system dependent.
1675 This variable can not be set directly, use the |:language|
1676 command.
1677 It can be different from |v:ctype| when messages are desired
1678 in a different language than what is used for character
1679 encoding. See |multi-lang|.
1680
1681 *v:lc_time* *lc_time-variable*
1682v:lc_time The current locale setting for time messages of the runtime
1683 environment. This allows Vim scripts to be aware of the
1684 current language. Technical: it's the value of LC_TIME.
1685 This variable can not be set directly, use the |:language|
1686 command. See |multi-lang|.
1687
1688 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001689v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1690 'indentexpr' expressions, tab page number for 'guitablabel'
1691 and 'guitabtooltip'. Only valid while one of these
1692 expressions is being evaluated. Read-only when in the
1693 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001694
Bram Moolenaar219b8702006-11-01 14:32:36 +00001695 *v:mouse_win* *mouse_win-variable*
1696v:mouse_win Window number for a mouse click obtained with |getchar()|.
1697 First window has number 1, like with |winnr()|. The value is
1698 zero when there was no mouse button click.
1699
Bram Moolenaar511972d2016-06-04 18:09:59 +02001700 *v:mouse_winid* *mouse_winid-variable*
1701v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1702 The value is zero when there was no mouse button click.
1703
Bram Moolenaar219b8702006-11-01 14:32:36 +00001704 *v:mouse_lnum* *mouse_lnum-variable*
1705v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1706 This is the text line number, not the screen line number. The
1707 value is zero when there was no mouse button click.
1708
1709 *v:mouse_col* *mouse_col-variable*
1710v:mouse_col Column number for a mouse click obtained with |getchar()|.
1711 This is the screen column number, like with |virtcol()|. The
1712 value is zero when there was no mouse button click.
1713
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001714 *v:none* *none-variable*
1715v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001716 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001717 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001718 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001719 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001720< v:none ~
1721 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001722 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001723
1724 *v:null* *null-variable*
1725v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001726 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001727 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001728 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001729 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001730< v:null ~
1731 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001732 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001733
Bram Moolenaard812df62008-11-09 12:46:09 +00001734 *v:oldfiles* *oldfiles-variable*
1735v:oldfiles List of file names that is loaded from the |viminfo| file on
1736 startup. These are the files that Vim remembers marks for.
1737 The length of the List is limited by the ' argument of the
1738 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001739 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001740 Also see |:oldfiles| and |c_#<|.
1741 The List can be modified, but this has no effect on what is
1742 stored in the |viminfo| file later. If you use values other
1743 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001744 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001745
Bram Moolenaar53744302015-07-17 17:38:22 +02001746 *v:option_new*
1747v:option_new New value of the option. Valid while executing an |OptionSet|
1748 autocommand.
1749 *v:option_old*
1750v:option_old Old value of the option. Valid while executing an |OptionSet|
1751 autocommand.
1752 *v:option_type*
1753v:option_type Scope of the set command. Valid while executing an
1754 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001755 *v:operator* *operator-variable*
1756v:operator The last operator given in Normal mode. This is a single
1757 character except for commands starting with <g> or <z>,
1758 in which case it is two characters. Best used alongside
1759 |v:prevcount| and |v:register|. Useful if you want to cancel
1760 Operator-pending mode and then use the operator, e.g.: >
1761 :omap O <Esc>:call MyMotion(v:operator)<CR>
1762< The value remains set until another operator is entered, thus
1763 don't expect it to be empty.
1764 v:operator is not set for |:delete|, |:yank| or other Ex
1765 commands.
1766 Read-only.
1767
Bram Moolenaar071d4272004-06-13 20:20:40 +00001768 *v:prevcount* *prevcount-variable*
1769v:prevcount The count given for the last but one Normal mode command.
1770 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001771 you want to cancel Visual or Operator-pending mode and then
1772 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1774< Read-only.
1775
Bram Moolenaar05159a02005-02-26 23:04:13 +00001776 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001777v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001778 See |profiling|.
1779
Bram Moolenaar071d4272004-06-13 20:20:40 +00001780 *v:progname* *progname-variable*
1781v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001782 invoked. Allows you to do special initialisations for |view|,
1783 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784 Read-only.
1785
Bram Moolenaara1706c92014-04-01 19:55:49 +02001786 *v:progpath* *progpath-variable*
1787v:progpath Contains the command with which Vim was invoked, including the
1788 path. Useful if you want to message a Vim server using a
1789 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001790 To get the full path use: >
1791 echo exepath(v:progpath)
Bram Moolenaar08cab962017-03-04 14:37:18 +01001792< If the path is relative it will be expanded to the full path,
1793 so that it still works after `:cd`. Thus starting "./vim"
1794 results in "/home/user/path/to/vim/src/vim".
1795 On MS-Windows the executable may be called "vim.exe", but the
1796 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001797 Read-only.
1798
Bram Moolenaar071d4272004-06-13 20:20:40 +00001799 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001800v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001801 command (regardless of whether that command actually used a
1802 register). Or for the currently executing normal mode mapping
1803 (use this in custom commands that take a register).
1804 If none is supplied it is the default register '"', unless
1805 'clipboard' contains "unnamed" or "unnamedplus", then it is
1806 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001807 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001808
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001809 *v:scrollstart* *scrollstart-variable*
1810v:scrollstart String describing the script or function that caused the
1811 screen to scroll up. It's only set when it is empty, thus the
1812 first reason is remembered. It is set to "Unknown" for a
1813 typed command.
1814 This can be used to find out why your script causes the
1815 hit-enter prompt.
1816
Bram Moolenaar071d4272004-06-13 20:20:40 +00001817 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02001818v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819 Read-only.
1820
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001821
Bram Moolenaar446cb832008-06-24 21:56:24 +00001822v:searchforward *v:searchforward* *searchforward-variable*
1823 Search direction: 1 after a forward search, 0 after a
1824 backward search. It is reset to forward when directly setting
1825 the last search pattern, see |quote/|.
1826 Note that the value is restored when returning from a
1827 function. |function-search-undo|.
1828 Read-write.
1829
Bram Moolenaar071d4272004-06-13 20:20:40 +00001830 *v:shell_error* *shell_error-variable*
1831v:shell_error Result of the last shell command. When non-zero, the last
1832 shell command had an error. When zero, there was no problem.
1833 This only works when the shell returns the error code to Vim.
1834 The value -1 is often used when the command could not be
1835 executed. Read-only.
1836 Example: >
1837 :!mv foo bar
1838 :if v:shell_error
1839 : echo 'could not rename "foo" to "bar"!'
1840 :endif
1841< "shell_error" also works, for backwards compatibility.
1842
1843 *v:statusmsg* *statusmsg-variable*
1844v:statusmsg Last given status message. It's allowed to set this variable.
1845
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001846 *v:swapname* *swapname-variable*
1847v:swapname Only valid when executing |SwapExists| autocommands: Name of
1848 the swap file found. Read-only.
1849
1850 *v:swapchoice* *swapchoice-variable*
1851v:swapchoice |SwapExists| autocommands can set this to the selected choice
1852 for handling an existing swap file:
1853 'o' Open read-only
1854 'e' Edit anyway
1855 'r' Recover
1856 'd' Delete swapfile
1857 'q' Quit
1858 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02001859 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001860 results in the user being asked, as would happen when there is
1861 no SwapExists autocommand. The default is empty.
1862
Bram Moolenaarb3480382005-12-11 21:33:32 +00001863 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001864v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001865 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02001866 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001867 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001868 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001869
Bram Moolenaard823fa92016-08-12 16:29:27 +02001870 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001871v:t_bool Value of Boolean type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001872 *v:t_channel* *t_channel-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001873v:t_channel Value of Channel type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001874 *v:t_dict* *t_dict-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001875v:t_dict Value of Dictionary type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001876 *v:t_float* *t_float-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001877v:t_float Value of Float type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001878 *v:t_func* *t_func-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001879v:t_func Value of Funcref type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001880 *v:t_job* *t_job-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001881v:t_job Value of Job type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001882 *v:t_list* *t_list-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001883v:t_list Value of List type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001884 *v:t_none* *t_none-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001885v:t_none Value of None type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001886 *v:t_number* *t_number-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001887v:t_number Value of Number type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02001888 *v:t_string* *t_string-variable*
Bram Moolenaarf562e722016-07-19 17:25:25 +02001889v:t_string Value of String type. Read-only. See: |type()|
1890
Bram Moolenaar071d4272004-06-13 20:20:40 +00001891 *v:termresponse* *termresponse-variable*
1892v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02001893 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001894 that starts with ESC [ or CSI and ends in a 'c', with only
1895 digits, ';' and '.' in between.
1896 When this option is set, the TermResponse autocommand event is
1897 fired, so that you can react to the response from the
1898 terminal.
1899 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1900 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1901 patch level (since this was introduced in patch 95, it's
1902 always 95 or bigger). Pc is always zero.
1903 {only when compiled with |+termresponse| feature}
1904
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02001905 *v:termblinkresp*
1906v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
1907 termcap entry. This is used to find out whether the terminal
1908 cursor is blinking. This is used by |term_getcursor()|.
1909
1910 *v:termstyleresp*
1911v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
1912 termcap entry. This is used to find out what the shape of the
1913 cursor is. This is used by |term_getcursor()|.
1914
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02001915 *v:termrbgresp*
1916v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02001917 termcap entry. This is used to find out what the terminal
1918 background color is, see 'background'.
1919
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02001920 *v:termrfgresp*
1921v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
1922 termcap entry. This is used to find out what the terminal
1923 foreground color is.
1924
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02001925 *v:termu7resp*
1926v:termu7resp The escape sequence returned by the terminal for the |t_u7|
1927 termcap entry. This is used to find out what the terminal
1928 does with ambiguous width characters, see 'ambiwidth'.
1929
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001930 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02001931v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001932 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001933 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001934
Bram Moolenaar071d4272004-06-13 20:20:40 +00001935 *v:this_session* *this_session-variable*
1936v:this_session Full filename of the last loaded or saved session file. See
1937 |:mksession|. It is allowed to set this variable. When no
1938 session file has been saved, this variable is empty.
1939 "this_session" also works, for backwards compatibility.
1940
1941 *v:throwpoint* *throwpoint-variable*
1942v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02001943 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001944 also |v:exception| and |throw-variables|.
1945 Example: >
1946 :try
1947 : throw "oops"
1948 :catch /.*/
1949 : echo "Exception from" v:throwpoint
1950 :endtry
1951< Output: "Exception from test.vim, line 2"
1952
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001953 *v:true* *true-variable*
1954v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001955 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001956 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001957 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001958< v:true ~
1959 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001960 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001961 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001962v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001963 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001964 |filter()|. Read-only.
1965
Bram Moolenaar071d4272004-06-13 20:20:40 +00001966 *v:version* *version-variable*
1967v:version Version number of Vim: Major version number times 100 plus
1968 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1969 is 501. Read-only. "version" also works, for backwards
1970 compatibility.
1971 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02001972 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001973< Note that patch numbers are specific to the version, thus both
1974 version 5.0 and 5.1 may have a patch 123, but these are
1975 completely different.
1976
Bram Moolenaar14735512016-03-26 21:00:08 +01001977 *v:vim_did_enter* *vim_did_enter-variable*
1978v:vim_did_enter Zero until most of startup is done. It is set to one just
1979 before |VimEnter| autocommands are triggered.
1980
Bram Moolenaar071d4272004-06-13 20:20:40 +00001981 *v:warningmsg* *warningmsg-variable*
1982v:warningmsg Last given warning message. It's allowed to set this variable.
1983
Bram Moolenaar727c8762010-10-20 19:17:48 +02001984 *v:windowid* *windowid-variable*
1985v:windowid When any X11 based GUI is running or when running in a
1986 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001987 set to the window ID.
1988 When an MS-Windows GUI is running this will be set to the
1989 window handle.
1990 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02001991 Note: for windows inside Vim use |winnr()| or |win_getid()|,
1992 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001993
Bram Moolenaar071d4272004-06-13 20:20:40 +00001994==============================================================================
19954. Builtin Functions *functions*
1996
1997See |function-list| for a list grouped by what the function is used for.
1998
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001999(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002000
2001USAGE RESULT DESCRIPTION ~
2002
Bram Moolenaar81edd172016-04-14 13:51:37 +02002003abs({expr}) Float or Number absolute value of {expr}
2004acos({expr}) Float arc cosine of {expr}
2005add({list}, {item}) List append {item} to |List| {list}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002006and({expr}, {expr}) Number bitwise AND
Bram Moolenaar81edd172016-04-14 13:51:37 +02002007append({lnum}, {string}) Number append {string} below line {lnum}
2008append({lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002009argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002010argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002011arglistid([{winnr} [, {tabnr}]]) Number argument list id
2012argv({nr}) String {nr} entry of the argument list
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002013argv() List the argument list
Bram Moolenaar42205552017-03-18 19:42:22 +01002014assert_equal({exp}, {act} [, {msg}])
2015 none assert {exp} is equal to {act}
2016assert_exception({error} [, {msg}])
2017 none assert {error} is in v:exception
2018assert_fails({cmd} [, {error}]) none assert {cmd} fails
2019assert_false({actual} [, {msg}])
2020 none assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002021assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002022 none assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002023assert_match({pat}, {text} [, {msg}])
2024 none assert {pat} matches {text}
2025assert_notequal({exp}, {act} [, {msg}])
2026 none assert {exp} is not equal {act}
2027assert_notmatch({pat}, {text} [, {msg}])
2028 none assert {pat} not matches {text}
2029assert_report({msg}) none report a test failure
2030assert_true({actual} [, {msg}]) none assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002031asin({expr}) Float arc sine of {expr}
2032atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002033atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar74240d32017-12-10 15:26:15 +01002034balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002035balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002036browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002037 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002038browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002039bufexists({expr}) Number |TRUE| if buffer {expr} exists
2040buflisted({expr}) Number |TRUE| if buffer {expr} is listed
2041bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaar81edd172016-04-14 13:51:37 +02002042bufname({expr}) String Name of the buffer {expr}
2043bufnr({expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002044bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002045bufwinnr({expr}) Number window number of buffer {expr}
2046byte2line({byte}) Number line number at byte count {byte}
2047byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2048byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2049call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002050 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002051ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002052ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002053ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002054ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002055ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002056 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002057ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002058 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002059ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2060ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002061ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002062ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2063ch_logfile({fname} [, {mode}]) none start logging channel activity
2064ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002065 Channel open a channel to {address}
2066ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002067ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002068 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002069ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002070 any send {expr} over JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002071ch_sendraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002072 any send {string} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002073ch_setoptions({handle}, {options})
2074 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002075ch_status({handle} [, {options}])
2076 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002077changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002078char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002079cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002080clearmatches() none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002081col({expr}) Number column nr of cursor or mark
2082complete({startcol}, {matches}) none set Insert mode completion
2083complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002084complete_check() Number check for key typed during completion
Bram Moolenaar81edd172016-04-14 13:51:37 +02002085confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002086 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002087copy({expr}) any make a shallow copy of {expr}
2088cos({expr}) Float cosine of {expr}
2089cosh({expr}) Float hyperbolic cosine of {expr}
2090count({list}, {expr} [, {ic} [, {start}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002091 Number count how many {expr} are in {list}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002092cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002093 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002094cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002095 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002096cursor({list}) Number move cursor to position in {list}
2097deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2098delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002099did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002100diff_filler({lnum}) Number diff filler lines about {lnum}
2101diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002102empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar81edd172016-04-14 13:51:37 +02002103escape({string}, {chars}) String escape {chars} in {string} with '\'
2104eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002105eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002106executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002107execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002108exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002109exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002110extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002111 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002112exp({expr}) Float exponential of {expr}
2113expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002114 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002115feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002116filereadable({file}) Number |TRUE| if {file} is a readable file
2117filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002118filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2119 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002120finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002121 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002122findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002123 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002124float2nr({expr}) Number convert Float {expr} to a Number
2125floor({expr}) Float round {expr} down
2126fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2127fnameescape({fname}) String escape special characters in {fname}
2128fnamemodify({fname}, {mods}) String modify file name
2129foldclosed({lnum}) Number first line of fold at {lnum} if closed
2130foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2131foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002132foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002133foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002134foreground() Number bring the Vim window to the foreground
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002135funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002136 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002137function({name} [, {arglist}] [, {dict}])
2138 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002139garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002140get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2141get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002142get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002143getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002144getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002145 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002146getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002147 any variable {varname} in buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002148getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002149getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002150getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002151getcmdline() String return the current command-line
2152getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002153getcmdtype() String return current command-line type
2154getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002155getcompletion({pat}, {type} [, {filtered}])
2156 List list of cmdline completion matches
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002157getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002158getcwd([{winnr} [, {tabnr}]]) String get the current working directory
2159getfontname([{name}]) String name of font being used
2160getfperm({fname}) String file permissions of file {fname}
2161getfsize({fname}) Number size in bytes of file {fname}
2162getftime({fname}) Number last modification time of file
2163getftype({fname}) String description of type of file {fname}
2164getline({lnum}) String line {lnum} of current buffer
2165getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002166getloclist({nr} [, {what}]) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002167getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002168getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002169getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaard823fa92016-08-12 16:29:27 +02002170getqflist([{what}]) List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002171getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002172 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002173getregtype([{regname}]) String type of register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002174gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002175gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002176 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002177gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002178 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002179getwininfo([{winid}]) List list of windows
Bram Moolenaar071d4272004-06-13 20:20:40 +00002180getwinposx() Number X coord in pixels of GUI Vim window
2181getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002182getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002183 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002184glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002185 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002186glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002187globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002188 String do glob({expr}) for all dirs in {path}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002189has({feature}) Number |TRUE| if feature {feature} supported
2190has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002191haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002192 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002193hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002194 Number |TRUE| if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002195histadd({history}, {item}) String add an item to a history
2196histdel({history} [, {item}]) String remove an item from a history
2197histget({history} [, {index}]) String get the item {index} from a history
2198histnr({history}) Number highest index of a history
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002199hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002200hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002201hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002202iconv({expr}, {from}, {to}) String convert encoding of {expr}
2203indent({lnum}) Number indent of line {lnum}
2204index({list}, {expr} [, {start} [, {ic}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002205 Number index in {list} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002206input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002207 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002208inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002209 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002210inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002211inputrestore() Number restore typeahead
2212inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002213inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar81edd172016-04-14 13:51:37 +02002214insert({list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002215invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002216isdirectory({directory}) Number |TRUE| if {directory} is a directory
2217islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002218isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002219items({dict}) List key-value pairs in {dict}
2220job_getchannel({job}) Channel get the channel handle for {job}
2221job_info({job}) Dict get information about {job}
2222job_setoptions({job}, {options}) none set options for {job}
2223job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002224 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002225job_status({job}) String get the status of {job}
2226job_stop({job} [, {how}]) Number stop {job}
2227join({list} [, {sep}]) String join {list} items into one String
2228js_decode({string}) any decode JS style JSON
2229js_encode({expr}) String encode JS style JSON
2230json_decode({string}) any decode JSON
2231json_encode({expr}) String encode JSON
2232keys({dict}) List keys in {dict}
2233len({expr}) Number the length of {expr}
2234libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002235libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002236line({expr}) Number line nr of cursor, last line or mark
2237line2byte({lnum}) Number byte count of line {lnum}
2238lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002239localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002240log({expr}) Float natural logarithm (base e) of {expr}
2241log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002242luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002243map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002244maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002245 String or Dict
2246 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002247mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002248 String check for mappings matching {name}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002249match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002250 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002251matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002252 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002253matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002254 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002255matcharg({nr}) List arguments of |:match|
2256matchdelete({id}) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002257matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002258 Number position where {pat} ends in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002259matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002260 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002261matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002262 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002263matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002264 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002265max({expr}) Number maximum value of items in {expr}
2266min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002267mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002268 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002269mode([expr]) String current editing mode
2270mzeval({expr}) any evaluate |MzScheme| expression
2271nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002272nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002273or({expr}, {expr}) Number bitwise OR
Bram Moolenaar81edd172016-04-14 13:51:37 +02002274pathshorten({expr}) String shorten directory names in a path
2275perleval({expr}) any evaluate |Perl| expression
2276pow({x}, {y}) Float {x} to the power of {y}
2277prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2278printf({fmt}, {expr1}...) String format text
Bram Moolenaar446cb832008-06-24 21:56:24 +00002279pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002280pyeval({expr}) any evaluate |Python| expression
2281py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002282pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002283range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002284 List items from {expr} to {max}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002285readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002286 List get list of lines from file {fname}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002287reltime([{start} [, {end}]]) List get time value
2288reltimefloat({time}) Float turn the time value into a Float
2289reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002290remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002291 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002292remote_foreground({server}) Number bring Vim server to the foreground
2293remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002294 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002295remote_read({serverid} [, {timeout}])
2296 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002297remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002298 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002299remote_startserver({name}) none become server {name}
2300 String send key sequence
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002301remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002302remove({dict}, {key}) any remove entry {key} from {dict}
2303rename({from}, {to}) Number rename (move) file from {from} to {to}
2304repeat({expr}, {count}) String repeat {expr} {count} times
2305resolve({filename}) String get filename a shortcut points to
2306reverse({list}) List reverse {list} in-place
2307round({expr}) Float round off {expr}
2308screenattr({row}, {col}) Number attribute at screen position
2309screenchar({row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002310screencol() Number current cursor column
2311screenrow() Number current cursor row
Bram Moolenaar81edd172016-04-14 13:51:37 +02002312search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002313 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002314searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002315 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002316searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002317 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002318searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002319 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002320searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002321 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002322server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002323 Number send reply string
2324serverlist() String get a list of available servers
Bram Moolenaar01164a62017-11-02 22:58:42 +01002325setbufline({expr}, {lnum}, {line})
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002326 Number set line {lnum} to {line} in buffer
2327 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002328setbufvar({expr}, {varname}, {val})
2329 none set {varname} in buffer {expr} to {val}
2330setcharsearch({dict}) Dict set character search from {dict}
2331setcmdpos({pos}) Number set cursor position in command-line
2332setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2333setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002334setloclist({nr}, {list} [, {action} [, {what}]])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002335 Number modify location list using {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002336setmatches({list}) Number restore a list of matches
2337setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002338setqflist({list} [, {action} [, {what}]])
Bram Moolenaard823fa92016-08-12 16:29:27 +02002339 Number modify quickfix list using {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002340setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002341settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2342settabwinvar({tabnr}, {winnr}, {varname}, {val})
2343 none set {varname} in window {winnr} in tab
2344 page {tabnr} to {val}
2345setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2346sha256({string}) String SHA256 checksum of {string}
2347shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002348 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002349 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02002350shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaar81edd172016-04-14 13:51:37 +02002351simplify({filename}) String simplify filename as much as possible
2352sin({expr}) Float sine of {expr}
2353sinh({expr}) Float hyperbolic sine of {expr}
2354sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002355 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002356soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002357spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002358spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002359 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002360split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002361 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002362sqrt({expr}) Float square root of {expr}
2363str2float({expr}) Float convert String to Float
2364str2nr({expr} [, {base}]) Number convert String to Number
2365strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002366strcharpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002367 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002368strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002369strftime({format} [, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002370strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002371stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002372 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002373string({expr}) String String representation of {expr} value
2374strlen({expr}) Number length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002375strpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002376 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002377strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002378 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002379strtrans({expr}) String translate string to make it printable
2380strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002381submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002382 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002383substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002384 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002385synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2386synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002387 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002388synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002389synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002390synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2391system({expr} [, {input}]) String output of shell command/filter {expr}
2392systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002393tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002394tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002395tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
2396taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002397tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002398tan({expr}) Float tangent of {expr}
2399tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002400tempname() String name for a temporary file
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002401term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaar45356542017-08-06 17:53:31 +02002402term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002403term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002404term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002405term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002406term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002407term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002408term_getstatus({buf}) String get the status of a terminal
2409term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002410term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002411term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002412term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002413term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
2414term_start({cmd}, {options}) Job open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002415term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002416test_alloc_fail({id}, {countdown}, {repeat})
2417 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02002418test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar5e80de32017-09-03 15:48:12 +02002419test_feedinput() none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02002420test_garbagecollect_now() none free memory right now for testing
Bram Moolenaare0c31f62017-03-01 15:07:05 +01002421test_ignore_error({expr}) none ignore a specific error
Bram Moolenaar574860b2016-05-24 17:33:34 +02002422test_null_channel() Channel null value for testing
2423test_null_dict() Dict null value for testing
2424test_null_job() Job null value for testing
2425test_null_list() List null value for testing
2426test_null_partial() Funcref null value for testing
2427test_null_string() String null value for testing
Bram Moolenaareb992cb2017-03-09 18:20:16 +01002428test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002429test_settime({expr}) none set current time for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02002430timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002431timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002432timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002433 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002434timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002435timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002436tolower({expr}) String the String {expr} switched to lowercase
2437toupper({expr}) String the String {expr} switched to uppercase
2438tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002439 to chars in {tostr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002440trunc({expr}) Float truncate Float {expr}
2441type({name}) Number type of variable {name}
2442undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002443undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002444uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002445 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002446values({dict}) List values in {dict}
2447virtcol({expr}) Number screen column of cursor or mark
2448visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002449wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar81edd172016-04-14 13:51:37 +02002450win_findbuf({bufnr}) List find windows containing {bufnr}
2451win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2452win_gotoid({expr}) Number go to window with ID {expr}
2453win_id2tabwin({expr}) List get tab and window nr from window ID
2454win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01002455win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002456winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002457wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002458winheight({nr}) Number height of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002459winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002460winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002461winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002462winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002463winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002464winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002465wordcount() Dict get byte/char/word statistics
Bram Moolenaar81edd172016-04-14 13:51:37 +02002466writefile({list}, {fname} [, {flags}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002467 Number write list of lines to file {fname}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002468xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002469
Bram Moolenaar03413f42016-04-12 21:07:15 +02002470
Bram Moolenaar446cb832008-06-24 21:56:24 +00002471abs({expr}) *abs()*
2472 Return the absolute value of {expr}. When {expr} evaluates to
2473 a |Float| abs() returns a |Float|. When {expr} can be
2474 converted to a |Number| abs() returns a |Number|. Otherwise
2475 abs() gives an error message and returns -1.
2476 Examples: >
2477 echo abs(1.456)
2478< 1.456 >
2479 echo abs(-5.456)
2480< 5.456 >
2481 echo abs(-4)
2482< 4
2483 {only available when compiled with the |+float| feature}
2484
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002485
2486acos({expr}) *acos()*
2487 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002488 |Float| in the range of [0, pi].
2489 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002490 [-1, 1].
2491 Examples: >
2492 :echo acos(0)
2493< 1.570796 >
2494 :echo acos(-0.5)
2495< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002496 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002497
2498
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002499add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002500 Append the item {expr} to |List| {list}. Returns the
2501 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002502 :let alist = add([1, 2, 3], item)
2503 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002504< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002505 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002506 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002507
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002508
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002509and({expr}, {expr}) *and()*
2510 Bitwise AND on the two arguments. The arguments are converted
2511 to a number. A List, Dict or Float argument causes an error.
2512 Example: >
2513 :let flag = and(bits, 0x80)
2514
2515
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002516append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002517 When {expr} is a |List|: Append each item of the |List| as a
2518 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002519 Otherwise append {expr} as one text line below line {lnum} in
2520 the current buffer.
2521 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002522 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02002523 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002524 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002525 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002526<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002527 *argc()*
2528argc() The result is the number of files in the argument list of the
2529 current window. See |arglist|.
2530
2531 *argidx()*
2532argidx() The result is the current index in the argument list. 0 is
2533 the first file. argc() - 1 is the last one. See |arglist|.
2534
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002535 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002536arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002537 Return the argument list ID. This is a number which
2538 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002539 global argument list. See |arglist|.
2540 Return -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002541
2542 Without arguments use the current window.
2543 With {winnr} only use this window in the current tab page.
2544 With {winnr} and {tabnr} use the window in the specified tab
2545 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002546 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002547
Bram Moolenaar071d4272004-06-13 20:20:40 +00002548 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002549argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002550 current window. See |arglist|. "argv(0)" is the first one.
2551 Example: >
2552 :let i = 0
2553 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002554 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002555 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2556 : let i = i + 1
2557 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002558< Without the {nr} argument a |List| with the whole |arglist| is
2559 returned.
2560
Bram Moolenaar683fa182015-11-30 21:38:24 +01002561 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002562assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002563 When {expected} and {actual} are not equal an error message is
2564 added to |v:errors|.
2565 There is no automatic conversion, the String "4" is different
2566 from the Number 4. And the number 4 is different from the
2567 Float 4.0. The value of 'ignorecase' is not used here, case
2568 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002569 When {msg} is omitted an error in the form "Expected
2570 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002571 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002572 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002573< Will result in a string to be added to |v:errors|:
2574 test.vim line 12: Expected 'foo' but got 'bar' ~
2575
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002576assert_exception({error} [, {msg}]) *assert_exception()*
2577 When v:exception does not contain the string {error} an error
2578 message is added to |v:errors|.
2579 This can be used to assert that a command throws an exception.
2580 Using the error number, followed by a colon, avoids problems
2581 with translations: >
2582 try
2583 commandthatfails
2584 call assert_false(1, 'command should have failed')
2585 catch
2586 call assert_exception('E492:')
2587 endtry
2588
Bram Moolenaara260b872016-01-15 20:48:22 +01002589assert_fails({cmd} [, {error}]) *assert_fails()*
2590 Run {cmd} and add an error message to |v:errors| if it does
2591 NOT produce an error.
Bram Moolenaar25de4c22016-11-06 14:48:06 +01002592 When {error} is given it must match in |v:errmsg|.
Bram Moolenaara260b872016-01-15 20:48:22 +01002593
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002594assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002595 When {actual} is not false an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002596 |v:errors|, like with |assert_equal()|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002597 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002598 number the assert fails.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002599 When {msg} is omitted an error in the form
2600 "Expected False but got {actual}" is produced.
2601
2602assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()*
2603 This asserts number values. When {actual} is lower than
2604 {lower} or higher than {upper} an error message is added to
2605 |v:errors|.
2606 When {msg} is omitted an error in the form
2607 "Expected range {lower} - {upper}, but got {actual}" is
2608 produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002609
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002610 *assert_match()*
2611assert_match({pattern}, {actual} [, {msg}])
2612 When {pattern} does not match {actual} an error message is
2613 added to |v:errors|.
2614
2615 {pattern} is used as with |=~|: The matching is always done
2616 like 'magic' was set and 'cpoptions' is empty, no matter what
2617 the actual value of 'magic' or 'cpoptions' is.
2618
2619 {actual} is used as a string, automatic conversion applies.
2620 Use "^" and "$" to match with the start and end of the text.
2621 Use both to match the whole text.
2622
Bram Moolenaar61c04492016-07-23 15:35:35 +02002623 When {msg} is omitted an error in the form
2624 "Pattern {pattern} does not match {actual}" is produced.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002625 Example: >
2626 assert_match('^f.*o$', 'foobar')
2627< Will result in a string to be added to |v:errors|:
2628 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2629
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002630 *assert_notequal()*
2631assert_notequal({expected}, {actual} [, {msg}])
2632 The opposite of `assert_equal()`: add an error message to
2633 |v:errors| when {expected} and {actual} are equal.
2634
2635 *assert_notmatch()*
2636assert_notmatch({pattern}, {actual} [, {msg}])
2637 The opposite of `assert_match()`: add an error message to
2638 |v:errors| when {pattern} matches {actual}.
2639
Bram Moolenaar42205552017-03-18 19:42:22 +01002640assert_report({msg}) *assert_report()*
2641 Report a test failure directly, using {msg}.
2642
2643assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002644 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002645 |v:errors|, like with |assert_equal()|.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002646 A value is TRUE when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002647 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002648 When {msg} is omitted an error in the form "Expected True but
2649 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002650
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002651asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002652 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002653 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002654 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002655 [-1, 1].
2656 Examples: >
2657 :echo asin(0.8)
2658< 0.927295 >
2659 :echo asin(-0.5)
2660< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002661 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002662
2663
Bram Moolenaar446cb832008-06-24 21:56:24 +00002664atan({expr}) *atan()*
2665 Return the principal value of the arc tangent of {expr}, in
2666 the range [-pi/2, +pi/2] radians, as a |Float|.
2667 {expr} must evaluate to a |Float| or a |Number|.
2668 Examples: >
2669 :echo atan(100)
2670< 1.560797 >
2671 :echo atan(-4.01)
2672< -1.326405
2673 {only available when compiled with the |+float| feature}
2674
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002675
2676atan2({expr1}, {expr2}) *atan2()*
2677 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002678 radians, as a |Float| in the range [-pi, pi].
2679 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002680 Examples: >
2681 :echo atan2(-1, 1)
2682< -0.785398 >
2683 :echo atan2(1, -1)
2684< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002685 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002686
Bram Moolenaar246fe032017-11-19 19:56:27 +01002687balloon_show({expr}) *balloon_show()*
2688 Show {expr} inside the balloon. For the GUI {expr} is used as
2689 a string. For a terminal {expr} can be a list, which contains
2690 the lines of the balloon. If {expr} is not a list it will be
2691 split with |balloon_split()|.
2692
Bram Moolenaar214641f2017-03-05 17:04:09 +01002693 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01002694 func GetBalloonContent()
2695 " initiate getting the content
2696 return ''
2697 endfunc
2698 set balloonexpr=GetBalloonContent()
2699
2700 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01002701 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01002702 endfunc
2703<
2704 The intended use is that fetching the content of the balloon
2705 is initiated from 'balloonexpr'. It will invoke an
2706 asynchronous method, in which a callback invokes
2707 balloon_show(). The 'balloonexpr' itself can return an
2708 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01002709
2710 When showing a balloon is not possible nothing happens, no
2711 error message.
Bram Moolenaar669a8282017-11-19 20:13:05 +01002712 {only available when compiled with the +balloon_eval or
2713 +balloon_eval_term feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002714
Bram Moolenaar246fe032017-11-19 19:56:27 +01002715balloon_split({msg}) *balloon_split()*
2716 Split {msg} into lines to be displayed in a balloon. The
2717 splits are made for the current window size and optimize to
2718 show debugger output.
2719 Returns a |List| with the split lines.
Bram Moolenaar669a8282017-11-19 20:13:05 +01002720 {only available when compiled with the +balloon_eval_term
2721 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01002722
Bram Moolenaar071d4272004-06-13 20:20:40 +00002723 *browse()*
2724browse({save}, {title}, {initdir}, {default})
2725 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002726 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00002727 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002728 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00002729 {title} title for the requester
2730 {initdir} directory to start browsing in
2731 {default} default file name
2732 When the "Cancel" button is hit, something went wrong, or
2733 browsing is not possible, an empty string is returned.
2734
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002735 *browsedir()*
2736browsedir({title}, {initdir})
2737 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002738 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002739 On systems where a directory browser is not supported a file
2740 browser is used. In that case: select a file in the directory
2741 to be used.
2742 The input fields are:
2743 {title} title for the requester
2744 {initdir} directory to start browsing in
2745 When the "Cancel" button is hit, something went wrong, or
2746 browsing is not possible, an empty string is returned.
2747
Bram Moolenaar071d4272004-06-13 20:20:40 +00002748bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002749 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00002750 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002751 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01002752 Number zero is the alternate buffer for the current window.
2753
Bram Moolenaar071d4272004-06-13 20:20:40 +00002754 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002755 exactly. The name can be:
2756 - Relative to the current directory.
2757 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002758 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002759 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002760 Unlisted buffers will be found.
2761 Note that help files are listed by their short name in the
2762 output of |:buffers|, but bufexists() requires using their
2763 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002764 bufexists() may report a buffer exists, but to use the name
2765 with a |:buffer| command you may need to use |expand()|. Esp
2766 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002767 Use "bufexists(0)" to test for the existence of an alternate
2768 file name.
2769 *buffer_exists()*
2770 Obsolete name: buffer_exists().
2771
2772buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002773 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00002774 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002775 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002776
2777bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002778 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00002779 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002780 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002781
2782bufname({expr}) *bufname()*
2783 The result is the name of a buffer, as it is displayed by the
2784 ":ls" command.
2785 If {expr} is a Number, that buffer number's name is given.
2786 Number zero is the alternate buffer for the current window.
2787 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02002788 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002789 set and 'cpoptions' is empty. When there is more than one
2790 match an empty string is returned.
2791 "" or "%" can be used for the current buffer, "#" for the
2792 alternate buffer.
2793 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002794 or middle of the buffer name is accepted. If you only want a
2795 full match then put "^" at the start and "$" at the end of the
2796 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002797 Listed buffers are found first. If there is a single match
2798 with a listed buffer, that one is returned. Next unlisted
2799 buffers are searched for.
2800 If the {expr} is a String, but you want to use it as a buffer
2801 number, force it to be a Number by adding zero to it: >
2802 :echo bufname("3" + 0)
2803< If the buffer doesn't exist, or doesn't have a name, an empty
2804 string is returned. >
2805 bufname("#") alternate buffer name
2806 bufname(3) name of buffer 3
2807 bufname("%") name of current buffer
2808 bufname("file2") name of buffer where "file2" matches.
2809< *buffer_name()*
2810 Obsolete name: buffer_name().
2811
2812 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002813bufnr({expr} [, {create}])
2814 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002815 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002816 above.
2817 If the buffer doesn't exist, -1 is returned. Or, if the
2818 {create} argument is present and not zero, a new, unlisted,
2819 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002820 bufnr("$") is the last buffer: >
2821 :let last_buffer = bufnr("$")
2822< The result is a Number, which is the highest buffer number
2823 of existing buffers. Note that not all buffers with a smaller
2824 number necessarily exist, because ":bwipeout" may have removed
2825 them. Use bufexists() to test for the existence of a buffer.
2826 *buffer_number()*
2827 Obsolete name: buffer_number().
2828 *last_buffer_nr()*
2829 Obsolete name for bufnr("$"): last_buffer_nr().
2830
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002831bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02002832 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002833 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02002834 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002835 there is no such window, -1 is returned. Example: >
2836
2837 echo "A window containing buffer 1 is " . (bufwinid(1))
2838<
2839 Only deals with the current tab page.
2840
Bram Moolenaar071d4272004-06-13 20:20:40 +00002841bufwinnr({expr}) *bufwinnr()*
2842 The result is a Number, which is the number of the first
2843 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02002844 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002845 there is no such window, -1 is returned. Example: >
2846
2847 echo "A window containing buffer 1 is " . (bufwinnr(1))
2848
2849< The number can be used with |CTRL-W_w| and ":wincmd w"
2850 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002851 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002852
Bram Moolenaar071d4272004-06-13 20:20:40 +00002853byte2line({byte}) *byte2line()*
2854 Return the line number that contains the character at byte
2855 count {byte} in the current buffer. This includes the
2856 end-of-line character, depending on the 'fileformat' option
2857 for the current buffer. The first character has byte count
2858 one.
2859 Also see |line2byte()|, |go| and |:goto|.
2860 {not available when compiled without the |+byte_offset|
2861 feature}
2862
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002863byteidx({expr}, {nr}) *byteidx()*
2864 Return byte index of the {nr}'th character in the string
2865 {expr}. Use zero for the first character, it returns zero.
2866 This function is only useful when there are multibyte
2867 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002868 Composing characters are not counted separately, their byte
2869 length is added to the preceding base character. See
2870 |byteidxcomp()| below for counting composing characters
2871 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002872 Example : >
2873 echo matchstr(str, ".", byteidx(str, 3))
2874< will display the fourth character. Another way to do the
2875 same: >
2876 let s = strpart(str, byteidx(str, 3))
2877 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002878< Also see |strgetchar()| and |strcharpart()|.
2879
2880 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002881 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002882 in bytes is returned.
2883
2884byteidxcomp({expr}, {nr}) *byteidxcomp()*
2885 Like byteidx(), except that a composing character is counted
2886 as a separate character. Example: >
2887 let s = 'e' . nr2char(0x301)
2888 echo byteidx(s, 1)
2889 echo byteidxcomp(s, 1)
2890 echo byteidxcomp(s, 2)
2891< The first and third echo result in 3 ('e' plus composing
2892 character is 3 bytes), the second echo results in 1 ('e' is
2893 one byte).
2894 Only works different from byteidx() when 'encoding' is set to
2895 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002896
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002897call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002898 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002899 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002900 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002901 a:firstline and a:lastline are set to the cursor line.
2902 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002903 {dict} is for functions with the "dict" attribute. It will be
2904 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002905
Bram Moolenaar446cb832008-06-24 21:56:24 +00002906ceil({expr}) *ceil()*
2907 Return the smallest integral value greater than or equal to
2908 {expr} as a |Float| (round up).
2909 {expr} must evaluate to a |Float| or a |Number|.
2910 Examples: >
2911 echo ceil(1.456)
2912< 2.0 >
2913 echo ceil(-5.456)
2914< -5.0 >
2915 echo ceil(4.0)
2916< 4.0
2917 {only available when compiled with the |+float| feature}
2918
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002919ch_canread({handle}) *ch_canread()*
2920 Return non-zero when there is something to read from {handle}.
2921 {handle} can be a Channel or a Job that has a Channel.
2922
2923 This is useful to read from a channel at a convenient time,
2924 e.g. from a timer.
2925
2926 Note that messages are dropped when the channel does not have
2927 a callback. Add a close callback to avoid that.
2928
2929 {only available when compiled with the |+channel| feature}
2930
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002931ch_close({handle}) *ch_close()*
2932 Close {handle}. See |channel-close|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002933 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02002934 A close callback is not invoked.
2935
2936 {only available when compiled with the |+channel| feature}
2937
2938ch_close_in({handle}) *ch_close_in()*
2939 Close the "in" part of {handle}. See |channel-close-in|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002940 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02002941 A close callback is not invoked.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002942
Bram Moolenaar835dc632016-02-07 14:27:38 +01002943 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002944
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002945ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
2946 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002947 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01002948 with a raw channel. See |channel-use|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002949 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002950 *E917*
2951 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002952 entry. It can have a "timeout" entry to specify the timeout
2953 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002954
2955 ch_evalexpr() waits for a response and returns the decoded
2956 expression. When there is an error or timeout it returns an
2957 empty string.
2958
2959 {only available when compiled with the |+channel| feature}
2960
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002961ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
2962 Send {string} over {handle}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002963 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002964
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002965 Works like |ch_evalexpr()|, but does not encode the request or
2966 decode the response. The caller is responsible for the
2967 correct contents. Also does not add a newline for a channel
2968 in NL mode, the caller must do that. The NL in the response
2969 is removed.
Bram Moolenaar01164a62017-11-02 22:58:42 +01002970 Note that Vim does not know when the text received on a raw
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002971 channel is complete, it may only return the first part and you
Bram Moolenaar01164a62017-11-02 22:58:42 +01002972 need to use ch_readraw() to fetch the rest.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002973 See |channel-use|.
2974
2975 {only available when compiled with the |+channel| feature}
2976
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002977ch_getbufnr({handle}, {what}) *ch_getbufnr()*
2978 Get the buffer number that {handle} is using for {what}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002979 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01002980 {what} can be "err" for stderr, "out" for stdout or empty for
2981 socket output.
2982 Returns -1 when there is no buffer.
2983 {only available when compiled with the |+channel| feature}
2984
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002985ch_getjob({channel}) *ch_getjob()*
2986 Get the Job associated with {channel}.
2987 If there is no job calling |job_status()| on the returned Job
2988 will result in "fail".
2989
2990 {only available when compiled with the |+channel| and
2991 |+job| features}
2992
Bram Moolenaar03602ec2016-03-20 20:57:45 +01002993ch_info({handle}) *ch_info()*
2994 Returns a Dictionary with information about {handle}. The
2995 items are:
2996 "id" number of the channel
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002997 "status" "open", "buffered" or "closed", like
2998 ch_status()
Bram Moolenaar03602ec2016-03-20 20:57:45 +01002999 When opened with ch_open():
3000 "hostname" the hostname of the address
3001 "port" the port of the address
3002 "sock_status" "open" or "closed"
3003 "sock_mode" "NL", "RAW", "JSON" or "JS"
3004 "sock_io" "socket"
3005 "sock_timeout" timeout in msec
3006 When opened with job_start():
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003007 "out_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003008 "out_mode" "NL", "RAW", "JSON" or "JS"
3009 "out_io" "null", "pipe", "file" or "buffer"
3010 "out_timeout" timeout in msec
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003011 "err_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003012 "err_mode" "NL", "RAW", "JSON" or "JS"
3013 "err_io" "out", "null", "pipe", "file" or "buffer"
3014 "err_timeout" timeout in msec
3015 "in_status" "open" or "closed"
3016 "in_mode" "NL", "RAW", "JSON" or "JS"
3017 "in_io" "null", "pipe", "file" or "buffer"
3018 "in_timeout" timeout in msec
3019
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003020ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003021 Write {msg} in the channel log file, if it was opened with
3022 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003023 When {handle} is passed the channel number is used for the
3024 message.
Bram Moolenaar51628222016-12-01 23:03:28 +01003025 {handle} can be a Channel or a Job that has a Channel. The
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02003026 Channel must be open for the channel number to be used.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003027
3028ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003029 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003030 When {fname} is an empty string: stop logging.
3031
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003032 When {mode} is omitted or "a" append to the file.
3033 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003034
3035 The file is flushed after every message, on Unix you can use
3036 "tail -f" to see what is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003037
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003038 This function is not available in the |sandbox|.
3039 NOTE: the channel communication is stored in the file, be
3040 aware that this may contain confidential and privacy sensitive
3041 information, e.g. a password you type in a terminal window.
3042
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003043
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003044ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003045 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003046 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003047
3048 {address} has the form "hostname:port", e.g.,
3049 "localhost:8765".
3050
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003051 If {options} is given it must be a |Dictionary|.
3052 See |channel-open-options|.
3053
Bram Moolenaar835dc632016-02-07 14:27:38 +01003054 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003055
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003056ch_read({handle} [, {options}]) *ch_read()*
3057 Read from {handle} and return the received message.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003058 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar74240d32017-12-10 15:26:15 +01003059 For a NL channel this waits for a NL to arrive, except when
3060 there is nothing more to read (channel was closed).
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003061 See |channel-more|.
3062 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003063
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003064ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003065 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar74240d32017-12-10 15:26:15 +01003066 the message. For a NL channel it does not block waiting for
3067 the NL to arrive, but otherwise works like ch_read().
3068 See |channel-more|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003069 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003070
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003071ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
3072 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003073 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003074 with a raw channel.
3075 See |channel-use|. *E912*
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003076 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003077
Bram Moolenaar835dc632016-02-07 14:27:38 +01003078 {only available when compiled with the |+channel| feature}
3079
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003080ch_sendraw({handle}, {string} [, {options}]) *ch_sendraw()*
3081 Send {string} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003082 Works like |ch_sendexpr()|, but does not encode the request or
3083 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01003084 correct contents. Also does not add a newline for a channel
3085 in NL mode, the caller must do that. The NL in the response
3086 is removed.
3087 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003088
Bram Moolenaar835dc632016-02-07 14:27:38 +01003089 {only available when compiled with the |+channel| feature}
3090
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003091ch_setoptions({handle}, {options}) *ch_setoptions()*
3092 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003093 "callback" the channel callback
3094 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003095 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003096 See |ch_open()| for more explanation.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003097 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003098
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003099 Note that changing the mode may cause queued messages to be
3100 lost.
3101
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003102 These options cannot be changed:
Bram Moolenaar7571d552016-08-18 22:54:46 +02003103 "waittime" only applies to |ch_open()|
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003104
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003105ch_status({handle} [, {options}]) *ch_status()*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003106 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01003107 "fail" failed to open the channel
3108 "open" channel can be used
Bram Moolenaar06481422016-04-30 15:13:38 +02003109 "buffered" channel can be read, not written to
Bram Moolenaar38a55632016-02-15 22:07:32 +01003110 "closed" channel can not be used
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003111 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar06481422016-04-30 15:13:38 +02003112 "buffered" is used when the channel was closed but there is
3113 still data that can be obtained with |ch_read()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003114
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003115 If {options} is given it can contain a "part" entry to specify
3116 the part of the channel to return the status for: "out" or
3117 "err". For example, to get the error status: >
3118 ch_status(job, {"part": "err"})
3119<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003120changenr() *changenr()*
3121 Return the number of the most recent change. This is the same
3122 number as what is displayed with |:undolist| and can be used
3123 with the |:undo| command.
3124 When a change was made it is the number of that change. After
3125 redo it is the number of the redone change. After undo it is
3126 one less than the number of the undone change.
3127
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003128char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003129 Return number value of the first char in {expr}. Examples: >
3130 char2nr(" ") returns 32
3131 char2nr("ABC") returns 65
3132< When {utf8} is omitted or zero, the current 'encoding' is used.
3133 Example for "utf-8": >
3134 char2nr("á") returns 225
3135 char2nr("á"[0]) returns 195
3136< With {utf8} set to 1, always treat as utf-8 characters.
3137 A combining character is a separate character.
3138 |nr2char()| does the opposite.
3139
3140cindent({lnum}) *cindent()*
3141 Get the amount of indent for line {lnum} according the C
3142 indenting rules, as with 'cindent'.
3143 The indent is counted in spaces, the value of 'tabstop' is
3144 relevant. {lnum} is used just like in |getline()|.
3145 When {lnum} is invalid or Vim was not compiled the |+cindent|
3146 feature, -1 is returned.
3147 See |C-indenting|.
3148
3149clearmatches() *clearmatches()*
3150 Clears all matches previously defined by |matchadd()| and the
3151 |:match| commands.
3152
3153 *col()*
3154col({expr}) The result is a Number, which is the byte index of the column
3155 position given with {expr}. The accepted positions are:
3156 . the cursor position
3157 $ the end of the cursor line (the result is the
3158 number of bytes in the cursor line plus one)
3159 'x position of mark x (if the mark is not set, 0 is
3160 returned)
3161 v In Visual mode: the start of the Visual area (the
3162 cursor is the end). When not in Visual mode
3163 returns the cursor position. Differs from |'<| in
3164 that it's updated right away.
3165 Additionally {expr} can be [lnum, col]: a |List| with the line
3166 and column number. Most useful when the column is "$", to get
3167 the last column of a specific line. When "lnum" or "col" is
3168 out of range then col() returns zero.
3169 To get the line number use |line()|. To get both use
3170 |getpos()|.
3171 For the screen column position use |virtcol()|.
3172 Note that only marks in the current file can be used.
3173 Examples: >
3174 col(".") column of cursor
3175 col("$") length of cursor line plus one
3176 col("'t") column of mark t
3177 col("'" . markname) column of mark markname
3178< The first column is 1. 0 is returned for an error.
3179 For an uppercase mark the column may actually be in another
3180 buffer.
3181 For the cursor position, when 'virtualedit' is active, the
3182 column is one higher if the cursor is after the end of the
3183 line. This can be used to obtain the column in Insert mode: >
3184 :imap <F2> <C-O>:let save_ve = &ve<CR>
3185 \<C-O>:set ve=all<CR>
3186 \<C-O>:echo col(".") . "\n" <Bar>
3187 \let &ve = save_ve<CR>
3188<
3189
3190complete({startcol}, {matches}) *complete()* *E785*
3191 Set the matches for Insert mode completion.
3192 Can only be used in Insert mode. You need to use a mapping
3193 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3194 or with an expression mapping.
3195 {startcol} is the byte offset in the line where the completed
3196 text start. The text up to the cursor is the original text
3197 that will be replaced by the matches. Use col('.') for an
3198 empty string. "col('.') - 1" will replace one character by a
3199 match.
3200 {matches} must be a |List|. Each |List| item is one match.
3201 See |complete-items| for the kind of items that are possible.
3202 Note that the after calling this function you need to avoid
3203 inserting anything that would cause completion to stop.
3204 The match can be selected with CTRL-N and CTRL-P as usual with
3205 Insert mode completion. The popup menu will appear if
3206 specified, see |ins-completion-menu|.
3207 Example: >
3208 inoremap <F5> <C-R>=ListMonths()<CR>
3209
3210 func! ListMonths()
3211 call complete(col('.'), ['January', 'February', 'March',
3212 \ 'April', 'May', 'June', 'July', 'August', 'September',
3213 \ 'October', 'November', 'December'])
3214 return ''
3215 endfunc
3216< This isn't very useful, but it shows how it works. Note that
3217 an empty string is returned to avoid a zero being inserted.
3218
3219complete_add({expr}) *complete_add()*
3220 Add {expr} to the list of matches. Only to be used by the
3221 function specified with the 'completefunc' option.
3222 Returns 0 for failure (empty string or out of memory),
3223 1 when the match was added, 2 when the match was already in
3224 the list.
3225 See |complete-functions| for an explanation of {expr}. It is
3226 the same as one item in the list that 'omnifunc' would return.
3227
3228complete_check() *complete_check()*
3229 Check for a key typed while looking for completion matches.
3230 This is to be used when looking for matches takes some time.
3231 Returns |TRUE| when searching for matches is to be aborted,
3232 zero otherwise.
3233 Only to be used by the function specified with the
3234 'completefunc' option.
3235
3236 *confirm()*
3237confirm({msg} [, {choices} [, {default} [, {type}]]])
3238 Confirm() offers the user a dialog, from which a choice can be
3239 made. It returns the number of the choice. For the first
3240 choice this is 1.
3241 Note: confirm() is only supported when compiled with dialog
3242 support, see |+dialog_con| and |+dialog_gui|.
3243
3244 {msg} is displayed in a |dialog| with {choices} as the
3245 alternatives. When {choices} is missing or empty, "&OK" is
3246 used (and translated).
3247 {msg} is a String, use '\n' to include a newline. Only on
3248 some systems the string is wrapped when it doesn't fit.
3249
3250 {choices} is a String, with the individual choices separated
3251 by '\n', e.g. >
3252 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3253< The letter after the '&' is the shortcut key for that choice.
3254 Thus you can type 'c' to select "Cancel". The shortcut does
3255 not need to be the first letter: >
3256 confirm("file has been modified", "&Save\nSave &All")
3257< For the console, the first letter of each choice is used as
3258 the default shortcut key.
3259
3260 The optional {default} argument is the number of the choice
3261 that is made if the user hits <CR>. Use 1 to make the first
3262 choice the default one. Use 0 to not set a default. If
3263 {default} is omitted, 1 is used.
3264
3265 The optional {type} argument gives the type of dialog. This
3266 is only used for the icon of the GTK, Mac, Motif and Win32
3267 GUI. It can be one of these values: "Error", "Question",
3268 "Info", "Warning" or "Generic". Only the first character is
3269 relevant. When {type} is omitted, "Generic" is used.
3270
3271 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3272 or another valid interrupt key, confirm() returns 0.
3273
3274 An example: >
3275 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3276 :if choice == 0
3277 : echo "make up your mind!"
3278 :elseif choice == 3
3279 : echo "tasteful"
3280 :else
3281 : echo "I prefer bananas myself."
3282 :endif
3283< In a GUI dialog, buttons are used. The layout of the buttons
3284 depends on the 'v' flag in 'guioptions'. If it is included,
3285 the buttons are always put vertically. Otherwise, confirm()
3286 tries to put the buttons in one horizontal line. If they
3287 don't fit, a vertical layout is used anyway. For some systems
3288 the horizontal layout is always used.
3289
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003290 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003291copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003292 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003293 When {expr} is a |List| a shallow copy is created. This means
3294 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003295 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003296 changing an item changes the contents of both |Lists|.
3297 A |Dictionary| is copied in a similar way as a |List|.
3298 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003299
Bram Moolenaar446cb832008-06-24 21:56:24 +00003300cos({expr}) *cos()*
3301 Return the cosine of {expr}, measured in radians, as a |Float|.
3302 {expr} must evaluate to a |Float| or a |Number|.
3303 Examples: >
3304 :echo cos(100)
3305< 0.862319 >
3306 :echo cos(-4.01)
3307< -0.646043
3308 {only available when compiled with the |+float| feature}
3309
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003310
3311cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003312 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003313 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003314 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003315 Examples: >
3316 :echo cosh(0.5)
3317< 1.127626 >
3318 :echo cosh(-0.5)
3319< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02003320 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003321
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003322
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003323count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003324 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003325 in |String|, |List| or |Dictionary| {comp}.
3326
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003327 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003328 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003329
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003330 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003331
Bram Moolenaar9966b212017-07-28 16:46:57 +02003332 When {comp} is a string then the number of not overlapping
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003333 occurrences of {expr} is returned.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003334
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003335
Bram Moolenaar071d4272004-06-13 20:20:40 +00003336 *cscope_connection()*
3337cscope_connection([{num} , {dbpath} [, {prepend}]])
3338 Checks for the existence of a |cscope| connection. If no
3339 parameters are specified, then the function returns:
3340 0, if cscope was not available (not compiled in), or
3341 if there are no cscope connections;
3342 1, if there is at least one cscope connection.
3343
3344 If parameters are specified, then the value of {num}
3345 determines how existence of a cscope connection is checked:
3346
3347 {num} Description of existence check
3348 ----- ------------------------------
3349 0 Same as no parameters (e.g., "cscope_connection()").
3350 1 Ignore {prepend}, and use partial string matches for
3351 {dbpath}.
3352 2 Ignore {prepend}, and use exact string matches for
3353 {dbpath}.
3354 3 Use {prepend}, use partial string matches for both
3355 {dbpath} and {prepend}.
3356 4 Use {prepend}, use exact string matches for both
3357 {dbpath} and {prepend}.
3358
3359 Note: All string comparisons are case sensitive!
3360
3361 Examples. Suppose we had the following (from ":cs show"): >
3362
3363 # pid database name prepend path
3364 0 27664 cscope.out /usr/local
3365<
3366 Invocation Return Val ~
3367 ---------- ---------- >
3368 cscope_connection() 1
3369 cscope_connection(1, "out") 1
3370 cscope_connection(2, "out") 0
3371 cscope_connection(3, "out") 0
3372 cscope_connection(3, "out", "local") 1
3373 cscope_connection(4, "out") 0
3374 cscope_connection(4, "out", "local") 0
3375 cscope_connection(4, "cscope.out", "/usr/local") 1
3376<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003377cursor({lnum}, {col} [, {off}]) *cursor()*
3378cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003379 Positions the cursor at the column (byte count) {col} in the
3380 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003381
Bram Moolenaar0b238792006-03-02 22:49:12 +00003382 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003383 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003384 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003385 [{lnum}, {col}, {off}]
3386 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003387 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003388 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003389
Bram Moolenaar071d4272004-06-13 20:20:40 +00003390 Does not change the jumplist.
3391 If {lnum} is greater than the number of lines in the buffer,
3392 the cursor will be positioned at the last line in the buffer.
3393 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003394 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003395 the cursor will be positioned at the last character in the
3396 line.
3397 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003398 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003399 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003400
Bram Moolenaar0b238792006-03-02 22:49:12 +00003401 When 'virtualedit' is used {off} specifies the offset in
3402 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003403 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003404 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003405
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003406
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003407deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003408 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003409 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003410 When {expr} is a |List| a full copy is created. This means
3411 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003412 copy, and vice versa. When an item is a |List| or
3413 |Dictionary|, a copy for it is made, recursively. Thus
3414 changing an item in the copy does not change the contents of
3415 the original |List|.
3416 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003417 When {noref} is omitted or zero a contained |List| or
3418 |Dictionary| is only copied once. All references point to
3419 this single copy. With {noref} set to 1 every occurrence of a
3420 |List| or |Dictionary| results in a new copy. This also means
3421 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003422 *E724*
3423 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003424 that refers back to a higher level making a deep copy with
3425 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003426 Also see |copy()|.
3427
Bram Moolenaarda440d22016-01-16 21:27:23 +01003428delete({fname} [, {flags}]) *delete()*
3429 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003430 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003431
3432 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003433 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003434
Bram Moolenaarda440d22016-01-16 21:27:23 +01003435 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003436 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003437 Note: on MS-Windows it is not possible to delete a directory
3438 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02003439
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003440 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003441
Bram Moolenaarda440d22016-01-16 21:27:23 +01003442 The result is a Number, which is 0 if the delete operation was
3443 successful and -1 when the deletion failed or partly failed.
3444
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003445 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01003446 To delete a line from the buffer use |:delete|. Use |:exe|
3447 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003448
3449 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003450did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003451 FileType event has been triggered at least once. Can be used
3452 to avoid triggering the FileType event again in the scripts
3453 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02003454 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003455 When editing another file, the counter is reset, thus this
3456 really checks if the FileType event has been triggered for the
3457 current buffer. This allows an autocommand that starts
3458 editing another buffer to set 'filetype' and load a syntax
3459 file.
3460
Bram Moolenaar47136d72004-10-12 20:02:24 +00003461diff_filler({lnum}) *diff_filler()*
3462 Returns the number of filler lines above line {lnum}.
3463 These are the lines that were inserted at this point in
3464 another diff'ed window. These filler lines are shown in the
3465 display but don't exist in the buffer.
3466 {lnum} is used like with |getline()|. Thus "." is the current
3467 line, "'m" mark m, etc.
3468 Returns 0 if the current window is not in diff mode.
3469
3470diff_hlID({lnum}, {col}) *diff_hlID()*
3471 Returns the highlight ID for diff mode at line {lnum} column
3472 {col} (byte index). When the current line does not have a
3473 diff change zero is returned.
3474 {lnum} is used like with |getline()|. Thus "." is the current
3475 line, "'m" mark m, etc.
3476 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3477 line.
3478 The highlight ID can be used with |synIDattr()| to obtain
3479 syntax information about the highlighting.
3480
Bram Moolenaar13065c42005-01-08 16:08:21 +00003481empty({expr}) *empty()*
3482 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003483 - A |List| or |Dictionary| is empty when it does not have any
3484 items.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003485 - A String is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003486 - A Number and Float is empty when its value is zero.
3487 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
3488 - A Job is empty when it failed to start.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003489 - A Channel is empty when it is closed.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003490
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003491 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003492 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003493
Bram Moolenaar071d4272004-06-13 20:20:40 +00003494escape({string}, {chars}) *escape()*
3495 Escape the characters in {chars} that occur in {string} with a
3496 backslash. Example: >
3497 :echo escape('c:\program files\vim', ' \')
3498< results in: >
3499 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003500< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003501
Bram Moolenaar446cb832008-06-24 21:56:24 +00003502 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003503eval({string}) Evaluate {string} and return the result. Especially useful to
3504 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003505 This works for Numbers, Floats, Strings and composites of
3506 them. Also works for |Funcref|s that refer to existing
3507 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003508
Bram Moolenaar071d4272004-06-13 20:20:40 +00003509eventhandler() *eventhandler()*
3510 Returns 1 when inside an event handler. That is that Vim got
3511 interrupted while waiting for the user to type a character,
3512 e.g., when dropping a file on Vim. This means interactive
3513 commands cannot be used. Otherwise zero is returned.
3514
3515executable({expr}) *executable()*
3516 This function checks if an executable with the name {expr}
3517 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003518 arguments.
3519 executable() uses the value of $PATH and/or the normal
3520 searchpath for programs. *PATHEXT*
3521 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3522 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar58b85342016-08-14 19:54:54 +02003523 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3524 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003525 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar58b85342016-08-14 19:54:54 +02003526 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003527 Unix shell, then the name is also tried without adding an
3528 extension.
3529 On MS-DOS and MS-Windows it only checks if the file exists and
3530 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003531 On MS-Windows an executable in the same directory as Vim is
3532 always found. Since this directory is added to $PATH it
3533 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003534 The result is a Number:
3535 1 exists
3536 0 does not exist
3537 -1 not implemented on this system
3538
Bram Moolenaar79815f12016-07-09 17:07:29 +02003539execute({command} [, {silent}]) *execute()*
3540 Execute an Ex command or commands and return the output as a
3541 string.
3542 {command} can be a string or a List. In case of a List the
3543 lines are executed one by one.
3544 This is equivalent to: >
3545 redir => var
3546 {command}
3547 redir END
3548<
3549 The optional {silent} argument can have these values:
3550 "" no `:silent` used
3551 "silent" `:silent` used
3552 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01003553 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02003554 `:redir`, error messages are dropped. When using an external
3555 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02003556 *E930*
3557 It is not possible to use `:redir` anywhere in {command}.
3558
3559 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02003560 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02003561
3562< When used recursively the output of the recursive call is not
3563 included in the output of the higher level call.
3564
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003565exepath({expr}) *exepath()*
3566 If {expr} is an executable and is either an absolute path, a
3567 relative path or found in $PATH, return the full path.
3568 Note that the current directory is used when {expr} starts
3569 with "./", which may be a problem for Vim: >
3570 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003571< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003572 an empty string is returned.
3573
Bram Moolenaar071d4272004-06-13 20:20:40 +00003574 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02003575exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
3576 zero otherwise.
3577
3578 For checking for a supported feature use |has()|.
3579 For checking if a file exists use |filereadable()|.
3580
3581 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003582 &option-name Vim option (only checks if it exists,
3583 not if it really works)
3584 +option-name Vim option that works.
3585 $ENVNAME environment variable (could also be
3586 done by comparing with an empty
3587 string)
3588 *funcname built-in function (see |functions|)
3589 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003590 |user-functions|). Also works for a
3591 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003592 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02003593 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003594 for |curly-braces-names|, |Dictionary|
3595 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003596 that evaluating an index may cause an
3597 error message for an invalid
3598 expression. E.g.: >
3599 :let l = [1, 2, 3]
3600 :echo exists("l[5]")
3601< 0 >
3602 :echo exists("l[xx]")
3603< E121: Undefined variable: xx
3604 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00003605 :cmdname Ex command: built-in command, user
3606 command or command modifier |:command|.
3607 Returns:
3608 1 for match with start of a command
3609 2 full match with a command
3610 3 matches several user commands
3611 To check for a supported command
3612 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00003613 :2match The |:2match| command.
3614 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003615 #event autocommand defined for this event
3616 #event#pattern autocommand defined for this event and
3617 pattern (the pattern is taken
3618 literally and compared to the
3619 autocommand patterns character by
3620 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003621 #group autocommand group exists
3622 #group#event autocommand defined for this group and
3623 event.
3624 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003625 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003626 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003627 ##event autocommand for this event is
3628 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003629
3630 Examples: >
3631 exists("&shortname")
3632 exists("$HOSTNAME")
3633 exists("*strftime")
3634 exists("*s:MyFunc")
3635 exists("bufcount")
3636 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003637 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003638 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003639 exists("#filetypeindent")
3640 exists("#filetypeindent#FileType")
3641 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003642 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003643< There must be no space between the symbol (&/$/*/#) and the
3644 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003645 There must be no extra characters after the name, although in
3646 a few cases this is ignored. That may become more strict in
3647 the future, thus don't count on it!
3648 Working example: >
3649 exists(":make")
3650< NOT working example: >
3651 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00003652
3653< Note that the argument must be a string, not the name of the
3654 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003655 exists(bufcount)
3656< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00003657 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003658
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003659exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003660 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003661 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003662 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003663 Examples: >
3664 :echo exp(2)
3665< 7.389056 >
3666 :echo exp(-1)
3667< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02003668 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003669
3670
Bram Moolenaar84f72352012-03-11 15:57:40 +01003671expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003672 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003673 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003674
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003675 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003676 Otherwise the result is a String and when there are several
3677 matches, they are separated by <NL> characters. [Note: in
3678 version 5.0 a space was used, which caused problems when a
3679 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00003680
Bram Moolenaar58b85342016-08-14 19:54:54 +02003681 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02003682 for a non-existing file is not included, unless {expr} does
3683 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003684
3685 When {expr} starts with '%', '#' or '<', the expansion is done
3686 like for the |cmdline-special| variables with their associated
3687 modifiers. Here is a short overview:
3688
3689 % current file name
3690 # alternate file name
3691 #n alternate file name n
3692 <cfile> file name under the cursor
3693 <afile> autocmd file name
3694 <abuf> autocmd buffer number (as a String!)
3695 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01003696 <sfile> sourced script file or function name
Bram Moolenaar81af9252010-12-10 20:35:50 +01003697 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00003698 <cword> word under the cursor
3699 <cWORD> WORD under the cursor
3700 <client> the {clientid} of the last received
3701 message |server2client()|
3702 Modifiers:
3703 :p expand to full path
3704 :h head (last path component removed)
3705 :t tail (last path component only)
3706 :r root (one extension removed)
3707 :e extension only
3708
3709 Example: >
3710 :let &tags = expand("%:p:h") . "/tags"
3711< Note that when expanding a string that starts with '%', '#' or
3712 '<', any following text is ignored. This does NOT work: >
3713 :let doesntwork = expand("%:h.bak")
3714< Use this: >
3715 :let doeswork = expand("%:h") . ".bak"
3716< Also note that expanding "<cfile>" and others only returns the
3717 referenced file name without further expansion. If "<cfile>"
3718 is "~/.cshrc", you need to do another expand() to have the
3719 "~/" expanded into the path of the home directory: >
3720 :echo expand(expand("<cfile>"))
3721<
3722 There cannot be white space between the variables and the
3723 following modifier. The |fnamemodify()| function can be used
3724 to modify normal file names.
3725
3726 When using '%' or '#', and the current or alternate file name
3727 is not defined, an empty string is used. Using "%:p" in a
3728 buffer with no name, results in the current directory, with a
3729 '/' added.
3730
3731 When {expr} does not start with '%', '#' or '<', it is
3732 expanded like a file name is expanded on the command line.
3733 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003734 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01003735 Names for non-existing files are included. The "**" item can
3736 be used to search in a directory tree. For example, to find
3737 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00003738 :echo expand("**/README")
3739<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003740 Expand() can also be used to expand variables and environment
3741 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003742 slow, because a shell may be used to do the expansion. See
3743 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003744 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02003745 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003746 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3747 "$FOOBAR".
3748
3749 See |glob()| for finding existing files. See |system()| for
3750 getting the raw output of an external command.
3751
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003752extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003753 {expr1} and {expr2} must be both |Lists| or both
3754 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003755
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003756 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003757 If {expr3} is given insert the items of {expr2} before item
3758 {expr3} in {expr1}. When {expr3} is zero insert before the
3759 first item. When {expr3} is equal to len({expr1}) then
3760 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003761 Examples: >
3762 :echo sort(extend(mylist, [7, 5]))
3763 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00003764< When {expr1} is the same List as {expr2} then the number of
3765 items copied is equal to the original length of the List.
3766 E.g., when {expr3} is 1 you get N new copies of the first item
3767 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02003768 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003769 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003770 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003771<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003772 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003773 Add all entries from {expr2} to {expr1}.
3774 If a key exists in both {expr1} and {expr2} then {expr3} is
3775 used to decide what to do:
3776 {expr3} = "keep": keep the value of {expr1}
3777 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003778 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003779 When {expr3} is omitted then "force" is assumed.
3780
3781 {expr1} is changed when {expr2} is not empty. If necessary
3782 make a copy of {expr1} first.
3783 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02003784 When {expr1} is locked and {expr2} is not empty the operation
3785 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003786 Returns {expr1}.
3787
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003788
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003789feedkeys({string} [, {mode}]) *feedkeys()*
3790 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003791 come from a mapping or were typed by the user.
3792 By default the string is added to the end of the typeahead
3793 buffer, thus if a mapping is still being executed the
3794 characters come after them. Use the 'i' flag to insert before
3795 other characters, they will be executed next, before any
3796 characters from a mapping.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003797 The function does not wait for processing of keys contained in
3798 {string}.
3799 To include special keys into {string}, use double-quotes
3800 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00003801 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003802 feedkeys('\<CR>') pushes 5 characters.
3803 If {mode} is absent, keys are remapped.
3804 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003805 'm' Remap keys. This is default.
3806 'n' Do not remap keys.
3807 't' Handle keys as if typed; otherwise they are handled as
3808 if coming from a mapping. This matters for undo,
3809 opening folds, etc.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003810 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01003811 'x' Execute commands until typeahead is empty. This is
3812 similar to using ":normal!". You can call feedkeys()
3813 several times without 'x' and then one time with 'x'
3814 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02003815 typeahead. Note that when Vim ends in Insert mode it
3816 will behave as if <Esc> is typed, to avoid getting
3817 stuck, waiting for a character to be typed before the
3818 script continues.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003819 '!' When used with 'x' will not end Insert mode. Can be
3820 used in a test when a timer is set to exit Insert mode
3821 a little later. Useful for testing CursorHoldI.
3822
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003823 Return value is always 0.
3824
Bram Moolenaar071d4272004-06-13 20:20:40 +00003825filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003826 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003827 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003828 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00003829 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003830 If you don't care about the file being readable you can use
3831 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003832 *file_readable()*
3833 Obsolete name: file_readable().
3834
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003835
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003836filewritable({file}) *filewritable()*
3837 The result is a Number, which is 1 when a file with the
3838 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00003839 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003840 directory, and we can write to it, the result is 2.
3841
3842
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003843filter({expr1}, {expr2}) *filter()*
3844 {expr1} must be a |List| or a |Dictionary|.
3845 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003846 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003847 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003848
Bram Moolenaar50ba5262016-09-22 22:33:02 +02003849 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003850 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02003851 of the current item and for a |List| |v:key| has the index of
3852 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003853 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003854 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003855< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003856 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003857< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003858 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003859< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003860
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003861 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003862 used as an expression again. Often it is good to use a
3863 |literal-string| to avoid having to double backslashes.
3864
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003865 If {expr2} is a |Funcref| it must take two arguments:
3866 1. the key or the index of the current item.
3867 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003868 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003869 Example that keeps the odd items of a list: >
3870 func Odd(idx, val)
3871 return a:idx % 2 == 1
3872 endfunc
3873 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02003874< It is shorter when using a |lambda|: >
3875 call filter(myList, {idx, val -> idx * val <= 42})
3876< If you do not use "val" you can leave it out: >
3877 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02003878<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003879 The operation is done in-place. If you want a |List| or
3880 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00003881 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003882
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003883< Returns {expr1}, the |List| or |Dictionary| that was filtered.
3884 When an error is encountered while evaluating {expr2} no
3885 further items in {expr1} are processed. When {expr2} is a
3886 Funcref errors inside a function are ignored, unless it was
3887 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003888
3889
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003890finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00003891 Find directory {name} in {path}. Supports both downwards and
3892 upwards recursive directory searches. See |file-searching|
3893 for the syntax of {path}.
3894 Returns the path of the first found match. When the found
3895 directory is below the current directory a relative path is
3896 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003897 If {path} is omitted or empty then 'path' is used.
3898 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003899 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00003900 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003901 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003902 {only available when compiled with the |+file_in_path|
3903 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003904
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003905findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003906 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003907 Uses 'suffixesadd'.
3908 Example: >
3909 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003910< Searches from the directory of the current file upwards until
3911 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003912
Bram Moolenaar446cb832008-06-24 21:56:24 +00003913float2nr({expr}) *float2nr()*
3914 Convert {expr} to a Number by omitting the part after the
3915 decimal point.
3916 {expr} must evaluate to a |Float| or a Number.
3917 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003918 result is truncated to 0x7fffffff or -0x7fffffff (or when
3919 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003920 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003921 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00003922 Examples: >
3923 echo float2nr(3.95)
3924< 3 >
3925 echo float2nr(-23.45)
3926< -23 >
3927 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003928< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00003929 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003930< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00003931 echo float2nr(1.0e-100)
3932< 0
3933 {only available when compiled with the |+float| feature}
3934
3935
3936floor({expr}) *floor()*
3937 Return the largest integral value less than or equal to
3938 {expr} as a |Float| (round down).
3939 {expr} must evaluate to a |Float| or a |Number|.
3940 Examples: >
3941 echo floor(1.856)
3942< 1.0 >
3943 echo floor(-5.456)
3944< -6.0 >
3945 echo floor(4.0)
3946< 4.0
3947 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003948
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003949
3950fmod({expr1}, {expr2}) *fmod()*
3951 Return the remainder of {expr1} / {expr2}, even if the
3952 division is not representable. Returns {expr1} - i * {expr2}
3953 for some integer i such that if {expr2} is non-zero, the
3954 result has the same sign as {expr1} and magnitude less than
3955 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003956 returned is zero. The value returned is a |Float|.
3957 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003958 Examples: >
3959 :echo fmod(12.33, 1.22)
3960< 0.13 >
3961 :echo fmod(-12.33, 1.22)
3962< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003963 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003964
3965
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003966fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003967 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003968 characters that have a special meaning, such as '%' and '|'
3969 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003970 For most systems the characters escaped are
3971 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3972 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003973 A leading '+' and '>' is also escaped (special after |:edit|
3974 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003975 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003976 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003977 :exe "edit " . fnameescape(fname)
3978< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003979 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003980
Bram Moolenaar071d4272004-06-13 20:20:40 +00003981fnamemodify({fname}, {mods}) *fnamemodify()*
3982 Modify file name {fname} according to {mods}. {mods} is a
3983 string of characters like it is used for file names on the
3984 command line. See |filename-modifiers|.
3985 Example: >
3986 :echo fnamemodify("main.c", ":p:h")
3987< results in: >
3988 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003989< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003990 |expand()| first then.
3991
3992foldclosed({lnum}) *foldclosed()*
3993 The result is a Number. If the line {lnum} is in a closed
3994 fold, the result is the number of the first line in that fold.
3995 If the line {lnum} is not in a closed fold, -1 is returned.
3996
3997foldclosedend({lnum}) *foldclosedend()*
3998 The result is a Number. If the line {lnum} is in a closed
3999 fold, the result is the number of the last line in that fold.
4000 If the line {lnum} is not in a closed fold, -1 is returned.
4001
4002foldlevel({lnum}) *foldlevel()*
4003 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004004 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004005 returned. If there is no fold at line {lnum}, zero is
4006 returned. It doesn't matter if the folds are open or closed.
4007 When used while updating folds (from 'foldexpr') -1 is
4008 returned for lines where folds are still to be updated and the
4009 foldlevel is unknown. As a special case the level of the
4010 previous line is usually available.
4011
4012 *foldtext()*
4013foldtext() Returns a String, to be displayed for a closed fold. This is
4014 the default function used for the 'foldtext' option and should
4015 only be called from evaluating 'foldtext'. It uses the
4016 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4017 The returned string looks like this: >
4018 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004019< The number of leading dashes depends on the foldlevel. The
4020 "45" is the number of lines in the fold. "abcdef" is the text
4021 in the first non-blank line of the fold. Leading white space,
4022 "//" or "/*" and the text from the 'foldmarker' and
4023 'commentstring' options is removed.
4024 When used to draw the actual foldtext, the rest of the line
4025 will be filled with the fold char from the 'fillchars'
4026 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004027 {not available when compiled without the |+folding| feature}
4028
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004029foldtextresult({lnum}) *foldtextresult()*
4030 Returns the text that is displayed for the closed fold at line
4031 {lnum}. Evaluates 'foldtext' in the appropriate context.
4032 When there is no closed fold at {lnum} an empty string is
4033 returned.
4034 {lnum} is used like with |getline()|. Thus "." is the current
4035 line, "'m" mark m, etc.
4036 Useful when exporting folded text, e.g., to HTML.
4037 {not available when compiled without the |+folding| feature}
4038
Bram Moolenaar071d4272004-06-13 20:20:40 +00004039 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004040foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004041 a client to a Vim server. |remote_send()|
4042 On Win32 systems this might not work, the OS does not always
4043 allow a window to bring itself to the foreground. Use
4044 |remote_foreground()| instead.
4045 {only in the Win32, Athena, Motif and GTK GUI versions and the
4046 Win32 console version}
4047
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004048 *funcref()*
4049funcref({name} [, {arglist}] [, {dict}])
4050 Just like |function()|, but the returned Funcref will lookup
4051 the function by reference, not by name. This matters when the
4052 function {name} is redefined later.
4053
4054 Unlike |function()|, {name} must be an existing user function.
4055 Also for autoloaded functions. {name} cannot be a builtin
4056 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004057
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004058 *function()* *E700* *E922* *E923*
4059function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004060 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004061 {name} can be the name of a user defined function or an
4062 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004063
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004064 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004065 partial the dict stored in it will be used and the {dict}
4066 argument is not allowed. E.g.: >
4067 let FuncWithArg = function(dict.Func, [arg])
4068 let Broken = function(dict.Func, [arg], dict)
4069<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004070 When using the Funcref the function will be found by {name},
4071 also when it was redefined later. Use |funcref()| to keep the
4072 same function.
4073
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004074 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004075 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004076 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004077
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004078 The arguments are passed to the function in front of other
4079 arguments. Example: >
4080 func Callback(arg1, arg2, name)
4081 ...
4082 let Func = function('Callback', ['one', 'two'])
4083 ...
4084 call Func('name')
4085< Invokes the function as with: >
4086 call Callback('one', 'two', 'name')
4087
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004088< The function() call can be nested to add more arguments to the
4089 Funcref. The extra arguments are appended to the list of
4090 arguments. Example: >
4091 func Callback(arg1, arg2, name)
4092 ...
4093 let Func = function('Callback', ['one'])
4094 let Func2 = function(Func, ['two'])
4095 ...
4096 call Func2('name')
4097< Invokes the function as with: >
4098 call Callback('one', 'two', 'name')
4099
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004100< The Dictionary is only useful when calling a "dict" function.
4101 In that case the {dict} is passed in as "self". Example: >
4102 function Callback() dict
4103 echo "called for " . self.name
4104 endfunction
4105 ...
4106 let context = {"name": "example"}
4107 let Func = function('Callback', context)
4108 ...
4109 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004110< The use of function() is not needed when there are no extra
4111 arguments, these two are equivalent: >
4112 let Func = function('Callback', context)
4113 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004114
4115< The argument list and the Dictionary can be combined: >
4116 function Callback(arg1, count) dict
4117 ...
4118 let context = {"name": "example"}
4119 let Func = function('Callback', ['one'], context)
4120 ...
4121 call Func(500)
4122< Invokes the function as with: >
4123 call context.Callback('one', 500)
4124
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004125
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004126garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004127 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
4128 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004129
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004130 There is hardly ever a need to invoke this function, as it is
4131 automatically done when Vim runs out of memory or is waiting
4132 for the user to press a key after 'updatetime'. Items without
4133 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004134 This is useful if you have deleted a very big |List| and/or
4135 |Dictionary| with circular references in a script that runs
4136 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004137
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004138 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00004139 collection will also be done when exiting Vim, if it wasn't
4140 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00004141
Bram Moolenaar574860b2016-05-24 17:33:34 +02004142 The garbage collection is not done immediately but only when
4143 it's safe to perform. This is when waiting for the user to
4144 type a character. To force garbage collection immediately use
4145 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004146
Bram Moolenaar677ee682005-01-27 14:41:15 +00004147get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004148 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004149 available return {default}. Return zero when {default} is
4150 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004151get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004152 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004153 item is not available return {default}. Return zero when
4154 {default} is omitted.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02004155get({func}, {what})
4156 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02004157 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01004158 "name" The function name
4159 "func" The function
4160 "dict" The dictionary
4161 "args" The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004162
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004163 *getbufinfo()*
4164getbufinfo([{expr}])
4165getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02004166 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004167
4168 Without an argument information about all the buffers is
4169 returned.
4170
4171 When the argument is a Dictionary only the buffers matching
4172 the specified criteria are returned. The following keys can
4173 be specified in {dict}:
4174 buflisted include only listed buffers.
4175 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01004176 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004177
4178 Otherwise, {expr} specifies a particular buffer to return
4179 information for. For the use of {expr}, see |bufname()|
4180 above. If the buffer is found the returned List has one item.
4181 Otherwise the result is an empty list.
4182
4183 Each returned List item is a dictionary with the following
4184 entries:
Bram Moolenaar33928832016-08-18 21:22:04 +02004185 bufnr buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004186 changed TRUE if the buffer is modified.
4187 changedtick number of changes made to the buffer.
4188 hidden TRUE if the buffer is hidden.
4189 listed TRUE if the buffer is listed.
4190 lnum current line number in buffer.
4191 loaded TRUE if the buffer is loaded.
4192 name full path to the file in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004193 signs list of signs placed in the buffer.
4194 Each list item is a dictionary with
4195 the following fields:
4196 id sign identifier
4197 lnum line number
4198 name sign name
Bram Moolenaar30567352016-08-27 21:25:44 +02004199 variables a reference to the dictionary with
4200 buffer-local variables.
4201 windows list of |window-ID|s that display this
4202 buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004203
4204 Examples: >
4205 for buf in getbufinfo()
4206 echo buf.name
4207 endfor
4208 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02004209 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004210 ....
4211 endif
4212 endfor
4213<
Bram Moolenaar30567352016-08-27 21:25:44 +02004214 To get buffer-local options use: >
4215 getbufvar({bufnr}, '&')
4216
4217<
Bram Moolenaar45360022005-07-21 21:08:21 +00004218 *getbufline()*
4219getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004220 Return a |List| with the lines starting from {lnum} to {end}
4221 (inclusive) in the buffer {expr}. If {end} is omitted, a
4222 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004223
4224 For the use of {expr}, see |bufname()| above.
4225
Bram Moolenaar661b1822005-07-28 22:36:45 +00004226 For {lnum} and {end} "$" can be used for the last line of the
4227 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00004228
4229 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004230 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004231
4232 When {end} is greater than the number of lines in the buffer,
4233 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004234 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00004235 returned.
4236
Bram Moolenaar661b1822005-07-28 22:36:45 +00004237 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004238 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004239
4240 Example: >
4241 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004242
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004243getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004244 The result is the value of option or local buffer variable
4245 {varname} in buffer {expr}. Note that the name without "b:"
4246 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004247 When {varname} is empty returns a dictionary with all the
4248 buffer-local variables.
Bram Moolenaar30567352016-08-27 21:25:44 +02004249 When {varname} is equal to "&" returns a dictionary with all
4250 the buffer-local options.
4251 Otherwise, when {varname} starts with "&" returns the value of
4252 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004253 This also works for a global or buffer-local option, but it
4254 doesn't work for a global variable, window-local variable or
4255 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004256 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004257 When the buffer or variable doesn't exist {def} or an empty
4258 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004259 Examples: >
4260 :let bufmodified = getbufvar(1, "&mod")
4261 :echo "todo myvar = " . getbufvar("todo", "myvar")
4262<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004263getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00004264 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004265 If [expr] is omitted, wait until a character is available.
4266 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004267 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004268 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00004269 not consumed. Return zero if no character available.
4270
Bram Moolenaardfb18412013-12-11 18:53:29 +01004271 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02004272 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00004273 result is a number. Use nr2char() to convert it to a String.
4274 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02004275 For a special key it's a String with a sequence of bytes
4276 starting with 0x80 (decimal: 128). This is the same value as
4277 the String "\<Key>", e.g., "\<Left>". The returned value is
4278 also a String when a modifier (shift, control, alt) was used
4279 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004280
Bram Moolenaar822ff862014-06-12 21:46:14 +02004281 When [expr] is 0 and Esc is typed, there will be a short delay
4282 while Vim waits to see if this is the start of an escape
4283 sequence.
4284
Bram Moolenaardfb18412013-12-11 18:53:29 +01004285 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004286 one-byte character it is the character itself as a number.
4287 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004288
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004289 Use getcharmod() to obtain any additional modifiers.
4290
Bram Moolenaar219b8702006-11-01 14:32:36 +00004291 When the user clicks a mouse button, the mouse event will be
4292 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02004293 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
4294 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00004295 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00004296 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00004297 exe v:mouse_win . "wincmd w"
4298 exe v:mouse_lnum
4299 exe "normal " . v:mouse_col . "|"
4300 endif
4301<
Bram Moolenaar690afe12017-01-28 18:34:47 +01004302 When using bracketed paste only the first character is
4303 returned, the rest of the pasted text is dropped.
4304 |xterm-bracketed-paste|.
4305
Bram Moolenaar071d4272004-06-13 20:20:40 +00004306 There is no prompt, you will somehow have to make clear to the
4307 user that a character has to be typed.
4308 There is no mapping for the character.
4309 Key codes are replaced, thus when the user presses the <Del>
4310 key you get the code for the <Del> key, not the raw character
4311 sequence. Examples: >
4312 getchar() == "\<Del>"
4313 getchar() == "\<S-Left>"
4314< This example redefines "f" to ignore case: >
4315 :nmap f :call FindChar()<CR>
4316 :function FindChar()
4317 : let c = nr2char(getchar())
4318 : while col('.') < col('$') - 1
4319 : normal l
4320 : if getline('.')[col('.') - 1] ==? c
4321 : break
4322 : endif
4323 : endwhile
4324 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01004325<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004326 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01004327 |<CursorHold>|. Often you will want to ignore this and get
4328 another character: >
4329 :function GetKey()
4330 : let c = getchar()
4331 : while c == "\<CursorHold>"
4332 : let c = getchar()
4333 : endwhile
4334 : return c
4335 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00004336
4337getcharmod() *getcharmod()*
4338 The result is a Number which is the state of the modifiers for
4339 the last obtained character with getchar() or in another way.
4340 These values are added together:
4341 2 shift
4342 4 control
4343 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004344 16 meta (when it's different from ALT)
4345 32 mouse double click
4346 64 mouse triple click
4347 96 mouse quadruple click (== 32 + 64)
4348 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004349 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02004350 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004351 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004352
Bram Moolenaardbd24b52015-08-11 14:26:19 +02004353getcharsearch() *getcharsearch()*
4354 Return the current character search information as a {dict}
4355 with the following entries:
4356
4357 char character previously used for a character
4358 search (|t|, |f|, |T|, or |F|); empty string
4359 if no character search has been performed
4360 forward direction of character search; 1 for forward,
4361 0 for backward
4362 until type of character search; 1 for a |t| or |T|
4363 character search, 0 for an |f| or |F|
4364 character search
4365
4366 This can be useful to always have |;| and |,| search
4367 forward/backward regardless of the direction of the previous
4368 character search: >
4369 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4370 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4371< Also see |setcharsearch()|.
4372
Bram Moolenaar071d4272004-06-13 20:20:40 +00004373getcmdline() *getcmdline()*
4374 Return the current command-line. Only works when the command
4375 line is being edited, thus requires use of |c_CTRL-\_e| or
4376 |c_CTRL-R_=|.
4377 Example: >
4378 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004379< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004380
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004381getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004382 Return the position of the cursor in the command line as a
4383 byte count. The first column is 1.
4384 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004385 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4386 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004387 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
4388
4389getcmdtype() *getcmdtype()*
4390 Return the current command-line type. Possible return values
4391 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00004392 : normal Ex command
4393 > debug mode command |debug-mode|
4394 / forward search command
4395 ? backward search command
4396 @ |input()| command
4397 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02004398 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004399 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004400 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4401 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004402 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004403
Bram Moolenaarfb539272014-08-22 19:21:47 +02004404getcmdwintype() *getcmdwintype()*
4405 Return the current |command-line-window| type. Possible return
4406 values are the same as |getcmdtype()|. Returns an empty string
4407 when not in the command-line window.
4408
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004409getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004410 Return a list of command-line completion matches. {type}
4411 specifies what for. The following completion types are
4412 supported:
4413
4414 augroup autocmd groups
4415 buffer buffer names
4416 behave :behave suboptions
4417 color color schemes
4418 command Ex command (and arguments)
4419 compiler compilers
4420 cscope |:cscope| suboptions
4421 dir directory names
4422 environment environment variable names
4423 event autocommand events
4424 expression Vim expression
4425 file file and directory names
4426 file_in_path file and directory names in |'path'|
4427 filetype filetype names |'filetype'|
4428 function function name
4429 help help subjects
4430 highlight highlight groups
4431 history :history suboptions
4432 locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02004433 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004434 mapping mapping name
4435 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004436 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004437 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004438 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004439 shellcmd Shell command
4440 sign |:sign| suboptions
4441 syntax syntax file names |'syntax'|
4442 syntime |:syntime| suboptions
4443 tag tags
4444 tag_listfiles tags, file names
4445 user user names
4446 var user variables
4447
4448 If {pat} is an empty string, then all the matches are returned.
4449 Otherwise only items matching {pat} are returned. See
4450 |wildcards| for the use of special characters in {pat}.
4451
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004452 If the optional {filtered} flag is set to 1, then 'wildignore'
4453 is applied to filter the results. Otherwise all the matches
4454 are returned. The 'wildignorecase' option always applies.
4455
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004456 If there are no matches, an empty list is returned. An
4457 invalid value for {type} produces an error.
4458
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004459 *getcurpos()*
4460getcurpos() Get the position of the cursor. This is like getpos('.'), but
4461 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01004462 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004463 The "curswant" number is the preferred column when moving the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004464 cursor vertically. Also see |getpos()|.
4465
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004466 This can be used to save and restore the cursor position: >
4467 let save_cursor = getcurpos()
4468 MoveTheCursorAround
4469 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004470< Note that this only works within the window. See
4471 |winrestview()| for restoring more state.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004472 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01004473getcwd([{winnr} [, {tabnr}]])
4474 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00004475 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004476 Without arguments, for the current window.
4477
4478 With {winnr} return the local current directory of this window
4479 in the current tab page.
4480 With {winnr} and {tabnr} return the local current directory of
4481 the window in the specified tab page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02004482 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004483 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004484
4485getfsize({fname}) *getfsize()*
4486 The result is a Number, which is the size in bytes of the
4487 given file {fname}.
4488 If {fname} is a directory, 0 is returned.
4489 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00004490 If the size of {fname} is too big to fit in a Number then -2
4491 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004492
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004493getfontname([{name}]) *getfontname()*
4494 Without an argument returns the name of the normal font being
4495 used. Like what is used for the Normal highlight group
4496 |hl-Normal|.
4497 With an argument a check is done whether {name} is a valid
4498 font name. If not then an empty string is returned.
4499 Otherwise the actual font name is returned, or {name} if the
4500 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00004501 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004502 gvimrc file. Use the |GUIEnter| autocommand to use this
4503 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01004504 Note that the GTK GUI accepts any font name, thus checking for
4505 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004506
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004507getfperm({fname}) *getfperm()*
4508 The result is a String, which is the read, write, and execute
4509 permissions of the given file {fname}.
4510 If {fname} does not exist or its directory cannot be read, an
4511 empty string is returned.
4512 The result is of the form "rwxrwxrwx", where each group of
4513 "rwx" flags represent, in turn, the permissions of the owner
4514 of the file, the group the file belongs to, and other users.
4515 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02004516 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004517 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02004518 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004519< This will hopefully (from a security point of view) display
4520 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004521
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004522 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01004523
Bram Moolenaar071d4272004-06-13 20:20:40 +00004524getftime({fname}) *getftime()*
4525 The result is a Number, which is the last modification time of
4526 the given file {fname}. The value is measured as seconds
4527 since 1st Jan 1970, and may be passed to strftime(). See also
4528 |localtime()| and |strftime()|.
4529 If the file {fname} can't be found -1 is returned.
4530
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004531getftype({fname}) *getftype()*
4532 The result is a String, which is a description of the kind of
4533 file of the given file {fname}.
4534 If {fname} does not exist an empty string is returned.
4535 Here is a table over different kinds of files and their
4536 results:
4537 Normal file "file"
4538 Directory "dir"
4539 Symbolic link "link"
4540 Block device "bdev"
4541 Character device "cdev"
4542 Socket "socket"
4543 FIFO "fifo"
4544 All other "other"
4545 Example: >
4546 getftype("/home")
4547< Note that a type such as "link" will only be returned on
4548 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01004549 "file" are returned. On MS-Windows a symbolic link to a
4550 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004551
Bram Moolenaar071d4272004-06-13 20:20:40 +00004552 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004553getline({lnum} [, {end}])
4554 Without {end} the result is a String, which is line {lnum}
4555 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004556 getline(1)
4557< When {lnum} is a String that doesn't start with a
4558 digit, line() is called to translate the String into a Number.
4559 To get the line under the cursor: >
4560 getline(".")
4561< When {lnum} is smaller than 1 or bigger than the number of
4562 lines in the buffer, an empty string is returned.
4563
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004564 When {end} is given the result is a |List| where each item is
4565 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004566 including line {end}.
4567 {end} is used in the same way as {lnum}.
4568 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004569 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004570 Example: >
4571 :let start = line('.')
4572 :let end = search("^$") - 1
4573 :let lines = getline(start, end)
4574
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004575< To get lines from another buffer see |getbufline()|
4576
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004577getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004578 Returns a list with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02004579 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004580 When {nr} is zero the current window is used.
4581
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004582 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00004583 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004584 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004585
Bram Moolenaard823fa92016-08-12 16:29:27 +02004586 If the optional {what} dictionary argument is supplied, then
4587 returns the items listed in {what} as a dictionary. Refer to
4588 |getqflist()| for the supported items in {what}.
4589
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004590getmatches() *getmatches()*
4591 Returns a |List| with all matches previously defined by
4592 |matchadd()| and the |:match| commands. |getmatches()| is
4593 useful in combination with |setmatches()|, as |setmatches()|
4594 can restore a list of matches saved by |getmatches()|.
4595 Example: >
4596 :echo getmatches()
4597< [{'group': 'MyGroup1', 'pattern': 'TODO',
4598 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4599 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4600 :let m = getmatches()
4601 :call clearmatches()
4602 :echo getmatches()
4603< [] >
4604 :call setmatches(m)
4605 :echo getmatches()
4606< [{'group': 'MyGroup1', 'pattern': 'TODO',
4607 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4608 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4609 :unlet m
4610<
Bram Moolenaar822ff862014-06-12 21:46:14 +02004611 *getpid()*
4612getpid() Return a Number which is the process ID of the Vim process.
4613 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar58b85342016-08-14 19:54:54 +02004614 exits. On MS-DOS it's always zero.
Bram Moolenaar822ff862014-06-12 21:46:14 +02004615
4616 *getpos()*
4617getpos({expr}) Get the position for {expr}. For possible values of {expr}
4618 see |line()|. For getting the cursor position see
4619 |getcurpos()|.
4620 The result is a |List| with four numbers:
4621 [bufnum, lnum, col, off]
4622 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4623 is the buffer number of the mark.
4624 "lnum" and "col" are the position in the buffer. The first
4625 column is 1.
4626 The "off" number is zero, unless 'virtualedit' is used. Then
4627 it is the offset in screen columns from the start of the
4628 character. E.g., a position within a <Tab> or after the last
4629 character.
4630 Note that for '< and '> Visual mode matters: when it is "V"
4631 (visual line mode) the column of '< is zero and the column of
4632 '> is a large number.
4633 This can be used to save and restore the position of a mark: >
4634 let save_a_mark = getpos("'a")
4635 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01004636 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02004637< Also see |getcurpos()| and |setpos()|.
4638
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004639
Bram Moolenaard823fa92016-08-12 16:29:27 +02004640getqflist([{what}]) *getqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004641 Returns a list with all the current quickfix errors. Each
4642 list item is a dictionary with these entries:
4643 bufnr number of buffer that has the file name, use
4644 bufname() to get the name
4645 lnum line number in the buffer (first line is 1)
4646 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004647 vcol |TRUE|: "col" is visual column
4648 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004649 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004650 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004651 text description of the error
4652 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004653 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004654
Bram Moolenaar7571d552016-08-18 22:54:46 +02004655 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004656 returned. Quickfix list entries with non-existing buffer
4657 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004658
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004659 Useful application: Find pattern matches in multiple files and
4660 do something with them: >
4661 :vimgrep /theword/jg *.c
4662 :for d in getqflist()
4663 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4664 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02004665<
4666 If the optional {what} dictionary argument is supplied, then
4667 returns only the items listed in {what} as a dictionary. The
4668 following string items are supported in {what}:
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02004669 context get the context stored with |setqflist()|
Bram Moolenaar36538222017-09-02 19:51:44 +02004670 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01004671 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02004672 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02004673 id get information for the quickfix list with
4674 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01004675 current list or the list specified by "nr"
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02004676 idx index of the current entry in the list
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02004677 items quickfix list entries
Bram Moolenaar2c809b72017-09-01 18:34:02 +02004678 lines use 'errorformat' to extract items from a list
4679 of lines and return the resulting entries.
4680 Only a |List| type is accepted. The current
4681 quickfix list is not modified.
Bram Moolenaar890680c2016-09-27 21:28:56 +02004682 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02004683 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02004684 the last quickfix list
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02004685 size number of entries in the quickfix list
Bram Moolenaar7571d552016-08-18 22:54:46 +02004686 title get the list title
Bram Moolenaar74240d32017-12-10 15:26:15 +01004687 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02004688 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01004689 Non-string items in {what} are ignored. To get the value of a
4690 particular item, set it to one.
Bram Moolenaard823fa92016-08-12 16:29:27 +02004691 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02004692 If both "nr" and a non-zero "id" are specified, then the list
4693 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004694 To get the number of lists in the quickfix stack, set "nr" to
4695 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02004696 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004697 When "lines" is specified, all the other items except "efm"
4698 are ignored. The returned dictionary contains the entry
4699 "items" with the list of entries.
Bram Moolenaard823fa92016-08-12 16:29:27 +02004700 In case of error processing {what}, an empty dictionary is
4701 returned.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004702
Bram Moolenaard823fa92016-08-12 16:29:27 +02004703 The returned dictionary contains the following entries:
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02004704 context context information stored with |setqflist()|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02004705 id quickfix list ID |quickfix-ID|
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02004706 idx index of the current entry in the list
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02004707 items quickfix list entries
Bram Moolenaard823fa92016-08-12 16:29:27 +02004708 nr quickfix list number
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02004709 size number of entries in the quickfix list
Bram Moolenaard823fa92016-08-12 16:29:27 +02004710 title quickfix list title text
Bram Moolenaar74240d32017-12-10 15:26:15 +01004711 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02004712
4713 Examples: >
4714 :echo getqflist({'all': 1})
4715 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02004716 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02004717<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004718
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004719getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004720 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004721 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004722 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004723< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004724
4725 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004726 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004727 getreg('=', 1) returns the expression itself, so that it can
4728 be restored with |setreg()|. For other registers the extra
4729 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004730
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004731 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004732 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004733 about zero bytes possibly present inside register: without
4734 third argument both NLs and zero bytes are represented as NLs
4735 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004736 When the register was not set an empty list is returned.
4737
Bram Moolenaar071d4272004-06-13 20:20:40 +00004738 If {regname} is not specified, |v:register| is used.
4739
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004740
Bram Moolenaar071d4272004-06-13 20:20:40 +00004741getregtype([{regname}]) *getregtype()*
4742 The result is a String, which is type of register {regname}.
4743 The value will be one of:
4744 "v" for |characterwise| text
4745 "V" for |linewise| text
4746 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01004747 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00004748 <CTRL-V> is one character with value 0x16.
4749 If {regname} is not specified, |v:register| is used.
4750
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004751gettabinfo([{arg}]) *gettabinfo()*
4752 If {arg} is not specified, then information about all the tab
4753 pages is returned as a List. Each List item is a Dictionary.
4754 Otherwise, {arg} specifies the tab page number and information
4755 about that one is returned. If the tab page does not exist an
4756 empty List is returned.
4757
4758 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02004759 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02004760 variables a reference to the dictionary with
4761 tabpage-local variables
Bram Moolenaar7571d552016-08-18 22:54:46 +02004762 windows List of |window-ID|s in the tag page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004763
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004764gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004765 Get the value of a tab-local variable {varname} in tab page
4766 {tabnr}. |t:var|
4767 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02004768 When {varname} is empty a dictionary with all tab-local
4769 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004770 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004771 When the tab or variable doesn't exist {def} or an empty
4772 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004773
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004774gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004775 Get the value of window-local variable {varname} in window
4776 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004777 When {varname} is empty a dictionary with all window-local
4778 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02004779 When {varname} is equal to "&" get the values of all
4780 window-local options in a Dictionary.
4781 Otherwise, when {varname} starts with "&" get the value of a
4782 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004783 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004784 Tabs are numbered starting with one. For the current tabpage
4785 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02004786 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004787 When {winnr} is zero the current window is used.
4788 This also works for a global option, buffer-local option and
4789 window-local option, but it doesn't work for a global variable
4790 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004791 When the tab, window or variable doesn't exist {def} or an
4792 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004793 Examples: >
4794 :let list_is_on = gettabwinvar(1, 2, '&list')
4795 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004796<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004797 *getwinposx()*
4798getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004799 the left hand side of the GUI Vim window. Also works for an
4800 xterm.
4801 The result will be -1 if the information is not available.
4802 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004803
4804 *getwinposy()*
4805getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004806 the top of the GUI Vim window. Also works for an xterm.
4807 The result will be -1 if the information is not available.
4808 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004809
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004810getwininfo([{winid}]) *getwininfo()*
4811 Returns information about windows as a List with Dictionaries.
4812
4813 If {winid} is given Information about the window with that ID
4814 is returned. If the window does not exist the result is an
4815 empty list.
4816
Bram Moolenaar7571d552016-08-18 22:54:46 +02004817 Without {winid} information about all the windows in all the
4818 tab pages is returned.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004819
4820 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02004821 bufnr number of buffer in the window
Bram Moolenaar37c64c72017-09-19 22:06:03 +02004822 height window height (excluding winbar)
4823 winbar 1 if the window has a toolbar, 0
4824 otherwise
Bram Moolenaar386600f2016-08-15 22:16:25 +02004825 loclist 1 if showing a location list
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004826 {only with the +quickfix feature}
Bram Moolenaar386600f2016-08-15 22:16:25 +02004827 quickfix 1 if quickfix or location list window
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004828 {only with the +quickfix feature}
Bram Moolenaar69905d12017-08-13 18:14:47 +02004829 terminal 1 if a terminal window
4830 {only with the +terminal feature}
Bram Moolenaar7571d552016-08-18 22:54:46 +02004831 tabnr tab page number
Bram Moolenaar30567352016-08-27 21:25:44 +02004832 variables a reference to the dictionary with
4833 window-local variables
Bram Moolenaar386600f2016-08-15 22:16:25 +02004834 width window width
Bram Moolenaar7571d552016-08-18 22:54:46 +02004835 winid |window-ID|
4836 winnr window number
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004837
Bram Moolenaar30567352016-08-27 21:25:44 +02004838 To obtain all window-local variables use: >
4839 gettabwinvar({tabnr}, {winnr}, '&')
4840
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004841getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004842 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004843 Examples: >
4844 :let list_is_on = getwinvar(2, '&list')
4845 :echo "myvar = " . getwinvar(1, 'myvar')
4846<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004847glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004848 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004849 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004850
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004851 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004852 the 'suffixes' and 'wildignore' options apply: Names matching
4853 one of the patterns in 'wildignore' will be skipped and
4854 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01004855 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004856
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004857 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar84f72352012-03-11 15:57:40 +01004858 with all matching files. The advantage of using a List is,
4859 you also get filenames containing newlines correctly.
4860 Otherwise the result is a String and when there are several
4861 matches, they are separated by <NL> characters.
4862
4863 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004864
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02004865 A name for a non-existing file is not included. A symbolic
4866 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004867 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004868 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004869
4870 For most systems backticks can be used to get files names from
4871 any external command. Example: >
4872 :let tagfiles = glob("`find . -name tags -print`")
4873 :let &tags = substitute(tagfiles, "\n", ",", "g")
4874< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02004875 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004876
4877 See |expand()| for expanding special Vim variables. See
4878 |system()| for getting the raw output of an external command.
4879
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01004880glob2regpat({expr}) *glob2regpat()*
4881 Convert a file pattern, as used by glob(), into a search
4882 pattern. The result can be used to match with a string that
4883 is a file name. E.g. >
4884 if filename =~ glob2regpat('Make*.mak')
4885< This is equivalent to: >
4886 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01004887< When {expr} is an empty string the result is "^$", match an
4888 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02004889 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02004890 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01004891
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004892 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004893globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004894 Perform glob() on all directories in {path} and concatenate
4895 the results. Example: >
4896 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004897<
4898 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00004899 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004900 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004901 To add a comma inside a directory name escape it with a
4902 backslash. Note that on MS-Windows a directory may have a
4903 trailing backslash, remove it if you put a comma after it.
4904 If the expansion fails for one of the directories, there is no
4905 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004906
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004907 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004908 the 'suffixes' and 'wildignore' options apply: Names matching
4909 one of the patterns in 'wildignore' will be skipped and
4910 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004911
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004912 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004913 with all matching files. The advantage of using a List is, you
4914 also get filenames containing newlines correctly. Otherwise
4915 the result is a String and when there are several matches,
4916 they are separated by <NL> characters. Example: >
4917 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4918<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004919 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004920
Bram Moolenaar02743632005-07-25 20:42:36 +00004921 The "**" item can be used to search in a directory tree.
4922 For example, to find all "README.txt" files in the directories
4923 in 'runtimepath' and below: >
4924 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00004925< Upwards search and limiting the depth of "**" is not
4926 supported, thus using 'path' will not always work properly.
4927
Bram Moolenaar071d4272004-06-13 20:20:40 +00004928 *has()*
4929has({feature}) The result is a Number, which is 1 if the feature {feature} is
4930 supported, zero otherwise. The {feature} argument is a
4931 string. See |feature-list| below.
4932 Also see |exists()|.
4933
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004934
4935has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004936 The result is a Number, which is 1 if |Dictionary| {dict} has
4937 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004938
Bram Moolenaarc9703302016-01-17 21:49:33 +01004939haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4940 The result is a Number, which is 1 when the window has set a
4941 local path via |:lcd|, and 0 otherwise.
4942
4943 Without arguments use the current window.
4944 With {winnr} use this window in the current tab page.
4945 With {winnr} and {tabnr} use the window in the specified tab
4946 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02004947 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004948 Return 0 if the arguments are invalid.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004949
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004950hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004951 The result is a Number, which is 1 if there is a mapping that
4952 contains {what} in somewhere in the rhs (what it is mapped to)
4953 and this mapping exists in one of the modes indicated by
4954 {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004955 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00004956 instead of mappings. Don't forget to specify Insert and/or
4957 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004958 Both the global mappings and the mappings local to the current
4959 buffer are checked for a match.
4960 If no matching mapping is found 0 is returned.
4961 The following characters are recognized in {mode}:
4962 n Normal mode
4963 v Visual mode
4964 o Operator-pending mode
4965 i Insert mode
4966 l Language-Argument ("r", "f", "t", etc.)
4967 c Command-line mode
4968 When {mode} is omitted, "nvo" is used.
4969
4970 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02004971 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004972 :if !hasmapto('\ABCdoit')
4973 : map <Leader>d \ABCdoit
4974 :endif
4975< This installs the mapping to "\ABCdoit" only if there isn't
4976 already a mapping to "\ABCdoit".
4977
4978histadd({history}, {item}) *histadd()*
4979 Add the String {item} to the history {history} which can be
4980 one of: *hist-names*
4981 "cmd" or ":" command line history
4982 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00004983 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00004984 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02004985 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02004986 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02004987 The {history} string does not need to be the whole name, one
4988 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004989 If {item} does already exist in the history, it will be
4990 shifted to become the newest entry.
4991 The result is a Number: 1 if the operation was successful,
4992 otherwise 0 is returned.
4993
4994 Example: >
4995 :call histadd("input", strftime("%Y %b %d"))
4996 :let date=input("Enter date: ")
4997< This function is not available in the |sandbox|.
4998
4999histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005000 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005001 for the possible values of {history}.
5002
Bram Moolenaarc236c162008-07-13 17:41:49 +00005003 If the parameter {item} evaluates to a String, it is used as a
5004 regular expression. All entries matching that expression will
5005 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005006 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005007 If {item} evaluates to a Number, it will be interpreted as
5008 an index, see |:history-indexing|. The respective entry will
5009 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005010
5011 The result is a Number: 1 for a successful operation,
5012 otherwise 0 is returned.
5013
5014 Examples:
5015 Clear expression register history: >
5016 :call histdel("expr")
5017<
5018 Remove all entries starting with "*" from the search history: >
5019 :call histdel("/", '^\*')
5020<
5021 The following three are equivalent: >
5022 :call histdel("search", histnr("search"))
5023 :call histdel("search", -1)
5024 :call histdel("search", '^'.histget("search", -1).'$')
5025<
5026 To delete the last search pattern and use the last-but-one for
5027 the "n" command and 'hlsearch': >
5028 :call histdel("search", -1)
5029 :let @/ = histget("search", -1)
5030
5031histget({history} [, {index}]) *histget()*
5032 The result is a String, the entry with Number {index} from
5033 {history}. See |hist-names| for the possible values of
5034 {history}, and |:history-indexing| for {index}. If there is
5035 no such entry, an empty String is returned. When {index} is
5036 omitted, the most recent item from the history is used.
5037
5038 Examples:
5039 Redo the second last search from history. >
5040 :execute '/' . histget("search", -2)
5041
5042< Define an Ex command ":H {num}" that supports re-execution of
5043 the {num}th entry from the output of |:history|. >
5044 :command -nargs=1 H execute histget("cmd", 0+<args>)
5045<
5046histnr({history}) *histnr()*
5047 The result is the Number of the current entry in {history}.
5048 See |hist-names| for the possible values of {history}.
5049 If an error occurred, -1 is returned.
5050
5051 Example: >
5052 :let inp_index = histnr("expr")
5053<
5054hlexists({name}) *hlexists()*
5055 The result is a Number, which is non-zero if a highlight group
5056 called {name} exists. This is when the group has been
5057 defined in some way. Not necessarily when highlighting has
5058 been defined for it, it may also have been used for a syntax
5059 item.
5060 *highlight_exists()*
5061 Obsolete name: highlight_exists().
5062
5063 *hlID()*
5064hlID({name}) The result is a Number, which is the ID of the highlight group
5065 with name {name}. When the highlight group doesn't exist,
5066 zero is returned.
5067 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02005068 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005069 "Comment" group: >
5070 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5071< *highlightID()*
5072 Obsolete name: highlightID().
5073
5074hostname() *hostname()*
5075 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005076 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00005077 256 characters long are truncated.
5078
5079iconv({expr}, {from}, {to}) *iconv()*
5080 The result is a String, which is the text {expr} converted
5081 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005082 When the conversion completely fails an empty string is
5083 returned. When some characters could not be converted they
5084 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005085 The encoding names are whatever the iconv() library function
5086 can accept, see ":!man 3 iconv".
5087 Most conversions require Vim to be compiled with the |+iconv|
5088 feature. Otherwise only UTF-8 to latin1 conversion and back
5089 can be done.
5090 This can be used to display messages with special characters,
5091 no matter what 'encoding' is set to. Write the message in
5092 UTF-8 and use: >
5093 echo iconv(utf8_str, "utf-8", &enc)
5094< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5095 from/to UCS-2 is automatically changed to use UTF-8. You
5096 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005097 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005098
5099 *indent()*
5100indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5101 current buffer. The indent is counted in spaces, the value
5102 of 'tabstop' is relevant. {lnum} is used just like in
5103 |getline()|.
5104 When {lnum} is invalid -1 is returned.
5105
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005106
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005107index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005108 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005109 value equal to {expr}. There is no automatic conversion, so
5110 the String "4" is different from the Number 4. And the number
5111 4 is different from the Float 4.0. The value of 'ignorecase'
5112 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00005113 If {start} is given then start looking at the item with index
5114 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005115 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005116 case must match.
5117 -1 is returned when {expr} is not found in {list}.
5118 Example: >
5119 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005120 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005121
5122
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005123input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005124 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005125 the command-line. The {prompt} argument is either a prompt
5126 string, or a blank string (for no prompt). A '\n' can be used
5127 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005128 The highlighting set with |:echohl| is used for the prompt.
5129 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02005130 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005131 for lines typed for input().
5132 Example: >
5133 :if input("Coffee or beer? ") == "beer"
5134 : echo "Cheers!"
5135 :endif
5136<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005137 If the optional {text} argument is present and not empty, this
5138 is used for the default reply, as if the user typed this.
5139 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005140 :let color = input("Color? ", "white")
5141
5142< The optional {completion} argument specifies the type of
5143 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02005144 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005145 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005146 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005147 more information. Example: >
5148 let fname = input("File: ", "", "file")
5149<
5150 NOTE: This function must not be used in a startup file, for
5151 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005152 Note: When input() is called from within a mapping it will
5153 consume remaining characters from that mapping, because a
5154 mapping is handled like the characters were typed.
5155 Use |inputsave()| before input() and |inputrestore()|
5156 after input() to avoid that. Another solution is to avoid
5157 that further characters follow in the mapping, e.g., by using
5158 |:execute| or |:normal|.
5159
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005160 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005161 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
5162 :function GetFoo()
5163 : call inputsave()
5164 : let g:Foo = input("enter search pattern: ")
5165 : call inputrestore()
5166 :endfunction
5167
5168inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005169 Like |input()|, but when the GUI is running and text dialogs
5170 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005171 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005172 :let n = inputdialog("value for shiftwidth", shiftwidth())
5173 :if n != ""
5174 : let &sw = n
5175 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00005176< When the dialog is cancelled {cancelreturn} is returned. When
5177 omitted an empty string is returned.
5178 Hitting <Enter> works like pressing the OK button. Hitting
5179 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005180 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005181
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005182inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005183 {textlist} must be a |List| of strings. This |List| is
5184 displayed, one string per line. The user will be prompted to
5185 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005186 The user can also select an item by clicking on it with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005187 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005188 above the first item a negative number is returned. When
5189 clicking on the prompt one more than the length of {textlist}
5190 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005191 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02005192 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005193 the start of the string. And put a prompt in the first item.
5194 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005195 let color = inputlist(['Select color:', '1. red',
5196 \ '2. green', '3. blue'])
5197
Bram Moolenaar071d4272004-06-13 20:20:40 +00005198inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005199 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005200 Should be called the same number of times inputsave() is
5201 called. Calling it more often is harmless though.
5202 Returns 1 when there is nothing to restore, 0 otherwise.
5203
5204inputsave() *inputsave()*
5205 Preserve typeahead (also from mappings) and clear it, so that
5206 a following prompt gets input from the user. Should be
5207 followed by a matching inputrestore() after the prompt. Can
5208 be used several times, in which case there must be just as
5209 many inputrestore() calls.
5210 Returns 1 when out of memory, 0 otherwise.
5211
5212inputsecret({prompt} [, {text}]) *inputsecret()*
5213 This function acts much like the |input()| function with but
5214 two exceptions:
5215 a) the user's response will be displayed as a sequence of
5216 asterisks ("*") thereby keeping the entry secret, and
5217 b) the user's response will not be recorded on the input
5218 |history| stack.
5219 The result is a String, which is whatever the user actually
5220 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005221 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005222
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005223insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005224 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005225 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02005226 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005227 like omitting {idx}. A negative {idx} is also possible, see
5228 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005229 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005230 :let mylist = insert([2, 3, 5], 1)
5231 :call insert(mylist, 4, -1)
5232 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005233< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005234 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005235 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005236
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005237invert({expr}) *invert()*
5238 Bitwise invert. The argument is converted to a number. A
5239 List, Dict or Float argument causes an error. Example: >
5240 :let bits = invert(bits)
5241
Bram Moolenaar071d4272004-06-13 20:20:40 +00005242isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005243 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00005244 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005245 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005246 is any expression, which is used as a String.
5247
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005248islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005249 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005250 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005251 {expr} must be the name of a variable, |List| item or
5252 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005253 :let alist = [0, ['a', 'b'], 2, 3]
5254 :lockvar 1 alist
5255 :echo islocked('alist') " 1
5256 :echo islocked('alist[1]') " 0
5257
5258< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005259 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005260
Bram Moolenaarf3913272016-02-25 00:00:01 +01005261isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005262 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01005263 echo isnan(0.0 / 0.0)
5264< 1 ~
5265
5266 {only available when compiled with the |+float| feature}
5267
Bram Moolenaar677ee682005-01-27 14:41:15 +00005268items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005269 Return a |List| with all the key-value pairs of {dict}. Each
5270 |List| item is a list with two items: the key of a {dict}
5271 entry and the value of this entry. The |List| is in arbitrary
5272 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005273
Bram Moolenaar38a55632016-02-15 22:07:32 +01005274job_getchannel({job}) *job_getchannel()*
5275 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01005276 To check if the job has no channel: >
5277 if string(job_getchannel()) == 'channel fail'
5278<
Bram Moolenaar38a55632016-02-15 22:07:32 +01005279 {only available when compiled with the |+job| feature}
5280
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005281job_info({job}) *job_info()*
5282 Returns a Dictionary with information about {job}:
5283 "status" what |job_status()| returns
5284 "channel" what |job_getchannel()| returns
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02005285 "process" process ID
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02005286 "tty_in" terminal input name, empty when none
5287 "tty_out" terminal output name, empty when none
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005288 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01005289 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005290 "stoponexit" |job-stoponexit|
5291
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005292job_setoptions({job}, {options}) *job_setoptions()*
5293 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005294 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01005295 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005296
Bram Moolenaar38a55632016-02-15 22:07:32 +01005297job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005298 Start a job and return a Job object. Unlike |system()| and
5299 |:!cmd| this does not wait for the job to finish.
Bram Moolenaarc572da52017-08-27 16:52:01 +02005300 To start a job in a terminal window see |term_start()|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005301
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005302 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01005303 Unix it is split up in white-separated parts to be passed to
5304 execvp(). Arguments in double quotes can contain white space.
5305
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005306 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01005307 and further items are the arguments. All items are converted
5308 to String. This works best on Unix.
5309
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005310 On MS-Windows, job_start() makes a GUI application hidden. If
5311 want to show it, Use |:!start| instead.
5312
Bram Moolenaar835dc632016-02-07 14:27:38 +01005313 The command is executed directly, not through a shell, the
5314 'shell' option is not used. To use the shell: >
5315 let job = job_start(["/bin/sh", "-c", "echo hello"])
5316< Or: >
5317 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005318< Note that this will start two processes, the shell and the
5319 command it executes. If you don't want this use the "exec"
5320 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005321
5322 On Unix $PATH is used to search for the executable only when
5323 the command does not contain a slash.
5324
5325 The job will use the same terminal as Vim. If it reads from
5326 stdin the job and Vim will be fighting over input, that
5327 doesn't work. Redirect stdin and stdout to avoid problems: >
5328 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
5329<
5330 The returned Job object can be used to get the status with
5331 |job_status()| and stop the job with |job_stop()|.
5332
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005333 {options} must be a Dictionary. It can contain many optional
5334 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005335
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005336 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005337
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005338job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005339 Returns a String with the status of {job}:
5340 "run" job is running
5341 "fail" job failed to start
5342 "dead" job died or was stopped after running
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005343
Bram Moolenaar511972d2016-06-04 18:09:59 +02005344 On Unix a non-existing command results in "dead" instead of
5345 "fail", because a fork happens before the failure can be
5346 detected.
5347
Bram Moolenaar03413f42016-04-12 21:07:15 +02005348 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005349 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005350
Bram Moolenaar8950a562016-03-12 15:22:55 +01005351 For more information see |job_info()|.
5352
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005353 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005354
5355job_stop({job} [, {how}]) *job_stop()*
5356 Stop the {job}. This can also be used to signal the job.
5357
Bram Moolenaar923d9262016-02-25 20:56:01 +01005358 When {how} is omitted or is "term" the job will be terminated.
5359 For Unix SIGTERM is sent. On MS-Windows the job will be
5360 terminated forcedly (there is no "gentle" way).
5361 This goes to the process group, thus children may also be
5362 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005363
Bram Moolenaar923d9262016-02-25 20:56:01 +01005364 Effect for Unix:
5365 "term" SIGTERM (default)
5366 "hup" SIGHUP
5367 "quit" SIGQUIT
5368 "int" SIGINT
5369 "kill" SIGKILL (strongest way to stop)
5370 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01005371
Bram Moolenaar923d9262016-02-25 20:56:01 +01005372 Effect for MS-Windows:
5373 "term" terminate process forcedly (default)
5374 "hup" CTRL_BREAK
5375 "quit" CTRL_BREAK
5376 "int" CTRL_C
5377 "kill" terminate process forcedly
5378 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005379
5380 On Unix the signal is sent to the process group. This means
5381 that when the job is "sh -c command" it affects both the shell
5382 and the command.
5383
Bram Moolenaar835dc632016-02-07 14:27:38 +01005384 The result is a Number: 1 if the operation could be executed,
5385 0 if "how" is not supported on the system.
5386 Note that even when the operation was executed, whether the
5387 job was actually stopped needs to be checked with
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02005388 |job_status()|.
5389
5390 If the status of the job is "dead", the signal will not be
5391 sent. This is to avoid to stop the wrong job (esp. on Unix,
5392 where process numbers are recycled).
5393
5394 When using "kill" Vim will assume the job will die and close
5395 the channel.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005396
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005397 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005398
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005399join({list} [, {sep}]) *join()*
5400 Join the items in {list} together into one String.
5401 When {sep} is specified it is put in between the items. If
5402 {sep} is omitted a single space is used.
5403 Note that {sep} is not added at the end. You might want to
5404 add it there too: >
5405 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005406< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005407 converted into a string like with |string()|.
5408 The opposite function is |split()|.
5409
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005410js_decode({string}) *js_decode()*
5411 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005412 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01005413 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005414 - Empty items in an array (between two commas) are allowed and
5415 result in v:none items.
5416
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005417js_encode({expr}) *js_encode()*
5418 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005419 - Object key names are not in quotes.
5420 - v:none items in an array result in an empty item between
5421 commas.
5422 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005423 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005424 Will be encoded as:
5425 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005426 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005427 [1,null,{"one":1},null] ~
5428 This encoding is valid for JavaScript. It is more efficient
5429 than JSON, especially when using an array with optional items.
5430
5431
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005432json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01005433 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005434 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01005435 JSON and Vim values.
5436 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005437 - A trailing comma in an array and object is ignored, e.g.
5438 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaar705ada12016-01-24 17:56:50 +01005439 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005440 "1.0", or "001.2" for "1.2". Special floating point values
5441 "Infinity" and "NaN" (capitalization ignored) are accepted.
5442 - Leading zeroes in integer numbers are ignored, e.g. "012"
5443 for "12" or "-012" for "-12".
5444 - Capitalization is ignored in literal names null, true or
5445 false, e.g. "NULL" for "null", "True" for "true".
5446 - Control characters U+0000 through U+001F which are not
5447 escaped in strings are accepted, e.g. " " (tab
5448 character in string) for "\t".
5449 - Backslash in an invalid 2-character sequence escape is
5450 ignored, e.g. "\a" is decoded as "a".
5451 - A correct surrogate pair in JSON strings should normally be
5452 a 12 character sequence such as "\uD834\uDD1E", but
5453 json_decode() silently accepts truncated surrogate pairs
5454 such as "\uD834" or "\uD834\u"
5455 *E938*
5456 A duplicate key in an object, valid in rfc7159, is not
5457 accepted by json_decode() as the result must be a valid Vim
5458 type, e.g. this fails: {"a":"b", "a":"c"}
5459
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005460
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005461json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01005462 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005463 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01005464 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005465 Vim values are converted as follows:
5466 Number decimal number
5467 Float floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01005468 Float nan "NaN"
5469 Float inf "Infinity"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005470 String in double quotes (possibly null)
Bram Moolenaar705ada12016-01-24 17:56:50 +01005471 Funcref not possible, error
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005472 List as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02005473 used recursively: []
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005474 Dict as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02005475 used recursively: {}
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005476 v:false "false"
5477 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005478 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005479 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01005480 Note that NaN and Infinity are passed on as values. This is
5481 missing in the JSON standard, but several implementations do
5482 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005483
Bram Moolenaard8b02732005-01-14 21:48:43 +00005484keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005485 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00005486 arbitrary order.
5487
Bram Moolenaar13065c42005-01-08 16:08:21 +00005488 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005489len({expr}) The result is a Number, which is the length of the argument.
5490 When {expr} is a String or a Number the length in bytes is
5491 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005492 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005493 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005494 When {expr} is a |Dictionary| the number of entries in the
5495 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005496 Otherwise an error is given.
5497
Bram Moolenaar071d4272004-06-13 20:20:40 +00005498 *libcall()* *E364* *E368*
5499libcall({libname}, {funcname}, {argument})
5500 Call function {funcname} in the run-time library {libname}
5501 with single argument {argument}.
5502 This is useful to call functions in a library that you
5503 especially made to be used with Vim. Since only one argument
5504 is possible, calling standard library functions is rather
5505 limited.
5506 The result is the String returned by the function. If the
5507 function returns NULL, this will appear as an empty string ""
5508 to Vim.
5509 If the function returns a number, use libcallnr()!
5510 If {argument} is a number, it is passed to the function as an
5511 int; if {argument} is a string, it is passed as a
5512 null-terminated string.
5513 This function will fail in |restricted-mode|.
5514
5515 libcall() allows you to write your own 'plug-in' extensions to
5516 Vim without having to recompile the program. It is NOT a
5517 means to call system functions! If you try to do so Vim will
5518 very probably crash.
5519
5520 For Win32, the functions you write must be placed in a DLL
5521 and use the normal C calling convention (NOT Pascal which is
5522 used in Windows System DLLs). The function must take exactly
5523 one parameter, either a character pointer or a long integer,
5524 and must return a character pointer or NULL. The character
5525 pointer returned must point to memory that will remain valid
5526 after the function has returned (e.g. in static data in the
5527 DLL). If it points to allocated memory, that memory will
5528 leak away. Using a static buffer in the function should work,
5529 it's then freed when the DLL is unloaded.
5530
5531 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00005532 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00005533 because Vim thinks it's a pointer.
5534 For Win32 systems, {libname} should be the filename of the DLL
5535 without the ".DLL" suffix. A full path is only required if
5536 the DLL is not in the usual places.
5537 For Unix: When compiling your own plugins, remember that the
5538 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005539 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005540 feature is present}
5541 Examples: >
5542 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005543<
5544 *libcallnr()*
5545libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005546 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005547 int instead of a string.
5548 {only in Win32 on some Unix versions, when the |+libcall|
5549 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00005550 Examples: >
5551 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005552 :call libcallnr("libc.so", "printf", "Hello World!\n")
5553 :call libcallnr("libc.so", "sleep", 10)
5554<
5555 *line()*
5556line({expr}) The result is a Number, which is the line number of the file
5557 position given with {expr}. The accepted positions are:
5558 . the cursor position
5559 $ the last line in the current buffer
5560 'x position of mark x (if the mark is not set, 0 is
5561 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02005562 w0 first line visible in current window (one if the
5563 display isn't updated, e.g. in silent Ex mode)
5564 w$ last line visible in current window (this is one
5565 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00005566 v In Visual mode: the start of the Visual area (the
5567 cursor is the end). When not in Visual mode
5568 returns the cursor position. Differs from |'<| in
5569 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005570 Note that a mark in another file can be used. The line number
5571 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00005572 To get the column number use |col()|. To get both use
5573 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005574 Examples: >
5575 line(".") line number of the cursor
5576 line("'t") line number of mark t
5577 line("'" . marker) line number of mark marker
5578< *last-position-jump*
5579 This autocommand jumps to the last known position in a file
5580 just after opening it, if the '" mark is set: >
Bram Moolenaar3ec574f2017-06-13 18:12:01 +02005581 :au BufReadPost *
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005582 \ if line("'\"") > 1 && line("'\"") <= line("$") && &ft !~# 'commit'
Bram Moolenaarf8be4612017-06-23 20:52:40 +02005583 \ | exe "normal! g`\""
5584 \ | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00005585
Bram Moolenaar071d4272004-06-13 20:20:40 +00005586line2byte({lnum}) *line2byte()*
5587 Return the byte count from the start of the buffer for line
5588 {lnum}. This includes the end-of-line character, depending on
5589 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01005590 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005591 This can also be used to get the byte count for the line just
5592 below the last line: >
5593 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01005594< This is the buffer size plus one. If 'fileencoding' is empty
5595 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005596 When {lnum} is invalid, or the |+byte_offset| feature has been
5597 disabled at compile time, -1 is returned.
5598 Also see |byte2line()|, |go| and |:goto|.
5599
5600lispindent({lnum}) *lispindent()*
5601 Get the amount of indent for line {lnum} according the lisp
5602 indenting rules, as with 'lisp'.
5603 The indent is counted in spaces, the value of 'tabstop' is
5604 relevant. {lnum} is used just like in |getline()|.
5605 When {lnum} is invalid or Vim was not compiled the
5606 |+lispindent| feature, -1 is returned.
5607
5608localtime() *localtime()*
5609 Return the current time, measured as seconds since 1st Jan
5610 1970. See also |strftime()| and |getftime()|.
5611
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005612
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005613log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005614 Return the natural logarithm (base e) of {expr} as a |Float|.
5615 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005616 (0, inf].
5617 Examples: >
5618 :echo log(10)
5619< 2.302585 >
5620 :echo log(exp(5))
5621< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02005622 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005623
5624
Bram Moolenaar446cb832008-06-24 21:56:24 +00005625log10({expr}) *log10()*
5626 Return the logarithm of Float {expr} to base 10 as a |Float|.
5627 {expr} must evaluate to a |Float| or a |Number|.
5628 Examples: >
5629 :echo log10(1000)
5630< 3.0 >
5631 :echo log10(0.01)
5632< -2.0
5633 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005634
5635luaeval({expr} [, {expr}]) *luaeval()*
5636 Evaluate Lua expression {expr} and return its result converted
5637 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02005638 argument accessible as _A inside first {expr}.
5639 Strings are returned as they are.
5640 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005641 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02005642 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005643 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02005644 as-is.
5645 Other objects are returned as zero without any errors.
5646 See |lua-luaeval| for more details.
5647 {only available when compiled with the |+lua| feature}
5648
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005649map({expr1}, {expr2}) *map()*
5650 {expr1} must be a |List| or a |Dictionary|.
5651 Replace each item in {expr1} with the result of evaluating
5652 {expr2}. {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005653
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005654 If {expr2} is a |string|, inside {expr2} |v:val| has the value
5655 of the current item. For a |Dictionary| |v:key| has the key
5656 of the current item and for a |List| |v:key| has the index of
5657 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005658 Example: >
5659 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005660< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005661
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005662 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005663 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005664 |literal-string| to avoid having to double backslashes. You
5665 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005666
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005667 If {expr2} is a |Funcref| it is called with two arguments:
5668 1. The key or the index of the current item.
5669 2. the value of the current item.
5670 The function must return the new value of the item. Example
5671 that changes each value by "key-value": >
5672 func KeyValue(key, val)
5673 return a:key . '-' . a:val
5674 endfunc
5675 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02005676< It is shorter when using a |lambda|: >
5677 call map(myDict, {key, val -> key . '-' . val})
5678< If you do not use "val" you can leave it out: >
5679 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005680<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005681 The operation is done in-place. If you want a |List| or
5682 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02005683 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005684
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005685< Returns {expr1}, the |List| or |Dictionary| that was filtered.
5686 When an error is encountered while evaluating {expr2} no
5687 further items in {expr1} are processed. When {expr2} is a
5688 Funcref errors inside a function are ignored, unless it was
5689 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005690
5691
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005692maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02005693 When {dict} is omitted or zero: Return the rhs of mapping
5694 {name} in mode {mode}. The returned String has special
5695 characters translated like in the output of the ":map" command
5696 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005697
Bram Moolenaarbd743252010-10-20 21:23:33 +02005698 When there is no mapping for {name}, an empty String is
5699 returned.
5700
5701 The {name} can have special key names, like in the ":map"
5702 command.
5703
Bram Moolenaard12f5c12006-01-25 22:10:52 +00005704 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005705 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02005706 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005707 "o" Operator-pending
5708 "i" Insert
5709 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02005710 "s" Select
5711 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00005712 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02005713 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00005714 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00005715 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005716
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005717 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005718 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005719
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005720 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02005721 containing all the information of the mapping with the
5722 following items:
5723 "lhs" The {lhs} of the mapping.
5724 "rhs" The {rhs} of the mapping as typed.
5725 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02005726 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005727 "expr" 1 for an expression mapping (|:map-<expr>|).
5728 "buffer" 1 for a buffer local mapping (|:map-local|).
5729 "mode" Modes for which the mapping is defined. In
5730 addition to the modes mentioned above, these
5731 characters will be used:
5732 " " Normal, Visual and Operator-pending
5733 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01005734 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02005735 "sid" The script local ID, used for <sid> mappings
5736 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01005737 "nowait" Do not wait for other, longer mappings.
5738 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02005739
Bram Moolenaar071d4272004-06-13 20:20:40 +00005740 The mappings local to the current buffer are checked first,
5741 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00005742 This function can be used to map a key even when it's already
5743 mapped, and have it do the original mapping too. Sketch: >
5744 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
5745
Bram Moolenaar071d4272004-06-13 20:20:40 +00005746
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005747mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005748 Check if there is a mapping that matches with {name} in mode
5749 {mode}. See |maparg()| for {mode} and special names in
5750 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005751 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005752 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005753 A match happens with a mapping that starts with {name} and
5754 with a mapping which is equal to the start of {name}.
5755
Bram Moolenaar446cb832008-06-24 21:56:24 +00005756 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005757 mapcheck("a") yes yes yes
5758 mapcheck("abc") yes yes yes
5759 mapcheck("ax") yes no no
5760 mapcheck("b") no no no
5761
5762 The difference with maparg() is that mapcheck() finds a
5763 mapping that matches with {name}, while maparg() only finds a
5764 mapping for {name} exactly.
5765 When there is no mapping that starts with {name}, an empty
5766 String is returned. If there is one, the rhs of that mapping
5767 is returned. If there are several mappings that start with
5768 {name}, the rhs of one of them is returned.
5769 The mappings local to the current buffer are checked first,
5770 then the global mappings.
5771 This function can be used to check if a mapping can be added
5772 without being ambiguous. Example: >
5773 :if mapcheck("_vv") == ""
5774 : map _vv :set guifont=7x13<CR>
5775 :endif
5776< This avoids adding the "_vv" mapping when there already is a
5777 mapping for "_v" or for "_vvv".
5778
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005779match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005780 When {expr} is a |List| then this returns the index of the
5781 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005782 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar58b85342016-08-14 19:54:54 +02005783 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005784 Number, which gives the index (byte offset) in {expr} where
5785 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005786 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005787 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02005788 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005789 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005790 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005791 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005792< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005793 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02005794 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00005795 :let sepidx = match(line, '[.,;: \t]')
5796< *strcasestr()*
5797 Vim doesn't have a strcasestr() function. But you can add
5798 "\c" to the pattern to ignore case: >
5799 :let idx = match(haystack, '\cneedle')
5800<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005801 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005802 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005803 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005804 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005805 :echo match("testing", "ing", 2)
5806< result is again "4". >
5807 :echo match("testing", "ing", 4)
5808< result is again "4". >
5809 :echo match("testing", "t", 2)
5810< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005811 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00005812 {start} bytes later, thus "^" will match at {start}. Except
5813 when {count} is given, then it's like matches before the
5814 {start} byte are ignored (this is a bit complicated to keep it
5815 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005816 For a String, if {start} < 0, it will be set to 0. For a list
5817 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005818 If {start} is out of range ({start} > strlen({expr}) for a
5819 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005820
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005821 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005822 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005823 character further. Thus this example results in 1: >
5824 echo match("testing", "..", 0, 2)
5825< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00005826 Note that when {count} is added the way {start} works changes,
5827 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005828
Bram Moolenaar071d4272004-06-13 20:20:40 +00005829 See |pattern| for the patterns that are accepted.
5830 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02005831 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00005832 done like 'magic' is set and 'cpoptions' is empty.
5833
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005834 *matchadd()* *E798* *E799* *E801*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005835matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005836 Defines a pattern to be highlighted in the current window (a
5837 "match"). It will be highlighted with {group}. Returns an
5838 identification number (ID), which can be used to delete the
5839 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01005840 Matching is case sensitive and magic, unless case sensitivity
5841 or magicness are explicitly overridden in {pattern}. The
5842 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02005843 The "Conceal" value is special, it causes the match to be
5844 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005845
5846 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005847 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005848 highlighting overrule that of a match with a lower priority.
5849 A priority is specified as an integer (negative numbers are no
5850 exception). If the {priority} argument is not specified, the
5851 default priority is 10. The priority of 'hlsearch' is zero,
5852 hence all matches with a priority greater than zero will
5853 overrule it. Syntax highlighting (see 'syntax') is a separate
5854 mechanism, and regardless of the chosen priority a match will
5855 always overrule syntax highlighting.
5856
5857 The optional {id} argument allows the request for a specific
5858 match ID. If a specified ID is already taken, an error
5859 message will appear and the match will not be added. An ID
5860 is specified as a positive integer (zero excluded). IDs 1, 2
5861 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02005862 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005863 |matchadd()| automatically chooses a free ID.
5864
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005865 The optional {dict} argument allows for further custom
5866 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02005867 conceal character that will be shown for |hl-Conceal|
5868 highlighted matches. The dict can have the following members:
5869
5870 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005871 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02005872 matches, see |:syn-cchar|)
5873
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005874 The number of matches is not limited, as it is the case with
5875 the |:match| commands.
5876
5877 Example: >
5878 :highlight MyGroup ctermbg=green guibg=green
5879 :let m = matchadd("MyGroup", "TODO")
5880< Deletion of the pattern: >
5881 :call matchdelete(m)
5882
5883< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02005884 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005885 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005886
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02005887 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005888matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02005889 Same as |matchadd()|, but requires a list of positions {pos}
5890 instead of a pattern. This command is faster than |matchadd()|
5891 because it does not require to handle regular expressions and
5892 sets buffer line boundaries to redraw screen. It is supposed
5893 to be used when fast match additions and deletions are
5894 required, for example to highlight matching parentheses.
5895
5896 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005897 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02005898 line has number 1.
5899 - A list with one number, e.g., [23]. The whole line with this
5900 number will be highlighted.
5901 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005902 the line number, the second one is the column number (first
5903 column is 1, the value must correspond to the byte index as
5904 |col()| would return). The character at this position will
5905 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005906 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005907 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005908
Bram Moolenaarb3414592014-06-17 17:48:32 +02005909 The maximum number of positions is 8.
5910
5911 Example: >
5912 :highlight MyGroup ctermbg=green guibg=green
5913 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5914< Deletion of the pattern: >
5915 :call matchdelete(m)
5916
5917< Matches added by |matchaddpos()| are returned by
5918 |getmatches()| with an entry "pos1", "pos2", etc., with the
5919 value a list like the {pos} item.
5920 These matches cannot be set via |setmatches()|, however they
5921 can still be deleted by |clearmatches()|.
5922
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005923matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005924 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005925 |:2match| or |:3match| command.
5926 Return a |List| with two elements:
5927 The name of the highlight group used
5928 The pattern used.
5929 When {nr} is not 1, 2 or 3 returns an empty |List|.
5930 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005931 This is useful to save and restore a |:match|.
5932 Highlighting matches using the |:match| commands are limited
5933 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005934
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005935matchdelete({id}) *matchdelete()* *E802* *E803*
5936 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00005937 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005938 otherwise -1. See example for |matchadd()|. All matches can
5939 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005940
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005941matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005942 Same as |match()|, but return the index of first character
5943 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005944 :echo matchend("testing", "ing")
5945< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00005946 *strspn()* *strcspn()*
5947 Vim doesn't have a strspn() or strcspn() function, but you can
5948 do it with matchend(): >
5949 :let span = matchend(line, '[a-zA-Z]')
5950 :let span = matchend(line, '[^a-zA-Z]')
5951< Except that -1 is returned when there are no matches.
5952
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005953 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005954 :echo matchend("testing", "ing", 2)
5955< results in "7". >
5956 :echo matchend("testing", "ing", 5)
5957< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005958 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005959
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005960matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005961 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005962 list is the matched string, same as what matchstr() would
5963 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005964 in |:substitute|. When an optional submatch didn't match an
5965 empty string is used. Example: >
5966 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5967< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005968 When there is no match an empty list is returned.
5969
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005970matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005971 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005972 :echo matchstr("testing", "ing")
5973< results in "ing".
5974 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005975 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005976 :echo matchstr("testing", "ing", 2)
5977< results in "ing". >
5978 :echo matchstr("testing", "ing", 5)
5979< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005980 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005981 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005982
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005983matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02005984 Same as |matchstr()|, but return the matched string, the start
5985 position and the end position of the match. Example: >
5986 :echo matchstrpos("testing", "ing")
5987< results in ["ing", 4, 7].
5988 When there is no match ["", -1, -1] is returned.
5989 The {start}, if given, has the same meaning as for |match()|. >
5990 :echo matchstrpos("testing", "ing", 2)
5991< results in ["ing", 4, 7]. >
5992 :echo matchstrpos("testing", "ing", 5)
5993< result is ["", -1, -1].
5994 When {expr} is a |List| then the matching item, the index
5995 of first item where {pat} matches, the start position and the
5996 end position of the match are returned. >
5997 :echo matchstrpos([1, '__x'], '\a')
5998< result is ["x", 1, 2, 3].
5999 The type isn't changed, it's not necessarily a String.
6000
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006001 *max()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006002max({expr}) Return the maximum value of all items in {expr}.
6003 {expr} can be a list or a dictionary. For a dictionary,
6004 it returns the maximum of all values in the dictionary.
6005 If {expr} is neither a list nor a dictionary, or one of the
6006 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006007 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006008
6009 *min()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006010min({expr}) Return the minimum value of all items in {expr}.
6011 {expr} can be a list or a dictionary. For a dictionary,
6012 it returns the minimum of all values in the dictionary.
6013 If {expr} is neither a list nor a dictionary, or one of the
6014 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006015 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006016
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006017 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006018mkdir({name} [, {path} [, {prot}]])
6019 Create directory {name}.
6020 If {path} is "p" then intermediate directories are created as
6021 necessary. Otherwise it must be "".
6022 If {prot} is given it is used to set the protection bits of
6023 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar58b85342016-08-14 19:54:54 +02006024 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006025 for others. This is only used for the last part of {name}.
6026 Thus if you create /tmp/foo/bar then /tmp/foo will be created
6027 with 0755.
6028 Example: >
6029 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
6030< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006031 Not available on all systems. To check use: >
6032 :if exists("*mkdir")
6033<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006034 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006035mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006036 If [expr] is supplied and it evaluates to a non-zero Number or
6037 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006038 returned, otherwise only the first letter is returned.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006039
Bram Moolenaarc572da52017-08-27 16:52:01 +02006040 n Normal, Terminal-Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00006041 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00006042 v Visual by character
6043 V Visual by line
6044 CTRL-V Visual blockwise
6045 s Select by character
6046 S Select by line
6047 CTRL-S Select blockwise
6048 i Insert
Bram Moolenaare90858d2017-02-01 17:24:34 +01006049 ic Insert mode completion |compl-generic|
6050 ix Insert mode |i_CTRL-X| completion
Bram Moolenaar446cb832008-06-24 21:56:24 +00006051 R Replace |R|
Bram Moolenaare90858d2017-02-01 17:24:34 +01006052 Rc Replace mode completion |compl-generic|
Bram Moolenaar446cb832008-06-24 21:56:24 +00006053 Rv Virtual Replace |gR|
Bram Moolenaare90858d2017-02-01 17:24:34 +01006054 Rx Replace mode |i_CTRL-X| completion
6055 c Command-line editing
Bram Moolenaar446cb832008-06-24 21:56:24 +00006056 cv Vim Ex mode |gQ|
6057 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006058 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00006059 rm The -- more -- prompt
6060 r? A |:confirm| query of some sort
6061 ! Shell or external command is executing
Bram Moolenaarc572da52017-08-27 16:52:01 +02006062 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00006063 This is useful in the 'statusline' option or when used
6064 with |remote_expr()| In most other places it always returns
6065 "c" or "n".
6066 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006067
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006068mzeval({expr}) *mzeval()*
6069 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02006070 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006071 Numbers and strings are returned as they are.
6072 Pairs (including lists and improper lists) and vectors are
6073 returned as Vim |Lists|.
6074 Hash tables are represented as Vim |Dictionary| type with keys
6075 converted to strings.
6076 All other types are converted to string with display function.
6077 Examples: >
6078 :mz (define l (list 1 2 3))
6079 :mz (define h (make-hash)) (hash-set! h "list" l)
6080 :echo mzeval("l")
6081 :echo mzeval("h")
6082<
6083 {only available when compiled with the |+mzscheme| feature}
6084
Bram Moolenaar071d4272004-06-13 20:20:40 +00006085nextnonblank({lnum}) *nextnonblank()*
6086 Return the line number of the first line at or below {lnum}
6087 that is not blank. Example: >
6088 if getline(nextnonblank(1)) =~ "Java"
6089< When {lnum} is invalid or there is no non-blank line at or
6090 below it, zero is returned.
6091 See also |prevnonblank()|.
6092
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006093nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006094 Return a string with a single character, which has the number
6095 value {expr}. Examples: >
6096 nr2char(64) returns "@"
6097 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01006098< When {utf8} is omitted or zero, the current 'encoding' is used.
6099 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006100 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01006101< With {utf8} set to 1, always return utf-8 characters.
6102 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006103 nr2char(10), because NULs are represented with newline
6104 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006105 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006106
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006107or({expr}, {expr}) *or()*
6108 Bitwise OR on the two arguments. The arguments are converted
6109 to a number. A List, Dict or Float argument causes an error.
6110 Example: >
6111 :let bits = or(bits, 0x80)
6112
6113
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006114pathshorten({expr}) *pathshorten()*
6115 Shorten directory names in the path {expr} and return the
6116 result. The tail, the file name, is kept as-is. The other
6117 components in the path are reduced to single letters. Leading
6118 '~' and '.' characters are kept. Example: >
6119 :echo pathshorten('~/.vim/autoload/myfile.vim')
6120< ~/.v/a/myfile.vim ~
6121 It doesn't matter if the path exists or not.
6122
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006123perleval({expr}) *perleval()*
6124 Evaluate Perl expression {expr} in scalar context and return
6125 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006126 converted, it is returned as a string Perl representation.
6127 Note: If you want an array or hash, {expr} must return a
6128 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006129 Example: >
6130 :echo perleval('[1 .. 4]')
6131< [1, 2, 3, 4]
6132 {only available when compiled with the |+perl| feature}
6133
Bram Moolenaar446cb832008-06-24 21:56:24 +00006134pow({x}, {y}) *pow()*
6135 Return the power of {x} to the exponent {y} as a |Float|.
6136 {x} and {y} must evaluate to a |Float| or a |Number|.
6137 Examples: >
6138 :echo pow(3, 3)
6139< 27.0 >
6140 :echo pow(2, 16)
6141< 65536.0 >
6142 :echo pow(32, 0.20)
6143< 2.0
6144 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006145
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006146prevnonblank({lnum}) *prevnonblank()*
6147 Return the line number of the first line at or above {lnum}
6148 that is not blank. Example: >
6149 let ind = indent(prevnonblank(v:lnum - 1))
6150< When {lnum} is invalid or there is no non-blank line at or
6151 above it, zero is returned.
6152 Also see |nextnonblank()|.
6153
6154
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006155printf({fmt}, {expr1} ...) *printf()*
6156 Return a String with {fmt}, where "%" items are replaced by
6157 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006158 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006159< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006160 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006161
6162 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006163 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006164 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00006165 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006166 %.9s string truncated to 9 bytes
6167 %c single byte
6168 %d decimal number
6169 %5d decimal number padded with spaces to 5 characters
6170 %x hex number
6171 %04x hex number padded with zeros to at least 4 characters
6172 %X hex number using upper case letters
6173 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02006174 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02006175 %f floating point number as 12.23, inf, -inf or nan
6176 %F floating point number as 12.23, INF, -INF or NAN
6177 %e floating point number as 1.23e3, inf, -inf or nan
6178 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00006179 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01006180 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00006181 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006182
6183 Conversion specifications start with '%' and end with the
6184 conversion type. All other characters are copied unchanged to
6185 the result.
6186
6187 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006188 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006189
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006190 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006191
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006192 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006193 Zero or more of the following flags:
6194
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006195 # The value should be converted to an "alternate
6196 form". For c, d, and s conversions, this option
6197 has no effect. For o conversions, the precision
6198 of the number is increased to force the first
6199 character of the output string to a zero (except
6200 if a zero value is printed with an explicit
6201 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02006202 For b and B conversions, a non-zero result has
6203 the string "0b" (or "0B" for B conversions)
6204 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006205 For x and X conversions, a non-zero result has
6206 the string "0x" (or "0X" for X conversions)
6207 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006208
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006209 0 (zero) Zero padding. For all conversions the converted
6210 value is padded on the left with zeros rather
6211 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02006212 numeric conversion (d, b, B, o, x, and X), the 0
6213 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006214
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006215 - A negative field width flag; the converted value
6216 is to be left adjusted on the field boundary.
6217 The converted value is padded on the right with
6218 blanks, rather than on the left with blanks or
6219 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006220
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006221 ' ' (space) A blank should be left before a positive
6222 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006223
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006224 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02006225 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006226 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006227
6228 field-width
6229 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00006230 field width. If the converted value has fewer bytes
6231 than the field width, it will be padded with spaces on
6232 the left (or right, if the left-adjustment flag has
6233 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006234
6235 .precision
6236 An optional precision, in the form of a period '.'
6237 followed by an optional digit string. If the digit
6238 string is omitted, the precision is taken as zero.
6239 This gives the minimum number of digits to appear for
6240 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00006241 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006242 For floating point it is the number of digits after
6243 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006244
6245 type
6246 A character that specifies the type of conversion to
6247 be applied, see below.
6248
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006249 A field width or precision, or both, may be indicated by an
6250 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02006251 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006252 negative field width is treated as a left adjustment flag
6253 followed by a positive field width; a negative precision is
6254 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006255 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006256< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006257 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006258
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006259 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006260
Bram Moolenaar91984b92016-08-16 21:58:41 +02006261 *printf-d* *printf-b* *printf-B* *printf-o*
6262 *printf-x* *printf-X*
6263 dbBoxX The Number argument is converted to signed decimal
6264 (d), unsigned binary (b and B), unsigned octal (o), or
6265 unsigned hexadecimal (x and X) notation. The letters
6266 "abcdef" are used for x conversions; the letters
6267 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006268 The precision, if any, gives the minimum number of
6269 digits that must appear; if the converted value
6270 requires fewer digits, it is padded on the left with
6271 zeros.
6272 In no case does a non-existent or small field width
6273 cause truncation of a numeric field; if the result of
6274 a conversion is wider than the field width, the field
6275 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02006276 The 'h' modifier indicates the argument is 16 bits.
6277 The 'l' modifier indicates the argument is 32 bits.
6278 The 'L' modifier indicates the argument is 64 bits.
6279 Generally, these modifiers are not useful. They are
6280 ignored when type is known from the argument.
6281
6282 i alias for d
6283 D alias for ld
6284 U alias for lu
6285 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006286
Bram Moolenaar446cb832008-06-24 21:56:24 +00006287 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006288 c The Number argument is converted to a byte, and the
6289 resulting character is written.
6290
Bram Moolenaar446cb832008-06-24 21:56:24 +00006291 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006292 s The text of the String argument is used. If a
6293 precision is specified, no more bytes than the number
6294 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02006295 If the argument is not a String type, it is
6296 automatically converted to text with the same format
6297 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01006298 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006299 S The text of the String argument is used. If a
6300 precision is specified, no more display cells than the
6301 number specified are used. Without the |+multi_byte|
6302 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006303
Bram Moolenaar446cb832008-06-24 21:56:24 +00006304 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006305 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006306 form 123.456. The precision specifies the number of
6307 digits after the decimal point. When the precision is
6308 zero the decimal point is omitted. When the precision
6309 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02006310 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006311 or "-inf" with %f (INF or -INF with %F).
6312 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006313 Example: >
6314 echo printf("%.2f", 12.115)
6315< 12.12
6316 Note that roundoff depends on the system libraries.
6317 Use |round()| when in doubt.
6318
6319 *printf-e* *printf-E*
6320 e E The Float argument is converted into a string of the
6321 form 1.234e+03 or 1.234E+03 when using 'E'. The
6322 precision specifies the number of digits after the
6323 decimal point, like with 'f'.
6324
6325 *printf-g* *printf-G*
6326 g G The Float argument is converted like with 'f' if the
6327 value is between 0.001 (inclusive) and 10000000.0
6328 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6329 for 'G'. When no precision is specified superfluous
6330 zeroes and '+' signs are removed, except for the zero
6331 immediately after the decimal point. Thus 10000000.0
6332 results in 1.0e7.
6333
6334 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006335 % A '%' is written. No argument is converted. The
6336 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006337
Bram Moolenaarc236c162008-07-13 17:41:49 +00006338 When a Number argument is expected a String argument is also
6339 accepted and automatically converted.
6340 When a Float or String argument is expected a Number argument
6341 is also accepted and automatically converted.
6342 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006343
Bram Moolenaar83bab712005-08-01 21:58:57 +00006344 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006345 The number of {exprN} arguments must exactly match the number
6346 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006347 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006348
6349
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006350pumvisible() *pumvisible()*
6351 Returns non-zero when the popup menu is visible, zero
6352 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006353 This can be used to avoid some things that would remove the
6354 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006355
Bram Moolenaar30b65812012-07-12 22:01:11 +02006356py3eval({expr}) *py3eval()*
6357 Evaluate Python expression {expr} and return its result
6358 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006359 Numbers and strings are returned as they are (strings are
6360 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02006361 'encoding').
6362 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006363 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02006364 keys converted to strings.
6365 {only available when compiled with the |+python3| feature}
6366
6367 *E858* *E859*
6368pyeval({expr}) *pyeval()*
6369 Evaluate Python expression {expr} and return its result
6370 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006371 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02006372 copied though).
6373 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006374 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02006375 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02006376 {only available when compiled with the |+python| feature}
6377
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01006378pyxeval({expr}) *pyxeval()*
6379 Evaluate Python expression {expr} and return its result
6380 converted to Vim data structures.
6381 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
6382 See also: |pyeval()|, |py3eval()|
6383 {only available when compiled with the |+python| or the
6384 |+python3| feature}
6385
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006386 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00006387range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006388 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00006389 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
6390 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
6391 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
6392 {max}] (increasing {expr} with {stride} each time, not
6393 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00006394 When the maximum is one before the start the result is an
6395 empty list. When the maximum is more than one before the
6396 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00006397 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006398 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00006399 range(2, 4) " [2, 3, 4]
6400 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006401 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00006402 range(0) " []
6403 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00006404<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006405 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006406readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006407 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02006408 as an item. Lines are broken at NL characters. Macintosh
6409 files separated with CR will result in a single long line
6410 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02006411 All NUL characters are replaced with a NL character.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006412 When {binary} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006413 - When the last line ends in a NL an extra empty list item is
6414 added.
6415 - No CR characters are removed.
6416 Otherwise:
6417 - CR characters that appear before a NL are removed.
6418 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02006419 - When 'encoding' is Unicode any UTF-8 byte order mark is
6420 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006421 When {max} is given this specifies the maximum number of lines
6422 to be read. Useful if you only want to check the first ten
6423 lines of a file: >
6424 :for line in readfile(fname, '', 10)
6425 : if line =~ 'Date' | echo line | endif
6426 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00006427< When {max} is negative -{max} lines from the end of the file
6428 are returned, or as many as there are.
6429 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006430 Note that without {max} the whole file is read into memory.
6431 Also note that there is no recognition of encoding. Read a
6432 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006433 When the file can't be opened an error message is given and
6434 the result is an empty list.
6435 Also see |writefile()|.
6436
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006437reltime([{start} [, {end}]]) *reltime()*
6438 Return an item that represents a time value. The format of
6439 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02006440 |reltimestr()| to convert it to a string or |reltimefloat()|
6441 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006442 Without an argument it returns the current time.
6443 With one argument is returns the time passed since the time
6444 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006445 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006446 and {end}.
6447 The {start} and {end} arguments must be values returned by
6448 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02006449 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006450
Bram Moolenaar03413f42016-04-12 21:07:15 +02006451reltimefloat({time}) *reltimefloat()*
6452 Return a Float that represents the time value of {time}.
6453 Example: >
6454 let start = reltime()
6455 call MyFunction()
6456 let seconds = reltimefloat(reltime(start))
6457< See the note of reltimestr() about overhead.
6458 Also see |profiling|.
6459 {only available when compiled with the |+reltime| feature}
6460
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006461reltimestr({time}) *reltimestr()*
6462 Return a String that represents the time value of {time}.
6463 This is the number of seconds, a dot and the number of
6464 microseconds. Example: >
6465 let start = reltime()
6466 call MyFunction()
6467 echo reltimestr(reltime(start))
6468< Note that overhead for the commands will be added to the time.
6469 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006470 Leading spaces are used to make the string align nicely. You
6471 can use split() to remove it. >
6472 echo split(reltimestr(reltime(start)))[0]
6473< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02006474 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006475
Bram Moolenaar071d4272004-06-13 20:20:40 +00006476 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01006477remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02006478 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006479 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006480 The result must be a String or a |List|. A |List| is turned
6481 into a String by joining the items with a line break in
6482 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01006483 If {idvar} is present and not empty, it is taken as the name
6484 of a variable and a {serverid} for later use with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006485 remote_read() is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01006486 If {timeout} is given the read times out after this many
6487 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006488 See also |clientserver| |RemoteReply|.
6489 This function is not available in the |sandbox|.
6490 {only available when compiled with the |+clientserver| feature}
6491 Note: Any errors will cause a local error message to be issued
6492 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01006493
6494 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006495 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01006496 when in debug mode, then local function variables and
6497 arguments can be evaluated.
6498
Bram Moolenaar071d4272004-06-13 20:20:40 +00006499 Examples: >
6500 :echo remote_expr("gvim", "2+2")
6501 :echo remote_expr("gvim1", "b:current_syntax")
6502<
6503
6504remote_foreground({server}) *remote_foreground()*
6505 Move the Vim server with the name {server} to the foreground.
6506 This works like: >
6507 remote_expr({server}, "foreground()")
6508< Except that on Win32 systems the client does the work, to work
6509 around the problem that the OS doesn't always allow the server
6510 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00006511 Note: This does not restore the window if it was minimized,
6512 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006513 This function is not available in the |sandbox|.
6514 {only in the Win32, Athena, Motif and GTK GUI versions and the
6515 Win32 console version}
6516
6517
6518remote_peek({serverid} [, {retvar}]) *remote_peek()*
6519 Returns a positive number if there are available strings
6520 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02006521 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006522 name of a variable.
6523 Returns zero if none are available.
6524 Returns -1 if something is wrong.
6525 See also |clientserver|.
6526 This function is not available in the |sandbox|.
6527 {only available when compiled with the |+clientserver| feature}
6528 Examples: >
6529 :let repl = ""
6530 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
6531
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01006532remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006533 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01006534 it. Unless a {timeout} in seconds is given, it blocks until a
6535 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006536 See also |clientserver|.
6537 This function is not available in the |sandbox|.
6538 {only available when compiled with the |+clientserver| feature}
6539 Example: >
6540 :echo remote_read(id)
6541<
6542 *remote_send()* *E241*
6543remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02006544 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00006545 keys and the function returns immediately. At the Vim server
6546 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006547 If {idvar} is present, it is taken as the name of a variable
6548 and a {serverid} for later use with remote_read() is stored
6549 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006550 See also |clientserver| |RemoteReply|.
6551 This function is not available in the |sandbox|.
6552 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01006553
Bram Moolenaar071d4272004-06-13 20:20:40 +00006554 Note: Any errors will be reported in the server and may mess
6555 up the display.
6556 Examples: >
6557 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
6558 \ remote_read(serverid)
6559
6560 :autocmd NONE RemoteReply *
6561 \ echo remote_read(expand("<amatch>"))
6562 :echo remote_send("gvim", ":sleep 10 | echo ".
6563 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006564<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01006565 *remote_startserver()* *E941* *E942*
6566remote_startserver({name})
6567 Become the server {name}. This fails if already running as a
6568 server, when |v:servername| is not empty.
6569 {only available when compiled with the |+clientserver| feature}
6570
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006571remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006572 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006573 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006574 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006575 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006576 item as {end} a list with one item is returned. When {end}
6577 points to an item before {idx} this is an error.
6578 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006579 Example: >
6580 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006581 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00006582remove({dict}, {key})
6583 Remove the entry from {dict} with key {key}. Example: >
6584 :echo "removed " . remove(dict, "one")
6585< If there is no {key} in {dict} this is an error.
6586
6587 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006588
Bram Moolenaar071d4272004-06-13 20:20:40 +00006589rename({from}, {to}) *rename()*
6590 Rename the file by the name {from} to the name {to}. This
6591 should also work to move files across file systems. The
6592 result is a Number, which is 0 if the file was renamed
6593 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00006594 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006595 This function is not available in the |sandbox|.
6596
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00006597repeat({expr}, {count}) *repeat()*
6598 Repeat {expr} {count} times and return the concatenated
6599 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006600 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00006601< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006602 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02006603 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006604 :let longlist = repeat(['a', 'b'], 3)
6605< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00006606
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006607
Bram Moolenaar071d4272004-06-13 20:20:40 +00006608resolve({filename}) *resolve()* *E655*
6609 On MS-Windows, when {filename} is a shortcut (a .lnk file),
6610 returns the path the shortcut points to in a simplified form.
6611 On Unix, repeat resolving symbolic links in all path
6612 components of {filename} and return the simplified result.
6613 To cope with link cycles, resolving of symbolic links is
6614 stopped after 100 iterations.
6615 On other systems, return the simplified {filename}.
6616 The simplification step is done as by |simplify()|.
6617 resolve() keeps a leading path component specifying the
6618 current directory (provided the result is still a relative
6619 path name) and also keeps a trailing path separator.
6620
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006621 *reverse()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02006622reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006623 {list}.
6624 If you want a list to remain unmodified make a copy first: >
6625 :let revlist = reverse(copy(mylist))
6626
Bram Moolenaar446cb832008-06-24 21:56:24 +00006627round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00006628 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00006629 as a |Float|. If {expr} lies halfway between two integral
6630 values, then use the larger one (away from zero).
6631 {expr} must evaluate to a |Float| or a |Number|.
6632 Examples: >
6633 echo round(0.456)
6634< 0.0 >
6635 echo round(4.5)
6636< 5.0 >
6637 echo round(-4.5)
6638< -5.0
6639 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01006640
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006641screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02006642 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02006643 arbitrary number that can only be used to compare to the
6644 attribute at other positions.
6645
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006646screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02006647 The result is a Number, which is the character at position
6648 [row, col] on the screen. This works for every possible
6649 screen position, also status lines, window separators and the
6650 command line. The top left position is row one, column one
6651 The character excludes composing characters. For double-byte
6652 encodings it may only be the first byte.
6653 This is mainly to be used for testing.
6654 Returns -1 when row or col is out of range.
6655
Bram Moolenaar34feacb2012-12-05 19:01:43 +01006656screencol() *screencol()*
6657 The result is a Number, which is the current screen column of
6658 the cursor. The leftmost column has number 1.
6659 This function is mainly used for testing.
6660
6661 Note: Always returns the current screen column, thus if used
6662 in a command (e.g. ":echo screencol()") it will return the
6663 column inside the command line, which is 1 when the command is
6664 executed. To get the cursor position in the file use one of
6665 the following mappings: >
6666 nnoremap <expr> GG ":echom ".screencol()."\n"
6667 nnoremap <silent> GG :echom screencol()<CR>
6668<
6669screenrow() *screenrow()*
6670 The result is a Number, which is the current screen row of the
6671 cursor. The top line has number one.
6672 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02006673 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01006674
6675 Note: Same restrictions as with |screencol()|.
6676
Bram Moolenaar76929292008-01-06 19:07:36 +00006677search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006678 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006679 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006680
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006681 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006682 If there is no match a 0 is returned and the cursor doesn't
6683 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006684
Bram Moolenaar071d4272004-06-13 20:20:40 +00006685 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006686 'b' search Backward instead of forward
6687 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006688 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006689 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006690 'p' return number of matching sub-Pattern (see below)
6691 's' Set the ' mark at the previous location of the cursor
6692 'w' Wrap around the end of the file
6693 'W' don't Wrap around the end of the file
6694 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00006695 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
6696
Bram Moolenaar02743632005-07-25 20:42:36 +00006697 If the 's' flag is supplied, the ' mark is set, only if the
6698 cursor is moved. The 's' flag cannot be combined with the 'n'
6699 flag.
6700
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006701 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006702
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006703 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006704 column zero and then matches before the cursor are skipped.
6705 When the 'c' flag is present in 'cpo' the next search starts
6706 after the match. Without the 'c' flag the next search starts
6707 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006708
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006709 When the {stopline} argument is given then the search stops
6710 after searching this line. This is useful to restrict the
6711 search to a range of lines. Examples: >
6712 let match = search('(', 'b', line("w0"))
6713 let end = search('END', '', line("w$"))
6714< When {stopline} is used and it is not zero this also implies
6715 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00006716 A zero value is equal to not giving the argument.
6717
6718 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02006719 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00006720 {timeout} is 500 the search stops after half a second.
6721 The value must not be negative. A zero value is like not
6722 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02006723 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006724
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006725 *search()-sub-match*
6726 With the 'p' flag the returned value is one more than the
6727 first sub-match in \(\). One if none of them matched but the
6728 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006729 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006730
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006731 The cursor will be positioned at the match, unless the 'n'
6732 flag is used.
6733
Bram Moolenaar071d4272004-06-13 20:20:40 +00006734 Example (goes over all files in the argument list): >
6735 :let n = 1
6736 :while n <= argc() " loop over all files in arglist
6737 : exe "argument " . n
6738 : " start at the last char in the file and wrap for the
6739 : " first search to find match at start of file
6740 : normal G$
6741 : let flags = "w"
6742 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00006743 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00006744 : let flags = "W"
6745 : endwhile
6746 : update " write the file if modified
6747 : let n = n + 1
6748 :endwhile
6749<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006750 Example for using some flags: >
6751 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
6752< This will search for the keywords "if", "else", and "endif"
6753 under or after the cursor. Because of the 'p' flag, it
6754 returns 1, 2, or 3 depending on which keyword is found, or 0
6755 if the search fails. With the cursor on the first word of the
6756 line:
6757 if (foo == 0) | let foo = foo + 1 | endif ~
6758 the function returns 1. Without the 'c' flag, the function
6759 finds the "endif" and returns 3. The same thing happens
6760 without the 'e' flag if the cursor is on the "f" of "if".
6761 The 'n' flag tells the function not to move the cursor.
6762
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006763
Bram Moolenaarf75a9632005-09-13 21:20:47 +00006764searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
6765 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006766
Bram Moolenaarf75a9632005-09-13 21:20:47 +00006767 With a non-zero {global} argument it works like |gD|, find
6768 first match in the file. Otherwise it works like |gd|, find
6769 first match in the function.
6770
6771 With a non-zero {thisblock} argument matches in a {} block
6772 that ends before the cursor position are ignored. Avoids
6773 finding variable declarations only valid in another scope.
6774
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006775 Moves the cursor to the found match.
6776 Returns zero for success, non-zero for failure.
6777 Example: >
6778 if searchdecl('myvar') == 0
6779 echo getline('.')
6780 endif
6781<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006782 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006783searchpair({start}, {middle}, {end} [, {flags} [, {skip}
6784 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006785 Search for the match of a nested start-end pair. This can be
6786 used to find the "endif" that matches an "if", while other
6787 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006788 The search starts at the cursor. The default is to search
6789 forward, include 'b' in {flags} to search backward.
6790 If a match is found, the cursor is positioned at it and the
6791 line number is returned. If no match is found 0 or -1 is
6792 returned and the cursor doesn't move. No error message is
6793 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006794
6795 {start}, {middle} and {end} are patterns, see |pattern|. They
6796 must not contain \( \) pairs. Use of \%( \) is allowed. When
6797 {middle} is not empty, it is found when searching from either
6798 direction, but only when not in a nested start-end pair. A
6799 typical use is: >
6800 searchpair('\<if\>', '\<else\>', '\<endif\>')
6801< By leaving {middle} empty the "else" is skipped.
6802
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006803 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
6804 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006805 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006806 outer pair. Implies the 'W' flag.
6807 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006808 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006809 Note: it's nearly always a good idea to use the 'W' flag, to
6810 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006811
6812 When a match for {start}, {middle} or {end} is found, the
6813 {skip} expression is evaluated with the cursor positioned on
6814 the start of the match. It should return non-zero if this
6815 match is to be skipped. E.g., because it is inside a comment
6816 or a string.
6817 When {skip} is omitted or empty, every match is accepted.
6818 When evaluating {skip} causes an error the search is aborted
6819 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01006820 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006821
Bram Moolenaar76929292008-01-06 19:07:36 +00006822 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006823
Bram Moolenaar071d4272004-06-13 20:20:40 +00006824 The value of 'ignorecase' is used. 'magic' is ignored, the
6825 patterns are used like it's on.
6826
6827 The search starts exactly at the cursor. A match with
6828 {start}, {middle} or {end} at the next character, in the
6829 direction of searching, is the first one found. Example: >
6830 if 1
6831 if 2
6832 endif 2
6833 endif 1
6834< When starting at the "if 2", with the cursor on the "i", and
6835 searching forwards, the "endif 2" is found. When starting on
6836 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02006837 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006838 then this is considered to be a nested if/endif from "if 2" to
6839 "endif 2".
6840 When searching backwards and {end} is more than one character,
6841 it may be useful to put "\zs" at the end of the pattern, so
6842 that when the cursor is inside a match with the end it finds
6843 the matching start.
6844
6845 Example, to find the "endif" command in a Vim script: >
6846
6847 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
6848 \ 'getline(".") =~ "^\\s*\""')
6849
6850< The cursor must be at or after the "if" for which a match is
6851 to be found. Note that single-quote strings are used to avoid
6852 having to double the backslashes. The skip expression only
6853 catches comments at the start of a line, not after a command.
6854 Also, a word "en" or "if" halfway a line is considered a
6855 match.
6856 Another example, to search for the matching "{" of a "}": >
6857
6858 :echo searchpair('{', '', '}', 'bW')
6859
6860< This works when the cursor is at or before the "}" for which a
6861 match is to be found. To reject matches that syntax
6862 highlighting recognized as strings: >
6863
6864 :echo searchpair('{', '', '}', 'bW',
6865 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
6866<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006867 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006868searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
6869 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006870 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006871 column position of the match. The first element of the |List|
6872 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006873 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006874 returns [0, 0]. >
6875
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006876 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
6877<
6878 See |match-parens| for a bigger and more useful example.
6879
Bram Moolenaar76929292008-01-06 19:07:36 +00006880searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006881 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006882 column position of the match. The first element of the |List|
6883 is the line number and the second element is the byte index of
6884 the column position of the match. If no match is found,
6885 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006886 Example: >
6887 :let [lnum, col] = searchpos('mypattern', 'n')
6888
6889< When the 'p' flag is given then there is an extra item with
6890 the sub-pattern match number |search()-sub-match|. Example: >
6891 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
6892< In this example "submatch" is 2 when a lowercase letter is
6893 found |/\l|, 3 when an uppercase letter is found |/\u|.
6894
Bram Moolenaar81edd172016-04-14 13:51:37 +02006895server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006896 Send a reply string to {clientid}. The most recent {clientid}
6897 that sent a string can be retrieved with expand("<client>").
6898 {only available when compiled with the |+clientserver| feature}
6899 Note:
6900 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006901 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006902 before calling any commands that waits for input.
6903 See also |clientserver|.
6904 Example: >
6905 :echo server2client(expand("<client>"), "HELLO")
6906<
6907serverlist() *serverlist()*
6908 Return a list of available server names, one per line.
6909 When there are no servers or the information is not available
6910 an empty string is returned. See also |clientserver|.
6911 {only available when compiled with the |+clientserver| feature}
6912 Example: >
6913 :echo serverlist()
6914<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02006915setbufline({expr}, {lnum}, {text}) *setbufline()*
6916 Set line {lnum} to {text} in buffer {expr}. To insert
6917 lines use |append()|.
6918
6919 For the use of {expr}, see |bufname()| above.
6920
6921 {lnum} is used like with |setline()|.
6922 This works like |setline()| for the specified buffer.
6923 On success 0 is returned, on failure 1 is returned.
6924
6925 If {expr} is not a valid buffer or {lnum} is not valid, an
6926 error message is given.
6927
Bram Moolenaar071d4272004-06-13 20:20:40 +00006928setbufvar({expr}, {varname}, {val}) *setbufvar()*
6929 Set option or local variable {varname} in buffer {expr} to
6930 {val}.
6931 This also works for a global or local window option, but it
6932 doesn't work for a global or local window variable.
6933 For a local window option the global value is unchanged.
6934 For the use of {expr}, see |bufname()| above.
6935 Note that the variable name without "b:" must be used.
6936 Examples: >
6937 :call setbufvar(1, "&mod", 1)
6938 :call setbufvar("todo", "myvar", "foobar")
6939< This function is not available in the |sandbox|.
6940
Bram Moolenaar12969c02015-09-08 23:36:10 +02006941setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02006942 Set the current character search information to {dict},
6943 which contains one or more of the following entries:
6944
6945 char character which will be used for a subsequent
6946 |,| or |;| command; an empty string clears the
6947 character search
6948 forward direction of character search; 1 for forward,
6949 0 for backward
6950 until type of character search; 1 for a |t| or |T|
6951 character search, 0 for an |f| or |F|
6952 character search
6953
6954 This can be useful to save/restore a user's character search
6955 from a script: >
6956 :let prevsearch = getcharsearch()
6957 :" Perform a command which clobbers user's search
6958 :call setcharsearch(prevsearch)
6959< Also see |getcharsearch()|.
6960
Bram Moolenaar071d4272004-06-13 20:20:40 +00006961setcmdpos({pos}) *setcmdpos()*
6962 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02006963 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006964 Use |getcmdpos()| to obtain the current position.
6965 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00006966 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
6967 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
6968 set after the command line is set to the expression. For
6969 |c_CTRL-R_=| it is set after evaluating the expression but
6970 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006971 When the number is too big the cursor is put at the end of the
6972 line. A number smaller than one has undefined results.
6973 Returns 0 when successful, 1 when not editing the command
6974 line.
6975
Bram Moolenaar80492532016-03-08 17:08:53 +01006976setfperm({fname}, {mode}) *setfperm()* *chmod*
6977 Set the file permissions for {fname} to {mode}.
6978 {mode} must be a string with 9 characters. It is of the form
6979 "rwxrwxrwx", where each group of "rwx" flags represent, in
6980 turn, the permissions of the owner of the file, the group the
6981 file belongs to, and other users. A '-' character means the
6982 permission is off, any other character means on. Multi-byte
6983 characters are not supported.
6984
6985 For example "rw-r-----" means read-write for the user,
6986 readable by the group, not accessible by others. "xx-x-----"
6987 would do the same thing.
6988
6989 Returns non-zero for success, zero for failure.
6990
6991 To read permissions see |getfperm()|.
6992
6993
Bram Moolenaar446cb832008-06-24 21:56:24 +00006994setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006995 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02006996 lines use |append()|. To set lines in another buffer use
6997 |setbufline()|.
6998
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006999 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007000 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007001 added as a new line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007002
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007003 If this succeeds, 0 is returned. If this fails (most likely
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007004 because {lnum} is invalid) 1 is returned.
7005
7006 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007007 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007008
Bram Moolenaar446cb832008-06-24 21:56:24 +00007009< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007010 will be set to the items in the list. Example: >
7011 :call setline(5, ['aaa', 'bbb', 'ccc'])
7012< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02007013 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007014 : call setline(n, l)
7015 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02007016
Bram Moolenaar071d4272004-06-13 20:20:40 +00007017< Note: The '[ and '] marks are not set.
7018
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007019setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00007020 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02007021 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02007022 When {nr} is zero the current window is used.
7023
7024 For a location list window, the displayed location list is
7025 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007026 Otherwise, same as |setqflist()|.
7027 Also see |location-list|.
7028
Bram Moolenaard823fa92016-08-12 16:29:27 +02007029 If the optional {what} dictionary argument is supplied, then
7030 only the items listed in {what} are set. Refer to |setqflist()|
7031 for the list of supported keys in {what}.
7032
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007033setmatches({list}) *setmatches()*
7034 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00007035 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007036 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007037
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007038 *setpos()*
7039setpos({expr}, {list})
7040 Set the position for {expr}. Possible values:
7041 . the cursor
7042 'x mark x
7043
Bram Moolenaar493c1782014-05-28 14:34:46 +02007044 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007045 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02007046 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007047
Bram Moolenaar58b85342016-08-14 19:54:54 +02007048 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01007049 current buffer. When setting an uppercase mark "bufnum" is
7050 used for the mark position. For other marks it specifies the
7051 buffer to set the mark in. You can use the |bufnr()| function
7052 to turn a file name into a buffer number.
7053 For setting the cursor and the ' mark "bufnum" is ignored,
7054 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00007055 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007056
7057 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007058 column is 1. Use a zero "lnum" to delete a mark. If "col" is
7059 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007060
7061 The "off" number is only used when 'virtualedit' is set. Then
7062 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007063 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007064 character.
7065
Bram Moolenaar493c1782014-05-28 14:34:46 +02007066 The "curswant" number is only used when setting the cursor
7067 position. It sets the preferred column for when moving the
7068 cursor vertically. When the "curswant" number is missing the
7069 preferred column is not set. When it is present and setting a
7070 mark position it is not used.
7071
Bram Moolenaardfb18412013-12-11 18:53:29 +01007072 Note that for '< and '> changing the line number may result in
7073 the marks to be effectively be swapped, so that '< is always
7074 before '>.
7075
Bram Moolenaar08250432008-02-13 11:42:46 +00007076 Returns 0 when the position could be set, -1 otherwise.
7077 An error message is given if {expr} is invalid.
7078
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02007079 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007080
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007081 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02007082 vertically; if you set the cursor position with this, |j| and
7083 |k| motions will jump to previous columns! Use |cursor()| to
7084 also set the preferred column. Also see the "curswant" key in
7085 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007086
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007087setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02007088 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007089
Bram Moolenaarae338332017-08-11 20:25:26 +02007090 When {what} is not present, use the items in {list}. Each
7091 item must be a dictionary. Non-dictionary items in {list} are
7092 ignored. Each dictionary item can contain the following
7093 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007094
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007095 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00007096 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007097 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00007098 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007099 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007100 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00007101 col column number
7102 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007103 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00007104 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007105 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00007106 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02007107 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007108
Bram Moolenaar582fd852005-03-28 20:58:01 +00007109 The "col", "vcol", "nr", "type" and "text" entries are
7110 optional. Either "lnum" or "pattern" entry can be used to
7111 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007112 If the "filename" and "bufnr" entries are not present or
7113 neither the "lnum" or "pattern" entries are present, then the
7114 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007115 If both "pattern" and "lnum" are present then "pattern" will
7116 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02007117 If the "valid" entry is not supplied, then the valid flag is
7118 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007119 If you supply an empty {list}, the quickfix list will be
7120 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007121 Note that the list is not exactly the same as what
7122 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007123
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007124 {action} values: *E927*
7125 'a' The items from {list} are added to the existing
7126 quickfix list. If there is no existing list, then a
7127 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007128
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007129 'r' The items from the current quickfix list are replaced
7130 with the items from {list}. This can also be used to
7131 clear the list: >
7132 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007133<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007134 'f' All the quickfix lists in the quickfix stack are
7135 freed.
7136
Bram Moolenaar511972d2016-06-04 18:09:59 +02007137 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02007138 is created. The new quickfix list is added after the current
7139 quickfix list in the stack and all the following lists are
7140 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02007141 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00007142
Bram Moolenaard823fa92016-08-12 16:29:27 +02007143 If the optional {what} dictionary argument is supplied, then
7144 only the items listed in {what} are set. The first {list}
7145 argument is ignored. The following items can be specified in
7146 {what}:
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02007147 context any Vim type can be stored as a context
Bram Moolenaar36538222017-09-02 19:51:44 +02007148 efm errorformat to use when parsing text from
7149 "lines". If this is not present, then the
7150 'errorformat' option value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007151 id quickfix list identifier |quickfix-ID|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02007152 items list of quickfix entries. Same as the {list}
7153 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02007154 lines use 'errorformat' to parse a list of lines and
7155 add the resulting entries to the quickfix list
7156 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar875feea2017-06-11 16:07:51 +02007157 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02007158 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02007159 the last quickfix list
Bram Moolenaard823fa92016-08-12 16:29:27 +02007160 title quickfix list title text
7161 Unsupported keys in {what} are ignored.
7162 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02007163 is modified. When creating a new quickfix list, "nr" can be
7164 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007165 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02007166 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007167 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02007168
7169 Examples: >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02007170 :call setqflist([], 'r', {'title': 'My search'})
7171 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
7172 :call setqflist([], 'a', {'id':myid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02007173<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007174 Returns zero for success, -1 for failure.
7175
7176 This function can be used to create a quickfix list
7177 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02007178 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007179
7180
Bram Moolenaar071d4272004-06-13 20:20:40 +00007181 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01007182setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00007183 Set the register {regname} to {value}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007184 {value} may be any value returned by |getreg()|, including
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007185 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007186 If {options} contains "a" or {regname} is upper case,
7187 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02007188 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007189 "c" or "v" |characterwise| mode
7190 "l" or "V" |linewise| mode
7191 "b" or "<CTRL-V>" |blockwise-visual| mode
7192 If a number immediately follows "b" or "<CTRL-V>" then this is
7193 used as the width of the selection - if it is not specified
7194 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007195 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007196
7197 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007198 is to use character mode unless {value} ends in a <NL> for
7199 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007200 mode is never selected automatically.
7201 Returns zero for success, non-zero for failure.
7202
7203 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007204 Note: you may not use |List| containing more than one item to
7205 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007206 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007207
7208 Examples: >
7209 :call setreg(v:register, @*)
7210 :call setreg('*', @%, 'ac')
7211 :call setreg('a', "1\n2\n3", 'b5')
7212
7213< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02007214 register: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007215 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007216 :let var_amode = getregtype('a')
7217 ....
7218 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007219< Note: you may not reliably restore register value
7220 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02007221 newlines are represented as newlines AND Nul bytes are
7222 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007223
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02007224 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00007225 nothing: >
7226 :call setreg('a', '', 'al')
7227
Bram Moolenaar06b5d512010-05-22 15:37:44 +02007228settabvar({tabnr}, {varname}, {val}) *settabvar()*
7229 Set tab-local variable {varname} to {val} in tab page {tabnr}.
7230 |t:var|
7231 Note that the variable name without "t:" must be used.
7232 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02007233 This function is not available in the |sandbox|.
7234
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00007235settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
7236 Set option or local variable {varname} in window {winnr} to
7237 {val}.
7238 Tabs are numbered starting with one. For the current tabpage
7239 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02007240 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00007241 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007242 This also works for a global or local buffer option, but it
7243 doesn't work for a global or local buffer variable.
7244 For a local buffer option the global value is unchanged.
7245 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00007246 Examples: >
7247 :call settabwinvar(1, 1, "&list", 0)
7248 :call settabwinvar(3, 2, "myvar", "foobar")
7249< This function is not available in the |sandbox|.
7250
7251setwinvar({nr}, {varname}, {val}) *setwinvar()*
7252 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007253 Examples: >
7254 :call setwinvar(1, "&list", 0)
7255 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01007257sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01007258 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01007259 checksum of {string}.
7260 {only available when compiled with the |+cryptv| feature}
7261
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007262shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007263 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00007264 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007265 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00007266 quotes within {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007267 Otherwise it will enclose {string} in single quotes and
7268 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02007269
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007270 When the {special} argument is present and it's a non-zero
7271 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007272 items such as "!", "%", "#" and "<cword>" will be preceded by
7273 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007274 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02007275
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007276 The "!" character will be escaped (again with a |non-zero-arg|
7277 {special}) when 'shell' contains "csh" in the tail. That is
7278 because for csh and tcsh "!" is used for history replacement
7279 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02007280
7281 With a |non-zero-arg| {special} the <NL> character is also
7282 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007283 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02007284
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007285 Example of use with a |:!| command: >
7286 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
7287< This results in a directory listing for the file under the
7288 cursor. Example of use with |system()|: >
7289 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01007290< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00007291
7292
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02007293shiftwidth() *shiftwidth()*
7294 Returns the effective value of 'shiftwidth'. This is the
7295 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01007296 'tabstop' value. This function was introduced with patch
7297 7.3.694 in 2012, everybody should have it by now.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02007298
7299
Bram Moolenaar071d4272004-06-13 20:20:40 +00007300simplify({filename}) *simplify()*
7301 Simplify the file name as much as possible without changing
7302 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
7303 Unix) are not resolved. If the first path component in
7304 {filename} designates the current directory, this will be
7305 valid for the result as well. A trailing path separator is
7306 not removed either.
7307 Example: >
7308 simplify("./dir/.././/file/") == "./file/"
7309< Note: The combination "dir/.." is only removed if "dir" is
7310 a searchable directory or does not exist. On Unix, it is also
7311 removed when "dir" is a symbolic link within the same
7312 directory. In order to resolve all the involved symbolic
7313 links before simplifying the path name, use |resolve()|.
7314
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007315
Bram Moolenaar446cb832008-06-24 21:56:24 +00007316sin({expr}) *sin()*
7317 Return the sine of {expr}, measured in radians, as a |Float|.
7318 {expr} must evaluate to a |Float| or a |Number|.
7319 Examples: >
7320 :echo sin(100)
7321< -0.506366 >
7322 :echo sin(-4.01)
7323< 0.763301
7324 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007325
Bram Moolenaar446cb832008-06-24 21:56:24 +00007326
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007327sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007328 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007329 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007330 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007331 Examples: >
7332 :echo sinh(0.5)
7333< 0.521095 >
7334 :echo sinh(-0.9)
7335< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02007336 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007337
7338
Bram Moolenaar5f894962011-06-19 02:55:37 +02007339sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01007340 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007341
Bram Moolenaar327aa022014-03-25 18:24:23 +01007342 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007343 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02007344
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007345< When {func} is omitted, is empty or zero, then sort() uses the
7346 string representation of each item to sort on. Numbers sort
7347 after Strings, |Lists| after Numbers. For sorting text in the
7348 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01007349
Bram Moolenaar34401cc2014-08-29 15:12:19 +02007350 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007351 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007352
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007353 When {func} is given and it is 'n' then all items will be
7354 sorted numerical (Implementation detail: This uses the
7355 strtod() function to parse numbers, Strings, Lists, Dicts and
7356 Funcrefs will be considered as being 0).
7357
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01007358 When {func} is given and it is 'N' then all items will be
7359 sorted numerical. This is like 'n' but a string containing
7360 digits will be used as the number they represent.
7361
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01007362 When {func} is given and it is 'f' then all items will be
7363 sorted numerical. All values must be a Number or a Float.
7364
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007365 When {func} is a |Funcref| or a function name, this function
7366 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007367 items as argument and must return zero if they are equal, 1 or
7368 bigger if the first one sorts after the second one, -1 or
7369 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01007370
7371 {dict} is for functions with the "dict" attribute. It will be
7372 used to set the local variable "self". |Dictionary-function|
7373
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02007374 The sort is stable, items which compare equal (as number or as
7375 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02007376 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02007377 same order as they were originally.
7378
Bram Moolenaar327aa022014-03-25 18:24:23 +01007379 Also see |uniq()|.
7380
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007381 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007382 func MyCompare(i1, i2)
7383 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
7384 endfunc
7385 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007386< A shorter compare version for this specific simple case, which
7387 ignores overflow: >
7388 func MyCompare(i1, i2)
7389 return a:i1 - a:i2
7390 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007391<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007392 *soundfold()*
7393soundfold({word})
7394 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00007395 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00007396 soundfolding. 'spell' must be set. When no sound folding is
7397 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007398 This can be used for making spelling suggestions. Note that
7399 the method can be quite slow.
7400
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007401 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00007402spellbadword([{sentence}])
7403 Without argument: The result is the badly spelled word under
7404 or after the cursor. The cursor is moved to the start of the
7405 bad word. When no bad word is found in the cursor line the
7406 result is an empty string and the cursor doesn't move.
7407
7408 With argument: The result is the first word in {sentence} that
7409 is badly spelled. If there are no spelling mistakes the
7410 result is an empty string.
7411
7412 The return value is a list with two items:
7413 - The badly spelled word or an empty string.
7414 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007415 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00007416 "rare" rare word
7417 "local" word only valid in another region
7418 "caps" word should start with Capital
7419 Example: >
7420 echo spellbadword("the quik brown fox")
7421< ['quik', 'bad'] ~
7422
7423 The spelling information for the current window is used. The
7424 'spell' option must be set and the value of 'spelllang' is
7425 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007426
7427 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00007428spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007429 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007430 When {max} is given up to this number of suggestions are
7431 returned. Otherwise up to 25 suggestions are returned.
7432
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00007433 When the {capital} argument is given and it's non-zero only
7434 suggestions with a leading capital will be given. Use this
7435 after a match with 'spellcapcheck'.
7436
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007437 {word} can be a badly spelled word followed by other text.
7438 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00007439 suggestions also include the following text, thus you can
7440 replace a line.
7441
7442 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00007443 returned. {word} itself is not included in the suggestions,
7444 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007445
7446 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00007447 'spell' option must be set and the values of 'spelllang' and
7448 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007449
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007450
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007451split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007452 Make a |List| out of {expr}. When {pattern} is omitted or
7453 empty each white-separated sequence of characters becomes an
7454 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007455 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01007456 removing the matched characters. 'ignorecase' is not used
7457 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007458 When the first or last item is empty it is omitted, unless the
7459 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00007460 Other empty items are kept when {pattern} matches at least one
7461 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007462 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007463 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007464< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007465 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02007466< If you want to keep the separator you can also use '\zs' at
7467 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00007468 :echo split('abc:def:ghi', ':\zs')
7469< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007470 Splitting a table where the first element can be empty: >
7471 :let items = split(line, ':', 1)
7472< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007473
7474
Bram Moolenaar446cb832008-06-24 21:56:24 +00007475sqrt({expr}) *sqrt()*
7476 Return the non-negative square root of Float {expr} as a
7477 |Float|.
7478 {expr} must evaluate to a |Float| or a |Number|. When {expr}
7479 is negative the result is NaN (Not a Number).
7480 Examples: >
7481 :echo sqrt(100)
7482< 10.0 >
7483 :echo sqrt(-4.01)
7484< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00007485 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007486 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007487
Bram Moolenaar446cb832008-06-24 21:56:24 +00007488
Bram Moolenaar81edd172016-04-14 13:51:37 +02007489str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007490 Convert String {expr} to a Float. This mostly works the same
7491 as when using a floating point number in an expression, see
7492 |floating-point-format|. But it's a bit more permissive.
7493 E.g., "1e40" is accepted, while in an expression you need to
7494 write "1.0e40".
7495 Text after the number is silently ignored.
7496 The decimal point is always '.', no matter what the locale is
7497 set to. A comma ends the number: "12,345.67" is converted to
7498 12.0. You can strip out thousands separators with
7499 |substitute()|: >
7500 let f = str2float(substitute(text, ',', '', 'g'))
7501< {only available when compiled with the |+float| feature}
7502
7503
Bram Moolenaar81edd172016-04-14 13:51:37 +02007504str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007505 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01007506 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007507 When {base} is omitted base 10 is used. This also means that
7508 a leading zero doesn't cause octal conversion to be used, as
7509 with the default String to Number conversion.
7510 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01007511 different base the result will be zero. Similarly, when
7512 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
7513 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007514 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007515
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007516
Bram Moolenaar979243b2015-06-26 19:35:49 +02007517strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02007518 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02007519 in String {expr}.
7520 When {skipcc} is omitted or zero, composing characters are
7521 counted separately.
7522 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02007523 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007524
Bram Moolenaar86ae7202015-07-10 19:31:35 +02007525 {skipcc} is only available after 7.4.755. For backward
7526 compatibility, you can define a wrapper function: >
7527 if has("patch-7.4.755")
7528 function s:strchars(str, skipcc)
7529 return strchars(a:str, a:skipcc)
7530 endfunction
7531 else
7532 function s:strchars(str, skipcc)
7533 if a:skipcc
7534 return strlen(substitute(a:str, ".", "x", "g"))
7535 else
7536 return strchars(a:str)
7537 endif
7538 endfunction
7539 endif
7540<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007541strcharpart({src}, {start} [, {len}]) *strcharpart()*
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007542 Like |strpart()| but using character index and length instead
7543 of byte index and length.
7544 When a character index is used where a character does not
Bram Moolenaar369b6f52017-01-17 12:22:32 +01007545 exist it is assumed to be one character. For example: >
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007546 strcharpart('abc', -1, 2)
7547< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02007548
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007549strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +02007550 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02007551 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02007552 When {col} is omitted zero is used. Otherwise it is the
7553 screen column where to start. This matters for Tab
7554 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02007555 The option settings of the current window are used. This
7556 matters for anything that's displayed differently, such as
7557 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02007558 When {expr} contains characters with East Asian Width Class
7559 Ambiguous, this function's return value depends on 'ambiwidth'.
7560 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02007561
Bram Moolenaar071d4272004-06-13 20:20:40 +00007562strftime({format} [, {time}]) *strftime()*
7563 The result is a String, which is a formatted date and time, as
7564 specified by the {format} string. The given {time} is used,
7565 or the current time if no time is given. The accepted
7566 {format} depends on your system, thus this is not portable!
7567 See the manual page of the C function strftime() for the
7568 format. The maximum length of the result is 80 characters.
7569 See also |localtime()| and |getftime()|.
7570 The language can be changed with the |:language| command.
7571 Examples: >
7572 :echo strftime("%c") Sun Apr 27 11:49:23 1997
7573 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
7574 :echo strftime("%y%m%d %T") 970427 11:53:55
7575 :echo strftime("%H:%M") 11:55
7576 :echo strftime("%c", getftime("file.c"))
7577 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007578< Not available on all systems. To check use: >
7579 :if exists("*strftime")
7580
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007581strgetchar({str}, {index}) *strgetchar()*
7582 Get character {index} from {str}. This uses a character
7583 index, not a byte index. Composing characters are considered
7584 separate characters here.
7585 Also see |strcharpart()| and |strchars()|.
7586
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007587stridx({haystack}, {needle} [, {start}]) *stridx()*
7588 The result is a Number, which gives the byte index in
7589 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00007590 If {start} is specified, the search starts at index {start}.
7591 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01007592 :let colon1 = stridx(line, ":")
7593 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00007594< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007595 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007596 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00007597 See also |strridx()|.
7598 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007599 :echo stridx("An Example", "Example") 3
7600 :echo stridx("Starting point", "Start") 0
7601 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007602< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00007603 stridx() works similar to the C function strstr(). When used
7604 with a single character it works similar to strchr().
7605
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007606 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007607string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00007608 Float, String or a composition of them, then the result can be
7609 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007610 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01007611 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007612 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00007613 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00007614 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007615 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00007616 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01007617
7618 When a List or Dictionary has a recursive reference it is
7619 replaced by "[...]" or "{...}". Using eval() on the result
7620 will then fail.
7621
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007622 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007623
Bram Moolenaar071d4272004-06-13 20:20:40 +00007624 *strlen()*
7625strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00007626 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007627 If the argument is a Number it is first converted to a String.
7628 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02007629 If you want to count the number of multi-byte characters use
7630 |strchars()|.
7631 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007632
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007633strpart({src}, {start} [, {len}]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007634 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00007635 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007636 To count characters instead of bytes use |strcharpart()|.
7637
7638 When bytes are selected which do not exist, this doesn't
7639 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007640 If {len} is missing, the copy continues from {start} till the
7641 end of the {src}. >
7642 strpart("abcdefg", 3, 2) == "de"
7643 strpart("abcdefg", -2, 4) == "ab"
7644 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00007645 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007646
Bram Moolenaar071d4272004-06-13 20:20:40 +00007647< Note: To get the first character, {start} must be 0. For
7648 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00007649 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007650<
Bram Moolenaar677ee682005-01-27 14:41:15 +00007651strridx({haystack}, {needle} [, {start}]) *strridx()*
7652 The result is a Number, which gives the byte index in
7653 {haystack} of the last occurrence of the String {needle}.
7654 When {start} is specified, matches beyond this index are
7655 ignored. This can be used to find a match before a previous
7656 match: >
7657 :let lastcomma = strridx(line, ",")
7658 :let comma2 = strridx(line, ",", lastcomma - 1)
7659< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007660 For pattern searches use |match()|.
7661 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007662 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007663 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007664 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007665< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00007666 When used with a single character it works similar to the C
7667 function strrchr().
7668
Bram Moolenaar071d4272004-06-13 20:20:40 +00007669strtrans({expr}) *strtrans()*
7670 The result is a String, which is {expr} with all unprintable
7671 characters translated into printable characters |'isprint'|.
7672 Like they are shown in a window. Example: >
7673 echo strtrans(@a)
7674< This displays a newline in register a as "^@" instead of
7675 starting a new line.
7676
Bram Moolenaar72597a52010-07-18 15:31:08 +02007677strwidth({expr}) *strwidth()*
7678 The result is a Number, which is the number of display cells
7679 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02007680 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02007681 When {expr} contains characters with East Asian Width Class
7682 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02007683 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02007684
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007685submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +02007686 Only for an expression in a |:substitute| command or
7687 substitute() function.
7688 Returns the {nr}'th submatch of the matched text. When {nr}
7689 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02007690 Note that a NL in the string can stand for a line break of a
7691 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02007692 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02007693
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007694 If {list} is present and non-zero then submatch() returns
7695 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +02007696 NL characters in the text represent NUL characters in the
7697 text.
7698 Only returns more than one item for |:substitute|, inside
7699 |substitute()| this list will always contain one or zero
7700 items, since there are no real line breaks.
7701
Bram Moolenaar6100d022016-10-02 16:51:57 +02007702 When substitute() is used recursively only the submatches in
7703 the current (deepest) call can be obtained.
7704
Bram Moolenaar2f058492017-11-30 20:27:52 +01007705 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007706 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +01007707 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +00007708< This finds the first number in the line and adds one to it.
7709 A line break is included as a newline character.
7710
7711substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
7712 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02007713 the first match of {pat} is replaced with {sub}.
7714 When {flags} is "g", all matches of {pat} in {expr} are
7715 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007716
Bram Moolenaar251e1912011-06-19 05:09:16 +02007717 This works like the ":substitute" command (without any flags).
7718 But the matching with {pat} is always done like the 'magic'
7719 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007720 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
7721 if you want to ignore or match case and ignore 'ignorecase'.
7722 'smartcase' is not used. See |string-match| for how {pat} is
7723 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02007724
7725 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007726 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +02007727 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00007728 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02007729
Bram Moolenaar071d4272004-06-13 20:20:40 +00007730 When {pat} does not match in {expr}, {expr} is returned
7731 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02007732
Bram Moolenaar071d4272004-06-13 20:20:40 +00007733 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02007734 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007735< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02007736 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007737< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02007738
7739 When {sub} starts with "\=", the remainder is interpreted as
7740 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02007741 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02007742 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00007743
Bram Moolenaardf48fb42016-07-22 21:50:18 +02007744< When {sub} is a Funcref that function is called, with one
7745 optional argument. Example: >
7746 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
7747< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +02007748 matched string and up to nine submatches, like what
7749 |submatch()| returns. Example: >
7750 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +02007751
Bram Moolenaar47136d72004-10-12 20:02:24 +00007752synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007753 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00007754 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007755 The syntax ID can be used with |synIDattr()| and
7756 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007757
Bram Moolenaar47136d72004-10-12 20:02:24 +00007758 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007759 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02007760 Note that when the position is after the last character,
7761 that's where the cursor can be in Insert mode, synID() returns
7762 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007763
Bram Moolenaar79815f12016-07-09 17:07:29 +02007764 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02007765 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +02007766 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +00007767 item is returned. This is useful when wanting to know which
7768 syntax item is effective (e.g. inside parens).
7769 Warning: This function can be very slow. Best speed is
7770 obtained by going through the file in forward direction.
7771
7772 Example (echoes the name of the syntax item under the cursor): >
7773 :echo synIDattr(synID(line("."), col("."), 1), "name")
7774<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02007775
Bram Moolenaar071d4272004-06-13 20:20:40 +00007776synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
7777 The result is a String, which is the {what} attribute of
7778 syntax ID {synID}. This can be used to obtain information
7779 about a syntax item.
7780 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +02007781 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00007782 used, the attributes for the currently active highlighting are
7783 used (GUI, cterm or term).
7784 Use synIDtrans() to follow linked highlight groups.
7785 {what} result
7786 "name" the name of the syntax item
7787 "fg" foreground color (GUI: color name used to set
7788 the color, cterm: color number as a string,
7789 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007790 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01007791 "font" font name (only available in the GUI)
7792 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007793 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794 "fg#" like "fg", but for the GUI and the GUI is
7795 running the name in "#RRGGBB" form
7796 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007797 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007798 "bold" "1" if bold
7799 "italic" "1" if italic
7800 "reverse" "1" if reverse
7801 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01007802 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00007803 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007804 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02007805 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +00007806
7807 Example (echoes the color of the syntax item under the
7808 cursor): >
7809 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
7810<
7811synIDtrans({synID}) *synIDtrans()*
7812 The result is a Number, which is the translated syntax ID of
7813 {synID}. This is the syntax group ID of what is being used to
7814 highlight the character. Highlight links given with
7815 ":highlight link" are followed.
7816
Bram Moolenaar483c5d82010-10-20 18:45:33 +02007817synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaar4d785892017-06-22 22:00:50 +02007818 The result is a List with currently three items:
7819 1. The first item in the list is 0 if the character at the
7820 position {lnum} and {col} is not part of a concealable
7821 region, 1 if it is.
7822 2. The second item in the list is a string. If the first item
7823 is 1, the second item contains the text which will be
7824 displayed in place of the concealed text, depending on the
7825 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02007826 3. The third and final item in the list is a number
7827 representing the specific syntax region matched in the
7828 line. When the character is not concealed the value is
7829 zero. This allows detection of the beginning of a new
7830 concealable region if there are two consecutive regions
7831 with the same replacement character. For an example, if
7832 the text is "123456" and both "23" and "45" are concealed
7833 and replace by the character "X", then:
7834 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +02007835 synconcealed(lnum, 1) [0, '', 0]
7836 synconcealed(lnum, 2) [1, 'X', 1]
7837 synconcealed(lnum, 3) [1, 'X', 1]
7838 synconcealed(lnum, 4) [1, 'X', 2]
7839 synconcealed(lnum, 5) [1, 'X', 2]
7840 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +02007841
7842
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007843synstack({lnum}, {col}) *synstack()*
7844 Return a |List|, which is the stack of syntax items at the
7845 position {lnum} and {col} in the current window. Each item in
7846 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007847 The first item in the List is the outer region, following are
7848 items contained in that one. The last one is what |synID()|
7849 returns, unless not the whole item is highlighted or it is a
7850 transparent item.
7851 This function is useful for debugging a syntax file.
7852 Example that shows the syntax stack under the cursor: >
7853 for id in synstack(line("."), col("."))
7854 echo synIDattr(id, "name")
7855 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02007856< When the position specified with {lnum} and {col} is invalid
7857 nothing is returned. The position just after the last
7858 character in a line and the first column in an empty line are
7859 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007860
Bram Moolenaarc0197e22004-09-13 20:26:32 +00007861system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007862 Get the output of the shell command {expr} as a string. See
7863 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02007864
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007865 When {input} is given and is a string this string is written
7866 to a file and passed as stdin to the command. The string is
7867 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02007868 separators yourself.
7869 If {input} is given and is a |List| it is written to the file
7870 in a way |writefile()| does with {binary} set to "b" (i.e.
7871 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +01007872 list items converted to NULs).
7873 When {input} is given and is a number that is a valid id for
7874 an existing buffer then the content of the buffer is written
7875 to the file line by line, each line terminated by a NL and
7876 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02007877
7878 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02007879
Bram Moolenaar04186092016-08-29 21:55:35 +02007880 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +02007881 cooked mode. This is meant to be used for commands that do
7882 not need the user to type. It avoids stray characters showing
7883 up on the screen which require |CTRL-L| to remove. >
7884 :silent let f = system('ls *.vim')
7885<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007886 Note: Use |shellescape()| or |::S| with |expand()| or
7887 |fnamemodify()| to escape special characters in a command
7888 argument. Newlines in {expr} may cause the command to fail.
7889 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +01007890 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007891 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007892
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007893 The result is a String. Example: >
7894 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01007895 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00007896
7897< To make the result more system-independent, the shell output
7898 is filtered to replace <CR> with <NL> for Macintosh, and
7899 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02007900 To avoid the string being truncated at a NUL, all NUL
7901 characters are replaced with SOH (0x01).
7902
Bram Moolenaar071d4272004-06-13 20:20:40 +00007903 The command executed is constructed using several options:
7904 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
7905 ({tmp} is an automatically generated file name).
7906 For Unix and OS/2 braces are put around {expr} to allow for
7907 concatenated commands.
7908
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007909 The command will be executed in "cooked" mode, so that a
7910 CTRL-C will interrupt the command (on Unix at least).
7911
Bram Moolenaar071d4272004-06-13 20:20:40 +00007912 The resulting error code can be found in |v:shell_error|.
7913 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00007914
7915 Note that any wrong value in the options mentioned above may
7916 make the function fail. It has also been reported to fail
7917 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007918 Unlike ":!cmd" there is no automatic check for changed files.
7919 Use |:checktime| to force a check.
7920
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007921
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007922systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007923 Same as |system()|, but returns a |List| with lines (parts of
7924 output separated by NL) with NULs transformed into NLs. Output
7925 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar68563932017-01-10 13:31:15 +01007926 set to "b". Note that on MS-Windows you may get trailing CR
7927 characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007928
Bram Moolenaar975b5272016-03-15 23:10:59 +01007929 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007930
7931
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007932tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007933 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007934 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02007935 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007936 omitted the current tab page is used.
7937 When {arg} is invalid the number zero is returned.
7938 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007939 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007940 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007941 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007942 endfor
7943< Note that a buffer may appear in more than one window.
7944
7945
7946tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00007947 The result is a Number, which is the number of the current
7948 tab page. The first tab page has number 1.
7949 When the optional argument is "$", the number of the last tab
7950 page is returned (the tab page count).
7951 The number can be used with the |:tab| command.
7952
7953
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007954tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02007955 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007956 {tabarg} specifies the number of tab page to be used.
7957 {arg} is used like with |winnr()|:
7958 - When omitted the current window number is returned. This is
7959 the window which will be used when going to this tab page.
7960 - When "$" the number of windows is returned.
7961 - When "#" the previous window nr is returned.
7962 Useful examples: >
7963 tabpagewinnr(1) " current window of tab page 1
7964 tabpagewinnr(4, '$') " number of windows in tab page 4
7965< When {tabarg} is invalid zero is returned.
7966
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00007967 *tagfiles()*
7968tagfiles() Returns a |List| with the file names used to search for tags
7969 for the current buffer. This is the 'tags' option expanded.
7970
7971
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007972taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007973 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +01007974
7975 If {filename} is passed it is used to prioritize the results
7976 in the same way that |:tselect| does. See |tag-priority|.
7977 {filename} should be the full path of the file.
7978
Bram Moolenaard8c00872005-07-22 21:52:15 +00007979 Each list item is a dictionary with at least the following
7980 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00007981 name Name of the tag.
7982 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007983 defined. It is either relative to the
7984 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007985 cmd Ex command used to locate the tag in
7986 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007987 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007988 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007989 kind values. Only available when
7990 using a tags file generated by
7991 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007992 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007993 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007994 More entries may be present, depending on the content of the
7995 tags file: access, implementation, inherits and signature.
7996 Refer to the ctags documentation for information about these
7997 fields. For C code the fields "struct", "class" and "enum"
7998 may appear, they give the name of the entity the tag is
7999 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008000
Bram Moolenaar214641f2017-03-05 17:04:09 +01008001 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00008002 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00008003
8004 If there are no matching tags, then an empty list is returned.
8005
8006 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01008007 used in {expr}. This also make the function work faster.
8008 Refer to |tag-regexp| for more information about the tag
8009 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00008010
8011 Refer to |'tags'| for information about how the tags file is
8012 located by Vim. Refer to |tags-file-format| for the format of
8013 the tags file generated by the different ctags tools.
8014
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008015tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008016 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008017 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008018 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008019 Examples: >
8020 :echo tan(10)
8021< 0.648361 >
8022 :echo tan(-4.01)
8023< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02008024 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008025
8026
8027tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008028 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008029 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008030 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008031 Examples: >
8032 :echo tanh(0.5)
8033< 0.462117 >
8034 :echo tanh(-1)
8035< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02008036 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008037
8038
Bram Moolenaar574860b2016-05-24 17:33:34 +02008039tempname() *tempname()* *temp-file-name*
8040 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +02008041 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +02008042 is different for at least 26 consecutive calls. Example: >
8043 :let tmpfile = tempname()
8044 :exe "redir > " . tmpfile
8045< For Unix, the file will be in a private directory |tempfile|.
8046 For MS-Windows forward slashes are used when the 'shellslash'
8047 option is set or when 'shellcmdflag' starts with '-'.
8048
Bram Moolenaare41e3b42017-08-11 16:24:50 +02008049term_getaltscreen({buf}) *term_getaltscreen()*
8050 Returns 1 if the terminal of {buf} is using the alternate
8051 screen.
8052 {buf} is used as with |term_getsize()|.
8053 {only available when compiled with the |+terminal| feature}
8054
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008055term_getattr({attr}, {what}) *term_getattr()*
8056 Given {attr}, a value returned by term_scrape() in the "attr"
8057 item, return whether {what} is on. {what} can be one of:
8058 bold
8059 italic
8060 underline
8061 strike
8062 reverse
Bram Moolenaar45356542017-08-06 17:53:31 +02008063 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02008064
Bram Moolenaar97870002017-07-30 18:28:38 +02008065term_getcursor({buf}) *term_getcursor()*
Bram Moolenaar45356542017-08-06 17:53:31 +02008066 Get the cursor position of terminal {buf}. Returns a list with
Bram Moolenaar37c64c72017-09-19 22:06:03 +02008067 two numbers and a dictionary: [row, col, dict].
Bram Moolenaar45356542017-08-06 17:53:31 +02008068
Bram Moolenaar37c64c72017-09-19 22:06:03 +02008069 "row" and "col" are one based, the first screen cell is row
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02008070 1, column 1. This is the cursor position of the terminal
8071 itself, not of the Vim window.
8072
8073 "dict" can have these members:
8074 "visible" one when the cursor is visible, zero when it
8075 is hidden.
8076 "blink" one when the cursor is visible, zero when it
8077 is hidden.
8078 "shape" 1 for a block cursor, 2 for underline and 3
8079 for a vertical bar.
Bram Moolenaar97870002017-07-30 18:28:38 +02008080
8081 {buf} must be the buffer number of a terminal window. If the
8082 buffer does not exist or is not a terminal window, an empty
8083 list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02008084 {only available when compiled with the |+terminal| feature}
Bram Moolenaar97870002017-07-30 18:28:38 +02008085
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008086term_getjob({buf}) *term_getjob()*
8087 Get the Job associated with terminal window {buf}.
8088 {buf} is used as with |term_getsize()|.
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02008089 Returns |v:null| when there is no job.
Bram Moolenaar45356542017-08-06 17:53:31 +02008090 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02008091
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02008092term_getline({buf}, {row}) *term_getline()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008093 Get a line of text from the terminal window of {buf}.
8094 {buf} is used as with |term_getsize()|.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008095
Bram Moolenaar45356542017-08-06 17:53:31 +02008096 The first line has {row} one. When {row} is "." the cursor
8097 line is used. When {row} is invalid an empty string is
8098 returned.
8099 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02008100
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02008101term_getscrolled({buf}) *term_getscrolled()*
8102 Return the number of lines that scrolled to above the top of
8103 terminal {buf}. This is the offset between the row number
8104 used for |term_getline()| and |getline()|, so that: >
8105 term_getline(buf, N)
8106< is equal to: >
8107 `getline(N + term_getscrolled(buf))
8108< (if that line exists).
8109
8110 {buf} is used as with |term_getsize()|.
8111 {only available when compiled with the |+terminal| feature}
8112
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008113term_getsize({buf}) *term_getsize()*
8114 Get the size of terminal {buf}. Returns a list with two
8115 numbers: [rows, cols]. This is the size of the terminal, not
8116 the window containing the terminal.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008117
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02008118 {buf} must be the buffer number of a terminal window. Use an
8119 empty string for the current buffer. If the buffer does not
8120 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02008121 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008122
Bram Moolenaarb000e322017-07-30 19:38:21 +02008123term_getstatus({buf}) *term_getstatus()*
8124 Get the status of terminal {buf}. This returns a comma
8125 separated list of these items:
8126 running job is running
8127 finished job has finished
Bram Moolenaar45356542017-08-06 17:53:31 +02008128 normal in Terminal-Normal mode
Bram Moolenaarb000e322017-07-30 19:38:21 +02008129 One of "running" or "finished" is always present.
8130
8131 {buf} must be the buffer number of a terminal window. If the
8132 buffer does not exist or is not a terminal window, an empty
8133 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02008134 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02008135
8136term_gettitle({buf}) *term_gettitle()*
8137 Get the title of terminal {buf}. This is the title that the
8138 job in the terminal has set.
8139
8140 {buf} must be the buffer number of a terminal window. If the
8141 buffer does not exist or is not a terminal window, an empty
8142 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02008143 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02008144
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02008145term_gettty({buf} [, {input}]) *term_gettty()*
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02008146 Get the name of the controlling terminal associated with
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02008147 terminal window {buf}. {buf} is used as with |term_getsize()|.
8148
8149 When {input} is omitted or 0, return the name for writing
8150 (stdout). When {input} is 1 return the name for reading
8151 (stdin). On UNIX, both return same name.
Bram Moolenaar45356542017-08-06 17:53:31 +02008152 {only available when compiled with the |+terminal| feature}
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02008153
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02008154term_list() *term_list()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008155 Return a list with the buffer numbers of all buffers for
8156 terminal windows.
Bram Moolenaar45356542017-08-06 17:53:31 +02008157 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008158
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02008159term_scrape({buf}, {row}) *term_scrape()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008160 Get the contents of {row} of terminal screen of {buf}.
8161 For {buf} see |term_getsize()|.
8162
Bram Moolenaar45356542017-08-06 17:53:31 +02008163 The first line has {row} one. When {row} is "." the cursor
8164 line is used. When {row} is invalid an empty string is
8165 returned.
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02008166
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008167 Return a List containing a Dict for each screen cell:
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008168 "chars" character(s) at the cell
8169 "fg" foreground color as #rrggbb
8170 "bg" background color as #rrggbb
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02008171 "attr" attributes of the cell, use |term_getattr()|
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02008172 to get the individual flags
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008173 "width" cell width: 1 or 2
Bram Moolenaar45356542017-08-06 17:53:31 +02008174 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008175
8176term_sendkeys({buf}, {keys}) *term_sendkeys()*
8177 Send keystrokes {keys} to terminal {buf}.
8178 {buf} is used as with |term_getsize()|.
8179
8180 {keys} are translated as key sequences. For example, "\<c-x>"
8181 means the character CTRL-X.
Bram Moolenaar45356542017-08-06 17:53:31 +02008182 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008183
Bram Moolenaar37c64c72017-09-19 22:06:03 +02008184term_setsize({buf}, {expr}) *term_setsize()*
8185 Not implemented yet.
8186 {only available when compiled with the |+terminal| feature}
8187
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008188term_start({cmd}, {options}) *term_start()*
8189 Open a terminal window and run {cmd} in it.
8190
Bram Moolenaar01164a62017-11-02 22:58:42 +01008191 {cmd} can be a string or a List, like with |job_start()|. The
8192 string "NONE" can be used to open a terminal window without
8193 starting a job, the pty of the terminal can be used by a
8194 command like gdb.
8195
Bram Moolenaar08d384f2017-08-11 21:51:23 +02008196 Returns the buffer number of the terminal window. If {cmd}
8197 cannot be executed the window does open and shows an error
8198 message.
8199 If opening the window fails zero is returned.
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008200
Bram Moolenaar78712a72017-08-05 14:50:12 +02008201 {options} are similar to what is used for |job_start()|, see
8202 |job-options|. However, not all options can be used. These
8203 are supported:
8204 all timeout options
8205 "stoponexit"
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008206 "callback", "out_cb", "err_cb"
Bram Moolenaar78712a72017-08-05 14:50:12 +02008207 "exit_cb", "close_cb"
8208 "in_io", "in_top", "in_bot", "in_name", "in_buf"
8209 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
8210 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
8211 However, at least one of stdin, stdout or stderr must be
8212 connected to the terminal. When I/O is connected to the
8213 terminal then the callback function for that part is not used.
8214
Bram Moolenaar08d384f2017-08-11 21:51:23 +02008215 There are extra options:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02008216 "term_name" name to use for the buffer name, instead
8217 of the command name.
Bram Moolenaar08d384f2017-08-11 21:51:23 +02008218 "term_rows" vertical size to use for the terminal,
8219 instead of using 'termsize'
8220 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02008221 instead of using 'termsize'
Bram Moolenaar08d384f2017-08-11 21:51:23 +02008222 "vertical" split the window vertically
Bram Moolenaarda43b612017-08-11 22:27:50 +02008223 "curwin" use the current window, do not split the
8224 window; fails if the current buffer
8225 cannot be |abandon|ed
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008226 "hidden" do not open a window
Bram Moolenaar08d384f2017-08-11 21:51:23 +02008227 "term_finish" What to do when the job is finished:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02008228 "close": close any windows
8229 "open": open window if needed
8230 Note that "open" can be interruptive.
8231 See |term++close| and |term++open|.
Bram Moolenaar37c45832017-08-12 16:01:04 +02008232 "term_opencmd" command to use for opening the window when
8233 "open" is used for "term_finish"; must
8234 have "%d" where the buffer number goes,
8235 e.g. "10split|buffer %d"; when not
8236 specified "botright sbuf %d" is used
Bram Moolenaaref68e4f2017-09-02 16:28:36 +02008237 "eof_chars" Text to send after all buffer lines were
8238 written to the terminal. When not set
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02008239 CTRL-D is used on MS-Windows. For Python
8240 use CTRL-Z or "exit()". For a shell use
8241 "exit". A CR is always added.
Bram Moolenaar37c45832017-08-12 16:01:04 +02008242
Bram Moolenaar45356542017-08-06 17:53:31 +02008243 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008244
Bram Moolenaarf3402b12017-08-06 19:07:08 +02008245term_wait({buf} [, {time}]) *term_wait()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02008246 Wait for pending updates of {buf} to be handled.
8247 {buf} is used as with |term_getsize()|.
Bram Moolenaarf3402b12017-08-06 19:07:08 +02008248 {time} is how long to wait for updates to arrive in msec. If
8249 not set then 10 msec will be used.
Bram Moolenaar45356542017-08-06 17:53:31 +02008250 {only available when compiled with the |+terminal| feature}
Bram Moolenaar574860b2016-05-24 17:33:34 +02008251
Bram Moolenaar8e8df252016-05-25 21:23:21 +02008252test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()*
8253 This is for testing: If the memory allocation with {id} is
8254 called, then decrement {countdown}, and when it reaches zero
8255 let memory allocation fail {repeat} times. When {repeat} is
8256 smaller than one it fails one time.
8257
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02008258test_autochdir() *test_autochdir()*
8259 Set a flag to enable the effect of 'autochdir' before Vim
8260 startup has finished.
Bram Moolenaar8e8df252016-05-25 21:23:21 +02008261
Bram Moolenaar5e80de32017-09-03 15:48:12 +02008262test_feedinput({string}) *test_feedinput()*
8263 Characters in {string} are queued for processing as if they
8264 were typed by the user. This uses a low level input buffer.
8265 This function works only when with |+unix| or GUI is running.
8266
Bram Moolenaar574860b2016-05-24 17:33:34 +02008267test_garbagecollect_now() *test_garbagecollect_now()*
8268 Like garbagecollect(), but executed right away. This must
8269 only be called directly to avoid any structure to exist
8270 internally, and |v:testing| must have been set before calling
8271 any function.
8272
Bram Moolenaare0c31f62017-03-01 15:07:05 +01008273test_ignore_error({expr}) *test_ignore_error()*
8274 Ignore any error containing {expr}. A normal message is given
8275 instead.
8276 This is only meant to be used in tests, where catching the
8277 error with try/catch cannot be used (because it skips over
8278 following code).
8279 {expr} is used literally, not as a pattern.
8280 There is currently no way to revert this.
8281
Bram Moolenaar574860b2016-05-24 17:33:34 +02008282test_null_channel() *test_null_channel()*
8283 Return a Channel that is null. Only useful for testing.
8284 {only available when compiled with the +channel feature}
8285
8286test_null_dict() *test_null_dict()*
8287 Return a Dict that is null. Only useful for testing.
8288
8289test_null_job() *test_null_job()*
8290 Return a Job that is null. Only useful for testing.
8291 {only available when compiled with the +job feature}
8292
8293test_null_list() *test_null_list()*
8294 Return a List that is null. Only useful for testing.
8295
8296test_null_partial() *test_null_partial()*
8297 Return a Partial that is null. Only useful for testing.
8298
8299test_null_string() *test_null_string()*
8300 Return a String that is null. Only useful for testing.
8301
Bram Moolenaar036986f2017-03-16 17:41:02 +01008302test_override({name}, {val}) *test_override()*
8303 Overrides certain parts of Vims internal processing to be able
8304 to run tests. Only to be used for testing Vim!
8305 The override is enabled when {val} is non-zero and removed
8306 when {val} is zero.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008307 Current supported values for name are:
Bram Moolenaar036986f2017-03-16 17:41:02 +01008308
8309 name effect when {val} is non-zero ~
8310 redraw disable the redrawing() function
8311 char_avail disable the char_avail() function
Bram Moolenaar182a17b2017-06-25 20:57:18 +02008312 starting reset the "starting" variable, see below
Bram Moolenaar036986f2017-03-16 17:41:02 +01008313 ALL clear all overrides ({val} is not used)
8314
Bram Moolenaar182a17b2017-06-25 20:57:18 +02008315 "starting" is to be used when a test should behave like
8316 startup was done. Since the tests are run by sourcing a
8317 script the "starting" variable is non-zero. This is usually a
8318 good thing (tests run faster), but sometimes changes behavior
8319 in a way that the test doesn't work properly.
8320 When using: >
8321 call test_override('starting', 1)
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02008322< The value of "starting" is saved. It is restored by: >
Bram Moolenaar182a17b2017-06-25 20:57:18 +02008323 call test_override('starting', 0)
8324
Bram Moolenaarc95a3022016-06-12 23:01:46 +02008325test_settime({expr}) *test_settime()*
8326 Set the time Vim uses internally. Currently only used for
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02008327 timestamps in the history, as they are used in viminfo, and
8328 for undo.
Bram Moolenaar3df01732017-02-17 22:47:16 +01008329 Using a value of 1 makes Vim not sleep after a warning or
8330 error message.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02008331 {expr} must evaluate to a number. When the value is zero the
8332 normal behavior is restored.
Bram Moolenaar574860b2016-05-24 17:33:34 +02008333
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02008334 *timer_info()*
8335timer_info([{id}])
8336 Return a list with information about timers.
8337 When {id} is given only information about this timer is
8338 returned. When timer {id} does not exist an empty list is
8339 returned.
8340 When {id} is omitted information about all timers is returned.
8341
8342 For each timer the information is stored in a Dictionary with
8343 these items:
8344 "id" the timer ID
8345 "time" time the timer was started with
8346 "remaining" time until the timer fires
8347 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +02008348 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02008349 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +02008350 "paused" 1 if the timer is paused, 0 otherwise
8351
8352 {only available when compiled with the |+timers| feature}
8353
8354timer_pause({timer}, {paused}) *timer_pause()*
8355 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +02008356 callback when its time expires. Unpausing a timer may cause
8357 the callback to be invoked almost immediately if enough time
8358 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02008359
8360 Pausing a timer is useful to avoid the callback to be called
8361 for a short time.
8362
8363 If {paused} evaluates to a non-zero Number or a non-empty
8364 String, then the timer is paused, otherwise it is unpaused.
8365 See |non-zero-arg|.
8366
8367 {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02008368
Bram Moolenaardc1f1642016-08-16 18:33:43 +02008369 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +01008370timer_start({time}, {callback} [, {options}])
8371 Create a timer and return the timer ID.
8372
8373 {time} is the waiting time in milliseconds. This is the
8374 minimum time before invoking the callback. When the system is
8375 busy or Vim is not waiting for input the time will be longer.
8376
8377 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +02008378 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +01008379 is the timer ID. The callback is only invoked when Vim is
8380 waiting for input.
8381
8382 {options} is a dictionary. Supported entries:
8383 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +02008384 callback. -1 means forever. When not present
8385 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +02008386 If the timer causes an error three times in a
8387 row the repeat is cancelled. This avoids that
8388 Vim becomes unusable because of all the error
8389 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +01008390
8391 Example: >
8392 func MyHandler(timer)
8393 echo 'Handler called'
8394 endfunc
8395 let timer = timer_start(500, 'MyHandler',
8396 \ {'repeat': 3})
8397< This will invoke MyHandler() three times at 500 msec
8398 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02008399
Bram Moolenaar975b5272016-03-15 23:10:59 +01008400 {only available when compiled with the |+timers| feature}
8401
Bram Moolenaar03602ec2016-03-20 20:57:45 +01008402timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +02008403 Stop a timer. The timer callback will no longer be invoked.
8404 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02008405 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +01008406
Bram Moolenaarb73598e2016-08-07 18:22:53 +02008407 {only available when compiled with the |+timers| feature}
8408
8409timer_stopall() *timer_stopall()*
8410 Stop all timers. The timer callbacks will no longer be
8411 invoked. Useful if some timers is misbehaving. If there are
8412 no timers there is no error.
8413
8414 {only available when compiled with the |+timers| feature}
8415
Bram Moolenaar071d4272004-06-13 20:20:40 +00008416tolower({expr}) *tolower()*
8417 The result is a copy of the String given, with all uppercase
8418 characters turned into lowercase (just like applying |gu| to
8419 the string).
8420
8421toupper({expr}) *toupper()*
8422 The result is a copy of the String given, with all lowercase
8423 characters turned into uppercase (just like applying |gU| to
8424 the string).
8425
Bram Moolenaar8299df92004-07-10 09:47:34 +00008426tr({src}, {fromstr}, {tostr}) *tr()*
8427 The result is a copy of the {src} string with all characters
8428 which appear in {fromstr} replaced by the character in that
8429 position in the {tostr} string. Thus the first character in
8430 {fromstr} is translated into the first character in {tostr}
8431 and so on. Exactly like the unix "tr" command.
8432 This code also deals with multibyte characters properly.
8433
8434 Examples: >
8435 echo tr("hello there", "ht", "HT")
8436< returns "Hello THere" >
8437 echo tr("<blob>", "<>", "{}")
8438< returns "{blob}"
8439
Bram Moolenaar446cb832008-06-24 21:56:24 +00008440trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00008441 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00008442 equal to {expr} as a |Float| (truncate towards zero).
8443 {expr} must evaluate to a |Float| or a |Number|.
8444 Examples: >
8445 echo trunc(1.456)
8446< 1.0 >
8447 echo trunc(-5.456)
8448< -5.0 >
8449 echo trunc(4.0)
8450< 4.0
8451 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008452
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008453 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008454type({expr}) The result is a Number representing the type of {expr}.
8455 Instead of using the number directly, it is better to use the
8456 v:t_ variable that has the value:
8457 Number: 0 |v:t_number|
8458 String: 1 |v:t_string|
8459 Funcref: 2 |v:t_func|
8460 List: 3 |v:t_list|
8461 Dictionary: 4 |v:t_dict|
8462 Float: 5 |v:t_float|
8463 Boolean: 6 |v:t_bool| (v:false and v:true)
8464 None 7 |v:t_none| (v:null and v:none)
8465 Job 8 |v:t_job|
8466 Channel 9 |v:t_channel|
8467 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008468 :if type(myvar) == type(0)
8469 :if type(myvar) == type("")
8470 :if type(myvar) == type(function("tr"))
8471 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00008472 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00008473 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +01008474 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +01008475 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008476< To check if the v:t_ variables exist use this: >
8477 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +00008478
Bram Moolenaara17d4c12010-05-30 18:30:36 +02008479undofile({name}) *undofile()*
8480 Return the name of the undo file that would be used for a file
8481 with name {name} when writing. This uses the 'undodir'
8482 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02008483 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008484 {name} is always expanded to the full path, since that is what
8485 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02008486 If {name} is empty undofile() returns an empty string, since a
8487 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02008488 Useful in combination with |:wundo| and |:rundo|.
8489 When compiled without the +persistent_undo option this always
8490 returns an empty string.
8491
Bram Moolenaara800b422010-06-27 01:15:55 +02008492undotree() *undotree()*
8493 Return the current state of the undo tree in a dictionary with
8494 the following items:
8495 "seq_last" The highest undo sequence number used.
8496 "seq_cur" The sequence number of the current position in
8497 the undo tree. This differs from "seq_last"
8498 when some changes were undone.
8499 "time_cur" Time last used for |:earlier| and related
8500 commands. Use |strftime()| to convert to
8501 something readable.
8502 "save_last" Number of the last file write. Zero when no
8503 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02008504 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008505 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02008506 "synced" Non-zero when the last undo block was synced.
8507 This happens when waiting from input from the
8508 user. See |undo-blocks|.
8509 "entries" A list of dictionaries with information about
8510 undo blocks.
8511
8512 The first item in the "entries" list is the oldest undo item.
8513 Each List item is a Dictionary with these items:
8514 "seq" Undo sequence number. Same as what appears in
8515 |:undolist|.
8516 "time" Timestamp when the change happened. Use
8517 |strftime()| to convert to something readable.
8518 "newhead" Only appears in the item that is the last one
8519 that was added. This marks the last change
8520 and where further changes will be added.
8521 "curhead" Only appears in the item that is the last one
8522 that was undone. This marks the current
8523 position in the undo tree, the block that will
8524 be used by a redo command. When nothing was
8525 undone after the last change this item will
8526 not appear anywhere.
8527 "save" Only appears on the last block before a file
8528 write. The number is the write count. The
8529 first write has number 1, the last one the
8530 "save_last" mentioned above.
8531 "alt" Alternate entry. This is again a List of undo
8532 blocks. Each item may again have an "alt"
8533 item.
8534
Bram Moolenaar327aa022014-03-25 18:24:23 +01008535uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
8536 Remove second and succeeding copies of repeated adjacent
8537 {list} items in-place. Returns {list}. If you want a list
8538 to remain unmodified make a copy first: >
8539 :let newlist = uniq(copy(mylist))
8540< The default compare function uses the string representation of
8541 each item. For the use of {func} and {dict} see |sort()|.
8542
Bram Moolenaar677ee682005-01-27 14:41:15 +00008543values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02008544 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008545 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00008546
8547
Bram Moolenaar071d4272004-06-13 20:20:40 +00008548virtcol({expr}) *virtcol()*
8549 The result is a Number, which is the screen column of the file
8550 position given with {expr}. That is, the last screen position
8551 occupied by the character at that position, when the screen
8552 would be of unlimited width. When there is a <Tab> at the
8553 position, the returned Number will be the column at the end of
8554 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02008555 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00008556 For the byte position use |col()|.
8557 For the use of {expr} see |col()|.
8558 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00008559 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008560 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02008561 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008562 When Virtual editing is active in the current mode, a position
8563 beyond the end of the line can be returned. |'virtualedit'|
8564 The accepted positions are:
8565 . the cursor position
8566 $ the end of the cursor line (the result is the
8567 number of displayed characters in the cursor line
8568 plus one)
8569 'x position of mark x (if the mark is not set, 0 is
8570 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01008571 v In Visual mode: the start of the Visual area (the
8572 cursor is the end). When not in Visual mode
8573 returns the cursor position. Differs from |'<| in
8574 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008575 Note that only marks in the current file can be used.
8576 Examples: >
8577 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
8578 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00008579 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +02008580< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008581 A more advanced example that echoes the maximum length of
8582 all lines: >
8583 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
8584
Bram Moolenaar071d4272004-06-13 20:20:40 +00008585
8586visualmode([expr]) *visualmode()*
8587 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008588 used in the current buffer. Initially it returns an empty
8589 string, but once Visual mode has been used, it returns "v",
8590 "V", or "<CTRL-V>" (a single CTRL-V character) for
8591 character-wise, line-wise, or block-wise Visual mode
8592 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008593 Example: >
8594 :exe "normal " . visualmode()
8595< This enters the same Visual mode as before. It is also useful
8596 in scripts if you wish to act differently depending on the
8597 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008598 If Visual mode is active, use |mode()| to get the Visual mode
8599 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008600 If [expr] is supplied and it evaluates to a non-zero Number or
8601 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008602 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008603
Bram Moolenaar8738fc12013-02-20 17:59:11 +01008604wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008605 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +01008606 otherwise. See 'wildmenu' and 'wildmode'.
8607 This can be used in mappings to handle the 'wildcharm' option
8608 gracefully. (Makes only sense with |mapmode-c| mappings).
8609
8610 For example to make <c-j> work like <down> in wildmode, use: >
8611 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
8612<
8613 (Note, this needs the 'wildcharm' option set appropriately).
8614
8615
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01008616win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02008617 Returns a list with |window-ID|s for windows that contain
8618 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01008619
Bram Moolenaar86edef62016-03-13 18:07:30 +01008620win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02008621 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +01008622 When {win} is missing use the current window.
8623 With {win} this is the window number. The top window has
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008624 number 1. Use `win_getid(winnr())` for the current window.
Bram Moolenaar86edef62016-03-13 18:07:30 +01008625 Without {tab} use the current tab, otherwise the tab with
8626 number {tab}. The first tab has number one.
8627 Return zero if the window cannot be found.
8628
8629win_gotoid({expr}) *win_gotoid()*
8630 Go to window with ID {expr}. This may also change the current
8631 tabpage.
8632 Return 1 if successful, 0 if the window cannot be found.
8633
Bram Moolenaar03413f42016-04-12 21:07:15 +02008634win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +01008635 Return a list with the tab number and window number of window
8636 with ID {expr}: [tabnr, winnr].
8637 Return [0, 0] if the window cannot be found.
8638
8639win_id2win({expr}) *win_id2win()*
8640 Return the window number of window with ID {expr}.
8641 Return 0 if the window cannot be found in the current tabpage.
8642
Bram Moolenaar22044dc2017-12-02 15:43:37 +01008643win_screenpos({nr}) *win_screenpos()*
8644 Return the screen position of window {nr} as a list with two
8645 numbers: [row, col]. The first window always has position
8646 [1, 1].
8647 {nr} can be the window number or the |window-ID|.
8648 Return [0, 0] if the window cannot be found in the current
8649 tabpage.
8650
Bram Moolenaar071d4272004-06-13 20:20:40 +00008651 *winbufnr()*
8652winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +02008653 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +02008654 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02008655 When {nr} is zero, the number of the buffer in the current
8656 window is returned.
8657 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008658 Example: >
8659 :echo "The file in the current window is " . bufname(winbufnr(0))
8660<
8661 *wincol()*
8662wincol() The result is a Number, which is the virtual column of the
8663 cursor in the window. This is counting screen cells from the
8664 left side of the window. The leftmost column is one.
8665
8666winheight({nr}) *winheight()*
8667 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008668 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008669 When {nr} is zero, the height of the current window is
8670 returned. When window {nr} doesn't exist, -1 is returned.
8671 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +02008672 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008673 Examples: >
8674 :echo "The current window has " . winheight(0) . " lines."
8675<
8676 *winline()*
8677winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +02008678 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00008679 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00008680 If the cursor was moved the view on the file will be updated
8681 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008682
8683 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00008684winnr([{arg}]) The result is a Number, which is the number of the current
8685 window. The top window has number 1.
8686 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01008687 last window is returned (the window count). >
8688 let window_count = winnr('$')
8689< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00008690 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008691 If there is no previous window or it is in another tab page 0
8692 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00008693 The number can be used with |CTRL-W_w| and ":wincmd w"
8694 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +01008695 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008696
8697 *winrestcmd()*
8698winrestcmd() Returns a sequence of |:resize| commands that should restore
8699 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008700 are opened or closed and the current window and tab page is
8701 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008702 Example: >
8703 :let cmd = winrestcmd()
8704 :call MessWithWindowSizes()
8705 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008706<
8707 *winrestview()*
8708winrestview({dict})
8709 Uses the |Dictionary| returned by |winsaveview()| to restore
8710 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +02008711 Note: The {dict} does not have to contain all values, that are
8712 returned by |winsaveview()|. If values are missing, those
8713 settings won't be restored. So you can use: >
8714 :call winrestview({'curswant': 4})
8715<
8716 This will only set the curswant value (the column the cursor
8717 wants to move on vertical movements) of the cursor to column 5
8718 (yes, that is 5), while all other settings will remain the
8719 same. This is useful, if you set the cursor position manually.
8720
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008721 If you have changed the values the result is unpredictable.
8722 If the window size changed the result won't be the same.
8723
8724 *winsaveview()*
8725winsaveview() Returns a |Dictionary| that contains information to restore
8726 the view of the current window. Use |winrestview()| to
8727 restore the view.
8728 This is useful if you have a mapping that jumps around in the
8729 buffer and you want to go back to the original view.
8730 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00008731 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +02008732 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008733 The return value includes:
8734 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +02008735 col cursor column (Note: the first column
8736 zero, as opposed to what getpos()
8737 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008738 coladd cursor column offset for 'virtualedit'
8739 curswant column for vertical movement
8740 topline first line in the window
8741 topfill filler lines, only in diff mode
8742 leftcol first column displayed
8743 skipcol columns skipped
8744 Note that no option values are saved.
8745
Bram Moolenaar071d4272004-06-13 20:20:40 +00008746
8747winwidth({nr}) *winwidth()*
8748 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008749 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008750 When {nr} is zero, the width of the current window is
8751 returned. When window {nr} doesn't exist, -1 is returned.
8752 An existing window always has a width of zero or more.
8753 Examples: >
8754 :echo "The current window has " . winwidth(0) . " columns."
8755 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +01008756 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +00008757 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +02008758< For getting the terminal or screen size, see the 'columns'
8759 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02008760
8761
Bram Moolenaared767a22016-01-03 22:49:16 +01008762wordcount() *wordcount()*
8763 The result is a dictionary of byte/chars/word statistics for
8764 the current buffer. This is the same info as provided by
8765 |g_CTRL-G|
8766 The return value includes:
8767 bytes Number of bytes in the buffer
8768 chars Number of chars in the buffer
8769 words Number of words in the buffer
8770 cursor_bytes Number of bytes before cursor position
8771 (not in Visual mode)
8772 cursor_chars Number of chars before cursor position
8773 (not in Visual mode)
8774 cursor_words Number of words before cursor position
8775 (not in Visual mode)
8776 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +02008777 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +01008778 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +02008779 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +02008780 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +02008781 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +01008782
8783
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008784 *writefile()*
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01008785writefile({list}, {fname} [, {flags}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008786 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008787 separated with a NL. Each list item must be a String or
8788 Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01008789 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008790 not be a NL after the last list item. An empty item at the
8791 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01008792
8793 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +02008794 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01008795 :call writefile(["foo"], "event.log", "a")
8796 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +01008797<
8798 When {flags} contains "s" then fsync() is called after writing
8799 the file. This flushes the file to disk, if possible. This
8800 takes more time but avoids losing the file if the system
8801 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +01008802 When {flags} does not contain "S" or "s" then fsync() is
8803 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +01008804 When {flags} contains "S" then fsync() is not called, even
8805 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008806
Bram Moolenaar7567d0b2017-11-16 23:04:15 +01008807 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008808 Inserting CR characters needs to be done before passing {list}
8809 to writefile().
8810 An existing file is overwritten, if possible.
8811 When the write fails -1 is returned, otherwise 0. There is an
8812 error message if the file can't be created or when writing
8813 fails.
8814 Also see |readfile()|.
8815 To copy a file byte for byte: >
8816 :let fl = readfile("foo", "b")
8817 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01008818
8819
8820xor({expr}, {expr}) *xor()*
8821 Bitwise XOR on the two arguments. The arguments are converted
8822 to a number. A List, Dict or Float argument causes an error.
8823 Example: >
8824 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01008825<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01008826
Bram Moolenaar071d4272004-06-13 20:20:40 +00008827
8828 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008829There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +000088301. Features that are only supported when they have been enabled when Vim
8831 was compiled |+feature-list|. Example: >
8832 :if has("cindent")
88332. Features that are only supported when certain conditions have been met.
8834 Example: >
8835 :if has("gui_running")
8836< *has-patch*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020088373. Included patches. The "patch123" feature means that patch 123 has been
8838 included. Note that this form does not check the version of Vim, you need
8839 to inspect |v:version| for that.
8840 Example (checking version 6.2.148 or later): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008841 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02008842< Note that it's possible for patch 147 to be omitted even though 148 is
8843 included.
8844
88454. Beyond a certain version or at a certain version and including a specific
Bram Moolenaarbcb98982014-05-01 14:08:19 +02008846 patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or
8847 later, or it is version 7.4 and patch 237 was included.
8848 Note that this only works for patch 7.4.237 and later, before that you
8849 need to use the example above that checks v:version. Example: >
8850 :if has("patch-7.4.248")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02008851< Note that it's possible for patch 147 to be omitted even though 148 is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008852 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008853
Bram Moolenaard823fa92016-08-12 16:29:27 +02008854Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
8855use: `if exists('+shellslash')`
8856
8857
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02008858acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008859all_builtin_terms Compiled with all builtin terminals enabled.
8860amiga Amiga version of Vim.
8861arabic Compiled with Arabic support |Arabic|.
8862arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00008863autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaare42a6d22017-11-12 19:21:51 +01008864autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008865balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00008866balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008867beos BeOS version of Vim.
8868browse Compiled with |:browse| support, and browse() will
8869 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02008870browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008871builtin_terms Compiled with some builtin terminals.
8872byte_offset Compiled with support for 'o' in 'statusline'
8873cindent Compiled with 'cindent' support.
8874clientserver Compiled with remote invocation support |clientserver|.
8875clipboard Compiled with 'clipboard' support.
8876cmdline_compl Compiled with |cmdline-completion| support.
8877cmdline_hist Compiled with |cmdline-history| support.
8878cmdline_info Compiled with 'showcmd' and 'ruler' support.
8879comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008880compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008881cryptv Compiled with encryption support |encryption|.
8882cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008883debug Compiled with "DEBUG" defined.
8884dialog_con Compiled with console dialog support.
8885dialog_gui Compiled with GUI dialog support.
8886diff Compiled with |vimdiff| and 'diff' support.
8887digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +02008888directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008889dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008890ebcdic Compiled on a machine with ebcdic character set.
8891emacs_tags Compiled with support for Emacs tags.
8892eval Compiled with expression evaluation support. Always
8893 true, of course!
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01008894ex_extra |+ex_extra|, always true now
Bram Moolenaar071d4272004-06-13 20:20:40 +00008895extra_search Compiled with support for |'incsearch'| and
8896 |'hlsearch'|
8897farsi Compiled with Farsi support |farsi|.
8898file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008899filterpipe When 'shelltemp' is off pipes are used for shell
8900 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00008901find_in_path Compiled with support for include file searches
8902 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008903float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008904fname_case Case in file names matters (for Amiga, MS-DOS, and
8905 Windows this is not present).
8906folding Compiled with |folding| support.
8907footer Compiled with GUI footer support. |gui-footer|
8908fork Compiled to use fork()/exec() instead of system().
8909gettext Compiled with message translation |multi-lang|
8910gui Compiled with GUI enabled.
8911gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008912gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008913gui_gtk Compiled with GTK+ GUI (any version).
8914gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +01008915gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008916gui_mac Compiled with Macintosh GUI.
8917gui_motif Compiled with Motif GUI.
8918gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008919gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008920gui_win32 Compiled with MS Windows Win32 GUI.
8921gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008922hangul_input Compiled with Hangul input support. |hangul|
8923iconv Can use iconv() for conversion.
8924insert_expand Compiled with support for CTRL-X expansion commands in
8925 Insert mode.
8926jumplist Compiled with |jumplist| support.
8927keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02008928lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008929langmap Compiled with 'langmap' support.
8930libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +02008931linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
8932 'breakindent' support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008933lispindent Compiled with support for lisp indenting.
8934listcmds Compiled with commands for the buffer list |:files|
8935 and the argument list |arglist|.
8936localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02008937lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +02008938mac Any Macintosh version of Vim cf. osx
8939macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +00008940menu Compiled with support for |:menu|.
8941mksession Compiled with support for |:mksession|.
8942modify_fname Compiled with file name modifiers. |filename-modifiers|
8943mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008944mouse_dec Compiled with support for Dec terminal mouse.
8945mouse_gpm Compiled with support for gpm (Linux console mouse)
8946mouse_netterm Compiled with support for netterm mouse.
8947mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008948mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02008949mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008950mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008951mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008952mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00008953multi_byte Compiled with support for 'encoding'
8954multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008955multi_byte_ime Compiled with support for IME input method.
8956multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00008957mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02008958netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008959netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02008960num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008961ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +02008962osx Compiled for macOS cf. mac
8963osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +02008964packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008965path_extra Compiled with up/downwards search in 'path' and 'tags'
8966perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008967persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008968postscript Compiled with PostScript file printing.
8969printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00008970profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02008971python Compiled with Python 2.x interface. |has-python|
8972python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01008973pythonx Compiled with |python_x| interface. |has-pythonx|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008974qnx QNX version of Vim.
8975quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00008976reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008977rightleft Compiled with 'rightleft' support.
8978ruby Compiled with Ruby interface |ruby|.
8979scrollbind Compiled with 'scrollbind' support.
8980showcmd Compiled with 'showcmd' support.
8981signs Compiled with |:sign| support.
8982smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01008983spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00008984startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008985statusline Compiled with support for 'statusline', 'rulerformat'
8986 and special formats of 'titlestring' and 'iconstring'.
8987sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00008988syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008989syntax_items There are active syntax highlighting items for the
8990 current buffer.
8991system Compiled to use system() instead of fork()/exec().
8992tag_binary Compiled with binary searching in tags files
8993 |tag-binary-search|.
8994tag_old_static Compiled with support for old static tags
8995 |tag-old-static|.
8996tag_any_white Compiled with support for any white characters in tags
8997 files |tag-any-white|.
8998tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +02008999termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009000terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009001terminfo Compiled with terminfo instead of termcap.
9002termresponse Compiled with support for |t_RV| and |v:termresponse|.
9003textobjects Compiled with support for |text-objects|.
9004tgetent Compiled with tgetent support, able to use a termcap
9005 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +01009006timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009007title Compiled with window title support |'title'|.
9008toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +01009009ttyin input is a terminal (tty)
9010ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009011unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +01009012unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaar071d4272004-06-13 20:20:40 +00009013user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009014vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01009015vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01009016 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01009017viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009018virtualedit Compiled with 'virtualedit' option.
9019visual Compiled with Visual mode.
9020visualextra Compiled with extra Visual mode commands.
9021 |blockwise-operators|.
9022vms VMS version of Vim.
9023vreplace Compiled with |gR| and |gr| commands.
9024wildignore Compiled with 'wildignore' option.
9025wildmenu Compiled with 'wildmenu' option.
Bram Moolenaard58e9292011-02-09 17:07:58 +01009026win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
9027 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009028win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01009029win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009030win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01009031winaltkeys Compiled with 'winaltkeys' option.
9032windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009033writebackup Compiled with 'writebackup' default on.
9034xfontset Compiled with X fontset support |xfontset|.
9035xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02009036xpm Compiled with pixmap support.
9037xpm_w32 Compiled with pixmap support for Win32. (Only for
9038 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009039xsmp Compiled with X session management support.
9040xsmp_interact Compiled with interactive X session management support.
9041xterm_clipboard Compiled with support for xterm clipboard.
9042xterm_save Compiled with support for saving and restoring the
9043 xterm screen.
9044x11 Compiled with X11 support.
9045
9046 *string-match*
9047Matching a pattern in a String
9048
9049A regexp pattern as explained at |pattern| is normally used to find a match in
9050the buffer lines. When a pattern is used to find a match in a String, almost
9051everything works in the same way. The difference is that a String is handled
9052like it is one line. When it contains a "\n" character, this is not seen as a
9053line break for the pattern. It can be matched with a "\n" in the pattern, or
9054with ".". Example: >
9055 :let a = "aaaa\nxxxx"
9056 :echo matchstr(a, "..\n..")
9057 aa
9058 xx
9059 :echo matchstr(a, "a.x")
9060 a
9061 x
9062
9063Don't forget that "^" will only match at the first character of the String and
9064"$" at the last character of the string. They don't match after or before a
9065"\n".
9066
9067==============================================================================
90685. Defining functions *user-functions*
9069
9070New functions can be defined. These can be called just like builtin
9071functions. The function executes a sequence of Ex commands. Normal mode
9072commands can be executed with the |:normal| command.
9073
9074The function name must start with an uppercase letter, to avoid confusion with
9075builtin functions. To prevent from using the same name in different scripts
9076avoid obvious, short names. A good habit is to start the function name with
9077the name of the script, e.g., "HTMLcolor()".
9078
Bram Moolenaar92d640f2005-09-05 22:11:52 +00009079It's also possible to use curly braces, see |curly-braces-names|. And the
9080|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009081
9082 *local-function*
9083A function local to a script must start with "s:". A local script function
9084can only be called from within the script and from functions, user commands
9085and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00009086function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00009087instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02009088There are only script-local functions, no buffer-local or window-local
9089functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009090
9091 *:fu* *:function* *E128* *E129* *E123*
9092:fu[nction] List all functions and their arguments.
9093
9094:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009095 {name} can also be a |Dictionary| entry that is a
9096 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009097 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00009098
9099:fu[nction] /{pattern} List functions with a name matching {pattern}.
9100 Example that lists all functions ending with "File": >
9101 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00009102<
9103 *:function-verbose*
9104When 'verbose' is non-zero, listing a function will also display where it was
9105last defined. Example: >
9106
9107 :verbose function SetFileTypeSH
9108 function SetFileTypeSH(name)
9109 Last set from /usr/share/vim/vim-7.0/filetype.vim
9110<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00009111See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00009112
Bram Moolenaarbcb98982014-05-01 14:08:19 +02009113 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02009114:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +01009115 Define a new function by the name {name}. The body of
9116 the function follows in the next lines, until the
9117 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009118
Bram Moolenaar01164a62017-11-02 22:58:42 +01009119 The name must be made of alphanumeric characters and
9120 '_', and must start with a capital or "s:" (see
9121 above). Note that using "b:" or "g:" is not allowed.
9122 (since patch 7.4.260 E884 is given if the function
9123 name has a colon in the name, e.g. for "foo:bar()".
9124 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009125
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009126 {name} can also be a |Dictionary| entry that is a
9127 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009128 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +02009129< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009130 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +02009131 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009132 result is a |Funcref| to a numbered function. The
9133 function can only be used with a |Funcref| and will be
9134 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009135 *E127* *E122*
9136 When a function by this name already exists and [!] is
9137 not used an error message is given. When [!] is used,
9138 an existing function is silently replaced. Unless it
9139 is currently being executed, that is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +02009140 NOTE: Use ! wisely. If used without care it can cause
9141 an existing function to be replaced unexpectedly,
9142 which is hard to debug.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009143
9144 For the {arguments} see |function-argument|.
9145
Bram Moolenaar8d043172014-01-23 14:24:41 +01009146 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009147 When the [range] argument is added, the function is
9148 expected to take care of a range itself. The range is
9149 passed as "a:firstline" and "a:lastline". If [range]
9150 is excluded, ":{range}call" will call the function for
9151 each line in the range, with the cursor on the start
9152 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01009153 The cursor is still moved to the first line of the
9154 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01009155 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009156 When the [abort] argument is added, the function will
9157 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01009158 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00009159 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +02009160 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00009161 local variable "self" will then be set to the
9162 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02009163 *:func-closure* *E932*
9164 When the [closure] argument is added, the function
9165 can access variables and arguments from the outer
9166 scope. This is usually called a closure. In this
9167 example Bar() uses "x" from the scope of Foo(). It
9168 remains referenced even after Foo() returns: >
9169 :function! Foo()
9170 : let x = 0
9171 : function! Bar() closure
9172 : let x += 1
9173 : return x
9174 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02009175 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02009176 :endfunction
9177
9178 :let F = Foo()
9179 :echo F()
9180< 1 >
9181 :echo F()
9182< 2 >
9183 :echo F()
9184< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +00009185
Bram Moolenaar446cb832008-06-24 21:56:24 +00009186 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00009187 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00009188 will not be changed by the function. This also
9189 implies that the effect of |:nohlsearch| is undone
9190 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00009191
Bram Moolenaarf8be4612017-06-23 20:52:40 +02009192 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +02009193:endf[unction] [argument]
9194 The end of a function definition. Best is to put it
9195 on a line by its own, without [argument].
9196
9197 [argument] can be:
9198 | command command to execute next
9199 \n command command to execute next
9200 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +02009201 anything else ignored, warning given when
9202 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +02009203 The support for a following command was added in Vim
9204 8.0.0654, before that any argument was silently
9205 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009206
Bram Moolenaarf8be4612017-06-23 20:52:40 +02009207 To be able to define a function inside an `:execute`
9208 command, use line breaks instead of |:bar|: >
9209 :exe "func Foo()\necho 'foo'\nendfunc"
9210<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02009211 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +02009212:delf[unction][!] {name}
9213 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009214 {name} can also be a |Dictionary| entry that is a
9215 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009216 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +02009217< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009218 function is deleted if there are no more references to
9219 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +02009220 With the ! there is no error if the function does not
9221 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009222 *:retu* *:return* *E133*
9223:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
9224 evaluated and returned as the result of the function.
9225 If "[expr]" is not given, the number 0 is returned.
9226 When a function ends without an explicit ":return",
9227 the number 0 is returned.
9228 Note that there is no check for unreachable lines,
9229 thus there is no warning if commands follow ":return".
9230
9231 If the ":return" is used after a |:try| but before the
9232 matching |:finally| (if present), the commands
9233 following the ":finally" up to the matching |:endtry|
9234 are executed first. This process applies to all
9235 nested ":try"s inside the function. The function
9236 returns at the outermost ":endtry".
9237
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009238 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +02009239An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009240be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009241 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009242Up to 20 arguments can be given, separated by commas. After the named
9243arguments an argument "..." can be specified, which means that more arguments
9244may optionally be following. In the function the extra arguments can be used
9245as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009246can be 0). "a:000" is set to a |List| that contains these arguments. Note
9247that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009248 *E742*
9249The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02009250However, if a composite type is used, such as |List| or |Dictionary| , you can
9251change their contents. Thus you can pass a |List| to a function and have the
9252function add an item to it. If you want to make sure the function cannot
9253change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009254
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009255When not using "...", the number of arguments in a function call must be equal
9256to the number of named arguments. When using "...", the number of arguments
9257may be larger.
9258
9259It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +01009260still supply the () then.
9261
9262It is allowed to define another function inside a function
9263body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009264
9265 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +02009266Inside a function local variables can be used. These will disappear when the
9267function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +00009268
9269Example: >
9270 :function Table(title, ...)
9271 : echohl Title
9272 : echo a:title
9273 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00009274 : echo a:0 . " items:"
9275 : for s in a:000
9276 : echon ' ' . s
9277 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00009278 :endfunction
9279
9280This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00009281 call Table("Table", "line1", "line2")
9282 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009283
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009284To return more than one value, return a |List|: >
9285 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009286 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009287 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00009288 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009289 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00009290 :endfunction
9291
9292This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009293 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009294 :if success == "ok"
9295 : echo div
9296 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009297<
Bram Moolenaar39f05632006-03-19 22:15:26 +00009298 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009299:[range]cal[l] {name}([arguments])
9300 Call a function. The name of the function and its arguments
9301 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009302 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009303 Without a range and for functions that accept a range, the
9304 function is called once. When a range is given the cursor is
9305 positioned at the start of the first line before executing the
9306 function.
9307 When a range is given and the function doesn't handle it
9308 itself, the function is executed for each line in the range,
9309 with the cursor in the first column of that line. The cursor
9310 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +02009311 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00009312 this works:
9313 *function-range-example* >
9314 :function Mynumber(arg)
9315 : echo line(".") . " " . a:arg
9316 :endfunction
9317 :1,5call Mynumber(getline("."))
9318<
9319 The "a:firstline" and "a:lastline" are defined anyway, they
9320 can be used to do something different at the start or end of
9321 the range.
9322
9323 Example of a function that handles the range itself: >
9324
9325 :function Cont() range
9326 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
9327 :endfunction
9328 :4,8call Cont()
9329<
9330 This function inserts the continuation character "\" in front
9331 of all the lines in the range, except the first one.
9332
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009333 When the function returns a composite value it can be further
9334 dereferenced, but the range will not be used then. Example: >
9335 :4,8call GetDict().method()
9336< Here GetDict() gets the range but method() does not.
9337
Bram Moolenaar071d4272004-06-13 20:20:40 +00009338 *E132*
9339The recursiveness of user functions is restricted with the |'maxfuncdepth'|
9340option.
9341
Bram Moolenaar7c626922005-02-07 22:01:03 +00009342
9343AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009344 *autoload-functions*
9345When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00009346only when they are used. There are two methods: with an autocommand and with
9347the "autoload" directory in 'runtimepath'.
9348
9349
9350Using an autocommand ~
9351
Bram Moolenaar05159a02005-02-26 23:04:13 +00009352This is introduced in the user manual, section |41.14|.
9353
Bram Moolenaar7c626922005-02-07 22:01:03 +00009354The autocommand is useful if you have a plugin that is a long Vim script file.
9355You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar58b85342016-08-14 19:54:54 +02009356That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00009357again, setting a variable to skip the |:finish| command.
9358
9359Use the FuncUndefined autocommand event with a pattern that matches the
9360function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009361
9362 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
9363
9364The file "~/vim/bufnetfuncs.vim" should then define functions that start with
9365"BufNet". Also see |FuncUndefined|.
9366
Bram Moolenaar7c626922005-02-07 22:01:03 +00009367
9368Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009369 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00009370This is introduced in the user manual, section |41.15|.
9371
Bram Moolenaar7c626922005-02-07 22:01:03 +00009372Using a script in the "autoload" directory is simpler, but requires using
9373exactly the right file name. A function that can be autoloaded has a name
9374like this: >
9375
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009376 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00009377
9378When such a function is called, and it is not defined yet, Vim will search the
9379"autoload" directories in 'runtimepath' for a script file called
9380"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
9381then define the function like this: >
9382
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009383 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00009384 echo "Done!"
9385 endfunction
9386
Bram Moolenaar60a795a2005-09-16 21:55:43 +00009387The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00009388exactly, and the defined function must have the name exactly as it will be
9389called.
9390
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009391It is possible to use subdirectories. Every # in the function name works like
9392a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00009393
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009394 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00009395
9396Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
9397
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009398This also works when reading a variable that has not been set yet: >
9399
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009400 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009401
Bram Moolenaara5792f52005-11-23 21:25:05 +00009402However, when the autoload script was already loaded it won't be loaded again
9403for an unknown variable.
9404
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009405When assigning a value to such a variable nothing special happens. This can
9406be used to pass settings to the autoload script before it's loaded: >
9407
Bram Moolenaara7fc0102005-05-18 22:17:12 +00009408 :let foo#bar#toggle = 1
9409 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009410
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009411Note that when you make a mistake and call a function that is supposed to be
9412defined in an autoload script, but the script doesn't actually define the
9413function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009414And you will get an error message every time.
9415
9416Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00009417other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00009418Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00009419
Bram Moolenaar433f7c82006-03-21 21:29:36 +00009420Hint: If you distribute a bunch of scripts you can pack them together with the
9421|vimball| utility. Also read the user manual |distribute-script|.
9422
Bram Moolenaar071d4272004-06-13 20:20:40 +00009423==============================================================================
94246. Curly braces names *curly-braces-names*
9425
Bram Moolenaar84f72352012-03-11 15:57:40 +01009426In most places where you can use a variable, you can use a "curly braces name"
9427variable. This is a regular variable name with one or more expressions
9428wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009429 my_{adjective}_variable
9430
9431When Vim encounters this, it evaluates the expression inside the braces, puts
9432that in place of the expression, and re-interprets the whole as a variable
9433name. So in the above example, if the variable "adjective" was set to
9434"noisy", then the reference would be to "my_noisy_variable", whereas if
9435"adjective" was set to "quiet", then it would be to "my_quiet_variable".
9436
9437One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +02009438value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009439 echo my_{&background}_message
9440
9441would output the contents of "my_dark_message" or "my_light_message" depending
9442on the current value of 'background'.
9443
9444You can use multiple brace pairs: >
9445 echo my_{adverb}_{adjective}_message
9446..or even nest them: >
9447 echo my_{ad{end_of_word}}_message
9448where "end_of_word" is either "verb" or "jective".
9449
9450However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009451variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009452 :let foo='a + b'
9453 :echo c{foo}d
9454.. since the result of expansion is "ca + bd", which is not a variable name.
9455
9456 *curly-braces-function-names*
9457You can call and define functions by an evaluated name in a similar way.
9458Example: >
9459 :let func_end='whizz'
9460 :call my_func_{func_end}(parameter)
9461
9462This would call the function "my_func_whizz(parameter)".
9463
Bram Moolenaar84f72352012-03-11 15:57:40 +01009464This does NOT work: >
9465 :let i = 3
9466 :let @{i} = '' " error
9467 :echo @{i} " error
9468
Bram Moolenaar071d4272004-06-13 20:20:40 +00009469==============================================================================
94707. Commands *expression-commands*
9471
9472:let {var-name} = {expr1} *:let* *E18*
9473 Set internal variable {var-name} to the result of the
9474 expression {expr1}. The variable will get the type
9475 from the {expr}. If {var-name} didn't exist yet, it
9476 is created.
9477
Bram Moolenaar13065c42005-01-08 16:08:21 +00009478:let {var-name}[{idx}] = {expr1} *E689*
9479 Set a list item to the result of the expression
9480 {expr1}. {var-name} must refer to a list and {idx}
9481 must be a valid index in that list. For nested list
9482 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009483 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +02009484 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +00009485 can do that like this: >
9486 :let var = var[0:2] . 'X' . var[4:]
9487<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009488 *E711* *E719*
9489:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009490 Set a sequence of items in a |List| to the result of
9491 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009492 correct number of items.
9493 {idx1} can be omitted, zero is used instead.
9494 {idx2} can be omitted, meaning the end of the list.
9495 When the selected range of items is partly past the
9496 end of the list, items will be added.
9497
Bram Moolenaar748bf032005-02-02 23:04:36 +00009498 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009499:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
9500:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
9501:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
9502 These fail if {var} was not set yet and when the type
9503 of {var} and {expr1} don't fit the operator.
9504
9505
Bram Moolenaar071d4272004-06-13 20:20:40 +00009506:let ${env-name} = {expr1} *:let-environment* *:let-$*
9507 Set environment variable {env-name} to the result of
9508 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009509:let ${env-name} .= {expr1}
9510 Append {expr1} to the environment variable {env-name}.
9511 If the environment variable didn't exist yet this
9512 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00009513
9514:let @{reg-name} = {expr1} *:let-register* *:let-@*
9515 Write the result of the expression {expr1} in register
9516 {reg-name}. {reg-name} must be a single letter, and
9517 must be the name of a writable register (see
9518 |registers|). "@@" can be used for the unnamed
9519 register, "@/" for the search pattern.
9520 If the result of {expr1} ends in a <CR> or <NL>, the
9521 register will be linewise, otherwise it will be set to
9522 characterwise.
9523 This can be used to clear the last search pattern: >
9524 :let @/ = ""
9525< This is different from searching for an empty string,
9526 that would match everywhere.
9527
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009528:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +02009529 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009530 register was empty it's like setting it to {expr1}.
9531
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009532:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009533 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009534 expression {expr1}. A String or Number value is
9535 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009536 For an option local to a window or buffer the effect
9537 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00009538 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009539 Example: >
9540 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +01009541< This also works for terminal codes in the form t_xx.
9542 But only for alphanumerical names. Example: >
9543 :let &t_k1 = "\<Esc>[234;"
9544< When the code does not exist yet it will be created as
9545 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009546
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009547:let &{option-name} .= {expr1}
9548 For a string option: Append {expr1} to the value.
9549 Does not insert a comma like |:set+=|.
9550
9551:let &{option-name} += {expr1}
9552:let &{option-name} -= {expr1}
9553 For a number or boolean option: Add or subtract
9554 {expr1}.
9555
Bram Moolenaar071d4272004-06-13 20:20:40 +00009556:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009557:let &l:{option-name} .= {expr1}
9558:let &l:{option-name} += {expr1}
9559:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00009560 Like above, but only set the local value of an option
9561 (if there is one). Works like |:setlocal|.
9562
9563:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009564:let &g:{option-name} .= {expr1}
9565:let &g:{option-name} += {expr1}
9566:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00009567 Like above, but only set the global value of an option
9568 (if there is one). Works like |:setglobal|.
9569
Bram Moolenaar13065c42005-01-08 16:08:21 +00009570:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009571 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009572 the list is assigned to {name1}, the second item to
9573 {name2}, etc.
9574 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009575 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009576 Each name can be one of the items of the ":let"
9577 command as mentioned above.
9578 Example: >
9579 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009580< Detail: {expr1} is evaluated first, then the
9581 assignments are done in sequence. This matters if
9582 {name2} depends on {name1}. Example: >
9583 :let x = [0, 1]
9584 :let i = 0
9585 :let [i, x[i]] = [1, 2]
9586 :echo x
9587< The result is [0, 2].
9588
9589:let [{name1}, {name2}, ...] .= {expr1}
9590:let [{name1}, {name2}, ...] += {expr1}
9591:let [{name1}, {name2}, ...] -= {expr1}
9592 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009593 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009594
9595:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009596 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009597 items than there are names. A list of the remaining
9598 items is assigned to {lastname}. If there are no
9599 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00009600 Example: >
9601 :let [a, b; rest] = ["aval", "bval", 3, 4]
9602<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009603:let [{name}, ..., ; {lastname}] .= {expr1}
9604:let [{name}, ..., ; {lastname}] += {expr1}
9605:let [{name}, ..., ; {lastname}] -= {expr1}
9606 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009607 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02009608
9609 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +02009610:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00009611 variable names may be given. Special names recognized
9612 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00009613 g: global variables
9614 b: local buffer variables
9615 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00009616 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00009617 s: script-local variables
9618 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00009619 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009620
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009621:let List the values of all variables. The type of the
9622 variable is indicated before the value:
9623 <nothing> String
9624 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009625 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00009626
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009627
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009628:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009629 Remove the internal variable {name}. Several variable
9630 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009631 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009632 With [!] no error message is given for non-existing
9633 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009634 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00009635 :unlet list[3] " remove fourth item
9636 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009637< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00009638 :unlet dict['two']
9639 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00009640< This is especially useful to clean up used global
9641 variables and script-local variables (these are not
9642 deleted when the script ends). Function-local
9643 variables are automatically deleted when the function
9644 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009645
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009646:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
9647 Lock the internal variable {name}. Locking means that
9648 it can no longer be changed (until it is unlocked).
9649 A locked variable can be deleted: >
9650 :lockvar v
9651 :let v = 'asdf' " fails!
9652 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +01009653< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009654 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +01009655 error message: "E741: Value is locked: {name}".
9656 If you try to lock or unlock a built-in variable you
9657 get an error message: "E940: Cannot lock or unlock
9658 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009659
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009660 [depth] is relevant when locking a |List| or
9661 |Dictionary|. It specifies how deep the locking goes:
9662 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009663 cannot add or remove items, but can
9664 still change their values.
9665 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009666 the items. If an item is a |List| or
9667 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009668 items, but can still change the
9669 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009670 3 Like 2 but for the |List| /
9671 |Dictionary| in the |List| /
9672 |Dictionary|, one level deeper.
9673 The default [depth] is 2, thus when {name} is a |List|
9674 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009675 *E743*
9676 For unlimited depth use [!] and omit [depth].
9677 However, there is a maximum depth of 100 to catch
9678 loops.
9679
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009680 Note that when two variables refer to the same |List|
9681 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00009682 locked when used through the other variable.
9683 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00009684 :let l = [0, 1, 2, 3]
9685 :let cl = l
9686 :lockvar l
9687 :let cl[1] = 99 " won't work!
9688< You may want to make a copy of a list to avoid this.
9689 See |deepcopy()|.
9690
9691
9692:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
9693 Unlock the internal variable {name}. Does the
9694 opposite of |:lockvar|.
9695
9696
Bram Moolenaar071d4272004-06-13 20:20:40 +00009697:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
9698:en[dif] Execute the commands until the next matching ":else"
9699 or ":endif" if {expr1} evaluates to non-zero.
9700
9701 From Vim version 4.5 until 5.0, every Ex command in
9702 between the ":if" and ":endif" is ignored. These two
9703 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01009704 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00009705 that any ":else" or ":elseif" was ignored, the "else"
9706 part was not executed either.
9707
9708 You can use this to remain compatible with older
9709 versions: >
9710 :if version >= 500
9711 : version-5-specific-commands
9712 :endif
9713< The commands still need to be parsed to find the
9714 "endif". Sometimes an older Vim has a problem with a
9715 new command. For example, ":silent" is recognized as
9716 a ":substitute" command. In that case ":execute" can
9717 avoid problems: >
9718 :if version >= 600
9719 : execute "silent 1,$delete"
9720 :endif
9721<
9722 NOTE: The ":append" and ":insert" commands don't work
9723 properly in between ":if" and ":endif".
9724
9725 *:else* *:el* *E581* *E583*
9726:el[se] Execute the commands until the next matching ":else"
9727 or ":endif" if they previously were not being
9728 executed.
9729
9730 *:elseif* *:elsei* *E582* *E584*
9731:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
9732 is no extra ":endif".
9733
9734:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009735 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009736:endw[hile] Repeat the commands between ":while" and ":endwhile",
9737 as long as {expr1} evaluates to non-zero.
9738 When an error is detected from a command inside the
9739 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00009740 Example: >
9741 :let lnum = 1
9742 :while lnum <= line("$")
9743 :call FixLine(lnum)
9744 :let lnum = lnum + 1
9745 :endwhile
9746<
Bram Moolenaar071d4272004-06-13 20:20:40 +00009747 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00009748 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009749
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00009750:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00009751:endfo[r] *:endfo* *:endfor*
9752 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00009753 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00009754 value of each item.
9755 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00009756 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00009757 Changing {list} inside the loop affects what items are
9758 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00009759 :for item in copy(mylist)
9760< When not making a copy, Vim stores a reference to the
9761 next item in the list, before executing the commands
Bram Moolenaar58b85342016-08-14 19:54:54 +02009762 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00009763 removed without effect. Removing any later item means
9764 it will not be found. Thus the following example
9765 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009766 for item in mylist
9767 call remove(mylist, 0)
9768 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009769< Note that reordering the list (e.g., with sort() or
9770 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +00009771
Bram Moolenaar12805862005-01-05 22:16:17 +00009772:for [{var1}, {var2}, ...] in {listlist}
9773:endfo[r]
9774 Like ":for" above, but each item in {listlist} must be
9775 a list, of which each item is assigned to {var1},
9776 {var2}, etc. Example: >
9777 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
9778 :echo getline(lnum)[col]
9779 :endfor
9780<
Bram Moolenaar071d4272004-06-13 20:20:40 +00009781 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00009782:con[tinue] When used inside a ":while" or ":for" loop, jumps back
9783 to the start of the loop.
9784 If it is used after a |:try| inside the loop but
9785 before the matching |:finally| (if present), the
9786 commands following the ":finally" up to the matching
9787 |:endtry| are executed first. This process applies to
9788 all nested ":try"s inside the loop. The outermost
9789 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009790
9791 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00009792:brea[k] When used inside a ":while" or ":for" loop, skips to
9793 the command after the matching ":endwhile" or
9794 ":endfor".
9795 If it is used after a |:try| inside the loop but
9796 before the matching |:finally| (if present), the
9797 commands following the ":finally" up to the matching
9798 |:endtry| are executed first. This process applies to
9799 all nested ":try"s inside the loop. The outermost
9800 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009801
9802:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
9803:endt[ry] Change the error handling for the commands between
9804 ":try" and ":endtry" including everything being
9805 executed across ":source" commands, function calls,
9806 or autocommand invocations.
9807
9808 When an error or interrupt is detected and there is
9809 a |:finally| command following, execution continues
9810 after the ":finally". Otherwise, or when the
9811 ":endtry" is reached thereafter, the next
9812 (dynamically) surrounding ":try" is checked for
9813 a corresponding ":finally" etc. Then the script
9814 processing is terminated. (Whether a function
9815 definition has an "abort" argument does not matter.)
9816 Example: >
9817 :try | edit too much | finally | echo "cleanup" | endtry
9818 :echo "impossible" " not reached, script terminated above
9819<
9820 Moreover, an error or interrupt (dynamically) inside
9821 ":try" and ":endtry" is converted to an exception. It
9822 can be caught as if it were thrown by a |:throw|
9823 command (see |:catch|). In this case, the script
9824 processing is not terminated.
9825
9826 The value "Vim:Interrupt" is used for an interrupt
9827 exception. An error in a Vim command is converted
9828 to a value of the form "Vim({command}):{errmsg}",
9829 other errors are converted to a value of the form
9830 "Vim:{errmsg}". {command} is the full command name,
9831 and {errmsg} is the message that is displayed if the
9832 error exception is not caught, always beginning with
9833 the error number.
9834 Examples: >
9835 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
9836 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
9837<
9838 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009839:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00009840 |:finally|, or |:endtry| that belongs to the same
9841 |:try| as the ":catch" are executed when an exception
9842 matching {pattern} is being thrown and has not yet
9843 been caught by a previous ":catch". Otherwise, these
9844 commands are skipped.
9845 When {pattern} is omitted all errors are caught.
9846 Examples: >
9847 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
9848 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
9849 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
9850 :catch /^Vim(write):/ " catch all errors in :write
9851 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
9852 :catch /my-exception/ " catch user exception
9853 :catch /.*/ " catch everything
9854 :catch " same as /.*/
9855<
9856 Another character can be used instead of / around the
9857 {pattern}, so long as it does not have a special
9858 meaning (e.g., '|' or '"') and doesn't occur inside
9859 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02009860 Information about the exception is available in
9861 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009862 NOTE: It is not reliable to ":catch" the TEXT of
9863 an error message because it may vary in different
9864 locales.
9865
9866 *:fina* *:finally* *E606* *E607*
9867:fina[lly] The following commands until the matching |:endtry|
9868 are executed whenever the part between the matching
9869 |:try| and the ":finally" is left: either by falling
9870 through to the ":finally" or by a |:continue|,
9871 |:break|, |:finish|, or |:return|, or by an error or
9872 interrupt or exception (see |:throw|).
9873
9874 *:th* *:throw* *E608*
9875:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
9876 If the ":throw" is used after a |:try| but before the
9877 first corresponding |:catch|, commands are skipped
9878 until the first ":catch" matching {expr1} is reached.
9879 If there is no such ":catch" or if the ":throw" is
9880 used after a ":catch" but before the |:finally|, the
9881 commands following the ":finally" (if present) up to
9882 the matching |:endtry| are executed. If the ":throw"
9883 is after the ":finally", commands up to the ":endtry"
9884 are skipped. At the ":endtry", this process applies
9885 again for the next dynamically surrounding ":try"
9886 (which may be found in a calling function or sourcing
9887 script), until a matching ":catch" has been found.
9888 If the exception is not caught, the command processing
9889 is terminated.
9890 Example: >
9891 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01009892< Note that "catch" may need to be on a separate line
9893 for when an error causes the parsing to skip the whole
9894 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009895
9896 *:ec* *:echo*
9897:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
9898 first {expr1} starts on a new line.
9899 Also see |:comment|.
9900 Use "\n" to start a new line. Use "\r" to move the
9901 cursor to the first column.
9902 Uses the highlighting set by the |:echohl| command.
9903 Cannot be followed by a comment.
9904 Example: >
9905 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009906< *:echo-redraw*
9907 A later redraw may make the message disappear again.
9908 And since Vim mostly postpones redrawing until it's
9909 finished with a sequence of commands this happens
9910 quite often. To avoid that a command from before the
9911 ":echo" causes a redraw afterwards (redraws are often
9912 postponed until you type something), force a redraw
9913 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009914 :new | redraw | echo "there is a new window"
9915<
9916 *:echon*
9917:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
9918 |:comment|.
9919 Uses the highlighting set by the |:echohl| command.
9920 Cannot be followed by a comment.
9921 Example: >
9922 :echon "the value of 'shell' is " &shell
9923<
9924 Note the difference between using ":echo", which is a
9925 Vim command, and ":!echo", which is an external shell
9926 command: >
9927 :!echo % --> filename
9928< The arguments of ":!" are expanded, see |:_%|. >
9929 :!echo "%" --> filename or "filename"
9930< Like the previous example. Whether you see the double
9931 quotes or not depends on your 'shell'. >
9932 :echo % --> nothing
9933< The '%' is an illegal character in an expression. >
9934 :echo "%" --> %
9935< This just echoes the '%' character. >
9936 :echo expand("%") --> filename
9937< This calls the expand() function to expand the '%'.
9938
9939 *:echoh* *:echohl*
9940:echoh[l] {name} Use the highlight group {name} for the following
9941 |:echo|, |:echon| and |:echomsg| commands. Also used
9942 for the |input()| prompt. Example: >
9943 :echohl WarningMsg | echo "Don't panic!" | echohl None
9944< Don't forget to set the group back to "None",
9945 otherwise all following echo's will be highlighted.
9946
9947 *:echom* *:echomsg*
9948:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
9949 message in the |message-history|.
9950 Spaces are placed between the arguments as with the
9951 |:echo| command. But unprintable characters are
9952 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009953 The parsing works slightly different from |:echo|,
9954 more like |:execute|. All the expressions are first
9955 evaluated and concatenated before echoing anything.
9956 The expressions must evaluate to a Number or String, a
9957 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009958 Uses the highlighting set by the |:echohl| command.
9959 Example: >
9960 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009961< See |:echo-redraw| to avoid the message disappearing
9962 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009963 *:echoe* *:echoerr*
9964:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
9965 message in the |message-history|. When used in a
9966 script or function the line number will be added.
9967 Spaces are placed between the arguments as with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02009968 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00009969 the message is raised as an error exception instead
9970 (see |try-echoerr|).
9971 Example: >
9972 :echoerr "This script just failed!"
9973< If you just want a highlighted message use |:echohl|.
9974 And to get a beep: >
9975 :exe "normal \<Esc>"
9976<
9977 *:exe* *:execute*
9978:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02009979 of {expr1} as an Ex command.
9980 Multiple arguments are concatenated, with a space in
9981 between. To avoid the extra space use the "."
9982 operator to concatenate strings into one argument.
9983 {expr1} is used as the processed command, command line
9984 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009985 Cannot be followed by a comment.
9986 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02009987 :execute "buffer" nextbuf
9988 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009989<
9990 ":execute" can be used to append a command to commands
9991 that don't accept a '|'. Example: >
9992 :execute '!ls' | echo "theend"
9993
9994< ":execute" is also a nice way to avoid having to type
9995 control characters in a Vim script for a ":normal"
9996 command: >
9997 :execute "normal ixxx\<Esc>"
9998< This has an <Esc> character, see |expr-string|.
9999
Bram Moolenaar446cb832008-06-24 21:56:24 +000010000 Be careful to correctly escape special characters in
10001 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000010002 for Vim commands, |shellescape()| for |:!| commands.
10003 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +000010004 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +010010005 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000010006<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010007 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010010008 starting or ending "if", "while" and "for" does not
10009 always work, because when commands are skipped the
10010 ":execute" is not evaluated and Vim loses track of
10011 where blocks start and end. Also "break" and
10012 "continue" should not be inside ":execute".
10013 This example does not work, because the ":execute" is
10014 not evaluated and Vim does not see the "while", and
10015 gives an error for finding an ":endwhile": >
10016 :if 0
10017 : execute 'while i > 5'
10018 : echo "test"
10019 : endwhile
10020 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000010021<
10022 It is allowed to have a "while" or "if" command
10023 completely in the executed string: >
10024 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
10025<
10026
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010010027 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010028 ":execute", ":echo" and ":echon" cannot be followed by
10029 a comment directly, because they see the '"' as the
10030 start of a string. But, you can use '|' followed by a
10031 comment. Example: >
10032 :echo "foo" | "this is a comment
10033
10034==============================================================================
100358. Exception handling *exception-handling*
10036
10037The Vim script language comprises an exception handling feature. This section
10038explains how it can be used in a Vim script.
10039
10040Exceptions may be raised by Vim on an error or on interrupt, see
10041|catch-errors| and |catch-interrupt|. You can also explicitly throw an
10042exception by using the ":throw" command, see |throw-catch|.
10043
10044
10045TRY CONDITIONALS *try-conditionals*
10046
10047Exceptions can be caught or can cause cleanup code to be executed. You can
10048use a try conditional to specify catch clauses (that catch exceptions) and/or
10049a finally clause (to be executed for cleanup).
10050 A try conditional begins with a |:try| command and ends at the matching
10051|:endtry| command. In between, you can use a |:catch| command to start
10052a catch clause, or a |:finally| command to start a finally clause. There may
10053be none or multiple catch clauses, but there is at most one finally clause,
10054which must not be followed by any catch clauses. The lines before the catch
10055clauses and the finally clause is called a try block. >
10056
10057 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000010058 : ...
10059 : ... TRY BLOCK
10060 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000010061 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000010062 : ...
10063 : ... CATCH CLAUSE
10064 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000010065 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000010066 : ...
10067 : ... CATCH CLAUSE
10068 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000010069 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000010070 : ...
10071 : ... FINALLY CLAUSE
10072 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000010073 :endtry
10074
10075The try conditional allows to watch code for exceptions and to take the
10076appropriate actions. Exceptions from the try block may be caught. Exceptions
10077from the try block and also the catch clauses may cause cleanup actions.
10078 When no exception is thrown during execution of the try block, the control
10079is transferred to the finally clause, if present. After its execution, the
10080script continues with the line following the ":endtry".
10081 When an exception occurs during execution of the try block, the remaining
10082lines in the try block are skipped. The exception is matched against the
10083patterns specified as arguments to the ":catch" commands. The catch clause
10084after the first matching ":catch" is taken, other catch clauses are not
10085executed. The catch clause ends when the next ":catch", ":finally", or
10086":endtry" command is reached - whatever is first. Then, the finally clause
10087(if present) is executed. When the ":endtry" is reached, the script execution
10088continues in the following line as usual.
10089 When an exception that does not match any of the patterns specified by the
10090":catch" commands is thrown in the try block, the exception is not caught by
10091that try conditional and none of the catch clauses is executed. Only the
10092finally clause, if present, is taken. The exception pends during execution of
10093the finally clause. It is resumed at the ":endtry", so that commands after
10094the ":endtry" are not executed and the exception might be caught elsewhere,
10095see |try-nesting|.
10096 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020010097remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000010098not matched against the patterns in any of the ":catch" commands of the same
10099try conditional and none of its catch clauses is taken. If there is, however,
10100a finally clause, it is executed, and the exception pends during its
10101execution. The commands following the ":endtry" are not executed. The new
10102exception might, however, be caught elsewhere, see |try-nesting|.
10103 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020010104thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000010105clause has been taken because of an exception from the try block or one of the
10106catch clauses, the original (pending) exception is discarded. The commands
10107following the ":endtry" are not executed, and the exception from the finally
10108clause is propagated and can be caught elsewhere, see |try-nesting|.
10109
10110The finally clause is also executed, when a ":break" or ":continue" for
10111a ":while" loop enclosing the complete try conditional is executed from the
10112try block or a catch clause. Or when a ":return" or ":finish" is executed
10113from the try block or a catch clause of a try conditional in a function or
10114sourced script, respectively. The ":break", ":continue", ":return", or
10115":finish" pends during execution of the finally clause and is resumed when the
10116":endtry" is reached. It is, however, discarded when an exception is thrown
10117from the finally clause.
10118 When a ":break" or ":continue" for a ":while" loop enclosing the complete
10119try conditional or when a ":return" or ":finish" is encountered in the finally
10120clause, the rest of the finally clause is skipped, and the ":break",
10121":continue", ":return" or ":finish" is executed as usual. If the finally
10122clause has been taken because of an exception or an earlier ":break",
10123":continue", ":return", or ":finish" from the try block or a catch clause,
10124this pending exception or command is discarded.
10125
10126For examples see |throw-catch| and |try-finally|.
10127
10128
10129NESTING OF TRY CONDITIONALS *try-nesting*
10130
10131Try conditionals can be nested arbitrarily. That is, a complete try
10132conditional can be put into the try block, a catch clause, or the finally
10133clause of another try conditional. If the inner try conditional does not
10134catch an exception thrown in its try block or throws a new exception from one
10135of its catch clauses or its finally clause, the outer try conditional is
10136checked according to the rules above. If the inner try conditional is in the
10137try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020010138otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000010139nesting, whether the inner try conditional is directly contained in the outer
10140one, or whether the outer one sources a script or calls a function containing
10141the inner try conditional.
10142
10143When none of the active try conditionals catches an exception, just their
10144finally clauses are executed. Thereafter, the script processing terminates.
10145An error message is displayed in case of an uncaught exception explicitly
10146thrown by a ":throw" command. For uncaught error and interrupt exceptions
10147implicitly raised by Vim, the error message(s) or interrupt message are shown
10148as usual.
10149
10150For examples see |throw-catch|.
10151
10152
10153EXAMINING EXCEPTION HANDLING CODE *except-examine*
10154
10155Exception handling code can get tricky. If you are in doubt what happens, set
10156'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
10157script file. Then you see when an exception is thrown, discarded, caught, or
10158finished. When using a verbosity level of at least 14, things pending in
10159a finally clause are also shown. This information is also given in debug mode
10160(see |debug-scripts|).
10161
10162
10163THROWING AND CATCHING EXCEPTIONS *throw-catch*
10164
10165You can throw any number or string as an exception. Use the |:throw| command
10166and pass the value to be thrown as argument: >
10167 :throw 4711
10168 :throw "string"
10169< *throw-expression*
10170You can also specify an expression argument. The expression is then evaluated
10171first, and the result is thrown: >
10172 :throw 4705 + strlen("string")
10173 :throw strpart("strings", 0, 6)
10174
10175An exception might be thrown during evaluation of the argument of the ":throw"
10176command. Unless it is caught there, the expression evaluation is abandoned.
10177The ":throw" command then does not throw a new exception.
10178 Example: >
10179
10180 :function! Foo(arg)
10181 : try
10182 : throw a:arg
10183 : catch /foo/
10184 : endtry
10185 : return 1
10186 :endfunction
10187 :
10188 :function! Bar()
10189 : echo "in Bar"
10190 : return 4710
10191 :endfunction
10192 :
10193 :throw Foo("arrgh") + Bar()
10194
10195This throws "arrgh", and "in Bar" is not displayed since Bar() is not
10196executed. >
10197 :throw Foo("foo") + Bar()
10198however displays "in Bar" and throws 4711.
10199
10200Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020010201abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000010202exception is then propagated to the caller of the command.
10203 Example: >
10204
10205 :if Foo("arrgh")
10206 : echo "then"
10207 :else
10208 : echo "else"
10209 :endif
10210
10211Here neither of "then" or "else" is displayed.
10212
10213 *catch-order*
10214Exceptions can be caught by a try conditional with one or more |:catch|
10215commands, see |try-conditionals|. The values to be caught by each ":catch"
10216command can be specified as a pattern argument. The subsequent catch clause
10217gets executed when a matching exception is caught.
10218 Example: >
10219
10220 :function! Foo(value)
10221 : try
10222 : throw a:value
10223 : catch /^\d\+$/
10224 : echo "Number thrown"
10225 : catch /.*/
10226 : echo "String thrown"
10227 : endtry
10228 :endfunction
10229 :
10230 :call Foo(0x1267)
10231 :call Foo('string')
10232
10233The first call to Foo() displays "Number thrown", the second "String thrown".
10234An exception is matched against the ":catch" commands in the order they are
10235specified. Only the first match counts. So you should place the more
10236specific ":catch" first. The following order does not make sense: >
10237
10238 : catch /.*/
10239 : echo "String thrown"
10240 : catch /^\d\+$/
10241 : echo "Number thrown"
10242
10243The first ":catch" here matches always, so that the second catch clause is
10244never taken.
10245
10246 *throw-variables*
10247If you catch an exception by a general pattern, you may access the exact value
10248in the variable |v:exception|: >
10249
10250 : catch /^\d\+$/
10251 : echo "Number thrown. Value is" v:exception
10252
10253You may also be interested where an exception was thrown. This is stored in
10254|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
10255exception most recently caught as long it is not finished.
10256 Example: >
10257
10258 :function! Caught()
10259 : if v:exception != ""
10260 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
10261 : else
10262 : echo 'Nothing caught'
10263 : endif
10264 :endfunction
10265 :
10266 :function! Foo()
10267 : try
10268 : try
10269 : try
10270 : throw 4711
10271 : finally
10272 : call Caught()
10273 : endtry
10274 : catch /.*/
10275 : call Caught()
10276 : throw "oops"
10277 : endtry
10278 : catch /.*/
10279 : call Caught()
10280 : finally
10281 : call Caught()
10282 : endtry
10283 :endfunction
10284 :
10285 :call Foo()
10286
10287This displays >
10288
10289 Nothing caught
10290 Caught "4711" in function Foo, line 4
10291 Caught "oops" in function Foo, line 10
10292 Nothing caught
10293
10294A practical example: The following command ":LineNumber" displays the line
10295number in the script or function where it has been used: >
10296
10297 :function! LineNumber()
10298 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
10299 :endfunction
10300 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
10301<
10302 *try-nested*
10303An exception that is not caught by a try conditional can be caught by
10304a surrounding try conditional: >
10305
10306 :try
10307 : try
10308 : throw "foo"
10309 : catch /foobar/
10310 : echo "foobar"
10311 : finally
10312 : echo "inner finally"
10313 : endtry
10314 :catch /foo/
10315 : echo "foo"
10316 :endtry
10317
10318The inner try conditional does not catch the exception, just its finally
10319clause is executed. The exception is then caught by the outer try
10320conditional. The example displays "inner finally" and then "foo".
10321
10322 *throw-from-catch*
10323You can catch an exception and throw a new one to be caught elsewhere from the
10324catch clause: >
10325
10326 :function! Foo()
10327 : throw "foo"
10328 :endfunction
10329 :
10330 :function! Bar()
10331 : try
10332 : call Foo()
10333 : catch /foo/
10334 : echo "Caught foo, throw bar"
10335 : throw "bar"
10336 : endtry
10337 :endfunction
10338 :
10339 :try
10340 : call Bar()
10341 :catch /.*/
10342 : echo "Caught" v:exception
10343 :endtry
10344
10345This displays "Caught foo, throw bar" and then "Caught bar".
10346
10347 *rethrow*
10348There is no real rethrow in the Vim script language, but you may throw
10349"v:exception" instead: >
10350
10351 :function! Bar()
10352 : try
10353 : call Foo()
10354 : catch /.*/
10355 : echo "Rethrow" v:exception
10356 : throw v:exception
10357 : endtry
10358 :endfunction
10359< *try-echoerr*
10360Note that this method cannot be used to "rethrow" Vim error or interrupt
10361exceptions, because it is not possible to fake Vim internal exceptions.
10362Trying so causes an error exception. You should throw your own exception
10363denoting the situation. If you want to cause a Vim error exception containing
10364the original error exception value, you can use the |:echoerr| command: >
10365
10366 :try
10367 : try
10368 : asdf
10369 : catch /.*/
10370 : echoerr v:exception
10371 : endtry
10372 :catch /.*/
10373 : echo v:exception
10374 :endtry
10375
10376This code displays
10377
Bram Moolenaar446cb832008-06-24 21:56:24 +000010378 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000010379
10380
10381CLEANUP CODE *try-finally*
10382
10383Scripts often change global settings and restore them at their end. If the
10384user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020010385an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000010386a script when an error occurs or you explicitly throw an exception without
10387catching it. You can solve these problems by using a try conditional with
10388a finally clause for restoring the settings. Its execution is guaranteed on
10389normal control flow, on error, on an explicit ":throw", and on interrupt.
10390(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020010391to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000010392clause has been executed.)
10393Example: >
10394
10395 :try
10396 : let s:saved_ts = &ts
10397 : set ts=17
10398 :
10399 : " Do the hard work here.
10400 :
10401 :finally
10402 : let &ts = s:saved_ts
10403 : unlet s:saved_ts
10404 :endtry
10405
10406This method should be used locally whenever a function or part of a script
10407changes global settings which need to be restored on failure or normal exit of
10408that function or script part.
10409
10410 *break-finally*
10411Cleanup code works also when the try block or a catch clause is left by
10412a ":continue", ":break", ":return", or ":finish".
10413 Example: >
10414
10415 :let first = 1
10416 :while 1
10417 : try
10418 : if first
10419 : echo "first"
10420 : let first = 0
10421 : continue
10422 : else
10423 : throw "second"
10424 : endif
10425 : catch /.*/
10426 : echo v:exception
10427 : break
10428 : finally
10429 : echo "cleanup"
10430 : endtry
10431 : echo "still in while"
10432 :endwhile
10433 :echo "end"
10434
10435This displays "first", "cleanup", "second", "cleanup", and "end". >
10436
10437 :function! Foo()
10438 : try
10439 : return 4711
10440 : finally
10441 : echo "cleanup\n"
10442 : endtry
10443 : echo "Foo still active"
10444 :endfunction
10445 :
10446 :echo Foo() "returned by Foo"
10447
10448This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020010449extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000010450return value.)
10451
10452 *except-from-finally*
10453Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
10454a finally clause is possible, but not recommended since it abandons the
10455cleanup actions for the try conditional. But, of course, interrupt and error
10456exceptions might get raised from a finally clause.
10457 Example where an error in the finally clause stops an interrupt from
10458working correctly: >
10459
10460 :try
10461 : try
10462 : echo "Press CTRL-C for interrupt"
10463 : while 1
10464 : endwhile
10465 : finally
10466 : unlet novar
10467 : endtry
10468 :catch /novar/
10469 :endtry
10470 :echo "Script still running"
10471 :sleep 1
10472
10473If you need to put commands that could fail into a finally clause, you should
10474think about catching or ignoring the errors in these commands, see
10475|catch-errors| and |ignore-errors|.
10476
10477
10478CATCHING ERRORS *catch-errors*
10479
10480If you want to catch specific errors, you just have to put the code to be
10481watched in a try block and add a catch clause for the error message. The
10482presence of the try conditional causes all errors to be converted to an
10483exception. No message is displayed and |v:errmsg| is not set then. To find
10484the right pattern for the ":catch" command, you have to know how the format of
10485the error exception is.
10486 Error exceptions have the following format: >
10487
10488 Vim({cmdname}):{errmsg}
10489or >
10490 Vim:{errmsg}
10491
10492{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020010493the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000010494when the error occurs outside try conditionals. It always begins with
10495a capital "E", followed by a two or three-digit error number, a colon, and
10496a space.
10497
10498Examples:
10499
10500The command >
10501 :unlet novar
10502normally produces the error message >
10503 E108: No such variable: "novar"
10504which is converted inside try conditionals to an exception >
10505 Vim(unlet):E108: No such variable: "novar"
10506
10507The command >
10508 :dwim
10509normally produces the error message >
10510 E492: Not an editor command: dwim
10511which is converted inside try conditionals to an exception >
10512 Vim:E492: Not an editor command: dwim
10513
10514You can catch all ":unlet" errors by a >
10515 :catch /^Vim(unlet):/
10516or all errors for misspelled command names by a >
10517 :catch /^Vim:E492:/
10518
10519Some error messages may be produced by different commands: >
10520 :function nofunc
10521and >
10522 :delfunction nofunc
10523both produce the error message >
10524 E128: Function name must start with a capital: nofunc
10525which is converted inside try conditionals to an exception >
10526 Vim(function):E128: Function name must start with a capital: nofunc
10527or >
10528 Vim(delfunction):E128: Function name must start with a capital: nofunc
10529respectively. You can catch the error by its number independently on the
10530command that caused it if you use the following pattern: >
10531 :catch /^Vim(\a\+):E128:/
10532
10533Some commands like >
10534 :let x = novar
10535produce multiple error messages, here: >
10536 E121: Undefined variable: novar
10537 E15: Invalid expression: novar
10538Only the first is used for the exception value, since it is the most specific
10539one (see |except-several-errors|). So you can catch it by >
10540 :catch /^Vim(\a\+):E121:/
10541
10542You can catch all errors related to the name "nofunc" by >
10543 :catch /\<nofunc\>/
10544
10545You can catch all Vim errors in the ":write" and ":read" commands by >
10546 :catch /^Vim(\(write\|read\)):E\d\+:/
10547
10548You can catch all Vim errors by the pattern >
10549 :catch /^Vim\((\a\+)\)\=:E\d\+:/
10550<
10551 *catch-text*
10552NOTE: You should never catch the error message text itself: >
10553 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010010554only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000010555a different language by the |:language| command. It is however helpful to
10556cite the message text in a comment: >
10557 :catch /^Vim(\a\+):E108:/ " No such variable
10558
10559
10560IGNORING ERRORS *ignore-errors*
10561
10562You can ignore errors in a specific Vim command by catching them locally: >
10563
10564 :try
10565 : write
10566 :catch
10567 :endtry
10568
10569But you are strongly recommended NOT to use this simple form, since it could
10570catch more than you want. With the ":write" command, some autocommands could
10571be executed and cause errors not related to writing, for instance: >
10572
10573 :au BufWritePre * unlet novar
10574
10575There could even be such errors you are not responsible for as a script
10576writer: a user of your script might have defined such autocommands. You would
10577then hide the error from the user.
10578 It is much better to use >
10579
10580 :try
10581 : write
10582 :catch /^Vim(write):/
10583 :endtry
10584
10585which only catches real write errors. So catch only what you'd like to ignore
10586intentionally.
10587
10588For a single command that does not cause execution of autocommands, you could
10589even suppress the conversion of errors to exceptions by the ":silent!"
10590command: >
10591 :silent! nunmap k
10592This works also when a try conditional is active.
10593
10594
10595CATCHING INTERRUPTS *catch-interrupt*
10596
10597When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020010598the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000010599script is not terminated, then.
10600 Example: >
10601
10602 :function! TASK1()
10603 : sleep 10
10604 :endfunction
10605
10606 :function! TASK2()
10607 : sleep 20
10608 :endfunction
10609
10610 :while 1
10611 : let command = input("Type a command: ")
10612 : try
10613 : if command == ""
10614 : continue
10615 : elseif command == "END"
10616 : break
10617 : elseif command == "TASK1"
10618 : call TASK1()
10619 : elseif command == "TASK2"
10620 : call TASK2()
10621 : else
10622 : echo "\nIllegal command:" command
10623 : continue
10624 : endif
10625 : catch /^Vim:Interrupt$/
10626 : echo "\nCommand interrupted"
10627 : " Caught the interrupt. Continue with next prompt.
10628 : endtry
10629 :endwhile
10630
10631You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020010632a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010633
10634For testing what happens when CTRL-C would be pressed on a specific line in
10635your script, use the debug mode and execute the |>quit| or |>interrupt|
10636command on that line. See |debug-scripts|.
10637
10638
10639CATCHING ALL *catch-all*
10640
10641The commands >
10642
10643 :catch /.*/
10644 :catch //
10645 :catch
10646
10647catch everything, error exceptions, interrupt exceptions and exceptions
10648explicitly thrown by the |:throw| command. This is useful at the top level of
10649a script in order to catch unexpected things.
10650 Example: >
10651
10652 :try
10653 :
10654 : " do the hard work here
10655 :
10656 :catch /MyException/
10657 :
10658 : " handle known problem
10659 :
10660 :catch /^Vim:Interrupt$/
10661 : echo "Script interrupted"
10662 :catch /.*/
10663 : echo "Internal error (" . v:exception . ")"
10664 : echo " - occurred at " . v:throwpoint
10665 :endtry
10666 :" end of script
10667
10668Note: Catching all might catch more things than you want. Thus, you are
10669strongly encouraged to catch only for problems that you can really handle by
10670specifying a pattern argument to the ":catch".
10671 Example: Catching all could make it nearly impossible to interrupt a script
10672by pressing CTRL-C: >
10673
10674 :while 1
10675 : try
10676 : sleep 1
10677 : catch
10678 : endtry
10679 :endwhile
10680
10681
10682EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
10683
10684Exceptions may be used during execution of autocommands. Example: >
10685
10686 :autocmd User x try
10687 :autocmd User x throw "Oops!"
10688 :autocmd User x catch
10689 :autocmd User x echo v:exception
10690 :autocmd User x endtry
10691 :autocmd User x throw "Arrgh!"
10692 :autocmd User x echo "Should not be displayed"
10693 :
10694 :try
10695 : doautocmd User x
10696 :catch
10697 : echo v:exception
10698 :endtry
10699
10700This displays "Oops!" and "Arrgh!".
10701
10702 *except-autocmd-Pre*
10703For some commands, autocommands get executed before the main action of the
10704command takes place. If an exception is thrown and not caught in the sequence
10705of autocommands, the sequence and the command that caused its execution are
10706abandoned and the exception is propagated to the caller of the command.
10707 Example: >
10708
10709 :autocmd BufWritePre * throw "FAIL"
10710 :autocmd BufWritePre * echo "Should not be displayed"
10711 :
10712 :try
10713 : write
10714 :catch
10715 : echo "Caught:" v:exception "from" v:throwpoint
10716 :endtry
10717
10718Here, the ":write" command does not write the file currently being edited (as
10719you can see by checking 'modified'), since the exception from the BufWritePre
10720autocommand abandons the ":write". The exception is then caught and the
10721script displays: >
10722
10723 Caught: FAIL from BufWrite Auto commands for "*"
10724<
10725 *except-autocmd-Post*
10726For some commands, autocommands get executed after the main action of the
10727command has taken place. If this main action fails and the command is inside
10728an active try conditional, the autocommands are skipped and an error exception
10729is thrown that can be caught by the caller of the command.
10730 Example: >
10731
10732 :autocmd BufWritePost * echo "File successfully written!"
10733 :
10734 :try
10735 : write /i/m/p/o/s/s/i/b/l/e
10736 :catch
10737 : echo v:exception
10738 :endtry
10739
10740This just displays: >
10741
10742 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
10743
10744If you really need to execute the autocommands even when the main action
10745fails, trigger the event from the catch clause.
10746 Example: >
10747
10748 :autocmd BufWritePre * set noreadonly
10749 :autocmd BufWritePost * set readonly
10750 :
10751 :try
10752 : write /i/m/p/o/s/s/i/b/l/e
10753 :catch
10754 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
10755 :endtry
10756<
10757You can also use ":silent!": >
10758
10759 :let x = "ok"
10760 :let v:errmsg = ""
10761 :autocmd BufWritePost * if v:errmsg != ""
10762 :autocmd BufWritePost * let x = "after fail"
10763 :autocmd BufWritePost * endif
10764 :try
10765 : silent! write /i/m/p/o/s/s/i/b/l/e
10766 :catch
10767 :endtry
10768 :echo x
10769
10770This displays "after fail".
10771
10772If the main action of the command does not fail, exceptions from the
10773autocommands will be catchable by the caller of the command: >
10774
10775 :autocmd BufWritePost * throw ":-("
10776 :autocmd BufWritePost * echo "Should not be displayed"
10777 :
10778 :try
10779 : write
10780 :catch
10781 : echo v:exception
10782 :endtry
10783<
10784 *except-autocmd-Cmd*
10785For some commands, the normal action can be replaced by a sequence of
10786autocommands. Exceptions from that sequence will be catchable by the caller
10787of the command.
10788 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020010789had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000010790some way. >
10791
10792 :if !exists("cnt")
10793 : let cnt = 0
10794 :
10795 : autocmd BufWriteCmd * if &modified
10796 : autocmd BufWriteCmd * let cnt = cnt + 1
10797 : autocmd BufWriteCmd * if cnt % 3 == 2
10798 : autocmd BufWriteCmd * throw "BufWriteCmdError"
10799 : autocmd BufWriteCmd * endif
10800 : autocmd BufWriteCmd * write | set nomodified
10801 : autocmd BufWriteCmd * if cnt % 3 == 0
10802 : autocmd BufWriteCmd * throw "BufWriteCmdError"
10803 : autocmd BufWriteCmd * endif
10804 : autocmd BufWriteCmd * echo "File successfully written!"
10805 : autocmd BufWriteCmd * endif
10806 :endif
10807 :
10808 :try
10809 : write
10810 :catch /^BufWriteCmdError$/
10811 : if &modified
10812 : echo "Error on writing (file contents not changed)"
10813 : else
10814 : echo "Error after writing"
10815 : endif
10816 :catch /^Vim(write):/
10817 : echo "Error on writing"
10818 :endtry
10819
10820When this script is sourced several times after making changes, it displays
10821first >
10822 File successfully written!
10823then >
10824 Error on writing (file contents not changed)
10825then >
10826 Error after writing
10827etc.
10828
10829 *except-autocmd-ill*
10830You cannot spread a try conditional over autocommands for different events.
10831The following code is ill-formed: >
10832
10833 :autocmd BufWritePre * try
10834 :
10835 :autocmd BufWritePost * catch
10836 :autocmd BufWritePost * echo v:exception
10837 :autocmd BufWritePost * endtry
10838 :
10839 :write
10840
10841
10842EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
10843
10844Some programming languages allow to use hierarchies of exception classes or to
10845pass additional information with the object of an exception class. You can do
10846similar things in Vim.
10847 In order to throw an exception from a hierarchy, just throw the complete
10848class name with the components separated by a colon, for instance throw the
10849string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
10850 When you want to pass additional information with your exception class, add
10851it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
10852for an error when writing "myfile".
10853 With the appropriate patterns in the ":catch" command, you can catch for
10854base classes or derived classes of your hierarchy. Additional information in
10855parentheses can be cut out from |v:exception| with the ":substitute" command.
10856 Example: >
10857
10858 :function! CheckRange(a, func)
10859 : if a:a < 0
10860 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
10861 : endif
10862 :endfunction
10863 :
10864 :function! Add(a, b)
10865 : call CheckRange(a:a, "Add")
10866 : call CheckRange(a:b, "Add")
10867 : let c = a:a + a:b
10868 : if c < 0
10869 : throw "EXCEPT:MATHERR:OVERFLOW"
10870 : endif
10871 : return c
10872 :endfunction
10873 :
10874 :function! Div(a, b)
10875 : call CheckRange(a:a, "Div")
10876 : call CheckRange(a:b, "Div")
10877 : if (a:b == 0)
10878 : throw "EXCEPT:MATHERR:ZERODIV"
10879 : endif
10880 : return a:a / a:b
10881 :endfunction
10882 :
10883 :function! Write(file)
10884 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000010885 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010886 : catch /^Vim(write):/
10887 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
10888 : endtry
10889 :endfunction
10890 :
10891 :try
10892 :
10893 : " something with arithmetics and I/O
10894 :
10895 :catch /^EXCEPT:MATHERR:RANGE/
10896 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
10897 : echo "Range error in" function
10898 :
10899 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
10900 : echo "Math error"
10901 :
10902 :catch /^EXCEPT:IO/
10903 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
10904 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
10905 : if file !~ '^/'
10906 : let file = dir . "/" . file
10907 : endif
10908 : echo 'I/O error for "' . file . '"'
10909 :
10910 :catch /^EXCEPT/
10911 : echo "Unspecified error"
10912 :
10913 :endtry
10914
10915The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
10916a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
10917exceptions with the "Vim" prefix; they are reserved for Vim.
10918 Vim error exceptions are parameterized with the name of the command that
10919failed, if known. See |catch-errors|.
10920
10921
10922PECULIARITIES
10923 *except-compat*
10924The exception handling concept requires that the command sequence causing the
10925exception is aborted immediately and control is transferred to finally clauses
10926and/or a catch clause.
10927
10928In the Vim script language there are cases where scripts and functions
10929continue after an error: in functions without the "abort" flag or in a command
10930after ":silent!", control flow goes to the following line, and outside
10931functions, control flow goes to the line following the outermost ":endwhile"
10932or ":endif". On the other hand, errors should be catchable as exceptions
10933(thus, requiring the immediate abortion).
10934
10935This problem has been solved by converting errors to exceptions and using
10936immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020010937conditional is active. This is no restriction since an (error) exception can
10938be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000010939termination without catching the error, just use a try conditional without
10940catch clause. (You can cause cleanup code being executed before termination
10941by specifying a finally clause.)
10942
10943When no try conditional is active, the usual abortion and continuation
10944behavior is used instead of immediate abortion. This ensures compatibility of
10945scripts written for Vim 6.1 and earlier.
10946
10947However, when sourcing an existing script that does not use exception handling
10948commands (or when calling one of its functions) from inside an active try
10949conditional of a new script, you might change the control flow of the existing
10950script on error. You get the immediate abortion on error and can catch the
10951error in the new script. If however the sourced script suppresses error
10952messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020010953|v:errmsg| if appropriate), its execution path is not changed. The error is
10954not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000010955where this happens is for scripts that don't care about errors and produce
10956error messages. You probably won't want to use such code from your new
10957scripts.
10958
10959 *except-syntax-err*
10960Syntax errors in the exception handling commands are never caught by any of
10961the ":catch" commands of the try conditional they belong to. Its finally
10962clauses, however, is executed.
10963 Example: >
10964
10965 :try
10966 : try
10967 : throw 4711
10968 : catch /\(/
10969 : echo "in catch with syntax error"
10970 : catch
10971 : echo "inner catch-all"
10972 : finally
10973 : echo "inner finally"
10974 : endtry
10975 :catch
10976 : echo 'outer catch-all caught "' . v:exception . '"'
10977 : finally
10978 : echo "outer finally"
10979 :endtry
10980
10981This displays: >
10982 inner finally
10983 outer catch-all caught "Vim(catch):E54: Unmatched \("
10984 outer finally
10985The original exception is discarded and an error exception is raised, instead.
10986
10987 *except-single-line*
10988The ":try", ":catch", ":finally", and ":endtry" commands can be put on
10989a single line, but then syntax errors may make it difficult to recognize the
10990"catch" line, thus you better avoid this.
10991 Example: >
10992 :try | unlet! foo # | catch | endtry
10993raises an error exception for the trailing characters after the ":unlet!"
10994argument, but does not see the ":catch" and ":endtry" commands, so that the
10995error exception is discarded and the "E488: Trailing characters" message gets
10996displayed.
10997
10998 *except-several-errors*
10999When several errors appear in a single command, the first error message is
11000usually the most specific one and therefor converted to the error exception.
11001 Example: >
11002 echo novar
11003causes >
11004 E121: Undefined variable: novar
11005 E15: Invalid expression: novar
11006The value of the error exception inside try conditionals is: >
11007 Vim(echo):E121: Undefined variable: novar
11008< *except-syntax-error*
11009But when a syntax error is detected after a normal error in the same command,
11010the syntax error is used for the exception being thrown.
11011 Example: >
11012 unlet novar #
11013causes >
11014 E108: No such variable: "novar"
11015 E488: Trailing characters
11016The value of the error exception inside try conditionals is: >
11017 Vim(unlet):E488: Trailing characters
11018This is done because the syntax error might change the execution path in a way
11019not intended by the user. Example: >
11020 try
11021 try | unlet novar # | catch | echo v:exception | endtry
11022 catch /.*/
11023 echo "outer catch:" v:exception
11024 endtry
11025This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
11026a "E600: Missing :endtry" error message is given, see |except-single-line|.
11027
11028==============================================================================
110299. Examples *eval-examples*
11030
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011031Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011032>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011033 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011034 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011035 : let n = a:nr
11036 : let r = ""
11037 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011038 : let r = '01'[n % 2] . r
11039 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000011040 : endwhile
11041 : return r
11042 :endfunc
11043
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011044 :" The function String2Bin() converts each character in a string to a
11045 :" binary string, separated with dashes.
11046 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011047 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011048 : for ix in range(strlen(a:str))
11049 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
11050 : endfor
11051 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000011052 :endfunc
11053
11054Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011055 :echo Nr2Bin(32)
11056result: "100000" >
11057 :echo String2Bin("32")
11058result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000011059
11060
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011061Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011062
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011063This example sorts lines with a specific compare function. >
11064
11065 :func SortBuffer()
11066 : let lines = getline(1, '$')
11067 : call sort(lines, function("Strcmp"))
11068 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011069 :endfunction
11070
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011071As a one-liner: >
11072 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000011073
Bram Moolenaar071d4272004-06-13 20:20:40 +000011074
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011075scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011076 *sscanf*
11077There is no sscanf() function in Vim. If you need to extract parts from a
11078line, you can use matchstr() and substitute() to do it. This example shows
11079how to get the file name, line number and column number out of a line like
11080"foobar.txt, 123, 45". >
11081 :" Set up the match bit
11082 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
11083 :"get the part matching the whole expression
11084 :let l = matchstr(line, mx)
11085 :"get each item out of the match
11086 :let file = substitute(l, mx, '\1', '')
11087 :let lnum = substitute(l, mx, '\2', '')
11088 :let col = substitute(l, mx, '\3', '')
11089
11090The input is in the variable "line", the results in the variables "file",
11091"lnum" and "col". (idea from Michael Geddes)
11092
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011093
11094getting the scriptnames in a Dictionary ~
11095 *scriptnames-dictionary*
11096The |:scriptnames| command can be used to get a list of all script files that
11097have been sourced. There is no equivalent function or variable for this
11098(because it's rarely needed). In case you need to manipulate the list this
11099code can be used: >
11100 " Get the output of ":scriptnames" in the scriptnames_output variable.
11101 let scriptnames_output = ''
11102 redir => scriptnames_output
11103 silent scriptnames
11104 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010011105
Bram Moolenaar446cb832008-06-24 21:56:24 +000011106 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011107 " "scripts" dictionary.
11108 let scripts = {}
11109 for line in split(scriptnames_output, "\n")
11110 " Only do non-blank lines.
11111 if line =~ '\S'
11112 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011113 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011114 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000011115 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011116 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000011117 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011118 endif
11119 endfor
11120 unlet scriptnames_output
11121
Bram Moolenaar071d4272004-06-13 20:20:40 +000011122==============================================================================
1112310. No +eval feature *no-eval-feature*
11124
11125When the |+eval| feature was disabled at compile time, none of the expression
11126evaluation commands are available. To prevent this from causing Vim scripts
11127to generate all kinds of errors, the ":if" and ":endif" commands are still
11128recognized, though the argument of the ":if" and everything between the ":if"
11129and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
11130only if the commands are at the start of the line. The ":else" command is not
11131recognized.
11132
11133Example of how to avoid executing commands when the |+eval| feature is
11134missing: >
11135
11136 :if 1
11137 : echo "Expression evaluation is compiled in"
11138 :else
11139 : echo "You will _never_ see this message"
11140 :endif
11141
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020011142To execute a command only when the |+eval| feature is disabled requires a trick,
11143as this example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020011144
11145 silent! while 0
11146 set history=111
11147 silent! endwhile
11148
11149When the |+eval| feature is available the command is skipped because of the
11150"while 0". Without the |+eval| feature the "while 0" is an error, which is
11151silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020011152
Bram Moolenaar071d4272004-06-13 20:20:40 +000011153==============================================================================
1115411. The sandbox *eval-sandbox* *sandbox* *E48*
11155
Bram Moolenaar368373e2010-07-19 20:46:22 +020011156The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
11157'foldtext' options may be evaluated in a sandbox. This means that you are
11158protected from these expressions having nasty side effects. This gives some
11159safety for when these options are set from a modeline. It is also used when
11160the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000011161The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011162
11163These items are not allowed in the sandbox:
11164 - changing the buffer text
11165 - defining or changing mapping, autocommands, functions, user commands
11166 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011167 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011168 - executing a shell command
11169 - reading or writing a file
11170 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000011171 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000011172This is not guaranteed 100% secure, but it should block most attacks.
11173
11174 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000011175:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000011176 option that may have been set from a modeline, e.g.
11177 'foldexpr'.
11178
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000011179 *sandbox-option*
11180A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000011181have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000011182restrictive, thus this only happens when the option was set from an insecure
11183location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000011184- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000011185- while executing in the sandbox
11186- value coming from a modeline
11187
11188Note that when in the sandbox and saving an option value and restoring it, the
11189option will still be marked as it was set in the sandbox.
11190
11191==============================================================================
1119212. Textlock *textlock*
11193
11194In a few situations it is not allowed to change the text in the buffer, jump
11195to another window and some other things that might confuse or break what Vim
11196is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020011197actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000011198happen any moment the mouse cursor is resting at some position.
11199
11200This is not allowed when the textlock is active:
11201 - changing the buffer text
11202 - jumping to another buffer or window
11203 - editing another file
11204 - closing a window or quitting Vim
11205 - etc.
11206
Bram Moolenaardc1f1642016-08-16 18:33:43 +020011207==============================================================================
1120813. Testing *testing*
11209
11210Vim can be tested after building it, usually with "make test".
11211The tests are located in the directory "src/testdir".
11212
11213There are several types of tests added over time:
11214 test33.in oldest, don't add any more
11215 test_something.in old style tests
11216 test_something.vim new style tests
11217
11218 *new-style-testing*
11219New tests should be added as new style tests. These use functions such as
11220|assert_equal()| to keep the test commands and the expected result in one
11221place.
11222 *old-style-testing*
11223In some cases an old style test needs to be used. E.g. when testing Vim
11224without the |+eval| feature.
11225
11226Find more information in the file src/testdir/README.txt.
11227
Bram Moolenaar071d4272004-06-13 20:20:40 +000011228
11229 vim:tw=78:ts=8:ft=help:norl: