blob: 66dbd9a1883c8f4cf148f595b1a0e64331bf67fc [file] [log] [blame]
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02001*eval.txt* For Vim version 7.4. Last change: 2016 Jul 04
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 Moolenaar446cb832008-06-24 21:56:24 +000012done, 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 Moolenaar071d4272004-06-13 20:20:40 +000032
33{Vi does not have any of these commands}
34
35==============================================================================
361. Variables *variables*
37
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000039 *E712*
Bram Moolenaar38a55632016-02-15 22:07:32 +010040There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000041
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020042Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020043 64-bit Number is available only when compiled with the
44 |+num64| feature.
Bram Moolenaard8b02732005-01-14 21:48:43 +000045 Examples: -123 0x10 0177
46
Bram Moolenaar446cb832008-06-24 21:56:24 +000047Float A floating point number. |floating-point-format| *Float*
48 {only when compiled with the |+float| feature}
49 Examples: 123.456 1.15e-6 -1.1e3
50
Bram Moolenaar06481422016-04-30 15:13:38 +020051 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000052String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000053 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000054
Bram Moolenaard8b02732005-01-14 21:48:43 +000055List An ordered sequence of items |List|.
56 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000057
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000058Dictionary An associative, unordered array: Each entry has a key and a
59 value. |Dictionary|
60 Example: {'blue': "#0000ff", 'red': "#ff0000"}
61
Bram Moolenaar835dc632016-02-07 14:27:38 +010062Funcref A reference to a function |Funcref|.
63 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020064 It can be bound to a dictionary and arguments, it then works
65 like a Partial.
66 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010067
Bram Moolenaar02e83b42016-02-21 20:10:26 +010068Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010069
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020070Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010071
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020072Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010073
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000074The Number and String types are converted automatically, depending on how they
75are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000076
77Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020078the Number. Examples:
79 Number 123 --> String "123" ~
80 Number 0 --> String "0" ~
81 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020082 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010083Conversion from a String to a Number is done by converting the first digits to
84a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
85recognized. If the String doesn't start with digits, the result is zero.
86Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020087 String "456" --> Number 456 ~
88 String "6bar" --> Number 6 ~
89 String "foo" --> Number 0 ~
90 String "0xf1" --> Number 241 ~
91 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010092 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020093 String "-8" --> Number -8 ~
94 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000095
96To force conversion from String to Number, add zero to it: >
97 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000098< 64 ~
99
100To avoid a leading zero to cause octal conversion, or for using a different
101base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000102
103For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
104
105Note that in the command >
106 :if "foo"
107"foo" is converted to 0, which means FALSE. To test for a non-empty string,
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200108use empty(): >
109 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100110<
Bram Moolenaar38a55632016-02-15 22:07:32 +0100111 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar835dc632016-02-07 14:27:38 +0100112List, Dictionary, Funcref and Job types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000113
Bram Moolenaar446cb832008-06-24 21:56:24 +0000114 *E805* *E806* *E808*
115When mixing Number and Float the Number is converted to Float. Otherwise
116there is no automatic conversion of Float. You can use str2float() for String
117to Float, printf() for Float to String and float2nr() for Float to Number.
118
Bram Moolenaar38a55632016-02-15 22:07:32 +0100119 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100120When expecting a Float a Number can also be used, but nothing else.
121
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100122 *no-type-checking*
123You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000124
Bram Moolenaar13065c42005-01-08 16:08:21 +0000125
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001261.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000127 *Funcref* *E695* *E718*
Bram Moolenaar446cb832008-06-24 21:56:24 +0000128A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000129in an expression in the place of a function name, before the parenthesis
130around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000131
132 :let Fn = function("MyFunc")
133 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000134< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000135A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200136can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000137cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000138
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000139A special case is defining a function and directly assigning its Funcref to a
140Dictionary entry. Example: >
141 :function dict.init() dict
142 : let self.val = 0
143 :endfunction
144
145The key of the Dictionary can start with a lower case letter. The actual
146function name is not used here. Also see |numbered-function|.
147
148A Funcref can also be used with the |:call| command: >
149 :call Fn()
150 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000151
152The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000153 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000154
155You can use |call()| to invoke a Funcref and use a list variable for the
156arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000157 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200158<
159 *Partial*
160A Funcref optionally binds a Dictionary and/or arguments. This is also called
161a Partial. This is created by passing the Dictionary and/or arguments to
162function(). When calling the function the Dictionary and/or arguments will be
163passed to the function. Example: >
164
165 let Cb = function('Callback', ['foo'], myDict)
166 call Cb()
167
168This will invoke the function as if using: >
169 call myDict.Callback('foo')
170
171This is very useful when passing a function around, e.g. in the arguments of
172|ch_open()|.
173
174Note that binding a function to a Dictionary also happens when the function is
175a member of the Dictionary: >
176
177 let myDict.myFunction = MyFunction
178 call myDict.myFunction()
179
180Here MyFunction() will get myDict passed as "self". This happens when the
181"myFunction" member is accessed. When making assigning "myFunction" to
182otherDict and calling it, it will be bound to otherDict: >
183
184 let otherDict.myFunction = myDict.myFunction
185 call otherDict.myFunction()
186
187Now "self" will be "otherDict". But when the dictionary was bound explicitly
188this won't happen: >
189
190 let myDict.myFunction = function(MyFunction, myDict)
191 let otherDict.myFunction = myDict.myFunction
192 call otherDict.myFunction()
193
194Here "self" will be "myDict", because it was bound explitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000195
196
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001971.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200198 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000199A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar446cb832008-06-24 21:56:24 +0000200can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000201position in the sequence.
202
Bram Moolenaar13065c42005-01-08 16:08:21 +0000203
204List creation ~
205 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000206A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000207Examples: >
208 :let mylist = [1, two, 3, "four"]
209 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000210
Bram Moolenaar446cb832008-06-24 21:56:24 +0000211An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000212List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000213 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000214
215An extra comma after the last item is ignored.
216
Bram Moolenaar13065c42005-01-08 16:08:21 +0000217
218List index ~
219 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000220An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000221after the List. Indexes are zero-based, thus the first item has index zero. >
222 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000223 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000224
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000225When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000226 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000227<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228A negative index is counted from the end. Index -1 refers to the last item in
229the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000230 :let last = mylist[-1] " get the last item: "four"
231
Bram Moolenaar13065c42005-01-08 16:08:21 +0000232To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000233is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000234 :echo get(mylist, idx)
235 :echo get(mylist, idx, "NONE")
236
237
238List concatenation ~
239
240Two lists can be concatenated with the "+" operator: >
241 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000242 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000243
244To prepend or append an item turn the item into a list by putting [] around
245it. To change a list in-place see |list-modification| below.
246
247
248Sublist ~
249
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000250A part of the List can be obtained by specifying the first and last index,
251separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000252 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000253
254Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000255similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000256 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
257 :let shortlist = mylist[2:2] " List with one item: [3]
258 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000259
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000260If the first index is beyond the last item of the List or the second item is
261before the first item, the result is an empty list. There is no error
262message.
263
264If the second index is equal to or greater than the length of the list the
265length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000266 :let mylist = [0, 1, 2, 3]
267 :echo mylist[2:8] " result: [2, 3]
268
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000269NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar446cb832008-06-24 21:56:24 +0000270using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000271mylist[s : e].
272
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000273
Bram Moolenaar13065c42005-01-08 16:08:21 +0000274List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000275 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000276When variable "aa" is a list and you assign it to another variable "bb", both
277variables refer to the same list. Thus changing the list "aa" will also
278change "bb": >
279 :let aa = [1, 2, 3]
280 :let bb = aa
281 :call add(aa, 4)
282 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000283< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000284
285Making a copy of a list is done with the |copy()| function. Using [:] also
286works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000287a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000288 :let aa = [[1, 'a'], 2, 3]
289 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000290 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000291 :let aa[0][1] = 'aaa'
292 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000293< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000294 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000295< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000296
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000297To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000298copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000299
300The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000301List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000302the same value. >
303 :let alist = [1, 2, 3]
304 :let blist = [1, 2, 3]
305 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000306< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000307 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000308< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000309
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000310Note about comparing lists: Two lists are considered equal if they have the
311same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000312exception: When comparing a number with a string they are considered
313different. There is no automatic type conversion, as with using "==" on
314variables. Example: >
315 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000316< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000317 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000318< 0
319
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000320Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000321can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000322
323 :let a = 5
324 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000325 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000326< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000327 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000328< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000329
Bram Moolenaar13065c42005-01-08 16:08:21 +0000330
331List unpack ~
332
333To unpack the items in a list to individual variables, put the variables in
334square brackets, like list items: >
335 :let [var1, var2] = mylist
336
337When the number of variables does not match the number of items in the list
338this produces an error. To handle any extra items from the list append ";"
339and a variable name: >
340 :let [var1, var2; rest] = mylist
341
342This works like: >
343 :let var1 = mylist[0]
344 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000345 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000346
347Except that there is no error if there are only two items. "rest" will be an
348empty list then.
349
350
351List modification ~
352 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000353To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000354 :let list[4] = "four"
355 :let listlist[0][3] = item
356
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000357To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000358modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000359 :let list[3:5] = [3, 4, 5]
360
Bram Moolenaar13065c42005-01-08 16:08:21 +0000361Adding and removing items from a list is done with functions. Here are a few
362examples: >
363 :call insert(list, 'a') " prepend item 'a'
364 :call insert(list, 'a', 3) " insert item 'a' before list[3]
365 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000366 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000367 :call extend(list, [1, 2]) " extend the list with two more items
368 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000369 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000370 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000371 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000372 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000373
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000374Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000375 :call sort(list) " sort a list alphabetically
376 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100377 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000378
Bram Moolenaar13065c42005-01-08 16:08:21 +0000379
380For loop ~
381
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382The |:for| loop executes commands for each item in a list. A variable is set
383to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000384 :for item in mylist
385 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000386 :endfor
387
388This works like: >
389 :let index = 0
390 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000391 : let item = mylist[index]
392 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000393 : let index = index + 1
394 :endwhile
395
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000396If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000397function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000398
Bram Moolenaar446cb832008-06-24 21:56:24 +0000399Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000400requires the argument to be a list of lists. >
401 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
402 : call Doit(lnum, col)
403 :endfor
404
405This works like a |:let| command is done for each list item. Again, the types
406must remain the same to avoid an error.
407
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000408It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000409 :for [i, j; rest] in listlist
410 : call Doit(i, j)
411 : if !empty(rest)
412 : echo "remainder: " . string(rest)
413 : endif
414 :endfor
415
416
417List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000418 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000419Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000420 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000421 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000422 :let l = len(list) " number of items in list
423 :let big = max(list) " maximum value in list
424 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000425 :let xs = count(list, 'x') " count nr of times 'x' appears in list
426 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000427 :let lines = getline(1, 10) " get ten text lines from buffer
428 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000429 :let list = split("a b c") " create list from items in a string
430 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000431 :let s = string(list) " String representation of list
432 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000433
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000434Don't forget that a combination of features can make things simple. For
435example, to add up all the numbers in a list: >
436 :exe 'let sum = ' . join(nrlist, '+')
437
Bram Moolenaar13065c42005-01-08 16:08:21 +0000438
Bram Moolenaard8b02732005-01-14 21:48:43 +00004391.4 Dictionaries ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200440 *dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000441A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000442entry can be located with the key. The entries are stored without a specific
443ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000444
445
446Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000447 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000448A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000449braces. Each entry has a key and a value, separated by a colon. Each key can
450only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000451 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
452 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000453< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000454A key is always a String. You can use a Number, it will be converted to a
455String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000456entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200457Number will be converted to the String '4'. The empty string can be used as a
458key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000459
Bram Moolenaar446cb832008-06-24 21:56:24 +0000460A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000461nested Dictionary: >
462 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
463
464An extra comma after the last entry is ignored.
465
466
467Accessing entries ~
468
469The normal way to access an entry is by putting the key in square brackets: >
470 :let val = mydict["one"]
471 :let mydict["four"] = 4
472
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000473You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000474
475For keys that consist entirely of letters, digits and underscore the following
476form can be used |expr-entry|: >
477 :let val = mydict.one
478 :let mydict.four = 4
479
480Since an entry can be any type, also a List and a Dictionary, the indexing and
481key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000482 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000483
484
485Dictionary to List conversion ~
486
Bram Moolenaar446cb832008-06-24 21:56:24 +0000487You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000488turn the Dictionary into a List and pass it to |:for|.
489
490Most often you want to loop over the keys, using the |keys()| function: >
491 :for key in keys(mydict)
492 : echo key . ': ' . mydict[key]
493 :endfor
494
495The List of keys is unsorted. You may want to sort them first: >
496 :for key in sort(keys(mydict))
497
498To loop over the values use the |values()| function: >
499 :for v in values(mydict)
500 : echo "value: " . v
501 :endfor
502
503If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000504a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000505 :for [key, value] in items(mydict)
506 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000507 :endfor
508
509
510Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000511 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000512Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
513Dictionary. Otherwise, assignment results in referring to the same
514Dictionary: >
515 :let onedict = {'a': 1, 'b': 2}
516 :let adict = onedict
517 :let adict['a'] = 11
518 :echo onedict['a']
519 11
520
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000521Two Dictionaries compare equal if all the key-value pairs compare equal. For
522more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000523
524
525Dictionary modification ~
526 *dict-modification*
527To change an already existing entry of a Dictionary, or to add a new entry,
528use |:let| this way: >
529 :let dict[4] = "four"
530 :let dict['one'] = item
531
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000532Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
533Three ways to remove the entry with key "aaa" from dict: >
534 :let i = remove(dict, 'aaa')
535 :unlet dict.aaa
536 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000537
538Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000539 :call extend(adict, bdict)
540This extends adict with all entries from bdict. Duplicate keys cause entries
541in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000542Note that the order of entries in a Dictionary is irrelevant, thus don't
543expect ":echo adict" to show the items from bdict after the older entries in
544adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000545
546Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000547 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000548This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000549
550
551Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100552 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000553When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000554special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000555 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000556 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000557 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000558 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
559 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000560
561This is like a method in object oriented programming. The entry in the
562Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
563the function was invoked from.
564
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000565It is also possible to add a function without the "dict" attribute as a
566Funcref to a Dictionary, but the "self" variable is not available then.
567
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000568 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000569To avoid the extra name for the function it can be defined and directly
570assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000571 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200572 :function mydict.len()
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 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000576
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000577The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000578that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000579|Funcref|. It will automatically be deleted when there is no |Funcref|
580remaining that refers to it.
581
582It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000583
Bram Moolenaar1affd722010-08-04 17:49:30 +0200584If you get an error for a numbered function, you can find out what it is with
585a trick. Assuming the function is 42, the command is: >
586 :function {42}
587
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000588
589Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000590 *E715*
591Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000592 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
593 :if empty(dict) " TRUE if dict is empty
594 :let l = len(dict) " number of items in dict
595 :let big = max(dict) " maximum value in dict
596 :let small = min(dict) " minimum value in dict
597 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
598 :let s = string(dict) " String representation of dict
599 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000600
601
6021.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000603 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000604If you need to know the type of a variable or expression, use the |type()|
605function.
606
607When the '!' flag is included in the 'viminfo' option, global variables that
608start with an uppercase letter, and don't contain a lowercase letter, are
609stored in the viminfo file |viminfo-file|.
610
611When the 'sessionoptions' option contains "global", global variables that
612start with an uppercase letter and contain at least one lowercase letter are
613stored in the session file |session-file|.
614
615variable name can be stored where ~
616my_var_6 not
617My_Var_6 session file
618MY_VAR_6 viminfo file
619
620
621It's possible to form a variable name with curly braces, see
622|curly-braces-names|.
623
624==============================================================================
6252. Expression syntax *expression-syntax*
626
627Expression syntax summary, from least to most significant:
628
629|expr1| expr2 ? expr1 : expr1 if-then-else
630
631|expr2| expr3 || expr3 .. logical OR
632
633|expr3| expr4 && expr4 .. logical AND
634
635|expr4| expr5 == expr5 equal
636 expr5 != expr5 not equal
637 expr5 > expr5 greater than
638 expr5 >= expr5 greater than or equal
639 expr5 < expr5 smaller than
640 expr5 <= expr5 smaller than or equal
641 expr5 =~ expr5 regexp matches
642 expr5 !~ expr5 regexp doesn't match
643
644 expr5 ==? expr5 equal, ignoring case
645 expr5 ==# expr5 equal, match case
646 etc. As above, append ? for ignoring case, # for
647 matching case
648
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000649 expr5 is expr5 same |List| instance
650 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000651
652|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000653 expr6 - expr6 .. number subtraction
654 expr6 . expr6 .. string concatenation
655
656|expr6| expr7 * expr7 .. number multiplication
657 expr7 / expr7 .. number division
658 expr7 % expr7 .. number modulo
659
660|expr7| ! expr7 logical NOT
661 - expr7 unary minus
662 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000663
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000664|expr8| expr8[expr1] byte of a String or item of a |List|
665 expr8[expr1 : expr1] substring of a String or sublist of a |List|
666 expr8.name entry in a |Dictionary|
667 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000668
669|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000670 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000671 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000672 [expr1, ...] |List|
673 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000674 &option option value
675 (expr1) nested expression
676 variable internal variable
677 va{ria}ble internal variable with curly braces
678 $VAR environment variable
679 @r contents of register 'r'
680 function(expr1, ...) function call
681 func{ti}on(expr1, ...) function call with curly braces
682
683
684".." indicates that the operations in this level can be concatenated.
685Example: >
686 &nu || &list && &shell == "csh"
687
688All expressions within one level are parsed from left to right.
689
690
691expr1 *expr1* *E109*
692-----
693
694expr2 ? expr1 : expr1
695
696The expression before the '?' is evaluated to a number. If it evaluates to
697non-zero, the result is the value of the expression between the '?' and ':',
698otherwise the result is the value of the expression after the ':'.
699Example: >
700 :echo lnum == 1 ? "top" : lnum
701
702Since the first expression is an "expr2", it cannot contain another ?:. The
703other two expressions can, thus allow for recursive use of ?:.
704Example: >
705 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
706
707To keep this readable, using |line-continuation| is suggested: >
708 :echo lnum == 1
709 :\ ? "top"
710 :\ : lnum == 1000
711 :\ ? "last"
712 :\ : lnum
713
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000714You should always put a space before the ':', otherwise it can be mistaken for
715use in a variable such as "a:1".
716
Bram Moolenaar071d4272004-06-13 20:20:40 +0000717
718expr2 and expr3 *expr2* *expr3*
719---------------
720
721 *expr-barbar* *expr-&&*
722The "||" and "&&" operators take one argument on each side. The arguments
723are (converted to) Numbers. The result is:
724
725 input output ~
726n1 n2 n1 || n2 n1 && n2 ~
727zero zero zero zero
728zero non-zero non-zero zero
729non-zero zero non-zero zero
730non-zero non-zero non-zero non-zero
731
732The operators can be concatenated, for example: >
733
734 &nu || &list && &shell == "csh"
735
736Note that "&&" takes precedence over "||", so this has the meaning of: >
737
738 &nu || (&list && &shell == "csh")
739
740Once the result is known, the expression "short-circuits", that is, further
741arguments are not evaluated. This is like what happens in C. For example: >
742
743 let a = 1
744 echo a || b
745
746This is valid even if there is no variable called "b" because "a" is non-zero,
747so the result must be non-zero. Similarly below: >
748
749 echo exists("b") && b == "yes"
750
751This is valid whether "b" has been defined or not. The second clause will
752only be evaluated if "b" has been defined.
753
754
755expr4 *expr4*
756-----
757
758expr5 {cmp} expr5
759
760Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
761if it evaluates to true.
762
Bram Moolenaar446cb832008-06-24 21:56:24 +0000763 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000764 *expr-<* *expr-<=* *expr-=~* *expr-!~*
765 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
766 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
767 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
768 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200769 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
770 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000771 use 'ignorecase' match case ignore case ~
772equal == ==# ==?
773not equal != !=# !=?
774greater than > ># >?
775greater than or equal >= >=# >=?
776smaller than < <# <?
777smaller than or equal <= <=# <=?
778regexp matches =~ =~# =~?
779regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200780same instance is is# is?
781different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000782
783Examples:
784"abc" ==# "Abc" evaluates to 0
785"abc" ==? "Abc" evaluates to 1
786"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
787
Bram Moolenaar13065c42005-01-08 16:08:21 +0000788 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000789A |List| can only be compared with a |List| and only "equal", "not equal" and
790"is" can be used. This compares the values of the list, recursively.
791Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000792
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000793 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000794A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
795equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000796recursively. Ignoring case means case is ignored when comparing item values.
797
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200798 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200799A |Funcref| can only be compared with a |Funcref| and only "equal", "not
800equal", "is" and "isnot" can be used. Case is never ignored. Whether
801arguments or a Dictionary are bound (with a partial) matters. The
802Dictionaries must also be equal (or the same, in case of "is") and the
803arguments must be equal (or the same).
804
805To compare Funcrefs to see if they refer to the same function, ignoring bound
806Dictionary and arguments, use |get()| to get the function name: >
807 if get(Part1, 'name') == get(Part2, 'name')
808 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000809
Bram Moolenaar251e1912011-06-19 05:09:16 +0200810When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
811expressions are referring to the same |List| or |Dictionary| instance. A copy
812of a |List| is different from the original |List|. When using "is" without
813a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
814equivalent to using "not equal". Except that a different type means the
Bram Moolenaar86edef62016-03-13 18:07:30 +0100815values are different: >
816 echo 4 == '4'
817 1
818 echo 4 is '4'
819 0
820 echo 0 is []
821 0
822"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000823
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar86edef62016-03-13 18:07:30 +0100825and the comparison is done on Numbers. This means that: >
826 echo 0 == 'x'
827 1
828because 'x' converted to a Number is zero. However: >
829 echo [0] == ['x']
830 0
831Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000832
833When comparing two Strings, this is done with strcmp() or stricmp(). This
834results in the mathematical difference (comparing byte values), not
835necessarily the alphabetical difference in the local language.
836
Bram Moolenaar446cb832008-06-24 21:56:24 +0000837When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000838'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000839
840When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000841'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
842
843'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000844
845The "=~" and "!~" operators match the lefthand argument with the righthand
846argument, which is used as a pattern. See |pattern| for what a pattern is.
847This matching is always done like 'magic' was set and 'cpoptions' is empty, no
848matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
849portable. To avoid backslashes in the regexp pattern to be doubled, use a
850single-quote string, see |literal-string|.
851Since a string is considered to be a single line, a multi-line pattern
852(containing \n, backslash-n) will not match. However, a literal NL character
853can be matched like an ordinary character. Examples:
854 "foo\nbar" =~ "\n" evaluates to 1
855 "foo\nbar" =~ "\\n" evaluates to 0
856
857
858expr5 and expr6 *expr5* *expr6*
859---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000860expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000861expr6 - expr6 .. Number subtraction *expr--*
862expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000863
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000864For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000865result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000866
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100867expr7 * expr7 .. Number multiplication *expr-star*
868expr7 / expr7 .. Number division *expr-/*
869expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000870
871For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100872For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000873
874Note the difference between "+" and ".":
875 "123" + "456" = 579
876 "123" . "456" = "123456"
877
Bram Moolenaar446cb832008-06-24 21:56:24 +0000878Since '.' has the same precedence as '+' and '-', you need to read: >
879 1 . 90 + 90.0
880As: >
881 (1 . 90) + 90.0
882That works, since the String "190" is automatically converted to the Number
883190, which can be added to the Float 90.0. However: >
884 1 . 90 * 90.0
885Should be read as: >
886 1 . (90 * 90.0)
887Since '.' has lower precedence than '*'. This does NOT work, since this
888attempts to concatenate a Float and a String.
889
890When dividing a Number by zero the result depends on the value:
891 0 / 0 = -0x80000000 (like NaN for Float)
892 >0 / 0 = 0x7fffffff (like positive infinity)
893 <0 / 0 = -0x7fffffff (like negative infinity)
894 (before Vim 7.2 it was always 0x7fffffff)
895
Bram Moolenaar22fcfad2016-07-01 18:17:26 +0200896When 64-bit Number support is enabled:
897 0 / 0 = -0x8000000000000000 (like NaN for Float)
898 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
899 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
900
Bram Moolenaar071d4272004-06-13 20:20:40 +0000901When the righthand side of '%' is zero, the result is 0.
902
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000903None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000904
Bram Moolenaar446cb832008-06-24 21:56:24 +0000905. and % do not work for Float. *E804*
906
Bram Moolenaar071d4272004-06-13 20:20:40 +0000907
908expr7 *expr7*
909-----
910! expr7 logical NOT *expr-!*
911- expr7 unary minus *expr-unary--*
912+ expr7 unary plus *expr-unary-+*
913
914For '!' non-zero becomes zero, zero becomes one.
915For '-' the sign of the number is changed.
916For '+' the number is unchanged.
917
918A String will be converted to a Number first.
919
Bram Moolenaar446cb832008-06-24 21:56:24 +0000920These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000921 !-1 == 0
922 !!8 == 1
923 --9 == 9
924
925
926expr8 *expr8*
927-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000928expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +0200929 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000930If expr8 is a Number or String this results in a String that contains the
931expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100932Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
Bram Moolenaar03413f42016-04-12 21:07:15 +0200933an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000934
Bram Moolenaar256972a2015-12-29 19:10:25 +0100935Index zero gives the first byte. This is like it works in C. Careful:
936text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000937cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000938 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000939
940If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +0100941String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000942compatibility). Use [-1:] to get the last byte.
943
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000944If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000945for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000946error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000947 :let item = mylist[-1] " get last item
948
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000949Generally, if a |List| index is equal to or higher than the length of the
950|List|, or more negative than the length of the |List|, this results in an
951error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000952
Bram Moolenaard8b02732005-01-14 21:48:43 +0000953
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000954expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000955
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000956If expr8 is a Number or String this results in the substring with the bytes
957from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100958expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
959|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000960
961If expr1a is omitted zero is used. If expr1b is omitted the length of the
962string minus one is used.
963
964A negative number can be used to measure from the end of the string. -1 is
965the last character, -2 the last but one, etc.
966
967If an index goes out of range for the string characters are omitted. If
968expr1b is smaller than expr1a the result is an empty string.
969
970Examples: >
971 :let c = name[-1:] " last byte of a string
972 :let c = name[-2:-2] " last but one byte of a string
973 :let s = line(".")[4:] " from the fifth byte to the end
974 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100975<
976 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000977If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000978the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000979just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000980 :let l = mylist[:3] " first four items
981 :let l = mylist[4:4] " List with one item
982 :let l = mylist[:] " shallow copy of a List
983
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000984Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
985error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000986
Bram Moolenaarda440d22016-01-16 21:27:23 +0100987Watch out for confusion between a namespace and a variable followed by a colon
988for a sublist: >
989 mylist[n:] " uses variable n
990 mylist[s:] " uses namespace s:, error!
991
Bram Moolenaard8b02732005-01-14 21:48:43 +0000992
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000993expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000994
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000995If expr8 is a |Dictionary| and it is followed by a dot, then the following
996name will be used as a key in the |Dictionary|. This is just like:
997expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000998
999The name must consist of alphanumeric characters, just like a variable name,
1000but it may start with a number. Curly braces cannot be used.
1001
1002There must not be white space before or after the dot.
1003
1004Examples: >
1005 :let dict = {"one": 1, 2: "two"}
1006 :echo dict.one
1007 :echo dict .2
1008
1009Note that the dot is also used for String concatenation. To avoid confusion
1010always put spaces around the dot for String concatenation.
1011
1012
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001013expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001014
1015When expr8 is a |Funcref| type variable, invoke the function it refers to.
1016
1017
1018
1019 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001020number
1021------
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001022number number constant *expr-number*
1023 *hex-number* *octal-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001024
1025Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
1026
Bram Moolenaar446cb832008-06-24 21:56:24 +00001027 *floating-point-format*
1028Floating point numbers can be written in two forms:
1029
1030 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001031 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001032
1033{N} and {M} are numbers. Both {N} and {M} must be present and can only
1034contain digits.
1035[-+] means there is an optional plus or minus sign.
1036{exp} is the exponent, power of 10.
1037Only a decimal point is accepted, not a comma. No matter what the current
1038locale is.
1039{only when compiled with the |+float| feature}
1040
1041Examples:
1042 123.456
1043 +0.0001
1044 55.0
1045 -0.123
1046 1.234e03
1047 1.0E-6
1048 -3.1416e+88
1049
1050These are INVALID:
1051 3. empty {M}
1052 1e40 missing .{M}
1053
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001054 *float-pi* *float-e*
1055A few useful values to copy&paste: >
1056 :let pi = 3.14159265359
1057 :let e = 2.71828182846
1058
Bram Moolenaar446cb832008-06-24 21:56:24 +00001059Rationale:
1060Before floating point was introduced, the text "123.456" was interpreted as
1061the two numbers "123" and "456", both converted to a string and concatenated,
1062resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001063could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001064incompatibility was accepted in favor of being able to use the normal notation
1065for floating point numbers.
1066
1067 *floating-point-precision*
1068The precision and range of floating points numbers depends on what "double"
1069means in the library Vim was compiled with. There is no way to change this at
1070runtime.
1071
1072The default for displaying a |Float| is to use 6 decimal places, like using
1073printf("%g", f). You can select something else when using the |printf()|
1074function. Example: >
1075 :echo printf('%.15e', atan(1))
1076< 7.853981633974483e-01
1077
1078
Bram Moolenaar071d4272004-06-13 20:20:40 +00001079
Bram Moolenaar979243b2015-06-26 19:35:49 +02001080string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001081------
1082"string" string constant *expr-quote*
1083
1084Note that double quotes are used.
1085
1086A string constant accepts these special characters:
1087\... three-digit octal number (e.g., "\316")
1088\.. two-digit octal number (must be followed by non-digit)
1089\. one-digit octal number (must be followed by non-digit)
1090\x.. byte specified with two hex numbers (e.g., "\x1f")
1091\x. byte specified with one hex number (must be followed by non-hex char)
1092\X.. same as \x..
1093\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001094\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001095 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001096\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001097\b backspace <BS>
1098\e escape <Esc>
1099\f formfeed <FF>
1100\n newline <NL>
1101\r return <CR>
1102\t tab <Tab>
1103\\ backslash
1104\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001105\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1106 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1107 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001108
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001109Note that "\xff" is stored as the byte 255, which may be invalid in some
1110encodings. Use "\u00ff" to store character 255 according to the current value
1111of 'encoding'.
1112
Bram Moolenaar071d4272004-06-13 20:20:40 +00001113Note that "\000" and "\x00" force the end of the string.
1114
1115
1116literal-string *literal-string* *E115*
1117---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001118'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001119
1120Note that single quotes are used.
1121
Bram Moolenaar446cb832008-06-24 21:56:24 +00001122This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001123meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001124
1125Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001126to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001127 if a =~ "\\s*"
1128 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129
1130
1131option *expr-option* *E112* *E113*
1132------
1133&option option value, local value if possible
1134&g:option global option value
1135&l:option local option value
1136
1137Examples: >
1138 echo "tabstop is " . &tabstop
1139 if &insertmode
1140
1141Any option name can be used here. See |options|. When using the local value
1142and there is no buffer-local or window-local value, the global value is used
1143anyway.
1144
1145
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001146register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001147--------
1148@r contents of register 'r'
1149
1150The result is the contents of the named register, as a single string.
1151Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001152register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001153registers.
1154
1155When using the '=' register you get the expression itself, not what it
1156evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001157
1158
1159nesting *expr-nesting* *E110*
1160-------
1161(expr1) nested expression
1162
1163
1164environment variable *expr-env*
1165--------------------
1166$VAR environment variable
1167
1168The String value of any environment variable. When it is not defined, the
1169result is an empty string.
1170 *expr-env-expand*
1171Note that there is a difference between using $VAR directly and using
1172expand("$VAR"). Using it directly will only expand environment variables that
1173are known inside the current Vim session. Using expand() will first try using
1174the environment variables known inside the current Vim session. If that
1175fails, a shell will be used to expand the variable. This can be slow, but it
1176does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001177 :echo $shell
1178 :echo expand("$shell")
1179The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001180variable (if your shell supports it).
1181
1182
1183internal variable *expr-variable*
1184-----------------
1185variable internal variable
1186See below |internal-variables|.
1187
1188
Bram Moolenaar05159a02005-02-26 23:04:13 +00001189function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001190-------------
1191function(expr1, ...) function call
1192See below |functions|.
1193
1194
1195==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011963. Internal variable *internal-variables* *E461*
1197
Bram Moolenaar071d4272004-06-13 20:20:40 +00001198An internal variable name can be made up of letters, digits and '_'. But it
1199cannot start with a digit. It's also possible to use curly braces, see
1200|curly-braces-names|.
1201
1202An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001203An internal variable is explicitly destroyed with the ":unlet" command
1204|:unlet|.
1205Using a name that is not an internal variable or refers to a variable that has
1206been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207
1208There are several name spaces for variables. Which one is to be used is
1209specified by what is prepended:
1210
1211 (nothing) In a function: local to a function; otherwise: global
1212|buffer-variable| b: Local to the current buffer.
1213|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001214|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001215|global-variable| g: Global.
1216|local-variable| l: Local to a function.
1217|script-variable| s: Local to a |:source|'ed Vim script.
1218|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001219|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001221The scope name by itself can be used as a |Dictionary|. For example, to
1222delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001223 :for k in keys(s:)
1224 : unlet s:[k]
1225 :endfor
1226<
Bram Moolenaar531da592013-05-06 05:58:55 +02001227 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001228A variable name that is preceded with "b:" is local to the current buffer.
1229Thus you can have several "b:foo" variables, one for each buffer.
1230This kind of variable is deleted when the buffer is wiped out or deleted with
1231|:bdelete|.
1232
1233One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001234 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001235b:changedtick The total number of changes to the current buffer. It is
1236 incremented for each change. An undo command is also a change
1237 in this case. This can be used to perform an action only when
1238 the buffer has changed. Example: >
1239 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001240 : let my_changedtick = b:changedtick
1241 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001242 :endif
1243<
Bram Moolenaar531da592013-05-06 05:58:55 +02001244 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001245A variable name that is preceded with "w:" is local to the current window. It
1246is deleted when the window is closed.
1247
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001248 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001249A variable name that is preceded with "t:" is local to the current tab page,
1250It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001251without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001252
Bram Moolenaar531da592013-05-06 05:58:55 +02001253 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001254Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001255access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001256place if you like.
1257
Bram Moolenaar531da592013-05-06 05:58:55 +02001258 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001259Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001260But you can also prepend "l:" if you like. However, without prepending "l:"
1261you may run into reserved variable names. For example "count". By itself it
1262refers to "v:count". Using "l:count" you can have a local variable with the
1263same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001264
1265 *script-variable* *s:var*
1266In a Vim script variables starting with "s:" can be used. They cannot be
1267accessed from outside of the scripts, thus are local to the script.
1268
1269They can be used in:
1270- commands executed while the script is sourced
1271- functions defined in the script
1272- autocommands defined in the script
1273- functions and autocommands defined in functions and autocommands which were
1274 defined in the script (recursively)
1275- user defined commands defined in the script
1276Thus not in:
1277- other scripts sourced from this one
1278- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001279- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001280- etc.
1281
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001282Script variables can be used to avoid conflicts with global variable names.
1283Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001284
1285 let s:counter = 0
1286 function MyCounter()
1287 let s:counter = s:counter + 1
1288 echo s:counter
1289 endfunction
1290 command Tick call MyCounter()
1291
1292You can now invoke "Tick" from any script, and the "s:counter" variable in
1293that script will not be changed, only the "s:counter" in the script where
1294"Tick" was defined is used.
1295
1296Another example that does the same: >
1297
1298 let s:counter = 0
1299 command Tick let s:counter = s:counter + 1 | echo s:counter
1300
1301When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001302script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001303defined.
1304
1305The script variables are also available when a function is defined inside a
1306function that is defined in a script. Example: >
1307
1308 let s:counter = 0
1309 function StartCounting(incr)
1310 if a:incr
1311 function MyCounter()
1312 let s:counter = s:counter + 1
1313 endfunction
1314 else
1315 function MyCounter()
1316 let s:counter = s:counter - 1
1317 endfunction
1318 endif
1319 endfunction
1320
1321This defines the MyCounter() function either for counting up or counting down
1322when calling StartCounting(). It doesn't matter from where StartCounting() is
1323called, the s:counter variable will be accessible in MyCounter().
1324
1325When the same script is sourced again it will use the same script variables.
1326They will remain valid as long as Vim is running. This can be used to
1327maintain a counter: >
1328
1329 if !exists("s:counter")
1330 let s:counter = 1
1331 echo "script executed for the first time"
1332 else
1333 let s:counter = s:counter + 1
1334 echo "script executed " . s:counter . " times now"
1335 endif
1336
1337Note that this means that filetype plugins don't get a different set of script
1338variables for each buffer. Use local buffer variables instead |b:var|.
1339
1340
Bram Moolenaar531da592013-05-06 05:58:55 +02001341Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001342
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001343 *v:beval_col* *beval_col-variable*
1344v:beval_col The number of the column, over which the mouse pointer is.
1345 This is the byte index in the |v:beval_lnum| line.
1346 Only valid while evaluating the 'balloonexpr' option.
1347
1348 *v:beval_bufnr* *beval_bufnr-variable*
1349v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1350 valid while evaluating the 'balloonexpr' option.
1351
1352 *v:beval_lnum* *beval_lnum-variable*
1353v:beval_lnum The number of the line, over which the mouse pointer is. Only
1354 valid while evaluating the 'balloonexpr' option.
1355
1356 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001357v:beval_text The text under or after the mouse pointer. Usually a word as
1358 it is useful for debugging a C program. 'iskeyword' applies,
1359 but a dot and "->" before the position is included. When on a
1360 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001361 word before it. When on a Visual area within one line the
1362 highlighted text is used.
1363 Only valid while evaluating the 'balloonexpr' option.
1364
1365 *v:beval_winnr* *beval_winnr-variable*
1366v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001367 valid while evaluating the 'balloonexpr' option. The first
1368 window has number zero (unlike most other places where a
1369 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001370
Bram Moolenaar511972d2016-06-04 18:09:59 +02001371 *v:beval_winid* *beval_winid-variable*
1372v:beval_winid The window ID of the window, over which the mouse pointer is.
1373 Otherwise like v:beval_winnr.
1374
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001375 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001376v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001377 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001378 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001379
Bram Moolenaar071d4272004-06-13 20:20:40 +00001380 *v:charconvert_from* *charconvert_from-variable*
1381v:charconvert_from
1382 The name of the character encoding of a file to be converted.
1383 Only valid while evaluating the 'charconvert' option.
1384
1385 *v:charconvert_to* *charconvert_to-variable*
1386v:charconvert_to
1387 The name of the character encoding of a file after conversion.
1388 Only valid while evaluating the 'charconvert' option.
1389
1390 *v:cmdarg* *cmdarg-variable*
1391v:cmdarg This variable is used for two purposes:
1392 1. The extra arguments given to a file read/write command.
1393 Currently these are "++enc=" and "++ff=". This variable is
1394 set before an autocommand event for a file read/write
1395 command is triggered. There is a leading space to make it
1396 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001397 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001398 included here, because it will be executed anyway.
1399 2. When printing a PostScript file with ":hardcopy" this is
1400 the argument for the ":hardcopy" command. This can be used
1401 in 'printexpr'.
1402
1403 *v:cmdbang* *cmdbang-variable*
1404v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1405 was used the value is 1, otherwise it is 0. Note that this
1406 can only be used in autocommands. For user commands |<bang>|
1407 can be used.
1408
Bram Moolenaar42a45122015-07-10 17:56:23 +02001409 *v:completed_item* *completed_item-variable*
1410v:completed_item
1411 |Dictionary| containing the |complete-items| for the most
1412 recently completed word after |CompleteDone|. The
1413 |Dictionary| is empty if the completion failed.
1414
Bram Moolenaar071d4272004-06-13 20:20:40 +00001415 *v:count* *count-variable*
1416v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001417 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001418 :map _x :<C-U>echo "the count is " . v:count<CR>
1419< Note: The <C-U> is required to remove the line range that you
1420 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001421 When there are two counts, as in "3d2w", they are multiplied,
1422 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001423 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424 "count" also works, for backwards compatibility.
1425
1426 *v:count1* *count1-variable*
1427v:count1 Just like "v:count", but defaults to one when no count is
1428 used.
1429
1430 *v:ctype* *ctype-variable*
1431v:ctype The current locale setting for characters of the runtime
1432 environment. This allows Vim scripts to be aware of the
1433 current locale encoding. Technical: it's the value of
1434 LC_CTYPE. When not using a locale the value is "C".
1435 This variable can not be set directly, use the |:language|
1436 command.
1437 See |multi-lang|.
1438
1439 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001440v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001441 one. When multiple signals are caught the number increases.
1442 Can be used in an autocommand to check if Vim didn't
1443 terminate normally. {only works on Unix}
1444 Example: >
1445 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001446< Note: if another deadly signal is caught when v:dying is one,
1447 VimLeave autocommands will not be executed.
1448
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449 *v:errmsg* *errmsg-variable*
1450v:errmsg Last given error message. It's allowed to set this variable.
1451 Example: >
1452 :let v:errmsg = ""
1453 :silent! next
1454 :if v:errmsg != ""
1455 : ... handle error
1456< "errmsg" also works, for backwards compatibility.
1457
Bram Moolenaar43345542015-11-29 17:35:35 +01001458 *v:errors* *errors-variable*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001459v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001460 This is a list of strings.
1461 The assert functions append an item when an assert fails.
1462 To remove old results make it empty: >
1463 :let v:errors = []
1464< If v:errors is set to anything but a list it is made an empty
1465 list by the assert function.
1466
Bram Moolenaar071d4272004-06-13 20:20:40 +00001467 *v:exception* *exception-variable*
1468v:exception The value of the exception most recently caught and not
1469 finished. See also |v:throwpoint| and |throw-variables|.
1470 Example: >
1471 :try
1472 : throw "oops"
1473 :catch /.*/
1474 : echo "caught" v:exception
1475 :endtry
1476< Output: "caught oops".
1477
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001478 *v:false* *false-variable*
1479v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001480 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001481 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001482 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001483< v:false ~
1484 That is so that eval() can parse the string back to the same
1485 value.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001486
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001487 *v:fcs_reason* *fcs_reason-variable*
1488v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1489 Can be used in an autocommand to decide what to do and/or what
1490 to set v:fcs_choice to. Possible values:
1491 deleted file no longer exists
1492 conflict file contents, mode or timestamp was
1493 changed and buffer is modified
1494 changed file contents has changed
1495 mode mode of file changed
1496 time only file timestamp changed
1497
1498 *v:fcs_choice* *fcs_choice-variable*
1499v:fcs_choice What should happen after a |FileChangedShell| event was
1500 triggered. Can be used in an autocommand to tell Vim what to
1501 do with the affected buffer:
1502 reload Reload the buffer (does not work if
1503 the file was deleted).
1504 ask Ask the user what to do, as if there
1505 was no autocommand. Except that when
1506 only the timestamp changed nothing
1507 will happen.
1508 <empty> Nothing, the autocommand should do
1509 everything that needs to be done.
1510 The default is empty. If another (invalid) value is used then
1511 Vim behaves like it is empty, there is no warning message.
1512
Bram Moolenaar071d4272004-06-13 20:20:40 +00001513 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001514v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515 option used for ~
1516 'charconvert' file to be converted
1517 'diffexpr' original file
1518 'patchexpr' original file
1519 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001520 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001521
1522 *v:fname_out* *fname_out-variable*
1523v:fname_out The name of the output file. Only valid while
1524 evaluating:
1525 option used for ~
1526 'charconvert' resulting converted file (*)
1527 'diffexpr' output of diff
1528 'patchexpr' resulting patched file
1529 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001530 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001531 for a read command (e.g., ":e file") it will be a temporary
1532 file and different from v:fname_in.
1533
1534 *v:fname_new* *fname_new-variable*
1535v:fname_new The name of the new version of the file. Only valid while
1536 evaluating 'diffexpr'.
1537
1538 *v:fname_diff* *fname_diff-variable*
1539v:fname_diff The name of the diff (patch) file. Only valid while
1540 evaluating 'patchexpr'.
1541
1542 *v:folddashes* *folddashes-variable*
1543v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1544 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001545 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546
1547 *v:foldlevel* *foldlevel-variable*
1548v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001549 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001550
1551 *v:foldend* *foldend-variable*
1552v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001553 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001554
1555 *v:foldstart* *foldstart-variable*
1556v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001557 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558
Bram Moolenaar817a8802013-11-09 01:44:43 +01001559 *v:hlsearch* *hlsearch-variable*
Bram Moolenaar76440e22014-11-27 19:14:49 +01001560v:hlsearch Variable that indicates whether search highlighting is on.
1561 Setting it makes sense only if 'hlsearch' is enabled which
1562 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001563 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001564 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001565< Note that the value is restored when returning from a
1566 function. |function-search-undo|.
1567
Bram Moolenaar843ee412004-06-30 16:16:41 +00001568 *v:insertmode* *insertmode-variable*
1569v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1570 events. Values:
1571 i Insert mode
1572 r Replace mode
1573 v Virtual Replace mode
1574
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001575 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001576v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001577 evaluating the expression used with |map()| and |filter()|.
1578 Read-only.
1579
Bram Moolenaar071d4272004-06-13 20:20:40 +00001580 *v:lang* *lang-variable*
1581v:lang The current locale setting for messages of the runtime
1582 environment. This allows Vim scripts to be aware of the
1583 current language. Technical: it's the value of LC_MESSAGES.
1584 The value is system dependent.
1585 This variable can not be set directly, use the |:language|
1586 command.
1587 It can be different from |v:ctype| when messages are desired
1588 in a different language than what is used for character
1589 encoding. See |multi-lang|.
1590
1591 *v:lc_time* *lc_time-variable*
1592v:lc_time The current locale setting for time messages of the runtime
1593 environment. This allows Vim scripts to be aware of the
1594 current language. Technical: it's the value of LC_TIME.
1595 This variable can not be set directly, use the |:language|
1596 command. See |multi-lang|.
1597
1598 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001599v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1600 'indentexpr' expressions, tab page number for 'guitablabel'
1601 and 'guitabtooltip'. Only valid while one of these
1602 expressions is being evaluated. Read-only when in the
1603 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001604
Bram Moolenaar219b8702006-11-01 14:32:36 +00001605 *v:mouse_win* *mouse_win-variable*
1606v:mouse_win Window number for a mouse click obtained with |getchar()|.
1607 First window has number 1, like with |winnr()|. The value is
1608 zero when there was no mouse button click.
1609
Bram Moolenaar511972d2016-06-04 18:09:59 +02001610 *v:mouse_winid* *mouse_winid-variable*
1611v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1612 The value is zero when there was no mouse button click.
1613
Bram Moolenaar219b8702006-11-01 14:32:36 +00001614 *v:mouse_lnum* *mouse_lnum-variable*
1615v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1616 This is the text line number, not the screen line number. The
1617 value is zero when there was no mouse button click.
1618
1619 *v:mouse_col* *mouse_col-variable*
1620v:mouse_col Column number for a mouse click obtained with |getchar()|.
1621 This is the screen column number, like with |virtcol()|. The
1622 value is zero when there was no mouse button click.
1623
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001624 *v:none* *none-variable*
1625v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001626 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001627 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001628 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001629 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001630< v:none ~
1631 That is so that eval() can parse the string back to the same
1632 value.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001633
1634 *v:null* *null-variable*
1635v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001636 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001637 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001638 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001639 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001640< v:null ~
1641 That is so that eval() can parse the string back to the same
1642 value.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001643
Bram Moolenaard812df62008-11-09 12:46:09 +00001644 *v:oldfiles* *oldfiles-variable*
1645v:oldfiles List of file names that is loaded from the |viminfo| file on
1646 startup. These are the files that Vim remembers marks for.
1647 The length of the List is limited by the ' argument of the
1648 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001649 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001650 Also see |:oldfiles| and |c_#<|.
1651 The List can be modified, but this has no effect on what is
1652 stored in the |viminfo| file later. If you use values other
1653 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001654 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001655
Bram Moolenaar53744302015-07-17 17:38:22 +02001656 *v:option_new*
1657v:option_new New value of the option. Valid while executing an |OptionSet|
1658 autocommand.
1659 *v:option_old*
1660v:option_old Old value of the option. Valid while executing an |OptionSet|
1661 autocommand.
1662 *v:option_type*
1663v:option_type Scope of the set command. Valid while executing an
1664 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001665 *v:operator* *operator-variable*
1666v:operator The last operator given in Normal mode. This is a single
1667 character except for commands starting with <g> or <z>,
1668 in which case it is two characters. Best used alongside
1669 |v:prevcount| and |v:register|. Useful if you want to cancel
1670 Operator-pending mode and then use the operator, e.g.: >
1671 :omap O <Esc>:call MyMotion(v:operator)<CR>
1672< The value remains set until another operator is entered, thus
1673 don't expect it to be empty.
1674 v:operator is not set for |:delete|, |:yank| or other Ex
1675 commands.
1676 Read-only.
1677
Bram Moolenaar071d4272004-06-13 20:20:40 +00001678 *v:prevcount* *prevcount-variable*
1679v:prevcount The count given for the last but one Normal mode command.
1680 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001681 you want to cancel Visual or Operator-pending mode and then
1682 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001683 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1684< Read-only.
1685
Bram Moolenaar05159a02005-02-26 23:04:13 +00001686 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001687v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001688 See |profiling|.
1689
Bram Moolenaar071d4272004-06-13 20:20:40 +00001690 *v:progname* *progname-variable*
1691v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001692 invoked. Allows you to do special initialisations for |view|,
1693 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001694 Read-only.
1695
Bram Moolenaara1706c92014-04-01 19:55:49 +02001696 *v:progpath* *progpath-variable*
1697v:progpath Contains the command with which Vim was invoked, including the
1698 path. Useful if you want to message a Vim server using a
1699 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001700 To get the full path use: >
1701 echo exepath(v:progpath)
1702< NOTE: This does not work when the command is a relative path
1703 and the current directory has changed.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001704 Read-only.
1705
Bram Moolenaar071d4272004-06-13 20:20:40 +00001706 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001707v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001708 command (regardless of whether that command actually used a
1709 register). Or for the currently executing normal mode mapping
1710 (use this in custom commands that take a register).
1711 If none is supplied it is the default register '"', unless
1712 'clipboard' contains "unnamed" or "unnamedplus", then it is
1713 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001714 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001715
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001716 *v:scrollstart* *scrollstart-variable*
1717v:scrollstart String describing the script or function that caused the
1718 screen to scroll up. It's only set when it is empty, thus the
1719 first reason is remembered. It is set to "Unknown" for a
1720 typed command.
1721 This can be used to find out why your script causes the
1722 hit-enter prompt.
1723
Bram Moolenaar071d4272004-06-13 20:20:40 +00001724 *v:servername* *servername-variable*
1725v:servername The resulting registered |x11-clientserver| name if any.
1726 Read-only.
1727
Bram Moolenaar446cb832008-06-24 21:56:24 +00001728
1729v:searchforward *v:searchforward* *searchforward-variable*
1730 Search direction: 1 after a forward search, 0 after a
1731 backward search. It is reset to forward when directly setting
1732 the last search pattern, see |quote/|.
1733 Note that the value is restored when returning from a
1734 function. |function-search-undo|.
1735 Read-write.
1736
Bram Moolenaar071d4272004-06-13 20:20:40 +00001737 *v:shell_error* *shell_error-variable*
1738v:shell_error Result of the last shell command. When non-zero, the last
1739 shell command had an error. When zero, there was no problem.
1740 This only works when the shell returns the error code to Vim.
1741 The value -1 is often used when the command could not be
1742 executed. Read-only.
1743 Example: >
1744 :!mv foo bar
1745 :if v:shell_error
1746 : echo 'could not rename "foo" to "bar"!'
1747 :endif
1748< "shell_error" also works, for backwards compatibility.
1749
1750 *v:statusmsg* *statusmsg-variable*
1751v:statusmsg Last given status message. It's allowed to set this variable.
1752
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001753 *v:swapname* *swapname-variable*
1754v:swapname Only valid when executing |SwapExists| autocommands: Name of
1755 the swap file found. Read-only.
1756
1757 *v:swapchoice* *swapchoice-variable*
1758v:swapchoice |SwapExists| autocommands can set this to the selected choice
1759 for handling an existing swap file:
1760 'o' Open read-only
1761 'e' Edit anyway
1762 'r' Recover
1763 'd' Delete swapfile
1764 'q' Quit
1765 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001766 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001767 results in the user being asked, as would happen when there is
1768 no SwapExists autocommand. The default is empty.
1769
Bram Moolenaarb3480382005-12-11 21:33:32 +00001770 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001771v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001772 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001773 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001774 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001775 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001776
Bram Moolenaar071d4272004-06-13 20:20:40 +00001777 *v:termresponse* *termresponse-variable*
1778v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001779 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001780 that starts with ESC [ or CSI and ends in a 'c', with only
1781 digits, ';' and '.' in between.
1782 When this option is set, the TermResponse autocommand event is
1783 fired, so that you can react to the response from the
1784 terminal.
1785 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1786 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1787 patch level (since this was introduced in patch 95, it's
1788 always 95 or bigger). Pc is always zero.
1789 {only when compiled with |+termresponse| feature}
1790
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001791 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02001792v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001793
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794 *v:this_session* *this_session-variable*
1795v:this_session Full filename of the last loaded or saved session file. See
1796 |:mksession|. It is allowed to set this variable. When no
1797 session file has been saved, this variable is empty.
1798 "this_session" also works, for backwards compatibility.
1799
1800 *v:throwpoint* *throwpoint-variable*
1801v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001802 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001803 also |v:exception| and |throw-variables|.
1804 Example: >
1805 :try
1806 : throw "oops"
1807 :catch /.*/
1808 : echo "Exception from" v:throwpoint
1809 :endtry
1810< Output: "Exception from test.vim, line 2"
1811
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001812 *v:true* *true-variable*
1813v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001814 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001815 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001816 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001817< v:true ~
1818 That is so that eval() can parse the string back to the same
1819 value.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001820 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001821v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001822 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001823 |filter()|. Read-only.
1824
Bram Moolenaar071d4272004-06-13 20:20:40 +00001825 *v:version* *version-variable*
1826v:version Version number of Vim: Major version number times 100 plus
1827 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1828 is 501. Read-only. "version" also works, for backwards
1829 compatibility.
1830 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02001831 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001832< Note that patch numbers are specific to the version, thus both
1833 version 5.0 and 5.1 may have a patch 123, but these are
1834 completely different.
1835
Bram Moolenaar14735512016-03-26 21:00:08 +01001836 *v:vim_did_enter* *vim_did_enter-variable*
1837v:vim_did_enter Zero until most of startup is done. It is set to one just
1838 before |VimEnter| autocommands are triggered.
1839
Bram Moolenaar071d4272004-06-13 20:20:40 +00001840 *v:warningmsg* *warningmsg-variable*
1841v:warningmsg Last given warning message. It's allowed to set this variable.
1842
Bram Moolenaar727c8762010-10-20 19:17:48 +02001843 *v:windowid* *windowid-variable*
1844v:windowid When any X11 based GUI is running or when running in a
1845 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001846 set to the window ID.
1847 When an MS-Windows GUI is running this will be set to the
1848 window handle.
1849 Otherwise the value is zero.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001850 Note: for windows inside Vim use |winnr()| or |win_getid()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001851
Bram Moolenaar071d4272004-06-13 20:20:40 +00001852==============================================================================
18534. Builtin Functions *functions*
1854
1855See |function-list| for a list grouped by what the function is used for.
1856
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001857(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001858
1859USAGE RESULT DESCRIPTION ~
1860
Bram Moolenaar81edd172016-04-14 13:51:37 +02001861abs({expr}) Float or Number absolute value of {expr}
1862acos({expr}) Float arc cosine of {expr}
1863add({list}, {item}) List append {item} to |List| {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001864and({expr}, {expr}) Number bitwise AND
1865append({lnum}, {string}) Number append {string} below line {lnum}
1866append({lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001867argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001868argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02001869arglistid([{winnr} [, {tabnr}]]) Number argument list id
1870argv({nr}) String {nr} entry of the argument list
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001871argv() List the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02001872assert_equal({exp}, {act} [, {msg}]) none assert {exp} is equal to {act}
1873assert_exception({error} [, {msg}]) none assert {error} is in v:exception
1874assert_fails({cmd} [, {error}]) none assert {cmd} fails
1875assert_false({actual} [, {msg}]) none assert {actual} is false
1876assert_match({pat}, {text} [, {msg}]) none assert {pat} matches {text}
1877assert_notequal({exp}, {act} [, {msg}]) none assert {exp} is not equal {act}
1878assert_notmatch({pat}, {text} [, {msg}]) none assert {pat} not matches {text}
1879assert_true({actual} [, {msg}]) none assert {actual} is true
1880asin({expr}) Float arc sine of {expr}
1881atan({expr}) Float arc tangent of {expr}
1882atan2({expr}, {expr}) Float arc tangent of {expr1} / {expr2}
1883browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00001884 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02001885browsedir({title}, {initdir}) String put up a directory requester
1886bufexists({expr}) Number TRUE if buffer {expr} exists
1887buflisted({expr}) Number TRUE if buffer {expr} is listed
1888bufloaded({expr}) Number TRUE if buffer {expr} is loaded
1889bufname({expr}) String Name of the buffer {expr}
1890bufnr({expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02001891bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001892bufwinnr({expr}) Number window number of buffer {expr}
1893byte2line({byte}) Number line number at byte count {byte}
1894byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
1895byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
1896call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001897 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001898ceil({expr}) Float round {expr} up
1899ch_close({handle}) none close {handle}
1900ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001901 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001902ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001903 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001904ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
1905ch_getjob({channel}) Job get the Job of {channel}
1906ch_info({handle}) String info about channel {handle}
1907ch_log({msg} [, {handle}]) none write {msg} in the channel log file
1908ch_logfile({fname} [, {mode}]) none start logging channel activity
1909ch_open({address} [, {options}])
1910 Channel open a channel to {address}
1911ch_read({handle} [, {options}]) String read from {handle}
1912ch_readraw({handle} [, {options}])
1913 String read raw from {handle}
1914ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001915 any send {expr} over JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001916ch_sendraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001917 any send {string} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001918ch_setoptions({handle}, {options})
1919 none set options for {handle}
1920ch_status({handle}) String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001921changenr() Number current change number
Bram Moolenaar81edd172016-04-14 13:51:37 +02001922char2nr({expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
1923cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001924clearmatches() none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02001925col({expr}) Number column nr of cursor or mark
1926complete({startcol}, {matches}) none set Insert mode completion
1927complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001928complete_check() Number check for key typed during completion
Bram Moolenaar81edd172016-04-14 13:51:37 +02001929confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001930 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02001931copy({expr}) any make a shallow copy of {expr}
1932cos({expr}) Float cosine of {expr}
1933cosh({expr}) Float hyperbolic cosine of {expr}
1934count({list}, {expr} [, {ic} [, {start}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001935 Number count how many {expr} are in {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001936cscope_connection([{num} , {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001937 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02001938cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01001939 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001940cursor({list}) Number move cursor to position in {list}
1941deepcopy({expr} [, {noref}]) any make a full copy of {expr}
1942delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02001944diff_filler({lnum}) Number diff filler lines about {lnum}
1945diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001946empty({expr}) Number TRUE if {expr} is empty
1947escape({string}, {chars}) String escape {chars} in {string} with '\'
1948eval({string}) any evaluate {string} into its value
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001949eventhandler() Number TRUE if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02001950executable({expr}) Number 1 if executable {expr} exists
1951exepath({expr}) String full path of the command {expr}
1952exists({expr}) Number TRUE if {expr} exists
1953extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001954 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001955exp({expr}) Float exponential of {expr}
1956expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001957 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001958feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
1959filereadable({file}) Number TRUE if {file} is a readable file
1960filewritable({file}) Number TRUE if {file} is a writable file
1961filter({expr}, {string}) List/Dict remove items from {expr} where
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001962 {string} is 0
Bram Moolenaar81edd172016-04-14 13:51:37 +02001963finddir({name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001964 String find directory {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001965findfile({name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001966 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001967float2nr({expr}) Number convert Float {expr} to a Number
1968floor({expr}) Float round {expr} down
1969fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
1970fnameescape({fname}) String escape special characters in {fname}
1971fnamemodify({fname}, {mods}) String modify file name
1972foldclosed({lnum}) Number first line of fold at {lnum} if closed
1973foldclosedend({lnum}) Number last line of fold at {lnum} if closed
1974foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001975foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02001976foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001977foreground() Number bring the Vim window to the foreground
Bram Moolenaar81edd172016-04-14 13:51:37 +02001978function({name} [, {arglist}] [, {dict}])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01001979 Funcref reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001980garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02001981get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
1982get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02001983get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001984getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00001985 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001986getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001987 any variable {varname} in buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001988getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001989getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02001990getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00001991getcmdline() String return the current command-line
1992getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02001993getcmdtype() String return current command-line type
1994getcmdwintype() String return current command-line window type
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001995getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02001996getcwd([{winnr} [, {tabnr}]]) String get the current working directory
1997getfontname([{name}]) String name of font being used
1998getfperm({fname}) String file permissions of file {fname}
1999getfsize({fname}) Number size in bytes of file {fname}
2000getftime({fname}) Number last modification time of file
2001getftype({fname}) String description of type of file {fname}
2002getline({lnum}) String line {lnum} of current buffer
2003getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
2004getloclist({nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002005getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002006getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002007getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002008getqflist() List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002009getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002010 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002011getregtype([{regname}]) String type of register
2012gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002013 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002014gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002015 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002016getwinposx() Number X coord in pixels of GUI Vim window
2017getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002018getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002019 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002020glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002021 any expand file wildcards in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002022glob2regpat({expr}) String convert a glob pat into a search pat
2023globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002024 String do glob({expr}) for all dirs in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002025has({feature}) Number TRUE if feature {feature} supported
2026has_key({dict}, {key}) Number TRUE if {dict} has entry {key}
2027haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaarc9703302016-01-17 21:49:33 +01002028 Number TRUE if the window executed |:lcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002029hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002030 Number TRUE if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002031histadd({history}, {item}) String add an item to a history
2032histdel({history} [, {item}]) String remove an item from a history
2033histget({history} [, {index}]) String get the item {index} from a history
2034histnr({history}) Number highest index of a history
2035hlexists({name}) Number TRUE if highlight group {name} exists
2036hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002037hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002038iconv({expr}, {from}, {to}) String convert encoding of {expr}
2039indent({lnum}) Number indent of line {lnum}
2040index({list}, {expr} [, {start} [, {ic}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002041 Number index in {list} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002042input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002043 String get input from the user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002044inputdialog({prompt} [, {text} [, {completion}]]])
2045 String like input() but in a GUI dialog
2046inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002047inputrestore() Number restore typeahead
2048inputsave() Number save and clear typeahead
Bram Moolenaar81edd172016-04-14 13:51:37 +02002049inputsecret({prompt} [, {text}]) String like input() but hiding the text
2050insert({list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
2051invert({expr}) Number bitwise invert
2052isdirectory({directory}) Number TRUE if {directory} is a directory
2053islocked({expr}) Number TRUE if {expr} is locked
2054isnan({expr}) Number TRUE if {expr} is NaN
2055items({dict}) List key-value pairs in {dict}
2056job_getchannel({job}) Channel get the channel handle for {job}
2057job_info({job}) Dict get information about {job}
2058job_setoptions({job}, {options}) none set options for {job}
2059job_start({command} [, {options}])
2060 Job start a job
2061job_status({job}) String get the status of {job}
2062job_stop({job} [, {how}]) Number stop {job}
2063join({list} [, {sep}]) String join {list} items into one String
2064js_decode({string}) any decode JS style JSON
2065js_encode({expr}) String encode JS style JSON
2066json_decode({string}) any decode JSON
2067json_encode({expr}) String encode JSON
2068keys({dict}) List keys in {dict}
2069len({expr}) Number the length of {expr}
2070libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002071libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002072line({expr}) Number line nr of cursor, last line or mark
2073line2byte({lnum}) Number byte count of line {lnum}
2074lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002075localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002076log({expr}) Float natural logarithm (base e) of {expr}
2077log10({expr}) Float logarithm of Float {expr} to base 10
2078luaeval({expr}[, {expr}]) any evaluate |Lua| expression
2079map({expr}, {string}) List/Dict change each item in {expr} to {expr}
2080maparg({name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002081 String or Dict
2082 rhs of mapping {name} in mode {mode}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002083mapcheck({name}[, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002084 String check for mappings matching {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002085match({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002086 Number position where {pat} matches in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002087matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002088 Number highlight {pattern} with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002089matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002090 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002091matcharg({nr}) List arguments of |:match|
2092matchdelete({id}) Number delete match identified by {id}
2093matchend({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002094 Number position where {pat} ends in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002095matchlist({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002096 List match and submatches of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002097matchstr({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002098 String {count}'th match of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002099matchstrpos({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002100 List {count}'th match of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002101max({list}) Number maximum value of items in {list}
2102min({list}) Number minimum value of items in {list}
2103mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002104 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002105mode([expr]) String current editing mode
2106mzeval({expr}) any evaluate |MzScheme| expression
2107nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
2108nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr}
2109or({expr}, {expr}) Number bitwise OR
2110pathshorten({expr}) String shorten directory names in a path
2111perleval({expr}) any evaluate |Perl| expression
2112pow({x}, {y}) Float {x} to the power of {y}
2113prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2114printf({fmt}, {expr1}...) String format text
Bram Moolenaar446cb832008-06-24 21:56:24 +00002115pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002116pyeval({expr}) any evaluate |Python| expression
2117py3eval({expr}) any evaluate |python3| expression
2118range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002119 List items from {expr} to {max}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002120readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002121 List get list of lines from file {fname}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002122reltime([{start} [, {end}]]) List get time value
2123reltimefloat({time}) Float turn the time value into a Float
2124reltimestr({time}) String turn time value into a String
2125remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002126 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002127remote_foreground({server}) Number bring Vim server to the foreground
2128remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002129 Number check for reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002130remote_read({serverid}) String read reply string
2131remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002132 String send key sequence
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002133remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002134remove({dict}, {key}) any remove entry {key} from {dict}
2135rename({from}, {to}) Number rename (move) file from {from} to {to}
2136repeat({expr}, {count}) String repeat {expr} {count} times
2137resolve({filename}) String get filename a shortcut points to
2138reverse({list}) List reverse {list} in-place
2139round({expr}) Float round off {expr}
2140screenattr({row}, {col}) Number attribute at screen position
2141screenchar({row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002142screencol() Number current cursor column
2143screenrow() Number current cursor row
Bram Moolenaar81edd172016-04-14 13:51:37 +02002144search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002145 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002146searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002147 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002148searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002149 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002150searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002151 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002152searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002153 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002154server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002155 Number send reply string
2156serverlist() String get a list of available servers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002157setbufvar({expr}, {varname}, {val})
2158 none set {varname} in buffer {expr} to {val}
2159setcharsearch({dict}) Dict set character search from {dict}
2160setcmdpos({pos}) Number set cursor position in command-line
2161setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2162setline({lnum}, {line}) Number set line {lnum} to {line}
2163setloclist({nr}, {list}[, {action}])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002164 Number modify location list using {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002165setmatches({list}) Number restore a list of matches
2166setpos({expr}, {list}) Number set the {expr} position to {list}
2167setqflist({list}[, {action}]) Number modify quickfix list using {list}
2168setreg({n}, {v}[, {opt}]) Number set register to value and type
2169settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2170settabwinvar({tabnr}, {winnr}, {varname}, {val})
2171 none set {varname} in window {winnr} in tab
2172 page {tabnr} to {val}
2173setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2174sha256({string}) String SHA256 checksum of {string}
2175shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002176 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002177 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02002178shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaar81edd172016-04-14 13:51:37 +02002179simplify({filename}) String simplify filename as much as possible
2180sin({expr}) Float sine of {expr}
2181sinh({expr}) Float hyperbolic sine of {expr}
2182sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002183 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002184soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002185spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002186spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002187 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002188split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002189 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002190sqrt({expr}) Float square root of {expr}
2191str2float({expr}) Float convert String to Float
2192str2nr({expr} [, {base}]) Number convert String to Number
2193strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002194strcharpart({str}, {start}[, {len}])
2195 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002196strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
2197strftime({format}[, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002198strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002199stridx({haystack}, {needle}[, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002200 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002201string({expr}) String String representation of {expr} value
2202strlen({expr}) Number length of the String {expr}
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002203strpart({str}, {start}[, {len}])
2204 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002205strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002206 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002207strtrans({expr}) String translate string to make it printable
2208strwidth({expr}) Number display cell length of the String {expr}
2209submatch({nr}[, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002210 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002211substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002212 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002213synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2214synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002215 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002216synIDtrans({synID}) Number translated syntax ID of {synID}
2217synconcealed({lnum}, {col}) List info about concealing
2218synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2219system({expr} [, {input}]) String output of shell command/filter {expr}
2220systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002221tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002222tabpagenr([{arg}]) Number number of current or last tab page
2223tabpagewinnr({tabarg}[, {arg}]) Number number of current window in tab page
2224taglist({expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002225tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002226tan({expr}) Float tangent of {expr}
2227tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002228tempname() String name for a temporary file
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002229test_alloc_fail({id}, {countdown}, {repeat})
2230 none make memory allocation fail
2231test_disable_char_avail({expr}) none test without typeahead
Bram Moolenaar574860b2016-05-24 17:33:34 +02002232test_garbagecollect_now() none free memory right now for testing
2233test_null_channel() Channel null value for testing
2234test_null_dict() Dict null value for testing
2235test_null_job() Job null value for testing
2236test_null_list() List null value for testing
2237test_null_partial() Funcref null value for testing
2238test_null_string() String null value for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002239test_settime({expr}) none set current time for testing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002240timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002241 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002242timer_stop({timer}) none stop a timer
2243tolower({expr}) String the String {expr} switched to lowercase
2244toupper({expr}) String the String {expr} switched to uppercase
2245tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002246 to chars in {tostr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002247trunc({expr}) Float truncate Float {expr}
2248type({name}) Number type of variable {name}
2249undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002250undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002251uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002252 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002253values({dict}) List values in {dict}
2254virtcol({expr}) Number screen column of cursor or mark
2255visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002256wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar81edd172016-04-14 13:51:37 +02002257win_findbuf({bufnr}) List find windows containing {bufnr}
2258win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2259win_gotoid({expr}) Number go to window with ID {expr}
2260win_id2tabwin({expr}) List get tab and window nr from window ID
2261win_id2win({expr}) Number get window nr from window ID
2262winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002263wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002264winheight({nr}) Number height of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002265winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002266winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002267winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002268winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002269winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002270winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002271wordcount() Dict get byte/char/word statistics
Bram Moolenaar81edd172016-04-14 13:51:37 +02002272writefile({list}, {fname} [, {flags}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002273 Number write list of lines to file {fname}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002274xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002275
Bram Moolenaar03413f42016-04-12 21:07:15 +02002276
Bram Moolenaar446cb832008-06-24 21:56:24 +00002277abs({expr}) *abs()*
2278 Return the absolute value of {expr}. When {expr} evaluates to
2279 a |Float| abs() returns a |Float|. When {expr} can be
2280 converted to a |Number| abs() returns a |Number|. Otherwise
2281 abs() gives an error message and returns -1.
2282 Examples: >
2283 echo abs(1.456)
2284< 1.456 >
2285 echo abs(-5.456)
2286< 5.456 >
2287 echo abs(-4)
2288< 4
2289 {only available when compiled with the |+float| feature}
2290
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002291
2292acos({expr}) *acos()*
2293 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002294 |Float| in the range of [0, pi].
2295 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002296 [-1, 1].
2297 Examples: >
2298 :echo acos(0)
2299< 1.570796 >
2300 :echo acos(-0.5)
2301< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002302 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002303
2304
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002305add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002306 Append the item {expr} to |List| {list}. Returns the
2307 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002308 :let alist = add([1, 2, 3], item)
2309 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002310< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002311 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002312 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002313
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002314
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002315and({expr}, {expr}) *and()*
2316 Bitwise AND on the two arguments. The arguments are converted
2317 to a number. A List, Dict or Float argument causes an error.
2318 Example: >
2319 :let flag = and(bits, 0x80)
2320
2321
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002322append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002323 When {expr} is a |List|: Append each item of the |List| as a
2324 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002325 Otherwise append {expr} as one text line below line {lnum} in
2326 the current buffer.
2327 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002328 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002329 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002330 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002331 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002332<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002333 *argc()*
2334argc() The result is the number of files in the argument list of the
2335 current window. See |arglist|.
2336
2337 *argidx()*
2338argidx() The result is the current index in the argument list. 0 is
2339 the first file. argc() - 1 is the last one. See |arglist|.
2340
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002341 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002342arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002343 Return the argument list ID. This is a number which
2344 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002345 global argument list. See |arglist|.
2346 Return -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002347
2348 Without arguments use the current window.
2349 With {winnr} only use this window in the current tab page.
2350 With {winnr} and {tabnr} use the window in the specified tab
2351 page.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02002352 {winnr} can be the window number or the window ID.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002353
Bram Moolenaar071d4272004-06-13 20:20:40 +00002354 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002355argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002356 current window. See |arglist|. "argv(0)" is the first one.
2357 Example: >
2358 :let i = 0
2359 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002360 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002361 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2362 : let i = i + 1
2363 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002364< Without the {nr} argument a |List| with the whole |arglist| is
2365 returned.
2366
Bram Moolenaar683fa182015-11-30 21:38:24 +01002367 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002368assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002369 When {expected} and {actual} are not equal an error message is
2370 added to |v:errors|.
2371 There is no automatic conversion, the String "4" is different
2372 from the Number 4. And the number 4 is different from the
2373 Float 4.0. The value of 'ignorecase' is not used here, case
2374 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002375 When {msg} is omitted an error in the form "Expected
2376 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002377 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002378 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002379< Will result in a string to be added to |v:errors|:
2380 test.vim line 12: Expected 'foo' but got 'bar' ~
2381
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002382assert_exception({error} [, {msg}]) *assert_exception()*
2383 When v:exception does not contain the string {error} an error
2384 message is added to |v:errors|.
2385 This can be used to assert that a command throws an exception.
2386 Using the error number, followed by a colon, avoids problems
2387 with translations: >
2388 try
2389 commandthatfails
2390 call assert_false(1, 'command should have failed')
2391 catch
2392 call assert_exception('E492:')
2393 endtry
2394
Bram Moolenaara260b872016-01-15 20:48:22 +01002395assert_fails({cmd} [, {error}]) *assert_fails()*
2396 Run {cmd} and add an error message to |v:errors| if it does
2397 NOT produce an error.
2398 When {error} is given it must match |v:errmsg|.
2399
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002400assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002401 When {actual} is not false an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002402 |v:errors|, like with |assert_equal()|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002403 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002404 number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002405 When {msg} is omitted an error in the form "Expected False but
2406 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002407
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002408 *assert_match()*
2409assert_match({pattern}, {actual} [, {msg}])
2410 When {pattern} does not match {actual} an error message is
2411 added to |v:errors|.
2412
2413 {pattern} is used as with |=~|: The matching is always done
2414 like 'magic' was set and 'cpoptions' is empty, no matter what
2415 the actual value of 'magic' or 'cpoptions' is.
2416
2417 {actual} is used as a string, automatic conversion applies.
2418 Use "^" and "$" to match with the start and end of the text.
2419 Use both to match the whole text.
2420
2421 When {msg} is omitted an error in the form "Pattern {pattern}
2422 does not match {actual}" is produced.
2423 Example: >
2424 assert_match('^f.*o$', 'foobar')
2425< Will result in a string to be added to |v:errors|:
2426 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2427
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002428 *assert_notequal()*
2429assert_notequal({expected}, {actual} [, {msg}])
2430 The opposite of `assert_equal()`: add an error message to
2431 |v:errors| when {expected} and {actual} are equal.
2432
2433 *assert_notmatch()*
2434assert_notmatch({pattern}, {actual} [, {msg}])
2435 The opposite of `assert_match()`: add an error message to
2436 |v:errors| when {pattern} matches {actual}.
2437
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002438assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002439 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002440 |v:errors|, like with |assert_equal()|.
2441 A value is true when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002442 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002443 When {msg} is omitted an error in the form "Expected True but
2444 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002445
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002446asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002447 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002448 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002449 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002450 [-1, 1].
2451 Examples: >
2452 :echo asin(0.8)
2453< 0.927295 >
2454 :echo asin(-0.5)
2455< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002456 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002457
2458
Bram Moolenaar446cb832008-06-24 21:56:24 +00002459atan({expr}) *atan()*
2460 Return the principal value of the arc tangent of {expr}, in
2461 the range [-pi/2, +pi/2] radians, as a |Float|.
2462 {expr} must evaluate to a |Float| or a |Number|.
2463 Examples: >
2464 :echo atan(100)
2465< 1.560797 >
2466 :echo atan(-4.01)
2467< -1.326405
2468 {only available when compiled with the |+float| feature}
2469
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002470
2471atan2({expr1}, {expr2}) *atan2()*
2472 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002473 radians, as a |Float| in the range [-pi, pi].
2474 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002475 Examples: >
2476 :echo atan2(-1, 1)
2477< -0.785398 >
2478 :echo atan2(1, -1)
2479< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002480 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002481
2482
Bram Moolenaar071d4272004-06-13 20:20:40 +00002483 *browse()*
2484browse({save}, {title}, {initdir}, {default})
2485 Put up a file requester. This only works when "has("browse")"
2486 returns non-zero (only in some GUI versions).
2487 The input fields are:
2488 {save} when non-zero, select file to write
2489 {title} title for the requester
2490 {initdir} directory to start browsing in
2491 {default} default file name
2492 When the "Cancel" button is hit, something went wrong, or
2493 browsing is not possible, an empty string is returned.
2494
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002495 *browsedir()*
2496browsedir({title}, {initdir})
2497 Put up a directory requester. This only works when
2498 "has("browse")" returns non-zero (only in some GUI versions).
2499 On systems where a directory browser is not supported a file
2500 browser is used. In that case: select a file in the directory
2501 to be used.
2502 The input fields are:
2503 {title} title for the requester
2504 {initdir} directory to start browsing in
2505 When the "Cancel" button is hit, something went wrong, or
2506 browsing is not possible, an empty string is returned.
2507
Bram Moolenaar071d4272004-06-13 20:20:40 +00002508bufexists({expr}) *bufexists()*
2509 The result is a Number, which is non-zero if a buffer called
2510 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002511 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002512 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002513 exactly. The name can be:
2514 - Relative to the current directory.
2515 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002516 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002517 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002518 Unlisted buffers will be found.
2519 Note that help files are listed by their short name in the
2520 output of |:buffers|, but bufexists() requires using their
2521 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002522 bufexists() may report a buffer exists, but to use the name
2523 with a |:buffer| command you may need to use |expand()|. Esp
2524 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002525 Use "bufexists(0)" to test for the existence of an alternate
2526 file name.
2527 *buffer_exists()*
2528 Obsolete name: buffer_exists().
2529
2530buflisted({expr}) *buflisted()*
2531 The result is a Number, which is non-zero if a buffer called
2532 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002533 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002534
2535bufloaded({expr}) *bufloaded()*
2536 The result is a Number, which is non-zero if a buffer called
2537 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002538 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002539
2540bufname({expr}) *bufname()*
2541 The result is the name of a buffer, as it is displayed by the
2542 ":ls" command.
2543 If {expr} is a Number, that buffer number's name is given.
2544 Number zero is the alternate buffer for the current window.
2545 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002546 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002547 set and 'cpoptions' is empty. When there is more than one
2548 match an empty string is returned.
2549 "" or "%" can be used for the current buffer, "#" for the
2550 alternate buffer.
2551 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002552 or middle of the buffer name is accepted. If you only want a
2553 full match then put "^" at the start and "$" at the end of the
2554 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002555 Listed buffers are found first. If there is a single match
2556 with a listed buffer, that one is returned. Next unlisted
2557 buffers are searched for.
2558 If the {expr} is a String, but you want to use it as a buffer
2559 number, force it to be a Number by adding zero to it: >
2560 :echo bufname("3" + 0)
2561< If the buffer doesn't exist, or doesn't have a name, an empty
2562 string is returned. >
2563 bufname("#") alternate buffer name
2564 bufname(3) name of buffer 3
2565 bufname("%") name of current buffer
2566 bufname("file2") name of buffer where "file2" matches.
2567< *buffer_name()*
2568 Obsolete name: buffer_name().
2569
2570 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002571bufnr({expr} [, {create}])
2572 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002573 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002574 above.
2575 If the buffer doesn't exist, -1 is returned. Or, if the
2576 {create} argument is present and not zero, a new, unlisted,
2577 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002578 bufnr("$") is the last buffer: >
2579 :let last_buffer = bufnr("$")
2580< The result is a Number, which is the highest buffer number
2581 of existing buffers. Note that not all buffers with a smaller
2582 number necessarily exist, because ":bwipeout" may have removed
2583 them. Use bufexists() to test for the existence of a buffer.
2584 *buffer_number()*
2585 Obsolete name: buffer_number().
2586 *last_buffer_nr()*
2587 Obsolete name for bufnr("$"): last_buffer_nr().
2588
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002589bufwinid({expr}) *bufwinid()*
2590 The result is a Number, which is the window ID of the first
2591 window associated with buffer {expr}. For the use of {expr},
2592 see |bufname()| above. If buffer {expr} doesn't exist or
2593 there is no such window, -1 is returned. Example: >
2594
2595 echo "A window containing buffer 1 is " . (bufwinid(1))
2596<
2597 Only deals with the current tab page.
2598
Bram Moolenaar071d4272004-06-13 20:20:40 +00002599bufwinnr({expr}) *bufwinnr()*
2600 The result is a Number, which is the number of the first
2601 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002602 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002603 there is no such window, -1 is returned. Example: >
2604
2605 echo "A window containing buffer 1 is " . (bufwinnr(1))
2606
2607< The number can be used with |CTRL-W_w| and ":wincmd w"
2608 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002609 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002610
Bram Moolenaar071d4272004-06-13 20:20:40 +00002611byte2line({byte}) *byte2line()*
2612 Return the line number that contains the character at byte
2613 count {byte} in the current buffer. This includes the
2614 end-of-line character, depending on the 'fileformat' option
2615 for the current buffer. The first character has byte count
2616 one.
2617 Also see |line2byte()|, |go| and |:goto|.
2618 {not available when compiled without the |+byte_offset|
2619 feature}
2620
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002621byteidx({expr}, {nr}) *byteidx()*
2622 Return byte index of the {nr}'th character in the string
2623 {expr}. Use zero for the first character, it returns zero.
2624 This function is only useful when there are multibyte
2625 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002626 Composing characters are not counted separately, their byte
2627 length is added to the preceding base character. See
2628 |byteidxcomp()| below for counting composing characters
2629 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002630 Example : >
2631 echo matchstr(str, ".", byteidx(str, 3))
2632< will display the fourth character. Another way to do the
2633 same: >
2634 let s = strpart(str, byteidx(str, 3))
2635 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002636< Also see |strgetchar()| and |strcharpart()|.
2637
2638 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002639 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002640 in bytes is returned.
2641
2642byteidxcomp({expr}, {nr}) *byteidxcomp()*
2643 Like byteidx(), except that a composing character is counted
2644 as a separate character. Example: >
2645 let s = 'e' . nr2char(0x301)
2646 echo byteidx(s, 1)
2647 echo byteidxcomp(s, 1)
2648 echo byteidxcomp(s, 2)
2649< The first and third echo result in 3 ('e' plus composing
2650 character is 3 bytes), the second echo results in 1 ('e' is
2651 one byte).
2652 Only works different from byteidx() when 'encoding' is set to
2653 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002654
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002655call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002656 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002657 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002658 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002659 a:firstline and a:lastline are set to the cursor line.
2660 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002661 {dict} is for functions with the "dict" attribute. It will be
2662 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002663
Bram Moolenaar446cb832008-06-24 21:56:24 +00002664ceil({expr}) *ceil()*
2665 Return the smallest integral value greater than or equal to
2666 {expr} as a |Float| (round up).
2667 {expr} must evaluate to a |Float| or a |Number|.
2668 Examples: >
2669 echo ceil(1.456)
2670< 2.0 >
2671 echo ceil(-5.456)
2672< -5.0 >
2673 echo ceil(4.0)
2674< 4.0
2675 {only available when compiled with the |+float| feature}
2676
Bram Moolenaarca003e12006-03-17 23:19:38 +00002677changenr() *changenr()*
2678 Return the number of the most recent change. This is the same
2679 number as what is displayed with |:undolist| and can be used
2680 with the |:undo| command.
2681 When a change was made it is the number of that change. After
2682 redo it is the number of the redone change. After undo it is
2683 one less than the number of the undone change.
2684
Bram Moolenaard35d7842013-01-23 17:17:10 +01002685char2nr({expr}[, {utf8}]) *char2nr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002686 Return number value of the first char in {expr}. Examples: >
2687 char2nr(" ") returns 32
2688 char2nr("ABC") returns 65
Bram Moolenaard35d7842013-01-23 17:17:10 +01002689< When {utf8} is omitted or zero, the current 'encoding' is used.
2690 Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002691 char2nr("á") returns 225
2692 char2nr("á"[0]) returns 195
Bram Moolenaard35d7842013-01-23 17:17:10 +01002693< With {utf8} set to 1, always treat as utf-8 characters.
2694 A combining character is a separate character.
Bram Moolenaar97293012011-07-18 19:40:27 +02002695 |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002696
2697cindent({lnum}) *cindent()*
2698 Get the amount of indent for line {lnum} according the C
2699 indenting rules, as with 'cindent'.
2700 The indent is counted in spaces, the value of 'tabstop' is
2701 relevant. {lnum} is used just like in |getline()|.
2702 When {lnum} is invalid or Vim was not compiled the |+cindent|
2703 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002704 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002705
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002706clearmatches() *clearmatches()*
2707 Clears all matches previously defined by |matchadd()| and the
2708 |:match| commands.
2709
Bram Moolenaar071d4272004-06-13 20:20:40 +00002710 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002711col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002712 position given with {expr}. The accepted positions are:
2713 . the cursor position
2714 $ the end of the cursor line (the result is the
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02002715 number of bytes in the cursor line plus one)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002716 'x position of mark x (if the mark is not set, 0 is
2717 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01002718 v In Visual mode: the start of the Visual area (the
2719 cursor is the end). When not in Visual mode
2720 returns the cursor position. Differs from |'<| in
2721 that it's updated right away.
Bram Moolenaar477933c2007-07-17 14:32:23 +00002722 Additionally {expr} can be [lnum, col]: a |List| with the line
2723 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002724 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002725 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002726 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002727 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002728 For the screen column position use |virtcol()|.
2729 Note that only marks in the current file can be used.
2730 Examples: >
2731 col(".") column of cursor
2732 col("$") length of cursor line plus one
2733 col("'t") column of mark t
2734 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002735< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002736 For an uppercase mark the column may actually be in another
2737 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002738 For the cursor position, when 'virtualedit' is active, the
2739 column is one higher if the cursor is after the end of the
2740 line. This can be used to obtain the column in Insert mode: >
2741 :imap <F2> <C-O>:let save_ve = &ve<CR>
2742 \<C-O>:set ve=all<CR>
2743 \<C-O>:echo col(".") . "\n" <Bar>
2744 \let &ve = save_ve<CR>
2745<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002746
Bram Moolenaara94bc432006-03-10 21:42:59 +00002747complete({startcol}, {matches}) *complete()* *E785*
2748 Set the matches for Insert mode completion.
2749 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002750 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2751 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002752 {startcol} is the byte offset in the line where the completed
2753 text start. The text up to the cursor is the original text
2754 that will be replaced by the matches. Use col('.') for an
2755 empty string. "col('.') - 1" will replace one character by a
2756 match.
2757 {matches} must be a |List|. Each |List| item is one match.
2758 See |complete-items| for the kind of items that are possible.
2759 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002760 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002761 The match can be selected with CTRL-N and CTRL-P as usual with
2762 Insert mode completion. The popup menu will appear if
2763 specified, see |ins-completion-menu|.
2764 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002765 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002766
2767 func! ListMonths()
2768 call complete(col('.'), ['January', 'February', 'March',
2769 \ 'April', 'May', 'June', 'July', 'August', 'September',
2770 \ 'October', 'November', 'December'])
2771 return ''
2772 endfunc
2773< This isn't very useful, but it shows how it works. Note that
2774 an empty string is returned to avoid a zero being inserted.
2775
Bram Moolenaar572cb562005-08-05 21:35:02 +00002776complete_add({expr}) *complete_add()*
2777 Add {expr} to the list of matches. Only to be used by the
2778 function specified with the 'completefunc' option.
2779 Returns 0 for failure (empty string or out of memory),
2780 1 when the match was added, 2 when the match was already in
2781 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002782 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002783 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002784
2785complete_check() *complete_check()*
2786 Check for a key typed while looking for completion matches.
2787 This is to be used when looking for matches takes some time.
2788 Returns non-zero when searching for matches is to be aborted,
2789 zero otherwise.
2790 Only to be used by the function specified with the
2791 'completefunc' option.
2792
Bram Moolenaar071d4272004-06-13 20:20:40 +00002793 *confirm()*
2794confirm({msg} [, {choices} [, {default} [, {type}]]])
2795 Confirm() offers the user a dialog, from which a choice can be
2796 made. It returns the number of the choice. For the first
2797 choice this is 1.
2798 Note: confirm() is only supported when compiled with dialog
2799 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002800
Bram Moolenaar071d4272004-06-13 20:20:40 +00002801 {msg} is displayed in a |dialog| with {choices} as the
2802 alternatives. When {choices} is missing or empty, "&OK" is
2803 used (and translated).
2804 {msg} is a String, use '\n' to include a newline. Only on
2805 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002806
Bram Moolenaar071d4272004-06-13 20:20:40 +00002807 {choices} is a String, with the individual choices separated
2808 by '\n', e.g. >
2809 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2810< The letter after the '&' is the shortcut key for that choice.
2811 Thus you can type 'c' to select "Cancel". The shortcut does
2812 not need to be the first letter: >
2813 confirm("file has been modified", "&Save\nSave &All")
2814< For the console, the first letter of each choice is used as
2815 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002816
Bram Moolenaar071d4272004-06-13 20:20:40 +00002817 The optional {default} argument is the number of the choice
2818 that is made if the user hits <CR>. Use 1 to make the first
2819 choice the default one. Use 0 to not set a default. If
2820 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002821
2822 The optional {type} argument gives the type of dialog. This
2823 is only used for the icon of the GTK, Mac, Motif and Win32
2824 GUI. It can be one of these values: "Error", "Question",
2825 "Info", "Warning" or "Generic". Only the first character is
2826 relevant. When {type} is omitted, "Generic" is used.
2827
Bram Moolenaar071d4272004-06-13 20:20:40 +00002828 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2829 or another valid interrupt key, confirm() returns 0.
2830
2831 An example: >
2832 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2833 :if choice == 0
2834 : echo "make up your mind!"
2835 :elseif choice == 3
2836 : echo "tasteful"
2837 :else
2838 : echo "I prefer bananas myself."
2839 :endif
2840< In a GUI dialog, buttons are used. The layout of the buttons
2841 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002842 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002843 tries to put the buttons in one horizontal line. If they
2844 don't fit, a vertical layout is used anyway. For some systems
2845 the horizontal layout is always used.
2846
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002847ch_close({handle}) *ch_close()*
2848 Close {handle}. See |channel-close|.
2849 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002850
Bram Moolenaar835dc632016-02-07 14:27:38 +01002851 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002852
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002853ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
2854 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002855 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01002856 with a raw channel. See |channel-use|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002857 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002858 *E917*
2859 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002860 entry. It can have a "timeout" entry to specify the timeout
2861 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002862
2863 ch_evalexpr() waits for a response and returns the decoded
2864 expression. When there is an error or timeout it returns an
2865 empty string.
2866
2867 {only available when compiled with the |+channel| feature}
2868
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002869ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
2870 Send {string} over {handle}.
2871 {handle} can be Channel or a Job that has a Channel.
2872
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002873 Works like |ch_evalexpr()|, but does not encode the request or
2874 decode the response. The caller is responsible for the
2875 correct contents. Also does not add a newline for a channel
2876 in NL mode, the caller must do that. The NL in the response
2877 is removed.
2878 See |channel-use|.
2879
2880 {only available when compiled with the |+channel| feature}
2881
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002882ch_getbufnr({handle}, {what}) *ch_getbufnr()*
2883 Get the buffer number that {handle} is using for {what}.
2884 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01002885 {what} can be "err" for stderr, "out" for stdout or empty for
2886 socket output.
2887 Returns -1 when there is no buffer.
2888 {only available when compiled with the |+channel| feature}
2889
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002890ch_getjob({channel}) *ch_getjob()*
2891 Get the Job associated with {channel}.
2892 If there is no job calling |job_status()| on the returned Job
2893 will result in "fail".
2894
2895 {only available when compiled with the |+channel| and
2896 |+job| features}
2897
Bram Moolenaar03602ec2016-03-20 20:57:45 +01002898ch_info({handle}) *ch_info()*
2899 Returns a Dictionary with information about {handle}. The
2900 items are:
2901 "id" number of the channel
2902 "status" "open" (any part is open) or "closed"
2903 When opened with ch_open():
2904 "hostname" the hostname of the address
2905 "port" the port of the address
2906 "sock_status" "open" or "closed"
2907 "sock_mode" "NL", "RAW", "JSON" or "JS"
2908 "sock_io" "socket"
2909 "sock_timeout" timeout in msec
2910 When opened with job_start():
2911 "out_status" "open" or "closed"
2912 "out_mode" "NL", "RAW", "JSON" or "JS"
2913 "out_io" "null", "pipe", "file" or "buffer"
2914 "out_timeout" timeout in msec
2915 "err_status" "open" or "closed"
2916 "err_mode" "NL", "RAW", "JSON" or "JS"
2917 "err_io" "out", "null", "pipe", "file" or "buffer"
2918 "err_timeout" timeout in msec
2919 "in_status" "open" or "closed"
2920 "in_mode" "NL", "RAW", "JSON" or "JS"
2921 "in_io" "null", "pipe", "file" or "buffer"
2922 "in_timeout" timeout in msec
2923
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002924ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002925 Write {msg} in the channel log file, if it was opened with
2926 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002927 When {handle} is passed the channel number is used for the
2928 message.
2929 {handle} can be Channel or a Job that has a Channel. The
2930 Channel must open.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002931
2932ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002933 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002934 When {fname} is an empty string: stop logging.
2935
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002936 When {mode} is omitted or "a" append to the file.
2937 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002938
2939 The file is flushed after every message, on Unix you can use
2940 "tail -f" to see what is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002941
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002942
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002943ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002944 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002945 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002946
2947 {address} has the form "hostname:port", e.g.,
2948 "localhost:8765".
2949
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002950 If {options} is given it must be a |Dictionary|.
2951 See |channel-open-options|.
2952
Bram Moolenaar835dc632016-02-07 14:27:38 +01002953 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002954
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002955ch_read({handle} [, {options}]) *ch_read()*
2956 Read from {handle} and return the received message.
2957 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002958 See |channel-more|.
2959 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002960
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002961ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002962 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002963 the message. See |channel-more|.
2964 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002965
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002966ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
2967 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002968 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002969 with a raw channel.
2970 See |channel-use|. *E912*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002971 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002972
Bram Moolenaar835dc632016-02-07 14:27:38 +01002973 {only available when compiled with the |+channel| feature}
2974
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002975ch_sendraw({handle}, {string} [, {options}]) *ch_sendraw()*
2976 Send {string} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002977 Works like |ch_sendexpr()|, but does not encode the request or
2978 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01002979 correct contents. Also does not add a newline for a channel
2980 in NL mode, the caller must do that. The NL in the response
2981 is removed.
2982 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002983
Bram Moolenaar835dc632016-02-07 14:27:38 +01002984 {only available when compiled with the |+channel| feature}
2985
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002986ch_setoptions({handle}, {options}) *ch_setoptions()*
2987 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002988 "callback" the channel callback
2989 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002990 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002991 See |ch_open()| for more explanation.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002992 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002993
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002994 Note that changing the mode may cause queued messages to be
2995 lost.
2996
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002997 These options cannot be changed:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002998 "waittime" only applies to "ch_open()|
2999
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003000ch_status({handle}) *ch_status()*
3001 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01003002 "fail" failed to open the channel
3003 "open" channel can be used
Bram Moolenaar06481422016-04-30 15:13:38 +02003004 "buffered" channel can be read, not written to
Bram Moolenaar38a55632016-02-15 22:07:32 +01003005 "closed" channel can not be used
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003006 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar06481422016-04-30 15:13:38 +02003007 "buffered" is used when the channel was closed but there is
3008 still data that can be obtained with |ch_read()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003009
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003010 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003011copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003012 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003013 When {expr} is a |List| a shallow copy is created. This means
3014 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003015 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003016 changing an item changes the contents of both |Lists|.
3017 A |Dictionary| is copied in a similar way as a |List|.
3018 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003019
Bram Moolenaar446cb832008-06-24 21:56:24 +00003020cos({expr}) *cos()*
3021 Return the cosine of {expr}, measured in radians, as a |Float|.
3022 {expr} must evaluate to a |Float| or a |Number|.
3023 Examples: >
3024 :echo cos(100)
3025< 0.862319 >
3026 :echo cos(-4.01)
3027< -0.646043
3028 {only available when compiled with the |+float| feature}
3029
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003030
3031cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003032 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003033 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003034 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003035 Examples: >
3036 :echo cosh(0.5)
3037< 1.127626 >
3038 :echo cosh(-0.5)
3039< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02003040 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003041
Bram Moolenaar446cb832008-06-24 21:56:24 +00003042
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003043count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003044 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003045 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003046 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003047 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003048 When {ic} is given and it's non-zero then case is ignored.
3049
3050
Bram Moolenaar071d4272004-06-13 20:20:40 +00003051 *cscope_connection()*
3052cscope_connection([{num} , {dbpath} [, {prepend}]])
3053 Checks for the existence of a |cscope| connection. If no
3054 parameters are specified, then the function returns:
3055 0, if cscope was not available (not compiled in), or
3056 if there are no cscope connections;
3057 1, if there is at least one cscope connection.
3058
3059 If parameters are specified, then the value of {num}
3060 determines how existence of a cscope connection is checked:
3061
3062 {num} Description of existence check
3063 ----- ------------------------------
3064 0 Same as no parameters (e.g., "cscope_connection()").
3065 1 Ignore {prepend}, and use partial string matches for
3066 {dbpath}.
3067 2 Ignore {prepend}, and use exact string matches for
3068 {dbpath}.
3069 3 Use {prepend}, use partial string matches for both
3070 {dbpath} and {prepend}.
3071 4 Use {prepend}, use exact string matches for both
3072 {dbpath} and {prepend}.
3073
3074 Note: All string comparisons are case sensitive!
3075
3076 Examples. Suppose we had the following (from ":cs show"): >
3077
3078 # pid database name prepend path
3079 0 27664 cscope.out /usr/local
3080<
3081 Invocation Return Val ~
3082 ---------- ---------- >
3083 cscope_connection() 1
3084 cscope_connection(1, "out") 1
3085 cscope_connection(2, "out") 0
3086 cscope_connection(3, "out") 0
3087 cscope_connection(3, "out", "local") 1
3088 cscope_connection(4, "out") 0
3089 cscope_connection(4, "out", "local") 0
3090 cscope_connection(4, "cscope.out", "/usr/local") 1
3091<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003092cursor({lnum}, {col} [, {off}]) *cursor()*
3093cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003094 Positions the cursor at the column (byte count) {col} in the
3095 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003096
Bram Moolenaar0b238792006-03-02 22:49:12 +00003097 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003098 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003099 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003100 [{lnum}, {col}, {off}]
3101 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003102 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003103 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003104
Bram Moolenaar071d4272004-06-13 20:20:40 +00003105 Does not change the jumplist.
3106 If {lnum} is greater than the number of lines in the buffer,
3107 the cursor will be positioned at the last line in the buffer.
3108 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003109 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003110 the cursor will be positioned at the last character in the
3111 line.
3112 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003113 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003114 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003115
Bram Moolenaar0b238792006-03-02 22:49:12 +00003116 When 'virtualedit' is used {off} specifies the offset in
3117 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003118 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003119 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003120
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003121
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003122deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003123 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003124 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003125 When {expr} is a |List| a full copy is created. This means
3126 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003127 copy, and vice versa. When an item is a |List| or
3128 |Dictionary|, a copy for it is made, recursively. Thus
3129 changing an item in the copy does not change the contents of
3130 the original |List|.
3131 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003132 When {noref} is omitted or zero a contained |List| or
3133 |Dictionary| is only copied once. All references point to
3134 this single copy. With {noref} set to 1 every occurrence of a
3135 |List| or |Dictionary| results in a new copy. This also means
3136 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003137 *E724*
3138 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003139 that refers back to a higher level making a deep copy with
3140 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003141 Also see |copy()|.
3142
Bram Moolenaarda440d22016-01-16 21:27:23 +01003143delete({fname} [, {flags}]) *delete()*
3144 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003145 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003146
3147 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003148 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003149
3150 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003151 {fname} and everything in it, recursively. BE CAREFUL!
3152 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003153
3154 The result is a Number, which is 0 if the delete operation was
3155 successful and -1 when the deletion failed or partly failed.
3156
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003157 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01003158 To delete a line from the buffer use |:delete|. Use |:exe|
3159 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003160
3161 *did_filetype()*
3162did_filetype() Returns non-zero when autocommands are being executed and the
3163 FileType event has been triggered at least once. Can be used
3164 to avoid triggering the FileType event again in the scripts
3165 that detect the file type. |FileType|
3166 When editing another file, the counter is reset, thus this
3167 really checks if the FileType event has been triggered for the
3168 current buffer. This allows an autocommand that starts
3169 editing another buffer to set 'filetype' and load a syntax
3170 file.
3171
Bram Moolenaar47136d72004-10-12 20:02:24 +00003172diff_filler({lnum}) *diff_filler()*
3173 Returns the number of filler lines above line {lnum}.
3174 These are the lines that were inserted at this point in
3175 another diff'ed window. These filler lines are shown in the
3176 display but don't exist in the buffer.
3177 {lnum} is used like with |getline()|. Thus "." is the current
3178 line, "'m" mark m, etc.
3179 Returns 0 if the current window is not in diff mode.
3180
3181diff_hlID({lnum}, {col}) *diff_hlID()*
3182 Returns the highlight ID for diff mode at line {lnum} column
3183 {col} (byte index). When the current line does not have a
3184 diff change zero is returned.
3185 {lnum} is used like with |getline()|. Thus "." is the current
3186 line, "'m" mark m, etc.
3187 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3188 line.
3189 The highlight ID can be used with |synIDattr()| to obtain
3190 syntax information about the highlighting.
3191
Bram Moolenaar13065c42005-01-08 16:08:21 +00003192empty({expr}) *empty()*
3193 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003194 - A |List| or |Dictionary| is empty when it does not have any
3195 items.
3196 - A Number and Float is empty when its value is zero.
3197 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
3198 - A Job is empty when it failed to start.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003199 - A Channel is empty when it is closed.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003200
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003201 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003202 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003203
Bram Moolenaar071d4272004-06-13 20:20:40 +00003204escape({string}, {chars}) *escape()*
3205 Escape the characters in {chars} that occur in {string} with a
3206 backslash. Example: >
3207 :echo escape('c:\program files\vim', ' \')
3208< results in: >
3209 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00003210< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003211
Bram Moolenaar446cb832008-06-24 21:56:24 +00003212 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003213eval({string}) Evaluate {string} and return the result. Especially useful to
3214 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003215 This works for Numbers, Floats, Strings and composites of
3216 them. Also works for |Funcref|s that refer to existing
3217 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003218
Bram Moolenaar071d4272004-06-13 20:20:40 +00003219eventhandler() *eventhandler()*
3220 Returns 1 when inside an event handler. That is that Vim got
3221 interrupted while waiting for the user to type a character,
3222 e.g., when dropping a file on Vim. This means interactive
3223 commands cannot be used. Otherwise zero is returned.
3224
3225executable({expr}) *executable()*
3226 This function checks if an executable with the name {expr}
3227 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003228 arguments.
3229 executable() uses the value of $PATH and/or the normal
3230 searchpath for programs. *PATHEXT*
3231 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3232 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00003233 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3234 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003235 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00003236 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003237 Unix shell, then the name is also tried without adding an
3238 extension.
3239 On MS-DOS and MS-Windows it only checks if the file exists and
3240 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003241 On MS-Windows an executable in the same directory as Vim is
3242 always found. Since this directory is added to $PATH it
3243 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244 The result is a Number:
3245 1 exists
3246 0 does not exist
3247 -1 not implemented on this system
3248
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003249exepath({expr}) *exepath()*
3250 If {expr} is an executable and is either an absolute path, a
3251 relative path or found in $PATH, return the full path.
3252 Note that the current directory is used when {expr} starts
3253 with "./", which may be a problem for Vim: >
3254 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003255< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003256 an empty string is returned.
3257
Bram Moolenaar071d4272004-06-13 20:20:40 +00003258 *exists()*
3259exists({expr}) The result is a Number, which is non-zero if {expr} is
3260 defined, zero otherwise. The {expr} argument is a string,
3261 which contains one of these:
3262 &option-name Vim option (only checks if it exists,
3263 not if it really works)
3264 +option-name Vim option that works.
3265 $ENVNAME environment variable (could also be
3266 done by comparing with an empty
3267 string)
3268 *funcname built-in function (see |functions|)
3269 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003270 |user-functions|). Also works for a
3271 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003272 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00003273 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003274 for |curly-braces-names|, |Dictionary|
3275 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003276 that evaluating an index may cause an
3277 error message for an invalid
3278 expression. E.g.: >
3279 :let l = [1, 2, 3]
3280 :echo exists("l[5]")
3281< 0 >
3282 :echo exists("l[xx]")
3283< E121: Undefined variable: xx
3284 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00003285 :cmdname Ex command: built-in command, user
3286 command or command modifier |:command|.
3287 Returns:
3288 1 for match with start of a command
3289 2 full match with a command
3290 3 matches several user commands
3291 To check for a supported command
3292 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00003293 :2match The |:2match| command.
3294 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003295 #event autocommand defined for this event
3296 #event#pattern autocommand defined for this event and
3297 pattern (the pattern is taken
3298 literally and compared to the
3299 autocommand patterns character by
3300 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003301 #group autocommand group exists
3302 #group#event autocommand defined for this group and
3303 event.
3304 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003305 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003306 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003307 ##event autocommand for this event is
3308 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003309 For checking for a supported feature use |has()|.
3310
3311 Examples: >
3312 exists("&shortname")
3313 exists("$HOSTNAME")
3314 exists("*strftime")
3315 exists("*s:MyFunc")
3316 exists("bufcount")
3317 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003318 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003319 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003320 exists("#filetypeindent")
3321 exists("#filetypeindent#FileType")
3322 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003323 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003324< There must be no space between the symbol (&/$/*/#) and the
3325 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003326 There must be no extra characters after the name, although in
3327 a few cases this is ignored. That may become more strict in
3328 the future, thus don't count on it!
3329 Working example: >
3330 exists(":make")
3331< NOT working example: >
3332 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00003333
3334< Note that the argument must be a string, not the name of the
3335 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003336 exists(bufcount)
3337< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00003338 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003339
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003340exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003341 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003342 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003343 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003344 Examples: >
3345 :echo exp(2)
3346< 7.389056 >
3347 :echo exp(-1)
3348< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02003349 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003350
3351
Bram Moolenaar84f72352012-03-11 15:57:40 +01003352expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003353 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003354 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003355
Bram Moolenaar84f72352012-03-11 15:57:40 +01003356 If {list} is given and it is non-zero, a List will be returned.
3357 Otherwise the result is a String and when there are several
3358 matches, they are separated by <NL> characters. [Note: in
3359 version 5.0 a space was used, which caused problems when a
3360 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00003361
Bram Moolenaar446cb832008-06-24 21:56:24 +00003362 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02003363 for a non-existing file is not included, unless {expr} does
3364 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003365
3366 When {expr} starts with '%', '#' or '<', the expansion is done
3367 like for the |cmdline-special| variables with their associated
3368 modifiers. Here is a short overview:
3369
3370 % current file name
3371 # alternate file name
3372 #n alternate file name n
3373 <cfile> file name under the cursor
3374 <afile> autocmd file name
3375 <abuf> autocmd buffer number (as a String!)
3376 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01003377 <sfile> sourced script file or function name
Bram Moolenaar81af9252010-12-10 20:35:50 +01003378 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00003379 <cword> word under the cursor
3380 <cWORD> WORD under the cursor
3381 <client> the {clientid} of the last received
3382 message |server2client()|
3383 Modifiers:
3384 :p expand to full path
3385 :h head (last path component removed)
3386 :t tail (last path component only)
3387 :r root (one extension removed)
3388 :e extension only
3389
3390 Example: >
3391 :let &tags = expand("%:p:h") . "/tags"
3392< Note that when expanding a string that starts with '%', '#' or
3393 '<', any following text is ignored. This does NOT work: >
3394 :let doesntwork = expand("%:h.bak")
3395< Use this: >
3396 :let doeswork = expand("%:h") . ".bak"
3397< Also note that expanding "<cfile>" and others only returns the
3398 referenced file name without further expansion. If "<cfile>"
3399 is "~/.cshrc", you need to do another expand() to have the
3400 "~/" expanded into the path of the home directory: >
3401 :echo expand(expand("<cfile>"))
3402<
3403 There cannot be white space between the variables and the
3404 following modifier. The |fnamemodify()| function can be used
3405 to modify normal file names.
3406
3407 When using '%' or '#', and the current or alternate file name
3408 is not defined, an empty string is used. Using "%:p" in a
3409 buffer with no name, results in the current directory, with a
3410 '/' added.
3411
3412 When {expr} does not start with '%', '#' or '<', it is
3413 expanded like a file name is expanded on the command line.
3414 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaar146e9c32012-03-07 19:18:23 +01003415 {nosuf} argument is given and it is non-zero.
3416 Names for non-existing files are included. The "**" item can
3417 be used to search in a directory tree. For example, to find
3418 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00003419 :echo expand("**/README")
3420<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003421 Expand() can also be used to expand variables and environment
3422 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003423 slow, because a shell may be used to do the expansion. See
3424 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003425 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00003426 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003427 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3428 "$FOOBAR".
3429
3430 See |glob()| for finding existing files. See |system()| for
3431 getting the raw output of an external command.
3432
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003433extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003434 {expr1} and {expr2} must be both |Lists| or both
3435 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003436
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003437 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003438 If {expr3} is given insert the items of {expr2} before item
3439 {expr3} in {expr1}. When {expr3} is zero insert before the
3440 first item. When {expr3} is equal to len({expr1}) then
3441 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003442 Examples: >
3443 :echo sort(extend(mylist, [7, 5]))
3444 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00003445< When {expr1} is the same List as {expr2} then the number of
3446 items copied is equal to the original length of the List.
3447 E.g., when {expr3} is 1 you get N new copies of the first item
3448 (where N is the original length of the List).
3449 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003450 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003451 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003452<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003453 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003454 Add all entries from {expr2} to {expr1}.
3455 If a key exists in both {expr1} and {expr2} then {expr3} is
3456 used to decide what to do:
3457 {expr3} = "keep": keep the value of {expr1}
3458 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003459 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003460 When {expr3} is omitted then "force" is assumed.
3461
3462 {expr1} is changed when {expr2} is not empty. If necessary
3463 make a copy of {expr1} first.
3464 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02003465 When {expr1} is locked and {expr2} is not empty the operation
3466 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003467 Returns {expr1}.
3468
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003469
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003470feedkeys({string} [, {mode}]) *feedkeys()*
3471 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003472 come from a mapping or were typed by the user.
3473 By default the string is added to the end of the typeahead
3474 buffer, thus if a mapping is still being executed the
3475 characters come after them. Use the 'i' flag to insert before
3476 other characters, they will be executed next, before any
3477 characters from a mapping.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003478 The function does not wait for processing of keys contained in
3479 {string}.
3480 To include special keys into {string}, use double-quotes
3481 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00003482 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003483 feedkeys('\<CR>') pushes 5 characters.
3484 If {mode} is absent, keys are remapped.
3485 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003486 'm' Remap keys. This is default.
3487 'n' Do not remap keys.
3488 't' Handle keys as if typed; otherwise they are handled as
3489 if coming from a mapping. This matters for undo,
3490 opening folds, etc.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003491 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01003492 'x' Execute commands until typeahead is empty. This is
3493 similar to using ":normal!". You can call feedkeys()
3494 several times without 'x' and then one time with 'x'
3495 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02003496 typeahead. Note that when Vim ends in Insert mode it
3497 will behave as if <Esc> is typed, to avoid getting
3498 stuck, waiting for a character to be typed before the
3499 script continues.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003500 '!' When used with 'x' will not end Insert mode. Can be
3501 used in a test when a timer is set to exit Insert mode
3502 a little later. Useful for testing CursorHoldI.
3503
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003504 Return value is always 0.
3505
Bram Moolenaar071d4272004-06-13 20:20:40 +00003506filereadable({file}) *filereadable()*
3507 The result is a Number, which is TRUE when a file with the
3508 name {file} exists, and can be read. If {file} doesn't exist,
3509 or is a directory, the result is FALSE. {file} is any
3510 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003511 If you don't care about the file being readable you can use
3512 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003513 *file_readable()*
3514 Obsolete name: file_readable().
3515
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003516
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003517filewritable({file}) *filewritable()*
3518 The result is a Number, which is 1 when a file with the
3519 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00003520 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003521 directory, and we can write to it, the result is 2.
3522
3523
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003524filter({expr1}, {expr2}) *filter()*
3525 {expr1} must be a |List| or a |Dictionary|.
3526 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003527 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003528 {expr2} must be a |string| or |Funcref|.
3529
3530 if {expr2} is a |string|, inside {expr2} |v:val| has the value
3531 of the current item. For a |Dictionary| |v:key| has the key
3532 of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003533 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003534 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003535< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003536 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003537< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003538 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003539< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003540
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003541 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003542 used as an expression again. Often it is good to use a
3543 |literal-string| to avoid having to double backslashes.
3544
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003545 If {expr2} is a |Funcref| it must take two arguments:
3546 1. the key or the index of the current item.
3547 2. the value of the current item.
3548 The function must return TRUE if the item should be kept.
3549 Example that keeps the odd items of a list: >
3550 func Odd(idx, val)
3551 return a:idx % 2 == 1
3552 endfunc
3553 call filter(mylist, function('Odd'))
3554<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003555 The operation is done in-place. If you want a |List| or
3556 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00003557 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003558
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02003559< Returns {expr1}, the |List| or |Dictionary| that was filtered.
3560 When an error is encountered while evaluating {expr2} no
3561 further items in {expr1} are processed. When {expr2} is a
3562 Funcref errors inside a function are ignored, unless it was
3563 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003564
3565
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003566finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00003567 Find directory {name} in {path}. Supports both downwards and
3568 upwards recursive directory searches. See |file-searching|
3569 for the syntax of {path}.
3570 Returns the path of the first found match. When the found
3571 directory is below the current directory a relative path is
3572 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003573 If {path} is omitted or empty then 'path' is used.
3574 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003575 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00003576 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003577 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003578 {only available when compiled with the |+file_in_path|
3579 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003580
3581findfile({name}[, {path}[, {count}]]) *findfile()*
3582 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003583 Uses 'suffixesadd'.
3584 Example: >
3585 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003586< Searches from the directory of the current file upwards until
3587 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003588
Bram Moolenaar446cb832008-06-24 21:56:24 +00003589float2nr({expr}) *float2nr()*
3590 Convert {expr} to a Number by omitting the part after the
3591 decimal point.
3592 {expr} must evaluate to a |Float| or a Number.
3593 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003594 result is truncated to 0x7fffffff or -0x7fffffff (or when
3595 64-bit Number support is enabled, 0x7fffffffffffffff or
3596 -0x7fffffffffffffff. NaN results in -0x80000000 (or when
3597 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00003598 Examples: >
3599 echo float2nr(3.95)
3600< 3 >
3601 echo float2nr(-23.45)
3602< -23 >
3603 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003604< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00003605 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02003606< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00003607 echo float2nr(1.0e-100)
3608< 0
3609 {only available when compiled with the |+float| feature}
3610
3611
3612floor({expr}) *floor()*
3613 Return the largest integral value less than or equal to
3614 {expr} as a |Float| (round down).
3615 {expr} must evaluate to a |Float| or a |Number|.
3616 Examples: >
3617 echo floor(1.856)
3618< 1.0 >
3619 echo floor(-5.456)
3620< -6.0 >
3621 echo floor(4.0)
3622< 4.0
3623 {only available when compiled with the |+float| feature}
3624
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003625
3626fmod({expr1}, {expr2}) *fmod()*
3627 Return the remainder of {expr1} / {expr2}, even if the
3628 division is not representable. Returns {expr1} - i * {expr2}
3629 for some integer i such that if {expr2} is non-zero, the
3630 result has the same sign as {expr1} and magnitude less than
3631 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003632 returned is zero. The value returned is a |Float|.
3633 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003634 Examples: >
3635 :echo fmod(12.33, 1.22)
3636< 0.13 >
3637 :echo fmod(-12.33, 1.22)
3638< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003639 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003640
3641
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003642fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003643 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003644 characters that have a special meaning, such as '%' and '|'
3645 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003646 For most systems the characters escaped are
3647 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3648 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003649 A leading '+' and '>' is also escaped (special after |:edit|
3650 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003651 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003652 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003653 :exe "edit " . fnameescape(fname)
3654< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003655 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003656
Bram Moolenaar071d4272004-06-13 20:20:40 +00003657fnamemodify({fname}, {mods}) *fnamemodify()*
3658 Modify file name {fname} according to {mods}. {mods} is a
3659 string of characters like it is used for file names on the
3660 command line. See |filename-modifiers|.
3661 Example: >
3662 :echo fnamemodify("main.c", ":p:h")
3663< results in: >
3664 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003665< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003666 |expand()| first then.
3667
3668foldclosed({lnum}) *foldclosed()*
3669 The result is a Number. If the line {lnum} is in a closed
3670 fold, the result is the number of the first line in that fold.
3671 If the line {lnum} is not in a closed fold, -1 is returned.
3672
3673foldclosedend({lnum}) *foldclosedend()*
3674 The result is a Number. If the line {lnum} is in a closed
3675 fold, the result is the number of the last line in that fold.
3676 If the line {lnum} is not in a closed fold, -1 is returned.
3677
3678foldlevel({lnum}) *foldlevel()*
3679 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003680 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003681 returned. If there is no fold at line {lnum}, zero is
3682 returned. It doesn't matter if the folds are open or closed.
3683 When used while updating folds (from 'foldexpr') -1 is
3684 returned for lines where folds are still to be updated and the
3685 foldlevel is unknown. As a special case the level of the
3686 previous line is usually available.
3687
3688 *foldtext()*
3689foldtext() Returns a String, to be displayed for a closed fold. This is
3690 the default function used for the 'foldtext' option and should
3691 only be called from evaluating 'foldtext'. It uses the
3692 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3693 The returned string looks like this: >
3694 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003695< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003696 the number of lines in the fold. "abcdef" is the text in the
3697 first non-blank line of the fold. Leading white space, "//"
3698 or "/*" and the text from the 'foldmarker' and 'commentstring'
3699 options is removed.
3700 {not available when compiled without the |+folding| feature}
3701
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003702foldtextresult({lnum}) *foldtextresult()*
3703 Returns the text that is displayed for the closed fold at line
3704 {lnum}. Evaluates 'foldtext' in the appropriate context.
3705 When there is no closed fold at {lnum} an empty string is
3706 returned.
3707 {lnum} is used like with |getline()|. Thus "." is the current
3708 line, "'m" mark m, etc.
3709 Useful when exporting folded text, e.g., to HTML.
3710 {not available when compiled without the |+folding| feature}
3711
Bram Moolenaar071d4272004-06-13 20:20:40 +00003712 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003713foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003714 a client to a Vim server. |remote_send()|
3715 On Win32 systems this might not work, the OS does not always
3716 allow a window to bring itself to the foreground. Use
3717 |remote_foreground()| instead.
3718 {only in the Win32, Athena, Motif and GTK GUI versions and the
3719 Win32 console version}
3720
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003721
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003722 *function()* *E700* *E922* *E923*
3723function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003724 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01003725 {name} can be the name of a user defined function or an
3726 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003727
Bram Moolenaar975b5272016-03-15 23:10:59 +01003728 {name} can also be a Funcref, also a partial. When it is a
3729 partial the dict stored in it will be used and the {dict}
3730 argument is not allowed. E.g.: >
3731 let FuncWithArg = function(dict.Func, [arg])
3732 let Broken = function(dict.Func, [arg], dict)
3733<
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003734 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02003735 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003736 the Funcref and will be used when the Funcref is called.
3737
3738 The arguments are passed to the function in front of other
3739 arguments. Example: >
3740 func Callback(arg1, arg2, name)
3741 ...
3742 let Func = function('Callback', ['one', 'two'])
3743 ...
3744 call Func('name')
3745< Invokes the function as with: >
3746 call Callback('one', 'two', 'name')
3747
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003748< The function() call can be nested to add more arguments to the
3749 Funcref. The extra arguments are appended to the list of
3750 arguments. Example: >
3751 func Callback(arg1, arg2, name)
3752 ...
3753 let Func = function('Callback', ['one'])
3754 let Func2 = function(Func, ['two'])
3755 ...
3756 call Func2('name')
3757< Invokes the function as with: >
3758 call Callback('one', 'two', 'name')
3759
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003760< The Dictionary is only useful when calling a "dict" function.
3761 In that case the {dict} is passed in as "self". Example: >
3762 function Callback() dict
3763 echo "called for " . self.name
3764 endfunction
3765 ...
3766 let context = {"name": "example"}
3767 let Func = function('Callback', context)
3768 ...
3769 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01003770< The use of function() is not needed when there are no extra
3771 arguments, these two are equivalent: >
3772 let Func = function('Callback', context)
3773 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003774
3775< The argument list and the Dictionary can be combined: >
3776 function Callback(arg1, count) dict
3777 ...
3778 let context = {"name": "example"}
3779 let Func = function('Callback', ['one'], context)
3780 ...
3781 call Func(500)
3782< Invokes the function as with: >
3783 call context.Callback('one', 500)
3784
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003785
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003786garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003787 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3788 that have circular references.
3789
3790 There is hardly ever a need to invoke this function, as it is
3791 automatically done when Vim runs out of memory or is waiting
3792 for the user to press a key after 'updatetime'. Items without
3793 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003794 This is useful if you have deleted a very big |List| and/or
3795 |Dictionary| with circular references in a script that runs
3796 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003797
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003798 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003799 collection will also be done when exiting Vim, if it wasn't
3800 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003801
Bram Moolenaar574860b2016-05-24 17:33:34 +02003802 The garbage collection is not done immediately but only when
3803 it's safe to perform. This is when waiting for the user to
3804 type a character. To force garbage collection immediately use
3805 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003806
Bram Moolenaar677ee682005-01-27 14:41:15 +00003807get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003808 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003809 available return {default}. Return zero when {default} is
3810 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003811get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003812 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003813 item is not available return {default}. Return zero when
3814 {default} is omitted.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02003815get({func}, {what})
3816 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02003817 {what} are:
Bram Moolenaar03e19a02016-05-24 22:29:49 +02003818 'name' The function name
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02003819 'func' The function
3820 'dict' The dictionary
3821 'args' The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003822
Bram Moolenaar45360022005-07-21 21:08:21 +00003823 *getbufline()*
3824getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003825 Return a |List| with the lines starting from {lnum} to {end}
3826 (inclusive) in the buffer {expr}. If {end} is omitted, a
3827 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003828
3829 For the use of {expr}, see |bufname()| above.
3830
Bram Moolenaar661b1822005-07-28 22:36:45 +00003831 For {lnum} and {end} "$" can be used for the last line of the
3832 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003833
3834 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003835 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003836
3837 When {end} is greater than the number of lines in the buffer,
3838 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003839 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003840 returned.
3841
Bram Moolenaar661b1822005-07-28 22:36:45 +00003842 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003843 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003844
3845 Example: >
3846 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003847
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003848getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003849 The result is the value of option or local buffer variable
3850 {varname} in buffer {expr}. Note that the name without "b:"
3851 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003852 When {varname} is empty returns a dictionary with all the
3853 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003854 This also works for a global or buffer-local option, but it
3855 doesn't work for a global variable, window-local variable or
3856 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003857 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003858 When the buffer or variable doesn't exist {def} or an empty
3859 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003860 Examples: >
3861 :let bufmodified = getbufvar(1, "&mod")
3862 :echo "todo myvar = " . getbufvar("todo", "myvar")
3863<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003864getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003865 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003866 If [expr] is omitted, wait until a character is available.
3867 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003868 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003869 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003870 not consumed. Return zero if no character available.
3871
Bram Moolenaardfb18412013-12-11 18:53:29 +01003872 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaar91170f82006-05-05 21:15:17 +00003873 special key is returned. If it is an 8-bit character, the
3874 result is a number. Use nr2char() to convert it to a String.
3875 Otherwise a String is returned with the encoded character.
3876 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003877 (decimal: 128). This is the same value as the string
3878 "\<Key>", e.g., "\<Left>". The returned value is also a
3879 String when a modifier (shift, control, alt) was used that is
3880 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003881
Bram Moolenaar822ff862014-06-12 21:46:14 +02003882 When [expr] is 0 and Esc is typed, there will be a short delay
3883 while Vim waits to see if this is the start of an escape
3884 sequence.
3885
Bram Moolenaardfb18412013-12-11 18:53:29 +01003886 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003887 one-byte character it is the character itself as a number.
3888 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003889
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003890 Use getcharmod() to obtain any additional modifiers.
3891
Bram Moolenaar219b8702006-11-01 14:32:36 +00003892 When the user clicks a mouse button, the mouse event will be
3893 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02003894 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
3895 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00003896 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003897 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003898 exe v:mouse_win . "wincmd w"
3899 exe v:mouse_lnum
3900 exe "normal " . v:mouse_col . "|"
3901 endif
3902<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003903 There is no prompt, you will somehow have to make clear to the
3904 user that a character has to be typed.
3905 There is no mapping for the character.
3906 Key codes are replaced, thus when the user presses the <Del>
3907 key you get the code for the <Del> key, not the raw character
3908 sequence. Examples: >
3909 getchar() == "\<Del>"
3910 getchar() == "\<S-Left>"
3911< This example redefines "f" to ignore case: >
3912 :nmap f :call FindChar()<CR>
3913 :function FindChar()
3914 : let c = nr2char(getchar())
3915 : while col('.') < col('$') - 1
3916 : normal l
3917 : if getline('.')[col('.') - 1] ==? c
3918 : break
3919 : endif
3920 : endwhile
3921 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01003922<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003923 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01003924 |<CursorHold>|. Often you will want to ignore this and get
3925 another character: >
3926 :function GetKey()
3927 : let c = getchar()
3928 : while c == "\<CursorHold>"
3929 : let c = getchar()
3930 : endwhile
3931 : return c
3932 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00003933
3934getcharmod() *getcharmod()*
3935 The result is a Number which is the state of the modifiers for
3936 the last obtained character with getchar() or in another way.
3937 These values are added together:
3938 2 shift
3939 4 control
3940 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003941 16 meta (when it's different from ALT)
3942 32 mouse double click
3943 64 mouse triple click
3944 96 mouse quadruple click (== 32 + 64)
3945 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003946 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003947 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003948 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003949
Bram Moolenaardbd24b52015-08-11 14:26:19 +02003950getcharsearch() *getcharsearch()*
3951 Return the current character search information as a {dict}
3952 with the following entries:
3953
3954 char character previously used for a character
3955 search (|t|, |f|, |T|, or |F|); empty string
3956 if no character search has been performed
3957 forward direction of character search; 1 for forward,
3958 0 for backward
3959 until type of character search; 1 for a |t| or |T|
3960 character search, 0 for an |f| or |F|
3961 character search
3962
3963 This can be useful to always have |;| and |,| search
3964 forward/backward regardless of the direction of the previous
3965 character search: >
3966 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3967 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3968< Also see |setcharsearch()|.
3969
Bram Moolenaar071d4272004-06-13 20:20:40 +00003970getcmdline() *getcmdline()*
3971 Return the current command-line. Only works when the command
3972 line is being edited, thus requires use of |c_CTRL-\_e| or
3973 |c_CTRL-R_=|.
3974 Example: >
3975 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003976< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003977
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003978getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003979 Return the position of the cursor in the command line as a
3980 byte count. The first column is 1.
3981 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003982 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3983 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003984 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3985
3986getcmdtype() *getcmdtype()*
3987 Return the current command-line type. Possible return values
3988 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003989 : normal Ex command
3990 > debug mode command |debug-mode|
3991 / forward search command
3992 ? backward search command
3993 @ |input()| command
3994 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02003995 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003996 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003997 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3998 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003999 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004000
Bram Moolenaarfb539272014-08-22 19:21:47 +02004001getcmdwintype() *getcmdwintype()*
4002 Return the current |command-line-window| type. Possible return
4003 values are the same as |getcmdtype()|. Returns an empty string
4004 when not in the command-line window.
4005
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004006 *getcurpos()*
4007getcurpos() Get the position of the cursor. This is like getpos('.'), but
4008 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01004009 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004010 The "curswant" number is the preferred column when moving the
4011 cursor vertically.
4012 This can be used to save and restore the cursor position: >
4013 let save_cursor = getcurpos()
4014 MoveTheCursorAround
4015 call setpos('.', save_cursor)
Bram Moolenaarfb539272014-08-22 19:21:47 +02004016<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004017 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01004018getcwd([{winnr} [, {tabnr}]])
4019 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00004020 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004021 Without arguments, for the current window.
4022
4023 With {winnr} return the local current directory of this window
4024 in the current tab page.
4025 With {winnr} and {tabnr} return the local current directory of
4026 the window in the specified tab page.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004027 {winnr} can be the window number or the window ID.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004028 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004029
4030getfsize({fname}) *getfsize()*
4031 The result is a Number, which is the size in bytes of the
4032 given file {fname}.
4033 If {fname} is a directory, 0 is returned.
4034 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00004035 If the size of {fname} is too big to fit in a Number then -2
4036 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004037
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004038getfontname([{name}]) *getfontname()*
4039 Without an argument returns the name of the normal font being
4040 used. Like what is used for the Normal highlight group
4041 |hl-Normal|.
4042 With an argument a check is done whether {name} is a valid
4043 font name. If not then an empty string is returned.
4044 Otherwise the actual font name is returned, or {name} if the
4045 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00004046 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004047 gvimrc file. Use the |GUIEnter| autocommand to use this
4048 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004049 Note that the GTK 2 GUI accepts any font name, thus checking
4050 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004051
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004052getfperm({fname}) *getfperm()*
4053 The result is a String, which is the read, write, and execute
4054 permissions of the given file {fname}.
4055 If {fname} does not exist or its directory cannot be read, an
4056 empty string is returned.
4057 The result is of the form "rwxrwxrwx", where each group of
4058 "rwx" flags represent, in turn, the permissions of the owner
4059 of the file, the group the file belongs to, and other users.
4060 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02004061 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004062 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02004063 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004064< This will hopefully (from a security point of view) display
4065 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004066
Bram Moolenaar80492532016-03-08 17:08:53 +01004067 For setting permissins use |setfperm()|.
4068
Bram Moolenaar071d4272004-06-13 20:20:40 +00004069getftime({fname}) *getftime()*
4070 The result is a Number, which is the last modification time of
4071 the given file {fname}. The value is measured as seconds
4072 since 1st Jan 1970, and may be passed to strftime(). See also
4073 |localtime()| and |strftime()|.
4074 If the file {fname} can't be found -1 is returned.
4075
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004076getftype({fname}) *getftype()*
4077 The result is a String, which is a description of the kind of
4078 file of the given file {fname}.
4079 If {fname} does not exist an empty string is returned.
4080 Here is a table over different kinds of files and their
4081 results:
4082 Normal file "file"
4083 Directory "dir"
4084 Symbolic link "link"
4085 Block device "bdev"
4086 Character device "cdev"
4087 Socket "socket"
4088 FIFO "fifo"
4089 All other "other"
4090 Example: >
4091 getftype("/home")
4092< Note that a type such as "link" will only be returned on
4093 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01004094 "file" are returned. On MS-Windows a symbolic link to a
4095 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004096
Bram Moolenaar071d4272004-06-13 20:20:40 +00004097 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004098getline({lnum} [, {end}])
4099 Without {end} the result is a String, which is line {lnum}
4100 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004101 getline(1)
4102< When {lnum} is a String that doesn't start with a
4103 digit, line() is called to translate the String into a Number.
4104 To get the line under the cursor: >
4105 getline(".")
4106< When {lnum} is smaller than 1 or bigger than the number of
4107 lines in the buffer, an empty string is returned.
4108
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004109 When {end} is given the result is a |List| where each item is
4110 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004111 including line {end}.
4112 {end} is used in the same way as {lnum}.
4113 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004114 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004115 Example: >
4116 :let start = line('.')
4117 :let end = search("^$") - 1
4118 :let lines = getline(start, end)
4119
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004120< To get lines from another buffer see |getbufline()|
4121
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004122getloclist({nr}) *getloclist()*
4123 Returns a list with all the entries in the location list for
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004124 window {nr}. {nr} can be the window number or the window ID.
4125 When {nr} is zero the current window is used.
4126
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004127 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00004128 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004129 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004130
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004131getmatches() *getmatches()*
4132 Returns a |List| with all matches previously defined by
4133 |matchadd()| and the |:match| commands. |getmatches()| is
4134 useful in combination with |setmatches()|, as |setmatches()|
4135 can restore a list of matches saved by |getmatches()|.
4136 Example: >
4137 :echo getmatches()
4138< [{'group': 'MyGroup1', 'pattern': 'TODO',
4139 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4140 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4141 :let m = getmatches()
4142 :call clearmatches()
4143 :echo getmatches()
4144< [] >
4145 :call setmatches(m)
4146 :echo getmatches()
4147< [{'group': 'MyGroup1', 'pattern': 'TODO',
4148 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4149 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4150 :unlet m
4151<
Bram Moolenaar822ff862014-06-12 21:46:14 +02004152 *getpid()*
4153getpid() Return a Number which is the process ID of the Vim process.
4154 On Unix and MS-Windows this is a unique number, until Vim
4155 exits. On MS-DOS it's always zero.
4156
4157 *getpos()*
4158getpos({expr}) Get the position for {expr}. For possible values of {expr}
4159 see |line()|. For getting the cursor position see
4160 |getcurpos()|.
4161 The result is a |List| with four numbers:
4162 [bufnum, lnum, col, off]
4163 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4164 is the buffer number of the mark.
4165 "lnum" and "col" are the position in the buffer. The first
4166 column is 1.
4167 The "off" number is zero, unless 'virtualedit' is used. Then
4168 it is the offset in screen columns from the start of the
4169 character. E.g., a position within a <Tab> or after the last
4170 character.
4171 Note that for '< and '> Visual mode matters: when it is "V"
4172 (visual line mode) the column of '< is zero and the column of
4173 '> is a large number.
4174 This can be used to save and restore the position of a mark: >
4175 let save_a_mark = getpos("'a")
4176 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01004177 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02004178< Also see |getcurpos()| and |setpos()|.
4179
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004180
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004181getqflist() *getqflist()*
4182 Returns a list with all the current quickfix errors. Each
4183 list item is a dictionary with these entries:
4184 bufnr number of buffer that has the file name, use
4185 bufname() to get the name
4186 lnum line number in the buffer (first line is 1)
4187 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00004188 vcol non-zero: "col" is visual column
4189 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004190 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004191 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004192 text description of the error
4193 type type of the error, 'E', '1', etc.
4194 valid non-zero: recognized error message
4195
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004196 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004197 returned. Quickfix list entries with non-existing buffer
4198 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004199
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004200 Useful application: Find pattern matches in multiple files and
4201 do something with them: >
4202 :vimgrep /theword/jg *.c
4203 :for d in getqflist()
4204 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4205 :endfor
4206
4207
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004208getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004209 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004210 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004211 :let cliptext = getreg('*')
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004212< When {regname} was not set the result is a empty string.
4213
4214 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004215 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004216 getreg('=', 1) returns the expression itself, so that it can
4217 be restored with |setreg()|. For other registers the extra
4218 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004219
4220 If {list} is present and non-zero, the result type is changed
4221 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004222 about zero bytes possibly present inside register: without
4223 third argument both NLs and zero bytes are represented as NLs
4224 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004225 When the register was not set an empty list is returned.
4226
Bram Moolenaar071d4272004-06-13 20:20:40 +00004227 If {regname} is not specified, |v:register| is used.
4228
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004229
Bram Moolenaar071d4272004-06-13 20:20:40 +00004230getregtype([{regname}]) *getregtype()*
4231 The result is a String, which is type of register {regname}.
4232 The value will be one of:
4233 "v" for |characterwise| text
4234 "V" for |linewise| text
4235 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01004236 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00004237 <CTRL-V> is one character with value 0x16.
4238 If {regname} is not specified, |v:register| is used.
4239
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004240gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004241 Get the value of a tab-local variable {varname} in tab page
4242 {tabnr}. |t:var|
4243 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02004244 When {varname} is empty a dictionary with all tab-local
4245 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004246 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004247 When the tab or variable doesn't exist {def} or an empty
4248 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004249
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004250gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004251 Get the value of window-local variable {varname} in window
4252 {winnr} in tab page {tabnr}.
4253 When {varname} starts with "&" get the value of a window-local
4254 option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004255 When {varname} is empty a dictionary with all window-local
4256 variables is returned.
4257 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004258 Tabs are numbered starting with one. For the current tabpage
4259 use |getwinvar()|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004260 {winnr} can be the window number or the window ID.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004261 When {winnr} is zero the current window is used.
4262 This also works for a global option, buffer-local option and
4263 window-local option, but it doesn't work for a global variable
4264 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004265 When the tab, window or variable doesn't exist {def} or an
4266 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004267 Examples: >
4268 :let list_is_on = gettabwinvar(1, 2, '&list')
4269 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004270<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004271 *getwinposx()*
4272getwinposx() The result is a Number, which is the X coordinate in pixels of
4273 the left hand side of the GUI Vim window. The result will be
4274 -1 if the information is not available.
4275
4276 *getwinposy()*
4277getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004278 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004279 information is not available.
4280
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004281getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004282 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004283 Examples: >
4284 :let list_is_on = getwinvar(2, '&list')
4285 :echo "myvar = " . getwinvar(1, 'myvar')
4286<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004287glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004288 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004289 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004290
4291 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004292 the 'suffixes' and 'wildignore' options apply: Names matching
4293 one of the patterns in 'wildignore' will be skipped and
4294 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01004295 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004296
4297 When {list} is present and it is non-zero the result is a List
4298 with all matching files. The advantage of using a List is,
4299 you also get filenames containing newlines correctly.
4300 Otherwise the result is a String and when there are several
4301 matches, they are separated by <NL> characters.
4302
4303 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004304
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02004305 A name for a non-existing file is not included. A symbolic
4306 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004307 However, when the {alllinks} argument is present and it is
4308 non-zero then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004309
4310 For most systems backticks can be used to get files names from
4311 any external command. Example: >
4312 :let tagfiles = glob("`find . -name tags -print`")
4313 :let &tags = substitute(tagfiles, "\n", ",", "g")
4314< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00004315 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004316
4317 See |expand()| for expanding special Vim variables. See
4318 |system()| for getting the raw output of an external command.
4319
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01004320glob2regpat({expr}) *glob2regpat()*
4321 Convert a file pattern, as used by glob(), into a search
4322 pattern. The result can be used to match with a string that
4323 is a file name. E.g. >
4324 if filename =~ glob2regpat('Make*.mak')
4325< This is equivalent to: >
4326 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01004327< When {expr} is an empty string the result is "^$", match an
4328 empty string.
4329
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004330 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004331globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004332 Perform glob() on all directories in {path} and concatenate
4333 the results. Example: >
4334 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004335<
4336 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00004337 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004338 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004339 To add a comma inside a directory name escape it with a
4340 backslash. Note that on MS-Windows a directory may have a
4341 trailing backslash, remove it if you put a comma after it.
4342 If the expansion fails for one of the directories, there is no
4343 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004344
4345 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004346 the 'suffixes' and 'wildignore' options apply: Names matching
4347 one of the patterns in 'wildignore' will be skipped and
4348 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004349
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004350 When {list} is present and it is non-zero the result is a List
4351 with all matching files. The advantage of using a List is, you
4352 also get filenames containing newlines correctly. Otherwise
4353 the result is a String and when there are several matches,
4354 they are separated by <NL> characters. Example: >
4355 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4356<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004357 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004358
Bram Moolenaar02743632005-07-25 20:42:36 +00004359 The "**" item can be used to search in a directory tree.
4360 For example, to find all "README.txt" files in the directories
4361 in 'runtimepath' and below: >
4362 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00004363< Upwards search and limiting the depth of "**" is not
4364 supported, thus using 'path' will not always work properly.
4365
Bram Moolenaar071d4272004-06-13 20:20:40 +00004366 *has()*
4367has({feature}) The result is a Number, which is 1 if the feature {feature} is
4368 supported, zero otherwise. The {feature} argument is a
4369 string. See |feature-list| below.
4370 Also see |exists()|.
4371
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004372
4373has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004374 The result is a Number, which is 1 if |Dictionary| {dict} has
4375 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004376
Bram Moolenaarc9703302016-01-17 21:49:33 +01004377haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4378 The result is a Number, which is 1 when the window has set a
4379 local path via |:lcd|, and 0 otherwise.
4380
4381 Without arguments use the current window.
4382 With {winnr} use this window in the current tab page.
4383 With {winnr} and {tabnr} use the window in the specified tab
4384 page.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004385 {winnr} can be the window number or the window ID.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004386 Return 0 if the arguments are invalid.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004387
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004388hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004389 The result is a Number, which is 1 if there is a mapping that
4390 contains {what} in somewhere in the rhs (what it is mapped to)
4391 and this mapping exists in one of the modes indicated by
4392 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004393 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00004394 instead of mappings. Don't forget to specify Insert and/or
4395 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004396 Both the global mappings and the mappings local to the current
4397 buffer are checked for a match.
4398 If no matching mapping is found 0 is returned.
4399 The following characters are recognized in {mode}:
4400 n Normal mode
4401 v Visual mode
4402 o Operator-pending mode
4403 i Insert mode
4404 l Language-Argument ("r", "f", "t", etc.)
4405 c Command-line mode
4406 When {mode} is omitted, "nvo" is used.
4407
4408 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00004409 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004410 :if !hasmapto('\ABCdoit')
4411 : map <Leader>d \ABCdoit
4412 :endif
4413< This installs the mapping to "\ABCdoit" only if there isn't
4414 already a mapping to "\ABCdoit".
4415
4416histadd({history}, {item}) *histadd()*
4417 Add the String {item} to the history {history} which can be
4418 one of: *hist-names*
4419 "cmd" or ":" command line history
4420 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00004421 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00004422 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02004423 "debug" or ">" debug command history
4424 The {history} string does not need to be the whole name, one
4425 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004426 If {item} does already exist in the history, it will be
4427 shifted to become the newest entry.
4428 The result is a Number: 1 if the operation was successful,
4429 otherwise 0 is returned.
4430
4431 Example: >
4432 :call histadd("input", strftime("%Y %b %d"))
4433 :let date=input("Enter date: ")
4434< This function is not available in the |sandbox|.
4435
4436histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004437 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004438 for the possible values of {history}.
4439
Bram Moolenaarc236c162008-07-13 17:41:49 +00004440 If the parameter {item} evaluates to a String, it is used as a
4441 regular expression. All entries matching that expression will
4442 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004443 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004444 If {item} evaluates to a Number, it will be interpreted as
4445 an index, see |:history-indexing|. The respective entry will
4446 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004447
4448 The result is a Number: 1 for a successful operation,
4449 otherwise 0 is returned.
4450
4451 Examples:
4452 Clear expression register history: >
4453 :call histdel("expr")
4454<
4455 Remove all entries starting with "*" from the search history: >
4456 :call histdel("/", '^\*')
4457<
4458 The following three are equivalent: >
4459 :call histdel("search", histnr("search"))
4460 :call histdel("search", -1)
4461 :call histdel("search", '^'.histget("search", -1).'$')
4462<
4463 To delete the last search pattern and use the last-but-one for
4464 the "n" command and 'hlsearch': >
4465 :call histdel("search", -1)
4466 :let @/ = histget("search", -1)
4467
4468histget({history} [, {index}]) *histget()*
4469 The result is a String, the entry with Number {index} from
4470 {history}. See |hist-names| for the possible values of
4471 {history}, and |:history-indexing| for {index}. If there is
4472 no such entry, an empty String is returned. When {index} is
4473 omitted, the most recent item from the history is used.
4474
4475 Examples:
4476 Redo the second last search from history. >
4477 :execute '/' . histget("search", -2)
4478
4479< Define an Ex command ":H {num}" that supports re-execution of
4480 the {num}th entry from the output of |:history|. >
4481 :command -nargs=1 H execute histget("cmd", 0+<args>)
4482<
4483histnr({history}) *histnr()*
4484 The result is the Number of the current entry in {history}.
4485 See |hist-names| for the possible values of {history}.
4486 If an error occurred, -1 is returned.
4487
4488 Example: >
4489 :let inp_index = histnr("expr")
4490<
4491hlexists({name}) *hlexists()*
4492 The result is a Number, which is non-zero if a highlight group
4493 called {name} exists. This is when the group has been
4494 defined in some way. Not necessarily when highlighting has
4495 been defined for it, it may also have been used for a syntax
4496 item.
4497 *highlight_exists()*
4498 Obsolete name: highlight_exists().
4499
4500 *hlID()*
4501hlID({name}) The result is a Number, which is the ID of the highlight group
4502 with name {name}. When the highlight group doesn't exist,
4503 zero is returned.
4504 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00004505 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004506 "Comment" group: >
4507 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4508< *highlightID()*
4509 Obsolete name: highlightID().
4510
4511hostname() *hostname()*
4512 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004513 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00004514 256 characters long are truncated.
4515
4516iconv({expr}, {from}, {to}) *iconv()*
4517 The result is a String, which is the text {expr} converted
4518 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004519 When the conversion completely fails an empty string is
4520 returned. When some characters could not be converted they
4521 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004522 The encoding names are whatever the iconv() library function
4523 can accept, see ":!man 3 iconv".
4524 Most conversions require Vim to be compiled with the |+iconv|
4525 feature. Otherwise only UTF-8 to latin1 conversion and back
4526 can be done.
4527 This can be used to display messages with special characters,
4528 no matter what 'encoding' is set to. Write the message in
4529 UTF-8 and use: >
4530 echo iconv(utf8_str, "utf-8", &enc)
4531< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4532 from/to UCS-2 is automatically changed to use UTF-8. You
4533 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004534 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004535
4536 *indent()*
4537indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4538 current buffer. The indent is counted in spaces, the value
4539 of 'tabstop' is relevant. {lnum} is used just like in
4540 |getline()|.
4541 When {lnum} is invalid -1 is returned.
4542
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004543
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004544index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004545 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004546 value equal to {expr}. There is no automatic conversion, so
4547 the String "4" is different from the Number 4. And the number
4548 4 is different from the Float 4.0. The value of 'ignorecase'
4549 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00004550 If {start} is given then start looking at the item with index
4551 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004552 When {ic} is given and it is non-zero, ignore case. Otherwise
4553 case must match.
4554 -1 is returned when {expr} is not found in {list}.
4555 Example: >
4556 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004557 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004558
4559
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004560input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004561 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004562 the command-line. The {prompt} argument is either a prompt
4563 string, or a blank string (for no prompt). A '\n' can be used
4564 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004565 The highlighting set with |:echohl| is used for the prompt.
4566 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00004567 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004568 for lines typed for input().
4569 Example: >
4570 :if input("Coffee or beer? ") == "beer"
4571 : echo "Cheers!"
4572 :endif
4573<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004574 If the optional {text} argument is present and not empty, this
4575 is used for the default reply, as if the user typed this.
4576 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004577 :let color = input("Color? ", "white")
4578
4579< The optional {completion} argument specifies the type of
4580 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00004581 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004582 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004583 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004584 more information. Example: >
4585 let fname = input("File: ", "", "file")
4586<
4587 NOTE: This function must not be used in a startup file, for
4588 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004589 Note: When input() is called from within a mapping it will
4590 consume remaining characters from that mapping, because a
4591 mapping is handled like the characters were typed.
4592 Use |inputsave()| before input() and |inputrestore()|
4593 after input() to avoid that. Another solution is to avoid
4594 that further characters follow in the mapping, e.g., by using
4595 |:execute| or |:normal|.
4596
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004597 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004598 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4599 :function GetFoo()
4600 : call inputsave()
4601 : let g:Foo = input("enter search pattern: ")
4602 : call inputrestore()
4603 :endfunction
4604
4605inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004606 Like |input()|, but when the GUI is running and text dialogs
4607 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004608 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02004609 :let n = inputdialog("value for shiftwidth", shiftwidth())
4610 :if n != ""
4611 : let &sw = n
4612 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00004613< When the dialog is cancelled {cancelreturn} is returned. When
4614 omitted an empty string is returned.
4615 Hitting <Enter> works like pressing the OK button. Hitting
4616 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004617 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004618
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004619inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004620 {textlist} must be a |List| of strings. This |List| is
4621 displayed, one string per line. The user will be prompted to
4622 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004623 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004624 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004625 above the first item a negative number is returned. When
4626 clicking on the prompt one more than the length of {textlist}
4627 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004628 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00004629 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004630 the start of the string. And put a prompt in the first item.
4631 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004632 let color = inputlist(['Select color:', '1. red',
4633 \ '2. green', '3. blue'])
4634
Bram Moolenaar071d4272004-06-13 20:20:40 +00004635inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004636 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004637 Should be called the same number of times inputsave() is
4638 called. Calling it more often is harmless though.
4639 Returns 1 when there is nothing to restore, 0 otherwise.
4640
4641inputsave() *inputsave()*
4642 Preserve typeahead (also from mappings) and clear it, so that
4643 a following prompt gets input from the user. Should be
4644 followed by a matching inputrestore() after the prompt. Can
4645 be used several times, in which case there must be just as
4646 many inputrestore() calls.
4647 Returns 1 when out of memory, 0 otherwise.
4648
4649inputsecret({prompt} [, {text}]) *inputsecret()*
4650 This function acts much like the |input()| function with but
4651 two exceptions:
4652 a) the user's response will be displayed as a sequence of
4653 asterisks ("*") thereby keeping the entry secret, and
4654 b) the user's response will not be recorded on the input
4655 |history| stack.
4656 The result is a String, which is whatever the user actually
4657 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004658 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004659
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004660insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004661 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004662 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00004663 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004664 like omitting {idx}. A negative {idx} is also possible, see
4665 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004666 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004667 :let mylist = insert([2, 3, 5], 1)
4668 :call insert(mylist, 4, -1)
4669 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004670< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004671 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004672 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004673
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004674invert({expr}) *invert()*
4675 Bitwise invert. The argument is converted to a number. A
4676 List, Dict or Float argument causes an error. Example: >
4677 :let bits = invert(bits)
4678
Bram Moolenaar071d4272004-06-13 20:20:40 +00004679isdirectory({directory}) *isdirectory()*
4680 The result is a Number, which is non-zero when a directory
4681 with the name {directory} exists. If {directory} doesn't
4682 exist, or isn't a directory, the result is FALSE. {directory}
4683 is any expression, which is used as a String.
4684
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004685islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004686 The result is a Number, which is non-zero when {expr} is the
4687 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004688 {expr} must be the name of a variable, |List| item or
4689 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004690 :let alist = [0, ['a', 'b'], 2, 3]
4691 :lockvar 1 alist
4692 :echo islocked('alist') " 1
4693 :echo islocked('alist[1]') " 0
4694
4695< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004696 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004697
Bram Moolenaarf3913272016-02-25 00:00:01 +01004698isnan({expr}) *isnan()*
4699 Return non-zero if {expr} is a float with value NaN. >
4700 echo isnan(0.0 / 0.0)
4701< 1 ~
4702
4703 {only available when compiled with the |+float| feature}
4704
Bram Moolenaar677ee682005-01-27 14:41:15 +00004705items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004706 Return a |List| with all the key-value pairs of {dict}. Each
4707 |List| item is a list with two items: the key of a {dict}
4708 entry and the value of this entry. The |List| is in arbitrary
4709 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004710
Bram Moolenaar38a55632016-02-15 22:07:32 +01004711job_getchannel({job}) *job_getchannel()*
4712 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01004713 To check if the job has no channel: >
4714 if string(job_getchannel()) == 'channel fail'
4715<
Bram Moolenaar38a55632016-02-15 22:07:32 +01004716 {only available when compiled with the |+job| feature}
4717
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004718job_info({job}) *job_info()*
4719 Returns a Dictionary with information about {job}:
4720 "status" what |job_status()| returns
4721 "channel" what |job_getchannel()| returns
4722 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01004723 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004724 "stoponexit" |job-stoponexit|
4725
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004726job_setoptions({job}, {options}) *job_setoptions()*
4727 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004728 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01004729 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004730
Bram Moolenaar38a55632016-02-15 22:07:32 +01004731job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004732 Start a job and return a Job object. Unlike |system()| and
4733 |:!cmd| this does not wait for the job to finish.
4734
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004735 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01004736 Unix it is split up in white-separated parts to be passed to
4737 execvp(). Arguments in double quotes can contain white space.
4738
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004739 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01004740 and further items are the arguments. All items are converted
4741 to String. This works best on Unix.
4742
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004743 On MS-Windows, job_start() makes a GUI application hidden. If
4744 want to show it, Use |:!start| instead.
4745
Bram Moolenaar835dc632016-02-07 14:27:38 +01004746 The command is executed directly, not through a shell, the
4747 'shell' option is not used. To use the shell: >
4748 let job = job_start(["/bin/sh", "-c", "echo hello"])
4749< Or: >
4750 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004751< Note that this will start two processes, the shell and the
4752 command it executes. If you don't want this use the "exec"
4753 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004754
4755 On Unix $PATH is used to search for the executable only when
4756 the command does not contain a slash.
4757
4758 The job will use the same terminal as Vim. If it reads from
4759 stdin the job and Vim will be fighting over input, that
4760 doesn't work. Redirect stdin and stdout to avoid problems: >
4761 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
4762<
4763 The returned Job object can be used to get the status with
4764 |job_status()| and stop the job with |job_stop()|.
4765
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004766 {options} must be a Dictionary. It can contain many optional
4767 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004768
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004769 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004770
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004771job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004772 Returns a String with the status of {job}:
4773 "run" job is running
4774 "fail" job failed to start
4775 "dead" job died or was stopped after running
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004776
Bram Moolenaar511972d2016-06-04 18:09:59 +02004777 On Unix a non-existing command results in "dead" instead of
4778 "fail", because a fork happens before the failure can be
4779 detected.
4780
Bram Moolenaar03413f42016-04-12 21:07:15 +02004781 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004782 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004783
Bram Moolenaar8950a562016-03-12 15:22:55 +01004784 For more information see |job_info()|.
4785
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004786 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004787
4788job_stop({job} [, {how}]) *job_stop()*
4789 Stop the {job}. This can also be used to signal the job.
4790
Bram Moolenaar923d9262016-02-25 20:56:01 +01004791 When {how} is omitted or is "term" the job will be terminated.
4792 For Unix SIGTERM is sent. On MS-Windows the job will be
4793 terminated forcedly (there is no "gentle" way).
4794 This goes to the process group, thus children may also be
4795 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004796
Bram Moolenaar923d9262016-02-25 20:56:01 +01004797 Effect for Unix:
4798 "term" SIGTERM (default)
4799 "hup" SIGHUP
4800 "quit" SIGQUIT
4801 "int" SIGINT
4802 "kill" SIGKILL (strongest way to stop)
4803 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01004804
Bram Moolenaar923d9262016-02-25 20:56:01 +01004805 Effect for MS-Windows:
4806 "term" terminate process forcedly (default)
4807 "hup" CTRL_BREAK
4808 "quit" CTRL_BREAK
4809 "int" CTRL_C
4810 "kill" terminate process forcedly
4811 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004812
4813 On Unix the signal is sent to the process group. This means
4814 that when the job is "sh -c command" it affects both the shell
4815 and the command.
4816
Bram Moolenaar835dc632016-02-07 14:27:38 +01004817 The result is a Number: 1 if the operation could be executed,
4818 0 if "how" is not supported on the system.
4819 Note that even when the operation was executed, whether the
4820 job was actually stopped needs to be checked with
4821 job_status().
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004822 The status of the job isn't checked, the operation will even
4823 be done when Vim thinks the job isn't running.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004824
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004825 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004826
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004827join({list} [, {sep}]) *join()*
4828 Join the items in {list} together into one String.
4829 When {sep} is specified it is put in between the items. If
4830 {sep} is omitted a single space is used.
4831 Note that {sep} is not added at the end. You might want to
4832 add it there too: >
4833 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004834< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004835 converted into a string like with |string()|.
4836 The opposite function is |split()|.
4837
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004838js_decode({string}) *js_decode()*
4839 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004840 - Object key names do not have to be in quotes.
4841 - Empty items in an array (between two commas) are allowed and
4842 result in v:none items.
4843
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004844js_encode({expr}) *js_encode()*
4845 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004846 - Object key names are not in quotes.
4847 - v:none items in an array result in an empty item between
4848 commas.
4849 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004850 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004851 Will be encoded as:
4852 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004853 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004854 [1,null,{"one":1},null] ~
4855 This encoding is valid for JavaScript. It is more efficient
4856 than JSON, especially when using an array with optional items.
4857
4858
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004859json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004860 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004861 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01004862 JSON and Vim values.
4863 The decoding is permissive:
4864 - A trailing comma in an array and object is ignored.
Bram Moolenaar705ada12016-01-24 17:56:50 +01004865 - More floating point numbers are recognized, e.g. "1." for
4866 "1.0".
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004867 The result must be a valid Vim type:
4868 - An empty object member name is not allowed.
4869 - Duplicate object member names are not allowed.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004870
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004871json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004872 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004873 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004874 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004875 Vim values are converted as follows:
4876 Number decimal number
4877 Float floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004878 Float nan "NaN"
4879 Float inf "Infinity"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004880 String in double quotes (possibly null)
Bram Moolenaar705ada12016-01-24 17:56:50 +01004881 Funcref not possible, error
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004882 List as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02004883 used recursively: []
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004884 Dict as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02004885 used recursively: {}
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004886 v:false "false"
4887 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004888 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004889 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004890 Note that NaN and Infinity are passed on as values. This is
4891 missing in the JSON standard, but several implementations do
4892 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004893
Bram Moolenaard8b02732005-01-14 21:48:43 +00004894keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004895 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00004896 arbitrary order.
4897
Bram Moolenaar13065c42005-01-08 16:08:21 +00004898 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004899len({expr}) The result is a Number, which is the length of the argument.
4900 When {expr} is a String or a Number the length in bytes is
4901 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004902 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004903 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004904 When {expr} is a |Dictionary| the number of entries in the
4905 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004906 Otherwise an error is given.
4907
Bram Moolenaar071d4272004-06-13 20:20:40 +00004908 *libcall()* *E364* *E368*
4909libcall({libname}, {funcname}, {argument})
4910 Call function {funcname} in the run-time library {libname}
4911 with single argument {argument}.
4912 This is useful to call functions in a library that you
4913 especially made to be used with Vim. Since only one argument
4914 is possible, calling standard library functions is rather
4915 limited.
4916 The result is the String returned by the function. If the
4917 function returns NULL, this will appear as an empty string ""
4918 to Vim.
4919 If the function returns a number, use libcallnr()!
4920 If {argument} is a number, it is passed to the function as an
4921 int; if {argument} is a string, it is passed as a
4922 null-terminated string.
4923 This function will fail in |restricted-mode|.
4924
4925 libcall() allows you to write your own 'plug-in' extensions to
4926 Vim without having to recompile the program. It is NOT a
4927 means to call system functions! If you try to do so Vim will
4928 very probably crash.
4929
4930 For Win32, the functions you write must be placed in a DLL
4931 and use the normal C calling convention (NOT Pascal which is
4932 used in Windows System DLLs). The function must take exactly
4933 one parameter, either a character pointer or a long integer,
4934 and must return a character pointer or NULL. The character
4935 pointer returned must point to memory that will remain valid
4936 after the function has returned (e.g. in static data in the
4937 DLL). If it points to allocated memory, that memory will
4938 leak away. Using a static buffer in the function should work,
4939 it's then freed when the DLL is unloaded.
4940
4941 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00004942 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00004943 because Vim thinks it's a pointer.
4944 For Win32 systems, {libname} should be the filename of the DLL
4945 without the ".DLL" suffix. A full path is only required if
4946 the DLL is not in the usual places.
4947 For Unix: When compiling your own plugins, remember that the
4948 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004949 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004950 feature is present}
4951 Examples: >
4952 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004953<
4954 *libcallnr()*
4955libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004956 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004957 int instead of a string.
4958 {only in Win32 on some Unix versions, when the |+libcall|
4959 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00004960 Examples: >
4961 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004962 :call libcallnr("libc.so", "printf", "Hello World!\n")
4963 :call libcallnr("libc.so", "sleep", 10)
4964<
4965 *line()*
4966line({expr}) The result is a Number, which is the line number of the file
4967 position given with {expr}. The accepted positions are:
4968 . the cursor position
4969 $ the last line in the current buffer
4970 'x position of mark x (if the mark is not set, 0 is
4971 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00004972 w0 first line visible in current window
4973 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00004974 v In Visual mode: the start of the Visual area (the
4975 cursor is the end). When not in Visual mode
4976 returns the cursor position. Differs from |'<| in
4977 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004978 Note that a mark in another file can be used. The line number
4979 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004980 To get the column number use |col()|. To get both use
4981 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004982 Examples: >
4983 line(".") line number of the cursor
4984 line("'t") line number of mark t
4985 line("'" . marker) line number of mark marker
4986< *last-position-jump*
4987 This autocommand jumps to the last known position in a file
4988 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004989 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004990
Bram Moolenaar071d4272004-06-13 20:20:40 +00004991line2byte({lnum}) *line2byte()*
4992 Return the byte count from the start of the buffer for line
4993 {lnum}. This includes the end-of-line character, depending on
4994 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004995 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004996 This can also be used to get the byte count for the line just
4997 below the last line: >
4998 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004999< This is the buffer size plus one. If 'fileencoding' is empty
5000 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005001 When {lnum} is invalid, or the |+byte_offset| feature has been
5002 disabled at compile time, -1 is returned.
5003 Also see |byte2line()|, |go| and |:goto|.
5004
5005lispindent({lnum}) *lispindent()*
5006 Get the amount of indent for line {lnum} according the lisp
5007 indenting rules, as with 'lisp'.
5008 The indent is counted in spaces, the value of 'tabstop' is
5009 relevant. {lnum} is used just like in |getline()|.
5010 When {lnum} is invalid or Vim was not compiled the
5011 |+lispindent| feature, -1 is returned.
5012
5013localtime() *localtime()*
5014 Return the current time, measured as seconds since 1st Jan
5015 1970. See also |strftime()| and |getftime()|.
5016
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005017
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005018log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005019 Return the natural logarithm (base e) of {expr} as a |Float|.
5020 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005021 (0, inf].
5022 Examples: >
5023 :echo log(10)
5024< 2.302585 >
5025 :echo log(exp(5))
5026< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02005027 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005028
5029
Bram Moolenaar446cb832008-06-24 21:56:24 +00005030log10({expr}) *log10()*
5031 Return the logarithm of Float {expr} to base 10 as a |Float|.
5032 {expr} must evaluate to a |Float| or a |Number|.
5033 Examples: >
5034 :echo log10(1000)
5035< 3.0 >
5036 :echo log10(0.01)
5037< -2.0
5038 {only available when compiled with the |+float| feature}
5039
Bram Moolenaard38b0552012-04-25 19:07:41 +02005040luaeval({expr}[, {expr}]) *luaeval()*
5041 Evaluate Lua expression {expr} and return its result converted
5042 to Vim data structures. Second {expr} may hold additional
5043 argument accessible as _A inside first {expr}.
5044 Strings are returned as they are.
5045 Boolean objects are converted to numbers.
5046 Numbers are converted to |Float| values if vim was compiled
5047 with |+float| and to numbers otherwise.
5048 Dictionaries and lists obtained by vim.eval() are returned
5049 as-is.
5050 Other objects are returned as zero without any errors.
5051 See |lua-luaeval| for more details.
5052 {only available when compiled with the |+lua| feature}
5053
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005054map({expr1}, {expr2}) *map()*
5055 {expr1} must be a |List| or a |Dictionary|.
5056 Replace each item in {expr1} with the result of evaluating
5057 {expr2}. {expr2} must be a |string| or |Funcref|.
5058
5059 If {expr2} is a |string|, inside {expr2} |v:val| has the value
5060 of the current item. For a |Dictionary| |v:key| has the key
5061 of the current item and for a |List| |v:key| has the index of
5062 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005063 Example: >
5064 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005065< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005066
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005067 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005068 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005069 |literal-string| to avoid having to double backslashes. You
5070 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005071
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005072 If {expr2} is a |Funcref| it is called with two arguments:
5073 1. The key or the index of the current item.
5074 2. the value of the current item.
5075 The function must return the new value of the item. Example
5076 that changes each value by "key-value": >
5077 func KeyValue(key, val)
5078 return a:key . '-' . a:val
5079 endfunc
5080 call map(myDict, function('KeyValue'))
5081<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005082 The operation is done in-place. If you want a |List| or
5083 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02005084 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005085
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02005086< Returns {expr1}, the |List| or |Dictionary| that was filtered.
5087 When an error is encountered while evaluating {expr2} no
5088 further items in {expr1} are processed. When {expr2} is a
5089 Funcref errors inside a function are ignored, unless it was
5090 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005091
5092
Bram Moolenaarbd743252010-10-20 21:23:33 +02005093maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
5094 When {dict} is omitted or zero: Return the rhs of mapping
5095 {name} in mode {mode}. The returned String has special
5096 characters translated like in the output of the ":map" command
5097 listing.
5098
5099 When there is no mapping for {name}, an empty String is
5100 returned.
5101
5102 The {name} can have special key names, like in the ":map"
5103 command.
5104
Bram Moolenaard12f5c12006-01-25 22:10:52 +00005105 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005106 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02005107 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005108 "o" Operator-pending
5109 "i" Insert
5110 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02005111 "s" Select
5112 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00005113 "l" langmap |language-mapping|
5114 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00005115 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005116
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005117 When {abbr} is there and it is non-zero use abbreviations
5118 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005119
5120 When {dict} is there and it is non-zero return a dictionary
5121 containing all the information of the mapping with the
5122 following items:
5123 "lhs" The {lhs} of the mapping.
5124 "rhs" The {rhs} of the mapping as typed.
5125 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02005126 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005127 "expr" 1 for an expression mapping (|:map-<expr>|).
5128 "buffer" 1 for a buffer local mapping (|:map-local|).
5129 "mode" Modes for which the mapping is defined. In
5130 addition to the modes mentioned above, these
5131 characters will be used:
5132 " " Normal, Visual and Operator-pending
5133 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01005134 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02005135 "sid" The script local ID, used for <sid> mappings
5136 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01005137 "nowait" Do not wait for other, longer mappings.
5138 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02005139
Bram Moolenaar071d4272004-06-13 20:20:40 +00005140 The mappings local to the current buffer are checked first,
5141 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00005142 This function can be used to map a key even when it's already
5143 mapped, and have it do the original mapping too. Sketch: >
5144 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
5145
Bram Moolenaar071d4272004-06-13 20:20:40 +00005146
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005147mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005148 Check if there is a mapping that matches with {name} in mode
5149 {mode}. See |maparg()| for {mode} and special names in
5150 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005151 When {abbr} is there and it is non-zero use abbreviations
5152 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005153 A match happens with a mapping that starts with {name} and
5154 with a mapping which is equal to the start of {name}.
5155
Bram Moolenaar446cb832008-06-24 21:56:24 +00005156 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005157 mapcheck("a") yes yes yes
5158 mapcheck("abc") yes yes yes
5159 mapcheck("ax") yes no no
5160 mapcheck("b") no no no
5161
5162 The difference with maparg() is that mapcheck() finds a
5163 mapping that matches with {name}, while maparg() only finds a
5164 mapping for {name} exactly.
5165 When there is no mapping that starts with {name}, an empty
5166 String is returned. If there is one, the rhs of that mapping
5167 is returned. If there are several mappings that start with
5168 {name}, the rhs of one of them is returned.
5169 The mappings local to the current buffer are checked first,
5170 then the global mappings.
5171 This function can be used to check if a mapping can be added
5172 without being ambiguous. Example: >
5173 :if mapcheck("_vv") == ""
5174 : map _vv :set guifont=7x13<CR>
5175 :endif
5176< This avoids adding the "_vv" mapping when there already is a
5177 mapping for "_v" or for "_vvv".
5178
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005179match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005180 When {expr} is a |List| then this returns the index of the
5181 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005182 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005183 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005184 Number, which gives the index (byte offset) in {expr} where
5185 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005186 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005187 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02005188 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005189 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005190 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005191 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005192< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005193 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005194 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00005195 :let sepidx = match(line, '[.,;: \t]')
5196< *strcasestr()*
5197 Vim doesn't have a strcasestr() function. But you can add
5198 "\c" to the pattern to ignore case: >
5199 :let idx = match(haystack, '\cneedle')
5200<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005201 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005202 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005203 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005204 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005205 :echo match("testing", "ing", 2)
5206< result is again "4". >
5207 :echo match("testing", "ing", 4)
5208< result is again "4". >
5209 :echo match("testing", "t", 2)
5210< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005211 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00005212 {start} bytes later, thus "^" will match at {start}. Except
5213 when {count} is given, then it's like matches before the
5214 {start} byte are ignored (this is a bit complicated to keep it
5215 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005216 For a String, if {start} < 0, it will be set to 0. For a list
5217 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005218 If {start} is out of range ({start} > strlen({expr}) for a
5219 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005220
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005221 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005222 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005223 character further. Thus this example results in 1: >
5224 echo match("testing", "..", 0, 2)
5225< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00005226 Note that when {count} is added the way {start} works changes,
5227 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005228
Bram Moolenaar071d4272004-06-13 20:20:40 +00005229 See |pattern| for the patterns that are accepted.
5230 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00005231 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00005232 done like 'magic' is set and 'cpoptions' is empty.
5233
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005234 *matchadd()* *E798* *E799* *E801*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005235matchadd({group}, {pattern}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005236 Defines a pattern to be highlighted in the current window (a
5237 "match"). It will be highlighted with {group}. Returns an
5238 identification number (ID), which can be used to delete the
5239 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01005240 Matching is case sensitive and magic, unless case sensitivity
5241 or magicness are explicitly overridden in {pattern}. The
5242 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02005243 The "Conceal" value is special, it causes the match to be
5244 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005245
5246 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005247 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005248 highlighting overrule that of a match with a lower priority.
5249 A priority is specified as an integer (negative numbers are no
5250 exception). If the {priority} argument is not specified, the
5251 default priority is 10. The priority of 'hlsearch' is zero,
5252 hence all matches with a priority greater than zero will
5253 overrule it. Syntax highlighting (see 'syntax') is a separate
5254 mechanism, and regardless of the chosen priority a match will
5255 always overrule syntax highlighting.
5256
5257 The optional {id} argument allows the request for a specific
5258 match ID. If a specified ID is already taken, an error
5259 message will appear and the match will not be added. An ID
5260 is specified as a positive integer (zero excluded). IDs 1, 2
5261 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02005262 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005263 |matchadd()| automatically chooses a free ID.
5264
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005265 The optional {dict} argument allows for further custom
5266 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02005267 conceal character that will be shown for |hl-Conceal|
5268 highlighted matches. The dict can have the following members:
5269
5270 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005271 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02005272 matches, see |:syn-cchar|)
5273
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005274 The number of matches is not limited, as it is the case with
5275 the |:match| commands.
5276
5277 Example: >
5278 :highlight MyGroup ctermbg=green guibg=green
5279 :let m = matchadd("MyGroup", "TODO")
5280< Deletion of the pattern: >
5281 :call matchdelete(m)
5282
5283< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00005284 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005285 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005286
Bram Moolenaar6561d522015-07-21 15:48:27 +02005287matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()*
Bram Moolenaarb3414592014-06-17 17:48:32 +02005288 Same as |matchadd()|, but requires a list of positions {pos}
5289 instead of a pattern. This command is faster than |matchadd()|
5290 because it does not require to handle regular expressions and
5291 sets buffer line boundaries to redraw screen. It is supposed
5292 to be used when fast match additions and deletions are
5293 required, for example to highlight matching parentheses.
5294
5295 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005296 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02005297 line has number 1.
5298 - A list with one number, e.g., [23]. The whole line with this
5299 number will be highlighted.
5300 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005301 the line number, the second one is the column number (first
5302 column is 1, the value must correspond to the byte index as
5303 |col()| would return). The character at this position will
5304 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005305 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005306 the third number gives the length of the highlight in bytes.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005307
5308 The maximum number of positions is 8.
5309
5310 Example: >
5311 :highlight MyGroup ctermbg=green guibg=green
5312 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5313< Deletion of the pattern: >
5314 :call matchdelete(m)
5315
5316< Matches added by |matchaddpos()| are returned by
5317 |getmatches()| with an entry "pos1", "pos2", etc., with the
5318 value a list like the {pos} item.
5319 These matches cannot be set via |setmatches()|, however they
5320 can still be deleted by |clearmatches()|.
5321
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005322matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005323 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005324 |:2match| or |:3match| command.
5325 Return a |List| with two elements:
5326 The name of the highlight group used
5327 The pattern used.
5328 When {nr} is not 1, 2 or 3 returns an empty |List|.
5329 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005330 This is useful to save and restore a |:match|.
5331 Highlighting matches using the |:match| commands are limited
5332 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005333
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005334matchdelete({id}) *matchdelete()* *E802* *E803*
5335 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00005336 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005337 otherwise -1. See example for |matchadd()|. All matches can
5338 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005339
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005340matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005341 Same as |match()|, but return the index of first character
5342 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005343 :echo matchend("testing", "ing")
5344< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00005345 *strspn()* *strcspn()*
5346 Vim doesn't have a strspn() or strcspn() function, but you can
5347 do it with matchend(): >
5348 :let span = matchend(line, '[a-zA-Z]')
5349 :let span = matchend(line, '[^a-zA-Z]')
5350< Except that -1 is returned when there are no matches.
5351
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005352 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005353 :echo matchend("testing", "ing", 2)
5354< results in "7". >
5355 :echo matchend("testing", "ing", 5)
5356< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005357 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005358
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005359matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005360 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005361 list is the matched string, same as what matchstr() would
5362 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005363 in |:substitute|. When an optional submatch didn't match an
5364 empty string is used. Example: >
5365 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5366< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005367 When there is no match an empty list is returned.
5368
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005369matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005370 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005371 :echo matchstr("testing", "ing")
5372< results in "ing".
5373 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005374 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005375 :echo matchstr("testing", "ing", 2)
5376< results in "ing". >
5377 :echo matchstr("testing", "ing", 5)
5378< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005379 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005380 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005381
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02005382matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()*
5383 Same as |matchstr()|, but return the matched string, the start
5384 position and the end position of the match. Example: >
5385 :echo matchstrpos("testing", "ing")
5386< results in ["ing", 4, 7].
5387 When there is no match ["", -1, -1] is returned.
5388 The {start}, if given, has the same meaning as for |match()|. >
5389 :echo matchstrpos("testing", "ing", 2)
5390< results in ["ing", 4, 7]. >
5391 :echo matchstrpos("testing", "ing", 5)
5392< result is ["", -1, -1].
5393 When {expr} is a |List| then the matching item, the index
5394 of first item where {pat} matches, the start position and the
5395 end position of the match are returned. >
5396 :echo matchstrpos([1, '__x'], '\a')
5397< result is ["x", 1, 2, 3].
5398 The type isn't changed, it's not necessarily a String.
5399
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005400 *max()*
5401max({list}) Return the maximum value of all items in {list}.
5402 If {list} is not a list or one of the items in {list} cannot
5403 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005404 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005405
5406 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00005407min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005408 If {list} is not a list or one of the items in {list} cannot
5409 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005410 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005411
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005412 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005413mkdir({name} [, {path} [, {prot}]])
5414 Create directory {name}.
5415 If {path} is "p" then intermediate directories are created as
5416 necessary. Otherwise it must be "".
5417 If {prot} is given it is used to set the protection bits of
5418 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00005419 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00005420 for others. This is only used for the last part of {name}.
5421 Thus if you create /tmp/foo/bar then /tmp/foo will be created
5422 with 0755.
5423 Example: >
5424 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
5425< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005426 Not available on all systems. To check use: >
5427 :if exists("*mkdir")
5428<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005429 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005430mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005431 If [expr] is supplied and it evaluates to a non-zero Number or
5432 a non-empty String (|non-zero-arg|), then the full mode is
5433 returned, otherwise only the first letter is returned. Note
5434 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005435
Bram Moolenaar071d4272004-06-13 20:20:40 +00005436 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00005437 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00005438 v Visual by character
5439 V Visual by line
5440 CTRL-V Visual blockwise
5441 s Select by character
5442 S Select by line
5443 CTRL-S Select blockwise
5444 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00005445 R Replace |R|
5446 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005447 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00005448 cv Vim Ex mode |gQ|
5449 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005450 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00005451 rm The -- more -- prompt
5452 r? A |:confirm| query of some sort
5453 ! Shell or external command is executing
5454 This is useful in the 'statusline' option or when used
5455 with |remote_expr()| In most other places it always returns
5456 "c" or "n".
5457 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005458
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005459mzeval({expr}) *mzeval()*
5460 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02005461 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005462 Numbers and strings are returned as they are.
5463 Pairs (including lists and improper lists) and vectors are
5464 returned as Vim |Lists|.
5465 Hash tables are represented as Vim |Dictionary| type with keys
5466 converted to strings.
5467 All other types are converted to string with display function.
5468 Examples: >
5469 :mz (define l (list 1 2 3))
5470 :mz (define h (make-hash)) (hash-set! h "list" l)
5471 :echo mzeval("l")
5472 :echo mzeval("h")
5473<
5474 {only available when compiled with the |+mzscheme| feature}
5475
Bram Moolenaar071d4272004-06-13 20:20:40 +00005476nextnonblank({lnum}) *nextnonblank()*
5477 Return the line number of the first line at or below {lnum}
5478 that is not blank. Example: >
5479 if getline(nextnonblank(1)) =~ "Java"
5480< When {lnum} is invalid or there is no non-blank line at or
5481 below it, zero is returned.
5482 See also |prevnonblank()|.
5483
Bram Moolenaard35d7842013-01-23 17:17:10 +01005484nr2char({expr}[, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005485 Return a string with a single character, which has the number
5486 value {expr}. Examples: >
5487 nr2char(64) returns "@"
5488 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01005489< When {utf8} is omitted or zero, the current 'encoding' is used.
5490 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005491 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01005492< With {utf8} set to 1, always return utf-8 characters.
5493 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00005494 nr2char(10), because NULs are represented with newline
5495 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005496 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005497
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005498or({expr}, {expr}) *or()*
5499 Bitwise OR on the two arguments. The arguments are converted
5500 to a number. A List, Dict or Float argument causes an error.
5501 Example: >
5502 :let bits = or(bits, 0x80)
5503
5504
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005505pathshorten({expr}) *pathshorten()*
5506 Shorten directory names in the path {expr} and return the
5507 result. The tail, the file name, is kept as-is. The other
5508 components in the path are reduced to single letters. Leading
5509 '~' and '.' characters are kept. Example: >
5510 :echo pathshorten('~/.vim/autoload/myfile.vim')
5511< ~/.v/a/myfile.vim ~
5512 It doesn't matter if the path exists or not.
5513
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005514perleval({expr}) *perleval()*
5515 Evaluate Perl expression {expr} in scalar context and return
5516 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005517 converted, it is returned as a string Perl representation.
5518 Note: If you want an array or hash, {expr} must return a
5519 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005520 Example: >
5521 :echo perleval('[1 .. 4]')
5522< [1, 2, 3, 4]
5523 {only available when compiled with the |+perl| feature}
5524
Bram Moolenaar446cb832008-06-24 21:56:24 +00005525pow({x}, {y}) *pow()*
5526 Return the power of {x} to the exponent {y} as a |Float|.
5527 {x} and {y} must evaluate to a |Float| or a |Number|.
5528 Examples: >
5529 :echo pow(3, 3)
5530< 27.0 >
5531 :echo pow(2, 16)
5532< 65536.0 >
5533 :echo pow(32, 0.20)
5534< 2.0
5535 {only available when compiled with the |+float| feature}
5536
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005537prevnonblank({lnum}) *prevnonblank()*
5538 Return the line number of the first line at or above {lnum}
5539 that is not blank. Example: >
5540 let ind = indent(prevnonblank(v:lnum - 1))
5541< When {lnum} is invalid or there is no non-blank line at or
5542 above it, zero is returned.
5543 Also see |nextnonblank()|.
5544
5545
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005546printf({fmt}, {expr1} ...) *printf()*
5547 Return a String with {fmt}, where "%" items are replaced by
5548 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005549 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005550< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005551 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005552
5553 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005554 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005555 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00005556 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00005557 %.9s string truncated to 9 bytes
5558 %c single byte
5559 %d decimal number
5560 %5d decimal number padded with spaces to 5 characters
5561 %x hex number
5562 %04x hex number padded with zeros to at least 4 characters
5563 %X hex number using upper case letters
5564 %o octal number
5565 %f floating point number in the form 123.456
5566 %e floating point number in the form 1.234e3
5567 %E floating point number in the form 1.234E3
5568 %g floating point number, as %f or %e depending on value
5569 %G floating point number, as %f or %E depending on value
5570 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005571
5572 Conversion specifications start with '%' and end with the
5573 conversion type. All other characters are copied unchanged to
5574 the result.
5575
5576 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005577 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005578
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005579 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005580
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005581 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005582 Zero or more of the following flags:
5583
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005584 # The value should be converted to an "alternate
5585 form". For c, d, and s conversions, this option
5586 has no effect. For o conversions, the precision
5587 of the number is increased to force the first
5588 character of the output string to a zero (except
5589 if a zero value is printed with an explicit
5590 precision of zero).
5591 For x and X conversions, a non-zero result has
5592 the string "0x" (or "0X" for X conversions)
5593 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005594
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005595 0 (zero) Zero padding. For all conversions the converted
5596 value is padded on the left with zeros rather
5597 than blanks. If a precision is given with a
5598 numeric conversion (d, o, x, and X), the 0 flag
5599 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005600
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005601 - A negative field width flag; the converted value
5602 is to be left adjusted on the field boundary.
5603 The converted value is padded on the right with
5604 blanks, rather than on the left with blanks or
5605 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005606
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005607 ' ' (space) A blank should be left before a positive
5608 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005609
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005610 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00005611 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005612 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005613
5614 field-width
5615 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00005616 field width. If the converted value has fewer bytes
5617 than the field width, it will be padded with spaces on
5618 the left (or right, if the left-adjustment flag has
5619 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005620
5621 .precision
5622 An optional precision, in the form of a period '.'
5623 followed by an optional digit string. If the digit
5624 string is omitted, the precision is taken as zero.
5625 This gives the minimum number of digits to appear for
5626 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00005627 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005628 For floating point it is the number of digits after
5629 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005630
5631 type
5632 A character that specifies the type of conversion to
5633 be applied, see below.
5634
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005635 A field width or precision, or both, may be indicated by an
5636 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00005637 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005638 negative field width is treated as a left adjustment flag
5639 followed by a positive field width; a negative precision is
5640 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005641 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005642< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005643 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005644
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005645 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005646
Bram Moolenaar446cb832008-06-24 21:56:24 +00005647 *printf-d* *printf-o* *printf-x* *printf-X*
5648 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005649 (d), unsigned octal (o), or unsigned hexadecimal (x
5650 and X) notation. The letters "abcdef" are used for
5651 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005652 conversions.
5653 The precision, if any, gives the minimum number of
5654 digits that must appear; if the converted value
5655 requires fewer digits, it is padded on the left with
5656 zeros.
5657 In no case does a non-existent or small field width
5658 cause truncation of a numeric field; if the result of
5659 a conversion is wider than the field width, the field
5660 is expanded to contain the conversion result.
5661
Bram Moolenaar446cb832008-06-24 21:56:24 +00005662 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005663 c The Number argument is converted to a byte, and the
5664 resulting character is written.
5665
Bram Moolenaar446cb832008-06-24 21:56:24 +00005666 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005667 s The text of the String argument is used. If a
5668 precision is specified, no more bytes than the number
5669 specified are used.
Bram Moolenaar0122c402015-02-03 19:13:34 +01005670 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005671 S The text of the String argument is used. If a
5672 precision is specified, no more display cells than the
5673 number specified are used. Without the |+multi_byte|
5674 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005675
Bram Moolenaar446cb832008-06-24 21:56:24 +00005676 *printf-f* *E807*
5677 f The Float argument is converted into a string of the
5678 form 123.456. The precision specifies the number of
5679 digits after the decimal point. When the precision is
5680 zero the decimal point is omitted. When the precision
5681 is not specified 6 is used. A really big number
5682 (out of range or dividing by zero) results in "inf".
5683 "0.0 / 0.0" results in "nan".
5684 Example: >
5685 echo printf("%.2f", 12.115)
5686< 12.12
5687 Note that roundoff depends on the system libraries.
5688 Use |round()| when in doubt.
5689
5690 *printf-e* *printf-E*
5691 e E The Float argument is converted into a string of the
5692 form 1.234e+03 or 1.234E+03 when using 'E'. The
5693 precision specifies the number of digits after the
5694 decimal point, like with 'f'.
5695
5696 *printf-g* *printf-G*
5697 g G The Float argument is converted like with 'f' if the
5698 value is between 0.001 (inclusive) and 10000000.0
5699 (exclusive). Otherwise 'e' is used for 'g' and 'E'
5700 for 'G'. When no precision is specified superfluous
5701 zeroes and '+' signs are removed, except for the zero
5702 immediately after the decimal point. Thus 10000000.0
5703 results in 1.0e7.
5704
5705 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005706 % A '%' is written. No argument is converted. The
5707 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005708
Bram Moolenaarc236c162008-07-13 17:41:49 +00005709 When a Number argument is expected a String argument is also
5710 accepted and automatically converted.
5711 When a Float or String argument is expected a Number argument
5712 is also accepted and automatically converted.
5713 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005714
Bram Moolenaar83bab712005-08-01 21:58:57 +00005715 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005716 The number of {exprN} arguments must exactly match the number
5717 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005718 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005719
5720
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005721pumvisible() *pumvisible()*
5722 Returns non-zero when the popup menu is visible, zero
5723 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005724 This can be used to avoid some things that would remove the
5725 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005726
Bram Moolenaar30b65812012-07-12 22:01:11 +02005727py3eval({expr}) *py3eval()*
5728 Evaluate Python expression {expr} and return its result
5729 converted to Vim data structures.
5730 Numbers and strings are returned as they are (strings are
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01005731 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02005732 'encoding').
5733 Lists are represented as Vim |List| type.
5734 Dictionaries are represented as Vim |Dictionary| type with
5735 keys converted to strings.
5736 {only available when compiled with the |+python3| feature}
5737
5738 *E858* *E859*
5739pyeval({expr}) *pyeval()*
5740 Evaluate Python expression {expr} and return its result
5741 converted to Vim data structures.
5742 Numbers and strings are returned as they are (strings are
5743 copied though).
5744 Lists are represented as Vim |List| type.
Bram Moolenaard09acef2012-09-21 14:54:30 +02005745 Dictionaries are represented as Vim |Dictionary| type,
5746 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02005747 {only available when compiled with the |+python| feature}
5748
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005749 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00005750range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005751 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00005752 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
5753 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
5754 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
5755 {max}] (increasing {expr} with {stride} each time, not
5756 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00005757 When the maximum is one before the start the result is an
5758 empty list. When the maximum is more than one before the
5759 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00005760 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005761 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00005762 range(2, 4) " [2, 3, 4]
5763 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005764 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00005765 range(0) " []
5766 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00005767<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005768 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005769readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005770 Read file {fname} and return a |List|, each line of the file
5771 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005772 separated with CR will result in a single long line (unless a
5773 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02005774 All NUL characters are replaced with a NL character.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02005775 When {binary} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005776 - When the last line ends in a NL an extra empty list item is
5777 added.
5778 - No CR characters are removed.
5779 Otherwise:
5780 - CR characters that appear before a NL are removed.
5781 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02005782 - When 'encoding' is Unicode any UTF-8 byte order mark is
5783 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005784 When {max} is given this specifies the maximum number of lines
5785 to be read. Useful if you only want to check the first ten
5786 lines of a file: >
5787 :for line in readfile(fname, '', 10)
5788 : if line =~ 'Date' | echo line | endif
5789 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00005790< When {max} is negative -{max} lines from the end of the file
5791 are returned, or as many as there are.
5792 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005793 Note that without {max} the whole file is read into memory.
5794 Also note that there is no recognition of encoding. Read a
5795 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005796 When the file can't be opened an error message is given and
5797 the result is an empty list.
5798 Also see |writefile()|.
5799
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005800reltime([{start} [, {end}]]) *reltime()*
5801 Return an item that represents a time value. The format of
5802 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02005803 |reltimestr()| to convert it to a string or |reltimefloat()|
5804 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005805 Without an argument it returns the current time.
5806 With one argument is returns the time passed since the time
5807 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005808 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005809 and {end}.
5810 The {start} and {end} arguments must be values returned by
5811 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02005812 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005813
Bram Moolenaar03413f42016-04-12 21:07:15 +02005814reltimefloat({time}) *reltimefloat()*
5815 Return a Float that represents the time value of {time}.
5816 Example: >
5817 let start = reltime()
5818 call MyFunction()
5819 let seconds = reltimefloat(reltime(start))
5820< See the note of reltimestr() about overhead.
5821 Also see |profiling|.
5822 {only available when compiled with the |+reltime| feature}
5823
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005824reltimestr({time}) *reltimestr()*
5825 Return a String that represents the time value of {time}.
5826 This is the number of seconds, a dot and the number of
5827 microseconds. Example: >
5828 let start = reltime()
5829 call MyFunction()
5830 echo reltimestr(reltime(start))
5831< Note that overhead for the commands will be added to the time.
5832 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005833 Leading spaces are used to make the string align nicely. You
5834 can use split() to remove it. >
5835 echo split(reltimestr(reltime(start)))[0]
5836< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005837 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005838
Bram Moolenaar071d4272004-06-13 20:20:40 +00005839 *remote_expr()* *E449*
5840remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005841 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005842 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005843 The result must be a String or a |List|. A |List| is turned
5844 into a String by joining the items with a line break in
5845 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00005846 If {idvar} is present, it is taken as the name of a
5847 variable and a {serverid} for later use with
5848 remote_read() is stored there.
5849 See also |clientserver| |RemoteReply|.
5850 This function is not available in the |sandbox|.
5851 {only available when compiled with the |+clientserver| feature}
5852 Note: Any errors will cause a local error message to be issued
5853 and the result will be the empty string.
5854 Examples: >
5855 :echo remote_expr("gvim", "2+2")
5856 :echo remote_expr("gvim1", "b:current_syntax")
5857<
5858
5859remote_foreground({server}) *remote_foreground()*
5860 Move the Vim server with the name {server} to the foreground.
5861 This works like: >
5862 remote_expr({server}, "foreground()")
5863< Except that on Win32 systems the client does the work, to work
5864 around the problem that the OS doesn't always allow the server
5865 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00005866 Note: This does not restore the window if it was minimized,
5867 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005868 This function is not available in the |sandbox|.
5869 {only in the Win32, Athena, Motif and GTK GUI versions and the
5870 Win32 console version}
5871
5872
5873remote_peek({serverid} [, {retvar}]) *remote_peek()*
5874 Returns a positive number if there are available strings
5875 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00005876 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005877 name of a variable.
5878 Returns zero if none are available.
5879 Returns -1 if something is wrong.
5880 See also |clientserver|.
5881 This function is not available in the |sandbox|.
5882 {only available when compiled with the |+clientserver| feature}
5883 Examples: >
5884 :let repl = ""
5885 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
5886
5887remote_read({serverid}) *remote_read()*
5888 Return the oldest available reply from {serverid} and consume
5889 it. It blocks until a reply is available.
5890 See also |clientserver|.
5891 This function is not available in the |sandbox|.
5892 {only available when compiled with the |+clientserver| feature}
5893 Example: >
5894 :echo remote_read(id)
5895<
5896 *remote_send()* *E241*
5897remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005898 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005899 keys and the function returns immediately. At the Vim server
5900 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005901 If {idvar} is present, it is taken as the name of a variable
5902 and a {serverid} for later use with remote_read() is stored
5903 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005904 See also |clientserver| |RemoteReply|.
5905 This function is not available in the |sandbox|.
5906 {only available when compiled with the |+clientserver| feature}
5907 Note: Any errors will be reported in the server and may mess
5908 up the display.
5909 Examples: >
5910 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
5911 \ remote_read(serverid)
5912
5913 :autocmd NONE RemoteReply *
5914 \ echo remote_read(expand("<amatch>"))
5915 :echo remote_send("gvim", ":sleep 10 | echo ".
5916 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005917<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005918remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005919 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005920 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005921 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005922 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005923 item as {end} a list with one item is returned. When {end}
5924 points to an item before {idx} this is an error.
5925 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005926 Example: >
5927 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005928 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00005929remove({dict}, {key})
5930 Remove the entry from {dict} with key {key}. Example: >
5931 :echo "removed " . remove(dict, "one")
5932< If there is no {key} in {dict} this is an error.
5933
5934 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005935
Bram Moolenaar071d4272004-06-13 20:20:40 +00005936rename({from}, {to}) *rename()*
5937 Rename the file by the name {from} to the name {to}. This
5938 should also work to move files across file systems. The
5939 result is a Number, which is 0 if the file was renamed
5940 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00005941 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005942 This function is not available in the |sandbox|.
5943
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005944repeat({expr}, {count}) *repeat()*
5945 Repeat {expr} {count} times and return the concatenated
5946 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005947 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005948< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005949 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00005950 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005951 :let longlist = repeat(['a', 'b'], 3)
5952< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005953
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005954
Bram Moolenaar071d4272004-06-13 20:20:40 +00005955resolve({filename}) *resolve()* *E655*
5956 On MS-Windows, when {filename} is a shortcut (a .lnk file),
5957 returns the path the shortcut points to in a simplified form.
5958 On Unix, repeat resolving symbolic links in all path
5959 components of {filename} and return the simplified result.
5960 To cope with link cycles, resolving of symbolic links is
5961 stopped after 100 iterations.
5962 On other systems, return the simplified {filename}.
5963 The simplification step is done as by |simplify()|.
5964 resolve() keeps a leading path component specifying the
5965 current directory (provided the result is still a relative
5966 path name) and also keeps a trailing path separator.
5967
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005968 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005969reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005970 {list}.
5971 If you want a list to remain unmodified make a copy first: >
5972 :let revlist = reverse(copy(mylist))
5973
Bram Moolenaar446cb832008-06-24 21:56:24 +00005974round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00005975 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00005976 as a |Float|. If {expr} lies halfway between two integral
5977 values, then use the larger one (away from zero).
5978 {expr} must evaluate to a |Float| or a |Number|.
5979 Examples: >
5980 echo round(0.456)
5981< 0.0 >
5982 echo round(4.5)
5983< 5.0 >
5984 echo round(-4.5)
5985< -5.0
5986 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005987
Bram Moolenaar9a773482013-06-11 18:40:13 +02005988screenattr(row, col) *screenattr()*
5989 Like screenchar(), but return the attribute. This is a rather
5990 arbitrary number that can only be used to compare to the
5991 attribute at other positions.
5992
5993screenchar(row, col) *screenchar()*
5994 The result is a Number, which is the character at position
5995 [row, col] on the screen. This works for every possible
5996 screen position, also status lines, window separators and the
5997 command line. The top left position is row one, column one
5998 The character excludes composing characters. For double-byte
5999 encodings it may only be the first byte.
6000 This is mainly to be used for testing.
6001 Returns -1 when row or col is out of range.
6002
Bram Moolenaar34feacb2012-12-05 19:01:43 +01006003screencol() *screencol()*
6004 The result is a Number, which is the current screen column of
6005 the cursor. The leftmost column has number 1.
6006 This function is mainly used for testing.
6007
6008 Note: Always returns the current screen column, thus if used
6009 in a command (e.g. ":echo screencol()") it will return the
6010 column inside the command line, which is 1 when the command is
6011 executed. To get the cursor position in the file use one of
6012 the following mappings: >
6013 nnoremap <expr> GG ":echom ".screencol()."\n"
6014 nnoremap <silent> GG :echom screencol()<CR>
6015<
6016screenrow() *screenrow()*
6017 The result is a Number, which is the current screen row of the
6018 cursor. The top line has number one.
6019 This function is mainly used for testing.
6020
6021 Note: Same restrictions as with |screencol()|.
6022
Bram Moolenaar76929292008-01-06 19:07:36 +00006023search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006024 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006025 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006026
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006027 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006028 If there is no match a 0 is returned and the cursor doesn't
6029 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006030
Bram Moolenaar071d4272004-06-13 20:20:40 +00006031 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006032 'b' search Backward instead of forward
6033 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006034 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006035 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006036 'p' return number of matching sub-Pattern (see below)
6037 's' Set the ' mark at the previous location of the cursor
6038 'w' Wrap around the end of the file
6039 'W' don't Wrap around the end of the file
6040 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00006041 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
6042
Bram Moolenaar02743632005-07-25 20:42:36 +00006043 If the 's' flag is supplied, the ' mark is set, only if the
6044 cursor is moved. The 's' flag cannot be combined with the 'n'
6045 flag.
6046
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006047 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006048
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006049 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01006050 column zero and then matches before the cursor are skipped.
6051 When the 'c' flag is present in 'cpo' the next search starts
6052 after the match. Without the 'c' flag the next search starts
6053 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006054
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006055 When the {stopline} argument is given then the search stops
6056 after searching this line. This is useful to restrict the
6057 search to a range of lines. Examples: >
6058 let match = search('(', 'b', line("w0"))
6059 let end = search('END', '', line("w$"))
6060< When {stopline} is used and it is not zero this also implies
6061 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00006062 A zero value is equal to not giving the argument.
6063
6064 When the {timeout} argument is given the search stops when
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02006065 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00006066 {timeout} is 500 the search stops after half a second.
6067 The value must not be negative. A zero value is like not
6068 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02006069 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006070
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006071 *search()-sub-match*
6072 With the 'p' flag the returned value is one more than the
6073 first sub-match in \(\). One if none of them matched but the
6074 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006075 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006076
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006077 The cursor will be positioned at the match, unless the 'n'
6078 flag is used.
6079
Bram Moolenaar071d4272004-06-13 20:20:40 +00006080 Example (goes over all files in the argument list): >
6081 :let n = 1
6082 :while n <= argc() " loop over all files in arglist
6083 : exe "argument " . n
6084 : " start at the last char in the file and wrap for the
6085 : " first search to find match at start of file
6086 : normal G$
6087 : let flags = "w"
6088 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00006089 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00006090 : let flags = "W"
6091 : endwhile
6092 : update " write the file if modified
6093 : let n = n + 1
6094 :endwhile
6095<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006096 Example for using some flags: >
6097 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
6098< This will search for the keywords "if", "else", and "endif"
6099 under or after the cursor. Because of the 'p' flag, it
6100 returns 1, 2, or 3 depending on which keyword is found, or 0
6101 if the search fails. With the cursor on the first word of the
6102 line:
6103 if (foo == 0) | let foo = foo + 1 | endif ~
6104 the function returns 1. Without the 'c' flag, the function
6105 finds the "endif" and returns 3. The same thing happens
6106 without the 'e' flag if the cursor is on the "f" of "if".
6107 The 'n' flag tells the function not to move the cursor.
6108
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006109
Bram Moolenaarf75a9632005-09-13 21:20:47 +00006110searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
6111 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006112
Bram Moolenaarf75a9632005-09-13 21:20:47 +00006113 With a non-zero {global} argument it works like |gD|, find
6114 first match in the file. Otherwise it works like |gd|, find
6115 first match in the function.
6116
6117 With a non-zero {thisblock} argument matches in a {} block
6118 that ends before the cursor position are ignored. Avoids
6119 finding variable declarations only valid in another scope.
6120
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006121 Moves the cursor to the found match.
6122 Returns zero for success, non-zero for failure.
6123 Example: >
6124 if searchdecl('myvar') == 0
6125 echo getline('.')
6126 endif
6127<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006128 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006129searchpair({start}, {middle}, {end} [, {flags} [, {skip}
6130 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006131 Search for the match of a nested start-end pair. This can be
6132 used to find the "endif" that matches an "if", while other
6133 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006134 The search starts at the cursor. The default is to search
6135 forward, include 'b' in {flags} to search backward.
6136 If a match is found, the cursor is positioned at it and the
6137 line number is returned. If no match is found 0 or -1 is
6138 returned and the cursor doesn't move. No error message is
6139 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006140
6141 {start}, {middle} and {end} are patterns, see |pattern|. They
6142 must not contain \( \) pairs. Use of \%( \) is allowed. When
6143 {middle} is not empty, it is found when searching from either
6144 direction, but only when not in a nested start-end pair. A
6145 typical use is: >
6146 searchpair('\<if\>', '\<else\>', '\<endif\>')
6147< By leaving {middle} empty the "else" is skipped.
6148
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006149 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
6150 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006151 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006152 outer pair. Implies the 'W' flag.
6153 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006154 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006155 Note: it's nearly always a good idea to use the 'W' flag, to
6156 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006157
6158 When a match for {start}, {middle} or {end} is found, the
6159 {skip} expression is evaluated with the cursor positioned on
6160 the start of the match. It should return non-zero if this
6161 match is to be skipped. E.g., because it is inside a comment
6162 or a string.
6163 When {skip} is omitted or empty, every match is accepted.
6164 When evaluating {skip} causes an error the search is aborted
6165 and -1 returned.
6166
Bram Moolenaar76929292008-01-06 19:07:36 +00006167 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006168
Bram Moolenaar071d4272004-06-13 20:20:40 +00006169 The value of 'ignorecase' is used. 'magic' is ignored, the
6170 patterns are used like it's on.
6171
6172 The search starts exactly at the cursor. A match with
6173 {start}, {middle} or {end} at the next character, in the
6174 direction of searching, is the first one found. Example: >
6175 if 1
6176 if 2
6177 endif 2
6178 endif 1
6179< When starting at the "if 2", with the cursor on the "i", and
6180 searching forwards, the "endif 2" is found. When starting on
6181 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00006182 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006183 then this is considered to be a nested if/endif from "if 2" to
6184 "endif 2".
6185 When searching backwards and {end} is more than one character,
6186 it may be useful to put "\zs" at the end of the pattern, so
6187 that when the cursor is inside a match with the end it finds
6188 the matching start.
6189
6190 Example, to find the "endif" command in a Vim script: >
6191
6192 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
6193 \ 'getline(".") =~ "^\\s*\""')
6194
6195< The cursor must be at or after the "if" for which a match is
6196 to be found. Note that single-quote strings are used to avoid
6197 having to double the backslashes. The skip expression only
6198 catches comments at the start of a line, not after a command.
6199 Also, a word "en" or "if" halfway a line is considered a
6200 match.
6201 Another example, to search for the matching "{" of a "}": >
6202
6203 :echo searchpair('{', '', '}', 'bW')
6204
6205< This works when the cursor is at or before the "}" for which a
6206 match is to be found. To reject matches that syntax
6207 highlighting recognized as strings: >
6208
6209 :echo searchpair('{', '', '}', 'bW',
6210 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
6211<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006212 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006213searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
6214 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006215 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006216 column position of the match. The first element of the |List|
6217 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006218 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006219 returns [0, 0]. >
6220
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006221 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
6222<
6223 See |match-parens| for a bigger and more useful example.
6224
Bram Moolenaar76929292008-01-06 19:07:36 +00006225searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006226 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006227 column position of the match. The first element of the |List|
6228 is the line number and the second element is the byte index of
6229 the column position of the match. If no match is found,
6230 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006231 Example: >
6232 :let [lnum, col] = searchpos('mypattern', 'n')
6233
6234< When the 'p' flag is given then there is an extra item with
6235 the sub-pattern match number |search()-sub-match|. Example: >
6236 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
6237< In this example "submatch" is 2 when a lowercase letter is
6238 found |/\l|, 3 when an uppercase letter is found |/\u|.
6239
Bram Moolenaar81edd172016-04-14 13:51:37 +02006240server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006241 Send a reply string to {clientid}. The most recent {clientid}
6242 that sent a string can be retrieved with expand("<client>").
6243 {only available when compiled with the |+clientserver| feature}
6244 Note:
6245 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006246 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006247 before calling any commands that waits for input.
6248 See also |clientserver|.
6249 Example: >
6250 :echo server2client(expand("<client>"), "HELLO")
6251<
6252serverlist() *serverlist()*
6253 Return a list of available server names, one per line.
6254 When there are no servers or the information is not available
6255 an empty string is returned. See also |clientserver|.
6256 {only available when compiled with the |+clientserver| feature}
6257 Example: >
6258 :echo serverlist()
6259<
6260setbufvar({expr}, {varname}, {val}) *setbufvar()*
6261 Set option or local variable {varname} in buffer {expr} to
6262 {val}.
6263 This also works for a global or local window option, but it
6264 doesn't work for a global or local window variable.
6265 For a local window option the global value is unchanged.
6266 For the use of {expr}, see |bufname()| above.
6267 Note that the variable name without "b:" must be used.
6268 Examples: >
6269 :call setbufvar(1, "&mod", 1)
6270 :call setbufvar("todo", "myvar", "foobar")
6271< This function is not available in the |sandbox|.
6272
Bram Moolenaar12969c02015-09-08 23:36:10 +02006273setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02006274 Set the current character search information to {dict},
6275 which contains one or more of the following entries:
6276
6277 char character which will be used for a subsequent
6278 |,| or |;| command; an empty string clears the
6279 character search
6280 forward direction of character search; 1 for forward,
6281 0 for backward
6282 until type of character search; 1 for a |t| or |T|
6283 character search, 0 for an |f| or |F|
6284 character search
6285
6286 This can be useful to save/restore a user's character search
6287 from a script: >
6288 :let prevsearch = getcharsearch()
6289 :" Perform a command which clobbers user's search
6290 :call setcharsearch(prevsearch)
6291< Also see |getcharsearch()|.
6292
Bram Moolenaar071d4272004-06-13 20:20:40 +00006293setcmdpos({pos}) *setcmdpos()*
6294 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00006295 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006296 Use |getcmdpos()| to obtain the current position.
6297 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00006298 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
6299 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
6300 set after the command line is set to the expression. For
6301 |c_CTRL-R_=| it is set after evaluating the expression but
6302 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006303 When the number is too big the cursor is put at the end of the
6304 line. A number smaller than one has undefined results.
6305 Returns 0 when successful, 1 when not editing the command
6306 line.
6307
Bram Moolenaar80492532016-03-08 17:08:53 +01006308setfperm({fname}, {mode}) *setfperm()* *chmod*
6309 Set the file permissions for {fname} to {mode}.
6310 {mode} must be a string with 9 characters. It is of the form
6311 "rwxrwxrwx", where each group of "rwx" flags represent, in
6312 turn, the permissions of the owner of the file, the group the
6313 file belongs to, and other users. A '-' character means the
6314 permission is off, any other character means on. Multi-byte
6315 characters are not supported.
6316
6317 For example "rw-r-----" means read-write for the user,
6318 readable by the group, not accessible by others. "xx-x-----"
6319 would do the same thing.
6320
6321 Returns non-zero for success, zero for failure.
6322
6323 To read permissions see |getfperm()|.
6324
6325
Bram Moolenaar446cb832008-06-24 21:56:24 +00006326setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006327 Set line {lnum} of the current buffer to {text}. To insert
6328 lines use |append()|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006329 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006330 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006331 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006332 If this succeeds, 0 is returned. If this fails (most likely
6333 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006334 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00006335< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006336 will be set to the items in the list. Example: >
6337 :call setline(5, ['aaa', 'bbb', 'ccc'])
6338< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02006339 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006340 : call setline(n, l)
6341 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00006342< Note: The '[ and '] marks are not set.
6343
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006344setloclist({nr}, {list} [, {action}]) *setloclist()*
6345 Create or replace or add to the location list for window {nr}.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02006346 {nr} can be the window number or the window ID.
6347 When {nr} is zero the current window is used.
6348
6349 For a location list window, the displayed location list is
6350 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006351 Otherwise, same as |setqflist()|.
6352 Also see |location-list|.
6353
6354setmatches({list}) *setmatches()*
6355 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00006356 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006357 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006358
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006359 *setpos()*
6360setpos({expr}, {list})
6361 Set the position for {expr}. Possible values:
6362 . the cursor
6363 'x mark x
6364
Bram Moolenaar493c1782014-05-28 14:34:46 +02006365 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006366 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02006367 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006368
Bram Moolenaar446cb832008-06-24 21:56:24 +00006369 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006370 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006371 the current buffer. To set a mark in another buffer you can
6372 use the |bufnr()| function to turn a file name into a buffer
6373 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00006374 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006375
6376 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006377 column is 1. Use a zero "lnum" to delete a mark. If "col" is
6378 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006379
6380 The "off" number is only used when 'virtualedit' is set. Then
6381 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006382 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006383 character.
6384
Bram Moolenaar493c1782014-05-28 14:34:46 +02006385 The "curswant" number is only used when setting the cursor
6386 position. It sets the preferred column for when moving the
6387 cursor vertically. When the "curswant" number is missing the
6388 preferred column is not set. When it is present and setting a
6389 mark position it is not used.
6390
Bram Moolenaardfb18412013-12-11 18:53:29 +01006391 Note that for '< and '> changing the line number may result in
6392 the marks to be effectively be swapped, so that '< is always
6393 before '>.
6394
Bram Moolenaar08250432008-02-13 11:42:46 +00006395 Returns 0 when the position could be set, -1 otherwise.
6396 An error message is given if {expr} is invalid.
6397
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02006398 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006399
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006400 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02006401 vertically; if you set the cursor position with this, |j| and
6402 |k| motions will jump to previous columns! Use |cursor()| to
6403 also set the preferred column. Also see the "curswant" key in
6404 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006405
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006406
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006407setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006408 Create or replace or add to the quickfix list using the items
6409 in {list}. Each item in {list} is a dictionary.
6410 Non-dictionary items in {list} are ignored. Each dictionary
6411 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006412
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006413 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00006414 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006415 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00006416 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006417 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006418 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006419 col column number
6420 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006421 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00006422 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006423 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006424 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006425
Bram Moolenaar582fd852005-03-28 20:58:01 +00006426 The "col", "vcol", "nr", "type" and "text" entries are
6427 optional. Either "lnum" or "pattern" entry can be used to
6428 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006429 If the "filename" and "bufnr" entries are not present or
6430 neither the "lnum" or "pattern" entries are present, then the
6431 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006432 If both "pattern" and "lnum" are present then "pattern" will
6433 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02006434 If you supply an empty {list}, the quickfix list will be
6435 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006436 Note that the list is not exactly the same as what
6437 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006438
Bram Moolenaar06481422016-04-30 15:13:38 +02006439 *E927*
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006440 If {action} is set to 'a', then the items from {list} are
6441 added to the existing quickfix list. If there is no existing
Bram Moolenaar511972d2016-06-04 18:09:59 +02006442 list, then a new list is created.
6443
6444 If {action} is set to 'r', then the items from the current
6445 quickfix list are replaced with the items from {list}. This
6446 can also be used to clear the list: >
6447 :call setqflist([], 'r')
6448<
6449 If {action} is not present or is set to ' ', then a new list
6450 is created.
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006451
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006452 Returns zero for success, -1 for failure.
6453
6454 This function can be used to create a quickfix list
6455 independent of the 'errorformat' setting. Use a command like
6456 ":cc 1" to jump to the first position.
6457
6458
Bram Moolenaar071d4272004-06-13 20:20:40 +00006459 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01006460setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006461 Set the register {regname} to {value}.
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006462 {value} may be any value returned by |getreg()|, including
6463 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006464 If {options} contains "a" or {regname} is upper case,
6465 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02006466 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006467 "c" or "v" |characterwise| mode
6468 "l" or "V" |linewise| mode
6469 "b" or "<CTRL-V>" |blockwise-visual| mode
6470 If a number immediately follows "b" or "<CTRL-V>" then this is
6471 used as the width of the selection - if it is not specified
6472 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006473 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006474
6475 If {options} contains no register settings, then the default
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006476 is to use character mode unless {value} ends in a <NL> for
6477 string {value} and linewise mode for list {value}. Blockwise
6478 mode is never selected automatically.
6479 Returns zero for success, non-zero for failure.
6480
6481 *E883*
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006482 Note: you may not use |List| containing more than one item to
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006483 set search and expression registers. Lists containing no
6484 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006485
6486 Examples: >
6487 :call setreg(v:register, @*)
6488 :call setreg('*', @%, 'ac')
6489 :call setreg('a', "1\n2\n3", 'b5')
6490
6491< This example shows using the functions to save and restore a
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006492 register (note: you may not reliably restore register value
6493 without using the third argument to |getreg()| as without it
6494 newlines are represented as newlines AND Nul bytes are
6495 represented as newlines as well, see |NL-used-for-Nul|). >
6496 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006497 :let var_amode = getregtype('a')
6498 ....
6499 :call setreg('a', var_a, var_amode)
6500
6501< You can also change the type of a register by appending
6502 nothing: >
6503 :call setreg('a', '', 'al')
6504
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006505settabvar({tabnr}, {varname}, {val}) *settabvar()*
6506 Set tab-local variable {varname} to {val} in tab page {tabnr}.
6507 |t:var|
6508 Note that the variable name without "t:" must be used.
6509 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006510 This function is not available in the |sandbox|.
6511
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006512settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
6513 Set option or local variable {varname} in window {winnr} to
6514 {val}.
6515 Tabs are numbered starting with one. For the current tabpage
6516 use |setwinvar()|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02006517 {winnr} can be the window number or the window ID.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006518 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006519 This also works for a global or local buffer option, but it
6520 doesn't work for a global or local buffer variable.
6521 For a local buffer option the global value is unchanged.
6522 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006523 Examples: >
6524 :call settabwinvar(1, 1, "&list", 0)
6525 :call settabwinvar(3, 2, "myvar", "foobar")
6526< This function is not available in the |sandbox|.
6527
6528setwinvar({nr}, {varname}, {val}) *setwinvar()*
6529 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006530 Examples: >
6531 :call setwinvar(1, "&list", 0)
6532 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006533
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006534sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01006535 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006536 checksum of {string}.
6537 {only available when compiled with the |+cryptv| feature}
6538
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006539shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006540 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006541 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006542 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006543 quotes within {string}.
6544 For other systems, it will enclose {string} in single quotes
6545 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006546 When the {special} argument is present and it's a non-zero
6547 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006548 items such as "!", "%", "#" and "<cword>" will be preceded by
6549 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006550 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006551 The "!" character will be escaped (again with a |non-zero-arg|
6552 {special}) when 'shell' contains "csh" in the tail. That is
6553 because for csh and tcsh "!" is used for history replacement
6554 even when inside single quotes.
6555 The <NL> character is also escaped. With a |non-zero-arg|
6556 {special} and 'shell' containing "csh" in the tail it's
6557 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006558 Example of use with a |:!| command: >
6559 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
6560< This results in a directory listing for the file under the
6561 cursor. Example of use with |system()|: >
6562 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01006563< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006564
6565
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006566shiftwidth() *shiftwidth()*
6567 Returns the effective value of 'shiftwidth'. This is the
6568 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006569 'tabstop' value. This function was introduced with patch
6570 7.3.694 in 2012, everybody should have it by now.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006571
6572
Bram Moolenaar071d4272004-06-13 20:20:40 +00006573simplify({filename}) *simplify()*
6574 Simplify the file name as much as possible without changing
6575 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
6576 Unix) are not resolved. If the first path component in
6577 {filename} designates the current directory, this will be
6578 valid for the result as well. A trailing path separator is
6579 not removed either.
6580 Example: >
6581 simplify("./dir/.././/file/") == "./file/"
6582< Note: The combination "dir/.." is only removed if "dir" is
6583 a searchable directory or does not exist. On Unix, it is also
6584 removed when "dir" is a symbolic link within the same
6585 directory. In order to resolve all the involved symbolic
6586 links before simplifying the path name, use |resolve()|.
6587
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006588
Bram Moolenaar446cb832008-06-24 21:56:24 +00006589sin({expr}) *sin()*
6590 Return the sine of {expr}, measured in radians, as a |Float|.
6591 {expr} must evaluate to a |Float| or a |Number|.
6592 Examples: >
6593 :echo sin(100)
6594< -0.506366 >
6595 :echo sin(-4.01)
6596< 0.763301
6597 {only available when compiled with the |+float| feature}
6598
6599
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006600sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006601 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006602 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006603 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006604 Examples: >
6605 :echo sinh(0.5)
6606< 0.521095 >
6607 :echo sinh(-0.9)
6608< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02006609 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006610
6611
Bram Moolenaar5f894962011-06-19 02:55:37 +02006612sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01006613 Sort the items in {list} in-place. Returns {list}.
6614
6615 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006616 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02006617
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006618< When {func} is omitted, is empty or zero, then sort() uses the
6619 string representation of each item to sort on. Numbers sort
6620 after Strings, |Lists| after Numbers. For sorting text in the
6621 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006622
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006623 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006624 ignored.
6625
6626 When {func} is given and it is 'n' then all items will be
6627 sorted numerical (Implementation detail: This uses the
6628 strtod() function to parse numbers, Strings, Lists, Dicts and
6629 Funcrefs will be considered as being 0).
6630
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01006631 When {func} is given and it is 'N' then all items will be
6632 sorted numerical. This is like 'n' but a string containing
6633 digits will be used as the number they represent.
6634
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01006635 When {func} is given and it is 'f' then all items will be
6636 sorted numerical. All values must be a Number or a Float.
6637
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006638 When {func} is a |Funcref| or a function name, this function
6639 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006640 items as argument and must return zero if they are equal, 1 or
6641 bigger if the first one sorts after the second one, -1 or
6642 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006643
6644 {dict} is for functions with the "dict" attribute. It will be
6645 used to set the local variable "self". |Dictionary-function|
6646
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006647 The sort is stable, items which compare equal (as number or as
6648 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02006649 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006650 same order as they were originally.
6651
Bram Moolenaar327aa022014-03-25 18:24:23 +01006652 Also see |uniq()|.
6653
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006654 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006655 func MyCompare(i1, i2)
6656 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
6657 endfunc
6658 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006659< A shorter compare version for this specific simple case, which
6660 ignores overflow: >
6661 func MyCompare(i1, i2)
6662 return a:i1 - a:i2
6663 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006664<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006665 *soundfold()*
6666soundfold({word})
6667 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00006668 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006669 soundfolding. 'spell' must be set. When no sound folding is
6670 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006671 This can be used for making spelling suggestions. Note that
6672 the method can be quite slow.
6673
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006674 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00006675spellbadword([{sentence}])
6676 Without argument: The result is the badly spelled word under
6677 or after the cursor. The cursor is moved to the start of the
6678 bad word. When no bad word is found in the cursor line the
6679 result is an empty string and the cursor doesn't move.
6680
6681 With argument: The result is the first word in {sentence} that
6682 is badly spelled. If there are no spelling mistakes the
6683 result is an empty string.
6684
6685 The return value is a list with two items:
6686 - The badly spelled word or an empty string.
6687 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006688 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00006689 "rare" rare word
6690 "local" word only valid in another region
6691 "caps" word should start with Capital
6692 Example: >
6693 echo spellbadword("the quik brown fox")
6694< ['quik', 'bad'] ~
6695
6696 The spelling information for the current window is used. The
6697 'spell' option must be set and the value of 'spelllang' is
6698 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006699
6700 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006701spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006702 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006703 When {max} is given up to this number of suggestions are
6704 returned. Otherwise up to 25 suggestions are returned.
6705
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006706 When the {capital} argument is given and it's non-zero only
6707 suggestions with a leading capital will be given. Use this
6708 after a match with 'spellcapcheck'.
6709
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006710 {word} can be a badly spelled word followed by other text.
6711 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00006712 suggestions also include the following text, thus you can
6713 replace a line.
6714
6715 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006716 returned. {word} itself is not included in the suggestions,
6717 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006718
6719 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006720 'spell' option must be set and the values of 'spelllang' and
6721 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006722
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006723
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006724split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006725 Make a |List| out of {expr}. When {pattern} is omitted or
6726 empty each white-separated sequence of characters becomes an
6727 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006728 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01006729 removing the matched characters. 'ignorecase' is not used
6730 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006731 When the first or last item is empty it is omitted, unless the
6732 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00006733 Other empty items are kept when {pattern} matches at least one
6734 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006735 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006736 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006737< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006738 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02006739< If you want to keep the separator you can also use '\zs' at
6740 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00006741 :echo split('abc:def:ghi', ':\zs')
6742< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006743 Splitting a table where the first element can be empty: >
6744 :let items = split(line, ':', 1)
6745< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006746
6747
Bram Moolenaar446cb832008-06-24 21:56:24 +00006748sqrt({expr}) *sqrt()*
6749 Return the non-negative square root of Float {expr} as a
6750 |Float|.
6751 {expr} must evaluate to a |Float| or a |Number|. When {expr}
6752 is negative the result is NaN (Not a Number).
6753 Examples: >
6754 :echo sqrt(100)
6755< 10.0 >
6756 :echo sqrt(-4.01)
6757< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00006758 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006759 {only available when compiled with the |+float| feature}
6760
6761
Bram Moolenaar81edd172016-04-14 13:51:37 +02006762str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006763 Convert String {expr} to a Float. This mostly works the same
6764 as when using a floating point number in an expression, see
6765 |floating-point-format|. But it's a bit more permissive.
6766 E.g., "1e40" is accepted, while in an expression you need to
6767 write "1.0e40".
6768 Text after the number is silently ignored.
6769 The decimal point is always '.', no matter what the locale is
6770 set to. A comma ends the number: "12,345.67" is converted to
6771 12.0. You can strip out thousands separators with
6772 |substitute()|: >
6773 let f = str2float(substitute(text, ',', '', 'g'))
6774< {only available when compiled with the |+float| feature}
6775
6776
Bram Moolenaar81edd172016-04-14 13:51:37 +02006777str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006778 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01006779 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006780 When {base} is omitted base 10 is used. This also means that
6781 a leading zero doesn't cause octal conversion to be used, as
6782 with the default String to Number conversion.
6783 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01006784 different base the result will be zero. Similarly, when
6785 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
6786 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006787 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006788
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006789
Bram Moolenaar979243b2015-06-26 19:35:49 +02006790strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02006791 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02006792 in String {expr}.
6793 When {skipcc} is omitted or zero, composing characters are
6794 counted separately.
6795 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02006796 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006797
6798 {skipcc} is only available after 7.4.755. For backward
6799 compatibility, you can define a wrapper function: >
6800 if has("patch-7.4.755")
6801 function s:strchars(str, skipcc)
6802 return strchars(a:str, a:skipcc)
6803 endfunction
6804 else
6805 function s:strchars(str, skipcc)
6806 if a:skipcc
6807 return strlen(substitute(a:str, ".", "x", "g"))
6808 else
6809 return strchars(a:str)
6810 endif
6811 endfunction
6812 endif
6813<
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006814strcharpart({src}, {start}[, {len}]) *strcharpart()*
6815 Like |strpart()| but using character index and length instead
6816 of byte index and length.
6817 When a character index is used where a character does not
6818 exist it is assumed to be one byte. For example: >
6819 strcharpart('abc', -1, 2)
6820< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006821
Bram Moolenaardc536092010-07-18 15:45:49 +02006822strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
6823 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02006824 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02006825 When {col} is omitted zero is used. Otherwise it is the
6826 screen column where to start. This matters for Tab
6827 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02006828 The option settings of the current window are used. This
6829 matters for anything that's displayed differently, such as
6830 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006831 When {expr} contains characters with East Asian Width Class
6832 Ambiguous, this function's return value depends on 'ambiwidth'.
6833 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006834
Bram Moolenaar071d4272004-06-13 20:20:40 +00006835strftime({format} [, {time}]) *strftime()*
6836 The result is a String, which is a formatted date and time, as
6837 specified by the {format} string. The given {time} is used,
6838 or the current time if no time is given. The accepted
6839 {format} depends on your system, thus this is not portable!
6840 See the manual page of the C function strftime() for the
6841 format. The maximum length of the result is 80 characters.
6842 See also |localtime()| and |getftime()|.
6843 The language can be changed with the |:language| command.
6844 Examples: >
6845 :echo strftime("%c") Sun Apr 27 11:49:23 1997
6846 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
6847 :echo strftime("%y%m%d %T") 970427 11:53:55
6848 :echo strftime("%H:%M") 11:55
6849 :echo strftime("%c", getftime("file.c"))
6850 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006851< Not available on all systems. To check use: >
6852 :if exists("*strftime")
6853
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006854strgetchar({str}, {index}) *strgetchar()*
6855 Get character {index} from {str}. This uses a character
6856 index, not a byte index. Composing characters are considered
6857 separate characters here.
6858 Also see |strcharpart()| and |strchars()|.
6859
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006860stridx({haystack}, {needle} [, {start}]) *stridx()*
6861 The result is a Number, which gives the byte index in
6862 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006863 If {start} is specified, the search starts at index {start}.
6864 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01006865 :let colon1 = stridx(line, ":")
6866 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00006867< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006868 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006869 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006870 See also |strridx()|.
6871 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006872 :echo stridx("An Example", "Example") 3
6873 :echo stridx("Starting point", "Start") 0
6874 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006875< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006876 stridx() works similar to the C function strstr(). When used
6877 with a single character it works similar to strchr().
6878
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006879 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006880string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00006881 Float, String or a composition of them, then the result can be
6882 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006883 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01006884 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006885 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00006886 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00006887 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006888 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00006889 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01006890
6891 When a List or Dictionary has a recursive reference it is
6892 replaced by "[...]" or "{...}". Using eval() on the result
6893 will then fail.
6894
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006895 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006896
Bram Moolenaar071d4272004-06-13 20:20:40 +00006897 *strlen()*
6898strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00006899 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006900 If the argument is a Number it is first converted to a String.
6901 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02006902 If you want to count the number of multi-byte characters use
6903 |strchars()|.
6904 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006905
6906strpart({src}, {start}[, {len}]) *strpart()*
6907 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00006908 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006909 To count characters instead of bytes use |strcharpart()|.
6910
6911 When bytes are selected which do not exist, this doesn't
6912 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006913 If {len} is missing, the copy continues from {start} till the
6914 end of the {src}. >
6915 strpart("abcdefg", 3, 2) == "de"
6916 strpart("abcdefg", -2, 4) == "ab"
6917 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00006918 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006919
Bram Moolenaar071d4272004-06-13 20:20:40 +00006920< Note: To get the first character, {start} must be 0. For
6921 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00006922 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006923<
Bram Moolenaar677ee682005-01-27 14:41:15 +00006924strridx({haystack}, {needle} [, {start}]) *strridx()*
6925 The result is a Number, which gives the byte index in
6926 {haystack} of the last occurrence of the String {needle}.
6927 When {start} is specified, matches beyond this index are
6928 ignored. This can be used to find a match before a previous
6929 match: >
6930 :let lastcomma = strridx(line, ",")
6931 :let comma2 = strridx(line, ",", lastcomma - 1)
6932< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006933 For pattern searches use |match()|.
6934 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00006935 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006936 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006937 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006938< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006939 When used with a single character it works similar to the C
6940 function strrchr().
6941
Bram Moolenaar071d4272004-06-13 20:20:40 +00006942strtrans({expr}) *strtrans()*
6943 The result is a String, which is {expr} with all unprintable
6944 characters translated into printable characters |'isprint'|.
6945 Like they are shown in a window. Example: >
6946 echo strtrans(@a)
6947< This displays a newline in register a as "^@" instead of
6948 starting a new line.
6949
Bram Moolenaar72597a52010-07-18 15:31:08 +02006950strwidth({expr}) *strwidth()*
6951 The result is a Number, which is the number of display cells
6952 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02006953 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006954 When {expr} contains characters with East Asian Width Class
6955 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006956 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006957
Bram Moolenaar41571762014-04-02 19:00:58 +02006958submatch({nr}[, {list}]) *submatch()*
Bram Moolenaar251e1912011-06-19 05:09:16 +02006959 Only for an expression in a |:substitute| command or
6960 substitute() function.
6961 Returns the {nr}'th submatch of the matched text. When {nr}
6962 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02006963 Note that a NL in the string can stand for a line break of a
6964 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006965 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02006966
6967 If {list} is present and non-zero then submatch() returns
6968 a list of strings, similar to |getline()| with two arguments.
6969 NL characters in the text represent NUL characters in the
6970 text.
6971 Only returns more than one item for |:substitute|, inside
6972 |substitute()| this list will always contain one or zero
6973 items, since there are no real line breaks.
6974
Bram Moolenaar071d4272004-06-13 20:20:40 +00006975 Example: >
6976 :s/\d\+/\=submatch(0) + 1/
6977< This finds the first number in the line and adds one to it.
6978 A line break is included as a newline character.
6979
6980substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
6981 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02006982 the first match of {pat} is replaced with {sub}.
6983 When {flags} is "g", all matches of {pat} in {expr} are
6984 replaced. Otherwise {flags} should be "".
6985
6986 This works like the ":substitute" command (without any flags).
6987 But the matching with {pat} is always done like the 'magic'
6988 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006989 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
6990 if you want to ignore or match case and ignore 'ignorecase'.
6991 'smartcase' is not used. See |string-match| for how {pat} is
6992 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006993
6994 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006995 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00006996 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006997 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006998
Bram Moolenaar071d4272004-06-13 20:20:40 +00006999 When {pat} does not match in {expr}, {expr} is returned
7000 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02007001
Bram Moolenaar071d4272004-06-13 20:20:40 +00007002 Example: >
7003 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
7004< This removes the last component of the 'path' option. >
7005 :echo substitute("testing", ".*", "\\U\\0", "")
7006< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02007007
7008 When {sub} starts with "\=", the remainder is interpreted as
7009 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02007010 :echo substitute(s, '%\(\x\x\)',
7011 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00007012
Bram Moolenaar47136d72004-10-12 20:02:24 +00007013synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007014 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00007015 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007016 The syntax ID can be used with |synIDattr()| and
7017 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007018
Bram Moolenaar47136d72004-10-12 20:02:24 +00007019 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007020 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02007021 Note that when the position is after the last character,
7022 that's where the cursor can be in Insert mode, synID() returns
7023 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007024
Bram Moolenaar071d4272004-06-13 20:20:40 +00007025 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007026 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00007027 the effective color. When {trans} is zero, the transparent
7028 item is returned. This is useful when wanting to know which
7029 syntax item is effective (e.g. inside parens).
7030 Warning: This function can be very slow. Best speed is
7031 obtained by going through the file in forward direction.
7032
7033 Example (echoes the name of the syntax item under the cursor): >
7034 :echo synIDattr(synID(line("."), col("."), 1), "name")
7035<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02007036
Bram Moolenaar071d4272004-06-13 20:20:40 +00007037synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
7038 The result is a String, which is the {what} attribute of
7039 syntax ID {synID}. This can be used to obtain information
7040 about a syntax item.
7041 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00007042 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00007043 used, the attributes for the currently active highlighting are
7044 used (GUI, cterm or term).
7045 Use synIDtrans() to follow linked highlight groups.
7046 {what} result
7047 "name" the name of the syntax item
7048 "fg" foreground color (GUI: color name used to set
7049 the color, cterm: color number as a string,
7050 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007051 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01007052 "font" font name (only available in the GUI)
7053 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007054 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007055 "fg#" like "fg", but for the GUI and the GUI is
7056 running the name in "#RRGGBB" form
7057 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00007058 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007059 "bold" "1" if bold
7060 "italic" "1" if italic
7061 "reverse" "1" if reverse
7062 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01007063 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00007064 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007065 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00007066
7067 Example (echoes the color of the syntax item under the
7068 cursor): >
7069 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
7070<
7071synIDtrans({synID}) *synIDtrans()*
7072 The result is a Number, which is the translated syntax ID of
7073 {synID}. This is the syntax group ID of what is being used to
7074 highlight the character. Highlight links given with
7075 ":highlight link" are followed.
7076
Bram Moolenaar483c5d82010-10-20 18:45:33 +02007077synconcealed({lnum}, {col}) *synconcealed()*
7078 The result is a List. The first item in the list is 0 if the
7079 character at the position {lnum} and {col} is not part of a
7080 concealable region, 1 if it is. The second item in the list is
7081 a string. If the first item is 1, the second item contains the
7082 text which will be displayed in place of the concealed text,
7083 depending on the current setting of 'conceallevel'. The third
7084 and final item in the list is a unique number representing the
7085 specific syntax region matched. This allows detection of the
7086 beginning of a new concealable region if there are two
7087 consecutive regions with the same replacement character.
7088 For an example use see $VIMRUNTIME/syntax/2html.vim .
7089
7090
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007091synstack({lnum}, {col}) *synstack()*
7092 Return a |List|, which is the stack of syntax items at the
7093 position {lnum} and {col} in the current window. Each item in
7094 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007095 The first item in the List is the outer region, following are
7096 items contained in that one. The last one is what |synID()|
7097 returns, unless not the whole item is highlighted or it is a
7098 transparent item.
7099 This function is useful for debugging a syntax file.
7100 Example that shows the syntax stack under the cursor: >
7101 for id in synstack(line("."), col("."))
7102 echo synIDattr(id, "name")
7103 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02007104< When the position specified with {lnum} and {col} is invalid
7105 nothing is returned. The position just after the last
7106 character in a line and the first column in an empty line are
7107 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00007108
Bram Moolenaarc0197e22004-09-13 20:26:32 +00007109system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007110 Get the output of the shell command {expr} as a string. See
7111 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02007112
7113 When {input} is given and is a string this string is written
7114 to a file and passed as stdin to the command. The string is
7115 written as-is, you need to take care of using the correct line
7116 separators yourself.
7117 If {input} is given and is a |List| it is written to the file
7118 in a way |writefile()| does with {binary} set to "b" (i.e.
7119 with a newline between each list item with newlines inside
7120 list items converted to NULs).
7121 Pipes are not used.
7122
Bram Moolenaar52a72462014-08-29 15:53:52 +02007123 When prepended by |:silent| the shell will not be set to
7124 cooked mode. This is meant to be used for commands that do
7125 not need the user to type. It avoids stray characters showing
7126 up on the screen which require |CTRL-L| to remove. >
7127 :silent let f = system('ls *.vim')
7128<
Bram Moolenaar26df0922014-02-23 23:39:13 +01007129 Note: Use |shellescape()| or |::S| with |expand()| or
7130 |fnamemodify()| to escape special characters in a command
7131 argument. Newlines in {expr} may cause the command to fail.
7132 The characters in 'shellquote' and 'shellxquote' may also
7133 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007134 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007135
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007136 The result is a String. Example: >
7137 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01007138 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00007139
7140< To make the result more system-independent, the shell output
7141 is filtered to replace <CR> with <NL> for Macintosh, and
7142 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02007143 To avoid the string being truncated at a NUL, all NUL
7144 characters are replaced with SOH (0x01).
7145
Bram Moolenaar071d4272004-06-13 20:20:40 +00007146 The command executed is constructed using several options:
7147 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
7148 ({tmp} is an automatically generated file name).
7149 For Unix and OS/2 braces are put around {expr} to allow for
7150 concatenated commands.
7151
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007152 The command will be executed in "cooked" mode, so that a
7153 CTRL-C will interrupt the command (on Unix at least).
7154
Bram Moolenaar071d4272004-06-13 20:20:40 +00007155 The resulting error code can be found in |v:shell_error|.
7156 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00007157
7158 Note that any wrong value in the options mentioned above may
7159 make the function fail. It has also been reported to fail
7160 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007161 Unlike ":!cmd" there is no automatic check for changed files.
7162 Use |:checktime| to force a check.
7163
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007164
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007165systemlist({expr} [, {input}]) *systemlist()*
7166 Same as |system()|, but returns a |List| with lines (parts of
7167 output separated by NL) with NULs transformed into NLs. Output
7168 is the same as |readfile()| will output with {binary} argument
7169 set to "b".
7170
Bram Moolenaar975b5272016-03-15 23:10:59 +01007171 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007172
7173
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007174tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007175 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007176 buffer associated with each window in the current tab page.
7177 {arg} specifies the number of tab page to be used. When
7178 omitted the current tab page is used.
7179 When {arg} is invalid the number zero is returned.
7180 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007181 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007182 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007183 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007184 endfor
7185< Note that a buffer may appear in more than one window.
7186
7187
7188tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00007189 The result is a Number, which is the number of the current
7190 tab page. The first tab page has number 1.
7191 When the optional argument is "$", the number of the last tab
7192 page is returned (the tab page count).
7193 The number can be used with the |:tab| command.
7194
7195
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007196tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02007197 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007198 {tabarg} specifies the number of tab page to be used.
7199 {arg} is used like with |winnr()|:
7200 - When omitted the current window number is returned. This is
7201 the window which will be used when going to this tab page.
7202 - When "$" the number of windows is returned.
7203 - When "#" the previous window nr is returned.
7204 Useful examples: >
7205 tabpagewinnr(1) " current window of tab page 1
7206 tabpagewinnr(4, '$') " number of windows in tab page 4
7207< When {tabarg} is invalid zero is returned.
7208
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00007209 *tagfiles()*
7210tagfiles() Returns a |List| with the file names used to search for tags
7211 for the current buffer. This is the 'tags' option expanded.
7212
7213
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007214taglist({expr}) *taglist()*
7215 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00007216 Each list item is a dictionary with at least the following
7217 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00007218 name Name of the tag.
7219 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007220 defined. It is either relative to the
7221 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007222 cmd Ex command used to locate the tag in
7223 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007224 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007225 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007226 kind values. Only available when
7227 using a tags file generated by
7228 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007229 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007230 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007231 More entries may be present, depending on the content of the
7232 tags file: access, implementation, inherits and signature.
7233 Refer to the ctags documentation for information about these
7234 fields. For C code the fields "struct", "class" and "enum"
7235 may appear, they give the name of the entity the tag is
7236 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007237
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00007238 The ex-command 'cmd' can be either an ex search pattern, a
7239 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007240
7241 If there are no matching tags, then an empty list is returned.
7242
7243 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01007244 used in {expr}. This also make the function work faster.
7245 Refer to |tag-regexp| for more information about the tag
7246 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007247
7248 Refer to |'tags'| for information about how the tags file is
7249 located by Vim. Refer to |tags-file-format| for the format of
7250 the tags file generated by the different ctags tools.
7251
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007252tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007253 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007254 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007255 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007256 Examples: >
7257 :echo tan(10)
7258< 0.648361 >
7259 :echo tan(-4.01)
7260< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02007261 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007262
7263
7264tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007265 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007266 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007267 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007268 Examples: >
7269 :echo tanh(0.5)
7270< 0.462117 >
7271 :echo tanh(-1)
7272< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02007273 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007274
7275
Bram Moolenaar574860b2016-05-24 17:33:34 +02007276tempname() *tempname()* *temp-file-name*
7277 The result is a String, which is the name of a file that
7278 doesn't exist. It can be used for a temporary file. The name
7279 is different for at least 26 consecutive calls. Example: >
7280 :let tmpfile = tempname()
7281 :exe "redir > " . tmpfile
7282< For Unix, the file will be in a private directory |tempfile|.
7283 For MS-Windows forward slashes are used when the 'shellslash'
7284 option is set or when 'shellcmdflag' starts with '-'.
7285
7286
Bram Moolenaar8e8df252016-05-25 21:23:21 +02007287test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()*
7288 This is for testing: If the memory allocation with {id} is
7289 called, then decrement {countdown}, and when it reaches zero
7290 let memory allocation fail {repeat} times. When {repeat} is
7291 smaller than one it fails one time.
7292
7293
7294 *test_disable_char_avail()*
7295test_disable_char_avail({expr})
7296 When {expr} is 1 the internal char_avail() function will
7297 return FALSE. When {expr} is 0 the char_avail() function will
7298 function normally.
7299 Only use this for a test where typeahead causes the test not
7300 to work. E.g., to trigger the CursorMovedI autocommand event.
7301
Bram Moolenaar574860b2016-05-24 17:33:34 +02007302test_garbagecollect_now() *test_garbagecollect_now()*
7303 Like garbagecollect(), but executed right away. This must
7304 only be called directly to avoid any structure to exist
7305 internally, and |v:testing| must have been set before calling
7306 any function.
7307
7308test_null_channel() *test_null_channel()*
7309 Return a Channel that is null. Only useful for testing.
7310 {only available when compiled with the +channel feature}
7311
7312test_null_dict() *test_null_dict()*
7313 Return a Dict that is null. Only useful for testing.
7314
7315test_null_job() *test_null_job()*
7316 Return a Job that is null. Only useful for testing.
7317 {only available when compiled with the +job feature}
7318
7319test_null_list() *test_null_list()*
7320 Return a List that is null. Only useful for testing.
7321
7322test_null_partial() *test_null_partial()*
7323 Return a Partial that is null. Only useful for testing.
7324
7325test_null_string() *test_null_string()*
7326 Return a String that is null. Only useful for testing.
7327
Bram Moolenaarc95a3022016-06-12 23:01:46 +02007328test_settime({expr}) *test_settime()*
7329 Set the time Vim uses internally. Currently only used for
7330 timestamps in the history, as they are used in viminfo.
7331 {expr} must evaluate to a number. When the value is zero the
7332 normal behavior is restored.
Bram Moolenaar574860b2016-05-24 17:33:34 +02007333
Bram Moolenaar975b5272016-03-15 23:10:59 +01007334 *timer_start()*
7335timer_start({time}, {callback} [, {options}])
7336 Create a timer and return the timer ID.
7337
7338 {time} is the waiting time in milliseconds. This is the
7339 minimum time before invoking the callback. When the system is
7340 busy or Vim is not waiting for input the time will be longer.
7341
7342 {callback} is the function to call. It can be the name of a
7343 function or a Funcref. It is called with one argument, which
7344 is the timer ID. The callback is only invoked when Vim is
7345 waiting for input.
7346
7347 {options} is a dictionary. Supported entries:
7348 "repeat" Number of times to repeat calling the
Bram Moolenaar81edd172016-04-14 13:51:37 +02007349 callback. -1 means forever.
Bram Moolenaar975b5272016-03-15 23:10:59 +01007350
7351 Example: >
7352 func MyHandler(timer)
7353 echo 'Handler called'
7354 endfunc
7355 let timer = timer_start(500, 'MyHandler',
7356 \ {'repeat': 3})
7357< This will invoke MyHandler() three times at 500 msec
7358 intervals.
7359 {only available when compiled with the |+timers| feature}
7360
Bram Moolenaar03602ec2016-03-20 20:57:45 +01007361timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +02007362 Stop a timer. The timer callback will no longer be invoked.
7363 {timer} is an ID returned by timer_start(), thus it must be a
7364 Number.
Bram Moolenaar03602ec2016-03-20 20:57:45 +01007365
Bram Moolenaar071d4272004-06-13 20:20:40 +00007366tolower({expr}) *tolower()*
7367 The result is a copy of the String given, with all uppercase
7368 characters turned into lowercase (just like applying |gu| to
7369 the string).
7370
7371toupper({expr}) *toupper()*
7372 The result is a copy of the String given, with all lowercase
7373 characters turned into uppercase (just like applying |gU| to
7374 the string).
7375
Bram Moolenaar8299df92004-07-10 09:47:34 +00007376tr({src}, {fromstr}, {tostr}) *tr()*
7377 The result is a copy of the {src} string with all characters
7378 which appear in {fromstr} replaced by the character in that
7379 position in the {tostr} string. Thus the first character in
7380 {fromstr} is translated into the first character in {tostr}
7381 and so on. Exactly like the unix "tr" command.
7382 This code also deals with multibyte characters properly.
7383
7384 Examples: >
7385 echo tr("hello there", "ht", "HT")
7386< returns "Hello THere" >
7387 echo tr("<blob>", "<>", "{}")
7388< returns "{blob}"
7389
Bram Moolenaar446cb832008-06-24 21:56:24 +00007390trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007391 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00007392 equal to {expr} as a |Float| (truncate towards zero).
7393 {expr} must evaluate to a |Float| or a |Number|.
7394 Examples: >
7395 echo trunc(1.456)
7396< 1.0 >
7397 echo trunc(-5.456)
7398< -5.0 >
7399 echo trunc(4.0)
7400< 4.0
7401 {only available when compiled with the |+float| feature}
7402
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007403 *type()*
7404type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00007405 Number: 0
7406 String: 1
7407 Funcref: 2
7408 List: 3
7409 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00007410 Float: 5
Bram Moolenaar705ada12016-01-24 17:56:50 +01007411 Boolean: 6 (v:false and v:true)
7412 None 7 (v:null and v:none)
Bram Moolenaar835dc632016-02-07 14:27:38 +01007413 Job 8
Bram Moolenaar38a55632016-02-15 22:07:32 +01007414 Channel 9
Bram Moolenaar748bf032005-02-02 23:04:36 +00007415 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007416 :if type(myvar) == type(0)
7417 :if type(myvar) == type("")
7418 :if type(myvar) == type(function("tr"))
7419 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00007420 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00007421 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +01007422 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +01007423 :if type(myvar) == type(v:none)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007424
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007425undofile({name}) *undofile()*
7426 Return the name of the undo file that would be used for a file
7427 with name {name} when writing. This uses the 'undodir'
7428 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02007429 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02007430 {name} is always expanded to the full path, since that is what
7431 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02007432 If {name} is empty undofile() returns an empty string, since a
7433 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007434 Useful in combination with |:wundo| and |:rundo|.
7435 When compiled without the +persistent_undo option this always
7436 returns an empty string.
7437
Bram Moolenaara800b422010-06-27 01:15:55 +02007438undotree() *undotree()*
7439 Return the current state of the undo tree in a dictionary with
7440 the following items:
7441 "seq_last" The highest undo sequence number used.
7442 "seq_cur" The sequence number of the current position in
7443 the undo tree. This differs from "seq_last"
7444 when some changes were undone.
7445 "time_cur" Time last used for |:earlier| and related
7446 commands. Use |strftime()| to convert to
7447 something readable.
7448 "save_last" Number of the last file write. Zero when no
7449 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02007450 "save_cur" Number of the current position in the undo
7451 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02007452 "synced" Non-zero when the last undo block was synced.
7453 This happens when waiting from input from the
7454 user. See |undo-blocks|.
7455 "entries" A list of dictionaries with information about
7456 undo blocks.
7457
7458 The first item in the "entries" list is the oldest undo item.
7459 Each List item is a Dictionary with these items:
7460 "seq" Undo sequence number. Same as what appears in
7461 |:undolist|.
7462 "time" Timestamp when the change happened. Use
7463 |strftime()| to convert to something readable.
7464 "newhead" Only appears in the item that is the last one
7465 that was added. This marks the last change
7466 and where further changes will be added.
7467 "curhead" Only appears in the item that is the last one
7468 that was undone. This marks the current
7469 position in the undo tree, the block that will
7470 be used by a redo command. When nothing was
7471 undone after the last change this item will
7472 not appear anywhere.
7473 "save" Only appears on the last block before a file
7474 write. The number is the write count. The
7475 first write has number 1, the last one the
7476 "save_last" mentioned above.
7477 "alt" Alternate entry. This is again a List of undo
7478 blocks. Each item may again have an "alt"
7479 item.
7480
Bram Moolenaar327aa022014-03-25 18:24:23 +01007481uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
7482 Remove second and succeeding copies of repeated adjacent
7483 {list} items in-place. Returns {list}. If you want a list
7484 to remain unmodified make a copy first: >
7485 :let newlist = uniq(copy(mylist))
7486< The default compare function uses the string representation of
7487 each item. For the use of {func} and {dict} see |sort()|.
7488
Bram Moolenaar677ee682005-01-27 14:41:15 +00007489values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007490 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007491 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00007492
7493
Bram Moolenaar071d4272004-06-13 20:20:40 +00007494virtcol({expr}) *virtcol()*
7495 The result is a Number, which is the screen column of the file
7496 position given with {expr}. That is, the last screen position
7497 occupied by the character at that position, when the screen
7498 would be of unlimited width. When there is a <Tab> at the
7499 position, the returned Number will be the column at the end of
7500 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007501 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00007502 For the byte position use |col()|.
7503 For the use of {expr} see |col()|.
7504 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00007505 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007506 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02007507 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007508 When Virtual editing is active in the current mode, a position
7509 beyond the end of the line can be returned. |'virtualedit'|
7510 The accepted positions are:
7511 . the cursor position
7512 $ the end of the cursor line (the result is the
7513 number of displayed characters in the cursor line
7514 plus one)
7515 'x position of mark x (if the mark is not set, 0 is
7516 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01007517 v In Visual mode: the start of the Visual area (the
7518 cursor is the end). When not in Visual mode
7519 returns the cursor position. Differs from |'<| in
7520 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007521 Note that only marks in the current file can be used.
7522 Examples: >
7523 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
7524 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00007525 virtcol("'t") with text " there", with 't at 'h', returns 6
7526< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007527 A more advanced example that echoes the maximum length of
7528 all lines: >
7529 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
7530
Bram Moolenaar071d4272004-06-13 20:20:40 +00007531
7532visualmode([expr]) *visualmode()*
7533 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007534 used in the current buffer. Initially it returns an empty
7535 string, but once Visual mode has been used, it returns "v",
7536 "V", or "<CTRL-V>" (a single CTRL-V character) for
7537 character-wise, line-wise, or block-wise Visual mode
7538 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007539 Example: >
7540 :exe "normal " . visualmode()
7541< This enters the same Visual mode as before. It is also useful
7542 in scripts if you wish to act differently depending on the
7543 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007544 If Visual mode is active, use |mode()| to get the Visual mode
7545 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007546 *non-zero-arg*
7547 If [expr] is supplied and it evaluates to a non-zero Number or
7548 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00007549 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007550 non-empty strings, thus cause the mode to be cleared. A List,
7551 Dictionary or Float is not a Number or String, thus does not
7552 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007553
Bram Moolenaar8738fc12013-02-20 17:59:11 +01007554wildmenumode() *wildmenumode()*
7555 Returns non-zero when the wildmenu is active and zero
7556 otherwise. See 'wildmenu' and 'wildmode'.
7557 This can be used in mappings to handle the 'wildcharm' option
7558 gracefully. (Makes only sense with |mapmode-c| mappings).
7559
7560 For example to make <c-j> work like <down> in wildmode, use: >
7561 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
7562<
7563 (Note, this needs the 'wildcharm' option set appropriately).
7564
7565
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01007566win_findbuf({bufnr}) *win_findbuf()*
7567 Returns a list with window IDs for windows that contain buffer
7568 {bufnr}. When there is none the list is empty.
7569
Bram Moolenaar86edef62016-03-13 18:07:30 +01007570win_getid([{win} [, {tab}]]) *win_getid()*
7571 Get the window ID for the specified window.
7572 When {win} is missing use the current window.
7573 With {win} this is the window number. The top window has
7574 number 1.
7575 Without {tab} use the current tab, otherwise the tab with
7576 number {tab}. The first tab has number one.
7577 Return zero if the window cannot be found.
7578
7579win_gotoid({expr}) *win_gotoid()*
7580 Go to window with ID {expr}. This may also change the current
7581 tabpage.
7582 Return 1 if successful, 0 if the window cannot be found.
7583
Bram Moolenaar03413f42016-04-12 21:07:15 +02007584win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +01007585 Return a list with the tab number and window number of window
7586 with ID {expr}: [tabnr, winnr].
7587 Return [0, 0] if the window cannot be found.
7588
7589win_id2win({expr}) *win_id2win()*
7590 Return the window number of window with ID {expr}.
7591 Return 0 if the window cannot be found in the current tabpage.
7592
Bram Moolenaar071d4272004-06-13 20:20:40 +00007593 *winbufnr()*
7594winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +02007595 associated with window {nr}. {nr} can be the window number or
7596 the window ID.
7597 When {nr} is zero, the number of the buffer in the current
7598 window is returned.
7599 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007600 Example: >
7601 :echo "The file in the current window is " . bufname(winbufnr(0))
7602<
7603 *wincol()*
7604wincol() The result is a Number, which is the virtual column of the
7605 cursor in the window. This is counting screen cells from the
7606 left side of the window. The leftmost column is one.
7607
7608winheight({nr}) *winheight()*
7609 The result is a Number, which is the height of window {nr}.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02007610 {nr} can be the window number or the window ID.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007611 When {nr} is zero, the height of the current window is
7612 returned. When window {nr} doesn't exist, -1 is returned.
7613 An existing window always has a height of zero or more.
7614 Examples: >
7615 :echo "The current window has " . winheight(0) . " lines."
7616<
7617 *winline()*
7618winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00007619 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007620 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00007621 If the cursor was moved the view on the file will be updated
7622 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007623
7624 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007625winnr([{arg}]) The result is a Number, which is the number of the current
7626 window. The top window has number 1.
7627 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007628 last window is returned (the window count). >
7629 let window_count = winnr('$')
7630< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007631 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007632 If there is no previous window or it is in another tab page 0
7633 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007634 The number can be used with |CTRL-W_w| and ":wincmd w"
7635 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007636 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007637
7638 *winrestcmd()*
7639winrestcmd() Returns a sequence of |:resize| commands that should restore
7640 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007641 are opened or closed and the current window and tab page is
7642 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007643 Example: >
7644 :let cmd = winrestcmd()
7645 :call MessWithWindowSizes()
7646 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007647<
7648 *winrestview()*
7649winrestview({dict})
7650 Uses the |Dictionary| returned by |winsaveview()| to restore
7651 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +02007652 Note: The {dict} does not have to contain all values, that are
7653 returned by |winsaveview()|. If values are missing, those
7654 settings won't be restored. So you can use: >
7655 :call winrestview({'curswant': 4})
7656<
7657 This will only set the curswant value (the column the cursor
7658 wants to move on vertical movements) of the cursor to column 5
7659 (yes, that is 5), while all other settings will remain the
7660 same. This is useful, if you set the cursor position manually.
7661
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007662 If you have changed the values the result is unpredictable.
7663 If the window size changed the result won't be the same.
7664
7665 *winsaveview()*
7666winsaveview() Returns a |Dictionary| that contains information to restore
7667 the view of the current window. Use |winrestview()| to
7668 restore the view.
7669 This is useful if you have a mapping that jumps around in the
7670 buffer and you want to go back to the original view.
7671 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00007672 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +02007673 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007674 The return value includes:
7675 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +02007676 col cursor column (Note: the first column
7677 zero, as opposed to what getpos()
7678 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007679 coladd cursor column offset for 'virtualedit'
7680 curswant column for vertical movement
7681 topline first line in the window
7682 topfill filler lines, only in diff mode
7683 leftcol first column displayed
7684 skipcol columns skipped
7685 Note that no option values are saved.
7686
Bram Moolenaar071d4272004-06-13 20:20:40 +00007687
7688winwidth({nr}) *winwidth()*
7689 The result is a Number, which is the width of window {nr}.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02007690 {nr} can be the window number or the window ID.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007691 When {nr} is zero, the width of the current window is
7692 returned. When window {nr} doesn't exist, -1 is returned.
7693 An existing window always has a width of zero or more.
7694 Examples: >
7695 :echo "The current window has " . winwidth(0) . " columns."
7696 :if winwidth(0) <= 50
7697 : exe "normal 50\<C-W>|"
7698 :endif
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02007699< For getting the terminal or screen size, see the 'columns'
7700 option.
7701
7702
Bram Moolenaared767a22016-01-03 22:49:16 +01007703wordcount() *wordcount()*
7704 The result is a dictionary of byte/chars/word statistics for
7705 the current buffer. This is the same info as provided by
7706 |g_CTRL-G|
7707 The return value includes:
7708 bytes Number of bytes in the buffer
7709 chars Number of chars in the buffer
7710 words Number of words in the buffer
7711 cursor_bytes Number of bytes before cursor position
7712 (not in Visual mode)
7713 cursor_chars Number of chars before cursor position
7714 (not in Visual mode)
7715 cursor_words Number of words before cursor position
7716 (not in Visual mode)
7717 visual_bytes Number of bytes visually selected
7718 (only in Visual mode)
7719 visual_chars Number of chars visually selected
7720 (only in Visual mode)
7721 visual_words Number of chars visually selected
7722 (only in Visual mode)
7723
7724
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007725 *writefile()*
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007726writefile({list}, {fname} [, {flags}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007727 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007728 separated with a NL. Each list item must be a String or
7729 Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007730 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007731 not be a NL after the last list item. An empty item at the
7732 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007733
7734 When {flags} contains "a" then append mode is used, lines are
7735 append to the file: >
7736 :call writefile(["foo"], "event.log", "a")
7737 :call writefile(["bar"], "event.log", "a")
7738>
7739< All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007740 Inserting CR characters needs to be done before passing {list}
7741 to writefile().
7742 An existing file is overwritten, if possible.
7743 When the write fails -1 is returned, otherwise 0. There is an
7744 error message if the file can't be created or when writing
7745 fails.
7746 Also see |readfile()|.
7747 To copy a file byte for byte: >
7748 :let fl = readfile("foo", "b")
7749 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007750
7751
7752xor({expr}, {expr}) *xor()*
7753 Bitwise XOR on the two arguments. The arguments are converted
7754 to a number. A List, Dict or Float argument causes an error.
7755 Example: >
7756 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01007757<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007758
Bram Moolenaar071d4272004-06-13 20:20:40 +00007759
7760 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007761There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +000077621. Features that are only supported when they have been enabled when Vim
7763 was compiled |+feature-list|. Example: >
7764 :if has("cindent")
77652. Features that are only supported when certain conditions have been met.
7766 Example: >
7767 :if has("gui_running")
7768< *has-patch*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020077693. Included patches. The "patch123" feature means that patch 123 has been
7770 included. Note that this form does not check the version of Vim, you need
7771 to inspect |v:version| for that.
7772 Example (checking version 6.2.148 or later): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007773 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007774< Note that it's possible for patch 147 to be omitted even though 148 is
7775 included.
7776
77774. Beyond a certain version or at a certain version and including a specific
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007778 patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or
7779 later, or it is version 7.4 and patch 237 was included.
7780 Note that this only works for patch 7.4.237 and later, before that you
7781 need to use the example above that checks v:version. Example: >
7782 :if has("patch-7.4.248")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007783< Note that it's possible for patch 147 to be omitted even though 148 is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007784 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007785
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007786acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007787all_builtin_terms Compiled with all builtin terminals enabled.
7788amiga Amiga version of Vim.
7789arabic Compiled with Arabic support |Arabic|.
7790arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00007791autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007792balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00007793balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794beos BeOS version of Vim.
7795browse Compiled with |:browse| support, and browse() will
7796 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007797browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007798builtin_terms Compiled with some builtin terminals.
7799byte_offset Compiled with support for 'o' in 'statusline'
7800cindent Compiled with 'cindent' support.
7801clientserver Compiled with remote invocation support |clientserver|.
7802clipboard Compiled with 'clipboard' support.
7803cmdline_compl Compiled with |cmdline-completion| support.
7804cmdline_hist Compiled with |cmdline-history| support.
7805cmdline_info Compiled with 'showcmd' and 'ruler' support.
7806comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007807compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007808cryptv Compiled with encryption support |encryption|.
7809cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007810debug Compiled with "DEBUG" defined.
7811dialog_con Compiled with console dialog support.
7812dialog_gui Compiled with GUI dialog support.
7813diff Compiled with |vimdiff| and 'diff' support.
7814digraphs Compiled with support for digraphs.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02007815directx Compiled with support for Direct-X and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007816dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007817dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007818dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007819ebcdic Compiled on a machine with ebcdic character set.
7820emacs_tags Compiled with support for Emacs tags.
7821eval Compiled with expression evaluation support. Always
7822 true, of course!
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007823ex_extra |+ex_extra|, always true now
Bram Moolenaar071d4272004-06-13 20:20:40 +00007824extra_search Compiled with support for |'incsearch'| and
7825 |'hlsearch'|
7826farsi Compiled with Farsi support |farsi|.
7827file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007828filterpipe When 'shelltemp' is off pipes are used for shell
7829 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00007830find_in_path Compiled with support for include file searches
7831 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007832float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007833fname_case Case in file names matters (for Amiga, MS-DOS, and
7834 Windows this is not present).
7835folding Compiled with |folding| support.
7836footer Compiled with GUI footer support. |gui-footer|
7837fork Compiled to use fork()/exec() instead of system().
7838gettext Compiled with message translation |multi-lang|
7839gui Compiled with GUI enabled.
7840gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007841gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007842gui_gtk Compiled with GTK+ GUI (any version).
7843gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +01007844gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007845gui_mac Compiled with Macintosh GUI.
7846gui_motif Compiled with Motif GUI.
7847gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007848gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007849gui_win32 Compiled with MS Windows Win32 GUI.
7850gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007851hangul_input Compiled with Hangul input support. |hangul|
7852iconv Can use iconv() for conversion.
7853insert_expand Compiled with support for CTRL-X expansion commands in
7854 Insert mode.
7855jumplist Compiled with |jumplist| support.
7856keymap Compiled with 'keymap' support.
7857langmap Compiled with 'langmap' support.
7858libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +02007859linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
7860 'breakindent' support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007861lispindent Compiled with support for lisp indenting.
7862listcmds Compiled with commands for the buffer list |:files|
7863 and the argument list |arglist|.
7864localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02007865lua Compiled with Lua interface |Lua|.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01007866mac Any Macintosh version of Vim.
Bram Moolenaarf8df7ad2016-02-16 14:07:40 +01007867macunix Compiled for OS X, with darwin
7868osx Compiled for OS X, with or without darwin
Bram Moolenaar071d4272004-06-13 20:20:40 +00007869menu Compiled with support for |:menu|.
7870mksession Compiled with support for |:mksession|.
7871modify_fname Compiled with file name modifiers. |filename-modifiers|
7872mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007873mouse_dec Compiled with support for Dec terminal mouse.
7874mouse_gpm Compiled with support for gpm (Linux console mouse)
7875mouse_netterm Compiled with support for netterm mouse.
7876mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007877mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02007878mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01007879mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007880mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007881mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00007882multi_byte Compiled with support for 'encoding'
7883multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007884multi_byte_ime Compiled with support for IME input method.
7885multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00007886mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02007887netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007888netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02007889num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007890ole Compiled with OLE automation support for Win32.
7891os2 OS/2 version of Vim.
Bram Moolenaar91c49372016-05-08 09:50:29 +02007892packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007893path_extra Compiled with up/downwards search in 'path' and 'tags'
7894perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02007895persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007896postscript Compiled with PostScript file printing.
7897printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00007898profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02007899python Compiled with Python 2.x interface. |has-python|
7900python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007901qnx QNX version of Vim.
7902quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00007903reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007904rightleft Compiled with 'rightleft' support.
7905ruby Compiled with Ruby interface |ruby|.
7906scrollbind Compiled with 'scrollbind' support.
7907showcmd Compiled with 'showcmd' support.
7908signs Compiled with |:sign| support.
7909smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007910spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00007911startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007912statusline Compiled with support for 'statusline', 'rulerformat'
7913 and special formats of 'titlestring' and 'iconstring'.
7914sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007915syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007916syntax_items There are active syntax highlighting items for the
7917 current buffer.
7918system Compiled to use system() instead of fork()/exec().
7919tag_binary Compiled with binary searching in tags files
7920 |tag-binary-search|.
7921tag_old_static Compiled with support for old static tags
7922 |tag-old-static|.
7923tag_any_white Compiled with support for any white characters in tags
7924 files |tag-any-white|.
7925tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +02007926termguicolors Compiled with true color in terminal support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007927terminfo Compiled with terminfo instead of termcap.
7928termresponse Compiled with support for |t_RV| and |v:termresponse|.
7929textobjects Compiled with support for |text-objects|.
7930tgetent Compiled with tgetent support, able to use a termcap
7931 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +01007932timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007933title Compiled with window title support |'title'|.
7934toolbar Compiled with support for |gui-toolbar|.
7935unix Unix version of Vim.
7936user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007937vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007938vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01007939 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007940viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007941virtualedit Compiled with 'virtualedit' option.
7942visual Compiled with Visual mode.
7943visualextra Compiled with extra Visual mode commands.
7944 |blockwise-operators|.
7945vms VMS version of Vim.
7946vreplace Compiled with |gR| and |gr| commands.
7947wildignore Compiled with 'wildignore' option.
7948wildmenu Compiled with 'wildmenu' option.
Bram Moolenaard58e9292011-02-09 17:07:58 +01007949win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
7950 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007951win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007952win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007953win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007954winaltkeys Compiled with 'winaltkeys' option.
7955windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007956writebackup Compiled with 'writebackup' default on.
7957xfontset Compiled with X fontset support |xfontset|.
7958xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007959xpm Compiled with pixmap support.
7960xpm_w32 Compiled with pixmap support for Win32. (Only for
7961 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007962xsmp Compiled with X session management support.
7963xsmp_interact Compiled with interactive X session management support.
7964xterm_clipboard Compiled with support for xterm clipboard.
7965xterm_save Compiled with support for saving and restoring the
7966 xterm screen.
7967x11 Compiled with X11 support.
7968
7969 *string-match*
7970Matching a pattern in a String
7971
7972A regexp pattern as explained at |pattern| is normally used to find a match in
7973the buffer lines. When a pattern is used to find a match in a String, almost
7974everything works in the same way. The difference is that a String is handled
7975like it is one line. When it contains a "\n" character, this is not seen as a
7976line break for the pattern. It can be matched with a "\n" in the pattern, or
7977with ".". Example: >
7978 :let a = "aaaa\nxxxx"
7979 :echo matchstr(a, "..\n..")
7980 aa
7981 xx
7982 :echo matchstr(a, "a.x")
7983 a
7984 x
7985
7986Don't forget that "^" will only match at the first character of the String and
7987"$" at the last character of the string. They don't match after or before a
7988"\n".
7989
7990==============================================================================
79915. Defining functions *user-functions*
7992
7993New functions can be defined. These can be called just like builtin
7994functions. The function executes a sequence of Ex commands. Normal mode
7995commands can be executed with the |:normal| command.
7996
7997The function name must start with an uppercase letter, to avoid confusion with
7998builtin functions. To prevent from using the same name in different scripts
7999avoid obvious, short names. A good habit is to start the function name with
8000the name of the script, e.g., "HTMLcolor()".
8001
Bram Moolenaar92d640f2005-09-05 22:11:52 +00008002It's also possible to use curly braces, see |curly-braces-names|. And the
8003|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008004
8005 *local-function*
8006A function local to a script must start with "s:". A local script function
8007can only be called from within the script and from functions, user commands
8008and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008009function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00008010instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02008011There are only script-local functions, no buffer-local or window-local
8012functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008013
8014 *:fu* *:function* *E128* *E129* *E123*
8015:fu[nction] List all functions and their arguments.
8016
8017:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008018 {name} can also be a |Dictionary| entry that is a
8019 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008020 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00008021
8022:fu[nction] /{pattern} List functions with a name matching {pattern}.
8023 Example that lists all functions ending with "File": >
8024 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00008025<
8026 *:function-verbose*
8027When 'verbose' is non-zero, listing a function will also display where it was
8028last defined. Example: >
8029
8030 :verbose function SetFileTypeSH
8031 function SetFileTypeSH(name)
8032 Last set from /usr/share/vim/vim-7.0/filetype.vim
8033<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00008034See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00008035
Bram Moolenaarbcb98982014-05-01 14:08:19 +02008036 *E124* *E125* *E853* *E884*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00008037:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008038 Define a new function by the name {name}. The name
8039 must be made of alphanumeric characters and '_', and
Bram Moolenaarbcb98982014-05-01 14:08:19 +02008040 must start with a capital or "s:" (see above). Note
8041 that using "b:" or "g:" is not allowed. (since patch
8042 7.4.260 E884 is given if the function name has a colon
8043 in the name, e.g. for "foo:bar()". Before that patch
8044 no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008045
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008046 {name} can also be a |Dictionary| entry that is a
8047 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008048 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00008049< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008050 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00008051 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008052 result is a |Funcref| to a numbered function. The
8053 function can only be used with a |Funcref| and will be
8054 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008055 *E127* *E122*
8056 When a function by this name already exists and [!] is
8057 not used an error message is given. When [!] is used,
8058 an existing function is silently replaced. Unless it
8059 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008060
8061 For the {arguments} see |function-argument|.
8062
Bram Moolenaar8d043172014-01-23 14:24:41 +01008063 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008064 When the [range] argument is added, the function is
8065 expected to take care of a range itself. The range is
8066 passed as "a:firstline" and "a:lastline". If [range]
8067 is excluded, ":{range}call" will call the function for
8068 each line in the range, with the cursor on the start
8069 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01008070 The cursor is still moved to the first line of the
8071 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01008072 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008073 When the [abort] argument is added, the function will
8074 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01008075 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00008076 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00008077 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00008078 local variable "self" will then be set to the
8079 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008080
Bram Moolenaar446cb832008-06-24 21:56:24 +00008081 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00008082 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00008083 will not be changed by the function. This also
8084 implies that the effect of |:nohlsearch| is undone
8085 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00008086
Bram Moolenaar071d4272004-06-13 20:20:40 +00008087 *:endf* *:endfunction* *E126* *E193*
8088:endf[unction] The end of a function definition. Must be on a line
8089 by its own, without other commands.
8090
8091 *:delf* *:delfunction* *E130* *E131*
8092:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008093 {name} can also be a |Dictionary| entry that is a
8094 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008095 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00008096< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008097 function is deleted if there are no more references to
8098 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008099 *:retu* *:return* *E133*
8100:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
8101 evaluated and returned as the result of the function.
8102 If "[expr]" is not given, the number 0 is returned.
8103 When a function ends without an explicit ":return",
8104 the number 0 is returned.
8105 Note that there is no check for unreachable lines,
8106 thus there is no warning if commands follow ":return".
8107
8108 If the ":return" is used after a |:try| but before the
8109 matching |:finally| (if present), the commands
8110 following the ":finally" up to the matching |:endtry|
8111 are executed first. This process applies to all
8112 nested ":try"s inside the function. The function
8113 returns at the outermost ":endtry".
8114
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008115 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008116An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008117be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008118 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008119Up to 20 arguments can be given, separated by commas. After the named
8120arguments an argument "..." can be specified, which means that more arguments
8121may optionally be following. In the function the extra arguments can be used
8122as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008123can be 0). "a:000" is set to a |List| that contains these arguments. Note
8124that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008125 *E742*
8126The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008127However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008128Thus you can pass a |List| to a function and have the function add an item to
8129it. If you want to make sure the function cannot change a |List| or
8130|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008131
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008132When not using "...", the number of arguments in a function call must be equal
8133to the number of named arguments. When using "...", the number of arguments
8134may be larger.
8135
8136It is also possible to define a function without any arguments. You must
8137still supply the () then. The body of the function follows in the next lines,
8138until the matching |:endfunction|. It is allowed to define another function
8139inside a function body.
8140
8141 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008142Inside a function variables can be used. These are local variables, which
8143will disappear when the function returns. Global variables need to be
8144accessed with "g:".
8145
8146Example: >
8147 :function Table(title, ...)
8148 : echohl Title
8149 : echo a:title
8150 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00008151 : echo a:0 . " items:"
8152 : for s in a:000
8153 : echon ' ' . s
8154 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00008155 :endfunction
8156
8157This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00008158 call Table("Table", "line1", "line2")
8159 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008160
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008161To return more than one value, return a |List|: >
8162 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008163 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008164 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008165 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008166 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008167 :endfunction
8168
8169This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008170 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008171 :if success == "ok"
8172 : echo div
8173 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008174<
Bram Moolenaar39f05632006-03-19 22:15:26 +00008175 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008176:[range]cal[l] {name}([arguments])
8177 Call a function. The name of the function and its arguments
8178 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008179 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008180 Without a range and for functions that accept a range, the
8181 function is called once. When a range is given the cursor is
8182 positioned at the start of the first line before executing the
8183 function.
8184 When a range is given and the function doesn't handle it
8185 itself, the function is executed for each line in the range,
8186 with the cursor in the first column of that line. The cursor
8187 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00008188 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00008189 this works:
8190 *function-range-example* >
8191 :function Mynumber(arg)
8192 : echo line(".") . " " . a:arg
8193 :endfunction
8194 :1,5call Mynumber(getline("."))
8195<
8196 The "a:firstline" and "a:lastline" are defined anyway, they
8197 can be used to do something different at the start or end of
8198 the range.
8199
8200 Example of a function that handles the range itself: >
8201
8202 :function Cont() range
8203 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
8204 :endfunction
8205 :4,8call Cont()
8206<
8207 This function inserts the continuation character "\" in front
8208 of all the lines in the range, except the first one.
8209
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008210 When the function returns a composite value it can be further
8211 dereferenced, but the range will not be used then. Example: >
8212 :4,8call GetDict().method()
8213< Here GetDict() gets the range but method() does not.
8214
Bram Moolenaar071d4272004-06-13 20:20:40 +00008215 *E132*
8216The recursiveness of user functions is restricted with the |'maxfuncdepth'|
8217option.
8218
Bram Moolenaar7c626922005-02-07 22:01:03 +00008219
8220AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008221 *autoload-functions*
8222When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00008223only when they are used. There are two methods: with an autocommand and with
8224the "autoload" directory in 'runtimepath'.
8225
8226
8227Using an autocommand ~
8228
Bram Moolenaar05159a02005-02-26 23:04:13 +00008229This is introduced in the user manual, section |41.14|.
8230
Bram Moolenaar7c626922005-02-07 22:01:03 +00008231The autocommand is useful if you have a plugin that is a long Vim script file.
8232You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008233That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00008234again, setting a variable to skip the |:finish| command.
8235
8236Use the FuncUndefined autocommand event with a pattern that matches the
8237function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008238
8239 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
8240
8241The file "~/vim/bufnetfuncs.vim" should then define functions that start with
8242"BufNet". Also see |FuncUndefined|.
8243
Bram Moolenaar7c626922005-02-07 22:01:03 +00008244
8245Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008246 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008247This is introduced in the user manual, section |41.15|.
8248
Bram Moolenaar7c626922005-02-07 22:01:03 +00008249Using a script in the "autoload" directory is simpler, but requires using
8250exactly the right file name. A function that can be autoloaded has a name
8251like this: >
8252
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008253 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008254
8255When such a function is called, and it is not defined yet, Vim will search the
8256"autoload" directories in 'runtimepath' for a script file called
8257"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
8258then define the function like this: >
8259
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008260 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008261 echo "Done!"
8262 endfunction
8263
Bram Moolenaar60a795a2005-09-16 21:55:43 +00008264The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00008265exactly, and the defined function must have the name exactly as it will be
8266called.
8267
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008268It is possible to use subdirectories. Every # in the function name works like
8269a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00008270
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008271 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008272
8273Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
8274
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008275This also works when reading a variable that has not been set yet: >
8276
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008277 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008278
Bram Moolenaara5792f52005-11-23 21:25:05 +00008279However, when the autoload script was already loaded it won't be loaded again
8280for an unknown variable.
8281
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008282When assigning a value to such a variable nothing special happens. This can
8283be used to pass settings to the autoload script before it's loaded: >
8284
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008285 :let foo#bar#toggle = 1
8286 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008287
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008288Note that when you make a mistake and call a function that is supposed to be
8289defined in an autoload script, but the script doesn't actually define the
8290function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008291And you will get an error message every time.
8292
8293Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008294other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008295Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00008296
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008297Hint: If you distribute a bunch of scripts you can pack them together with the
8298|vimball| utility. Also read the user manual |distribute-script|.
8299
Bram Moolenaar071d4272004-06-13 20:20:40 +00008300==============================================================================
83016. Curly braces names *curly-braces-names*
8302
Bram Moolenaar84f72352012-03-11 15:57:40 +01008303In most places where you can use a variable, you can use a "curly braces name"
8304variable. This is a regular variable name with one or more expressions
8305wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008306 my_{adjective}_variable
8307
8308When Vim encounters this, it evaluates the expression inside the braces, puts
8309that in place of the expression, and re-interprets the whole as a variable
8310name. So in the above example, if the variable "adjective" was set to
8311"noisy", then the reference would be to "my_noisy_variable", whereas if
8312"adjective" was set to "quiet", then it would be to "my_quiet_variable".
8313
8314One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00008315value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008316 echo my_{&background}_message
8317
8318would output the contents of "my_dark_message" or "my_light_message" depending
8319on the current value of 'background'.
8320
8321You can use multiple brace pairs: >
8322 echo my_{adverb}_{adjective}_message
8323..or even nest them: >
8324 echo my_{ad{end_of_word}}_message
8325where "end_of_word" is either "verb" or "jective".
8326
8327However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008328variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008329 :let foo='a + b'
8330 :echo c{foo}d
8331.. since the result of expansion is "ca + bd", which is not a variable name.
8332
8333 *curly-braces-function-names*
8334You can call and define functions by an evaluated name in a similar way.
8335Example: >
8336 :let func_end='whizz'
8337 :call my_func_{func_end}(parameter)
8338
8339This would call the function "my_func_whizz(parameter)".
8340
Bram Moolenaar84f72352012-03-11 15:57:40 +01008341This does NOT work: >
8342 :let i = 3
8343 :let @{i} = '' " error
8344 :echo @{i} " error
8345
Bram Moolenaar071d4272004-06-13 20:20:40 +00008346==============================================================================
83477. Commands *expression-commands*
8348
8349:let {var-name} = {expr1} *:let* *E18*
8350 Set internal variable {var-name} to the result of the
8351 expression {expr1}. The variable will get the type
8352 from the {expr}. If {var-name} didn't exist yet, it
8353 is created.
8354
Bram Moolenaar13065c42005-01-08 16:08:21 +00008355:let {var-name}[{idx}] = {expr1} *E689*
8356 Set a list item to the result of the expression
8357 {expr1}. {var-name} must refer to a list and {idx}
8358 must be a valid index in that list. For nested list
8359 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008360 This cannot be used to add an item to a |List|.
8361 This cannot be used to set a byte in a String. You
8362 can do that like this: >
8363 :let var = var[0:2] . 'X' . var[4:]
8364<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008365 *E711* *E719*
8366:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008367 Set a sequence of items in a |List| to the result of
8368 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008369 correct number of items.
8370 {idx1} can be omitted, zero is used instead.
8371 {idx2} can be omitted, meaning the end of the list.
8372 When the selected range of items is partly past the
8373 end of the list, items will be added.
8374
Bram Moolenaar748bf032005-02-02 23:04:36 +00008375 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008376:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
8377:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
8378:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
8379 These fail if {var} was not set yet and when the type
8380 of {var} and {expr1} don't fit the operator.
8381
8382
Bram Moolenaar071d4272004-06-13 20:20:40 +00008383:let ${env-name} = {expr1} *:let-environment* *:let-$*
8384 Set environment variable {env-name} to the result of
8385 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008386:let ${env-name} .= {expr1}
8387 Append {expr1} to the environment variable {env-name}.
8388 If the environment variable didn't exist yet this
8389 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008390
8391:let @{reg-name} = {expr1} *:let-register* *:let-@*
8392 Write the result of the expression {expr1} in register
8393 {reg-name}. {reg-name} must be a single letter, and
8394 must be the name of a writable register (see
8395 |registers|). "@@" can be used for the unnamed
8396 register, "@/" for the search pattern.
8397 If the result of {expr1} ends in a <CR> or <NL>, the
8398 register will be linewise, otherwise it will be set to
8399 characterwise.
8400 This can be used to clear the last search pattern: >
8401 :let @/ = ""
8402< This is different from searching for an empty string,
8403 that would match everywhere.
8404
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008405:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00008406 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008407 register was empty it's like setting it to {expr1}.
8408
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008409:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008410 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008411 expression {expr1}. A String or Number value is
8412 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008413 For an option local to a window or buffer the effect
8414 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00008415 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008416 Example: >
8417 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00008418
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008419:let &{option-name} .= {expr1}
8420 For a string option: Append {expr1} to the value.
8421 Does not insert a comma like |:set+=|.
8422
8423:let &{option-name} += {expr1}
8424:let &{option-name} -= {expr1}
8425 For a number or boolean option: Add or subtract
8426 {expr1}.
8427
Bram Moolenaar071d4272004-06-13 20:20:40 +00008428:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008429:let &l:{option-name} .= {expr1}
8430:let &l:{option-name} += {expr1}
8431:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008432 Like above, but only set the local value of an option
8433 (if there is one). Works like |:setlocal|.
8434
8435:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008436:let &g:{option-name} .= {expr1}
8437:let &g:{option-name} += {expr1}
8438:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008439 Like above, but only set the global value of an option
8440 (if there is one). Works like |:setglobal|.
8441
Bram Moolenaar13065c42005-01-08 16:08:21 +00008442:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008443 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008444 the list is assigned to {name1}, the second item to
8445 {name2}, etc.
8446 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008447 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008448 Each name can be one of the items of the ":let"
8449 command as mentioned above.
8450 Example: >
8451 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008452< Detail: {expr1} is evaluated first, then the
8453 assignments are done in sequence. This matters if
8454 {name2} depends on {name1}. Example: >
8455 :let x = [0, 1]
8456 :let i = 0
8457 :let [i, x[i]] = [1, 2]
8458 :echo x
8459< The result is [0, 2].
8460
8461:let [{name1}, {name2}, ...] .= {expr1}
8462:let [{name1}, {name2}, ...] += {expr1}
8463:let [{name1}, {name2}, ...] -= {expr1}
8464 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008465 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008466
8467:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008468 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008469 items than there are names. A list of the remaining
8470 items is assigned to {lastname}. If there are no
8471 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008472 Example: >
8473 :let [a, b; rest] = ["aval", "bval", 3, 4]
8474<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008475:let [{name}, ..., ; {lastname}] .= {expr1}
8476:let [{name}, ..., ; {lastname}] += {expr1}
8477:let [{name}, ..., ; {lastname}] -= {expr1}
8478 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008479 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02008480
8481 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008482:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008483 variable names may be given. Special names recognized
8484 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00008485 g: global variables
8486 b: local buffer variables
8487 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008488 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00008489 s: script-local variables
8490 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008491 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008492
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008493:let List the values of all variables. The type of the
8494 variable is indicated before the value:
8495 <nothing> String
8496 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008497 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00008498
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008499
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008500:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008501 Remove the internal variable {name}. Several variable
8502 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008503 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008504 With [!] no error message is given for non-existing
8505 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008506 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008507 :unlet list[3] " remove fourth item
8508 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008509< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008510 :unlet dict['two']
8511 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00008512< This is especially useful to clean up used global
8513 variables and script-local variables (these are not
8514 deleted when the script ends). Function-local
8515 variables are automatically deleted when the function
8516 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008517
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008518:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
8519 Lock the internal variable {name}. Locking means that
8520 it can no longer be changed (until it is unlocked).
8521 A locked variable can be deleted: >
8522 :lockvar v
8523 :let v = 'asdf' " fails!
8524 :unlet v
8525< *E741*
8526 If you try to change a locked variable you get an
Bram Moolenaar8a94d872015-01-25 13:02:57 +01008527 error message: "E741: Value is locked: {name}"
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008528
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008529 [depth] is relevant when locking a |List| or
8530 |Dictionary|. It specifies how deep the locking goes:
8531 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008532 cannot add or remove items, but can
8533 still change their values.
8534 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008535 the items. If an item is a |List| or
8536 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008537 items, but can still change the
8538 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008539 3 Like 2 but for the |List| /
8540 |Dictionary| in the |List| /
8541 |Dictionary|, one level deeper.
8542 The default [depth] is 2, thus when {name} is a |List|
8543 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008544 *E743*
8545 For unlimited depth use [!] and omit [depth].
8546 However, there is a maximum depth of 100 to catch
8547 loops.
8548
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008549 Note that when two variables refer to the same |List|
8550 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008551 locked when used through the other variable.
8552 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008553 :let l = [0, 1, 2, 3]
8554 :let cl = l
8555 :lockvar l
8556 :let cl[1] = 99 " won't work!
8557< You may want to make a copy of a list to avoid this.
8558 See |deepcopy()|.
8559
8560
8561:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
8562 Unlock the internal variable {name}. Does the
8563 opposite of |:lockvar|.
8564
8565
Bram Moolenaar071d4272004-06-13 20:20:40 +00008566:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
8567:en[dif] Execute the commands until the next matching ":else"
8568 or ":endif" if {expr1} evaluates to non-zero.
8569
8570 From Vim version 4.5 until 5.0, every Ex command in
8571 between the ":if" and ":endif" is ignored. These two
8572 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01008573 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00008574 that any ":else" or ":elseif" was ignored, the "else"
8575 part was not executed either.
8576
8577 You can use this to remain compatible with older
8578 versions: >
8579 :if version >= 500
8580 : version-5-specific-commands
8581 :endif
8582< The commands still need to be parsed to find the
8583 "endif". Sometimes an older Vim has a problem with a
8584 new command. For example, ":silent" is recognized as
8585 a ":substitute" command. In that case ":execute" can
8586 avoid problems: >
8587 :if version >= 600
8588 : execute "silent 1,$delete"
8589 :endif
8590<
8591 NOTE: The ":append" and ":insert" commands don't work
8592 properly in between ":if" and ":endif".
8593
8594 *:else* *:el* *E581* *E583*
8595:el[se] Execute the commands until the next matching ":else"
8596 or ":endif" if they previously were not being
8597 executed.
8598
8599 *:elseif* *:elsei* *E582* *E584*
8600:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
8601 is no extra ":endif".
8602
8603:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008604 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008605:endw[hile] Repeat the commands between ":while" and ":endwhile",
8606 as long as {expr1} evaluates to non-zero.
8607 When an error is detected from a command inside the
8608 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00008609 Example: >
8610 :let lnum = 1
8611 :while lnum <= line("$")
8612 :call FixLine(lnum)
8613 :let lnum = lnum + 1
8614 :endwhile
8615<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008616 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00008617 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008618
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008619:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00008620:endfo[r] *:endfo* *:endfor*
8621 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008622 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008623 value of each item.
8624 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00008625 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00008626 Changing {list} inside the loop affects what items are
8627 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008628 :for item in copy(mylist)
8629< When not making a copy, Vim stores a reference to the
8630 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00008631 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008632 removed without effect. Removing any later item means
8633 it will not be found. Thus the following example
8634 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008635 for item in mylist
8636 call remove(mylist, 0)
8637 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008638< Note that reordering the list (e.g., with sort() or
8639 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +00008640
Bram Moolenaar12805862005-01-05 22:16:17 +00008641:for [{var1}, {var2}, ...] in {listlist}
8642:endfo[r]
8643 Like ":for" above, but each item in {listlist} must be
8644 a list, of which each item is assigned to {var1},
8645 {var2}, etc. Example: >
8646 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
8647 :echo getline(lnum)[col]
8648 :endfor
8649<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008650 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00008651:con[tinue] When used inside a ":while" or ":for" loop, jumps back
8652 to the start of the loop.
8653 If it is used after a |:try| inside the loop but
8654 before the matching |:finally| (if present), the
8655 commands following the ":finally" up to the matching
8656 |:endtry| are executed first. This process applies to
8657 all nested ":try"s inside the loop. The outermost
8658 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008659
8660 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00008661:brea[k] When used inside a ":while" or ":for" loop, skips to
8662 the command after the matching ":endwhile" or
8663 ":endfor".
8664 If it is used after a |:try| inside the loop but
8665 before the matching |:finally| (if present), the
8666 commands following the ":finally" up to the matching
8667 |:endtry| are executed first. This process applies to
8668 all nested ":try"s inside the loop. The outermost
8669 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008670
8671:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
8672:endt[ry] Change the error handling for the commands between
8673 ":try" and ":endtry" including everything being
8674 executed across ":source" commands, function calls,
8675 or autocommand invocations.
8676
8677 When an error or interrupt is detected and there is
8678 a |:finally| command following, execution continues
8679 after the ":finally". Otherwise, or when the
8680 ":endtry" is reached thereafter, the next
8681 (dynamically) surrounding ":try" is checked for
8682 a corresponding ":finally" etc. Then the script
8683 processing is terminated. (Whether a function
8684 definition has an "abort" argument does not matter.)
8685 Example: >
8686 :try | edit too much | finally | echo "cleanup" | endtry
8687 :echo "impossible" " not reached, script terminated above
8688<
8689 Moreover, an error or interrupt (dynamically) inside
8690 ":try" and ":endtry" is converted to an exception. It
8691 can be caught as if it were thrown by a |:throw|
8692 command (see |:catch|). In this case, the script
8693 processing is not terminated.
8694
8695 The value "Vim:Interrupt" is used for an interrupt
8696 exception. An error in a Vim command is converted
8697 to a value of the form "Vim({command}):{errmsg}",
8698 other errors are converted to a value of the form
8699 "Vim:{errmsg}". {command} is the full command name,
8700 and {errmsg} is the message that is displayed if the
8701 error exception is not caught, always beginning with
8702 the error number.
8703 Examples: >
8704 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
8705 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
8706<
8707 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008708:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008709 |:finally|, or |:endtry| that belongs to the same
8710 |:try| as the ":catch" are executed when an exception
8711 matching {pattern} is being thrown and has not yet
8712 been caught by a previous ":catch". Otherwise, these
8713 commands are skipped.
8714 When {pattern} is omitted all errors are caught.
8715 Examples: >
8716 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
8717 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
8718 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
8719 :catch /^Vim(write):/ " catch all errors in :write
8720 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
8721 :catch /my-exception/ " catch user exception
8722 :catch /.*/ " catch everything
8723 :catch " same as /.*/
8724<
8725 Another character can be used instead of / around the
8726 {pattern}, so long as it does not have a special
8727 meaning (e.g., '|' or '"') and doesn't occur inside
8728 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02008729 Information about the exception is available in
8730 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008731 NOTE: It is not reliable to ":catch" the TEXT of
8732 an error message because it may vary in different
8733 locales.
8734
8735 *:fina* *:finally* *E606* *E607*
8736:fina[lly] The following commands until the matching |:endtry|
8737 are executed whenever the part between the matching
8738 |:try| and the ":finally" is left: either by falling
8739 through to the ":finally" or by a |:continue|,
8740 |:break|, |:finish|, or |:return|, or by an error or
8741 interrupt or exception (see |:throw|).
8742
8743 *:th* *:throw* *E608*
8744:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
8745 If the ":throw" is used after a |:try| but before the
8746 first corresponding |:catch|, commands are skipped
8747 until the first ":catch" matching {expr1} is reached.
8748 If there is no such ":catch" or if the ":throw" is
8749 used after a ":catch" but before the |:finally|, the
8750 commands following the ":finally" (if present) up to
8751 the matching |:endtry| are executed. If the ":throw"
8752 is after the ":finally", commands up to the ":endtry"
8753 are skipped. At the ":endtry", this process applies
8754 again for the next dynamically surrounding ":try"
8755 (which may be found in a calling function or sourcing
8756 script), until a matching ":catch" has been found.
8757 If the exception is not caught, the command processing
8758 is terminated.
8759 Example: >
8760 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01008761< Note that "catch" may need to be on a separate line
8762 for when an error causes the parsing to skip the whole
8763 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008764
8765 *:ec* *:echo*
8766:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
8767 first {expr1} starts on a new line.
8768 Also see |:comment|.
8769 Use "\n" to start a new line. Use "\r" to move the
8770 cursor to the first column.
8771 Uses the highlighting set by the |:echohl| command.
8772 Cannot be followed by a comment.
8773 Example: >
8774 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008775< *:echo-redraw*
8776 A later redraw may make the message disappear again.
8777 And since Vim mostly postpones redrawing until it's
8778 finished with a sequence of commands this happens
8779 quite often. To avoid that a command from before the
8780 ":echo" causes a redraw afterwards (redraws are often
8781 postponed until you type something), force a redraw
8782 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008783 :new | redraw | echo "there is a new window"
8784<
8785 *:echon*
8786:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
8787 |:comment|.
8788 Uses the highlighting set by the |:echohl| command.
8789 Cannot be followed by a comment.
8790 Example: >
8791 :echon "the value of 'shell' is " &shell
8792<
8793 Note the difference between using ":echo", which is a
8794 Vim command, and ":!echo", which is an external shell
8795 command: >
8796 :!echo % --> filename
8797< The arguments of ":!" are expanded, see |:_%|. >
8798 :!echo "%" --> filename or "filename"
8799< Like the previous example. Whether you see the double
8800 quotes or not depends on your 'shell'. >
8801 :echo % --> nothing
8802< The '%' is an illegal character in an expression. >
8803 :echo "%" --> %
8804< This just echoes the '%' character. >
8805 :echo expand("%") --> filename
8806< This calls the expand() function to expand the '%'.
8807
8808 *:echoh* *:echohl*
8809:echoh[l] {name} Use the highlight group {name} for the following
8810 |:echo|, |:echon| and |:echomsg| commands. Also used
8811 for the |input()| prompt. Example: >
8812 :echohl WarningMsg | echo "Don't panic!" | echohl None
8813< Don't forget to set the group back to "None",
8814 otherwise all following echo's will be highlighted.
8815
8816 *:echom* *:echomsg*
8817:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
8818 message in the |message-history|.
8819 Spaces are placed between the arguments as with the
8820 |:echo| command. But unprintable characters are
8821 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008822 The parsing works slightly different from |:echo|,
8823 more like |:execute|. All the expressions are first
8824 evaluated and concatenated before echoing anything.
8825 The expressions must evaluate to a Number or String, a
8826 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008827 Uses the highlighting set by the |:echohl| command.
8828 Example: >
8829 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008830< See |:echo-redraw| to avoid the message disappearing
8831 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008832 *:echoe* *:echoerr*
8833:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
8834 message in the |message-history|. When used in a
8835 script or function the line number will be added.
8836 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008837 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008838 the message is raised as an error exception instead
8839 (see |try-echoerr|).
8840 Example: >
8841 :echoerr "This script just failed!"
8842< If you just want a highlighted message use |:echohl|.
8843 And to get a beep: >
8844 :exe "normal \<Esc>"
8845<
8846 *:exe* *:execute*
8847:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008848 of {expr1} as an Ex command.
8849 Multiple arguments are concatenated, with a space in
8850 between. To avoid the extra space use the "."
8851 operator to concatenate strings into one argument.
8852 {expr1} is used as the processed command, command line
8853 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008854 Cannot be followed by a comment.
8855 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008856 :execute "buffer" nextbuf
8857 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008858<
8859 ":execute" can be used to append a command to commands
8860 that don't accept a '|'. Example: >
8861 :execute '!ls' | echo "theend"
8862
8863< ":execute" is also a nice way to avoid having to type
8864 control characters in a Vim script for a ":normal"
8865 command: >
8866 :execute "normal ixxx\<Esc>"
8867< This has an <Esc> character, see |expr-string|.
8868
Bram Moolenaar446cb832008-06-24 21:56:24 +00008869 Be careful to correctly escape special characters in
8870 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008871 for Vim commands, |shellescape()| for |:!| commands.
8872 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00008873 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +01008874 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00008875<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008876 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01008877 starting or ending "if", "while" and "for" does not
8878 always work, because when commands are skipped the
8879 ":execute" is not evaluated and Vim loses track of
8880 where blocks start and end. Also "break" and
8881 "continue" should not be inside ":execute".
8882 This example does not work, because the ":execute" is
8883 not evaluated and Vim does not see the "while", and
8884 gives an error for finding an ":endwhile": >
8885 :if 0
8886 : execute 'while i > 5'
8887 : echo "test"
8888 : endwhile
8889 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00008890<
8891 It is allowed to have a "while" or "if" command
8892 completely in the executed string: >
8893 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
8894<
8895
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008896 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008897 ":execute", ":echo" and ":echon" cannot be followed by
8898 a comment directly, because they see the '"' as the
8899 start of a string. But, you can use '|' followed by a
8900 comment. Example: >
8901 :echo "foo" | "this is a comment
8902
8903==============================================================================
89048. Exception handling *exception-handling*
8905
8906The Vim script language comprises an exception handling feature. This section
8907explains how it can be used in a Vim script.
8908
8909Exceptions may be raised by Vim on an error or on interrupt, see
8910|catch-errors| and |catch-interrupt|. You can also explicitly throw an
8911exception by using the ":throw" command, see |throw-catch|.
8912
8913
8914TRY CONDITIONALS *try-conditionals*
8915
8916Exceptions can be caught or can cause cleanup code to be executed. You can
8917use a try conditional to specify catch clauses (that catch exceptions) and/or
8918a finally clause (to be executed for cleanup).
8919 A try conditional begins with a |:try| command and ends at the matching
8920|:endtry| command. In between, you can use a |:catch| command to start
8921a catch clause, or a |:finally| command to start a finally clause. There may
8922be none or multiple catch clauses, but there is at most one finally clause,
8923which must not be followed by any catch clauses. The lines before the catch
8924clauses and the finally clause is called a try block. >
8925
8926 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008927 : ...
8928 : ... TRY BLOCK
8929 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008930 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008931 : ...
8932 : ... CATCH CLAUSE
8933 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008934 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008935 : ...
8936 : ... CATCH CLAUSE
8937 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008938 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00008939 : ...
8940 : ... FINALLY CLAUSE
8941 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008942 :endtry
8943
8944The try conditional allows to watch code for exceptions and to take the
8945appropriate actions. Exceptions from the try block may be caught. Exceptions
8946from the try block and also the catch clauses may cause cleanup actions.
8947 When no exception is thrown during execution of the try block, the control
8948is transferred to the finally clause, if present. After its execution, the
8949script continues with the line following the ":endtry".
8950 When an exception occurs during execution of the try block, the remaining
8951lines in the try block are skipped. The exception is matched against the
8952patterns specified as arguments to the ":catch" commands. The catch clause
8953after the first matching ":catch" is taken, other catch clauses are not
8954executed. The catch clause ends when the next ":catch", ":finally", or
8955":endtry" command is reached - whatever is first. Then, the finally clause
8956(if present) is executed. When the ":endtry" is reached, the script execution
8957continues in the following line as usual.
8958 When an exception that does not match any of the patterns specified by the
8959":catch" commands is thrown in the try block, the exception is not caught by
8960that try conditional and none of the catch clauses is executed. Only the
8961finally clause, if present, is taken. The exception pends during execution of
8962the finally clause. It is resumed at the ":endtry", so that commands after
8963the ":endtry" are not executed and the exception might be caught elsewhere,
8964see |try-nesting|.
8965 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008966remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00008967not matched against the patterns in any of the ":catch" commands of the same
8968try conditional and none of its catch clauses is taken. If there is, however,
8969a finally clause, it is executed, and the exception pends during its
8970execution. The commands following the ":endtry" are not executed. The new
8971exception might, however, be caught elsewhere, see |try-nesting|.
8972 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00008973thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008974clause has been taken because of an exception from the try block or one of the
8975catch clauses, the original (pending) exception is discarded. The commands
8976following the ":endtry" are not executed, and the exception from the finally
8977clause is propagated and can be caught elsewhere, see |try-nesting|.
8978
8979The finally clause is also executed, when a ":break" or ":continue" for
8980a ":while" loop enclosing the complete try conditional is executed from the
8981try block or a catch clause. Or when a ":return" or ":finish" is executed
8982from the try block or a catch clause of a try conditional in a function or
8983sourced script, respectively. The ":break", ":continue", ":return", or
8984":finish" pends during execution of the finally clause and is resumed when the
8985":endtry" is reached. It is, however, discarded when an exception is thrown
8986from the finally clause.
8987 When a ":break" or ":continue" for a ":while" loop enclosing the complete
8988try conditional or when a ":return" or ":finish" is encountered in the finally
8989clause, the rest of the finally clause is skipped, and the ":break",
8990":continue", ":return" or ":finish" is executed as usual. If the finally
8991clause has been taken because of an exception or an earlier ":break",
8992":continue", ":return", or ":finish" from the try block or a catch clause,
8993this pending exception or command is discarded.
8994
8995For examples see |throw-catch| and |try-finally|.
8996
8997
8998NESTING OF TRY CONDITIONALS *try-nesting*
8999
9000Try conditionals can be nested arbitrarily. That is, a complete try
9001conditional can be put into the try block, a catch clause, or the finally
9002clause of another try conditional. If the inner try conditional does not
9003catch an exception thrown in its try block or throws a new exception from one
9004of its catch clauses or its finally clause, the outer try conditional is
9005checked according to the rules above. If the inner try conditional is in the
9006try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00009007otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00009008nesting, whether the inner try conditional is directly contained in the outer
9009one, or whether the outer one sources a script or calls a function containing
9010the inner try conditional.
9011
9012When none of the active try conditionals catches an exception, just their
9013finally clauses are executed. Thereafter, the script processing terminates.
9014An error message is displayed in case of an uncaught exception explicitly
9015thrown by a ":throw" command. For uncaught error and interrupt exceptions
9016implicitly raised by Vim, the error message(s) or interrupt message are shown
9017as usual.
9018
9019For examples see |throw-catch|.
9020
9021
9022EXAMINING EXCEPTION HANDLING CODE *except-examine*
9023
9024Exception handling code can get tricky. If you are in doubt what happens, set
9025'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
9026script file. Then you see when an exception is thrown, discarded, caught, or
9027finished. When using a verbosity level of at least 14, things pending in
9028a finally clause are also shown. This information is also given in debug mode
9029(see |debug-scripts|).
9030
9031
9032THROWING AND CATCHING EXCEPTIONS *throw-catch*
9033
9034You can throw any number or string as an exception. Use the |:throw| command
9035and pass the value to be thrown as argument: >
9036 :throw 4711
9037 :throw "string"
9038< *throw-expression*
9039You can also specify an expression argument. The expression is then evaluated
9040first, and the result is thrown: >
9041 :throw 4705 + strlen("string")
9042 :throw strpart("strings", 0, 6)
9043
9044An exception might be thrown during evaluation of the argument of the ":throw"
9045command. Unless it is caught there, the expression evaluation is abandoned.
9046The ":throw" command then does not throw a new exception.
9047 Example: >
9048
9049 :function! Foo(arg)
9050 : try
9051 : throw a:arg
9052 : catch /foo/
9053 : endtry
9054 : return 1
9055 :endfunction
9056 :
9057 :function! Bar()
9058 : echo "in Bar"
9059 : return 4710
9060 :endfunction
9061 :
9062 :throw Foo("arrgh") + Bar()
9063
9064This throws "arrgh", and "in Bar" is not displayed since Bar() is not
9065executed. >
9066 :throw Foo("foo") + Bar()
9067however displays "in Bar" and throws 4711.
9068
9069Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00009070abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009071exception is then propagated to the caller of the command.
9072 Example: >
9073
9074 :if Foo("arrgh")
9075 : echo "then"
9076 :else
9077 : echo "else"
9078 :endif
9079
9080Here neither of "then" or "else" is displayed.
9081
9082 *catch-order*
9083Exceptions can be caught by a try conditional with one or more |:catch|
9084commands, see |try-conditionals|. The values to be caught by each ":catch"
9085command can be specified as a pattern argument. The subsequent catch clause
9086gets executed when a matching exception is caught.
9087 Example: >
9088
9089 :function! Foo(value)
9090 : try
9091 : throw a:value
9092 : catch /^\d\+$/
9093 : echo "Number thrown"
9094 : catch /.*/
9095 : echo "String thrown"
9096 : endtry
9097 :endfunction
9098 :
9099 :call Foo(0x1267)
9100 :call Foo('string')
9101
9102The first call to Foo() displays "Number thrown", the second "String thrown".
9103An exception is matched against the ":catch" commands in the order they are
9104specified. Only the first match counts. So you should place the more
9105specific ":catch" first. The following order does not make sense: >
9106
9107 : catch /.*/
9108 : echo "String thrown"
9109 : catch /^\d\+$/
9110 : echo "Number thrown"
9111
9112The first ":catch" here matches always, so that the second catch clause is
9113never taken.
9114
9115 *throw-variables*
9116If you catch an exception by a general pattern, you may access the exact value
9117in the variable |v:exception|: >
9118
9119 : catch /^\d\+$/
9120 : echo "Number thrown. Value is" v:exception
9121
9122You may also be interested where an exception was thrown. This is stored in
9123|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
9124exception most recently caught as long it is not finished.
9125 Example: >
9126
9127 :function! Caught()
9128 : if v:exception != ""
9129 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
9130 : else
9131 : echo 'Nothing caught'
9132 : endif
9133 :endfunction
9134 :
9135 :function! Foo()
9136 : try
9137 : try
9138 : try
9139 : throw 4711
9140 : finally
9141 : call Caught()
9142 : endtry
9143 : catch /.*/
9144 : call Caught()
9145 : throw "oops"
9146 : endtry
9147 : catch /.*/
9148 : call Caught()
9149 : finally
9150 : call Caught()
9151 : endtry
9152 :endfunction
9153 :
9154 :call Foo()
9155
9156This displays >
9157
9158 Nothing caught
9159 Caught "4711" in function Foo, line 4
9160 Caught "oops" in function Foo, line 10
9161 Nothing caught
9162
9163A practical example: The following command ":LineNumber" displays the line
9164number in the script or function where it has been used: >
9165
9166 :function! LineNumber()
9167 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
9168 :endfunction
9169 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
9170<
9171 *try-nested*
9172An exception that is not caught by a try conditional can be caught by
9173a surrounding try conditional: >
9174
9175 :try
9176 : try
9177 : throw "foo"
9178 : catch /foobar/
9179 : echo "foobar"
9180 : finally
9181 : echo "inner finally"
9182 : endtry
9183 :catch /foo/
9184 : echo "foo"
9185 :endtry
9186
9187The inner try conditional does not catch the exception, just its finally
9188clause is executed. The exception is then caught by the outer try
9189conditional. The example displays "inner finally" and then "foo".
9190
9191 *throw-from-catch*
9192You can catch an exception and throw a new one to be caught elsewhere from the
9193catch clause: >
9194
9195 :function! Foo()
9196 : throw "foo"
9197 :endfunction
9198 :
9199 :function! Bar()
9200 : try
9201 : call Foo()
9202 : catch /foo/
9203 : echo "Caught foo, throw bar"
9204 : throw "bar"
9205 : endtry
9206 :endfunction
9207 :
9208 :try
9209 : call Bar()
9210 :catch /.*/
9211 : echo "Caught" v:exception
9212 :endtry
9213
9214This displays "Caught foo, throw bar" and then "Caught bar".
9215
9216 *rethrow*
9217There is no real rethrow in the Vim script language, but you may throw
9218"v:exception" instead: >
9219
9220 :function! Bar()
9221 : try
9222 : call Foo()
9223 : catch /.*/
9224 : echo "Rethrow" v:exception
9225 : throw v:exception
9226 : endtry
9227 :endfunction
9228< *try-echoerr*
9229Note that this method cannot be used to "rethrow" Vim error or interrupt
9230exceptions, because it is not possible to fake Vim internal exceptions.
9231Trying so causes an error exception. You should throw your own exception
9232denoting the situation. If you want to cause a Vim error exception containing
9233the original error exception value, you can use the |:echoerr| command: >
9234
9235 :try
9236 : try
9237 : asdf
9238 : catch /.*/
9239 : echoerr v:exception
9240 : endtry
9241 :catch /.*/
9242 : echo v:exception
9243 :endtry
9244
9245This code displays
9246
Bram Moolenaar446cb832008-06-24 21:56:24 +00009247 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009248
9249
9250CLEANUP CODE *try-finally*
9251
9252Scripts often change global settings and restore them at their end. If the
9253user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00009254an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00009255a script when an error occurs or you explicitly throw an exception without
9256catching it. You can solve these problems by using a try conditional with
9257a finally clause for restoring the settings. Its execution is guaranteed on
9258normal control flow, on error, on an explicit ":throw", and on interrupt.
9259(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00009260to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00009261clause has been executed.)
9262Example: >
9263
9264 :try
9265 : let s:saved_ts = &ts
9266 : set ts=17
9267 :
9268 : " Do the hard work here.
9269 :
9270 :finally
9271 : let &ts = s:saved_ts
9272 : unlet s:saved_ts
9273 :endtry
9274
9275This method should be used locally whenever a function or part of a script
9276changes global settings which need to be restored on failure or normal exit of
9277that function or script part.
9278
9279 *break-finally*
9280Cleanup code works also when the try block or a catch clause is left by
9281a ":continue", ":break", ":return", or ":finish".
9282 Example: >
9283
9284 :let first = 1
9285 :while 1
9286 : try
9287 : if first
9288 : echo "first"
9289 : let first = 0
9290 : continue
9291 : else
9292 : throw "second"
9293 : endif
9294 : catch /.*/
9295 : echo v:exception
9296 : break
9297 : finally
9298 : echo "cleanup"
9299 : endtry
9300 : echo "still in while"
9301 :endwhile
9302 :echo "end"
9303
9304This displays "first", "cleanup", "second", "cleanup", and "end". >
9305
9306 :function! Foo()
9307 : try
9308 : return 4711
9309 : finally
9310 : echo "cleanup\n"
9311 : endtry
9312 : echo "Foo still active"
9313 :endfunction
9314 :
9315 :echo Foo() "returned by Foo"
9316
9317This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00009318extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009319return value.)
9320
9321 *except-from-finally*
9322Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
9323a finally clause is possible, but not recommended since it abandons the
9324cleanup actions for the try conditional. But, of course, interrupt and error
9325exceptions might get raised from a finally clause.
9326 Example where an error in the finally clause stops an interrupt from
9327working correctly: >
9328
9329 :try
9330 : try
9331 : echo "Press CTRL-C for interrupt"
9332 : while 1
9333 : endwhile
9334 : finally
9335 : unlet novar
9336 : endtry
9337 :catch /novar/
9338 :endtry
9339 :echo "Script still running"
9340 :sleep 1
9341
9342If you need to put commands that could fail into a finally clause, you should
9343think about catching or ignoring the errors in these commands, see
9344|catch-errors| and |ignore-errors|.
9345
9346
9347CATCHING ERRORS *catch-errors*
9348
9349If you want to catch specific errors, you just have to put the code to be
9350watched in a try block and add a catch clause for the error message. The
9351presence of the try conditional causes all errors to be converted to an
9352exception. No message is displayed and |v:errmsg| is not set then. To find
9353the right pattern for the ":catch" command, you have to know how the format of
9354the error exception is.
9355 Error exceptions have the following format: >
9356
9357 Vim({cmdname}):{errmsg}
9358or >
9359 Vim:{errmsg}
9360
9361{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00009362the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00009363when the error occurs outside try conditionals. It always begins with
9364a capital "E", followed by a two or three-digit error number, a colon, and
9365a space.
9366
9367Examples:
9368
9369The command >
9370 :unlet novar
9371normally produces the error message >
9372 E108: No such variable: "novar"
9373which is converted inside try conditionals to an exception >
9374 Vim(unlet):E108: No such variable: "novar"
9375
9376The command >
9377 :dwim
9378normally produces the error message >
9379 E492: Not an editor command: dwim
9380which is converted inside try conditionals to an exception >
9381 Vim:E492: Not an editor command: dwim
9382
9383You can catch all ":unlet" errors by a >
9384 :catch /^Vim(unlet):/
9385or all errors for misspelled command names by a >
9386 :catch /^Vim:E492:/
9387
9388Some error messages may be produced by different commands: >
9389 :function nofunc
9390and >
9391 :delfunction nofunc
9392both produce the error message >
9393 E128: Function name must start with a capital: nofunc
9394which is converted inside try conditionals to an exception >
9395 Vim(function):E128: Function name must start with a capital: nofunc
9396or >
9397 Vim(delfunction):E128: Function name must start with a capital: nofunc
9398respectively. You can catch the error by its number independently on the
9399command that caused it if you use the following pattern: >
9400 :catch /^Vim(\a\+):E128:/
9401
9402Some commands like >
9403 :let x = novar
9404produce multiple error messages, here: >
9405 E121: Undefined variable: novar
9406 E15: Invalid expression: novar
9407Only the first is used for the exception value, since it is the most specific
9408one (see |except-several-errors|). So you can catch it by >
9409 :catch /^Vim(\a\+):E121:/
9410
9411You can catch all errors related to the name "nofunc" by >
9412 :catch /\<nofunc\>/
9413
9414You can catch all Vim errors in the ":write" and ":read" commands by >
9415 :catch /^Vim(\(write\|read\)):E\d\+:/
9416
9417You can catch all Vim errors by the pattern >
9418 :catch /^Vim\((\a\+)\)\=:E\d\+:/
9419<
9420 *catch-text*
9421NOTE: You should never catch the error message text itself: >
9422 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01009423only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00009424a different language by the |:language| command. It is however helpful to
9425cite the message text in a comment: >
9426 :catch /^Vim(\a\+):E108:/ " No such variable
9427
9428
9429IGNORING ERRORS *ignore-errors*
9430
9431You can ignore errors in a specific Vim command by catching them locally: >
9432
9433 :try
9434 : write
9435 :catch
9436 :endtry
9437
9438But you are strongly recommended NOT to use this simple form, since it could
9439catch more than you want. With the ":write" command, some autocommands could
9440be executed and cause errors not related to writing, for instance: >
9441
9442 :au BufWritePre * unlet novar
9443
9444There could even be such errors you are not responsible for as a script
9445writer: a user of your script might have defined such autocommands. You would
9446then hide the error from the user.
9447 It is much better to use >
9448
9449 :try
9450 : write
9451 :catch /^Vim(write):/
9452 :endtry
9453
9454which only catches real write errors. So catch only what you'd like to ignore
9455intentionally.
9456
9457For a single command that does not cause execution of autocommands, you could
9458even suppress the conversion of errors to exceptions by the ":silent!"
9459command: >
9460 :silent! nunmap k
9461This works also when a try conditional is active.
9462
9463
9464CATCHING INTERRUPTS *catch-interrupt*
9465
9466When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00009467the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009468script is not terminated, then.
9469 Example: >
9470
9471 :function! TASK1()
9472 : sleep 10
9473 :endfunction
9474
9475 :function! TASK2()
9476 : sleep 20
9477 :endfunction
9478
9479 :while 1
9480 : let command = input("Type a command: ")
9481 : try
9482 : if command == ""
9483 : continue
9484 : elseif command == "END"
9485 : break
9486 : elseif command == "TASK1"
9487 : call TASK1()
9488 : elseif command == "TASK2"
9489 : call TASK2()
9490 : else
9491 : echo "\nIllegal command:" command
9492 : continue
9493 : endif
9494 : catch /^Vim:Interrupt$/
9495 : echo "\nCommand interrupted"
9496 : " Caught the interrupt. Continue with next prompt.
9497 : endtry
9498 :endwhile
9499
9500You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00009501a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009502
9503For testing what happens when CTRL-C would be pressed on a specific line in
9504your script, use the debug mode and execute the |>quit| or |>interrupt|
9505command on that line. See |debug-scripts|.
9506
9507
9508CATCHING ALL *catch-all*
9509
9510The commands >
9511
9512 :catch /.*/
9513 :catch //
9514 :catch
9515
9516catch everything, error exceptions, interrupt exceptions and exceptions
9517explicitly thrown by the |:throw| command. This is useful at the top level of
9518a script in order to catch unexpected things.
9519 Example: >
9520
9521 :try
9522 :
9523 : " do the hard work here
9524 :
9525 :catch /MyException/
9526 :
9527 : " handle known problem
9528 :
9529 :catch /^Vim:Interrupt$/
9530 : echo "Script interrupted"
9531 :catch /.*/
9532 : echo "Internal error (" . v:exception . ")"
9533 : echo " - occurred at " . v:throwpoint
9534 :endtry
9535 :" end of script
9536
9537Note: Catching all might catch more things than you want. Thus, you are
9538strongly encouraged to catch only for problems that you can really handle by
9539specifying a pattern argument to the ":catch".
9540 Example: Catching all could make it nearly impossible to interrupt a script
9541by pressing CTRL-C: >
9542
9543 :while 1
9544 : try
9545 : sleep 1
9546 : catch
9547 : endtry
9548 :endwhile
9549
9550
9551EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
9552
9553Exceptions may be used during execution of autocommands. Example: >
9554
9555 :autocmd User x try
9556 :autocmd User x throw "Oops!"
9557 :autocmd User x catch
9558 :autocmd User x echo v:exception
9559 :autocmd User x endtry
9560 :autocmd User x throw "Arrgh!"
9561 :autocmd User x echo "Should not be displayed"
9562 :
9563 :try
9564 : doautocmd User x
9565 :catch
9566 : echo v:exception
9567 :endtry
9568
9569This displays "Oops!" and "Arrgh!".
9570
9571 *except-autocmd-Pre*
9572For some commands, autocommands get executed before the main action of the
9573command takes place. If an exception is thrown and not caught in the sequence
9574of autocommands, the sequence and the command that caused its execution are
9575abandoned and the exception is propagated to the caller of the command.
9576 Example: >
9577
9578 :autocmd BufWritePre * throw "FAIL"
9579 :autocmd BufWritePre * echo "Should not be displayed"
9580 :
9581 :try
9582 : write
9583 :catch
9584 : echo "Caught:" v:exception "from" v:throwpoint
9585 :endtry
9586
9587Here, the ":write" command does not write the file currently being edited (as
9588you can see by checking 'modified'), since the exception from the BufWritePre
9589autocommand abandons the ":write". The exception is then caught and the
9590script displays: >
9591
9592 Caught: FAIL from BufWrite Auto commands for "*"
9593<
9594 *except-autocmd-Post*
9595For some commands, autocommands get executed after the main action of the
9596command has taken place. If this main action fails and the command is inside
9597an active try conditional, the autocommands are skipped and an error exception
9598is thrown that can be caught by the caller of the command.
9599 Example: >
9600
9601 :autocmd BufWritePost * echo "File successfully written!"
9602 :
9603 :try
9604 : write /i/m/p/o/s/s/i/b/l/e
9605 :catch
9606 : echo v:exception
9607 :endtry
9608
9609This just displays: >
9610
9611 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
9612
9613If you really need to execute the autocommands even when the main action
9614fails, trigger the event from the catch clause.
9615 Example: >
9616
9617 :autocmd BufWritePre * set noreadonly
9618 :autocmd BufWritePost * set readonly
9619 :
9620 :try
9621 : write /i/m/p/o/s/s/i/b/l/e
9622 :catch
9623 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
9624 :endtry
9625<
9626You can also use ":silent!": >
9627
9628 :let x = "ok"
9629 :let v:errmsg = ""
9630 :autocmd BufWritePost * if v:errmsg != ""
9631 :autocmd BufWritePost * let x = "after fail"
9632 :autocmd BufWritePost * endif
9633 :try
9634 : silent! write /i/m/p/o/s/s/i/b/l/e
9635 :catch
9636 :endtry
9637 :echo x
9638
9639This displays "after fail".
9640
9641If the main action of the command does not fail, exceptions from the
9642autocommands will be catchable by the caller of the command: >
9643
9644 :autocmd BufWritePost * throw ":-("
9645 :autocmd BufWritePost * echo "Should not be displayed"
9646 :
9647 :try
9648 : write
9649 :catch
9650 : echo v:exception
9651 :endtry
9652<
9653 *except-autocmd-Cmd*
9654For some commands, the normal action can be replaced by a sequence of
9655autocommands. Exceptions from that sequence will be catchable by the caller
9656of the command.
9657 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00009658had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00009659some way. >
9660
9661 :if !exists("cnt")
9662 : let cnt = 0
9663 :
9664 : autocmd BufWriteCmd * if &modified
9665 : autocmd BufWriteCmd * let cnt = cnt + 1
9666 : autocmd BufWriteCmd * if cnt % 3 == 2
9667 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9668 : autocmd BufWriteCmd * endif
9669 : autocmd BufWriteCmd * write | set nomodified
9670 : autocmd BufWriteCmd * if cnt % 3 == 0
9671 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9672 : autocmd BufWriteCmd * endif
9673 : autocmd BufWriteCmd * echo "File successfully written!"
9674 : autocmd BufWriteCmd * endif
9675 :endif
9676 :
9677 :try
9678 : write
9679 :catch /^BufWriteCmdError$/
9680 : if &modified
9681 : echo "Error on writing (file contents not changed)"
9682 : else
9683 : echo "Error after writing"
9684 : endif
9685 :catch /^Vim(write):/
9686 : echo "Error on writing"
9687 :endtry
9688
9689When this script is sourced several times after making changes, it displays
9690first >
9691 File successfully written!
9692then >
9693 Error on writing (file contents not changed)
9694then >
9695 Error after writing
9696etc.
9697
9698 *except-autocmd-ill*
9699You cannot spread a try conditional over autocommands for different events.
9700The following code is ill-formed: >
9701
9702 :autocmd BufWritePre * try
9703 :
9704 :autocmd BufWritePost * catch
9705 :autocmd BufWritePost * echo v:exception
9706 :autocmd BufWritePost * endtry
9707 :
9708 :write
9709
9710
9711EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
9712
9713Some programming languages allow to use hierarchies of exception classes or to
9714pass additional information with the object of an exception class. You can do
9715similar things in Vim.
9716 In order to throw an exception from a hierarchy, just throw the complete
9717class name with the components separated by a colon, for instance throw the
9718string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
9719 When you want to pass additional information with your exception class, add
9720it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
9721for an error when writing "myfile".
9722 With the appropriate patterns in the ":catch" command, you can catch for
9723base classes or derived classes of your hierarchy. Additional information in
9724parentheses can be cut out from |v:exception| with the ":substitute" command.
9725 Example: >
9726
9727 :function! CheckRange(a, func)
9728 : if a:a < 0
9729 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
9730 : endif
9731 :endfunction
9732 :
9733 :function! Add(a, b)
9734 : call CheckRange(a:a, "Add")
9735 : call CheckRange(a:b, "Add")
9736 : let c = a:a + a:b
9737 : if c < 0
9738 : throw "EXCEPT:MATHERR:OVERFLOW"
9739 : endif
9740 : return c
9741 :endfunction
9742 :
9743 :function! Div(a, b)
9744 : call CheckRange(a:a, "Div")
9745 : call CheckRange(a:b, "Div")
9746 : if (a:b == 0)
9747 : throw "EXCEPT:MATHERR:ZERODIV"
9748 : endif
9749 : return a:a / a:b
9750 :endfunction
9751 :
9752 :function! Write(file)
9753 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009754 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009755 : catch /^Vim(write):/
9756 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
9757 : endtry
9758 :endfunction
9759 :
9760 :try
9761 :
9762 : " something with arithmetics and I/O
9763 :
9764 :catch /^EXCEPT:MATHERR:RANGE/
9765 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
9766 : echo "Range error in" function
9767 :
9768 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
9769 : echo "Math error"
9770 :
9771 :catch /^EXCEPT:IO/
9772 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
9773 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
9774 : if file !~ '^/'
9775 : let file = dir . "/" . file
9776 : endif
9777 : echo 'I/O error for "' . file . '"'
9778 :
9779 :catch /^EXCEPT/
9780 : echo "Unspecified error"
9781 :
9782 :endtry
9783
9784The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
9785a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
9786exceptions with the "Vim" prefix; they are reserved for Vim.
9787 Vim error exceptions are parameterized with the name of the command that
9788failed, if known. See |catch-errors|.
9789
9790
9791PECULIARITIES
9792 *except-compat*
9793The exception handling concept requires that the command sequence causing the
9794exception is aborted immediately and control is transferred to finally clauses
9795and/or a catch clause.
9796
9797In the Vim script language there are cases where scripts and functions
9798continue after an error: in functions without the "abort" flag or in a command
9799after ":silent!", control flow goes to the following line, and outside
9800functions, control flow goes to the line following the outermost ":endwhile"
9801or ":endif". On the other hand, errors should be catchable as exceptions
9802(thus, requiring the immediate abortion).
9803
9804This problem has been solved by converting errors to exceptions and using
9805immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009806conditional is active. This is no restriction since an (error) exception can
9807be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00009808termination without catching the error, just use a try conditional without
9809catch clause. (You can cause cleanup code being executed before termination
9810by specifying a finally clause.)
9811
9812When no try conditional is active, the usual abortion and continuation
9813behavior is used instead of immediate abortion. This ensures compatibility of
9814scripts written for Vim 6.1 and earlier.
9815
9816However, when sourcing an existing script that does not use exception handling
9817commands (or when calling one of its functions) from inside an active try
9818conditional of a new script, you might change the control flow of the existing
9819script on error. You get the immediate abortion on error and can catch the
9820error in the new script. If however the sourced script suppresses error
9821messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00009822|v:errmsg| if appropriate), its execution path is not changed. The error is
9823not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00009824where this happens is for scripts that don't care about errors and produce
9825error messages. You probably won't want to use such code from your new
9826scripts.
9827
9828 *except-syntax-err*
9829Syntax errors in the exception handling commands are never caught by any of
9830the ":catch" commands of the try conditional they belong to. Its finally
9831clauses, however, is executed.
9832 Example: >
9833
9834 :try
9835 : try
9836 : throw 4711
9837 : catch /\(/
9838 : echo "in catch with syntax error"
9839 : catch
9840 : echo "inner catch-all"
9841 : finally
9842 : echo "inner finally"
9843 : endtry
9844 :catch
9845 : echo 'outer catch-all caught "' . v:exception . '"'
9846 : finally
9847 : echo "outer finally"
9848 :endtry
9849
9850This displays: >
9851 inner finally
9852 outer catch-all caught "Vim(catch):E54: Unmatched \("
9853 outer finally
9854The original exception is discarded and an error exception is raised, instead.
9855
9856 *except-single-line*
9857The ":try", ":catch", ":finally", and ":endtry" commands can be put on
9858a single line, but then syntax errors may make it difficult to recognize the
9859"catch" line, thus you better avoid this.
9860 Example: >
9861 :try | unlet! foo # | catch | endtry
9862raises an error exception for the trailing characters after the ":unlet!"
9863argument, but does not see the ":catch" and ":endtry" commands, so that the
9864error exception is discarded and the "E488: Trailing characters" message gets
9865displayed.
9866
9867 *except-several-errors*
9868When several errors appear in a single command, the first error message is
9869usually the most specific one and therefor converted to the error exception.
9870 Example: >
9871 echo novar
9872causes >
9873 E121: Undefined variable: novar
9874 E15: Invalid expression: novar
9875The value of the error exception inside try conditionals is: >
9876 Vim(echo):E121: Undefined variable: novar
9877< *except-syntax-error*
9878But when a syntax error is detected after a normal error in the same command,
9879the syntax error is used for the exception being thrown.
9880 Example: >
9881 unlet novar #
9882causes >
9883 E108: No such variable: "novar"
9884 E488: Trailing characters
9885The value of the error exception inside try conditionals is: >
9886 Vim(unlet):E488: Trailing characters
9887This is done because the syntax error might change the execution path in a way
9888not intended by the user. Example: >
9889 try
9890 try | unlet novar # | catch | echo v:exception | endtry
9891 catch /.*/
9892 echo "outer catch:" v:exception
9893 endtry
9894This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
9895a "E600: Missing :endtry" error message is given, see |except-single-line|.
9896
9897==============================================================================
98989. Examples *eval-examples*
9899
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009900Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009901>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009902 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009903 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009904 : let n = a:nr
9905 : let r = ""
9906 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009907 : let r = '01'[n % 2] . r
9908 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00009909 : endwhile
9910 : return r
9911 :endfunc
9912
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009913 :" The function String2Bin() converts each character in a string to a
9914 :" binary string, separated with dashes.
9915 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009916 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009917 : for ix in range(strlen(a:str))
9918 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
9919 : endfor
9920 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00009921 :endfunc
9922
9923Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009924 :echo Nr2Bin(32)
9925result: "100000" >
9926 :echo String2Bin("32")
9927result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009928
9929
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009930Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009931
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009932This example sorts lines with a specific compare function. >
9933
9934 :func SortBuffer()
9935 : let lines = getline(1, '$')
9936 : call sort(lines, function("Strcmp"))
9937 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009938 :endfunction
9939
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009940As a one-liner: >
9941 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009942
Bram Moolenaar071d4272004-06-13 20:20:40 +00009943
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009944scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009945 *sscanf*
9946There is no sscanf() function in Vim. If you need to extract parts from a
9947line, you can use matchstr() and substitute() to do it. This example shows
9948how to get the file name, line number and column number out of a line like
9949"foobar.txt, 123, 45". >
9950 :" Set up the match bit
9951 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
9952 :"get the part matching the whole expression
9953 :let l = matchstr(line, mx)
9954 :"get each item out of the match
9955 :let file = substitute(l, mx, '\1', '')
9956 :let lnum = substitute(l, mx, '\2', '')
9957 :let col = substitute(l, mx, '\3', '')
9958
9959The input is in the variable "line", the results in the variables "file",
9960"lnum" and "col". (idea from Michael Geddes)
9961
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009962
9963getting the scriptnames in a Dictionary ~
9964 *scriptnames-dictionary*
9965The |:scriptnames| command can be used to get a list of all script files that
9966have been sourced. There is no equivalent function or variable for this
9967(because it's rarely needed). In case you need to manipulate the list this
9968code can be used: >
9969 " Get the output of ":scriptnames" in the scriptnames_output variable.
9970 let scriptnames_output = ''
9971 redir => scriptnames_output
9972 silent scriptnames
9973 redir END
9974
Bram Moolenaar446cb832008-06-24 21:56:24 +00009975 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009976 " "scripts" dictionary.
9977 let scripts = {}
9978 for line in split(scriptnames_output, "\n")
9979 " Only do non-blank lines.
9980 if line =~ '\S'
9981 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009982 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009983 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00009984 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009985 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00009986 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009987 endif
9988 endfor
9989 unlet scriptnames_output
9990
Bram Moolenaar071d4272004-06-13 20:20:40 +00009991==============================================================================
999210. No +eval feature *no-eval-feature*
9993
9994When the |+eval| feature was disabled at compile time, none of the expression
9995evaluation commands are available. To prevent this from causing Vim scripts
9996to generate all kinds of errors, the ":if" and ":endif" commands are still
9997recognized, though the argument of the ":if" and everything between the ":if"
9998and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
9999only if the commands are at the start of the line. The ":else" command is not
10000recognized.
10001
10002Example of how to avoid executing commands when the |+eval| feature is
10003missing: >
10004
10005 :if 1
10006 : echo "Expression evaluation is compiled in"
10007 :else
10008 : echo "You will _never_ see this message"
10009 :endif
10010
10011==============================================================================
1001211. The sandbox *eval-sandbox* *sandbox* *E48*
10013
Bram Moolenaar368373e2010-07-19 20:46:22 +020010014The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
10015'foldtext' options may be evaluated in a sandbox. This means that you are
10016protected from these expressions having nasty side effects. This gives some
10017safety for when these options are set from a modeline. It is also used when
10018the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000010019The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010020
10021These items are not allowed in the sandbox:
10022 - changing the buffer text
10023 - defining or changing mapping, autocommands, functions, user commands
10024 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010025 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010026 - executing a shell command
10027 - reading or writing a file
10028 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000010029 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000010030This is not guaranteed 100% secure, but it should block most attacks.
10031
10032 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000010033:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000010034 option that may have been set from a modeline, e.g.
10035 'foldexpr'.
10036
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000010037 *sandbox-option*
10038A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000010039have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000010040restrictive, thus this only happens when the option was set from an insecure
10041location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000010042- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000010043- while executing in the sandbox
10044- value coming from a modeline
10045
10046Note that when in the sandbox and saving an option value and restoring it, the
10047option will still be marked as it was set in the sandbox.
10048
10049==============================================================================
1005012. Textlock *textlock*
10051
10052In a few situations it is not allowed to change the text in the buffer, jump
10053to another window and some other things that might confuse or break what Vim
10054is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +000010055actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000010056happen any moment the mouse cursor is resting at some position.
10057
10058This is not allowed when the textlock is active:
10059 - changing the buffer text
10060 - jumping to another buffer or window
10061 - editing another file
10062 - closing a window or quitting Vim
10063 - etc.
10064
Bram Moolenaar071d4272004-06-13 20:20:40 +000010065
10066 vim:tw=78:ts=8:ft=help:norl: