blob: 21ccf2b8cedc48af00b89b36aa73e497e49a24a9 [file] [log] [blame]
Bram Moolenaarb3480382005-12-11 21:33:32 +00001*eval.txt* For Vim version 7.0aa. Last change: 2005 Dec 11
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
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 Moolenaare2cc9702005-03-15 22:43:58 +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 Moolenaar071d4272004-06-13 20:20:40 +000031
32{Vi does not have any of these commands}
33
34==============================================================================
351. Variables *variables*
36
Bram Moolenaar13065c42005-01-08 16:08:21 +0000371.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000038 *E712*
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000039There are five types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000040
Bram Moolenaard8b02732005-01-14 21:48:43 +000041Number A 32 bit signed number.
42 Examples: -123 0x10 0177
43
44String A NUL terminated string of 8-bit unsigned characters (bytes).
45 Examples: "ab\txx\"--" 'x-z''a,c'
46
47Funcref A reference to a function |Funcref|.
48 Example: function("strlen")
49
50List An ordered sequence of items |List|.
51 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000052
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000053Dictionary An associative, unordered array: Each entry has a key and a
54 value. |Dictionary|
55 Example: {'blue': "#0000ff", 'red': "#ff0000"}
56
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000057The Number and String types are converted automatically, depending on how they
58are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000059
60Conversion from a Number to a String is by making the ASCII representation of
61the Number. Examples: >
62 Number 123 --> String "123"
63 Number 0 --> String "0"
64 Number -1 --> String "-1"
65
66Conversion from a String to a Number is done by converting the first digits
67to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
68the String doesn't start with digits, the result is zero. Examples: >
69 String "456" --> Number 456
70 String "6bar" --> Number 6
71 String "foo" --> Number 0
72 String "0xf1" --> Number 241
73 String "0100" --> Number 64
74 String "-8" --> Number -8
75 String "+8" --> Number 0
76
77To force conversion from String to Number, add zero to it: >
78 :echo "0100" + 0
79
80For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
81
82Note that in the command >
83 :if "foo"
84"foo" is converted to 0, which means FALSE. To test for a non-empty string,
85use strlen(): >
86 :if strlen("foo")
Bram Moolenaar748bf032005-02-02 23:04:36 +000087< *E745* *E728* *E703* *E729* *E730* *E731*
88List, Dictionary and Funcref types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000089
Bram Moolenaar13065c42005-01-08 16:08:21 +000090 *E706*
91You will get an error if you try to change the type of a variable. You need
92to |:unlet| it first to avoid this error. String and Number are considered
Bram Moolenaard8b02732005-01-14 21:48:43 +000093equivalent though. Consider this sequence of commands: >
Bram Moolenaar13065c42005-01-08 16:08:21 +000094 :let l = "string"
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000095 :let l = 44 " changes type from String to Number
Bram Moolenaar13065c42005-01-08 16:08:21 +000096 :let l = [1, 2, 3] " error!
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000097
Bram Moolenaar13065c42005-01-08 16:08:21 +000098
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000991.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000100 *Funcref* *E695* *E718*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000101A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000102in an expression in the place of a function name, before the parenthesis
103around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000104
105 :let Fn = function("MyFunc")
106 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000107< *E704* *E705* *E707*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000108A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot
109have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000110
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000111A special case is defining a function and directly assigning its Funcref to a
112Dictionary entry. Example: >
113 :function dict.init() dict
114 : let self.val = 0
115 :endfunction
116
117The key of the Dictionary can start with a lower case letter. The actual
118function name is not used here. Also see |numbered-function|.
119
120A Funcref can also be used with the |:call| command: >
121 :call Fn()
122 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000123
124The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000125 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000126
127You can use |call()| to invoke a Funcref and use a list variable for the
128arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000129 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000130
131
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001321.3 Lists ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000133 *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000134A List is an ordered sequence of items. An item can be of any type. Items
135can be accessed by their index number. Items can be added and removed at any
136position in the sequence.
137
Bram Moolenaar13065c42005-01-08 16:08:21 +0000138
139List creation ~
140 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000141A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000142Examples: >
143 :let mylist = [1, two, 3, "four"]
144 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000145
146An item can be any expression. Using a List for an item creates a
Bram Moolenaar13065c42005-01-08 16:08:21 +0000147nested List: >
148 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000149
150An extra comma after the last item is ignored.
151
Bram Moolenaar13065c42005-01-08 16:08:21 +0000152
153List index ~
154 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000155An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000156after the List. Indexes are zero-based, thus the first item has index zero. >
157 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000158 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000159
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000160When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000161 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000162<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000163A negative index is counted from the end. Index -1 refers to the last item in
164the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000165 :let last = mylist[-1] " get the last item: "four"
166
Bram Moolenaar13065c42005-01-08 16:08:21 +0000167To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000168is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000169 :echo get(mylist, idx)
170 :echo get(mylist, idx, "NONE")
171
172
173List concatenation ~
174
175Two lists can be concatenated with the "+" operator: >
176 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000177 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000178
179To prepend or append an item turn the item into a list by putting [] around
180it. To change a list in-place see |list-modification| below.
181
182
183Sublist ~
184
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000185A part of the List can be obtained by specifying the first and last index,
186separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000187 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000188
189Omitting the first index is similar to zero. Omitting the last index is
190similar to -1. The difference is that there is no error if the items are not
191available. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000192 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
193 :let shortlist = mylist[2:2] " List with one item: [3]
194 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000195
Bram Moolenaard8b02732005-01-14 21:48:43 +0000196The second index can be just before the first index. In that case the result
197is an empty list. If the second index is lower, this results in an error. >
198 :echo mylist[2:1] " result: []
199 :echo mylist[2:0] " error!
200
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000201NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
202using a single letter variable before the ":". Insert a space when needed:
203mylist[s : e].
204
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000205
Bram Moolenaar13065c42005-01-08 16:08:21 +0000206List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000207 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000208When variable "aa" is a list and you assign it to another variable "bb", both
209variables refer to the same list. Thus changing the list "aa" will also
210change "bb": >
211 :let aa = [1, 2, 3]
212 :let bb = aa
213 :call add(aa, 4)
214 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000215< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000216
217Making a copy of a list is done with the |copy()| function. Using [:] also
218works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000219a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000220 :let aa = [[1, 'a'], 2, 3]
221 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000222 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000223 :let aa[0][1] = 'aaa'
224 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000225< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000226 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000227< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000229To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000230copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231
232The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000233List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000234the same value. >
235 :let alist = [1, 2, 3]
236 :let blist = [1, 2, 3]
237 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000238< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000239 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000240< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000242Note about comparing lists: Two lists are considered equal if they have the
243same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000244exception: When comparing a number with a string they are considered
245different. There is no automatic type conversion, as with using "==" on
246variables. Example: >
247 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000248< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000249 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000250< 0
251
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000252Thus comparing Lists is more strict than comparing numbers and strings. You
253can compare simple values this way too by putting them in a string: >
254
255 :let a = 5
256 :let b = "5"
257 echo a == b
258< 1 >
259 echo [a] == [b]
260< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000261
Bram Moolenaar13065c42005-01-08 16:08:21 +0000262
263List unpack ~
264
265To unpack the items in a list to individual variables, put the variables in
266square brackets, like list items: >
267 :let [var1, var2] = mylist
268
269When the number of variables does not match the number of items in the list
270this produces an error. To handle any extra items from the list append ";"
271and a variable name: >
272 :let [var1, var2; rest] = mylist
273
274This works like: >
275 :let var1 = mylist[0]
276 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000277 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000278
279Except that there is no error if there are only two items. "rest" will be an
280empty list then.
281
282
283List modification ~
284 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000285To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000286 :let list[4] = "four"
287 :let listlist[0][3] = item
288
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000289To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000290modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000291 :let list[3:5] = [3, 4, 5]
292
Bram Moolenaar13065c42005-01-08 16:08:21 +0000293Adding and removing items from a list is done with functions. Here are a few
294examples: >
295 :call insert(list, 'a') " prepend item 'a'
296 :call insert(list, 'a', 3) " insert item 'a' before list[3]
297 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000298 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000299 :call extend(list, [1, 2]) " extend the list with two more items
300 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000301 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000302 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000303 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000304 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000305
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000306Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000307 :call sort(list) " sort a list alphabetically
308 :call reverse(list) " reverse the order of items
309
Bram Moolenaar13065c42005-01-08 16:08:21 +0000310
311For loop ~
312
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000313The |:for| loop executes commands for each item in a list. A variable is set
314to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315 :for item in mylist
316 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000317 :endfor
318
319This works like: >
320 :let index = 0
321 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000322 : let item = mylist[index]
323 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000324 : let index = index + 1
325 :endwhile
326
327Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000328results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000329the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000330
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000331If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000332function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000333
Bram Moolenaar13065c42005-01-08 16:08:21 +0000334Just like the |:let| command, |:for| also accepts a list of variables. This
335requires the argument to be a list of lists. >
336 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
337 : call Doit(lnum, col)
338 :endfor
339
340This works like a |:let| command is done for each list item. Again, the types
341must remain the same to avoid an error.
342
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000343It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000344 :for [i, j; rest] in listlist
345 : call Doit(i, j)
346 : if !empty(rest)
347 : echo "remainder: " . string(rest)
348 : endif
349 :endfor
350
351
352List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000353 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000354Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000355 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000356 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000357 :let l = len(list) " number of items in list
358 :let big = max(list) " maximum value in list
359 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000360 :let xs = count(list, 'x') " count nr of times 'x' appears in list
361 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000362 :let lines = getline(1, 10) " get ten text lines from buffer
363 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000364 :let list = split("a b c") " create list from items in a string
365 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000366 :let s = string(list) " String representation of list
367 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000368
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000369Don't forget that a combination of features can make things simple. For
370example, to add up all the numbers in a list: >
371 :exe 'let sum = ' . join(nrlist, '+')
372
Bram Moolenaar13065c42005-01-08 16:08:21 +0000373
Bram Moolenaard8b02732005-01-14 21:48:43 +00003741.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000376A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000377entry can be located with the key. The entries are stored without a specific
378ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000379
380
381Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000382 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000383A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000384braces. Each entry has a key and a value, separated by a colon. Each key can
385only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000386 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
387 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000388< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000389A key is always a String. You can use a Number, it will be converted to a
390String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000391entry. Note that the String '04' and the Number 04 are different, since the
392Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000393
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000394A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000395nested Dictionary: >
396 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
397
398An extra comma after the last entry is ignored.
399
400
401Accessing entries ~
402
403The normal way to access an entry is by putting the key in square brackets: >
404 :let val = mydict["one"]
405 :let mydict["four"] = 4
406
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000407You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000408
409For keys that consist entirely of letters, digits and underscore the following
410form can be used |expr-entry|: >
411 :let val = mydict.one
412 :let mydict.four = 4
413
414Since an entry can be any type, also a List and a Dictionary, the indexing and
415key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000416 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000417
418
419Dictionary to List conversion ~
420
421You may want to loop over the entries in a dictionary. For this you need to
422turn the Dictionary into a List and pass it to |:for|.
423
424Most often you want to loop over the keys, using the |keys()| function: >
425 :for key in keys(mydict)
426 : echo key . ': ' . mydict[key]
427 :endfor
428
429The List of keys is unsorted. You may want to sort them first: >
430 :for key in sort(keys(mydict))
431
432To loop over the values use the |values()| function: >
433 :for v in values(mydict)
434 : echo "value: " . v
435 :endfor
436
437If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000438a List in which each item is a List with two items, the key and the value: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000439 :for entry in items(mydict)
440 : echo entry[0] . ': ' . entry[1]
441 :endfor
442
443
444Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000445 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000446Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
447Dictionary. Otherwise, assignment results in referring to the same
448Dictionary: >
449 :let onedict = {'a': 1, 'b': 2}
450 :let adict = onedict
451 :let adict['a'] = 11
452 :echo onedict['a']
453 11
454
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000455Two Dictionaries compare equal if all the key-value pairs compare equal. For
456more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000457
458
459Dictionary modification ~
460 *dict-modification*
461To change an already existing entry of a Dictionary, or to add a new entry,
462use |:let| this way: >
463 :let dict[4] = "four"
464 :let dict['one'] = item
465
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000466Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
467Three ways to remove the entry with key "aaa" from dict: >
468 :let i = remove(dict, 'aaa')
469 :unlet dict.aaa
470 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000471
472Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000473 :call extend(adict, bdict)
474This extends adict with all entries from bdict. Duplicate keys cause entries
475in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000476Note that the order of entries in a Dictionary is irrelevant, thus don't
477expect ":echo adict" to show the items from bdict after the older entries in
478adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479
480Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaare2cc9702005-03-15 22:43:58 +0000481 :call filter(dict 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000482This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000483
484
485Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000486 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000487When a function is defined with the "dict" attribute it can be used in a
488special way with a dictionary. Example: >
489 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000490 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000491 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000492 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
493 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000494
495This is like a method in object oriented programming. The entry in the
496Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
497the function was invoked from.
498
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000499It is also possible to add a function without the "dict" attribute as a
500Funcref to a Dictionary, but the "self" variable is not available then.
501
502 *numbered-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000503To avoid the extra name for the function it can be defined and directly
504assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000505 :let mydict = {'data': [0, 1, 2, 3]}
506 :function mydict.len() dict
507 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000508 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000509 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000510
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000511The function will then get a number and the value of dict.len is a |Funcref|
512that references this function. The function can only be used through a
513|Funcref|. It will automatically be deleted when there is no |Funcref|
514remaining that refers to it.
515
516It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000517
518
519Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000520 *E715*
521Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000522 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
523 :if empty(dict) " TRUE if dict is empty
524 :let l = len(dict) " number of items in dict
525 :let big = max(dict) " maximum value in dict
526 :let small = min(dict) " minimum value in dict
527 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
528 :let s = string(dict) " String representation of dict
529 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000530
531
5321.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000533 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534If you need to know the type of a variable or expression, use the |type()|
535function.
536
537When the '!' flag is included in the 'viminfo' option, global variables that
538start with an uppercase letter, and don't contain a lowercase letter, are
539stored in the viminfo file |viminfo-file|.
540
541When the 'sessionoptions' option contains "global", global variables that
542start with an uppercase letter and contain at least one lowercase letter are
543stored in the session file |session-file|.
544
545variable name can be stored where ~
546my_var_6 not
547My_Var_6 session file
548MY_VAR_6 viminfo file
549
550
551It's possible to form a variable name with curly braces, see
552|curly-braces-names|.
553
554==============================================================================
5552. Expression syntax *expression-syntax*
556
557Expression syntax summary, from least to most significant:
558
559|expr1| expr2 ? expr1 : expr1 if-then-else
560
561|expr2| expr3 || expr3 .. logical OR
562
563|expr3| expr4 && expr4 .. logical AND
564
565|expr4| expr5 == expr5 equal
566 expr5 != expr5 not equal
567 expr5 > expr5 greater than
568 expr5 >= expr5 greater than or equal
569 expr5 < expr5 smaller than
570 expr5 <= expr5 smaller than or equal
571 expr5 =~ expr5 regexp matches
572 expr5 !~ expr5 regexp doesn't match
573
574 expr5 ==? expr5 equal, ignoring case
575 expr5 ==# expr5 equal, match case
576 etc. As above, append ? for ignoring case, # for
577 matching case
578
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000579 expr5 is expr5 same List instance
580 expr5 isnot expr5 different List instance
581
582|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000583 expr6 - expr6 .. number subtraction
584 expr6 . expr6 .. string concatenation
585
586|expr6| expr7 * expr7 .. number multiplication
587 expr7 / expr7 .. number division
588 expr7 % expr7 .. number modulo
589
590|expr7| ! expr7 logical NOT
591 - expr7 unary minus
592 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000593
Bram Moolenaar071d4272004-06-13 20:20:40 +0000594
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000595|expr8| expr8[expr1] byte of a String or item of a List
596 expr8[expr1 : expr1] substring of a String or sublist of a List
597 expr8.name entry in a Dictionary
598 expr8(expr1, ...) function call with Funcref variable
599
600|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000601 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000602 'string' string constant, ' is doubled
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000603 [expr1, ...] List
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000604 {expr1: expr1, ...} Dictionary
Bram Moolenaar071d4272004-06-13 20:20:40 +0000605 &option option value
606 (expr1) nested expression
607 variable internal variable
608 va{ria}ble internal variable with curly braces
609 $VAR environment variable
610 @r contents of register 'r'
611 function(expr1, ...) function call
612 func{ti}on(expr1, ...) function call with curly braces
613
614
615".." indicates that the operations in this level can be concatenated.
616Example: >
617 &nu || &list && &shell == "csh"
618
619All expressions within one level are parsed from left to right.
620
621
622expr1 *expr1* *E109*
623-----
624
625expr2 ? expr1 : expr1
626
627The expression before the '?' is evaluated to a number. If it evaluates to
628non-zero, the result is the value of the expression between the '?' and ':',
629otherwise the result is the value of the expression after the ':'.
630Example: >
631 :echo lnum == 1 ? "top" : lnum
632
633Since the first expression is an "expr2", it cannot contain another ?:. The
634other two expressions can, thus allow for recursive use of ?:.
635Example: >
636 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
637
638To keep this readable, using |line-continuation| is suggested: >
639 :echo lnum == 1
640 :\ ? "top"
641 :\ : lnum == 1000
642 :\ ? "last"
643 :\ : lnum
644
645
646expr2 and expr3 *expr2* *expr3*
647---------------
648
649 *expr-barbar* *expr-&&*
650The "||" and "&&" operators take one argument on each side. The arguments
651are (converted to) Numbers. The result is:
652
653 input output ~
654n1 n2 n1 || n2 n1 && n2 ~
655zero zero zero zero
656zero non-zero non-zero zero
657non-zero zero non-zero zero
658non-zero non-zero non-zero non-zero
659
660The operators can be concatenated, for example: >
661
662 &nu || &list && &shell == "csh"
663
664Note that "&&" takes precedence over "||", so this has the meaning of: >
665
666 &nu || (&list && &shell == "csh")
667
668Once the result is known, the expression "short-circuits", that is, further
669arguments are not evaluated. This is like what happens in C. For example: >
670
671 let a = 1
672 echo a || b
673
674This is valid even if there is no variable called "b" because "a" is non-zero,
675so the result must be non-zero. Similarly below: >
676
677 echo exists("b") && b == "yes"
678
679This is valid whether "b" has been defined or not. The second clause will
680only be evaluated if "b" has been defined.
681
682
683expr4 *expr4*
684-----
685
686expr5 {cmp} expr5
687
688Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
689if it evaluates to true.
690
691 *expr-==* *expr-!=* *expr->* *expr->=*
692 *expr-<* *expr-<=* *expr-=~* *expr-!~*
693 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
694 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
695 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
696 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000697 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000698 use 'ignorecase' match case ignore case ~
699equal == ==# ==?
700not equal != !=# !=?
701greater than > ># >?
702greater than or equal >= >=# >=?
703smaller than < <# <?
704smaller than or equal <= <=# <=?
705regexp matches =~ =~# =~?
706regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000707same instance is
708different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000709
710Examples:
711"abc" ==# "Abc" evaluates to 0
712"abc" ==? "Abc" evaluates to 1
713"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
714
Bram Moolenaar13065c42005-01-08 16:08:21 +0000715 *E691* *E692*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000716A List can only be compared with a List and only "equal", "not equal" and "is"
717can be used. This compares the values of the list, recursively. Ignoring
718case means case is ignored when comparing item values.
719
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000720 *E735* *E736*
721A Dictionary can only be compared with a Dictionary and only "equal", "not
722equal" and "is" can be used. This compares the key/values of the Dictionary,
723recursively. Ignoring case means case is ignored when comparing item values.
724
Bram Moolenaar13065c42005-01-08 16:08:21 +0000725 *E693* *E694*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000726A Funcref can only be compared with a Funcref and only "equal" and "not equal"
727can be used. Case is never ignored.
728
729When using "is" or "isnot" with a List this checks if the expressions are
730referring to the same List instance. A copy of a List is different from the
731original List. When using "is" without a List it is equivalent to using
732"equal", using "isnot" equivalent to using "not equal". Except that a
733different type means the values are different. "4 == '4'" is true, "4 is '4'"
734is false.
735
Bram Moolenaar071d4272004-06-13 20:20:40 +0000736When comparing a String with a Number, the String is converted to a Number,
737and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
738because 'x' converted to a Number is zero.
739
740When comparing two Strings, this is done with strcmp() or stricmp(). This
741results in the mathematical difference (comparing byte values), not
742necessarily the alphabetical difference in the local language.
743
744When using the operators with a trailing '#", or the short version and
745'ignorecase' is off, the comparing is done with strcmp().
746
747When using the operators with a trailing '?', or the short version and
748'ignorecase' is set, the comparing is done with stricmp().
749
750The "=~" and "!~" operators match the lefthand argument with the righthand
751argument, which is used as a pattern. See |pattern| for what a pattern is.
752This matching is always done like 'magic' was set and 'cpoptions' is empty, no
753matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
754portable. To avoid backslashes in the regexp pattern to be doubled, use a
755single-quote string, see |literal-string|.
756Since a string is considered to be a single line, a multi-line pattern
757(containing \n, backslash-n) will not match. However, a literal NL character
758can be matched like an ordinary character. Examples:
759 "foo\nbar" =~ "\n" evaluates to 1
760 "foo\nbar" =~ "\\n" evaluates to 0
761
762
763expr5 and expr6 *expr5* *expr6*
764---------------
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000765expr6 + expr6 .. Number addition or List concatenation *expr-+*
766expr6 - expr6 .. Number subtraction *expr--*
767expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000768
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000769For Lists only "+" is possible and then both expr6 must be a list. The result
770is a new list with the two lists Concatenated.
771
772expr7 * expr7 .. number multiplication *expr-star*
773expr7 / expr7 .. number division *expr-/*
774expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000775
776For all, except ".", Strings are converted to Numbers.
777
778Note the difference between "+" and ".":
779 "123" + "456" = 579
780 "123" . "456" = "123456"
781
782When the righthand side of '/' is zero, the result is 0x7fffffff.
783When the righthand side of '%' is zero, the result is 0.
784
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000785None of these work for Funcrefs.
786
Bram Moolenaar071d4272004-06-13 20:20:40 +0000787
788expr7 *expr7*
789-----
790! expr7 logical NOT *expr-!*
791- expr7 unary minus *expr-unary--*
792+ expr7 unary plus *expr-unary-+*
793
794For '!' non-zero becomes zero, zero becomes one.
795For '-' the sign of the number is changed.
796For '+' the number is unchanged.
797
798A String will be converted to a Number first.
799
800These three can be repeated and mixed. Examples:
801 !-1 == 0
802 !!8 == 1
803 --9 == 9
804
805
806expr8 *expr8*
807-----
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000808expr8[expr1] item of String or List *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000809
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000810If expr8 is a Number or String this results in a String that contains the
811expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000812Number. Note that this doesn't recognize multi-byte encodings.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000813
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000814Index zero gives the first character. This is like it works in C. Careful:
815text column numbers start with one! Example, to get the character under the
816cursor: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817 :let c = getline(line("."))[col(".") - 1]
818
819If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000820String. A negative index always results in an empty string (reason: backwards
821compatibility). Use [-1:] to get the last byte.
822
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000823If expr8 is a List then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000824for possible index values. If the index is out of range this results in an
825error. Example: >
826 :let item = mylist[-1] " get last item
827
828Generally, if a List index is equal to or higher than the length of the List,
829or more negative than the length of the List, this results in an error.
830
Bram Moolenaard8b02732005-01-14 21:48:43 +0000831
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000832expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000833
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000834If expr8 is a Number or String this results in the substring with the bytes
835from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000836expr1b are used as a Number. Note that this doesn't recognize multi-byte
837encodings.
838
839If expr1a is omitted zero is used. If expr1b is omitted the length of the
840string minus one is used.
841
842A negative number can be used to measure from the end of the string. -1 is
843the last character, -2 the last but one, etc.
844
845If an index goes out of range for the string characters are omitted. If
846expr1b is smaller than expr1a the result is an empty string.
847
848Examples: >
849 :let c = name[-1:] " last byte of a string
850 :let c = name[-2:-2] " last but one byte of a string
851 :let s = line(".")[4:] " from the fifth byte to the end
852 :let s = s[:-3] " remove last two bytes
853
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000854If expr8 is a List this results in a new List with the items indicated by the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000855indexes expr1a and expr1b. This works like with a String, as explained just
856above, except that indexes out of range cause an error. Examples: >
857 :let l = mylist[:3] " first four items
858 :let l = mylist[4:4] " List with one item
859 :let l = mylist[:] " shallow copy of a List
860
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000861Using expr8[expr1] or expr8[expr1a : expr1b] on a Funcref results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862
Bram Moolenaard8b02732005-01-14 21:48:43 +0000863
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000864expr8.name entry in a Dictionary *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000865
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000866If expr8 is a Dictionary and it is followed by a dot, then the following name
867will be used as a key in the Dictionary. This is just like: expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000868
869The name must consist of alphanumeric characters, just like a variable name,
870but it may start with a number. Curly braces cannot be used.
871
872There must not be white space before or after the dot.
873
874Examples: >
875 :let dict = {"one": 1, 2: "two"}
876 :echo dict.one
877 :echo dict .2
878
879Note that the dot is also used for String concatenation. To avoid confusion
880always put spaces around the dot for String concatenation.
881
882
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000883expr8(expr1, ...) Funcref function call
884
885When expr8 is a |Funcref| type variable, invoke the function it refers to.
886
887
888
889 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000890number
891------
892number number constant *expr-number*
893
894Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
895
896
897string *expr-string* *E114*
898------
899"string" string constant *expr-quote*
900
901Note that double quotes are used.
902
903A string constant accepts these special characters:
904\... three-digit octal number (e.g., "\316")
905\.. two-digit octal number (must be followed by non-digit)
906\. one-digit octal number (must be followed by non-digit)
907\x.. byte specified with two hex numbers (e.g., "\x1f")
908\x. byte specified with one hex number (must be followed by non-hex char)
909\X.. same as \x..
910\X. same as \x.
911\u.... character specified with up to 4 hex numbers, stored according to the
912 current value of 'encoding' (e.g., "\u02a4")
913\U.... same as \u....
914\b backspace <BS>
915\e escape <Esc>
916\f formfeed <FF>
917\n newline <NL>
918\r return <CR>
919\t tab <Tab>
920\\ backslash
921\" double quote
922\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
923
924Note that "\000" and "\x00" force the end of the string.
925
926
927literal-string *literal-string* *E115*
928---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000929'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000930
931Note that single quotes are used.
932
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000933This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000934meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000935
936Single quoted strings are useful for patterns, so that backslashes do not need
937to be doubled. These two commands are equivalent: >
938 if a =~ "\\s*"
939 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000940
941
942option *expr-option* *E112* *E113*
943------
944&option option value, local value if possible
945&g:option global option value
946&l:option local option value
947
948Examples: >
949 echo "tabstop is " . &tabstop
950 if &insertmode
951
952Any option name can be used here. See |options|. When using the local value
953and there is no buffer-local or window-local value, the global value is used
954anyway.
955
956
957register *expr-register*
958--------
959@r contents of register 'r'
960
961The result is the contents of the named register, as a single string.
962Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaare7566042005-06-17 22:00:15 +0000963register use @" or @@. See |registers| for an explanation of the available
964registers.
965
966When using the '=' register you get the expression itself, not what it
967evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968
969
970nesting *expr-nesting* *E110*
971-------
972(expr1) nested expression
973
974
975environment variable *expr-env*
976--------------------
977$VAR environment variable
978
979The String value of any environment variable. When it is not defined, the
980result is an empty string.
981 *expr-env-expand*
982Note that there is a difference between using $VAR directly and using
983expand("$VAR"). Using it directly will only expand environment variables that
984are known inside the current Vim session. Using expand() will first try using
985the environment variables known inside the current Vim session. If that
986fails, a shell will be used to expand the variable. This can be slow, but it
987does expand all variables that the shell knows about. Example: >
988 :echo $version
989 :echo expand("$version")
990The first one probably doesn't echo anything, the second echoes the $version
991variable (if your shell supports it).
992
993
994internal variable *expr-variable*
995-----------------
996variable internal variable
997See below |internal-variables|.
998
999
Bram Moolenaar05159a02005-02-26 23:04:13 +00001000function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001001-------------
1002function(expr1, ...) function call
1003See below |functions|.
1004
1005
1006==============================================================================
10073. Internal variable *internal-variables* *E121*
1008 *E461*
1009An internal variable name can be made up of letters, digits and '_'. But it
1010cannot start with a digit. It's also possible to use curly braces, see
1011|curly-braces-names|.
1012
1013An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001014An internal variable is explicitly destroyed with the ":unlet" command
1015|:unlet|.
1016Using a name that is not an internal variable or refers to a variable that has
1017been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001018
1019There are several name spaces for variables. Which one is to be used is
1020specified by what is prepended:
1021
1022 (nothing) In a function: local to a function; otherwise: global
1023|buffer-variable| b: Local to the current buffer.
1024|window-variable| w: Local to the current window.
1025|global-variable| g: Global.
1026|local-variable| l: Local to a function.
1027|script-variable| s: Local to a |:source|'ed Vim script.
1028|function-argument| a: Function argument (only inside a function).
1029|vim-variable| v: Global, predefined by Vim.
1030
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001031The scope name by itself can be used as a Dictionary. For example, to delete
1032all script-local variables: >
1033 :for k in keys(s:)
1034 : unlet s:[k]
1035 :endfor
1036<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001037 *buffer-variable* *b:var*
1038A variable name that is preceded with "b:" is local to the current buffer.
1039Thus you can have several "b:foo" variables, one for each buffer.
1040This kind of variable is deleted when the buffer is wiped out or deleted with
1041|:bdelete|.
1042
1043One local buffer variable is predefined:
1044 *b:changedtick-variable* *changetick*
1045b:changedtick The total number of changes to the current buffer. It is
1046 incremented for each change. An undo command is also a change
1047 in this case. This can be used to perform an action only when
1048 the buffer has changed. Example: >
1049 :if my_changedtick != b:changedtick
1050 : let my_changedtick = b:changedtick
1051 : call My_Update()
1052 :endif
1053<
1054 *window-variable* *w:var*
1055A variable name that is preceded with "w:" is local to the current window. It
1056is deleted when the window is closed.
1057
1058 *global-variable* *g:var*
1059Inside functions global variables are accessed with "g:". Omitting this will
1060access a variable local to a function. But "g:" can also be used in any other
1061place if you like.
1062
1063 *local-variable* *l:var*
1064Inside functions local variables are accessed without prepending anything.
1065But you can also prepend "l:" if you like.
1066
1067 *script-variable* *s:var*
1068In a Vim script variables starting with "s:" can be used. They cannot be
1069accessed from outside of the scripts, thus are local to the script.
1070
1071They can be used in:
1072- commands executed while the script is sourced
1073- functions defined in the script
1074- autocommands defined in the script
1075- functions and autocommands defined in functions and autocommands which were
1076 defined in the script (recursively)
1077- user defined commands defined in the script
1078Thus not in:
1079- other scripts sourced from this one
1080- mappings
1081- etc.
1082
1083script variables can be used to avoid conflicts with global variable names.
1084Take this example:
1085
1086 let s:counter = 0
1087 function MyCounter()
1088 let s:counter = s:counter + 1
1089 echo s:counter
1090 endfunction
1091 command Tick call MyCounter()
1092
1093You can now invoke "Tick" from any script, and the "s:counter" variable in
1094that script will not be changed, only the "s:counter" in the script where
1095"Tick" was defined is used.
1096
1097Another example that does the same: >
1098
1099 let s:counter = 0
1100 command Tick let s:counter = s:counter + 1 | echo s:counter
1101
1102When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001103script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001104defined.
1105
1106The script variables are also available when a function is defined inside a
1107function that is defined in a script. Example: >
1108
1109 let s:counter = 0
1110 function StartCounting(incr)
1111 if a:incr
1112 function MyCounter()
1113 let s:counter = s:counter + 1
1114 endfunction
1115 else
1116 function MyCounter()
1117 let s:counter = s:counter - 1
1118 endfunction
1119 endif
1120 endfunction
1121
1122This defines the MyCounter() function either for counting up or counting down
1123when calling StartCounting(). It doesn't matter from where StartCounting() is
1124called, the s:counter variable will be accessible in MyCounter().
1125
1126When the same script is sourced again it will use the same script variables.
1127They will remain valid as long as Vim is running. This can be used to
1128maintain a counter: >
1129
1130 if !exists("s:counter")
1131 let s:counter = 1
1132 echo "script executed for the first time"
1133 else
1134 let s:counter = s:counter + 1
1135 echo "script executed " . s:counter . " times now"
1136 endif
1137
1138Note that this means that filetype plugins don't get a different set of script
1139variables for each buffer. Use local buffer variables instead |b:var|.
1140
1141
1142Predefined Vim variables: *vim-variable* *v:var*
1143
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001144 *v:beval_col* *beval_col-variable*
1145v:beval_col The number of the column, over which the mouse pointer is.
1146 This is the byte index in the |v:beval_lnum| line.
1147 Only valid while evaluating the 'balloonexpr' option.
1148
1149 *v:beval_bufnr* *beval_bufnr-variable*
1150v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1151 valid while evaluating the 'balloonexpr' option.
1152
1153 *v:beval_lnum* *beval_lnum-variable*
1154v:beval_lnum The number of the line, over which the mouse pointer is. Only
1155 valid while evaluating the 'balloonexpr' option.
1156
1157 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001158v:beval_text The text under or after the mouse pointer. Usually a word as
1159 it is useful for debugging a C program. 'iskeyword' applies,
1160 but a dot and "->" before the position is included. When on a
1161 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001162 word before it. When on a Visual area within one line the
1163 highlighted text is used.
1164 Only valid while evaluating the 'balloonexpr' option.
1165
1166 *v:beval_winnr* *beval_winnr-variable*
1167v:beval_winnr The number of the window, over which the mouse pointer is. Only
1168 valid while evaluating the 'balloonexpr' option.
1169
Bram Moolenaar071d4272004-06-13 20:20:40 +00001170 *v:charconvert_from* *charconvert_from-variable*
1171v:charconvert_from
1172 The name of the character encoding of a file to be converted.
1173 Only valid while evaluating the 'charconvert' option.
1174
1175 *v:charconvert_to* *charconvert_to-variable*
1176v:charconvert_to
1177 The name of the character encoding of a file after conversion.
1178 Only valid while evaluating the 'charconvert' option.
1179
1180 *v:cmdarg* *cmdarg-variable*
1181v:cmdarg This variable is used for two purposes:
1182 1. The extra arguments given to a file read/write command.
1183 Currently these are "++enc=" and "++ff=". This variable is
1184 set before an autocommand event for a file read/write
1185 command is triggered. There is a leading space to make it
1186 possible to append this variable directly after the
1187 read/write command. Note: The "+cmd" argument isn't
1188 included here, because it will be executed anyway.
1189 2. When printing a PostScript file with ":hardcopy" this is
1190 the argument for the ":hardcopy" command. This can be used
1191 in 'printexpr'.
1192
1193 *v:cmdbang* *cmdbang-variable*
1194v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1195 was used the value is 1, otherwise it is 0. Note that this
1196 can only be used in autocommands. For user commands |<bang>|
1197 can be used.
1198
1199 *v:count* *count-variable*
1200v:count The count given for the last Normal mode command. Can be used
1201 to get the count before a mapping. Read-only. Example: >
1202 :map _x :<C-U>echo "the count is " . v:count<CR>
1203< Note: The <C-U> is required to remove the line range that you
1204 get when typing ':' after a count.
1205 "count" also works, for backwards compatibility.
1206
1207 *v:count1* *count1-variable*
1208v:count1 Just like "v:count", but defaults to one when no count is
1209 used.
1210
1211 *v:ctype* *ctype-variable*
1212v:ctype The current locale setting for characters of the runtime
1213 environment. This allows Vim scripts to be aware of the
1214 current locale encoding. Technical: it's the value of
1215 LC_CTYPE. When not using a locale the value is "C".
1216 This variable can not be set directly, use the |:language|
1217 command.
1218 See |multi-lang|.
1219
1220 *v:dying* *dying-variable*
1221v:dying Normally zero. When a deadly signal is caught it's set to
1222 one. When multiple signals are caught the number increases.
1223 Can be used in an autocommand to check if Vim didn't
1224 terminate normally. {only works on Unix}
1225 Example: >
1226 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1227<
1228 *v:errmsg* *errmsg-variable*
1229v:errmsg Last given error message. It's allowed to set this variable.
1230 Example: >
1231 :let v:errmsg = ""
1232 :silent! next
1233 :if v:errmsg != ""
1234 : ... handle error
1235< "errmsg" also works, for backwards compatibility.
1236
1237 *v:exception* *exception-variable*
1238v:exception The value of the exception most recently caught and not
1239 finished. See also |v:throwpoint| and |throw-variables|.
1240 Example: >
1241 :try
1242 : throw "oops"
1243 :catch /.*/
1244 : echo "caught" v:exception
1245 :endtry
1246< Output: "caught oops".
1247
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001248 *v:fcs_reason* *fcs_reason-variable*
1249v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1250 Can be used in an autocommand to decide what to do and/or what
1251 to set v:fcs_choice to. Possible values:
1252 deleted file no longer exists
1253 conflict file contents, mode or timestamp was
1254 changed and buffer is modified
1255 changed file contents has changed
1256 mode mode of file changed
1257 time only file timestamp changed
1258
1259 *v:fcs_choice* *fcs_choice-variable*
1260v:fcs_choice What should happen after a |FileChangedShell| event was
1261 triggered. Can be used in an autocommand to tell Vim what to
1262 do with the affected buffer:
1263 reload Reload the buffer (does not work if
1264 the file was deleted).
1265 ask Ask the user what to do, as if there
1266 was no autocommand. Except that when
1267 only the timestamp changed nothing
1268 will happen.
1269 <empty> Nothing, the autocommand should do
1270 everything that needs to be done.
1271 The default is empty. If another (invalid) value is used then
1272 Vim behaves like it is empty, there is no warning message.
1273
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001275v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001276 option used for ~
1277 'charconvert' file to be converted
1278 'diffexpr' original file
1279 'patchexpr' original file
1280 'printexpr' file to be printed
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001281 And set to the swap file name for |SwapExits|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001282
1283 *v:fname_out* *fname_out-variable*
1284v:fname_out The name of the output file. Only valid while
1285 evaluating:
1286 option used for ~
1287 'charconvert' resulting converted file (*)
1288 'diffexpr' output of diff
1289 'patchexpr' resulting patched file
1290 (*) When doing conversion for a write command (e.g., ":w
1291 file") it will be equal to v:fname_in. When doing conversion
1292 for a read command (e.g., ":e file") it will be a temporary
1293 file and different from v:fname_in.
1294
1295 *v:fname_new* *fname_new-variable*
1296v:fname_new The name of the new version of the file. Only valid while
1297 evaluating 'diffexpr'.
1298
1299 *v:fname_diff* *fname_diff-variable*
1300v:fname_diff The name of the diff (patch) file. Only valid while
1301 evaluating 'patchexpr'.
1302
1303 *v:folddashes* *folddashes-variable*
1304v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1305 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001306 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001307
1308 *v:foldlevel* *foldlevel-variable*
1309v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001310 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001311
1312 *v:foldend* *foldend-variable*
1313v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001314 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001315
1316 *v:foldstart* *foldstart-variable*
1317v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001318 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001319
Bram Moolenaar843ee412004-06-30 16:16:41 +00001320 *v:insertmode* *insertmode-variable*
1321v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1322 events. Values:
1323 i Insert mode
1324 r Replace mode
1325 v Virtual Replace mode
1326
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001327 *v:key* *key-variable*
1328v:key Key of the current item of a Dictionary. Only valid while
1329 evaluating the expression used with |map()| and |filter()|.
1330 Read-only.
1331
Bram Moolenaar071d4272004-06-13 20:20:40 +00001332 *v:lang* *lang-variable*
1333v:lang The current locale setting for messages of the runtime
1334 environment. This allows Vim scripts to be aware of the
1335 current language. Technical: it's the value of LC_MESSAGES.
1336 The value is system dependent.
1337 This variable can not be set directly, use the |:language|
1338 command.
1339 It can be different from |v:ctype| when messages are desired
1340 in a different language than what is used for character
1341 encoding. See |multi-lang|.
1342
1343 *v:lc_time* *lc_time-variable*
1344v:lc_time The current locale setting for time messages of the runtime
1345 environment. This allows Vim scripts to be aware of the
1346 current language. Technical: it's the value of LC_TIME.
1347 This variable can not be set directly, use the |:language|
1348 command. See |multi-lang|.
1349
1350 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001351v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1352 expressions. Only valid while one of these expressions is
1353 being evaluated. Read-only when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001354
1355 *v:prevcount* *prevcount-variable*
1356v:prevcount The count given for the last but one Normal mode command.
1357 This is the v:count value of the previous command. Useful if
1358 you want to cancel Visual mode and then use the count. >
1359 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1360< Read-only.
1361
Bram Moolenaar05159a02005-02-26 23:04:13 +00001362 *v:profiling* *profiling-variable*
1363v:profiling Normally zero. Set to one after using ":profile start".
1364 See |profiling|.
1365
Bram Moolenaar071d4272004-06-13 20:20:40 +00001366 *v:progname* *progname-variable*
1367v:progname Contains the name (with path removed) with which Vim was
1368 invoked. Allows you to do special initialisations for "view",
1369 "evim" etc., or any other name you might symlink to Vim.
1370 Read-only.
1371
1372 *v:register* *register-variable*
1373v:register The name of the register supplied to the last normal mode
1374 command. Empty if none were supplied. |getreg()| |setreg()|
1375
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001376 *v:scrollstart* *scrollstart-variable*
1377v:scrollstart String describing the script or function that caused the
1378 screen to scroll up. It's only set when it is empty, thus the
1379 first reason is remembered. It is set to "Unknown" for a
1380 typed command.
1381 This can be used to find out why your script causes the
1382 hit-enter prompt.
1383
Bram Moolenaar071d4272004-06-13 20:20:40 +00001384 *v:servername* *servername-variable*
1385v:servername The resulting registered |x11-clientserver| name if any.
1386 Read-only.
1387
1388 *v:shell_error* *shell_error-variable*
1389v:shell_error Result of the last shell command. When non-zero, the last
1390 shell command had an error. When zero, there was no problem.
1391 This only works when the shell returns the error code to Vim.
1392 The value -1 is often used when the command could not be
1393 executed. Read-only.
1394 Example: >
1395 :!mv foo bar
1396 :if v:shell_error
1397 : echo 'could not rename "foo" to "bar"!'
1398 :endif
1399< "shell_error" also works, for backwards compatibility.
1400
1401 *v:statusmsg* *statusmsg-variable*
1402v:statusmsg Last given status message. It's allowed to set this variable.
1403
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001404 *v:swapname* *swapname-variable*
1405v:swapname Only valid when executing |SwapExists| autocommands: Name of
1406 the swap file found. Read-only.
1407
1408 *v:swapchoice* *swapchoice-variable*
1409v:swapchoice |SwapExists| autocommands can set this to the selected choice
1410 for handling an existing swap file:
1411 'o' Open read-only
1412 'e' Edit anyway
1413 'r' Recover
1414 'd' Delete swapfile
1415 'q' Quit
1416 'a' Abort
1417 The value should be a single-character string. An empty value
1418 results in the user being asked, as would happen when there is
1419 no SwapExists autocommand. The default is empty.
1420
Bram Moolenaarb3480382005-12-11 21:33:32 +00001421 *v:swapcommand* *swapcommand-variable*
1422v:swapcommand Normal mode ommand to be executed after a file has been
1423 opened. Can be used for a |SwapExists| autocommand to have
1424 another Vim open the file and jump to the right place. For
1425 example, when jumping to a tag the value is ":tag tagname\r".
1426
Bram Moolenaar071d4272004-06-13 20:20:40 +00001427 *v:termresponse* *termresponse-variable*
1428v:termresponse The escape sequence returned by the terminal for the |t_RV|
1429 termcap entry. It is set when Vim receives an escape sequence
1430 that starts with ESC [ or CSI and ends in a 'c', with only
1431 digits, ';' and '.' in between.
1432 When this option is set, the TermResponse autocommand event is
1433 fired, so that you can react to the response from the
1434 terminal.
1435 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1436 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1437 patch level (since this was introduced in patch 95, it's
1438 always 95 or bigger). Pc is always zero.
1439 {only when compiled with |+termresponse| feature}
1440
1441 *v:this_session* *this_session-variable*
1442v:this_session Full filename of the last loaded or saved session file. See
1443 |:mksession|. It is allowed to set this variable. When no
1444 session file has been saved, this variable is empty.
1445 "this_session" also works, for backwards compatibility.
1446
1447 *v:throwpoint* *throwpoint-variable*
1448v:throwpoint The point where the exception most recently caught and not
1449 finished was thrown. Not set when commands are typed. See
1450 also |v:exception| and |throw-variables|.
1451 Example: >
1452 :try
1453 : throw "oops"
1454 :catch /.*/
1455 : echo "Exception from" v:throwpoint
1456 :endtry
1457< Output: "Exception from test.vim, line 2"
1458
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001459 *v:val* *val-variable*
1460v:val Value of the current item of a List or Dictionary. Only valid
1461 while evaluating the expression used with |map()| and
1462 |filter()|. Read-only.
1463
Bram Moolenaar071d4272004-06-13 20:20:40 +00001464 *v:version* *version-variable*
1465v:version Version number of Vim: Major version number times 100 plus
1466 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1467 is 501. Read-only. "version" also works, for backwards
1468 compatibility.
1469 Use |has()| to check if a certain patch was included, e.g.: >
1470 if has("patch123")
1471< Note that patch numbers are specific to the version, thus both
1472 version 5.0 and 5.1 may have a patch 123, but these are
1473 completely different.
1474
1475 *v:warningmsg* *warningmsg-variable*
1476v:warningmsg Last given warning message. It's allowed to set this variable.
1477
1478==============================================================================
14794. Builtin Functions *functions*
1480
1481See |function-list| for a list grouped by what the function is used for.
1482
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001483(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001484
1485USAGE RESULT DESCRIPTION ~
1486
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001487add( {list}, {item}) List append {item} to List {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001488append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001489append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001490argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001491argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001492argv( {nr}) String {nr} entry of the argument list
1493browse( {save}, {title}, {initdir}, {default})
1494 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001495browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001496bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001497buflisted( {expr}) Number TRUE if buffer {expr} is listed
1498bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001499bufname( {expr}) String Name of the buffer {expr}
1500bufnr( {expr}) Number Number of the buffer {expr}
1501bufwinnr( {expr}) Number window number of buffer {expr}
1502byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001503byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001504call( {func}, {arglist} [, {dict}])
1505 any call {func} with arguments {arglist}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001506char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001507cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001508col( {expr}) Number column nr of cursor or mark
Bram Moolenaar572cb562005-08-05 21:35:02 +00001509complete_add( {expr}) Number add completion match
1510complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511confirm( {msg} [, {choices} [, {default} [, {type}]]])
1512 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001513copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001514count( {list}, {expr} [, {start} [, {ic}]])
1515 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001516cscope_connection( [{num} , {dbpath} [, {prepend}]])
1517 Number checks existence of cscope connection
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001518cursor( {lnum}, {col}) Number position cursor at {lnum}, {col}
1519deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001520delete( {fname}) Number delete file {fname}
1521did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001522diff_filler( {lnum}) Number diff filler lines about {lnum}
1523diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001524empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001526eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001527eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001528executable( {expr}) Number 1 if executable {expr} exists
1529exists( {expr}) Number TRUE if {expr} exists
1530expand( {expr}) String expand special keywords in {expr}
1531filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001532filter( {expr}, {string}) List/Dict remove items from {expr} where
1533 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001534finddir( {name}[, {path}[, {count}]])
1535 String Find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001536findfile( {name}[, {path}[, {count}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001537 String Find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001538filewritable( {file}) Number TRUE if {file} is a writable file
1539fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001540foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1541foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001542foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001543foldtext( ) String line displayed for closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +00001544foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001545function( {name}) Funcref reference to function {name}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001546get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001547get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001548getbufline( {expr}, {lnum} [, {end}])
1549 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001550getchar( [expr]) Number get one character from the user
1551getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001552getbufvar( {expr}, {varname}) variable {varname} in buffer {expr}
1553getcmdline() String return the current command-line
1554getcmdpos() Number return cursor position in command-line
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001555getcmdtype() String return the current command-line type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001556getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001557getfperm( {fname}) String file permissions of file {fname}
1558getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001559getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001561getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001562getline( {lnum}) String line {lnum} of current buffer
1563getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001564getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001565getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001566getregtype( [{regname}]) String type of register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001567getwinposx() Number X coord in pixels of GUI Vim window
1568getwinposy() Number Y coord in pixels of GUI Vim window
1569getwinvar( {nr}, {varname}) variable {varname} in window {nr}
1570glob( {expr}) String expand file wildcards in {expr}
1571globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1572has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001573has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574hasmapto( {what} [, {mode}]) Number TRUE if mapping to {what} exists
1575histadd( {history},{item}) String add an item to a history
1576histdel( {history} [, {item}]) String remove an item from a history
1577histget( {history} [, {index}]) String get the item {index} from a history
1578histnr( {history}) Number highest index of a history
1579hlexists( {name}) Number TRUE if highlight group {name} exists
1580hlID( {name}) Number syntax ID of highlight group {name}
1581hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001582iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1583indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001584index( {list}, {expr} [, {start} [, {ic}]])
1585 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001586input( {prompt} [, {text} [, {completion}]])
1587 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001588inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001589inputrestore() Number restore typeahead
1590inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001591inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001592insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001593isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001594islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar677ee682005-01-27 14:41:15 +00001595items( {dict}) List List of key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001596join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaard8b02732005-01-14 21:48:43 +00001597keys( {dict}) List List of keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001598len( {expr}) Number the length of {expr}
1599libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001600libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1601line( {expr}) Number line nr of cursor, last line or mark
1602line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001603lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001604localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001605map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001606maparg( {name}[, {mode}]) String rhs of mapping {name} in mode {mode}
1607mapcheck( {name}[, {mode}]) String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001608match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001609 Number position where {pat} matches in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001610matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001611 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001612matchlist( {expr}, {pat}[, {start}[, {count}]])
1613 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001614matchstr( {expr}, {pat}[, {start}[, {count}]])
1615 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001616max({list}) Number maximum value of items in {list}
1617min({list}) Number minumum value of items in {list}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001618mkdir({name} [, {path} [, {prot}]])
1619 Number create directory {name}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001620mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001621nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1622nr2char( {expr}) String single char with ASCII value {expr}
1623prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001624printf( {fmt}, {expr1}...) String format text
Bram Moolenaard8b02732005-01-14 21:48:43 +00001625range( {expr} [, {max} [, {stride}]])
1626 List items from {expr} to {max}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001627readfile({fname} [, {binary} [, {max}]])
1628 List get list of lines from file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001629remote_expr( {server}, {string} [, {idvar}])
1630 String send expression
1631remote_foreground( {server}) Number bring Vim server to the foreground
1632remote_peek( {serverid} [, {retvar}])
1633 Number check for reply string
1634remote_read( {serverid}) String read reply string
1635remote_send( {server}, {string} [, {idvar}])
1636 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001637remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001638remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001639rename( {from}, {to}) Number rename (move) file from {from} to {to}
1640repeat( {expr}, {count}) String repeat {expr} {count} times
1641resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001642reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001643search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001644searchdecl({name} [, {global} [, {thisblock}]])
1645 Number search for variable declaration
Bram Moolenaar071d4272004-06-13 20:20:40 +00001646searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001647 Number search for other end of start/end pair
Bram Moolenaar071d4272004-06-13 20:20:40 +00001648server2client( {clientid}, {string})
1649 Number send reply string
1650serverlist() String get a list of available servers
1651setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1652setcmdpos( {pos}) Number set cursor position in command-line
1653setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar35c54e52005-05-20 21:25:31 +00001654setqflist( {list}[, {action}]) Number set list of quickfix items using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001655setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001656setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001657simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001658sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001659soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001660spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00001661spellsuggest( {word} [, {max} [, {capital}]])
1662 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001663split( {expr} [, {pat} [, {keepempty}]])
1664 List make List from {pat} separated {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001665strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001666stridx( {haystack}, {needle}[, {start}])
1667 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001668string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001669strlen( {expr}) Number length of the String {expr}
1670strpart( {src}, {start}[, {len}])
1671 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001672strridx( {haystack}, {needle} [, {start}])
1673 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001674strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001675submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001676substitute( {expr}, {pat}, {sub}, {flags})
1677 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001678synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001679synIDattr( {synID}, {what} [, {mode}])
1680 String attribute {what} of syntax ID {synID}
1681synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001682system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00001683taglist( {expr}) List list of tags matching {expr}
1684tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001685tempname() String name for a temporary file
1686tolower( {expr}) String the String {expr} switched to lowercase
1687toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001688tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1689 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001690type( {name}) Number type of variable {name}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001691values( {dict}) List List of values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001692virtcol( {expr}) Number screen column of cursor or mark
1693visualmode( [expr]) String last visual mode used
1694winbufnr( {nr}) Number buffer number of window {nr}
1695wincol() Number window column of the cursor
1696winheight( {nr}) Number height of window {nr}
1697winline() Number window line of the cursor
1698winnr() Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001699winrestcmd() String returns command to restore window sizes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001700winwidth( {nr}) Number width of window {nr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001701writefile({list}, {fname} [, {binary}])
1702 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001703
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001704add({list}, {expr}) *add()*
1705 Append the item {expr} to List {list}. Returns the resulting
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001706 List. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001707 :let alist = add([1, 2, 3], item)
1708 :call add(mylist, "woodstock")
1709< Note that when {expr} is a List it is appended as a single
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001710 item. Use |extend()| to concatenate Lists.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001711 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001712
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001713
1714append({lnum}, {expr}) *append()*
Bram Moolenaar748bf032005-02-02 23:04:36 +00001715 When {expr} is a List: Append each item of the List as a text
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001716 line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00001717 Otherwise append {expr} as one text line below line {lnum} in
1718 the current buffer.
1719 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001720 Returns 1 for failure ({lnum} out of range or out of memory),
1721 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001722 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001723 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001724<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001725 *argc()*
1726argc() The result is the number of files in the argument list of the
1727 current window. See |arglist|.
1728
1729 *argidx()*
1730argidx() The result is the current index in the argument list. 0 is
1731 the first file. argc() - 1 is the last one. See |arglist|.
1732
1733 *argv()*
1734argv({nr}) The result is the {nr}th file in the argument list of the
1735 current window. See |arglist|. "argv(0)" is the first one.
1736 Example: >
1737 :let i = 0
1738 :while i < argc()
1739 : let f = escape(argv(i), '. ')
1740 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1741 : let i = i + 1
1742 :endwhile
1743<
1744 *browse()*
1745browse({save}, {title}, {initdir}, {default})
1746 Put up a file requester. This only works when "has("browse")"
1747 returns non-zero (only in some GUI versions).
1748 The input fields are:
1749 {save} when non-zero, select file to write
1750 {title} title for the requester
1751 {initdir} directory to start browsing in
1752 {default} default file name
1753 When the "Cancel" button is hit, something went wrong, or
1754 browsing is not possible, an empty string is returned.
1755
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001756 *browsedir()*
1757browsedir({title}, {initdir})
1758 Put up a directory requester. This only works when
1759 "has("browse")" returns non-zero (only in some GUI versions).
1760 On systems where a directory browser is not supported a file
1761 browser is used. In that case: select a file in the directory
1762 to be used.
1763 The input fields are:
1764 {title} title for the requester
1765 {initdir} directory to start browsing in
1766 When the "Cancel" button is hit, something went wrong, or
1767 browsing is not possible, an empty string is returned.
1768
Bram Moolenaar071d4272004-06-13 20:20:40 +00001769bufexists({expr}) *bufexists()*
1770 The result is a Number, which is non-zero if a buffer called
1771 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001772 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001774 exactly. The name can be:
1775 - Relative to the current directory.
1776 - A full path.
1777 - The name of a buffer with 'filetype' set to "nofile".
1778 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001779 Unlisted buffers will be found.
1780 Note that help files are listed by their short name in the
1781 output of |:buffers|, but bufexists() requires using their
1782 long name to be able to find them.
1783 Use "bufexists(0)" to test for the existence of an alternate
1784 file name.
1785 *buffer_exists()*
1786 Obsolete name: buffer_exists().
1787
1788buflisted({expr}) *buflisted()*
1789 The result is a Number, which is non-zero if a buffer called
1790 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001791 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001792
1793bufloaded({expr}) *bufloaded()*
1794 The result is a Number, which is non-zero if a buffer called
1795 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001796 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001797
1798bufname({expr}) *bufname()*
1799 The result is the name of a buffer, as it is displayed by the
1800 ":ls" command.
1801 If {expr} is a Number, that buffer number's name is given.
1802 Number zero is the alternate buffer for the current window.
1803 If {expr} is a String, it is used as a |file-pattern| to match
1804 with the buffer names. This is always done like 'magic' is
1805 set and 'cpoptions' is empty. When there is more than one
1806 match an empty string is returned.
1807 "" or "%" can be used for the current buffer, "#" for the
1808 alternate buffer.
1809 A full match is preferred, otherwise a match at the start, end
1810 or middle of the buffer name is accepted.
1811 Listed buffers are found first. If there is a single match
1812 with a listed buffer, that one is returned. Next unlisted
1813 buffers are searched for.
1814 If the {expr} is a String, but you want to use it as a buffer
1815 number, force it to be a Number by adding zero to it: >
1816 :echo bufname("3" + 0)
1817< If the buffer doesn't exist, or doesn't have a name, an empty
1818 string is returned. >
1819 bufname("#") alternate buffer name
1820 bufname(3) name of buffer 3
1821 bufname("%") name of current buffer
1822 bufname("file2") name of buffer where "file2" matches.
1823< *buffer_name()*
1824 Obsolete name: buffer_name().
1825
1826 *bufnr()*
1827bufnr({expr}) The result is the number of a buffer, as it is displayed by
1828 the ":ls" command. For the use of {expr}, see |bufname()|
1829 above. If the buffer doesn't exist, -1 is returned.
1830 bufnr("$") is the last buffer: >
1831 :let last_buffer = bufnr("$")
1832< The result is a Number, which is the highest buffer number
1833 of existing buffers. Note that not all buffers with a smaller
1834 number necessarily exist, because ":bwipeout" may have removed
1835 them. Use bufexists() to test for the existence of a buffer.
1836 *buffer_number()*
1837 Obsolete name: buffer_number().
1838 *last_buffer_nr()*
1839 Obsolete name for bufnr("$"): last_buffer_nr().
1840
1841bufwinnr({expr}) *bufwinnr()*
1842 The result is a Number, which is the number of the first
1843 window associated with buffer {expr}. For the use of {expr},
1844 see |bufname()| above. If buffer {expr} doesn't exist or
1845 there is no such window, -1 is returned. Example: >
1846
1847 echo "A window containing buffer 1 is " . (bufwinnr(1))
1848
1849< The number can be used with |CTRL-W_w| and ":wincmd w"
1850 |:wincmd|.
1851
1852
1853byte2line({byte}) *byte2line()*
1854 Return the line number that contains the character at byte
1855 count {byte} in the current buffer. This includes the
1856 end-of-line character, depending on the 'fileformat' option
1857 for the current buffer. The first character has byte count
1858 one.
1859 Also see |line2byte()|, |go| and |:goto|.
1860 {not available when compiled without the |+byte_offset|
1861 feature}
1862
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001863byteidx({expr}, {nr}) *byteidx()*
1864 Return byte index of the {nr}'th character in the string
1865 {expr}. Use zero for the first character, it returns zero.
1866 This function is only useful when there are multibyte
1867 characters, otherwise the returned value is equal to {nr}.
1868 Composing characters are counted as a separate character.
1869 Example : >
1870 echo matchstr(str, ".", byteidx(str, 3))
1871< will display the fourth character. Another way to do the
1872 same: >
1873 let s = strpart(str, byteidx(str, 3))
1874 echo strpart(s, 0, byteidx(s, 1))
1875< If there are less than {nr} characters -1 is returned.
1876 If there are exactly {nr} characters the length of the string
1877 is returned.
1878
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001879call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001880 Call function {func} with the items in List {arglist} as
1881 arguments.
1882 {func} can either be a Funcref or the name of a function.
1883 a:firstline and a:lastline are set to the cursor line.
1884 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001885 {dict} is for functions with the "dict" attribute. It will be
1886 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001887
Bram Moolenaar071d4272004-06-13 20:20:40 +00001888char2nr({expr}) *char2nr()*
1889 Return number value of the first char in {expr}. Examples: >
1890 char2nr(" ") returns 32
1891 char2nr("ABC") returns 65
1892< The current 'encoding' is used. Example for "utf-8": >
1893 char2nr("á") returns 225
1894 char2nr("á"[0]) returns 195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001895< nr2char() does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001896
1897cindent({lnum}) *cindent()*
1898 Get the amount of indent for line {lnum} according the C
1899 indenting rules, as with 'cindent'.
1900 The indent is counted in spaces, the value of 'tabstop' is
1901 relevant. {lnum} is used just like in |getline()|.
1902 When {lnum} is invalid or Vim was not compiled the |+cindent|
1903 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00001904 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001905
1906 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001907col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001908 position given with {expr}. The accepted positions are:
1909 . the cursor position
1910 $ the end of the cursor line (the result is the
1911 number of characters in the cursor line plus one)
1912 'x position of mark x (if the mark is not set, 0 is
1913 returned)
1914 For the screen column position use |virtcol()|.
1915 Note that only marks in the current file can be used.
1916 Examples: >
1917 col(".") column of cursor
1918 col("$") length of cursor line plus one
1919 col("'t") column of mark t
1920 col("'" . markname) column of mark markname
1921< The first column is 1. 0 is returned for an error.
1922 For the cursor position, when 'virtualedit' is active, the
1923 column is one higher if the cursor is after the end of the
1924 line. This can be used to obtain the column in Insert mode: >
1925 :imap <F2> <C-O>:let save_ve = &ve<CR>
1926 \<C-O>:set ve=all<CR>
1927 \<C-O>:echo col(".") . "\n" <Bar>
1928 \let &ve = save_ve<CR>
1929<
Bram Moolenaar572cb562005-08-05 21:35:02 +00001930
1931complete_add({expr}) *complete_add()*
1932 Add {expr} to the list of matches. Only to be used by the
1933 function specified with the 'completefunc' option.
1934 Returns 0 for failure (empty string or out of memory),
1935 1 when the match was added, 2 when the match was already in
1936 the list.
1937
1938complete_check() *complete_check()*
1939 Check for a key typed while looking for completion matches.
1940 This is to be used when looking for matches takes some time.
1941 Returns non-zero when searching for matches is to be aborted,
1942 zero otherwise.
1943 Only to be used by the function specified with the
1944 'completefunc' option.
1945
Bram Moolenaar071d4272004-06-13 20:20:40 +00001946 *confirm()*
1947confirm({msg} [, {choices} [, {default} [, {type}]]])
1948 Confirm() offers the user a dialog, from which a choice can be
1949 made. It returns the number of the choice. For the first
1950 choice this is 1.
1951 Note: confirm() is only supported when compiled with dialog
1952 support, see |+dialog_con| and |+dialog_gui|.
1953 {msg} is displayed in a |dialog| with {choices} as the
1954 alternatives. When {choices} is missing or empty, "&OK" is
1955 used (and translated).
1956 {msg} is a String, use '\n' to include a newline. Only on
1957 some systems the string is wrapped when it doesn't fit.
1958 {choices} is a String, with the individual choices separated
1959 by '\n', e.g. >
1960 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1961< The letter after the '&' is the shortcut key for that choice.
1962 Thus you can type 'c' to select "Cancel". The shortcut does
1963 not need to be the first letter: >
1964 confirm("file has been modified", "&Save\nSave &All")
1965< For the console, the first letter of each choice is used as
1966 the default shortcut key.
1967 The optional {default} argument is the number of the choice
1968 that is made if the user hits <CR>. Use 1 to make the first
1969 choice the default one. Use 0 to not set a default. If
1970 {default} is omitted, 1 is used.
1971 The optional {type} argument gives the type of dialog. This
1972 is only used for the icon of the Win32 GUI. It can be one of
1973 these values: "Error", "Question", "Info", "Warning" or
1974 "Generic". Only the first character is relevant. When {type}
1975 is omitted, "Generic" is used.
1976 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1977 or another valid interrupt key, confirm() returns 0.
1978
1979 An example: >
1980 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1981 :if choice == 0
1982 : echo "make up your mind!"
1983 :elseif choice == 3
1984 : echo "tasteful"
1985 :else
1986 : echo "I prefer bananas myself."
1987 :endif
1988< In a GUI dialog, buttons are used. The layout of the buttons
1989 depends on the 'v' flag in 'guioptions'. If it is included,
1990 the buttons are always put vertically. Otherwise, confirm()
1991 tries to put the buttons in one horizontal line. If they
1992 don't fit, a vertical layout is used anyway. For some systems
1993 the horizontal layout is always used.
1994
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001995 *copy()*
1996copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1997 different from using {expr} directly.
1998 When {expr} is a List a shallow copy is created. This means
1999 that the original List can be changed without changing the
2000 copy, and vise versa. But the items are identical, thus
2001 changing an item changes the contents of both Lists. Also see
2002 |deepcopy()|.
2003
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002004count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002005 Return the number of times an item with value {expr} appears
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002006 in List or Dictionary {comp}.
2007 If {start} is given then start with the item with this index.
2008 {start} can only be used with a List.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002009 When {ic} is given and it's non-zero then case is ignored.
2010
2011
Bram Moolenaar071d4272004-06-13 20:20:40 +00002012 *cscope_connection()*
2013cscope_connection([{num} , {dbpath} [, {prepend}]])
2014 Checks for the existence of a |cscope| connection. If no
2015 parameters are specified, then the function returns:
2016 0, if cscope was not available (not compiled in), or
2017 if there are no cscope connections;
2018 1, if there is at least one cscope connection.
2019
2020 If parameters are specified, then the value of {num}
2021 determines how existence of a cscope connection is checked:
2022
2023 {num} Description of existence check
2024 ----- ------------------------------
2025 0 Same as no parameters (e.g., "cscope_connection()").
2026 1 Ignore {prepend}, and use partial string matches for
2027 {dbpath}.
2028 2 Ignore {prepend}, and use exact string matches for
2029 {dbpath}.
2030 3 Use {prepend}, use partial string matches for both
2031 {dbpath} and {prepend}.
2032 4 Use {prepend}, use exact string matches for both
2033 {dbpath} and {prepend}.
2034
2035 Note: All string comparisons are case sensitive!
2036
2037 Examples. Suppose we had the following (from ":cs show"): >
2038
2039 # pid database name prepend path
2040 0 27664 cscope.out /usr/local
2041<
2042 Invocation Return Val ~
2043 ---------- ---------- >
2044 cscope_connection() 1
2045 cscope_connection(1, "out") 1
2046 cscope_connection(2, "out") 0
2047 cscope_connection(3, "out") 0
2048 cscope_connection(3, "out", "local") 1
2049 cscope_connection(4, "out") 0
2050 cscope_connection(4, "out", "local") 0
2051 cscope_connection(4, "cscope.out", "/usr/local") 1
2052<
2053cursor({lnum}, {col}) *cursor()*
2054 Positions the cursor at the column {col} in the line {lnum}.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002055 The first column is one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002056 Does not change the jumplist.
2057 If {lnum} is greater than the number of lines in the buffer,
2058 the cursor will be positioned at the last line in the buffer.
2059 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002060 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002061 the cursor will be positioned at the last character in the
2062 line.
2063 If {col} is zero, the cursor will stay in the current column.
2064
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002065
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002066deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002067 Make a copy of {expr}. For Numbers and Strings this isn't
2068 different from using {expr} directly.
2069 When {expr} is a List a full copy is created. This means
2070 that the original List can be changed without changing the
2071 copy, and vise versa. When an item is a List, a copy for it
2072 is made, recursively. Thus changing an item in the copy does
2073 not change the contents of the original List.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002074 When {noref} is omitted or zero a contained List or Dictionary
2075 is only copied once. All references point to this single
2076 copy. With {noref} set to 1 every occurrence of a List or
2077 Dictionary results in a new copy. This also means that a
2078 cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002079 *E724*
2080 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002081 that refers back to a higher level making a deep copy with
2082 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002083 Also see |copy()|.
2084
2085delete({fname}) *delete()*
2086 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002087 which is 0 if the file was deleted successfully, and non-zero
2088 when the deletion failed.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002089 Use |remove()| to delete an item from a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002090
2091 *did_filetype()*
2092did_filetype() Returns non-zero when autocommands are being executed and the
2093 FileType event has been triggered at least once. Can be used
2094 to avoid triggering the FileType event again in the scripts
2095 that detect the file type. |FileType|
2096 When editing another file, the counter is reset, thus this
2097 really checks if the FileType event has been triggered for the
2098 current buffer. This allows an autocommand that starts
2099 editing another buffer to set 'filetype' and load a syntax
2100 file.
2101
Bram Moolenaar47136d72004-10-12 20:02:24 +00002102diff_filler({lnum}) *diff_filler()*
2103 Returns the number of filler lines above line {lnum}.
2104 These are the lines that were inserted at this point in
2105 another diff'ed window. These filler lines are shown in the
2106 display but don't exist in the buffer.
2107 {lnum} is used like with |getline()|. Thus "." is the current
2108 line, "'m" mark m, etc.
2109 Returns 0 if the current window is not in diff mode.
2110
2111diff_hlID({lnum}, {col}) *diff_hlID()*
2112 Returns the highlight ID for diff mode at line {lnum} column
2113 {col} (byte index). When the current line does not have a
2114 diff change zero is returned.
2115 {lnum} is used like with |getline()|. Thus "." is the current
2116 line, "'m" mark m, etc.
2117 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2118 line.
2119 The highlight ID can be used with |synIDattr()| to obtain
2120 syntax information about the highlighting.
2121
Bram Moolenaar13065c42005-01-08 16:08:21 +00002122empty({expr}) *empty()*
2123 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002124 A List or Dictionary is empty when it does not have any items.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002125 A Number is empty when its value is zero.
2126 For a long List this is much faster then comparing the length
2127 with zero.
2128
Bram Moolenaar071d4272004-06-13 20:20:40 +00002129escape({string}, {chars}) *escape()*
2130 Escape the characters in {chars} that occur in {string} with a
2131 backslash. Example: >
2132 :echo escape('c:\program files\vim', ' \')
2133< results in: >
2134 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002135
2136< *eval()*
2137eval({string}) Evaluate {string} and return the result. Especially useful to
2138 turn the result of |string()| back into the original value.
2139 This works for Numbers, Strings and composites of them.
2140 Also works for Funcrefs that refer to existing functions.
2141
Bram Moolenaar071d4272004-06-13 20:20:40 +00002142eventhandler() *eventhandler()*
2143 Returns 1 when inside an event handler. That is that Vim got
2144 interrupted while waiting for the user to type a character,
2145 e.g., when dropping a file on Vim. This means interactive
2146 commands cannot be used. Otherwise zero is returned.
2147
2148executable({expr}) *executable()*
2149 This function checks if an executable with the name {expr}
2150 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002151 arguments.
2152 executable() uses the value of $PATH and/or the normal
2153 searchpath for programs. *PATHEXT*
2154 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2155 optionally be included. Then the extensions in $PATHEXT are
2156 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2157 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2158 used. A dot by itself can be used in $PATHEXT to try using
2159 the name without an extension. When 'shell' looks like a
2160 Unix shell, then the name is also tried without adding an
2161 extension.
2162 On MS-DOS and MS-Windows it only checks if the file exists and
2163 is not a directory, not if it's really executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002164 The result is a Number:
2165 1 exists
2166 0 does not exist
2167 -1 not implemented on this system
2168
2169 *exists()*
2170exists({expr}) The result is a Number, which is non-zero if {expr} is
2171 defined, zero otherwise. The {expr} argument is a string,
2172 which contains one of these:
2173 &option-name Vim option (only checks if it exists,
2174 not if it really works)
2175 +option-name Vim option that works.
2176 $ENVNAME environment variable (could also be
2177 done by comparing with an empty
2178 string)
2179 *funcname built-in function (see |functions|)
2180 or user defined function (see
2181 |user-functions|).
2182 varname internal variable (see
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002183 |internal-variables|). Also works
2184 for |curly-braces-names|, Dictionary
2185 entries, List items, etc. Beware that
2186 this may cause functions to be
2187 invoked cause an error message for an
2188 invalid expression.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002189 :cmdname Ex command: built-in command, user
2190 command or command modifier |:command|.
2191 Returns:
2192 1 for match with start of a command
2193 2 full match with a command
2194 3 matches several user commands
2195 To check for a supported command
2196 always check the return value to be 2.
2197 #event autocommand defined for this event
2198 #event#pattern autocommand defined for this event and
2199 pattern (the pattern is taken
2200 literally and compared to the
2201 autocommand patterns character by
2202 character)
2203 For checking for a supported feature use |has()|.
2204
2205 Examples: >
2206 exists("&shortname")
2207 exists("$HOSTNAME")
2208 exists("*strftime")
2209 exists("*s:MyFunc")
2210 exists("bufcount")
2211 exists(":Make")
2212 exists("#CursorHold");
2213 exists("#BufReadPre#*.gz")
2214< There must be no space between the symbol (&/$/*/#) and the
2215 name.
2216 Note that the argument must be a string, not the name of the
2217 variable itself! For example: >
2218 exists(bufcount)
2219< This doesn't check for existence of the "bufcount" variable,
2220 but gets the contents of "bufcount", and checks if that
2221 exists.
2222
2223expand({expr} [, {flag}]) *expand()*
2224 Expand wildcards and the following special keywords in {expr}.
2225 The result is a String.
2226
2227 When there are several matches, they are separated by <NL>
2228 characters. [Note: in version 5.0 a space was used, which
2229 caused problems when a file name contains a space]
2230
2231 If the expansion fails, the result is an empty string. A name
2232 for a non-existing file is not included.
2233
2234 When {expr} starts with '%', '#' or '<', the expansion is done
2235 like for the |cmdline-special| variables with their associated
2236 modifiers. Here is a short overview:
2237
2238 % current file name
2239 # alternate file name
2240 #n alternate file name n
2241 <cfile> file name under the cursor
2242 <afile> autocmd file name
2243 <abuf> autocmd buffer number (as a String!)
2244 <amatch> autocmd matched name
2245 <sfile> sourced script file name
2246 <cword> word under the cursor
2247 <cWORD> WORD under the cursor
2248 <client> the {clientid} of the last received
2249 message |server2client()|
2250 Modifiers:
2251 :p expand to full path
2252 :h head (last path component removed)
2253 :t tail (last path component only)
2254 :r root (one extension removed)
2255 :e extension only
2256
2257 Example: >
2258 :let &tags = expand("%:p:h") . "/tags"
2259< Note that when expanding a string that starts with '%', '#' or
2260 '<', any following text is ignored. This does NOT work: >
2261 :let doesntwork = expand("%:h.bak")
2262< Use this: >
2263 :let doeswork = expand("%:h") . ".bak"
2264< Also note that expanding "<cfile>" and others only returns the
2265 referenced file name without further expansion. If "<cfile>"
2266 is "~/.cshrc", you need to do another expand() to have the
2267 "~/" expanded into the path of the home directory: >
2268 :echo expand(expand("<cfile>"))
2269<
2270 There cannot be white space between the variables and the
2271 following modifier. The |fnamemodify()| function can be used
2272 to modify normal file names.
2273
2274 When using '%' or '#', and the current or alternate file name
2275 is not defined, an empty string is used. Using "%:p" in a
2276 buffer with no name, results in the current directory, with a
2277 '/' added.
2278
2279 When {expr} does not start with '%', '#' or '<', it is
2280 expanded like a file name is expanded on the command line.
2281 'suffixes' and 'wildignore' are used, unless the optional
2282 {flag} argument is given and it is non-zero. Names for
Bram Moolenaar02743632005-07-25 20:42:36 +00002283 non-existing files are included. The "**" item can be used to
2284 search in a directory tree. For example, to find all "README"
2285 files in the current directory and below: >
2286 :echo expand("**/README")
2287<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002288 Expand() can also be used to expand variables and environment
2289 variables that are only known in a shell. But this can be
2290 slow, because a shell must be started. See |expr-env-expand|.
2291 The expanded variable is still handled like a list of file
2292 names. When an environment variable cannot be expanded, it is
2293 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2294 "$FOOBAR".
2295
2296 See |glob()| for finding existing files. See |system()| for
2297 getting the raw output of an external command.
2298
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002299extend({expr1}, {expr2} [, {expr3}]) *extend()*
2300 {expr1} and {expr2} must be both Lists or both Dictionaries.
2301
2302 If they are Lists: Append {expr2} to {expr1}.
2303 If {expr3} is given insert the items of {expr2} before item
2304 {expr3} in {expr1}. When {expr3} is zero insert before the
2305 first item. When {expr3} is equal to len({expr1}) then
2306 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002307 Examples: >
2308 :echo sort(extend(mylist, [7, 5]))
2309 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002310< Use |add()| to concatenate one item to a list. To concatenate
2311 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002312 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002313<
2314 If they are Dictionaries:
2315 Add all entries from {expr2} to {expr1}.
2316 If a key exists in both {expr1} and {expr2} then {expr3} is
2317 used to decide what to do:
2318 {expr3} = "keep": keep the value of {expr1}
2319 {expr3} = "force": use the value of {expr2}
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00002320 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002321 When {expr3} is omitted then "force" is assumed.
2322
2323 {expr1} is changed when {expr2} is not empty. If necessary
2324 make a copy of {expr1} first.
2325 {expr2} remains unchanged.
2326 Returns {expr1}.
2327
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002328
Bram Moolenaar071d4272004-06-13 20:20:40 +00002329filereadable({file}) *filereadable()*
2330 The result is a Number, which is TRUE when a file with the
2331 name {file} exists, and can be read. If {file} doesn't exist,
2332 or is a directory, the result is FALSE. {file} is any
2333 expression, which is used as a String.
2334 *file_readable()*
2335 Obsolete name: file_readable().
2336
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002337
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002338filter({expr}, {string}) *filter()*
2339 {expr} must be a List or a Dictionary.
2340 For each item in {expr} evaluate {string} and when the result
2341 is zero remove the item from the List or Dictionary.
2342 Inside {string} |v:val| has the value of the current item.
2343 For a Dictionary |v:key| has the key of the current item.
2344 Examples: >
2345 :call filter(mylist, 'v:val !~ "OLD"')
2346< Removes the items where "OLD" appears. >
2347 :call filter(mydict, 'v:key >= 8')
2348< Removes the items with a key below 8. >
2349 :call filter(var, 0)
Bram Moolenaard8b02732005-01-14 21:48:43 +00002350< Removes all the items, thus clears the List or Dictionary.
2351
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002352 Note that {string} is the result of expression and is then
2353 used as an expression again. Often it is good to use a
2354 |literal-string| to avoid having to double backslashes.
2355
2356 The operation is done in-place. If you want a List or
2357 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00002358 :let l = filter(copy(mylist), '& =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002359
2360< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002361
2362
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002363finddir({name}[, {path}[, {count}]]) *finddir()*
2364 Find directory {name} in {path}.
2365 If {path} is omitted or empty then 'path' is used.
2366 If the optional {count} is given, find {count}'s occurrence of
2367 {name} in {path}.
2368 This is quite similar to the ex-command |:find|.
2369 When the found directory is below the current directory a
2370 relative path is returned. Otherwise a full path is returned.
2371 Example: >
2372 :echo findfile("tags.vim", ".;")
2373< Searches from the current directory upwards until it finds
2374 the file "tags.vim".
2375 {only available when compiled with the +file_in_path feature}
2376
2377findfile({name}[, {path}[, {count}]]) *findfile()*
2378 Just like |finddir()|, but find a file instead of a directory.
2379
Bram Moolenaar071d4272004-06-13 20:20:40 +00002380filewritable({file}) *filewritable()*
2381 The result is a Number, which is 1 when a file with the
2382 name {file} exists, and can be written. If {file} doesn't
2383 exist, or is not writable, the result is 0. If (file) is a
2384 directory, and we can write to it, the result is 2.
2385
2386fnamemodify({fname}, {mods}) *fnamemodify()*
2387 Modify file name {fname} according to {mods}. {mods} is a
2388 string of characters like it is used for file names on the
2389 command line. See |filename-modifiers|.
2390 Example: >
2391 :echo fnamemodify("main.c", ":p:h")
2392< results in: >
2393 /home/mool/vim/vim/src
2394< Note: Environment variables and "~" don't work in {fname}, use
2395 |expand()| first then.
2396
2397foldclosed({lnum}) *foldclosed()*
2398 The result is a Number. If the line {lnum} is in a closed
2399 fold, the result is the number of the first line in that fold.
2400 If the line {lnum} is not in a closed fold, -1 is returned.
2401
2402foldclosedend({lnum}) *foldclosedend()*
2403 The result is a Number. If the line {lnum} is in a closed
2404 fold, the result is the number of the last line in that fold.
2405 If the line {lnum} is not in a closed fold, -1 is returned.
2406
2407foldlevel({lnum}) *foldlevel()*
2408 The result is a Number, which is the foldlevel of line {lnum}
2409 in the current buffer. For nested folds the deepest level is
2410 returned. If there is no fold at line {lnum}, zero is
2411 returned. It doesn't matter if the folds are open or closed.
2412 When used while updating folds (from 'foldexpr') -1 is
2413 returned for lines where folds are still to be updated and the
2414 foldlevel is unknown. As a special case the level of the
2415 previous line is usually available.
2416
2417 *foldtext()*
2418foldtext() Returns a String, to be displayed for a closed fold. This is
2419 the default function used for the 'foldtext' option and should
2420 only be called from evaluating 'foldtext'. It uses the
2421 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2422 The returned string looks like this: >
2423 +-- 45 lines: abcdef
2424< The number of dashes depends on the foldlevel. The "45" is
2425 the number of lines in the fold. "abcdef" is the text in the
2426 first non-blank line of the fold. Leading white space, "//"
2427 or "/*" and the text from the 'foldmarker' and 'commentstring'
2428 options is removed.
2429 {not available when compiled without the |+folding| feature}
2430
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002431foldtextresult({lnum}) *foldtextresult()*
2432 Returns the text that is displayed for the closed fold at line
2433 {lnum}. Evaluates 'foldtext' in the appropriate context.
2434 When there is no closed fold at {lnum} an empty string is
2435 returned.
2436 {lnum} is used like with |getline()|. Thus "." is the current
2437 line, "'m" mark m, etc.
2438 Useful when exporting folded text, e.g., to HTML.
2439 {not available when compiled without the |+folding| feature}
2440
Bram Moolenaar071d4272004-06-13 20:20:40 +00002441 *foreground()*
2442foreground() Move the Vim window to the foreground. Useful when sent from
2443 a client to a Vim server. |remote_send()|
2444 On Win32 systems this might not work, the OS does not always
2445 allow a window to bring itself to the foreground. Use
2446 |remote_foreground()| instead.
2447 {only in the Win32, Athena, Motif and GTK GUI versions and the
2448 Win32 console version}
2449
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002450
Bram Moolenaar13065c42005-01-08 16:08:21 +00002451function({name}) *function()* *E700*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002452 Return a Funcref variable that refers to function {name}.
2453 {name} can be a user defined function or an internal function.
2454
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002455
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002456garbagecollect() *garbagecollect()*
2457 Cleanup unused Lists and Dictionaries that have circular
2458 references. There is hardly ever a need to invoke this
2459 function, as it is automatically done when Vim runs out of
2460 memory or is waiting for the user to press a key after
2461 'updatetime'. Items without circular references are always
2462 freed when they become unused.
2463 This is useful if you have deleted a very big List and/or
2464 Dictionary with circular references in a script that runs for
2465 a long time.
2466
Bram Moolenaar677ee682005-01-27 14:41:15 +00002467get({list}, {idx} [, {default}]) *get()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002468 Get item {idx} from List {list}. When this item is not
2469 available return {default}. Return zero when {default} is
2470 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002471get({dict}, {key} [, {default}])
2472 Get item with key {key} from Dictionary {dict}. When this
2473 item is not available return {default}. Return zero when
2474 {default} is omitted.
2475
Bram Moolenaar45360022005-07-21 21:08:21 +00002476 *getbufline()*
2477getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar661b1822005-07-28 22:36:45 +00002478 Return a List with the lines starting from {lnum} to {end}
2479 (inclusive) in the buffer {expr}. If {end} is omitted, a List
2480 with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002481
2482 For the use of {expr}, see |bufname()| above.
2483
Bram Moolenaar661b1822005-07-28 22:36:45 +00002484 For {lnum} and {end} "$" can be used for the last line of the
2485 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00002486
2487 When {lnum} is smaller than 1 or bigger than the number of
2488 lines in the buffer, an empty List is returned.
2489
2490 When {end} is greater than the number of lines in the buffer,
2491 it is treated as {end} is set to the number of lines in the
Bram Moolenaar661b1822005-07-28 22:36:45 +00002492 buffer. When {end} is before {lnum} an empty List is
Bram Moolenaar45360022005-07-21 21:08:21 +00002493 returned.
2494
Bram Moolenaar661b1822005-07-28 22:36:45 +00002495 This function works only for loaded buffers. For unloaded and
Bram Moolenaar45360022005-07-21 21:08:21 +00002496 non-existing buffers, an empty List is returned.
2497
2498 Example: >
2499 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002500
2501getbufvar({expr}, {varname}) *getbufvar()*
2502 The result is the value of option or local buffer variable
2503 {varname} in buffer {expr}. Note that the name without "b:"
2504 must be used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002505 This also works for a global or buffer-local option, but it
2506 doesn't work for a global variable, window-local variable or
2507 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002508 For the use of {expr}, see |bufname()| above.
2509 When the buffer or variable doesn't exist an empty string is
2510 returned, there is no error message.
2511 Examples: >
2512 :let bufmodified = getbufvar(1, "&mod")
2513 :echo "todo myvar = " . getbufvar("todo", "myvar")
2514<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002515getchar([expr]) *getchar()*
2516 Get a single character from the user. If it is an 8-bit
2517 character, the result is a number. Otherwise a String is
2518 returned with the encoded character. For a special key it's a
2519 sequence of bytes starting with 0x80 (decimal: 128).
2520 If [expr] is omitted, wait until a character is available.
2521 If [expr] is 0, only get a character when one is available.
2522 If [expr] is 1, only check if a character is available, it is
2523 not consumed. If a normal character is
2524 available, it is returned, otherwise a
2525 non-zero value is returned.
2526 If a normal character available, it is returned as a Number.
2527 Use nr2char() to convert it to a String.
2528 The returned value is zero if no character is available.
2529 The returned value is a string of characters for special keys
2530 and when a modifier (shift, control, alt) was used.
2531 There is no prompt, you will somehow have to make clear to the
2532 user that a character has to be typed.
2533 There is no mapping for the character.
2534 Key codes are replaced, thus when the user presses the <Del>
2535 key you get the code for the <Del> key, not the raw character
2536 sequence. Examples: >
2537 getchar() == "\<Del>"
2538 getchar() == "\<S-Left>"
2539< This example redefines "f" to ignore case: >
2540 :nmap f :call FindChar()<CR>
2541 :function FindChar()
2542 : let c = nr2char(getchar())
2543 : while col('.') < col('$') - 1
2544 : normal l
2545 : if getline('.')[col('.') - 1] ==? c
2546 : break
2547 : endif
2548 : endwhile
2549 :endfunction
2550
2551getcharmod() *getcharmod()*
2552 The result is a Number which is the state of the modifiers for
2553 the last obtained character with getchar() or in another way.
2554 These values are added together:
2555 2 shift
2556 4 control
2557 8 alt (meta)
2558 16 mouse double click
2559 32 mouse triple click
2560 64 mouse quadruple click
2561 128 Macintosh only: command
2562 Only the modifiers that have not been included in the
2563 character itself are obtained. Thus Shift-a results in "A"
2564 with no modifier.
2565
Bram Moolenaar071d4272004-06-13 20:20:40 +00002566getcmdline() *getcmdline()*
2567 Return the current command-line. Only works when the command
2568 line is being edited, thus requires use of |c_CTRL-\_e| or
2569 |c_CTRL-R_=|.
2570 Example: >
2571 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002572< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002573
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002574getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002575 Return the position of the cursor in the command line as a
2576 byte count. The first column is 1.
2577 Only works when editing the command line, thus requires use of
2578 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002579 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
2580
2581getcmdtype() *getcmdtype()*
2582 Return the current command-line type. Possible return values
2583 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00002584 : normal Ex command
2585 > debug mode command |debug-mode|
2586 / forward search command
2587 ? backward search command
2588 @ |input()| command
2589 - |:insert| or |:append| command
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002590 Only works when editing the command line, thus requires use of
2591 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
2592 otherwise.
2593 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002594
2595 *getcwd()*
2596getcwd() The result is a String, which is the name of the current
2597 working directory.
2598
2599getfsize({fname}) *getfsize()*
2600 The result is a Number, which is the size in bytes of the
2601 given file {fname}.
2602 If {fname} is a directory, 0 is returned.
2603 If the file {fname} can't be found, -1 is returned.
2604
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002605getfontname([{name}]) *getfontname()*
2606 Without an argument returns the name of the normal font being
2607 used. Like what is used for the Normal highlight group
2608 |hl-Normal|.
2609 With an argument a check is done whether {name} is a valid
2610 font name. If not then an empty string is returned.
2611 Otherwise the actual font name is returned, or {name} if the
2612 GUI does not support obtaining the real name.
2613 Only works when the GUI is running, thus not you your vimrc or
2614 Note that the GTK 2 GUI accepts any font name, thus checking
2615 for a valid name does not work.
2616 gvimrc file. Use the |GUIEnter| autocommand to use this
2617 function just after the GUI has started.
2618
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002619getfperm({fname}) *getfperm()*
2620 The result is a String, which is the read, write, and execute
2621 permissions of the given file {fname}.
2622 If {fname} does not exist or its directory cannot be read, an
2623 empty string is returned.
2624 The result is of the form "rwxrwxrwx", where each group of
2625 "rwx" flags represent, in turn, the permissions of the owner
2626 of the file, the group the file belongs to, and other users.
2627 If a user does not have a given permission the flag for this
2628 is replaced with the string "-". Example: >
2629 :echo getfperm("/etc/passwd")
2630< This will hopefully (from a security point of view) display
2631 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00002632
Bram Moolenaar071d4272004-06-13 20:20:40 +00002633getftime({fname}) *getftime()*
2634 The result is a Number, which is the last modification time of
2635 the given file {fname}. The value is measured as seconds
2636 since 1st Jan 1970, and may be passed to strftime(). See also
2637 |localtime()| and |strftime()|.
2638 If the file {fname} can't be found -1 is returned.
2639
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002640getftype({fname}) *getftype()*
2641 The result is a String, which is a description of the kind of
2642 file of the given file {fname}.
2643 If {fname} does not exist an empty string is returned.
2644 Here is a table over different kinds of files and their
2645 results:
2646 Normal file "file"
2647 Directory "dir"
2648 Symbolic link "link"
2649 Block device "bdev"
2650 Character device "cdev"
2651 Socket "socket"
2652 FIFO "fifo"
2653 All other "other"
2654 Example: >
2655 getftype("/home")
2656< Note that a type such as "link" will only be returned on
2657 systems that support it. On some systems only "dir" and
2658 "file" are returned.
2659
Bram Moolenaar071d4272004-06-13 20:20:40 +00002660 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002661getline({lnum} [, {end}])
2662 Without {end} the result is a String, which is line {lnum}
2663 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002664 getline(1)
2665< When {lnum} is a String that doesn't start with a
2666 digit, line() is called to translate the String into a Number.
2667 To get the line under the cursor: >
2668 getline(".")
2669< When {lnum} is smaller than 1 or bigger than the number of
2670 lines in the buffer, an empty string is returned.
2671
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002672 When {end} is given the result is a List where each item is a
2673 line from the current buffer in the range {lnum} to {end},
2674 including line {end}.
2675 {end} is used in the same way as {lnum}.
2676 Non-existing lines are silently omitted.
Bram Moolenaar45360022005-07-21 21:08:21 +00002677 When {end} is before {lnum} an empty List is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002678 Example: >
2679 :let start = line('.')
2680 :let end = search("^$") - 1
2681 :let lines = getline(start, end)
2682
2683
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002684getqflist() *getqflist()*
2685 Returns a list with all the current quickfix errors. Each
2686 list item is a dictionary with these entries:
2687 bufnr number of buffer that has the file name, use
2688 bufname() to get the name
2689 lnum line number in the buffer (first line is 1)
2690 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00002691 vcol non-zero: "col" is visual column
2692 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002693 nr error number
2694 text description of the error
2695 type type of the error, 'E', '1', etc.
2696 valid non-zero: recognized error message
2697
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00002698 When there is no error list or it's empty an empty list is
2699 returned.
2700
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002701 Useful application: Find pattern matches in multiple files and
2702 do something with them: >
2703 :vimgrep /theword/jg *.c
2704 :for d in getqflist()
2705 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
2706 :endfor
2707
2708
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002709getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002710 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002711 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002712 :let cliptext = getreg('*')
2713< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002714 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002715 getreg('=', 1) returns the expression itself, so that it can
2716 be restored with |setreg()|. For other registers the extra
2717 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002718 If {regname} is not specified, |v:register| is used.
2719
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002720
Bram Moolenaar071d4272004-06-13 20:20:40 +00002721getregtype([{regname}]) *getregtype()*
2722 The result is a String, which is type of register {regname}.
2723 The value will be one of:
2724 "v" for |characterwise| text
2725 "V" for |linewise| text
2726 "<CTRL-V>{width}" for |blockwise-visual| text
2727 0 for an empty or unknown register
2728 <CTRL-V> is one character with value 0x16.
2729 If {regname} is not specified, |v:register| is used.
2730
2731 *getwinposx()*
2732getwinposx() The result is a Number, which is the X coordinate in pixels of
2733 the left hand side of the GUI Vim window. The result will be
2734 -1 if the information is not available.
2735
2736 *getwinposy()*
2737getwinposy() The result is a Number, which is the Y coordinate in pixels of
2738 the top of the GUI Vim window. The result will be -1 if the
2739 information is not available.
2740
2741getwinvar({nr}, {varname}) *getwinvar()*
2742 The result is the value of option or local window variable
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002743 {varname} in window {nr}. When {nr} is zero the current
2744 window is used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002745 This also works for a global option, buffer-local option and
2746 window-local option, but it doesn't work for a global variable
2747 or buffer-local variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002748 Note that the name without "w:" must be used.
2749 Examples: >
2750 :let list_is_on = getwinvar(2, '&list')
2751 :echo "myvar = " . getwinvar(1, 'myvar')
2752<
2753 *glob()*
2754glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2755 When there are several matches, they are separated by <NL>
2756 characters.
2757 If the expansion fails, the result is an empty string.
2758 A name for a non-existing file is not included.
2759
2760 For most systems backticks can be used to get files names from
2761 any external command. Example: >
2762 :let tagfiles = glob("`find . -name tags -print`")
2763 :let &tags = substitute(tagfiles, "\n", ",", "g")
2764< The result of the program inside the backticks should be one
2765 item per line. Spaces inside an item are allowed.
2766
2767 See |expand()| for expanding special Vim variables. See
2768 |system()| for getting the raw output of an external command.
2769
2770globpath({path}, {expr}) *globpath()*
2771 Perform glob() on all directories in {path} and concatenate
2772 the results. Example: >
2773 :echo globpath(&rtp, "syntax/c.vim")
2774< {path} is a comma-separated list of directory names. Each
2775 directory name is prepended to {expr} and expanded like with
2776 glob(). A path separator is inserted when needed.
2777 To add a comma inside a directory name escape it with a
2778 backslash. Note that on MS-Windows a directory may have a
2779 trailing backslash, remove it if you put a comma after it.
2780 If the expansion fails for one of the directories, there is no
2781 error message.
2782 The 'wildignore' option applies: Names matching one of the
2783 patterns in 'wildignore' will be skipped.
2784
Bram Moolenaar02743632005-07-25 20:42:36 +00002785 The "**" item can be used to search in a directory tree.
2786 For example, to find all "README.txt" files in the directories
2787 in 'runtimepath' and below: >
2788 :echo globpath(&rtp, "**/README.txt")
2789<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002790 *has()*
2791has({feature}) The result is a Number, which is 1 if the feature {feature} is
2792 supported, zero otherwise. The {feature} argument is a
2793 string. See |feature-list| below.
2794 Also see |exists()|.
2795
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002796
2797has_key({dict}, {key}) *has_key()*
2798 The result is a Number, which is 1 if Dictionary {dict} has an
2799 entry with key {key}. Zero otherwise.
2800
2801
Bram Moolenaar071d4272004-06-13 20:20:40 +00002802hasmapto({what} [, {mode}]) *hasmapto()*
2803 The result is a Number, which is 1 if there is a mapping that
2804 contains {what} in somewhere in the rhs (what it is mapped to)
2805 and this mapping exists in one of the modes indicated by
2806 {mode}.
2807 Both the global mappings and the mappings local to the current
2808 buffer are checked for a match.
2809 If no matching mapping is found 0 is returned.
2810 The following characters are recognized in {mode}:
2811 n Normal mode
2812 v Visual mode
2813 o Operator-pending mode
2814 i Insert mode
2815 l Language-Argument ("r", "f", "t", etc.)
2816 c Command-line mode
2817 When {mode} is omitted, "nvo" is used.
2818
2819 This function is useful to check if a mapping already exists
2820 to a function in a Vim script. Example: >
2821 :if !hasmapto('\ABCdoit')
2822 : map <Leader>d \ABCdoit
2823 :endif
2824< This installs the mapping to "\ABCdoit" only if there isn't
2825 already a mapping to "\ABCdoit".
2826
2827histadd({history}, {item}) *histadd()*
2828 Add the String {item} to the history {history} which can be
2829 one of: *hist-names*
2830 "cmd" or ":" command line history
2831 "search" or "/" search pattern history
2832 "expr" or "=" typed expression history
2833 "input" or "@" input line history
2834 If {item} does already exist in the history, it will be
2835 shifted to become the newest entry.
2836 The result is a Number: 1 if the operation was successful,
2837 otherwise 0 is returned.
2838
2839 Example: >
2840 :call histadd("input", strftime("%Y %b %d"))
2841 :let date=input("Enter date: ")
2842< This function is not available in the |sandbox|.
2843
2844histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002845 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002846 for the possible values of {history}.
2847
2848 If the parameter {item} is given as String, this is seen
2849 as regular expression. All entries matching that expression
2850 will be removed from the history (if there are any).
2851 Upper/lowercase must match, unless "\c" is used |/\c|.
2852 If {item} is a Number, it will be interpreted as index, see
2853 |:history-indexing|. The respective entry will be removed
2854 if it exists.
2855
2856 The result is a Number: 1 for a successful operation,
2857 otherwise 0 is returned.
2858
2859 Examples:
2860 Clear expression register history: >
2861 :call histdel("expr")
2862<
2863 Remove all entries starting with "*" from the search history: >
2864 :call histdel("/", '^\*')
2865<
2866 The following three are equivalent: >
2867 :call histdel("search", histnr("search"))
2868 :call histdel("search", -1)
2869 :call histdel("search", '^'.histget("search", -1).'$')
2870<
2871 To delete the last search pattern and use the last-but-one for
2872 the "n" command and 'hlsearch': >
2873 :call histdel("search", -1)
2874 :let @/ = histget("search", -1)
2875
2876histget({history} [, {index}]) *histget()*
2877 The result is a String, the entry with Number {index} from
2878 {history}. See |hist-names| for the possible values of
2879 {history}, and |:history-indexing| for {index}. If there is
2880 no such entry, an empty String is returned. When {index} is
2881 omitted, the most recent item from the history is used.
2882
2883 Examples:
2884 Redo the second last search from history. >
2885 :execute '/' . histget("search", -2)
2886
2887< Define an Ex command ":H {num}" that supports re-execution of
2888 the {num}th entry from the output of |:history|. >
2889 :command -nargs=1 H execute histget("cmd", 0+<args>)
2890<
2891histnr({history}) *histnr()*
2892 The result is the Number of the current entry in {history}.
2893 See |hist-names| for the possible values of {history}.
2894 If an error occurred, -1 is returned.
2895
2896 Example: >
2897 :let inp_index = histnr("expr")
2898<
2899hlexists({name}) *hlexists()*
2900 The result is a Number, which is non-zero if a highlight group
2901 called {name} exists. This is when the group has been
2902 defined in some way. Not necessarily when highlighting has
2903 been defined for it, it may also have been used for a syntax
2904 item.
2905 *highlight_exists()*
2906 Obsolete name: highlight_exists().
2907
2908 *hlID()*
2909hlID({name}) The result is a Number, which is the ID of the highlight group
2910 with name {name}. When the highlight group doesn't exist,
2911 zero is returned.
2912 This can be used to retrieve information about the highlight
2913 group. For example, to get the background color of the
2914 "Comment" group: >
2915 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
2916< *highlightID()*
2917 Obsolete name: highlightID().
2918
2919hostname() *hostname()*
2920 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002921 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00002922 256 characters long are truncated.
2923
2924iconv({expr}, {from}, {to}) *iconv()*
2925 The result is a String, which is the text {expr} converted
2926 from encoding {from} to encoding {to}.
2927 When the conversion fails an empty string is returned.
2928 The encoding names are whatever the iconv() library function
2929 can accept, see ":!man 3 iconv".
2930 Most conversions require Vim to be compiled with the |+iconv|
2931 feature. Otherwise only UTF-8 to latin1 conversion and back
2932 can be done.
2933 This can be used to display messages with special characters,
2934 no matter what 'encoding' is set to. Write the message in
2935 UTF-8 and use: >
2936 echo iconv(utf8_str, "utf-8", &enc)
2937< Note that Vim uses UTF-8 for all Unicode encodings, conversion
2938 from/to UCS-2 is automatically changed to use UTF-8. You
2939 cannot use UCS-2 in a string anyway, because of the NUL bytes.
2940 {only available when compiled with the +multi_byte feature}
2941
2942 *indent()*
2943indent({lnum}) The result is a Number, which is indent of line {lnum} in the
2944 current buffer. The indent is counted in spaces, the value
2945 of 'tabstop' is relevant. {lnum} is used just like in
2946 |getline()|.
2947 When {lnum} is invalid -1 is returned.
2948
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002949
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002950index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002951 Return the lowest index in List {list} where the item has a
2952 value equal to {expr}.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002953 If {start} is given then start looking at the item with index
2954 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002955 When {ic} is given and it is non-zero, ignore case. Otherwise
2956 case must match.
2957 -1 is returned when {expr} is not found in {list}.
2958 Example: >
2959 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002960 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002961
2962
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002963input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002964 The result is a String, which is whatever the user typed on
2965 the command-line. The parameter is either a prompt string, or
2966 a blank string (for no prompt). A '\n' can be used in the
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002967 prompt to start a new line.
2968 The highlighting set with |:echohl| is used for the prompt.
2969 The input is entered just like a command-line, with the same
2970 editing commands and mappings. There is a separate history
2971 for lines typed for input().
2972 Example: >
2973 :if input("Coffee or beer? ") == "beer"
2974 : echo "Cheers!"
2975 :endif
2976<
Bram Moolenaar1e015462005-09-25 22:16:38 +00002977 If the optional {text} is present and not empty, this is used
2978 for the default reply, as if the user typed this. Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002979 :let color = input("Color? ", "white")
2980
2981< The optional {completion} argument specifies the type of
2982 completion supported for the input. Without it completion is
2983 not performed. The supported completion types are the same as
2984 that can be supplied to a user-defined command using the
2985 "-complete=" argument. Refer to |:command-completion| for
2986 more information. Example: >
2987 let fname = input("File: ", "", "file")
2988<
2989 NOTE: This function must not be used in a startup file, for
2990 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00002991 Note: When input() is called from within a mapping it will
2992 consume remaining characters from that mapping, because a
2993 mapping is handled like the characters were typed.
2994 Use |inputsave()| before input() and |inputrestore()|
2995 after input() to avoid that. Another solution is to avoid
2996 that further characters follow in the mapping, e.g., by using
2997 |:execute| or |:normal|.
2998
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002999 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003000 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3001 :function GetFoo()
3002 : call inputsave()
3003 : let g:Foo = input("enter search pattern: ")
3004 : call inputrestore()
3005 :endfunction
3006
3007inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3008 Like input(), but when the GUI is running and text dialogs are
3009 supported, a dialog window pops up to input the text.
3010 Example: >
3011 :let n = inputdialog("value for shiftwidth", &sw)
3012 :if n != ""
3013 : let &sw = n
3014 :endif
3015< When the dialog is cancelled {cancelreturn} is returned. When
3016 omitted an empty string is returned.
3017 Hitting <Enter> works like pressing the OK button. Hitting
3018 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003019 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003020
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003021inputlist({textlist}) *inputlist()*
3022 {textlist} must be a list of strings. This list is displayed,
3023 one string per line. The user will be prompted to enter a
3024 number, which is returned.
3025 The user can also select an item by clicking on it with the
3026 mouse. For the first string 0 is returned. When clicking
3027 above the first item a negative number is returned. When
3028 clicking on the prompt one more than the length of {textlist}
3029 is returned.
3030 Make sure {textlist} has less then 'lines' entries, otherwise
3031 it won't work. It's a good idea to put the entry number at
3032 the start of the string. Example: >
3033 let color = inputlist(['Select color:', '1. red',
3034 \ '2. green', '3. blue'])
3035
Bram Moolenaar071d4272004-06-13 20:20:40 +00003036inputrestore() *inputrestore()*
3037 Restore typeahead that was saved with a previous inputsave().
3038 Should be called the same number of times inputsave() is
3039 called. Calling it more often is harmless though.
3040 Returns 1 when there is nothing to restore, 0 otherwise.
3041
3042inputsave() *inputsave()*
3043 Preserve typeahead (also from mappings) and clear it, so that
3044 a following prompt gets input from the user. Should be
3045 followed by a matching inputrestore() after the prompt. Can
3046 be used several times, in which case there must be just as
3047 many inputrestore() calls.
3048 Returns 1 when out of memory, 0 otherwise.
3049
3050inputsecret({prompt} [, {text}]) *inputsecret()*
3051 This function acts much like the |input()| function with but
3052 two exceptions:
3053 a) the user's response will be displayed as a sequence of
3054 asterisks ("*") thereby keeping the entry secret, and
3055 b) the user's response will not be recorded on the input
3056 |history| stack.
3057 The result is a String, which is whatever the user actually
3058 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003059 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003060
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003061insert({list}, {item} [, {idx}]) *insert()*
3062 Insert {item} at the start of List {list}.
3063 If {idx} is specified insert {item} before the item with index
3064 {idx}. If {idx} is zero it goes before the first item, just
3065 like omitting {idx}. A negative {idx} is also possible, see
3066 |list-index|. -1 inserts just before the last item.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003067 Returns the resulting List. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003068 :let mylist = insert([2, 3, 5], 1)
3069 :call insert(mylist, 4, -1)
3070 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003071< The last example can be done simpler with |add()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003072 Note that when {item} is a List it is inserted as a single
3073 item. Use |extend()| to concatenate Lists.
3074
Bram Moolenaar071d4272004-06-13 20:20:40 +00003075isdirectory({directory}) *isdirectory()*
3076 The result is a Number, which is non-zero when a directory
3077 with the name {directory} exists. If {directory} doesn't
3078 exist, or isn't a directory, the result is FALSE. {directory}
3079 is any expression, which is used as a String.
3080
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003081islocked({expr}) *islocked()*
3082 The result is a Number, which is non-zero when {expr} is the
3083 name of a locked variable.
3084 {expr} must be the name of a variable, List item or Dictionary
3085 entry, not the variable itself! Example: >
3086 :let alist = [0, ['a', 'b'], 2, 3]
3087 :lockvar 1 alist
3088 :echo islocked('alist') " 1
3089 :echo islocked('alist[1]') " 0
3090
3091< When {expr} is a variable that does not exist you get an error
3092 message. Use |exists()| to check for existance.
3093
Bram Moolenaar677ee682005-01-27 14:41:15 +00003094items({dict}) *items()*
3095 Return a List with all the key-value pairs of {dict}. Each
3096 List item is a list with two items: the key of a {dict} entry
3097 and the value of this entry. The List is in arbitrary order.
3098
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003099
3100join({list} [, {sep}]) *join()*
3101 Join the items in {list} together into one String.
3102 When {sep} is specified it is put in between the items. If
3103 {sep} is omitted a single space is used.
3104 Note that {sep} is not added at the end. You might want to
3105 add it there too: >
3106 let lines = join(mylist, "\n") . "\n"
3107< String items are used as-is. Lists and Dictionaries are
3108 converted into a string like with |string()|.
3109 The opposite function is |split()|.
3110
Bram Moolenaard8b02732005-01-14 21:48:43 +00003111keys({dict}) *keys()*
3112 Return a List with all the keys of {dict}. The List is in
3113 arbitrary order.
3114
Bram Moolenaar13065c42005-01-08 16:08:21 +00003115 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003116len({expr}) The result is a Number, which is the length of the argument.
3117 When {expr} is a String or a Number the length in bytes is
3118 used, as with |strlen()|.
3119 When {expr} is a List the number of items in the List is
3120 returned.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003121 When {expr} is a Dictionary the number of entries in the
3122 Dictionary is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003123 Otherwise an error is given.
3124
Bram Moolenaar071d4272004-06-13 20:20:40 +00003125 *libcall()* *E364* *E368*
3126libcall({libname}, {funcname}, {argument})
3127 Call function {funcname} in the run-time library {libname}
3128 with single argument {argument}.
3129 This is useful to call functions in a library that you
3130 especially made to be used with Vim. Since only one argument
3131 is possible, calling standard library functions is rather
3132 limited.
3133 The result is the String returned by the function. If the
3134 function returns NULL, this will appear as an empty string ""
3135 to Vim.
3136 If the function returns a number, use libcallnr()!
3137 If {argument} is a number, it is passed to the function as an
3138 int; if {argument} is a string, it is passed as a
3139 null-terminated string.
3140 This function will fail in |restricted-mode|.
3141
3142 libcall() allows you to write your own 'plug-in' extensions to
3143 Vim without having to recompile the program. It is NOT a
3144 means to call system functions! If you try to do so Vim will
3145 very probably crash.
3146
3147 For Win32, the functions you write must be placed in a DLL
3148 and use the normal C calling convention (NOT Pascal which is
3149 used in Windows System DLLs). The function must take exactly
3150 one parameter, either a character pointer or a long integer,
3151 and must return a character pointer or NULL. The character
3152 pointer returned must point to memory that will remain valid
3153 after the function has returned (e.g. in static data in the
3154 DLL). If it points to allocated memory, that memory will
3155 leak away. Using a static buffer in the function should work,
3156 it's then freed when the DLL is unloaded.
3157
3158 WARNING: If the function returns a non-valid pointer, Vim may
3159 crash! This also happens if the function returns a number,
3160 because Vim thinks it's a pointer.
3161 For Win32 systems, {libname} should be the filename of the DLL
3162 without the ".DLL" suffix. A full path is only required if
3163 the DLL is not in the usual places.
3164 For Unix: When compiling your own plugins, remember that the
3165 object code must be compiled as position-independent ('PIC').
3166 {only in Win32 on some Unix versions, when the |+libcall|
3167 feature is present}
3168 Examples: >
3169 :echo libcall("libc.so", "getenv", "HOME")
3170 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3171<
3172 *libcallnr()*
3173libcallnr({libname}, {funcname}, {argument})
3174 Just like libcall(), but used for a function that returns an
3175 int instead of a string.
3176 {only in Win32 on some Unix versions, when the |+libcall|
3177 feature is present}
3178 Example (not very useful...): >
3179 :call libcallnr("libc.so", "printf", "Hello World!\n")
3180 :call libcallnr("libc.so", "sleep", 10)
3181<
3182 *line()*
3183line({expr}) The result is a Number, which is the line number of the file
3184 position given with {expr}. The accepted positions are:
3185 . the cursor position
3186 $ the last line in the current buffer
3187 'x position of mark x (if the mark is not set, 0 is
3188 returned)
3189 Note that only marks in the current file can be used.
3190 Examples: >
3191 line(".") line number of the cursor
3192 line("'t") line number of mark t
3193 line("'" . marker) line number of mark marker
3194< *last-position-jump*
3195 This autocommand jumps to the last known position in a file
3196 just after opening it, if the '" mark is set: >
3197 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003198
Bram Moolenaar071d4272004-06-13 20:20:40 +00003199line2byte({lnum}) *line2byte()*
3200 Return the byte count from the start of the buffer for line
3201 {lnum}. This includes the end-of-line character, depending on
3202 the 'fileformat' option for the current buffer. The first
3203 line returns 1.
3204 This can also be used to get the byte count for the line just
3205 below the last line: >
3206 line2byte(line("$") + 1)
3207< This is the file size plus one.
3208 When {lnum} is invalid, or the |+byte_offset| feature has been
3209 disabled at compile time, -1 is returned.
3210 Also see |byte2line()|, |go| and |:goto|.
3211
3212lispindent({lnum}) *lispindent()*
3213 Get the amount of indent for line {lnum} according the lisp
3214 indenting rules, as with 'lisp'.
3215 The indent is counted in spaces, the value of 'tabstop' is
3216 relevant. {lnum} is used just like in |getline()|.
3217 When {lnum} is invalid or Vim was not compiled the
3218 |+lispindent| feature, -1 is returned.
3219
3220localtime() *localtime()*
3221 Return the current time, measured as seconds since 1st Jan
3222 1970. See also |strftime()| and |getftime()|.
3223
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003224
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003225map({expr}, {string}) *map()*
3226 {expr} must be a List or a Dictionary.
3227 Replace each item in {expr} with the result of evaluating
3228 {string}.
3229 Inside {string} |v:val| has the value of the current item.
3230 For a Dictionary |v:key| has the key of the current item.
3231 Example: >
3232 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003233< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003234
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003235 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003236 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003237 |literal-string| to avoid having to double backslashes. You
3238 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003239
3240 The operation is done in-place. If you want a List or
3241 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003242 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003243
3244< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003245
3246
Bram Moolenaar071d4272004-06-13 20:20:40 +00003247maparg({name}[, {mode}]) *maparg()*
3248 Return the rhs of mapping {name} in mode {mode}. When there
3249 is no mapping for {name}, an empty String is returned.
3250 These characters can be used for {mode}:
3251 "n" Normal
3252 "v" Visual
3253 "o" Operator-pending
3254 "i" Insert
3255 "c" Cmd-line
3256 "l" langmap |language-mapping|
3257 "" Normal, Visual and Operator-pending
3258 When {mode} is omitted, the modes from "" are used.
3259 The {name} can have special key names, like in the ":map"
3260 command. The returned String has special characters
3261 translated like in the output of the ":map" command listing.
3262 The mappings local to the current buffer are checked first,
3263 then the global mappings.
3264
3265mapcheck({name}[, {mode}]) *mapcheck()*
3266 Check if there is a mapping that matches with {name} in mode
3267 {mode}. See |maparg()| for {mode} and special names in
3268 {name}.
3269 A match happens with a mapping that starts with {name} and
3270 with a mapping which is equal to the start of {name}.
3271
3272 matches mapping "a" "ab" "abc" ~
3273 mapcheck("a") yes yes yes
3274 mapcheck("abc") yes yes yes
3275 mapcheck("ax") yes no no
3276 mapcheck("b") no no no
3277
3278 The difference with maparg() is that mapcheck() finds a
3279 mapping that matches with {name}, while maparg() only finds a
3280 mapping for {name} exactly.
3281 When there is no mapping that starts with {name}, an empty
3282 String is returned. If there is one, the rhs of that mapping
3283 is returned. If there are several mappings that start with
3284 {name}, the rhs of one of them is returned.
3285 The mappings local to the current buffer are checked first,
3286 then the global mappings.
3287 This function can be used to check if a mapping can be added
3288 without being ambiguous. Example: >
3289 :if mapcheck("_vv") == ""
3290 : map _vv :set guifont=7x13<CR>
3291 :endif
3292< This avoids adding the "_vv" mapping when there already is a
3293 mapping for "_v" or for "_vvv".
3294
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003295match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003296 When {expr} is a List then this returns the index of the first
3297 item where {pat} matches. Each item is used as a String,
3298 Lists and Dictionaries are used as echoed.
3299 Otherwise, {expr} is used as a String. The result is a
3300 Number, which gives the index (byte offset) in {expr} where
3301 {pat} matches.
3302 A match at the first character or List item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003303 If there is no match -1 is returned.
3304 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003305 :echo match("testing", "ing") " results in 4
3306 :echo match([1, 'x'], '\a') " results in 2
3307< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00003308 *strpbrk()*
3309 Vim doesn't have a strpbrk() function. But you can do: >
3310 :let sepidx = match(line, '[.,;: \t]')
3311< *strcasestr()*
3312 Vim doesn't have a strcasestr() function. But you can add
3313 "\c" to the pattern to ignore case: >
3314 :let idx = match(haystack, '\cneedle')
3315<
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003316 When {count} is given use the {count}'th match. When a match
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003317 is found in a String the search for the next one starts on
3318 character further. Thus this example results in 1: >
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003319 echo match("testing", "..", 0, 2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003320< In a List the search continues in the next item.
3321
3322 If {start} is given, the search starts from byte index
3323 {start} in a String or item {start} in a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003324 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003325 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003326 :echo match("testing", "ing", 2)
3327< result is again "4". >
3328 :echo match("testing", "ing", 4)
3329< result is again "4". >
3330 :echo match("testing", "t", 2)
3331< result is "3".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003332 For a String, if {start} < 0, it will be set to 0. For a list
3333 the index is counted from the end.
3334 If {start} is out of range (> strlen({expr} for a String or
3335 > len({expr} for a List) -1 is returned.
3336
Bram Moolenaar071d4272004-06-13 20:20:40 +00003337 See |pattern| for the patterns that are accepted.
3338 The 'ignorecase' option is used to set the ignore-caseness of
3339 the pattern. 'smartcase' is NOT used. The matching is always
3340 done like 'magic' is set and 'cpoptions' is empty.
3341
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003342matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003343 Same as match(), but return the index of first character after
3344 the match. Example: >
3345 :echo matchend("testing", "ing")
3346< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00003347 *strspn()* *strcspn()*
3348 Vim doesn't have a strspn() or strcspn() function, but you can
3349 do it with matchend(): >
3350 :let span = matchend(line, '[a-zA-Z]')
3351 :let span = matchend(line, '[^a-zA-Z]')
3352< Except that -1 is returned when there are no matches.
3353
Bram Moolenaar071d4272004-06-13 20:20:40 +00003354 The {start}, if given, has the same meaning as for match(). >
3355 :echo matchend("testing", "ing", 2)
3356< results in "7". >
3357 :echo matchend("testing", "ing", 5)
3358< result is "-1".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003359 When {expr} is a List the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003360
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003361matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
3362 Same as match(), but return a List. The first item in the
3363 list is the matched string, same as what matchstr() would
3364 return. Following items are submatches, like "\1", "\2", etc.
3365 in |:substitute|.
3366 When there is no match an empty list is returned.
3367
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003368matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003369 Same as match(), but return the matched string. Example: >
3370 :echo matchstr("testing", "ing")
3371< results in "ing".
3372 When there is no match "" is returned.
3373 The {start}, if given, has the same meaning as for match(). >
3374 :echo matchstr("testing", "ing", 2)
3375< results in "ing". >
3376 :echo matchstr("testing", "ing", 5)
3377< result is "".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003378 When {expr} is a List then the matching item is returned.
3379 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003380
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003381 *max()*
3382max({list}) Return the maximum value of all items in {list}.
3383 If {list} is not a list or one of the items in {list} cannot
3384 be used as a Number this results in an error.
3385 An empty List results in zero.
3386
3387 *min()*
3388min({list}) Return the minumum value of all items in {list}.
3389 If {list} is not a list or one of the items in {list} cannot
3390 be used as a Number this results in an error.
3391 An empty List results in zero.
3392
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003393 *mkdir()* *E749*
3394mkdir({name} [, {path} [, {prot}]])
3395 Create directory {name}.
3396 If {path} is "p" then intermediate directories are created as
3397 necessary. Otherwise it must be "".
3398 If {prot} is given it is used to set the protection bits of
3399 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3400 the user readable for others). Use 0700 to make it unreadable
3401 for others.
3402 This function is not available in the |sandbox|.
3403 Not available on all systems. To check use: >
3404 :if exists("*mkdir")
3405<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003406 *mode()*
3407mode() Return a string that indicates the current mode:
3408 n Normal
3409 v Visual by character
3410 V Visual by line
3411 CTRL-V Visual blockwise
3412 s Select by character
3413 S Select by line
3414 CTRL-S Select blockwise
3415 i Insert
3416 R Replace
3417 c Command-line
3418 r Hit-enter prompt
3419 This is useful in the 'statusline' option. In most other
3420 places it always returns "c" or "n".
3421
3422nextnonblank({lnum}) *nextnonblank()*
3423 Return the line number of the first line at or below {lnum}
3424 that is not blank. Example: >
3425 if getline(nextnonblank(1)) =~ "Java"
3426< When {lnum} is invalid or there is no non-blank line at or
3427 below it, zero is returned.
3428 See also |prevnonblank()|.
3429
3430nr2char({expr}) *nr2char()*
3431 Return a string with a single character, which has the number
3432 value {expr}. Examples: >
3433 nr2char(64) returns "@"
3434 nr2char(32) returns " "
3435< The current 'encoding' is used. Example for "utf-8": >
3436 nr2char(300) returns I with bow character
3437< Note that a NUL character in the file is specified with
3438 nr2char(10), because NULs are represented with newline
3439 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003440 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003441
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003442printf({fmt}, {expr1} ...) *printf()*
3443 Return a String with {fmt}, where "%" items are replaced by
3444 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003445 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003446< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003447 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003448
3449 Often used items are:
3450 %s string
3451 %6s string right-aligned in 6 characters
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003452 %c single byte
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003453 %d decimal number
3454 %5d decimal number padded with spaces to 5 characters
3455 %x hex number
3456 %04x hex number padded with zeros to at least 4 characters
3457 %X hex number using upper case letters
3458 %o octal number
3459 %% the % character
3460
3461 Conversion specifications start with '%' and end with the
3462 conversion type. All other characters are copied unchanged to
3463 the result.
3464
3465 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003466 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003467
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003468 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003469
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003470 flags
3471 Zero or more of the following flags:
3472
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003473 # The value should be converted to an "alternate
3474 form". For c, d, and s conversions, this option
3475 has no effect. For o conversions, the precision
3476 of the number is increased to force the first
3477 character of the output string to a zero (except
3478 if a zero value is printed with an explicit
3479 precision of zero).
3480 For x and X conversions, a non-zero result has
3481 the string "0x" (or "0X" for X conversions)
3482 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003483
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003484 0 (zero) Zero padding. For all conversions the converted
3485 value is padded on the left with zeros rather
3486 than blanks. If a precision is given with a
3487 numeric conversion (d, o, x, and X), the 0 flag
3488 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003489
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003490 - A negative field width flag; the converted value
3491 is to be left adjusted on the field boundary.
3492 The converted value is padded on the right with
3493 blanks, rather than on the left with blanks or
3494 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003495
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003496 ' ' (space) A blank should be left before a positive
3497 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003498
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003499 + A sign must always be placed before a number
3500 produced by a signed conversion. A + overrides
3501 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003502
3503 field-width
3504 An optional decimal digit string specifying a minimum
3505 field width. If the converted value has fewer
3506 characters than the field width, it will be padded
3507 with spaces on the left (or right, if the
3508 left-adjustment flag has been given) to fill out the
3509 field width.
3510
3511 .precision
3512 An optional precision, in the form of a period '.'
3513 followed by an optional digit string. If the digit
3514 string is omitted, the precision is taken as zero.
3515 This gives the minimum number of digits to appear for
3516 d, o, x, and X conversions, or the maximum number of
3517 characters to be printed from a string for s
3518 conversions.
3519
3520 type
3521 A character that specifies the type of conversion to
3522 be applied, see below.
3523
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003524 A field width or precision, or both, may be indicated by an
3525 asterisk '*' instead of a digit string. In this case, a
3526 Number argument supplies the field width or precision. A
3527 negative field width is treated as a left adjustment flag
3528 followed by a positive field width; a negative precision is
3529 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003530 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003531< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003532 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003533
3534 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003535
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003536 doxX The Number argument is converted to signed decimal
3537 (d), unsigned octal (o), or unsigned hexadecimal (x
3538 and X) notation. The letters "abcdef" are used for
3539 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003540 conversions.
3541 The precision, if any, gives the minimum number of
3542 digits that must appear; if the converted value
3543 requires fewer digits, it is padded on the left with
3544 zeros.
3545 In no case does a non-existent or small field width
3546 cause truncation of a numeric field; if the result of
3547 a conversion is wider than the field width, the field
3548 is expanded to contain the conversion result.
3549
3550 c The Number argument is converted to a byte, and the
3551 resulting character is written.
3552
3553 s The text of the String argument is used. If a
3554 precision is specified, no more bytes than the number
3555 specified are used.
3556
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003557 % A '%' is written. No argument is converted. The
3558 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003559
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003560 Each argument can be Number or String and is converted
3561 automatically to fit the conversion specifier. Any other
3562 argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003563
Bram Moolenaar83bab712005-08-01 21:58:57 +00003564 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003565 The number of {exprN} arguments must exactly match the number
3566 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003567 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003568
3569
Bram Moolenaar071d4272004-06-13 20:20:40 +00003570prevnonblank({lnum}) *prevnonblank()*
3571 Return the line number of the first line at or above {lnum}
3572 that is not blank. Example: >
3573 let ind = indent(prevnonblank(v:lnum - 1))
3574< When {lnum} is invalid or there is no non-blank line at or
3575 above it, zero is returned.
3576 Also see |nextnonblank()|.
3577
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003578 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003579range({expr} [, {max} [, {stride}]]) *range()*
3580 Returns a List with Numbers:
3581 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3582 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3583 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3584 {max}] (increasing {expr} with {stride} each time, not
3585 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00003586 When the maximum is one before the start the result is an
3587 empty list. When the maximum is more than one before the
3588 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003589 Examples: >
3590 range(4) " [0, 1, 2, 3]
3591 range(2, 4) " [2, 3, 4]
3592 range(2, 9, 3) " [2, 5, 8]
3593 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00003594 range(0) " []
3595 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00003596<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003597 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003598readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003599 Read file {fname} and return a List, each line of the file as
3600 an item. Lines broken at NL characters. Macintosh files
3601 separated with CR will result in a single long line (unless a
3602 NL appears somewhere).
3603 When {binary} is equal to "b" binary mode is used:
3604 - When the last line ends in a NL an extra empty list item is
3605 added.
3606 - No CR characters are removed.
3607 Otherwise:
3608 - CR characters that appear before a NL are removed.
3609 - Whether the last line ends in a NL or not does not matter.
3610 All NUL characters are replaced with a NL character.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003611 When {max} is given this specifies the maximum number of lines
3612 to be read. Useful if you only want to check the first ten
3613 lines of a file: >
3614 :for line in readfile(fname, '', 10)
3615 : if line =~ 'Date' | echo line | endif
3616 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00003617< When {max} is negative -{max} lines from the end of the file
3618 are returned, or as many as there are.
3619 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003620 Note that without {max} the whole file is read into memory.
3621 Also note that there is no recognition of encoding. Read a
3622 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003623 When the file can't be opened an error message is given and
3624 the result is an empty list.
3625 Also see |writefile()|.
3626
Bram Moolenaar071d4272004-06-13 20:20:40 +00003627 *remote_expr()* *E449*
3628remote_expr({server}, {string} [, {idvar}])
3629 Send the {string} to {server}. The string is sent as an
3630 expression and the result is returned after evaluation.
3631 If {idvar} is present, it is taken as the name of a
3632 variable and a {serverid} for later use with
3633 remote_read() is stored there.
3634 See also |clientserver| |RemoteReply|.
3635 This function is not available in the |sandbox|.
3636 {only available when compiled with the |+clientserver| feature}
3637 Note: Any errors will cause a local error message to be issued
3638 and the result will be the empty string.
3639 Examples: >
3640 :echo remote_expr("gvim", "2+2")
3641 :echo remote_expr("gvim1", "b:current_syntax")
3642<
3643
3644remote_foreground({server}) *remote_foreground()*
3645 Move the Vim server with the name {server} to the foreground.
3646 This works like: >
3647 remote_expr({server}, "foreground()")
3648< Except that on Win32 systems the client does the work, to work
3649 around the problem that the OS doesn't always allow the server
3650 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00003651 Note: This does not restore the window if it was minimized,
3652 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003653 This function is not available in the |sandbox|.
3654 {only in the Win32, Athena, Motif and GTK GUI versions and the
3655 Win32 console version}
3656
3657
3658remote_peek({serverid} [, {retvar}]) *remote_peek()*
3659 Returns a positive number if there are available strings
3660 from {serverid}. Copies any reply string into the variable
3661 {retvar} if specified. {retvar} must be a string with the
3662 name of a variable.
3663 Returns zero if none are available.
3664 Returns -1 if something is wrong.
3665 See also |clientserver|.
3666 This function is not available in the |sandbox|.
3667 {only available when compiled with the |+clientserver| feature}
3668 Examples: >
3669 :let repl = ""
3670 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3671
3672remote_read({serverid}) *remote_read()*
3673 Return the oldest available reply from {serverid} and consume
3674 it. It blocks until a reply is available.
3675 See also |clientserver|.
3676 This function is not available in the |sandbox|.
3677 {only available when compiled with the |+clientserver| feature}
3678 Example: >
3679 :echo remote_read(id)
3680<
3681 *remote_send()* *E241*
3682remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003683 Send the {string} to {server}. The string is sent as input
3684 keys and the function returns immediately. At the Vim server
3685 the keys are not mapped |:map|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003686 If {idvar} is present, it is taken as the name of a
3687 variable and a {serverid} for later use with
3688 remote_read() is stored there.
3689 See also |clientserver| |RemoteReply|.
3690 This function is not available in the |sandbox|.
3691 {only available when compiled with the |+clientserver| feature}
3692 Note: Any errors will be reported in the server and may mess
3693 up the display.
3694 Examples: >
3695 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3696 \ remote_read(serverid)
3697
3698 :autocmd NONE RemoteReply *
3699 \ echo remote_read(expand("<amatch>"))
3700 :echo remote_send("gvim", ":sleep 10 | echo ".
3701 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003702<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003703remove({list}, {idx} [, {end}]) *remove()*
3704 Without {end}: Remove the item at {idx} from List {list} and
3705 return it.
3706 With {end}: Remove items from {idx} to {end} (inclusive) and
3707 return a list with these items. When {idx} points to the same
3708 item as {end} a list with one item is returned. When {end}
3709 points to an item before {idx} this is an error.
3710 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003711 Example: >
3712 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003713 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00003714remove({dict}, {key})
3715 Remove the entry from {dict} with key {key}. Example: >
3716 :echo "removed " . remove(dict, "one")
3717< If there is no {key} in {dict} this is an error.
3718
3719 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003720
Bram Moolenaar071d4272004-06-13 20:20:40 +00003721rename({from}, {to}) *rename()*
3722 Rename the file by the name {from} to the name {to}. This
3723 should also work to move files across file systems. The
3724 result is a Number, which is 0 if the file was renamed
3725 successfully, and non-zero when the renaming failed.
3726 This function is not available in the |sandbox|.
3727
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003728repeat({expr}, {count}) *repeat()*
3729 Repeat {expr} {count} times and return the concatenated
3730 result. Example: >
3731 :let seperator = repeat('-', 80)
3732< When {count} is zero or negative the result is empty.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003733 When {expr} is a List the result is {expr} concatenated
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003734 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003735 :let longlist = repeat(['a', 'b'], 3)
3736< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003737
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003738
Bram Moolenaar071d4272004-06-13 20:20:40 +00003739resolve({filename}) *resolve()* *E655*
3740 On MS-Windows, when {filename} is a shortcut (a .lnk file),
3741 returns the path the shortcut points to in a simplified form.
3742 On Unix, repeat resolving symbolic links in all path
3743 components of {filename} and return the simplified result.
3744 To cope with link cycles, resolving of symbolic links is
3745 stopped after 100 iterations.
3746 On other systems, return the simplified {filename}.
3747 The simplification step is done as by |simplify()|.
3748 resolve() keeps a leading path component specifying the
3749 current directory (provided the result is still a relative
3750 path name) and also keeps a trailing path separator.
3751
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003752 *reverse()*
3753reverse({list}) Reverse the order of items in {list} in-place. Returns
3754 {list}.
3755 If you want a list to remain unmodified make a copy first: >
3756 :let revlist = reverse(copy(mylist))
3757
Bram Moolenaar071d4272004-06-13 20:20:40 +00003758search({pattern} [, {flags}]) *search()*
3759 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003760 cursor position (you can use |cursor()| to set it).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003761 {flags} is a String, which can contain these character flags:
3762 'b' search backward instead of forward
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003763 'n' do Not move the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003764 'w' wrap around the end of the file
3765 'W' don't wrap around the end of the file
Bram Moolenaar02743632005-07-25 20:42:36 +00003766 's' set the ' mark at the previous location of the
3767 cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003768 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
3769
Bram Moolenaar02743632005-07-25 20:42:36 +00003770 If the 's' flag is supplied, the ' mark is set, only if the
3771 cursor is moved. The 's' flag cannot be combined with the 'n'
3772 flag.
3773
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003774 When a match has been found its line number is returned.
3775 The cursor will be positioned at the match, unless the 'n'
3776 flag is used).
3777 If there is no match a 0 is returned and the cursor doesn't
3778 move. No error message is given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003779
3780 Example (goes over all files in the argument list): >
3781 :let n = 1
3782 :while n <= argc() " loop over all files in arglist
3783 : exe "argument " . n
3784 : " start at the last char in the file and wrap for the
3785 : " first search to find match at start of file
3786 : normal G$
3787 : let flags = "w"
3788 : while search("foo", flags) > 0
3789 : s/foo/bar/g
3790 : let flags = "W"
3791 : endwhile
3792 : update " write the file if modified
3793 : let n = n + 1
3794 :endwhile
3795<
Bram Moolenaar92d640f2005-09-05 22:11:52 +00003796
Bram Moolenaarf75a9632005-09-13 21:20:47 +00003797searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
3798 Search for the declaration of {name}.
3799
3800 With a non-zero {global} argument it works like |gD|, find
3801 first match in the file. Otherwise it works like |gd|, find
3802 first match in the function.
3803
3804 With a non-zero {thisblock} argument matches in a {} block
3805 that ends before the cursor position are ignored. Avoids
3806 finding variable declarations only valid in another scope.
3807
Bram Moolenaar92d640f2005-09-05 22:11:52 +00003808 Moves the cursor to the found match.
3809 Returns zero for success, non-zero for failure.
3810 Example: >
3811 if searchdecl('myvar') == 0
3812 echo getline('.')
3813 endif
3814<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003815 *searchpair()*
3816searchpair({start}, {middle}, {end} [, {flags} [, {skip}]])
3817 Search for the match of a nested start-end pair. This can be
3818 used to find the "endif" that matches an "if", while other
3819 if/endif pairs in between are ignored.
3820 The search starts at the cursor. If a match is found, the
3821 cursor is positioned at it and the line number is returned.
3822 If no match is found 0 or -1 is returned and the cursor
3823 doesn't move. No error message is given.
3824
3825 {start}, {middle} and {end} are patterns, see |pattern|. They
3826 must not contain \( \) pairs. Use of \%( \) is allowed. When
3827 {middle} is not empty, it is found when searching from either
3828 direction, but only when not in a nested start-end pair. A
3829 typical use is: >
3830 searchpair('\<if\>', '\<else\>', '\<endif\>')
3831< By leaving {middle} empty the "else" is skipped.
3832
3833 {flags} are used like with |search()|. Additionally:
3834 'n' do Not move the cursor
3835 'r' Repeat until no more matches found; will find the
3836 outer pair
3837 'm' return number of Matches instead of line number with
3838 the match; will only be > 1 when 'r' is used.
3839
3840 When a match for {start}, {middle} or {end} is found, the
3841 {skip} expression is evaluated with the cursor positioned on
3842 the start of the match. It should return non-zero if this
3843 match is to be skipped. E.g., because it is inside a comment
3844 or a string.
3845 When {skip} is omitted or empty, every match is accepted.
3846 When evaluating {skip} causes an error the search is aborted
3847 and -1 returned.
3848
3849 The value of 'ignorecase' is used. 'magic' is ignored, the
3850 patterns are used like it's on.
3851
3852 The search starts exactly at the cursor. A match with
3853 {start}, {middle} or {end} at the next character, in the
3854 direction of searching, is the first one found. Example: >
3855 if 1
3856 if 2
3857 endif 2
3858 endif 1
3859< When starting at the "if 2", with the cursor on the "i", and
3860 searching forwards, the "endif 2" is found. When starting on
3861 the character just before the "if 2", the "endif 1" will be
3862 found. That's because the "if 2" will be found first, and
3863 then this is considered to be a nested if/endif from "if 2" to
3864 "endif 2".
3865 When searching backwards and {end} is more than one character,
3866 it may be useful to put "\zs" at the end of the pattern, so
3867 that when the cursor is inside a match with the end it finds
3868 the matching start.
3869
3870 Example, to find the "endif" command in a Vim script: >
3871
3872 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
3873 \ 'getline(".") =~ "^\\s*\""')
3874
3875< The cursor must be at or after the "if" for which a match is
3876 to be found. Note that single-quote strings are used to avoid
3877 having to double the backslashes. The skip expression only
3878 catches comments at the start of a line, not after a command.
3879 Also, a word "en" or "if" halfway a line is considered a
3880 match.
3881 Another example, to search for the matching "{" of a "}": >
3882
3883 :echo searchpair('{', '', '}', 'bW')
3884
3885< This works when the cursor is at or before the "}" for which a
3886 match is to be found. To reject matches that syntax
3887 highlighting recognized as strings: >
3888
3889 :echo searchpair('{', '', '}', 'bW',
3890 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
3891<
3892server2client( {clientid}, {string}) *server2client()*
3893 Send a reply string to {clientid}. The most recent {clientid}
3894 that sent a string can be retrieved with expand("<client>").
3895 {only available when compiled with the |+clientserver| feature}
3896 Note:
3897 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003898 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003899 before calling any commands that waits for input.
3900 See also |clientserver|.
3901 Example: >
3902 :echo server2client(expand("<client>"), "HELLO")
3903<
3904serverlist() *serverlist()*
3905 Return a list of available server names, one per line.
3906 When there are no servers or the information is not available
3907 an empty string is returned. See also |clientserver|.
3908 {only available when compiled with the |+clientserver| feature}
3909 Example: >
3910 :echo serverlist()
3911<
3912setbufvar({expr}, {varname}, {val}) *setbufvar()*
3913 Set option or local variable {varname} in buffer {expr} to
3914 {val}.
3915 This also works for a global or local window option, but it
3916 doesn't work for a global or local window variable.
3917 For a local window option the global value is unchanged.
3918 For the use of {expr}, see |bufname()| above.
3919 Note that the variable name without "b:" must be used.
3920 Examples: >
3921 :call setbufvar(1, "&mod", 1)
3922 :call setbufvar("todo", "myvar", "foobar")
3923< This function is not available in the |sandbox|.
3924
3925setcmdpos({pos}) *setcmdpos()*
3926 Set the cursor position in the command line to byte position
3927 {pos}. The first position is 1.
3928 Use |getcmdpos()| to obtain the current position.
3929 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00003930 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
3931 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
3932 set after the command line is set to the expression. For
3933 |c_CTRL-R_=| it is set after evaluating the expression but
3934 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003935 When the number is too big the cursor is put at the end of the
3936 line. A number smaller than one has undefined results.
3937 Returns 0 when successful, 1 when not editing the command
3938 line.
3939
3940setline({lnum}, {line}) *setline()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003941 Set line {lnum} of the current buffer to {line}.
3942 {lnum} is used like with |getline()|.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003943 When {lnum} is just below the last line the {line} will be
3944 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003945 If this succeeds, 0 is returned. If this fails (most likely
3946 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003947 :call setline(5, strftime("%c"))
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003948< When {line} is a List then line {lnum} and following lines
3949 will be set to the items in the list. Example: >
3950 :call setline(5, ['aaa', 'bbb', 'ccc'])
3951< This is equivalent to: >
3952 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
3953 : call setline(n, l)
3954 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003955< Note: The '[ and '] marks are not set.
3956
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003957
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003958setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003959 Creates a quickfix list using the items in {list}. Each item
3960 in {list} is a dictionary. Non-dictionary items in {list} are
3961 ignored. Each dictionary item can contain the following
3962 entries:
3963
3964 filename name of a file
3965 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003966 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003967 col column number
3968 vcol when non-zero: "col" is visual column
3969 when zero: "col" is byte index
3970 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003971 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003972 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003973
Bram Moolenaar582fd852005-03-28 20:58:01 +00003974 The "col", "vcol", "nr", "type" and "text" entries are
3975 optional. Either "lnum" or "pattern" entry can be used to
3976 locate a matching error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003977 If the "filename" entry is not present or neither the "lnum"
3978 or "pattern" entries are present, then the item will not be
3979 handled as an error line.
3980 If both "pattern" and "lnum" are present then "pattern" will
3981 be used.
3982
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003983 If {action} is set to 'a', then the items from {list} are
3984 added to the existing quickfix list. If there is no existing
3985 list, then a new list is created. If {action} is set to 'r',
3986 then the items from the current quickfix list are replaced
3987 with the items from {list}. If {action} is not present or is
3988 set to ' ', then a new list is created.
3989
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003990 Returns zero for success, -1 for failure.
3991
3992 This function can be used to create a quickfix list
3993 independent of the 'errorformat' setting. Use a command like
3994 ":cc 1" to jump to the first position.
3995
3996
Bram Moolenaar071d4272004-06-13 20:20:40 +00003997 *setreg()*
3998setreg({regname}, {value} [,{options}])
3999 Set the register {regname} to {value}.
4000 If {options} contains "a" or {regname} is upper case,
4001 then the value is appended.
4002 {options} can also contains a register type specification:
4003 "c" or "v" |characterwise| mode
4004 "l" or "V" |linewise| mode
4005 "b" or "<CTRL-V>" |blockwise-visual| mode
4006 If a number immediately follows "b" or "<CTRL-V>" then this is
4007 used as the width of the selection - if it is not specified
4008 then the width of the block is set to the number of characters
4009 in the longest line (counting a <TAB> as 1 character).
4010
4011 If {options} contains no register settings, then the default
4012 is to use character mode unless {value} ends in a <NL>.
4013 Setting the '=' register is not possible.
4014 Returns zero for success, non-zero for failure.
4015
4016 Examples: >
4017 :call setreg(v:register, @*)
4018 :call setreg('*', @%, 'ac')
4019 :call setreg('a', "1\n2\n3", 'b5')
4020
4021< This example shows using the functions to save and restore a
4022 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004023 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004024 :let var_amode = getregtype('a')
4025 ....
4026 :call setreg('a', var_a, var_amode)
4027
4028< You can also change the type of a register by appending
4029 nothing: >
4030 :call setreg('a', '', 'al')
4031
4032setwinvar({nr}, {varname}, {val}) *setwinvar()*
4033 Set option or local variable {varname} in window {nr} to
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00004034 {val}. When {nr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004035 This also works for a global or local buffer option, but it
4036 doesn't work for a global or local buffer variable.
4037 For a local buffer option the global value is unchanged.
4038 Note that the variable name without "w:" must be used.
4039 Examples: >
4040 :call setwinvar(1, "&list", 0)
4041 :call setwinvar(2, "myvar", "foobar")
4042< This function is not available in the |sandbox|.
4043
4044simplify({filename}) *simplify()*
4045 Simplify the file name as much as possible without changing
4046 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
4047 Unix) are not resolved. If the first path component in
4048 {filename} designates the current directory, this will be
4049 valid for the result as well. A trailing path separator is
4050 not removed either.
4051 Example: >
4052 simplify("./dir/.././/file/") == "./file/"
4053< Note: The combination "dir/.." is only removed if "dir" is
4054 a searchable directory or does not exist. On Unix, it is also
4055 removed when "dir" is a symbolic link within the same
4056 directory. In order to resolve all the involved symbolic
4057 links before simplifying the path name, use |resolve()|.
4058
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004059
Bram Moolenaar13065c42005-01-08 16:08:21 +00004060sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004061 Sort the items in {list} in-place. Returns {list}. If you
4062 want a list to remain unmodified make a copy first: >
4063 :let sortedlist = sort(copy(mylist))
4064< Uses the string representation of each item to sort on.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004065 Numbers sort after Strings, Lists after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004066 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004067 When {func} is given and it is one then case is ignored.
4068 When {func} is a Funcref or a function name, this function is
4069 called to compare items. The function is invoked with two
4070 items as argument and must return zero if they are equal, 1 if
4071 the first one sorts after the second one, -1 if the first one
4072 sorts before the second one. Example: >
4073 func MyCompare(i1, i2)
4074 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
4075 endfunc
4076 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004077<
4078
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004079 *soundfold()*
4080soundfold({word})
4081 Return the sound-folded equivalent of {word}. Uses the first
4082 language in 'spellang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004083 soundfolding. 'spell' must be set. When no sound folding is
4084 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004085 This can be used for making spelling suggestions. Note that
4086 the method can be quite slow.
4087
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004088 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00004089spellbadword([{sentence}])
4090 Without argument: The result is the badly spelled word under
4091 or after the cursor. The cursor is moved to the start of the
4092 bad word. When no bad word is found in the cursor line the
4093 result is an empty string and the cursor doesn't move.
4094
4095 With argument: The result is the first word in {sentence} that
4096 is badly spelled. If there are no spelling mistakes the
4097 result is an empty string.
4098
4099 The return value is a list with two items:
4100 - The badly spelled word or an empty string.
4101 - The type of the spelling error:
4102 "bad" spelling mistake
4103 "rare" rare word
4104 "local" word only valid in another region
4105 "caps" word should start with Capital
4106 Example: >
4107 echo spellbadword("the quik brown fox")
4108< ['quik', 'bad'] ~
4109
4110 The spelling information for the current window is used. The
4111 'spell' option must be set and the value of 'spelllang' is
4112 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004113
4114 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004115spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004116 Return a List with spelling suggestions to replace {word}.
4117 When {max} is given up to this number of suggestions are
4118 returned. Otherwise up to 25 suggestions are returned.
4119
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004120 When the {capital} argument is given and it's non-zero only
4121 suggestions with a leading capital will be given. Use this
4122 after a match with 'spellcapcheck'.
4123
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004124 {word} can be a badly spelled word followed by other text.
4125 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00004126 suggestions also include the following text, thus you can
4127 replace a line.
4128
4129 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004130 returned. {word} itself is not included in the suggestions,
4131 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004132
4133 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004134 'spell' option must be set and the values of 'spelllang' and
4135 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004136
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004137
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004138split({expr} [, {pattern} [, {keepempty}]]) *split()*
4139 Make a List out of {expr}. When {pattern} is omitted or empty
4140 each white-separated sequence of characters becomes an item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004141 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004142 removing the matched characters.
4143 When the first or last item is empty it is omitted, unless the
4144 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00004145 Other empty items are kept when {pattern} matches at least one
4146 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004147 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004148 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004149< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004150 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00004151< If you want to keep the separator you can also use '\zs': >
4152 :echo split('abc:def:ghi', ':\zs')
4153< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004154 Splitting a table where the first element can be empty: >
4155 :let items = split(line, ':', 1)
4156< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004157
4158
Bram Moolenaar071d4272004-06-13 20:20:40 +00004159strftime({format} [, {time}]) *strftime()*
4160 The result is a String, which is a formatted date and time, as
4161 specified by the {format} string. The given {time} is used,
4162 or the current time if no time is given. The accepted
4163 {format} depends on your system, thus this is not portable!
4164 See the manual page of the C function strftime() for the
4165 format. The maximum length of the result is 80 characters.
4166 See also |localtime()| and |getftime()|.
4167 The language can be changed with the |:language| command.
4168 Examples: >
4169 :echo strftime("%c") Sun Apr 27 11:49:23 1997
4170 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
4171 :echo strftime("%y%m%d %T") 970427 11:53:55
4172 :echo strftime("%H:%M") 11:55
4173 :echo strftime("%c", getftime("file.c"))
4174 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004175< Not available on all systems. To check use: >
4176 :if exists("*strftime")
4177
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004178stridx({haystack}, {needle} [, {start}]) *stridx()*
4179 The result is a Number, which gives the byte index in
4180 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004181 If {start} is specified, the search starts at index {start}.
4182 This can be used to find a second match: >
4183 :let comma1 = stridx(line, ",")
4184 :let comma2 = stridx(line, ",", comma1 + 1)
4185< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004186 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004187 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004188 See also |strridx()|.
4189 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004190 :echo stridx("An Example", "Example") 3
4191 :echo stridx("Starting point", "Start") 0
4192 :echo stridx("Starting point", "start") -1
Bram Moolenaar05159a02005-02-26 23:04:13 +00004193< *strstr()* *strchr()*
4194 stridx() works similar to the C function strstr(). When used
4195 with a single character it works similar to strchr().
4196
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004197 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004198string({expr}) Return {expr} converted to a String. If {expr} is a Number,
4199 String or a composition of them, then the result can be parsed
4200 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004201 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00004202 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004203 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00004204 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004205 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00004206 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00004207 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004208
Bram Moolenaar071d4272004-06-13 20:20:40 +00004209 *strlen()*
4210strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00004211 {expr} in bytes.
4212 If you want to count the number of multi-byte characters (not
4213 counting composing characters) use something like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004214
4215 :let len = strlen(substitute(str, ".", "x", "g"))
Bram Moolenaare344bea2005-09-01 20:46:49 +00004216<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004217 If the argument is a Number it is first converted to a String.
4218 For other types an error is given.
4219 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004220
4221strpart({src}, {start}[, {len}]) *strpart()*
4222 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00004223 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004224 When non-existing bytes are included, this doesn't result in
4225 an error, the bytes are simply omitted.
4226 If {len} is missing, the copy continues from {start} till the
4227 end of the {src}. >
4228 strpart("abcdefg", 3, 2) == "de"
4229 strpart("abcdefg", -2, 4) == "ab"
4230 strpart("abcdefg", 5, 4) == "fg"
4231 strpart("abcdefg", 3) == "defg"
4232< Note: To get the first character, {start} must be 0. For
4233 example, to get three bytes under and after the cursor: >
4234 strpart(getline(line(".")), col(".") - 1, 3)
4235<
Bram Moolenaar677ee682005-01-27 14:41:15 +00004236strridx({haystack}, {needle} [, {start}]) *strridx()*
4237 The result is a Number, which gives the byte index in
4238 {haystack} of the last occurrence of the String {needle}.
4239 When {start} is specified, matches beyond this index are
4240 ignored. This can be used to find a match before a previous
4241 match: >
4242 :let lastcomma = strridx(line, ",")
4243 :let comma2 = strridx(line, ",", lastcomma - 1)
4244< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004245 For pattern searches use |match()|.
4246 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00004247 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004248 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004249 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaar05159a02005-02-26 23:04:13 +00004250< *strrchr()*
4251 When used with a single character it works similar to the C
4252 function strrchr().
4253
Bram Moolenaar071d4272004-06-13 20:20:40 +00004254strtrans({expr}) *strtrans()*
4255 The result is a String, which is {expr} with all unprintable
4256 characters translated into printable characters |'isprint'|.
4257 Like they are shown in a window. Example: >
4258 echo strtrans(@a)
4259< This displays a newline in register a as "^@" instead of
4260 starting a new line.
4261
4262submatch({nr}) *submatch()*
4263 Only for an expression in a |:substitute| command. Returns
4264 the {nr}'th submatch of the matched text. When {nr} is 0
4265 the whole matched text is returned.
4266 Example: >
4267 :s/\d\+/\=submatch(0) + 1/
4268< This finds the first number in the line and adds one to it.
4269 A line break is included as a newline character.
4270
4271substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
4272 The result is a String, which is a copy of {expr}, in which
4273 the first match of {pat} is replaced with {sub}. This works
4274 like the ":substitute" command (without any flags). But the
4275 matching with {pat} is always done like the 'magic' option is
4276 set and 'cpoptions' is empty (to make scripts portable).
4277 See |string-match| for how {pat} is used.
4278 And a "~" in {sub} is not replaced with the previous {sub}.
4279 Note that some codes in {sub} have a special meaning
4280 |sub-replace-special|. For example, to replace something with
4281 "\n" (two characters), use "\\\\n" or '\\n'.
4282 When {pat} does not match in {expr}, {expr} is returned
4283 unmodified.
4284 When {flags} is "g", all matches of {pat} in {expr} are
4285 replaced. Otherwise {flags} should be "".
4286 Example: >
4287 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
4288< This removes the last component of the 'path' option. >
4289 :echo substitute("testing", ".*", "\\U\\0", "")
4290< results in "TESTING".
4291
Bram Moolenaar47136d72004-10-12 20:02:24 +00004292synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004293 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00004294 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004295 The syntax ID can be used with |synIDattr()| and
4296 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004297
Bram Moolenaar47136d72004-10-12 20:02:24 +00004298 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004299 line. 'synmaxcol' applies, in a longer line zero is returned.
4300
Bram Moolenaar071d4272004-06-13 20:20:40 +00004301 When {trans} is non-zero, transparent items are reduced to the
4302 item that they reveal. This is useful when wanting to know
4303 the effective color. When {trans} is zero, the transparent
4304 item is returned. This is useful when wanting to know which
4305 syntax item is effective (e.g. inside parens).
4306 Warning: This function can be very slow. Best speed is
4307 obtained by going through the file in forward direction.
4308
4309 Example (echoes the name of the syntax item under the cursor): >
4310 :echo synIDattr(synID(line("."), col("."), 1), "name")
4311<
4312synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
4313 The result is a String, which is the {what} attribute of
4314 syntax ID {synID}. This can be used to obtain information
4315 about a syntax item.
4316 {mode} can be "gui", "cterm" or "term", to get the attributes
4317 for that mode. When {mode} is omitted, or an invalid value is
4318 used, the attributes for the currently active highlighting are
4319 used (GUI, cterm or term).
4320 Use synIDtrans() to follow linked highlight groups.
4321 {what} result
4322 "name" the name of the syntax item
4323 "fg" foreground color (GUI: color name used to set
4324 the color, cterm: color number as a string,
4325 term: empty string)
4326 "bg" background color (like "fg")
4327 "fg#" like "fg", but for the GUI and the GUI is
4328 running the name in "#RRGGBB" form
4329 "bg#" like "fg#" for "bg"
4330 "bold" "1" if bold
4331 "italic" "1" if italic
4332 "reverse" "1" if reverse
4333 "inverse" "1" if inverse (= reverse)
4334 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004335 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00004336
4337 Example (echoes the color of the syntax item under the
4338 cursor): >
4339 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
4340<
4341synIDtrans({synID}) *synIDtrans()*
4342 The result is a Number, which is the translated syntax ID of
4343 {synID}. This is the syntax group ID of what is being used to
4344 highlight the character. Highlight links given with
4345 ":highlight link" are followed.
4346
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004347system({expr} [, {input}]) *system()* *E677*
4348 Get the output of the shell command {expr}.
4349 When {input} is given, this string is written to a file and
4350 passed as stdin to the command. The string is written as-is,
4351 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00004352 yourself. Pipes are not used.
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004353 Note: newlines in {expr} may cause the command to fail. The
4354 characters in 'shellquote' and 'shellxquote' may also cause
4355 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004356 This is not to be used for interactive commands.
4357 The result is a String. Example: >
4358
4359 :let files = system("ls")
4360
4361< To make the result more system-independent, the shell output
4362 is filtered to replace <CR> with <NL> for Macintosh, and
4363 <CR><NL> with <NL> for DOS-like systems.
4364 The command executed is constructed using several options:
4365 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
4366 ({tmp} is an automatically generated file name).
4367 For Unix and OS/2 braces are put around {expr} to allow for
4368 concatenated commands.
4369
4370 The resulting error code can be found in |v:shell_error|.
4371 This function will fail in |restricted-mode|.
4372 Unlike ":!cmd" there is no automatic check for changed files.
4373 Use |:checktime| to force a check.
4374
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004375
4376taglist({expr}) *taglist()*
4377 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00004378 Each list item is a dictionary with at least the following
4379 entries:
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004380 name name of the tag.
4381 filename name of the file where the tag is
4382 defined.
4383 cmd Ex command used to locate the tag in
4384 the file.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004385 kind type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004386 entry depends on the language specific
4387 kind values generated by the ctags
4388 tool.
4389 static a file specific tag. Refer to
4390 |static-tag| for more information.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004391 The "kind" entry is only available when using Exuberant ctags
4392 generated tags file. More entries may be present, depending
4393 on the content of the tags file: access, implementation,
4394 inherits and signature. Refer to the ctags documentation for
4395 information about these fields. For C code the fields
4396 "struct", "class" and "enum" may appear, they give the name of
4397 the entity the tag is contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004398
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004399 The ex-command 'cmd' can be either an ex search pattern, a
4400 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004401
4402 If there are no matching tags, then an empty list is returned.
4403
4404 To get an exact tag match, the anchors '^' and '$' should be
4405 used in {expr}. Refer to |tag-regexp| for more information
4406 about the tag search regular expression pattern.
4407
4408 Refer to |'tags'| for information about how the tags file is
4409 located by Vim. Refer to |tags-file-format| for the format of
4410 the tags file generated by the different ctags tools.
4411
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004412 *tagfiles()*
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004413tagfiles() Returns a List with the file names used to search for tags for
4414 the current buffer. This is the 'tags' option expanded.
4415
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004416
Bram Moolenaar071d4272004-06-13 20:20:40 +00004417tempname() *tempname()* *temp-file-name*
4418 The result is a String, which is the name of a file that
4419 doesn't exist. It can be used for a temporary file. The name
4420 is different for at least 26 consecutive calls. Example: >
4421 :let tmpfile = tempname()
4422 :exe "redir > " . tmpfile
4423< For Unix, the file will be in a private directory (only
4424 accessible by the current user) to avoid security problems
4425 (e.g., a symlink attack or other people reading your file).
4426 When Vim exits the directory and all files in it are deleted.
4427 For MS-Windows forward slashes are used when the 'shellslash'
4428 option is set or when 'shellcmdflag' starts with '-'.
4429
4430tolower({expr}) *tolower()*
4431 The result is a copy of the String given, with all uppercase
4432 characters turned into lowercase (just like applying |gu| to
4433 the string).
4434
4435toupper({expr}) *toupper()*
4436 The result is a copy of the String given, with all lowercase
4437 characters turned into uppercase (just like applying |gU| to
4438 the string).
4439
Bram Moolenaar8299df92004-07-10 09:47:34 +00004440tr({src}, {fromstr}, {tostr}) *tr()*
4441 The result is a copy of the {src} string with all characters
4442 which appear in {fromstr} replaced by the character in that
4443 position in the {tostr} string. Thus the first character in
4444 {fromstr} is translated into the first character in {tostr}
4445 and so on. Exactly like the unix "tr" command.
4446 This code also deals with multibyte characters properly.
4447
4448 Examples: >
4449 echo tr("hello there", "ht", "HT")
4450< returns "Hello THere" >
4451 echo tr("<blob>", "<>", "{}")
4452< returns "{blob}"
4453
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004454 *type()*
4455type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00004456 Number: 0
4457 String: 1
4458 Funcref: 2
4459 List: 3
4460 Dictionary: 4
4461 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004462 :if type(myvar) == type(0)
4463 :if type(myvar) == type("")
4464 :if type(myvar) == type(function("tr"))
4465 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00004466 :if type(myvar) == type({})
Bram Moolenaar071d4272004-06-13 20:20:40 +00004467
Bram Moolenaar677ee682005-01-27 14:41:15 +00004468values({dict}) *values()*
4469 Return a List with all the values of {dict}. The List is in
4470 arbitrary order.
4471
4472
Bram Moolenaar071d4272004-06-13 20:20:40 +00004473virtcol({expr}) *virtcol()*
4474 The result is a Number, which is the screen column of the file
4475 position given with {expr}. That is, the last screen position
4476 occupied by the character at that position, when the screen
4477 would be of unlimited width. When there is a <Tab> at the
4478 position, the returned Number will be the column at the end of
4479 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
4480 set to 8, it returns 8.
4481 For the byte position use |col()|.
4482 When Virtual editing is active in the current mode, a position
4483 beyond the end of the line can be returned. |'virtualedit'|
4484 The accepted positions are:
4485 . the cursor position
4486 $ the end of the cursor line (the result is the
4487 number of displayed characters in the cursor line
4488 plus one)
4489 'x position of mark x (if the mark is not set, 0 is
4490 returned)
4491 Note that only marks in the current file can be used.
4492 Examples: >
4493 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
4494 virtcol("$") with text "foo^Lbar", returns 9
4495 virtcol("'t") with text " there", with 't at 'h', returns 6
4496< The first column is 1. 0 is returned for an error.
4497
4498visualmode([expr]) *visualmode()*
4499 The result is a String, which describes the last Visual mode
4500 used. Initially it returns an empty string, but once Visual
4501 mode has been used, it returns "v", "V", or "<CTRL-V>" (a
4502 single CTRL-V character) for character-wise, line-wise, or
4503 block-wise Visual mode respectively.
4504 Example: >
4505 :exe "normal " . visualmode()
4506< This enters the same Visual mode as before. It is also useful
4507 in scripts if you wish to act differently depending on the
4508 Visual mode that was used.
4509
4510 If an expression is supplied that results in a non-zero number
4511 or a non-empty string, then the Visual mode will be cleared
4512 and the old value is returned. Note that " " and "0" are also
4513 non-empty strings, thus cause the mode to be cleared.
4514
4515 *winbufnr()*
4516winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004517 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004518 the buffer in the current window is returned. When window
4519 {nr} doesn't exist, -1 is returned.
4520 Example: >
4521 :echo "The file in the current window is " . bufname(winbufnr(0))
4522<
4523 *wincol()*
4524wincol() The result is a Number, which is the virtual column of the
4525 cursor in the window. This is counting screen cells from the
4526 left side of the window. The leftmost column is one.
4527
4528winheight({nr}) *winheight()*
4529 The result is a Number, which is the height of window {nr}.
4530 When {nr} is zero, the height of the current window is
4531 returned. When window {nr} doesn't exist, -1 is returned.
4532 An existing window always has a height of zero or more.
4533 Examples: >
4534 :echo "The current window has " . winheight(0) . " lines."
4535<
4536 *winline()*
4537winline() The result is a Number, which is the screen line of the cursor
4538 in the window. This is counting screen lines from the top of
4539 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004540 If the cursor was moved the view on the file will be updated
4541 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004542
4543 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004544winnr([{arg}]) The result is a Number, which is the number of the current
4545 window. The top window has number 1.
4546 When the optional argument is "$", the number of the
4547 last window is returnd (the window count).
4548 When the optional argument is "#", the number of the last
4549 accessed window is returned (where |CTRL-W_p| goes to).
4550 If there is no previous window 0 is returned.
4551 The number can be used with |CTRL-W_w| and ":wincmd w"
4552 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004553
4554 *winrestcmd()*
4555winrestcmd() Returns a sequence of |:resize| commands that should restore
4556 the current window sizes. Only works properly when no windows
4557 are opened or closed and the current window is unchanged.
4558 Example: >
4559 :let cmd = winrestcmd()
4560 :call MessWithWindowSizes()
4561 :exe cmd
4562
4563winwidth({nr}) *winwidth()*
4564 The result is a Number, which is the width of window {nr}.
4565 When {nr} is zero, the width of the current window is
4566 returned. When window {nr} doesn't exist, -1 is returned.
4567 An existing window always has a width of zero or more.
4568 Examples: >
4569 :echo "The current window has " . winwidth(0) . " columns."
4570 :if winwidth(0) <= 50
4571 : exe "normal 50\<C-W>|"
4572 :endif
4573<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004574 *writefile()*
4575writefile({list}, {fname} [, {binary}])
4576 Write List {list} to file {fname}. Each list item is
4577 separated with a NL. Each list item must be a String or
4578 Number.
4579 When {binary} is equal to "b" binary mode is used: There will
4580 not be a NL after the last list item. An empty item at the
4581 end does cause the last line in the file to end in a NL.
4582 All NL characters are replaced with a NUL character.
4583 Inserting CR characters needs to be done before passing {list}
4584 to writefile().
4585 An existing file is overwritten, if possible.
4586 When the write fails -1 is returned, otherwise 0. There is an
4587 error message if the file can't be created or when writing
4588 fails.
4589 Also see |readfile()|.
4590 To copy a file byte for byte: >
4591 :let fl = readfile("foo", "b")
4592 :call writefile(fl, "foocopy", "b")
4593<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004594
4595 *feature-list*
4596There are three types of features:
45971. Features that are only supported when they have been enabled when Vim
4598 was compiled |+feature-list|. Example: >
4599 :if has("cindent")
46002. Features that are only supported when certain conditions have been met.
4601 Example: >
4602 :if has("gui_running")
4603< *has-patch*
46043. Included patches. First check |v:version| for the version of Vim.
4605 Then the "patch123" feature means that patch 123 has been included for
4606 this version. Example (checking version 6.2.148 or later): >
4607 :if v:version > 602 || v:version == 602 && has("patch148")
4608
4609all_builtin_terms Compiled with all builtin terminals enabled.
4610amiga Amiga version of Vim.
4611arabic Compiled with Arabic support |Arabic|.
4612arp Compiled with ARP support (Amiga).
4613autocmd Compiled with autocommands support.
4614balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00004615balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004616beos BeOS version of Vim.
4617browse Compiled with |:browse| support, and browse() will
4618 work.
4619builtin_terms Compiled with some builtin terminals.
4620byte_offset Compiled with support for 'o' in 'statusline'
4621cindent Compiled with 'cindent' support.
4622clientserver Compiled with remote invocation support |clientserver|.
4623clipboard Compiled with 'clipboard' support.
4624cmdline_compl Compiled with |cmdline-completion| support.
4625cmdline_hist Compiled with |cmdline-history| support.
4626cmdline_info Compiled with 'showcmd' and 'ruler' support.
4627comments Compiled with |'comments'| support.
4628cryptv Compiled with encryption support |encryption|.
4629cscope Compiled with |cscope| support.
4630compatible Compiled to be very Vi compatible.
4631debug Compiled with "DEBUG" defined.
4632dialog_con Compiled with console dialog support.
4633dialog_gui Compiled with GUI dialog support.
4634diff Compiled with |vimdiff| and 'diff' support.
4635digraphs Compiled with support for digraphs.
4636dnd Compiled with support for the "~ register |quote_~|.
4637dos32 32 bits DOS (DJGPP) version of Vim.
4638dos16 16 bits DOS version of Vim.
4639ebcdic Compiled on a machine with ebcdic character set.
4640emacs_tags Compiled with support for Emacs tags.
4641eval Compiled with expression evaluation support. Always
4642 true, of course!
4643ex_extra Compiled with extra Ex commands |+ex_extra|.
4644extra_search Compiled with support for |'incsearch'| and
4645 |'hlsearch'|
4646farsi Compiled with Farsi support |farsi|.
4647file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004648filterpipe When 'shelltemp' is off pipes are used for shell
4649 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00004650find_in_path Compiled with support for include file searches
4651 |+find_in_path|.
4652fname_case Case in file names matters (for Amiga, MS-DOS, and
4653 Windows this is not present).
4654folding Compiled with |folding| support.
4655footer Compiled with GUI footer support. |gui-footer|
4656fork Compiled to use fork()/exec() instead of system().
4657gettext Compiled with message translation |multi-lang|
4658gui Compiled with GUI enabled.
4659gui_athena Compiled with Athena GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004660gui_gtk Compiled with GTK+ GUI (any version).
4661gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar843ee412004-06-30 16:16:41 +00004662gui_kde Compiled with KDE GUI |KVim|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004663gui_mac Compiled with Macintosh GUI.
4664gui_motif Compiled with Motif GUI.
4665gui_photon Compiled with Photon GUI.
4666gui_win32 Compiled with MS Windows Win32 GUI.
4667gui_win32s idem, and Win32s system being used (Windows 3.1)
4668gui_running Vim is running in the GUI, or it will start soon.
4669hangul_input Compiled with Hangul input support. |hangul|
4670iconv Can use iconv() for conversion.
4671insert_expand Compiled with support for CTRL-X expansion commands in
4672 Insert mode.
4673jumplist Compiled with |jumplist| support.
4674keymap Compiled with 'keymap' support.
4675langmap Compiled with 'langmap' support.
4676libcall Compiled with |libcall()| support.
4677linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
4678 support.
4679lispindent Compiled with support for lisp indenting.
4680listcmds Compiled with commands for the buffer list |:files|
4681 and the argument list |arglist|.
4682localmap Compiled with local mappings and abbr. |:map-local|
4683mac Macintosh version of Vim.
4684macunix Macintosh version of Vim, using Unix files (OS-X).
4685menu Compiled with support for |:menu|.
4686mksession Compiled with support for |:mksession|.
4687modify_fname Compiled with file name modifiers. |filename-modifiers|
4688mouse Compiled with support mouse.
4689mouseshape Compiled with support for 'mouseshape'.
4690mouse_dec Compiled with support for Dec terminal mouse.
4691mouse_gpm Compiled with support for gpm (Linux console mouse)
4692mouse_netterm Compiled with support for netterm mouse.
4693mouse_pterm Compiled with support for qnx pterm mouse.
4694mouse_xterm Compiled with support for xterm mouse.
4695multi_byte Compiled with support for editing Korean et al.
4696multi_byte_ime Compiled with support for IME input method.
4697multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00004698mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004699netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00004700netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004701ole Compiled with OLE automation support for Win32.
4702os2 OS/2 version of Vim.
4703osfiletype Compiled with support for osfiletypes |+osfiletype|
4704path_extra Compiled with up/downwards search in 'path' and 'tags'
4705perl Compiled with Perl interface.
4706postscript Compiled with PostScript file printing.
4707printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004708profile Compiled with |:profile| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004709python Compiled with Python interface.
4710qnx QNX version of Vim.
4711quickfix Compiled with |quickfix| support.
4712rightleft Compiled with 'rightleft' support.
4713ruby Compiled with Ruby interface |ruby|.
4714scrollbind Compiled with 'scrollbind' support.
4715showcmd Compiled with 'showcmd' support.
4716signs Compiled with |:sign| support.
4717smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004718sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004719statusline Compiled with support for 'statusline', 'rulerformat'
4720 and special formats of 'titlestring' and 'iconstring'.
4721sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00004722spell Compiled with spell checking support |spell|.
4723syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004724syntax_items There are active syntax highlighting items for the
4725 current buffer.
4726system Compiled to use system() instead of fork()/exec().
4727tag_binary Compiled with binary searching in tags files
4728 |tag-binary-search|.
4729tag_old_static Compiled with support for old static tags
4730 |tag-old-static|.
4731tag_any_white Compiled with support for any white characters in tags
4732 files |tag-any-white|.
4733tcl Compiled with Tcl interface.
4734terminfo Compiled with terminfo instead of termcap.
4735termresponse Compiled with support for |t_RV| and |v:termresponse|.
4736textobjects Compiled with support for |text-objects|.
4737tgetent Compiled with tgetent support, able to use a termcap
4738 or terminfo file.
4739title Compiled with window title support |'title'|.
4740toolbar Compiled with support for |gui-toolbar|.
4741unix Unix version of Vim.
4742user_commands User-defined commands.
4743viminfo Compiled with viminfo support.
4744vim_starting True while initial source'ing takes place.
4745vertsplit Compiled with vertically split windows |:vsplit|.
4746virtualedit Compiled with 'virtualedit' option.
4747visual Compiled with Visual mode.
4748visualextra Compiled with extra Visual mode commands.
4749 |blockwise-operators|.
4750vms VMS version of Vim.
4751vreplace Compiled with |gR| and |gr| commands.
4752wildignore Compiled with 'wildignore' option.
4753wildmenu Compiled with 'wildmenu' option.
4754windows Compiled with support for more than one window.
4755winaltkeys Compiled with 'winaltkeys' option.
4756win16 Win16 version of Vim (MS-Windows 3.1).
4757win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
4758win64 Win64 version of Vim (MS-Windows 64 bit).
4759win32unix Win32 version of Vim, using Unix files (Cygwin)
4760win95 Win32 version for MS-Windows 95/98/ME.
4761writebackup Compiled with 'writebackup' default on.
4762xfontset Compiled with X fontset support |xfontset|.
4763xim Compiled with X input method support |xim|.
4764xsmp Compiled with X session management support.
4765xsmp_interact Compiled with interactive X session management support.
4766xterm_clipboard Compiled with support for xterm clipboard.
4767xterm_save Compiled with support for saving and restoring the
4768 xterm screen.
4769x11 Compiled with X11 support.
4770
4771 *string-match*
4772Matching a pattern in a String
4773
4774A regexp pattern as explained at |pattern| is normally used to find a match in
4775the buffer lines. When a pattern is used to find a match in a String, almost
4776everything works in the same way. The difference is that a String is handled
4777like it is one line. When it contains a "\n" character, this is not seen as a
4778line break for the pattern. It can be matched with a "\n" in the pattern, or
4779with ".". Example: >
4780 :let a = "aaaa\nxxxx"
4781 :echo matchstr(a, "..\n..")
4782 aa
4783 xx
4784 :echo matchstr(a, "a.x")
4785 a
4786 x
4787
4788Don't forget that "^" will only match at the first character of the String and
4789"$" at the last character of the string. They don't match after or before a
4790"\n".
4791
4792==============================================================================
47935. Defining functions *user-functions*
4794
4795New functions can be defined. These can be called just like builtin
4796functions. The function executes a sequence of Ex commands. Normal mode
4797commands can be executed with the |:normal| command.
4798
4799The function name must start with an uppercase letter, to avoid confusion with
4800builtin functions. To prevent from using the same name in different scripts
4801avoid obvious, short names. A good habit is to start the function name with
4802the name of the script, e.g., "HTMLcolor()".
4803
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004804It's also possible to use curly braces, see |curly-braces-names|. And the
4805|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004806
4807 *local-function*
4808A function local to a script must start with "s:". A local script function
4809can only be called from within the script and from functions, user commands
4810and autocommands defined in the script. It is also possible to call the
4811function from a mappings defined in the script, but then |<SID>| must be used
4812instead of "s:" when the mapping is expanded outside of the script.
4813
4814 *:fu* *:function* *E128* *E129* *E123*
4815:fu[nction] List all functions and their arguments.
4816
4817:fu[nction] {name} List function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004818 {name} can also be a Dictionary entry that is a
4819 Funcref: >
4820 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004821
4822:fu[nction] /{pattern} List functions with a name matching {pattern}.
4823 Example that lists all functions ending with "File": >
4824 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00004825<
4826 *:function-verbose*
4827When 'verbose' is non-zero, listing a function will also display where it was
4828last defined. Example: >
4829
4830 :verbose function SetFileTypeSH
4831 function SetFileTypeSH(name)
4832 Last set from /usr/share/vim/vim-7.0/filetype.vim
4833<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00004834See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00004835
4836 *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004837:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004838 Define a new function by the name {name}. The name
4839 must be made of alphanumeric characters and '_', and
4840 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004841
4842 {name} can also be a Dictionary entry that is a
4843 Funcref: >
4844 :function dict.init(arg)
4845< "dict" must be an existing dictionary. The entry
4846 "init" is added if it didn't exist yet. Otherwise [!]
4847 is required to overwrite an existing function. The
4848 result is a |Funcref| to a numbered function. The
4849 function can only be used with a |Funcref| and will be
4850 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004851 *E127* *E122*
4852 When a function by this name already exists and [!] is
4853 not used an error message is given. When [!] is used,
4854 an existing function is silently replaced. Unless it
4855 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004856
4857 For the {arguments} see |function-argument|.
4858
Bram Moolenaar071d4272004-06-13 20:20:40 +00004859 *a:firstline* *a:lastline*
4860 When the [range] argument is added, the function is
4861 expected to take care of a range itself. The range is
4862 passed as "a:firstline" and "a:lastline". If [range]
4863 is excluded, ":{range}call" will call the function for
4864 each line in the range, with the cursor on the start
4865 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004866
Bram Moolenaar071d4272004-06-13 20:20:40 +00004867 When the [abort] argument is added, the function will
4868 abort as soon as an error is detected.
4869 The last used search pattern and the redo command "."
4870 will not be changed by the function.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004871
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004872 When the [dict] argument is added, the function must
4873 be invoked through an entry in a Dictionary. The
4874 local variable "self" will then be set to the
4875 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004876
4877 *:endf* *:endfunction* *E126* *E193*
4878:endf[unction] The end of a function definition. Must be on a line
4879 by its own, without other commands.
4880
4881 *:delf* *:delfunction* *E130* *E131*
4882:delf[unction] {name} Delete function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004883 {name} can also be a Dictionary entry that is a
4884 Funcref: >
4885 :delfunc dict.init
4886< This will remove the "init" entry from "dict". The
4887 function is deleted if there are no more references to
4888 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004889 *:retu* *:return* *E133*
4890:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
4891 evaluated and returned as the result of the function.
4892 If "[expr]" is not given, the number 0 is returned.
4893 When a function ends without an explicit ":return",
4894 the number 0 is returned.
4895 Note that there is no check for unreachable lines,
4896 thus there is no warning if commands follow ":return".
4897
4898 If the ":return" is used after a |:try| but before the
4899 matching |:finally| (if present), the commands
4900 following the ":finally" up to the matching |:endtry|
4901 are executed first. This process applies to all
4902 nested ":try"s inside the function. The function
4903 returns at the outermost ":endtry".
4904
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004905 *function-argument* *a:var*
4906An argument can be defined by giving its name. In the function this can then
4907be used as "a:name" ("a:" for argument).
4908 *a:0* *a:1* *a:000* *E740*
4909Up to 20 arguments can be given, separated by commas. After the named
4910arguments an argument "..." can be specified, which means that more arguments
4911may optionally be following. In the function the extra arguments can be used
4912as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004913can be 0). "a:000" is set to a List that contains these arguments. Note that
4914"a:1" is the same as "a:000[0]".
4915 *E742*
4916The a: scope and the variables in it cannot be changed, they are fixed.
4917However, if a List or Dictionary is used, you can changes their contents.
4918Thus you can pass a List to a function and have the function add an item to
4919it. If you want to make sure the function cannot change a List or Dictionary
4920use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004921
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004922When not using "...", the number of arguments in a function call must be equal
4923to the number of named arguments. When using "...", the number of arguments
4924may be larger.
4925
4926It is also possible to define a function without any arguments. You must
4927still supply the () then. The body of the function follows in the next lines,
4928until the matching |:endfunction|. It is allowed to define another function
4929inside a function body.
4930
4931 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004932Inside a function variables can be used. These are local variables, which
4933will disappear when the function returns. Global variables need to be
4934accessed with "g:".
4935
4936Example: >
4937 :function Table(title, ...)
4938 : echohl Title
4939 : echo a:title
4940 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00004941 : echo a:0 . " items:"
4942 : for s in a:000
4943 : echon ' ' . s
4944 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004945 :endfunction
4946
4947This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00004948 call Table("Table", "line1", "line2")
4949 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004950
4951To return more than one value, pass the name of a global variable: >
4952 :function Compute(n1, n2, divname)
4953 : if a:n2 == 0
4954 : return "fail"
4955 : endif
4956 : let g:{a:divname} = a:n1 / a:n2
4957 : return "ok"
4958 :endfunction
4959
4960This function can then be called with: >
4961 :let success = Compute(13, 1324, "div")
4962 :if success == "ok"
4963 : echo div
4964 :endif
4965
4966An alternative is to return a command that can be executed. This also works
4967with local variables in a calling function. Example: >
4968 :function Foo()
4969 : execute Bar()
4970 : echo "line " . lnum . " column " . col
4971 :endfunction
4972
4973 :function Bar()
4974 : return "let lnum = " . line(".") . " | let col = " . col(".")
4975 :endfunction
4976
4977The names "lnum" and "col" could also be passed as argument to Bar(), to allow
4978the caller to set the names.
4979
4980 *:cal* *:call* *E107*
4981:[range]cal[l] {name}([arguments])
4982 Call a function. The name of the function and its arguments
4983 are as specified with |:function|. Up to 20 arguments can be
4984 used.
4985 Without a range and for functions that accept a range, the
4986 function is called once. When a range is given the cursor is
4987 positioned at the start of the first line before executing the
4988 function.
4989 When a range is given and the function doesn't handle it
4990 itself, the function is executed for each line in the range,
4991 with the cursor in the first column of that line. The cursor
4992 is left at the last line (possibly moved by the last function
4993 call). The arguments are re-evaluated for each line. Thus
4994 this works:
4995 *function-range-example* >
4996 :function Mynumber(arg)
4997 : echo line(".") . " " . a:arg
4998 :endfunction
4999 :1,5call Mynumber(getline("."))
5000<
5001 The "a:firstline" and "a:lastline" are defined anyway, they
5002 can be used to do something different at the start or end of
5003 the range.
5004
5005 Example of a function that handles the range itself: >
5006
5007 :function Cont() range
5008 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
5009 :endfunction
5010 :4,8call Cont()
5011<
5012 This function inserts the continuation character "\" in front
5013 of all the lines in the range, except the first one.
5014
5015 *E132*
5016The recursiveness of user functions is restricted with the |'maxfuncdepth'|
5017option.
5018
Bram Moolenaar7c626922005-02-07 22:01:03 +00005019
5020AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005021 *autoload-functions*
5022When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00005023only when they are used. There are two methods: with an autocommand and with
5024the "autoload" directory in 'runtimepath'.
5025
5026
5027Using an autocommand ~
5028
Bram Moolenaar05159a02005-02-26 23:04:13 +00005029This is introduced in the user manual, section |41.14|.
5030
Bram Moolenaar7c626922005-02-07 22:01:03 +00005031The autocommand is useful if you have a plugin that is a long Vim script file.
5032You can define the autocommand and quickly quit the script with |:finish|.
5033That makes Vim startup faster. The autocommand should then load the same file
5034again, setting a variable to skip the |:finish| command.
5035
5036Use the FuncUndefined autocommand event with a pattern that matches the
5037function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005038
5039 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
5040
5041The file "~/vim/bufnetfuncs.vim" should then define functions that start with
5042"BufNet". Also see |FuncUndefined|.
5043
Bram Moolenaar7c626922005-02-07 22:01:03 +00005044
5045Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005046 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005047This is introduced in the user manual, section |41.15|.
5048
Bram Moolenaar7c626922005-02-07 22:01:03 +00005049Using a script in the "autoload" directory is simpler, but requires using
5050exactly the right file name. A function that can be autoloaded has a name
5051like this: >
5052
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005053 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005054
5055When such a function is called, and it is not defined yet, Vim will search the
5056"autoload" directories in 'runtimepath' for a script file called
5057"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
5058then define the function like this: >
5059
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005060 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005061 echo "Done!"
5062 endfunction
5063
Bram Moolenaar60a795a2005-09-16 21:55:43 +00005064The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00005065exactly, and the defined function must have the name exactly as it will be
5066called.
5067
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005068It is possible to use subdirectories. Every # in the function name works like
5069a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00005070
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005071 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005072
5073Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
5074
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005075This also works when reading a variable that has not been set yet: >
5076
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005077 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005078
Bram Moolenaara5792f52005-11-23 21:25:05 +00005079However, when the autoload script was already loaded it won't be loaded again
5080for an unknown variable.
5081
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005082When assigning a value to such a variable nothing special happens. This can
5083be used to pass settings to the autoload script before it's loaded: >
5084
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005085 :let foo#bar#toggle = 1
5086 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005087
Bram Moolenaar4399ef42005-02-12 14:29:27 +00005088Note that when you make a mistake and call a function that is supposed to be
5089defined in an autoload script, but the script doesn't actually define the
5090function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005091And you will get an error message every time.
5092
5093Also note that if you have two script files, and one calls a function in the
5094other and vise versa, before the used function is defined, it won't work.
5095Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00005096
Bram Moolenaar071d4272004-06-13 20:20:40 +00005097==============================================================================
50986. Curly braces names *curly-braces-names*
5099
5100Wherever you can use a variable, you can use a "curly braces name" variable.
5101This is a regular variable name with one or more expressions wrapped in braces
5102{} like this: >
5103 my_{adjective}_variable
5104
5105When Vim encounters this, it evaluates the expression inside the braces, puts
5106that in place of the expression, and re-interprets the whole as a variable
5107name. So in the above example, if the variable "adjective" was set to
5108"noisy", then the reference would be to "my_noisy_variable", whereas if
5109"adjective" was set to "quiet", then it would be to "my_quiet_variable".
5110
5111One application for this is to create a set of variables governed by an option
5112value. For example, the statement >
5113 echo my_{&background}_message
5114
5115would output the contents of "my_dark_message" or "my_light_message" depending
5116on the current value of 'background'.
5117
5118You can use multiple brace pairs: >
5119 echo my_{adverb}_{adjective}_message
5120..or even nest them: >
5121 echo my_{ad{end_of_word}}_message
5122where "end_of_word" is either "verb" or "jective".
5123
5124However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005125variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005126 :let foo='a + b'
5127 :echo c{foo}d
5128.. since the result of expansion is "ca + bd", which is not a variable name.
5129
5130 *curly-braces-function-names*
5131You can call and define functions by an evaluated name in a similar way.
5132Example: >
5133 :let func_end='whizz'
5134 :call my_func_{func_end}(parameter)
5135
5136This would call the function "my_func_whizz(parameter)".
5137
5138==============================================================================
51397. Commands *expression-commands*
5140
5141:let {var-name} = {expr1} *:let* *E18*
5142 Set internal variable {var-name} to the result of the
5143 expression {expr1}. The variable will get the type
5144 from the {expr}. If {var-name} didn't exist yet, it
5145 is created.
5146
Bram Moolenaar13065c42005-01-08 16:08:21 +00005147:let {var-name}[{idx}] = {expr1} *E689*
5148 Set a list item to the result of the expression
5149 {expr1}. {var-name} must refer to a list and {idx}
5150 must be a valid index in that list. For nested list
5151 the index can be repeated.
5152 This cannot be used to add an item to a list.
5153
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005154 *E711* *E719*
5155:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005156 Set a sequence of items in a List to the result of the
5157 expression {expr1}, which must be a list with the
5158 correct number of items.
5159 {idx1} can be omitted, zero is used instead.
5160 {idx2} can be omitted, meaning the end of the list.
5161 When the selected range of items is partly past the
5162 end of the list, items will be added.
5163
Bram Moolenaar748bf032005-02-02 23:04:36 +00005164 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005165:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
5166:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
5167:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
5168 These fail if {var} was not set yet and when the type
5169 of {var} and {expr1} don't fit the operator.
5170
5171
Bram Moolenaar071d4272004-06-13 20:20:40 +00005172:let ${env-name} = {expr1} *:let-environment* *:let-$*
5173 Set environment variable {env-name} to the result of
5174 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005175:let ${env-name} .= {expr1}
5176 Append {expr1} to the environment variable {env-name}.
5177 If the environment variable didn't exist yet this
5178 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005179
5180:let @{reg-name} = {expr1} *:let-register* *:let-@*
5181 Write the result of the expression {expr1} in register
5182 {reg-name}. {reg-name} must be a single letter, and
5183 must be the name of a writable register (see
5184 |registers|). "@@" can be used for the unnamed
5185 register, "@/" for the search pattern.
5186 If the result of {expr1} ends in a <CR> or <NL>, the
5187 register will be linewise, otherwise it will be set to
5188 characterwise.
5189 This can be used to clear the last search pattern: >
5190 :let @/ = ""
5191< This is different from searching for an empty string,
5192 that would match everywhere.
5193
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005194:let @{reg-name} .= {expr1}
5195 Append {expr1} to register {reg-name}. If the
5196 register was empty it's like setting it to {expr1}.
5197
Bram Moolenaar071d4272004-06-13 20:20:40 +00005198:let &{option-name} = {expr1} *:let-option* *:let-star*
5199 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005200 expression {expr1}. A String or Number value is
5201 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005202 For an option local to a window or buffer the effect
5203 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00005204 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005205 Example: >
5206 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00005207
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005208:let &{option-name} .= {expr1}
5209 For a string option: Append {expr1} to the value.
5210 Does not insert a comma like |:set+=|.
5211
5212:let &{option-name} += {expr1}
5213:let &{option-name} -= {expr1}
5214 For a number or boolean option: Add or subtract
5215 {expr1}.
5216
Bram Moolenaar071d4272004-06-13 20:20:40 +00005217:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005218:let &l:{option-name} .= {expr1}
5219:let &l:{option-name} += {expr1}
5220:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005221 Like above, but only set the local value of an option
5222 (if there is one). Works like |:setlocal|.
5223
5224:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005225:let &g:{option-name} .= {expr1}
5226:let &g:{option-name} += {expr1}
5227:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005228 Like above, but only set the global value of an option
5229 (if there is one). Works like |:setglobal|.
5230
Bram Moolenaar13065c42005-01-08 16:08:21 +00005231:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005232 {expr1} must evaluate to a List. The first item in
5233 the list is assigned to {name1}, the second item to
5234 {name2}, etc.
5235 The number of names must match the number of items in
5236 the List.
5237 Each name can be one of the items of the ":let"
5238 command as mentioned above.
5239 Example: >
5240 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005241< Detail: {expr1} is evaluated first, then the
5242 assignments are done in sequence. This matters if
5243 {name2} depends on {name1}. Example: >
5244 :let x = [0, 1]
5245 :let i = 0
5246 :let [i, x[i]] = [1, 2]
5247 :echo x
5248< The result is [0, 2].
5249
5250:let [{name1}, {name2}, ...] .= {expr1}
5251:let [{name1}, {name2}, ...] += {expr1}
5252:let [{name1}, {name2}, ...] -= {expr1}
5253 Like above, but append/add/subtract the value for each
5254 List item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005255
5256:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar677ee682005-01-27 14:41:15 +00005257 Like |:let-unpack| above, but the List may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005258 items than there are names. A list of the remaining
5259 items is assigned to {lastname}. If there are no
5260 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005261 Example: >
5262 :let [a, b; rest] = ["aval", "bval", 3, 4]
5263<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005264:let [{name}, ..., ; {lastname}] .= {expr1}
5265:let [{name}, ..., ; {lastname}] += {expr1}
5266:let [{name}, ..., ; {lastname}] -= {expr1}
5267 Like above, but append/add/subtract the value for each
5268 List item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005269 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005270:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00005271 variable names may be given. Special names recognized
5272 here: *E738*
5273 g: global variables.
5274 b: local buffer variables.
5275 w: local window variables.
5276 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005277
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005278:let List the values of all variables. The type of the
5279 variable is indicated before the value:
5280 <nothing> String
5281 # Number
5282 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00005283
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005284
5285:unl[et][!] {name} ... *:unlet* *:unl* *E108*
5286 Remove the internal variable {name}. Several variable
5287 names can be given, they are all removed. The name
5288 may also be a List or Dictionary item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005289 With [!] no error message is given for non-existing
5290 variables.
Bram Moolenaar9cd15162005-01-16 22:02:49 +00005291 One or more items from a List can be removed: >
5292 :unlet list[3] " remove fourth item
5293 :unlet list[3:] " remove fourth item to last
5294< One item from a Dictionary can be removed at a time: >
5295 :unlet dict['two']
5296 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00005297
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005298:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
5299 Lock the internal variable {name}. Locking means that
5300 it can no longer be changed (until it is unlocked).
5301 A locked variable can be deleted: >
5302 :lockvar v
5303 :let v = 'asdf' " fails!
5304 :unlet v
5305< *E741*
5306 If you try to change a locked variable you get an
5307 error message: "E741: Value of {name} is locked"
5308
5309 [depth] is relevant when locking a List or Dictionary.
5310 It specifies how deep the locking goes:
5311 1 Lock the List or Dictionary itself,
5312 cannot add or remove items, but can
5313 still change their values.
5314 2 Also lock the values, cannot change
5315 the items. If an item is a List or
5316 Dictionary, cannot add or remove
5317 items, but can still change the
5318 values.
5319 3 Like 2 but for the List/Dictionary in
5320 the List/Dictionary, one level deeper.
5321 The default [depth] is 2, thus when {name} is a List
5322 or Dictionary the values cannot be changed.
5323 *E743*
5324 For unlimited depth use [!] and omit [depth].
5325 However, there is a maximum depth of 100 to catch
5326 loops.
5327
5328 Note that when two variables refer to the same List
5329 and you lock one of them, the List will also be locked
5330 when used through the other variable. Example: >
5331 :let l = [0, 1, 2, 3]
5332 :let cl = l
5333 :lockvar l
5334 :let cl[1] = 99 " won't work!
5335< You may want to make a copy of a list to avoid this.
5336 See |deepcopy()|.
5337
5338
5339:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
5340 Unlock the internal variable {name}. Does the
5341 opposite of |:lockvar|.
5342
5343
Bram Moolenaar071d4272004-06-13 20:20:40 +00005344:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
5345:en[dif] Execute the commands until the next matching ":else"
5346 or ":endif" if {expr1} evaluates to non-zero.
5347
5348 From Vim version 4.5 until 5.0, every Ex command in
5349 between the ":if" and ":endif" is ignored. These two
5350 commands were just to allow for future expansions in a
5351 backwards compatible way. Nesting was allowed. Note
5352 that any ":else" or ":elseif" was ignored, the "else"
5353 part was not executed either.
5354
5355 You can use this to remain compatible with older
5356 versions: >
5357 :if version >= 500
5358 : version-5-specific-commands
5359 :endif
5360< The commands still need to be parsed to find the
5361 "endif". Sometimes an older Vim has a problem with a
5362 new command. For example, ":silent" is recognized as
5363 a ":substitute" command. In that case ":execute" can
5364 avoid problems: >
5365 :if version >= 600
5366 : execute "silent 1,$delete"
5367 :endif
5368<
5369 NOTE: The ":append" and ":insert" commands don't work
5370 properly in between ":if" and ":endif".
5371
5372 *:else* *:el* *E581* *E583*
5373:el[se] Execute the commands until the next matching ":else"
5374 or ":endif" if they previously were not being
5375 executed.
5376
5377 *:elseif* *:elsei* *E582* *E584*
5378:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
5379 is no extra ":endif".
5380
5381:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005382 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005383:endw[hile] Repeat the commands between ":while" and ":endwhile",
5384 as long as {expr1} evaluates to non-zero.
5385 When an error is detected from a command inside the
5386 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00005387 Example: >
5388 :let lnum = 1
5389 :while lnum <= line("$")
5390 :call FixLine(lnum)
5391 :let lnum = lnum + 1
5392 :endwhile
5393<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005394 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00005395 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005396
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005397:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00005398:endfo[r] *:endfo* *:endfor*
5399 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005400 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005401 value of each item.
5402 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00005403 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00005404 Changing {list} inside the loop affects what items are
5405 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005406 :for item in copy(mylist)
5407< When not making a copy, Vim stores a reference to the
5408 next item in the list, before executing the commands
5409 with the current item. Thus the current item can be
5410 removed without effect. Removing any later item means
5411 it will not be found. Thus the following example
5412 works (an inefficient way to make a list empty): >
5413 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00005414 :call remove(mylist, 0)
5415 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005416< Note that reordering the list (e.g., with sort() or
5417 reverse()) may have unexpected effects.
5418 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00005419 identical to avoid errors for the type of {var}
5420 changing. Unlet the variable at the end of the loop
5421 to allow multiple item types.
5422
Bram Moolenaar12805862005-01-05 22:16:17 +00005423:for [{var1}, {var2}, ...] in {listlist}
5424:endfo[r]
5425 Like ":for" above, but each item in {listlist} must be
5426 a list, of which each item is assigned to {var1},
5427 {var2}, etc. Example: >
5428 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
5429 :echo getline(lnum)[col]
5430 :endfor
5431<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005432 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00005433:con[tinue] When used inside a ":while" or ":for" loop, jumps back
5434 to the start of the loop.
5435 If it is used after a |:try| inside the loop but
5436 before the matching |:finally| (if present), the
5437 commands following the ":finally" up to the matching
5438 |:endtry| are executed first. This process applies to
5439 all nested ":try"s inside the loop. The outermost
5440 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005441
5442 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00005443:brea[k] When used inside a ":while" or ":for" loop, skips to
5444 the command after the matching ":endwhile" or
5445 ":endfor".
5446 If it is used after a |:try| inside the loop but
5447 before the matching |:finally| (if present), the
5448 commands following the ":finally" up to the matching
5449 |:endtry| are executed first. This process applies to
5450 all nested ":try"s inside the loop. The outermost
5451 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005452
5453:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
5454:endt[ry] Change the error handling for the commands between
5455 ":try" and ":endtry" including everything being
5456 executed across ":source" commands, function calls,
5457 or autocommand invocations.
5458
5459 When an error or interrupt is detected and there is
5460 a |:finally| command following, execution continues
5461 after the ":finally". Otherwise, or when the
5462 ":endtry" is reached thereafter, the next
5463 (dynamically) surrounding ":try" is checked for
5464 a corresponding ":finally" etc. Then the script
5465 processing is terminated. (Whether a function
5466 definition has an "abort" argument does not matter.)
5467 Example: >
5468 :try | edit too much | finally | echo "cleanup" | endtry
5469 :echo "impossible" " not reached, script terminated above
5470<
5471 Moreover, an error or interrupt (dynamically) inside
5472 ":try" and ":endtry" is converted to an exception. It
5473 can be caught as if it were thrown by a |:throw|
5474 command (see |:catch|). In this case, the script
5475 processing is not terminated.
5476
5477 The value "Vim:Interrupt" is used for an interrupt
5478 exception. An error in a Vim command is converted
5479 to a value of the form "Vim({command}):{errmsg}",
5480 other errors are converted to a value of the form
5481 "Vim:{errmsg}". {command} is the full command name,
5482 and {errmsg} is the message that is displayed if the
5483 error exception is not caught, always beginning with
5484 the error number.
5485 Examples: >
5486 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
5487 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
5488<
5489 *:cat* *:catch* *E603* *E604* *E605*
5490:cat[ch] /{pattern}/ The following commands until the next ":catch",
5491 |:finally|, or |:endtry| that belongs to the same
5492 |:try| as the ":catch" are executed when an exception
5493 matching {pattern} is being thrown and has not yet
5494 been caught by a previous ":catch". Otherwise, these
5495 commands are skipped.
5496 When {pattern} is omitted all errors are caught.
5497 Examples: >
5498 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
5499 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
5500 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
5501 :catch /^Vim(write):/ " catch all errors in :write
5502 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
5503 :catch /my-exception/ " catch user exception
5504 :catch /.*/ " catch everything
5505 :catch " same as /.*/
5506<
5507 Another character can be used instead of / around the
5508 {pattern}, so long as it does not have a special
5509 meaning (e.g., '|' or '"') and doesn't occur inside
5510 {pattern}.
5511 NOTE: It is not reliable to ":catch" the TEXT of
5512 an error message because it may vary in different
5513 locales.
5514
5515 *:fina* *:finally* *E606* *E607*
5516:fina[lly] The following commands until the matching |:endtry|
5517 are executed whenever the part between the matching
5518 |:try| and the ":finally" is left: either by falling
5519 through to the ":finally" or by a |:continue|,
5520 |:break|, |:finish|, or |:return|, or by an error or
5521 interrupt or exception (see |:throw|).
5522
5523 *:th* *:throw* *E608*
5524:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
5525 If the ":throw" is used after a |:try| but before the
5526 first corresponding |:catch|, commands are skipped
5527 until the first ":catch" matching {expr1} is reached.
5528 If there is no such ":catch" or if the ":throw" is
5529 used after a ":catch" but before the |:finally|, the
5530 commands following the ":finally" (if present) up to
5531 the matching |:endtry| are executed. If the ":throw"
5532 is after the ":finally", commands up to the ":endtry"
5533 are skipped. At the ":endtry", this process applies
5534 again for the next dynamically surrounding ":try"
5535 (which may be found in a calling function or sourcing
5536 script), until a matching ":catch" has been found.
5537 If the exception is not caught, the command processing
5538 is terminated.
5539 Example: >
5540 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
5541<
5542
5543 *:ec* *:echo*
5544:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
5545 first {expr1} starts on a new line.
5546 Also see |:comment|.
5547 Use "\n" to start a new line. Use "\r" to move the
5548 cursor to the first column.
5549 Uses the highlighting set by the |:echohl| command.
5550 Cannot be followed by a comment.
5551 Example: >
5552 :echo "the value of 'shell' is" &shell
5553< A later redraw may make the message disappear again.
5554 To avoid that a command from before the ":echo" causes
5555 a redraw afterwards (redraws are often postponed until
5556 you type something), force a redraw with the |:redraw|
5557 command. Example: >
5558 :new | redraw | echo "there is a new window"
5559<
5560 *:echon*
5561:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
5562 |:comment|.
5563 Uses the highlighting set by the |:echohl| command.
5564 Cannot be followed by a comment.
5565 Example: >
5566 :echon "the value of 'shell' is " &shell
5567<
5568 Note the difference between using ":echo", which is a
5569 Vim command, and ":!echo", which is an external shell
5570 command: >
5571 :!echo % --> filename
5572< The arguments of ":!" are expanded, see |:_%|. >
5573 :!echo "%" --> filename or "filename"
5574< Like the previous example. Whether you see the double
5575 quotes or not depends on your 'shell'. >
5576 :echo % --> nothing
5577< The '%' is an illegal character in an expression. >
5578 :echo "%" --> %
5579< This just echoes the '%' character. >
5580 :echo expand("%") --> filename
5581< This calls the expand() function to expand the '%'.
5582
5583 *:echoh* *:echohl*
5584:echoh[l] {name} Use the highlight group {name} for the following
5585 |:echo|, |:echon| and |:echomsg| commands. Also used
5586 for the |input()| prompt. Example: >
5587 :echohl WarningMsg | echo "Don't panic!" | echohl None
5588< Don't forget to set the group back to "None",
5589 otherwise all following echo's will be highlighted.
5590
5591 *:echom* *:echomsg*
5592:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
5593 message in the |message-history|.
5594 Spaces are placed between the arguments as with the
5595 |:echo| command. But unprintable characters are
5596 displayed, not interpreted.
5597 Uses the highlighting set by the |:echohl| command.
5598 Example: >
5599 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
5600<
5601 *:echoe* *:echoerr*
5602:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
5603 message in the |message-history|. When used in a
5604 script or function the line number will be added.
5605 Spaces are placed between the arguments as with the
5606 :echo command. When used inside a try conditional,
5607 the message is raised as an error exception instead
5608 (see |try-echoerr|).
5609 Example: >
5610 :echoerr "This script just failed!"
5611< If you just want a highlighted message use |:echohl|.
5612 And to get a beep: >
5613 :exe "normal \<Esc>"
5614<
5615 *:exe* *:execute*
5616:exe[cute] {expr1} .. Executes the string that results from the evaluation
5617 of {expr1} as an Ex command. Multiple arguments are
5618 concatenated, with a space in between. {expr1} is
5619 used as the processed command, command line editing
5620 keys are not recognized.
5621 Cannot be followed by a comment.
5622 Examples: >
5623 :execute "buffer " nextbuf
5624 :execute "normal " count . "w"
5625<
5626 ":execute" can be used to append a command to commands
5627 that don't accept a '|'. Example: >
5628 :execute '!ls' | echo "theend"
5629
5630< ":execute" is also a nice way to avoid having to type
5631 control characters in a Vim script for a ":normal"
5632 command: >
5633 :execute "normal ixxx\<Esc>"
5634< This has an <Esc> character, see |expr-string|.
5635
5636 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00005637 you cannot start or end a "while", "for" or "if"
5638 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005639 :execute 'while i > 5'
5640 :execute 'echo "test" | break'
5641<
5642 It is allowed to have a "while" or "if" command
5643 completely in the executed string: >
5644 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
5645<
5646
5647 *:comment*
5648 ":execute", ":echo" and ":echon" cannot be followed by
5649 a comment directly, because they see the '"' as the
5650 start of a string. But, you can use '|' followed by a
5651 comment. Example: >
5652 :echo "foo" | "this is a comment
5653
5654==============================================================================
56558. Exception handling *exception-handling*
5656
5657The Vim script language comprises an exception handling feature. This section
5658explains how it can be used in a Vim script.
5659
5660Exceptions may be raised by Vim on an error or on interrupt, see
5661|catch-errors| and |catch-interrupt|. You can also explicitly throw an
5662exception by using the ":throw" command, see |throw-catch|.
5663
5664
5665TRY CONDITIONALS *try-conditionals*
5666
5667Exceptions can be caught or can cause cleanup code to be executed. You can
5668use a try conditional to specify catch clauses (that catch exceptions) and/or
5669a finally clause (to be executed for cleanup).
5670 A try conditional begins with a |:try| command and ends at the matching
5671|:endtry| command. In between, you can use a |:catch| command to start
5672a catch clause, or a |:finally| command to start a finally clause. There may
5673be none or multiple catch clauses, but there is at most one finally clause,
5674which must not be followed by any catch clauses. The lines before the catch
5675clauses and the finally clause is called a try block. >
5676
5677 :try
5678 : ...
5679 : ... TRY BLOCK
5680 : ...
5681 :catch /{pattern}/
5682 : ...
5683 : ... CATCH CLAUSE
5684 : ...
5685 :catch /{pattern}/
5686 : ...
5687 : ... CATCH CLAUSE
5688 : ...
5689 :finally
5690 : ...
5691 : ... FINALLY CLAUSE
5692 : ...
5693 :endtry
5694
5695The try conditional allows to watch code for exceptions and to take the
5696appropriate actions. Exceptions from the try block may be caught. Exceptions
5697from the try block and also the catch clauses may cause cleanup actions.
5698 When no exception is thrown during execution of the try block, the control
5699is transferred to the finally clause, if present. After its execution, the
5700script continues with the line following the ":endtry".
5701 When an exception occurs during execution of the try block, the remaining
5702lines in the try block are skipped. The exception is matched against the
5703patterns specified as arguments to the ":catch" commands. The catch clause
5704after the first matching ":catch" is taken, other catch clauses are not
5705executed. The catch clause ends when the next ":catch", ":finally", or
5706":endtry" command is reached - whatever is first. Then, the finally clause
5707(if present) is executed. When the ":endtry" is reached, the script execution
5708continues in the following line as usual.
5709 When an exception that does not match any of the patterns specified by the
5710":catch" commands is thrown in the try block, the exception is not caught by
5711that try conditional and none of the catch clauses is executed. Only the
5712finally clause, if present, is taken. The exception pends during execution of
5713the finally clause. It is resumed at the ":endtry", so that commands after
5714the ":endtry" are not executed and the exception might be caught elsewhere,
5715see |try-nesting|.
5716 When during execution of a catch clause another exception is thrown, the
5717remaining lines in that catch clause are not executed. The new exception is
5718not matched against the patterns in any of the ":catch" commands of the same
5719try conditional and none of its catch clauses is taken. If there is, however,
5720a finally clause, it is executed, and the exception pends during its
5721execution. The commands following the ":endtry" are not executed. The new
5722exception might, however, be caught elsewhere, see |try-nesting|.
5723 When during execution of the finally clause (if present) an exception is
5724thrown, the remaining lines in the finally clause are skipped. If the finally
5725clause has been taken because of an exception from the try block or one of the
5726catch clauses, the original (pending) exception is discarded. The commands
5727following the ":endtry" are not executed, and the exception from the finally
5728clause is propagated and can be caught elsewhere, see |try-nesting|.
5729
5730The finally clause is also executed, when a ":break" or ":continue" for
5731a ":while" loop enclosing the complete try conditional is executed from the
5732try block or a catch clause. Or when a ":return" or ":finish" is executed
5733from the try block or a catch clause of a try conditional in a function or
5734sourced script, respectively. The ":break", ":continue", ":return", or
5735":finish" pends during execution of the finally clause and is resumed when the
5736":endtry" is reached. It is, however, discarded when an exception is thrown
5737from the finally clause.
5738 When a ":break" or ":continue" for a ":while" loop enclosing the complete
5739try conditional or when a ":return" or ":finish" is encountered in the finally
5740clause, the rest of the finally clause is skipped, and the ":break",
5741":continue", ":return" or ":finish" is executed as usual. If the finally
5742clause has been taken because of an exception or an earlier ":break",
5743":continue", ":return", or ":finish" from the try block or a catch clause,
5744this pending exception or command is discarded.
5745
5746For examples see |throw-catch| and |try-finally|.
5747
5748
5749NESTING OF TRY CONDITIONALS *try-nesting*
5750
5751Try conditionals can be nested arbitrarily. That is, a complete try
5752conditional can be put into the try block, a catch clause, or the finally
5753clause of another try conditional. If the inner try conditional does not
5754catch an exception thrown in its try block or throws a new exception from one
5755of its catch clauses or its finally clause, the outer try conditional is
5756checked according to the rules above. If the inner try conditional is in the
5757try block of the outer try conditional, its catch clauses are checked, but
5758otherwise only the finally clause is executed. It does not matter for
5759nesting, whether the inner try conditional is directly contained in the outer
5760one, or whether the outer one sources a script or calls a function containing
5761the inner try conditional.
5762
5763When none of the active try conditionals catches an exception, just their
5764finally clauses are executed. Thereafter, the script processing terminates.
5765An error message is displayed in case of an uncaught exception explicitly
5766thrown by a ":throw" command. For uncaught error and interrupt exceptions
5767implicitly raised by Vim, the error message(s) or interrupt message are shown
5768as usual.
5769
5770For examples see |throw-catch|.
5771
5772
5773EXAMINING EXCEPTION HANDLING CODE *except-examine*
5774
5775Exception handling code can get tricky. If you are in doubt what happens, set
5776'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
5777script file. Then you see when an exception is thrown, discarded, caught, or
5778finished. When using a verbosity level of at least 14, things pending in
5779a finally clause are also shown. This information is also given in debug mode
5780(see |debug-scripts|).
5781
5782
5783THROWING AND CATCHING EXCEPTIONS *throw-catch*
5784
5785You can throw any number or string as an exception. Use the |:throw| command
5786and pass the value to be thrown as argument: >
5787 :throw 4711
5788 :throw "string"
5789< *throw-expression*
5790You can also specify an expression argument. The expression is then evaluated
5791first, and the result is thrown: >
5792 :throw 4705 + strlen("string")
5793 :throw strpart("strings", 0, 6)
5794
5795An exception might be thrown during evaluation of the argument of the ":throw"
5796command. Unless it is caught there, the expression evaluation is abandoned.
5797The ":throw" command then does not throw a new exception.
5798 Example: >
5799
5800 :function! Foo(arg)
5801 : try
5802 : throw a:arg
5803 : catch /foo/
5804 : endtry
5805 : return 1
5806 :endfunction
5807 :
5808 :function! Bar()
5809 : echo "in Bar"
5810 : return 4710
5811 :endfunction
5812 :
5813 :throw Foo("arrgh") + Bar()
5814
5815This throws "arrgh", and "in Bar" is not displayed since Bar() is not
5816executed. >
5817 :throw Foo("foo") + Bar()
5818however displays "in Bar" and throws 4711.
5819
5820Any other command that takes an expression as argument might also be
5821abandoned by an (uncaught) exception during the expression evaluation. The
5822exception is then propagated to the caller of the command.
5823 Example: >
5824
5825 :if Foo("arrgh")
5826 : echo "then"
5827 :else
5828 : echo "else"
5829 :endif
5830
5831Here neither of "then" or "else" is displayed.
5832
5833 *catch-order*
5834Exceptions can be caught by a try conditional with one or more |:catch|
5835commands, see |try-conditionals|. The values to be caught by each ":catch"
5836command can be specified as a pattern argument. The subsequent catch clause
5837gets executed when a matching exception is caught.
5838 Example: >
5839
5840 :function! Foo(value)
5841 : try
5842 : throw a:value
5843 : catch /^\d\+$/
5844 : echo "Number thrown"
5845 : catch /.*/
5846 : echo "String thrown"
5847 : endtry
5848 :endfunction
5849 :
5850 :call Foo(0x1267)
5851 :call Foo('string')
5852
5853The first call to Foo() displays "Number thrown", the second "String thrown".
5854An exception is matched against the ":catch" commands in the order they are
5855specified. Only the first match counts. So you should place the more
5856specific ":catch" first. The following order does not make sense: >
5857
5858 : catch /.*/
5859 : echo "String thrown"
5860 : catch /^\d\+$/
5861 : echo "Number thrown"
5862
5863The first ":catch" here matches always, so that the second catch clause is
5864never taken.
5865
5866 *throw-variables*
5867If you catch an exception by a general pattern, you may access the exact value
5868in the variable |v:exception|: >
5869
5870 : catch /^\d\+$/
5871 : echo "Number thrown. Value is" v:exception
5872
5873You may also be interested where an exception was thrown. This is stored in
5874|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
5875exception most recently caught as long it is not finished.
5876 Example: >
5877
5878 :function! Caught()
5879 : if v:exception != ""
5880 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
5881 : else
5882 : echo 'Nothing caught'
5883 : endif
5884 :endfunction
5885 :
5886 :function! Foo()
5887 : try
5888 : try
5889 : try
5890 : throw 4711
5891 : finally
5892 : call Caught()
5893 : endtry
5894 : catch /.*/
5895 : call Caught()
5896 : throw "oops"
5897 : endtry
5898 : catch /.*/
5899 : call Caught()
5900 : finally
5901 : call Caught()
5902 : endtry
5903 :endfunction
5904 :
5905 :call Foo()
5906
5907This displays >
5908
5909 Nothing caught
5910 Caught "4711" in function Foo, line 4
5911 Caught "oops" in function Foo, line 10
5912 Nothing caught
5913
5914A practical example: The following command ":LineNumber" displays the line
5915number in the script or function where it has been used: >
5916
5917 :function! LineNumber()
5918 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
5919 :endfunction
5920 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
5921<
5922 *try-nested*
5923An exception that is not caught by a try conditional can be caught by
5924a surrounding try conditional: >
5925
5926 :try
5927 : try
5928 : throw "foo"
5929 : catch /foobar/
5930 : echo "foobar"
5931 : finally
5932 : echo "inner finally"
5933 : endtry
5934 :catch /foo/
5935 : echo "foo"
5936 :endtry
5937
5938The inner try conditional does not catch the exception, just its finally
5939clause is executed. The exception is then caught by the outer try
5940conditional. The example displays "inner finally" and then "foo".
5941
5942 *throw-from-catch*
5943You can catch an exception and throw a new one to be caught elsewhere from the
5944catch clause: >
5945
5946 :function! Foo()
5947 : throw "foo"
5948 :endfunction
5949 :
5950 :function! Bar()
5951 : try
5952 : call Foo()
5953 : catch /foo/
5954 : echo "Caught foo, throw bar"
5955 : throw "bar"
5956 : endtry
5957 :endfunction
5958 :
5959 :try
5960 : call Bar()
5961 :catch /.*/
5962 : echo "Caught" v:exception
5963 :endtry
5964
5965This displays "Caught foo, throw bar" and then "Caught bar".
5966
5967 *rethrow*
5968There is no real rethrow in the Vim script language, but you may throw
5969"v:exception" instead: >
5970
5971 :function! Bar()
5972 : try
5973 : call Foo()
5974 : catch /.*/
5975 : echo "Rethrow" v:exception
5976 : throw v:exception
5977 : endtry
5978 :endfunction
5979< *try-echoerr*
5980Note that this method cannot be used to "rethrow" Vim error or interrupt
5981exceptions, because it is not possible to fake Vim internal exceptions.
5982Trying so causes an error exception. You should throw your own exception
5983denoting the situation. If you want to cause a Vim error exception containing
5984the original error exception value, you can use the |:echoerr| command: >
5985
5986 :try
5987 : try
5988 : asdf
5989 : catch /.*/
5990 : echoerr v:exception
5991 : endtry
5992 :catch /.*/
5993 : echo v:exception
5994 :endtry
5995
5996This code displays
5997
5998 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
5999
6000
6001CLEANUP CODE *try-finally*
6002
6003Scripts often change global settings and restore them at their end. If the
6004user however interrupts the script by pressing CTRL-C, the settings remain in
6005an inconsistent state. The same may happen to you in the development phase of
6006a script when an error occurs or you explicitly throw an exception without
6007catching it. You can solve these problems by using a try conditional with
6008a finally clause for restoring the settings. Its execution is guaranteed on
6009normal control flow, on error, on an explicit ":throw", and on interrupt.
6010(Note that errors and interrupts from inside the try conditional are converted
6011to exceptions. When not caught, they terminate the script after the finally
6012clause has been executed.)
6013Example: >
6014
6015 :try
6016 : let s:saved_ts = &ts
6017 : set ts=17
6018 :
6019 : " Do the hard work here.
6020 :
6021 :finally
6022 : let &ts = s:saved_ts
6023 : unlet s:saved_ts
6024 :endtry
6025
6026This method should be used locally whenever a function or part of a script
6027changes global settings which need to be restored on failure or normal exit of
6028that function or script part.
6029
6030 *break-finally*
6031Cleanup code works also when the try block or a catch clause is left by
6032a ":continue", ":break", ":return", or ":finish".
6033 Example: >
6034
6035 :let first = 1
6036 :while 1
6037 : try
6038 : if first
6039 : echo "first"
6040 : let first = 0
6041 : continue
6042 : else
6043 : throw "second"
6044 : endif
6045 : catch /.*/
6046 : echo v:exception
6047 : break
6048 : finally
6049 : echo "cleanup"
6050 : endtry
6051 : echo "still in while"
6052 :endwhile
6053 :echo "end"
6054
6055This displays "first", "cleanup", "second", "cleanup", and "end". >
6056
6057 :function! Foo()
6058 : try
6059 : return 4711
6060 : finally
6061 : echo "cleanup\n"
6062 : endtry
6063 : echo "Foo still active"
6064 :endfunction
6065 :
6066 :echo Foo() "returned by Foo"
6067
6068This displays "cleanup" and "4711 returned by Foo". You don't need to add an
6069extra ":return" in the finally clause. (Above all, this would override the
6070return value.)
6071
6072 *except-from-finally*
6073Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
6074a finally clause is possible, but not recommended since it abandons the
6075cleanup actions for the try conditional. But, of course, interrupt and error
6076exceptions might get raised from a finally clause.
6077 Example where an error in the finally clause stops an interrupt from
6078working correctly: >
6079
6080 :try
6081 : try
6082 : echo "Press CTRL-C for interrupt"
6083 : while 1
6084 : endwhile
6085 : finally
6086 : unlet novar
6087 : endtry
6088 :catch /novar/
6089 :endtry
6090 :echo "Script still running"
6091 :sleep 1
6092
6093If you need to put commands that could fail into a finally clause, you should
6094think about catching or ignoring the errors in these commands, see
6095|catch-errors| and |ignore-errors|.
6096
6097
6098CATCHING ERRORS *catch-errors*
6099
6100If you want to catch specific errors, you just have to put the code to be
6101watched in a try block and add a catch clause for the error message. The
6102presence of the try conditional causes all errors to be converted to an
6103exception. No message is displayed and |v:errmsg| is not set then. To find
6104the right pattern for the ":catch" command, you have to know how the format of
6105the error exception is.
6106 Error exceptions have the following format: >
6107
6108 Vim({cmdname}):{errmsg}
6109or >
6110 Vim:{errmsg}
6111
6112{cmdname} is the name of the command that failed; the second form is used when
6113the command name is not known. {errmsg} is the error message usually produced
6114when the error occurs outside try conditionals. It always begins with
6115a capital "E", followed by a two or three-digit error number, a colon, and
6116a space.
6117
6118Examples:
6119
6120The command >
6121 :unlet novar
6122normally produces the error message >
6123 E108: No such variable: "novar"
6124which is converted inside try conditionals to an exception >
6125 Vim(unlet):E108: No such variable: "novar"
6126
6127The command >
6128 :dwim
6129normally produces the error message >
6130 E492: Not an editor command: dwim
6131which is converted inside try conditionals to an exception >
6132 Vim:E492: Not an editor command: dwim
6133
6134You can catch all ":unlet" errors by a >
6135 :catch /^Vim(unlet):/
6136or all errors for misspelled command names by a >
6137 :catch /^Vim:E492:/
6138
6139Some error messages may be produced by different commands: >
6140 :function nofunc
6141and >
6142 :delfunction nofunc
6143both produce the error message >
6144 E128: Function name must start with a capital: nofunc
6145which is converted inside try conditionals to an exception >
6146 Vim(function):E128: Function name must start with a capital: nofunc
6147or >
6148 Vim(delfunction):E128: Function name must start with a capital: nofunc
6149respectively. You can catch the error by its number independently on the
6150command that caused it if you use the following pattern: >
6151 :catch /^Vim(\a\+):E128:/
6152
6153Some commands like >
6154 :let x = novar
6155produce multiple error messages, here: >
6156 E121: Undefined variable: novar
6157 E15: Invalid expression: novar
6158Only the first is used for the exception value, since it is the most specific
6159one (see |except-several-errors|). So you can catch it by >
6160 :catch /^Vim(\a\+):E121:/
6161
6162You can catch all errors related to the name "nofunc" by >
6163 :catch /\<nofunc\>/
6164
6165You can catch all Vim errors in the ":write" and ":read" commands by >
6166 :catch /^Vim(\(write\|read\)):E\d\+:/
6167
6168You can catch all Vim errors by the pattern >
6169 :catch /^Vim\((\a\+)\)\=:E\d\+:/
6170<
6171 *catch-text*
6172NOTE: You should never catch the error message text itself: >
6173 :catch /No such variable/
6174only works in the english locale, but not when the user has selected
6175a different language by the |:language| command. It is however helpful to
6176cite the message text in a comment: >
6177 :catch /^Vim(\a\+):E108:/ " No such variable
6178
6179
6180IGNORING ERRORS *ignore-errors*
6181
6182You can ignore errors in a specific Vim command by catching them locally: >
6183
6184 :try
6185 : write
6186 :catch
6187 :endtry
6188
6189But you are strongly recommended NOT to use this simple form, since it could
6190catch more than you want. With the ":write" command, some autocommands could
6191be executed and cause errors not related to writing, for instance: >
6192
6193 :au BufWritePre * unlet novar
6194
6195There could even be such errors you are not responsible for as a script
6196writer: a user of your script might have defined such autocommands. You would
6197then hide the error from the user.
6198 It is much better to use >
6199
6200 :try
6201 : write
6202 :catch /^Vim(write):/
6203 :endtry
6204
6205which only catches real write errors. So catch only what you'd like to ignore
6206intentionally.
6207
6208For a single command that does not cause execution of autocommands, you could
6209even suppress the conversion of errors to exceptions by the ":silent!"
6210command: >
6211 :silent! nunmap k
6212This works also when a try conditional is active.
6213
6214
6215CATCHING INTERRUPTS *catch-interrupt*
6216
6217When there are active try conditionals, an interrupt (CTRL-C) is converted to
6218the exception "Vim:Interrupt". You can catch it like every exception. The
6219script is not terminated, then.
6220 Example: >
6221
6222 :function! TASK1()
6223 : sleep 10
6224 :endfunction
6225
6226 :function! TASK2()
6227 : sleep 20
6228 :endfunction
6229
6230 :while 1
6231 : let command = input("Type a command: ")
6232 : try
6233 : if command == ""
6234 : continue
6235 : elseif command == "END"
6236 : break
6237 : elseif command == "TASK1"
6238 : call TASK1()
6239 : elseif command == "TASK2"
6240 : call TASK2()
6241 : else
6242 : echo "\nIllegal command:" command
6243 : continue
6244 : endif
6245 : catch /^Vim:Interrupt$/
6246 : echo "\nCommand interrupted"
6247 : " Caught the interrupt. Continue with next prompt.
6248 : endtry
6249 :endwhile
6250
6251You can interrupt a task here by pressing CTRL-C; the script then asks for
6252a new command. If you press CTRL-C at the prompt, the script is terminated.
6253
6254For testing what happens when CTRL-C would be pressed on a specific line in
6255your script, use the debug mode and execute the |>quit| or |>interrupt|
6256command on that line. See |debug-scripts|.
6257
6258
6259CATCHING ALL *catch-all*
6260
6261The commands >
6262
6263 :catch /.*/
6264 :catch //
6265 :catch
6266
6267catch everything, error exceptions, interrupt exceptions and exceptions
6268explicitly thrown by the |:throw| command. This is useful at the top level of
6269a script in order to catch unexpected things.
6270 Example: >
6271
6272 :try
6273 :
6274 : " do the hard work here
6275 :
6276 :catch /MyException/
6277 :
6278 : " handle known problem
6279 :
6280 :catch /^Vim:Interrupt$/
6281 : echo "Script interrupted"
6282 :catch /.*/
6283 : echo "Internal error (" . v:exception . ")"
6284 : echo " - occurred at " . v:throwpoint
6285 :endtry
6286 :" end of script
6287
6288Note: Catching all might catch more things than you want. Thus, you are
6289strongly encouraged to catch only for problems that you can really handle by
6290specifying a pattern argument to the ":catch".
6291 Example: Catching all could make it nearly impossible to interrupt a script
6292by pressing CTRL-C: >
6293
6294 :while 1
6295 : try
6296 : sleep 1
6297 : catch
6298 : endtry
6299 :endwhile
6300
6301
6302EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
6303
6304Exceptions may be used during execution of autocommands. Example: >
6305
6306 :autocmd User x try
6307 :autocmd User x throw "Oops!"
6308 :autocmd User x catch
6309 :autocmd User x echo v:exception
6310 :autocmd User x endtry
6311 :autocmd User x throw "Arrgh!"
6312 :autocmd User x echo "Should not be displayed"
6313 :
6314 :try
6315 : doautocmd User x
6316 :catch
6317 : echo v:exception
6318 :endtry
6319
6320This displays "Oops!" and "Arrgh!".
6321
6322 *except-autocmd-Pre*
6323For some commands, autocommands get executed before the main action of the
6324command takes place. If an exception is thrown and not caught in the sequence
6325of autocommands, the sequence and the command that caused its execution are
6326abandoned and the exception is propagated to the caller of the command.
6327 Example: >
6328
6329 :autocmd BufWritePre * throw "FAIL"
6330 :autocmd BufWritePre * echo "Should not be displayed"
6331 :
6332 :try
6333 : write
6334 :catch
6335 : echo "Caught:" v:exception "from" v:throwpoint
6336 :endtry
6337
6338Here, the ":write" command does not write the file currently being edited (as
6339you can see by checking 'modified'), since the exception from the BufWritePre
6340autocommand abandons the ":write". The exception is then caught and the
6341script displays: >
6342
6343 Caught: FAIL from BufWrite Auto commands for "*"
6344<
6345 *except-autocmd-Post*
6346For some commands, autocommands get executed after the main action of the
6347command has taken place. If this main action fails and the command is inside
6348an active try conditional, the autocommands are skipped and an error exception
6349is thrown that can be caught by the caller of the command.
6350 Example: >
6351
6352 :autocmd BufWritePost * echo "File successfully written!"
6353 :
6354 :try
6355 : write /i/m/p/o/s/s/i/b/l/e
6356 :catch
6357 : echo v:exception
6358 :endtry
6359
6360This just displays: >
6361
6362 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
6363
6364If you really need to execute the autocommands even when the main action
6365fails, trigger the event from the catch clause.
6366 Example: >
6367
6368 :autocmd BufWritePre * set noreadonly
6369 :autocmd BufWritePost * set readonly
6370 :
6371 :try
6372 : write /i/m/p/o/s/s/i/b/l/e
6373 :catch
6374 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
6375 :endtry
6376<
6377You can also use ":silent!": >
6378
6379 :let x = "ok"
6380 :let v:errmsg = ""
6381 :autocmd BufWritePost * if v:errmsg != ""
6382 :autocmd BufWritePost * let x = "after fail"
6383 :autocmd BufWritePost * endif
6384 :try
6385 : silent! write /i/m/p/o/s/s/i/b/l/e
6386 :catch
6387 :endtry
6388 :echo x
6389
6390This displays "after fail".
6391
6392If the main action of the command does not fail, exceptions from the
6393autocommands will be catchable by the caller of the command: >
6394
6395 :autocmd BufWritePost * throw ":-("
6396 :autocmd BufWritePost * echo "Should not be displayed"
6397 :
6398 :try
6399 : write
6400 :catch
6401 : echo v:exception
6402 :endtry
6403<
6404 *except-autocmd-Cmd*
6405For some commands, the normal action can be replaced by a sequence of
6406autocommands. Exceptions from that sequence will be catchable by the caller
6407of the command.
6408 Example: For the ":write" command, the caller cannot know whether the file
6409had actually been written when the exception occurred. You need to tell it in
6410some way. >
6411
6412 :if !exists("cnt")
6413 : let cnt = 0
6414 :
6415 : autocmd BufWriteCmd * if &modified
6416 : autocmd BufWriteCmd * let cnt = cnt + 1
6417 : autocmd BufWriteCmd * if cnt % 3 == 2
6418 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6419 : autocmd BufWriteCmd * endif
6420 : autocmd BufWriteCmd * write | set nomodified
6421 : autocmd BufWriteCmd * if cnt % 3 == 0
6422 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6423 : autocmd BufWriteCmd * endif
6424 : autocmd BufWriteCmd * echo "File successfully written!"
6425 : autocmd BufWriteCmd * endif
6426 :endif
6427 :
6428 :try
6429 : write
6430 :catch /^BufWriteCmdError$/
6431 : if &modified
6432 : echo "Error on writing (file contents not changed)"
6433 : else
6434 : echo "Error after writing"
6435 : endif
6436 :catch /^Vim(write):/
6437 : echo "Error on writing"
6438 :endtry
6439
6440When this script is sourced several times after making changes, it displays
6441first >
6442 File successfully written!
6443then >
6444 Error on writing (file contents not changed)
6445then >
6446 Error after writing
6447etc.
6448
6449 *except-autocmd-ill*
6450You cannot spread a try conditional over autocommands for different events.
6451The following code is ill-formed: >
6452
6453 :autocmd BufWritePre * try
6454 :
6455 :autocmd BufWritePost * catch
6456 :autocmd BufWritePost * echo v:exception
6457 :autocmd BufWritePost * endtry
6458 :
6459 :write
6460
6461
6462EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
6463
6464Some programming languages allow to use hierarchies of exception classes or to
6465pass additional information with the object of an exception class. You can do
6466similar things in Vim.
6467 In order to throw an exception from a hierarchy, just throw the complete
6468class name with the components separated by a colon, for instance throw the
6469string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
6470 When you want to pass additional information with your exception class, add
6471it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
6472for an error when writing "myfile".
6473 With the appropriate patterns in the ":catch" command, you can catch for
6474base classes or derived classes of your hierarchy. Additional information in
6475parentheses can be cut out from |v:exception| with the ":substitute" command.
6476 Example: >
6477
6478 :function! CheckRange(a, func)
6479 : if a:a < 0
6480 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
6481 : endif
6482 :endfunction
6483 :
6484 :function! Add(a, b)
6485 : call CheckRange(a:a, "Add")
6486 : call CheckRange(a:b, "Add")
6487 : let c = a:a + a:b
6488 : if c < 0
6489 : throw "EXCEPT:MATHERR:OVERFLOW"
6490 : endif
6491 : return c
6492 :endfunction
6493 :
6494 :function! Div(a, b)
6495 : call CheckRange(a:a, "Div")
6496 : call CheckRange(a:b, "Div")
6497 : if (a:b == 0)
6498 : throw "EXCEPT:MATHERR:ZERODIV"
6499 : endif
6500 : return a:a / a:b
6501 :endfunction
6502 :
6503 :function! Write(file)
6504 : try
6505 : execute "write" a:file
6506 : catch /^Vim(write):/
6507 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
6508 : endtry
6509 :endfunction
6510 :
6511 :try
6512 :
6513 : " something with arithmetics and I/O
6514 :
6515 :catch /^EXCEPT:MATHERR:RANGE/
6516 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
6517 : echo "Range error in" function
6518 :
6519 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
6520 : echo "Math error"
6521 :
6522 :catch /^EXCEPT:IO/
6523 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
6524 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
6525 : if file !~ '^/'
6526 : let file = dir . "/" . file
6527 : endif
6528 : echo 'I/O error for "' . file . '"'
6529 :
6530 :catch /^EXCEPT/
6531 : echo "Unspecified error"
6532 :
6533 :endtry
6534
6535The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
6536a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
6537exceptions with the "Vim" prefix; they are reserved for Vim.
6538 Vim error exceptions are parameterized with the name of the command that
6539failed, if known. See |catch-errors|.
6540
6541
6542PECULIARITIES
6543 *except-compat*
6544The exception handling concept requires that the command sequence causing the
6545exception is aborted immediately and control is transferred to finally clauses
6546and/or a catch clause.
6547
6548In the Vim script language there are cases where scripts and functions
6549continue after an error: in functions without the "abort" flag or in a command
6550after ":silent!", control flow goes to the following line, and outside
6551functions, control flow goes to the line following the outermost ":endwhile"
6552or ":endif". On the other hand, errors should be catchable as exceptions
6553(thus, requiring the immediate abortion).
6554
6555This problem has been solved by converting errors to exceptions and using
6556immediate abortion (if not suppressed by ":silent!") only when a try
6557conditional is active. This is no restriction since an (error) exception can
6558be caught only from an active try conditional. If you want an immediate
6559termination without catching the error, just use a try conditional without
6560catch clause. (You can cause cleanup code being executed before termination
6561by specifying a finally clause.)
6562
6563When no try conditional is active, the usual abortion and continuation
6564behavior is used instead of immediate abortion. This ensures compatibility of
6565scripts written for Vim 6.1 and earlier.
6566
6567However, when sourcing an existing script that does not use exception handling
6568commands (or when calling one of its functions) from inside an active try
6569conditional of a new script, you might change the control flow of the existing
6570script on error. You get the immediate abortion on error and can catch the
6571error in the new script. If however the sourced script suppresses error
6572messages by using the ":silent!" command (checking for errors by testing
6573|v:errmsg| if appropriate), its execution path is not changed. The error is
6574not converted to an exception. (See |:silent|.) So the only remaining cause
6575where this happens is for scripts that don't care about errors and produce
6576error messages. You probably won't want to use such code from your new
6577scripts.
6578
6579 *except-syntax-err*
6580Syntax errors in the exception handling commands are never caught by any of
6581the ":catch" commands of the try conditional they belong to. Its finally
6582clauses, however, is executed.
6583 Example: >
6584
6585 :try
6586 : try
6587 : throw 4711
6588 : catch /\(/
6589 : echo "in catch with syntax error"
6590 : catch
6591 : echo "inner catch-all"
6592 : finally
6593 : echo "inner finally"
6594 : endtry
6595 :catch
6596 : echo 'outer catch-all caught "' . v:exception . '"'
6597 : finally
6598 : echo "outer finally"
6599 :endtry
6600
6601This displays: >
6602 inner finally
6603 outer catch-all caught "Vim(catch):E54: Unmatched \("
6604 outer finally
6605The original exception is discarded and an error exception is raised, instead.
6606
6607 *except-single-line*
6608The ":try", ":catch", ":finally", and ":endtry" commands can be put on
6609a single line, but then syntax errors may make it difficult to recognize the
6610"catch" line, thus you better avoid this.
6611 Example: >
6612 :try | unlet! foo # | catch | endtry
6613raises an error exception for the trailing characters after the ":unlet!"
6614argument, but does not see the ":catch" and ":endtry" commands, so that the
6615error exception is discarded and the "E488: Trailing characters" message gets
6616displayed.
6617
6618 *except-several-errors*
6619When several errors appear in a single command, the first error message is
6620usually the most specific one and therefor converted to the error exception.
6621 Example: >
6622 echo novar
6623causes >
6624 E121: Undefined variable: novar
6625 E15: Invalid expression: novar
6626The value of the error exception inside try conditionals is: >
6627 Vim(echo):E121: Undefined variable: novar
6628< *except-syntax-error*
6629But when a syntax error is detected after a normal error in the same command,
6630the syntax error is used for the exception being thrown.
6631 Example: >
6632 unlet novar #
6633causes >
6634 E108: No such variable: "novar"
6635 E488: Trailing characters
6636The value of the error exception inside try conditionals is: >
6637 Vim(unlet):E488: Trailing characters
6638This is done because the syntax error might change the execution path in a way
6639not intended by the user. Example: >
6640 try
6641 try | unlet novar # | catch | echo v:exception | endtry
6642 catch /.*/
6643 echo "outer catch:" v:exception
6644 endtry
6645This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
6646a "E600: Missing :endtry" error message is given, see |except-single-line|.
6647
6648==============================================================================
66499. Examples *eval-examples*
6650
6651Printing in Hex ~
6652>
6653 :" The function Nr2Hex() returns the Hex string of a number.
6654 :func Nr2Hex(nr)
6655 : let n = a:nr
6656 : let r = ""
6657 : while n
6658 : let r = '0123456789ABCDEF'[n % 16] . r
6659 : let n = n / 16
6660 : endwhile
6661 : return r
6662 :endfunc
6663
6664 :" The function String2Hex() converts each character in a string to a two
6665 :" character Hex string.
6666 :func String2Hex(str)
6667 : let out = ''
6668 : let ix = 0
6669 : while ix < strlen(a:str)
6670 : let out = out . Nr2Hex(char2nr(a:str[ix]))
6671 : let ix = ix + 1
6672 : endwhile
6673 : return out
6674 :endfunc
6675
6676Example of its use: >
6677 :echo Nr2Hex(32)
6678result: "20" >
6679 :echo String2Hex("32")
6680result: "3332"
6681
6682
6683Sorting lines (by Robert Webb) ~
6684
6685Here is a Vim script to sort lines. Highlight the lines in Vim and type
6686":Sort". This doesn't call any external programs so it'll work on any
6687platform. The function Sort() actually takes the name of a comparison
6688function as its argument, like qsort() does in C. So you could supply it
6689with different comparison functions in order to sort according to date etc.
6690>
6691 :" Function for use with Sort(), to compare two strings.
6692 :func! Strcmp(str1, str2)
6693 : if (a:str1 < a:str2)
6694 : return -1
6695 : elseif (a:str1 > a:str2)
6696 : return 1
6697 : else
6698 : return 0
6699 : endif
6700 :endfunction
6701
6702 :" Sort lines. SortR() is called recursively.
6703 :func! SortR(start, end, cmp)
6704 : if (a:start >= a:end)
6705 : return
6706 : endif
6707 : let partition = a:start - 1
6708 : let middle = partition
6709 : let partStr = getline((a:start + a:end) / 2)
6710 : let i = a:start
6711 : while (i <= a:end)
6712 : let str = getline(i)
6713 : exec "let result = " . a:cmp . "(str, partStr)"
6714 : if (result <= 0)
6715 : " Need to put it before the partition. Swap lines i and partition.
6716 : let partition = partition + 1
6717 : if (result == 0)
6718 : let middle = partition
6719 : endif
6720 : if (i != partition)
6721 : let str2 = getline(partition)
6722 : call setline(i, str2)
6723 : call setline(partition, str)
6724 : endif
6725 : endif
6726 : let i = i + 1
6727 : endwhile
6728
6729 : " Now we have a pointer to the "middle" element, as far as partitioning
6730 : " goes, which could be anywhere before the partition. Make sure it is at
6731 : " the end of the partition.
6732 : if (middle != partition)
6733 : let str = getline(middle)
6734 : let str2 = getline(partition)
6735 : call setline(middle, str2)
6736 : call setline(partition, str)
6737 : endif
6738 : call SortR(a:start, partition - 1, a:cmp)
6739 : call SortR(partition + 1, a:end, a:cmp)
6740 :endfunc
6741
6742 :" To Sort a range of lines, pass the range to Sort() along with the name of a
6743 :" function that will compare two lines.
6744 :func! Sort(cmp) range
6745 : call SortR(a:firstline, a:lastline, a:cmp)
6746 :endfunc
6747
6748 :" :Sort takes a range of lines and sorts them.
6749 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
6750<
6751 *sscanf*
6752There is no sscanf() function in Vim. If you need to extract parts from a
6753line, you can use matchstr() and substitute() to do it. This example shows
6754how to get the file name, line number and column number out of a line like
6755"foobar.txt, 123, 45". >
6756 :" Set up the match bit
6757 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
6758 :"get the part matching the whole expression
6759 :let l = matchstr(line, mx)
6760 :"get each item out of the match
6761 :let file = substitute(l, mx, '\1', '')
6762 :let lnum = substitute(l, mx, '\2', '')
6763 :let col = substitute(l, mx, '\3', '')
6764
6765The input is in the variable "line", the results in the variables "file",
6766"lnum" and "col". (idea from Michael Geddes)
6767
6768==============================================================================
676910. No +eval feature *no-eval-feature*
6770
6771When the |+eval| feature was disabled at compile time, none of the expression
6772evaluation commands are available. To prevent this from causing Vim scripts
6773to generate all kinds of errors, the ":if" and ":endif" commands are still
6774recognized, though the argument of the ":if" and everything between the ":if"
6775and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
6776only if the commands are at the start of the line. The ":else" command is not
6777recognized.
6778
6779Example of how to avoid executing commands when the |+eval| feature is
6780missing: >
6781
6782 :if 1
6783 : echo "Expression evaluation is compiled in"
6784 :else
6785 : echo "You will _never_ see this message"
6786 :endif
6787
6788==============================================================================
678911. The sandbox *eval-sandbox* *sandbox* *E48*
6790
6791The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
6792options are evaluated in a sandbox. This means that you are protected from
6793these expressions having nasty side effects. This gives some safety for when
6794these options are set from a modeline. It is also used when the command from
6795a tags file is executed.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006796The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006797
6798These items are not allowed in the sandbox:
6799 - changing the buffer text
6800 - defining or changing mapping, autocommands, functions, user commands
6801 - setting certain options (see |option-summary|)
6802 - executing a shell command
6803 - reading or writing a file
6804 - jumping to another buffer or editing a file
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006805This is not guaranteed 100% secure, but it should block most attacks.
6806
6807 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00006808:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006809 option that may have been set from a modeline, e.g.
6810 'foldexpr'.
6811
Bram Moolenaar071d4272004-06-13 20:20:40 +00006812
6813 vim:tw=78:ts=8:ft=help:norl: