blob: 9eb1ba645de1674aa98709f08760014d754ded3d [file] [log] [blame]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +00001*eval.txt* For Vim version 7.0aa. Last change: 2005 Jul 03
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*
1275v:fname_in The name of the input file. Only valid while evaluating:
1276 option used for ~
1277 'charconvert' file to be converted
1278 'diffexpr' original file
1279 'patchexpr' original file
1280 'printexpr' file to be printed
1281
1282 *v:fname_out* *fname_out-variable*
1283v:fname_out The name of the output file. Only valid while
1284 evaluating:
1285 option used for ~
1286 'charconvert' resulting converted file (*)
1287 'diffexpr' output of diff
1288 'patchexpr' resulting patched file
1289 (*) When doing conversion for a write command (e.g., ":w
1290 file") it will be equal to v:fname_in. When doing conversion
1291 for a read command (e.g., ":e file") it will be a temporary
1292 file and different from v:fname_in.
1293
1294 *v:fname_new* *fname_new-variable*
1295v:fname_new The name of the new version of the file. Only valid while
1296 evaluating 'diffexpr'.
1297
1298 *v:fname_diff* *fname_diff-variable*
1299v:fname_diff The name of the diff (patch) file. Only valid while
1300 evaluating 'patchexpr'.
1301
1302 *v:folddashes* *folddashes-variable*
1303v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1304 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001305 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001306
1307 *v:foldlevel* *foldlevel-variable*
1308v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001309 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310
1311 *v:foldend* *foldend-variable*
1312v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001313 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001314
1315 *v:foldstart* *foldstart-variable*
1316v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001317 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001318
Bram Moolenaar843ee412004-06-30 16:16:41 +00001319 *v:insertmode* *insertmode-variable*
1320v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1321 events. Values:
1322 i Insert mode
1323 r Replace mode
1324 v Virtual Replace mode
1325
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001326 *v:key* *key-variable*
1327v:key Key of the current item of a Dictionary. Only valid while
1328 evaluating the expression used with |map()| and |filter()|.
1329 Read-only.
1330
Bram Moolenaar071d4272004-06-13 20:20:40 +00001331 *v:lang* *lang-variable*
1332v:lang The current locale setting for messages of the runtime
1333 environment. This allows Vim scripts to be aware of the
1334 current language. Technical: it's the value of LC_MESSAGES.
1335 The value is system dependent.
1336 This variable can not be set directly, use the |:language|
1337 command.
1338 It can be different from |v:ctype| when messages are desired
1339 in a different language than what is used for character
1340 encoding. See |multi-lang|.
1341
1342 *v:lc_time* *lc_time-variable*
1343v:lc_time The current locale setting for time messages of the runtime
1344 environment. This allows Vim scripts to be aware of the
1345 current language. Technical: it's the value of LC_TIME.
1346 This variable can not be set directly, use the |:language|
1347 command. See |multi-lang|.
1348
1349 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001350v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1351 expressions. Only valid while one of these expressions is
1352 being evaluated. Read-only when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001353
1354 *v:prevcount* *prevcount-variable*
1355v:prevcount The count given for the last but one Normal mode command.
1356 This is the v:count value of the previous command. Useful if
1357 you want to cancel Visual mode and then use the count. >
1358 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1359< Read-only.
1360
Bram Moolenaar05159a02005-02-26 23:04:13 +00001361 *v:profiling* *profiling-variable*
1362v:profiling Normally zero. Set to one after using ":profile start".
1363 See |profiling|.
1364
Bram Moolenaar071d4272004-06-13 20:20:40 +00001365 *v:progname* *progname-variable*
1366v:progname Contains the name (with path removed) with which Vim was
1367 invoked. Allows you to do special initialisations for "view",
1368 "evim" etc., or any other name you might symlink to Vim.
1369 Read-only.
1370
1371 *v:register* *register-variable*
1372v:register The name of the register supplied to the last normal mode
1373 command. Empty if none were supplied. |getreg()| |setreg()|
1374
1375 *v:servername* *servername-variable*
1376v:servername The resulting registered |x11-clientserver| name if any.
1377 Read-only.
1378
1379 *v:shell_error* *shell_error-variable*
1380v:shell_error Result of the last shell command. When non-zero, the last
1381 shell command had an error. When zero, there was no problem.
1382 This only works when the shell returns the error code to Vim.
1383 The value -1 is often used when the command could not be
1384 executed. Read-only.
1385 Example: >
1386 :!mv foo bar
1387 :if v:shell_error
1388 : echo 'could not rename "foo" to "bar"!'
1389 :endif
1390< "shell_error" also works, for backwards compatibility.
1391
1392 *v:statusmsg* *statusmsg-variable*
1393v:statusmsg Last given status message. It's allowed to set this variable.
1394
1395 *v:termresponse* *termresponse-variable*
1396v:termresponse The escape sequence returned by the terminal for the |t_RV|
1397 termcap entry. It is set when Vim receives an escape sequence
1398 that starts with ESC [ or CSI and ends in a 'c', with only
1399 digits, ';' and '.' in between.
1400 When this option is set, the TermResponse autocommand event is
1401 fired, so that you can react to the response from the
1402 terminal.
1403 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1404 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1405 patch level (since this was introduced in patch 95, it's
1406 always 95 or bigger). Pc is always zero.
1407 {only when compiled with |+termresponse| feature}
1408
1409 *v:this_session* *this_session-variable*
1410v:this_session Full filename of the last loaded or saved session file. See
1411 |:mksession|. It is allowed to set this variable. When no
1412 session file has been saved, this variable is empty.
1413 "this_session" also works, for backwards compatibility.
1414
1415 *v:throwpoint* *throwpoint-variable*
1416v:throwpoint The point where the exception most recently caught and not
1417 finished was thrown. Not set when commands are typed. See
1418 also |v:exception| and |throw-variables|.
1419 Example: >
1420 :try
1421 : throw "oops"
1422 :catch /.*/
1423 : echo "Exception from" v:throwpoint
1424 :endtry
1425< Output: "Exception from test.vim, line 2"
1426
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001427 *v:val* *val-variable*
1428v:val Value of the current item of a List or Dictionary. Only valid
1429 while evaluating the expression used with |map()| and
1430 |filter()|. Read-only.
1431
Bram Moolenaar071d4272004-06-13 20:20:40 +00001432 *v:version* *version-variable*
1433v:version Version number of Vim: Major version number times 100 plus
1434 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1435 is 501. Read-only. "version" also works, for backwards
1436 compatibility.
1437 Use |has()| to check if a certain patch was included, e.g.: >
1438 if has("patch123")
1439< Note that patch numbers are specific to the version, thus both
1440 version 5.0 and 5.1 may have a patch 123, but these are
1441 completely different.
1442
1443 *v:warningmsg* *warningmsg-variable*
1444v:warningmsg Last given warning message. It's allowed to set this variable.
1445
1446==============================================================================
14474. Builtin Functions *functions*
1448
1449See |function-list| for a list grouped by what the function is used for.
1450
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001451(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452
1453USAGE RESULT DESCRIPTION ~
1454
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001455add( {list}, {item}) List append {item} to List {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001456append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001457append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001459argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001460argv( {nr}) String {nr} entry of the argument list
1461browse( {save}, {title}, {initdir}, {default})
1462 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001463browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001464bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001465buflisted( {expr}) Number TRUE if buffer {expr} is listed
1466bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001467bufname( {expr}) String Name of the buffer {expr}
1468bufnr( {expr}) Number Number of the buffer {expr}
1469bufwinnr( {expr}) Number window number of buffer {expr}
1470byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001471byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001472call( {func}, {arglist} [, {dict}])
1473 any call {func} with arguments {arglist}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001474char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001475cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001476col( {expr}) Number column nr of cursor or mark
1477confirm( {msg} [, {choices} [, {default} [, {type}]]])
1478 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001479copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001480count( {list}, {expr} [, {start} [, {ic}]])
1481 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001482cscope_connection( [{num} , {dbpath} [, {prepend}]])
1483 Number checks existence of cscope connection
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001484cursor( {lnum}, {col}) Number position cursor at {lnum}, {col}
1485deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001486delete( {fname}) Number delete file {fname}
1487did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001488diff_filler( {lnum}) Number diff filler lines about {lnum}
1489diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001490empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001491escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001492eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001493eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001494executable( {expr}) Number 1 if executable {expr} exists
1495exists( {expr}) Number TRUE if {expr} exists
1496expand( {expr}) String expand special keywords in {expr}
1497filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001498filter( {expr}, {string}) List/Dict remove items from {expr} where
1499 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001500finddir( {name}[, {path}[, {count}]])
1501 String Find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001502findfile( {name}[, {path}[, {count}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001503 String Find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001504filewritable( {file}) Number TRUE if {file} is a writable file
1505fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001506foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1507foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001508foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001509foldtext( ) String line displayed for closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +00001510foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001511function( {name}) Funcref reference to function {name}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001512get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001513get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001514getchar( [expr]) Number get one character from the user
1515getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001516getbufvar( {expr}, {varname}) variable {varname} in buffer {expr}
1517getcmdline() String return the current command-line
1518getcmdpos() Number return cursor position in command-line
1519getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001520getfperm( {fname}) String file permissions of file {fname}
1521getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001522getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001524getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001525getline( {lnum}) String line {lnum} of current buffer
1526getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001527getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001528getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001529getregtype( [{regname}]) String type of register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001530getwinposx() Number X coord in pixels of GUI Vim window
1531getwinposy() Number Y coord in pixels of GUI Vim window
1532getwinvar( {nr}, {varname}) variable {varname} in window {nr}
1533glob( {expr}) String expand file wildcards in {expr}
1534globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1535has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001536has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537hasmapto( {what} [, {mode}]) Number TRUE if mapping to {what} exists
1538histadd( {history},{item}) String add an item to a history
1539histdel( {history} [, {item}]) String remove an item from a history
1540histget( {history} [, {index}]) String get the item {index} from a history
1541histnr( {history}) Number highest index of a history
1542hlexists( {name}) Number TRUE if highlight group {name} exists
1543hlID( {name}) Number syntax ID of highlight group {name}
1544hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001545iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1546indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001547index( {list}, {expr} [, {start} [, {ic}]])
1548 Number index in {list} where {expr} appears
Bram Moolenaar071d4272004-06-13 20:20:40 +00001549input( {prompt} [, {text}]) String get input from the user
1550inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001551inputrestore() Number restore typeahead
1552inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001553inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001554insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001555isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001556islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar677ee682005-01-27 14:41:15 +00001557items( {dict}) List List of key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001558join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaard8b02732005-01-14 21:48:43 +00001559keys( {dict}) List List of keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001560len( {expr}) Number the length of {expr}
1561libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001562libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1563line( {expr}) Number line nr of cursor, last line or mark
1564line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001565lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001566localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001567map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001568maparg( {name}[, {mode}]) String rhs of mapping {name} in mode {mode}
1569mapcheck( {name}[, {mode}]) String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001570match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001571 Number position where {pat} matches in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001572matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001573 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001574matchlist( {expr}, {pat}[, {start}[, {count}]])
1575 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001576matchstr( {expr}, {pat}[, {start}[, {count}]])
1577 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001578max({list}) Number maximum value of items in {list}
1579min({list}) Number minumum value of items in {list}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001580mkdir({name} [, {path} [, {prot}]])
1581 Number create directory {name}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001582mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001583nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1584nr2char( {expr}) String single char with ASCII value {expr}
1585prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001586range( {expr} [, {max} [, {stride}]])
1587 List items from {expr} to {max}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001588readfile({fname} [, {binary} [, {max}]])
1589 List get list of lines from file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001590remote_expr( {server}, {string} [, {idvar}])
1591 String send expression
1592remote_foreground( {server}) Number bring Vim server to the foreground
1593remote_peek( {serverid} [, {retvar}])
1594 Number check for reply string
1595remote_read( {serverid}) String read reply string
1596remote_send( {server}, {string} [, {idvar}])
1597 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001598remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001599remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001600rename( {from}, {to}) Number rename (move) file from {from} to {to}
1601repeat( {expr}, {count}) String repeat {expr} {count} times
1602resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001603reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001604search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001605searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001606 Number search for other end of start/end pair
Bram Moolenaar071d4272004-06-13 20:20:40 +00001607server2client( {clientid}, {string})
1608 Number send reply string
1609serverlist() String get a list of available servers
1610setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1611setcmdpos( {pos}) Number set cursor position in command-line
1612setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar35c54e52005-05-20 21:25:31 +00001613setqflist( {list}[, {action}]) Number set list of quickfix items using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001614setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001615setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001616simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001617sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001618soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001619spellbadword() String badly spelled word at cursor
1620spellsuggest({word} [, {max}]) List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001621split( {expr} [, {pat} [, {keepempty}]])
1622 List make List from {pat} separated {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001624stridx( {haystack}, {needle}[, {start}])
1625 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001626string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001627strlen( {expr}) Number length of the String {expr}
1628strpart( {src}, {start}[, {len}])
1629 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001630strridx( {haystack}, {needle} [, {start}])
1631 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001632strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001633submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001634substitute( {expr}, {pat}, {sub}, {flags})
1635 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001636synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001637synIDattr( {synID}, {what} [, {mode}])
1638 String attribute {what} of syntax ID {synID}
1639synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001640system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001641taglist({expr}) List list of tags matching {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001642tempname() String name for a temporary file
1643tolower( {expr}) String the String {expr} switched to lowercase
1644toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001645tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1646 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001647type( {name}) Number type of variable {name}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001648values( {dict}) List List of values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001649virtcol( {expr}) Number screen column of cursor or mark
1650visualmode( [expr]) String last visual mode used
1651winbufnr( {nr}) Number buffer number of window {nr}
1652wincol() Number window column of the cursor
1653winheight( {nr}) Number height of window {nr}
1654winline() Number window line of the cursor
1655winnr() Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001656winrestcmd() String returns command to restore window sizes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001657winwidth( {nr}) Number width of window {nr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001658writefile({list}, {fname} [, {binary}])
1659 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001660
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001661add({list}, {expr}) *add()*
1662 Append the item {expr} to List {list}. Returns the resulting
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001663 List. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001664 :let alist = add([1, 2, 3], item)
1665 :call add(mylist, "woodstock")
1666< Note that when {expr} is a List it is appended as a single
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001667 item. Use |extend()| to concatenate Lists.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001668 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001669
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001670
1671append({lnum}, {expr}) *append()*
Bram Moolenaar748bf032005-02-02 23:04:36 +00001672 When {expr} is a List: Append each item of the List as a text
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001673 line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00001674 Otherwise append {expr} as one text line below line {lnum} in
1675 the current buffer.
1676 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001677 Returns 1 for failure ({lnum} out of range or out of memory),
1678 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001679 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001680 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001681<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001682 *argc()*
1683argc() The result is the number of files in the argument list of the
1684 current window. See |arglist|.
1685
1686 *argidx()*
1687argidx() The result is the current index in the argument list. 0 is
1688 the first file. argc() - 1 is the last one. See |arglist|.
1689
1690 *argv()*
1691argv({nr}) The result is the {nr}th file in the argument list of the
1692 current window. See |arglist|. "argv(0)" is the first one.
1693 Example: >
1694 :let i = 0
1695 :while i < argc()
1696 : let f = escape(argv(i), '. ')
1697 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1698 : let i = i + 1
1699 :endwhile
1700<
1701 *browse()*
1702browse({save}, {title}, {initdir}, {default})
1703 Put up a file requester. This only works when "has("browse")"
1704 returns non-zero (only in some GUI versions).
1705 The input fields are:
1706 {save} when non-zero, select file to write
1707 {title} title for the requester
1708 {initdir} directory to start browsing in
1709 {default} default file name
1710 When the "Cancel" button is hit, something went wrong, or
1711 browsing is not possible, an empty string is returned.
1712
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001713 *browsedir()*
1714browsedir({title}, {initdir})
1715 Put up a directory requester. This only works when
1716 "has("browse")" returns non-zero (only in some GUI versions).
1717 On systems where a directory browser is not supported a file
1718 browser is used. In that case: select a file in the directory
1719 to be used.
1720 The input fields are:
1721 {title} title for the requester
1722 {initdir} directory to start browsing in
1723 When the "Cancel" button is hit, something went wrong, or
1724 browsing is not possible, an empty string is returned.
1725
Bram Moolenaar071d4272004-06-13 20:20:40 +00001726bufexists({expr}) *bufexists()*
1727 The result is a Number, which is non-zero if a buffer called
1728 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001729 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001730 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001731 exactly. The name can be:
1732 - Relative to the current directory.
1733 - A full path.
1734 - The name of a buffer with 'filetype' set to "nofile".
1735 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001736 Unlisted buffers will be found.
1737 Note that help files are listed by their short name in the
1738 output of |:buffers|, but bufexists() requires using their
1739 long name to be able to find them.
1740 Use "bufexists(0)" to test for the existence of an alternate
1741 file name.
1742 *buffer_exists()*
1743 Obsolete name: buffer_exists().
1744
1745buflisted({expr}) *buflisted()*
1746 The result is a Number, which is non-zero if a buffer called
1747 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001748 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001749
1750bufloaded({expr}) *bufloaded()*
1751 The result is a Number, which is non-zero if a buffer called
1752 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001753 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001754
1755bufname({expr}) *bufname()*
1756 The result is the name of a buffer, as it is displayed by the
1757 ":ls" command.
1758 If {expr} is a Number, that buffer number's name is given.
1759 Number zero is the alternate buffer for the current window.
1760 If {expr} is a String, it is used as a |file-pattern| to match
1761 with the buffer names. This is always done like 'magic' is
1762 set and 'cpoptions' is empty. When there is more than one
1763 match an empty string is returned.
1764 "" or "%" can be used for the current buffer, "#" for the
1765 alternate buffer.
1766 A full match is preferred, otherwise a match at the start, end
1767 or middle of the buffer name is accepted.
1768 Listed buffers are found first. If there is a single match
1769 with a listed buffer, that one is returned. Next unlisted
1770 buffers are searched for.
1771 If the {expr} is a String, but you want to use it as a buffer
1772 number, force it to be a Number by adding zero to it: >
1773 :echo bufname("3" + 0)
1774< If the buffer doesn't exist, or doesn't have a name, an empty
1775 string is returned. >
1776 bufname("#") alternate buffer name
1777 bufname(3) name of buffer 3
1778 bufname("%") name of current buffer
1779 bufname("file2") name of buffer where "file2" matches.
1780< *buffer_name()*
1781 Obsolete name: buffer_name().
1782
1783 *bufnr()*
1784bufnr({expr}) The result is the number of a buffer, as it is displayed by
1785 the ":ls" command. For the use of {expr}, see |bufname()|
1786 above. If the buffer doesn't exist, -1 is returned.
1787 bufnr("$") is the last buffer: >
1788 :let last_buffer = bufnr("$")
1789< The result is a Number, which is the highest buffer number
1790 of existing buffers. Note that not all buffers with a smaller
1791 number necessarily exist, because ":bwipeout" may have removed
1792 them. Use bufexists() to test for the existence of a buffer.
1793 *buffer_number()*
1794 Obsolete name: buffer_number().
1795 *last_buffer_nr()*
1796 Obsolete name for bufnr("$"): last_buffer_nr().
1797
1798bufwinnr({expr}) *bufwinnr()*
1799 The result is a Number, which is the number of the first
1800 window associated with buffer {expr}. For the use of {expr},
1801 see |bufname()| above. If buffer {expr} doesn't exist or
1802 there is no such window, -1 is returned. Example: >
1803
1804 echo "A window containing buffer 1 is " . (bufwinnr(1))
1805
1806< The number can be used with |CTRL-W_w| and ":wincmd w"
1807 |:wincmd|.
1808
1809
1810byte2line({byte}) *byte2line()*
1811 Return the line number that contains the character at byte
1812 count {byte} in the current buffer. This includes the
1813 end-of-line character, depending on the 'fileformat' option
1814 for the current buffer. The first character has byte count
1815 one.
1816 Also see |line2byte()|, |go| and |:goto|.
1817 {not available when compiled without the |+byte_offset|
1818 feature}
1819
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001820byteidx({expr}, {nr}) *byteidx()*
1821 Return byte index of the {nr}'th character in the string
1822 {expr}. Use zero for the first character, it returns zero.
1823 This function is only useful when there are multibyte
1824 characters, otherwise the returned value is equal to {nr}.
1825 Composing characters are counted as a separate character.
1826 Example : >
1827 echo matchstr(str, ".", byteidx(str, 3))
1828< will display the fourth character. Another way to do the
1829 same: >
1830 let s = strpart(str, byteidx(str, 3))
1831 echo strpart(s, 0, byteidx(s, 1))
1832< If there are less than {nr} characters -1 is returned.
1833 If there are exactly {nr} characters the length of the string
1834 is returned.
1835
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001836call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001837 Call function {func} with the items in List {arglist} as
1838 arguments.
1839 {func} can either be a Funcref or the name of a function.
1840 a:firstline and a:lastline are set to the cursor line.
1841 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001842 {dict} is for functions with the "dict" attribute. It will be
1843 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001844
Bram Moolenaar071d4272004-06-13 20:20:40 +00001845char2nr({expr}) *char2nr()*
1846 Return number value of the first char in {expr}. Examples: >
1847 char2nr(" ") returns 32
1848 char2nr("ABC") returns 65
1849< The current 'encoding' is used. Example for "utf-8": >
1850 char2nr("á") returns 225
1851 char2nr("á"[0]) returns 195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001852< nr2char() does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001853
1854cindent({lnum}) *cindent()*
1855 Get the amount of indent for line {lnum} according the C
1856 indenting rules, as with 'cindent'.
1857 The indent is counted in spaces, the value of 'tabstop' is
1858 relevant. {lnum} is used just like in |getline()|.
1859 When {lnum} is invalid or Vim was not compiled the |+cindent|
1860 feature, -1 is returned.
1861
1862 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001863col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001864 position given with {expr}. The accepted positions are:
1865 . the cursor position
1866 $ the end of the cursor line (the result is the
1867 number of characters in the cursor line plus one)
1868 'x position of mark x (if the mark is not set, 0 is
1869 returned)
1870 For the screen column position use |virtcol()|.
1871 Note that only marks in the current file can be used.
1872 Examples: >
1873 col(".") column of cursor
1874 col("$") length of cursor line plus one
1875 col("'t") column of mark t
1876 col("'" . markname) column of mark markname
1877< The first column is 1. 0 is returned for an error.
1878 For the cursor position, when 'virtualedit' is active, the
1879 column is one higher if the cursor is after the end of the
1880 line. This can be used to obtain the column in Insert mode: >
1881 :imap <F2> <C-O>:let save_ve = &ve<CR>
1882 \<C-O>:set ve=all<CR>
1883 \<C-O>:echo col(".") . "\n" <Bar>
1884 \let &ve = save_ve<CR>
1885<
1886 *confirm()*
1887confirm({msg} [, {choices} [, {default} [, {type}]]])
1888 Confirm() offers the user a dialog, from which a choice can be
1889 made. It returns the number of the choice. For the first
1890 choice this is 1.
1891 Note: confirm() is only supported when compiled with dialog
1892 support, see |+dialog_con| and |+dialog_gui|.
1893 {msg} is displayed in a |dialog| with {choices} as the
1894 alternatives. When {choices} is missing or empty, "&OK" is
1895 used (and translated).
1896 {msg} is a String, use '\n' to include a newline. Only on
1897 some systems the string is wrapped when it doesn't fit.
1898 {choices} is a String, with the individual choices separated
1899 by '\n', e.g. >
1900 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1901< The letter after the '&' is the shortcut key for that choice.
1902 Thus you can type 'c' to select "Cancel". The shortcut does
1903 not need to be the first letter: >
1904 confirm("file has been modified", "&Save\nSave &All")
1905< For the console, the first letter of each choice is used as
1906 the default shortcut key.
1907 The optional {default} argument is the number of the choice
1908 that is made if the user hits <CR>. Use 1 to make the first
1909 choice the default one. Use 0 to not set a default. If
1910 {default} is omitted, 1 is used.
1911 The optional {type} argument gives the type of dialog. This
1912 is only used for the icon of the Win32 GUI. It can be one of
1913 these values: "Error", "Question", "Info", "Warning" or
1914 "Generic". Only the first character is relevant. When {type}
1915 is omitted, "Generic" is used.
1916 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1917 or another valid interrupt key, confirm() returns 0.
1918
1919 An example: >
1920 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1921 :if choice == 0
1922 : echo "make up your mind!"
1923 :elseif choice == 3
1924 : echo "tasteful"
1925 :else
1926 : echo "I prefer bananas myself."
1927 :endif
1928< In a GUI dialog, buttons are used. The layout of the buttons
1929 depends on the 'v' flag in 'guioptions'. If it is included,
1930 the buttons are always put vertically. Otherwise, confirm()
1931 tries to put the buttons in one horizontal line. If they
1932 don't fit, a vertical layout is used anyway. For some systems
1933 the horizontal layout is always used.
1934
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001935 *copy()*
1936copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1937 different from using {expr} directly.
1938 When {expr} is a List a shallow copy is created. This means
1939 that the original List can be changed without changing the
1940 copy, and vise versa. But the items are identical, thus
1941 changing an item changes the contents of both Lists. Also see
1942 |deepcopy()|.
1943
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001944count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001945 Return the number of times an item with value {expr} appears
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001946 in List or Dictionary {comp}.
1947 If {start} is given then start with the item with this index.
1948 {start} can only be used with a List.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001949 When {ic} is given and it's non-zero then case is ignored.
1950
1951
Bram Moolenaar071d4272004-06-13 20:20:40 +00001952 *cscope_connection()*
1953cscope_connection([{num} , {dbpath} [, {prepend}]])
1954 Checks for the existence of a |cscope| connection. If no
1955 parameters are specified, then the function returns:
1956 0, if cscope was not available (not compiled in), or
1957 if there are no cscope connections;
1958 1, if there is at least one cscope connection.
1959
1960 If parameters are specified, then the value of {num}
1961 determines how existence of a cscope connection is checked:
1962
1963 {num} Description of existence check
1964 ----- ------------------------------
1965 0 Same as no parameters (e.g., "cscope_connection()").
1966 1 Ignore {prepend}, and use partial string matches for
1967 {dbpath}.
1968 2 Ignore {prepend}, and use exact string matches for
1969 {dbpath}.
1970 3 Use {prepend}, use partial string matches for both
1971 {dbpath} and {prepend}.
1972 4 Use {prepend}, use exact string matches for both
1973 {dbpath} and {prepend}.
1974
1975 Note: All string comparisons are case sensitive!
1976
1977 Examples. Suppose we had the following (from ":cs show"): >
1978
1979 # pid database name prepend path
1980 0 27664 cscope.out /usr/local
1981<
1982 Invocation Return Val ~
1983 ---------- ---------- >
1984 cscope_connection() 1
1985 cscope_connection(1, "out") 1
1986 cscope_connection(2, "out") 0
1987 cscope_connection(3, "out") 0
1988 cscope_connection(3, "out", "local") 1
1989 cscope_connection(4, "out") 0
1990 cscope_connection(4, "out", "local") 0
1991 cscope_connection(4, "cscope.out", "/usr/local") 1
1992<
1993cursor({lnum}, {col}) *cursor()*
1994 Positions the cursor at the column {col} in the line {lnum}.
1995 Does not change the jumplist.
1996 If {lnum} is greater than the number of lines in the buffer,
1997 the cursor will be positioned at the last line in the buffer.
1998 If {lnum} is zero, the cursor will stay in the current line.
1999 If {col} is greater than the number of characters in the line,
2000 the cursor will be positioned at the last character in the
2001 line.
2002 If {col} is zero, the cursor will stay in the current column.
2003
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002004
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002005deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002006 Make a copy of {expr}. For Numbers and Strings this isn't
2007 different from using {expr} directly.
2008 When {expr} is a List a full copy is created. This means
2009 that the original List can be changed without changing the
2010 copy, and vise versa. When an item is a List, a copy for it
2011 is made, recursively. Thus changing an item in the copy does
2012 not change the contents of the original List.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002013 When {noref} is omitted or zero a contained List or Dictionary
2014 is only copied once. All references point to this single
2015 copy. With {noref} set to 1 every occurrence of a List or
2016 Dictionary results in a new copy. This also means that a
2017 cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002018 *E724*
2019 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002020 that refers back to a higher level making a deep copy with
2021 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002022 Also see |copy()|.
2023
2024delete({fname}) *delete()*
2025 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002026 which is 0 if the file was deleted successfully, and non-zero
2027 when the deletion failed.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002028 Use |remove()| to delete an item from a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002029
2030 *did_filetype()*
2031did_filetype() Returns non-zero when autocommands are being executed and the
2032 FileType event has been triggered at least once. Can be used
2033 to avoid triggering the FileType event again in the scripts
2034 that detect the file type. |FileType|
2035 When editing another file, the counter is reset, thus this
2036 really checks if the FileType event has been triggered for the
2037 current buffer. This allows an autocommand that starts
2038 editing another buffer to set 'filetype' and load a syntax
2039 file.
2040
Bram Moolenaar47136d72004-10-12 20:02:24 +00002041diff_filler({lnum}) *diff_filler()*
2042 Returns the number of filler lines above line {lnum}.
2043 These are the lines that were inserted at this point in
2044 another diff'ed window. These filler lines are shown in the
2045 display but don't exist in the buffer.
2046 {lnum} is used like with |getline()|. Thus "." is the current
2047 line, "'m" mark m, etc.
2048 Returns 0 if the current window is not in diff mode.
2049
2050diff_hlID({lnum}, {col}) *diff_hlID()*
2051 Returns the highlight ID for diff mode at line {lnum} column
2052 {col} (byte index). When the current line does not have a
2053 diff change zero is returned.
2054 {lnum} is used like with |getline()|. Thus "." is the current
2055 line, "'m" mark m, etc.
2056 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2057 line.
2058 The highlight ID can be used with |synIDattr()| to obtain
2059 syntax information about the highlighting.
2060
Bram Moolenaar13065c42005-01-08 16:08:21 +00002061empty({expr}) *empty()*
2062 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002063 A List or Dictionary is empty when it does not have any items.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002064 A Number is empty when its value is zero.
2065 For a long List this is much faster then comparing the length
2066 with zero.
2067
Bram Moolenaar071d4272004-06-13 20:20:40 +00002068escape({string}, {chars}) *escape()*
2069 Escape the characters in {chars} that occur in {string} with a
2070 backslash. Example: >
2071 :echo escape('c:\program files\vim', ' \')
2072< results in: >
2073 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002074
2075< *eval()*
2076eval({string}) Evaluate {string} and return the result. Especially useful to
2077 turn the result of |string()| back into the original value.
2078 This works for Numbers, Strings and composites of them.
2079 Also works for Funcrefs that refer to existing functions.
2080
Bram Moolenaar071d4272004-06-13 20:20:40 +00002081eventhandler() *eventhandler()*
2082 Returns 1 when inside an event handler. That is that Vim got
2083 interrupted while waiting for the user to type a character,
2084 e.g., when dropping a file on Vim. This means interactive
2085 commands cannot be used. Otherwise zero is returned.
2086
2087executable({expr}) *executable()*
2088 This function checks if an executable with the name {expr}
2089 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002090 arguments.
2091 executable() uses the value of $PATH and/or the normal
2092 searchpath for programs. *PATHEXT*
2093 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2094 optionally be included. Then the extensions in $PATHEXT are
2095 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2096 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2097 used. A dot by itself can be used in $PATHEXT to try using
2098 the name without an extension. When 'shell' looks like a
2099 Unix shell, then the name is also tried without adding an
2100 extension.
2101 On MS-DOS and MS-Windows it only checks if the file exists and
2102 is not a directory, not if it's really executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002103 The result is a Number:
2104 1 exists
2105 0 does not exist
2106 -1 not implemented on this system
2107
2108 *exists()*
2109exists({expr}) The result is a Number, which is non-zero if {expr} is
2110 defined, zero otherwise. The {expr} argument is a string,
2111 which contains one of these:
2112 &option-name Vim option (only checks if it exists,
2113 not if it really works)
2114 +option-name Vim option that works.
2115 $ENVNAME environment variable (could also be
2116 done by comparing with an empty
2117 string)
2118 *funcname built-in function (see |functions|)
2119 or user defined function (see
2120 |user-functions|).
2121 varname internal variable (see
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002122 |internal-variables|). Also works
2123 for |curly-braces-names|, Dictionary
2124 entries, List items, etc. Beware that
2125 this may cause functions to be
2126 invoked cause an error message for an
2127 invalid expression.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002128 :cmdname Ex command: built-in command, user
2129 command or command modifier |:command|.
2130 Returns:
2131 1 for match with start of a command
2132 2 full match with a command
2133 3 matches several user commands
2134 To check for a supported command
2135 always check the return value to be 2.
2136 #event autocommand defined for this event
2137 #event#pattern autocommand defined for this event and
2138 pattern (the pattern is taken
2139 literally and compared to the
2140 autocommand patterns character by
2141 character)
2142 For checking for a supported feature use |has()|.
2143
2144 Examples: >
2145 exists("&shortname")
2146 exists("$HOSTNAME")
2147 exists("*strftime")
2148 exists("*s:MyFunc")
2149 exists("bufcount")
2150 exists(":Make")
2151 exists("#CursorHold");
2152 exists("#BufReadPre#*.gz")
2153< There must be no space between the symbol (&/$/*/#) and the
2154 name.
2155 Note that the argument must be a string, not the name of the
2156 variable itself! For example: >
2157 exists(bufcount)
2158< This doesn't check for existence of the "bufcount" variable,
2159 but gets the contents of "bufcount", and checks if that
2160 exists.
2161
2162expand({expr} [, {flag}]) *expand()*
2163 Expand wildcards and the following special keywords in {expr}.
2164 The result is a String.
2165
2166 When there are several matches, they are separated by <NL>
2167 characters. [Note: in version 5.0 a space was used, which
2168 caused problems when a file name contains a space]
2169
2170 If the expansion fails, the result is an empty string. A name
2171 for a non-existing file is not included.
2172
2173 When {expr} starts with '%', '#' or '<', the expansion is done
2174 like for the |cmdline-special| variables with their associated
2175 modifiers. Here is a short overview:
2176
2177 % current file name
2178 # alternate file name
2179 #n alternate file name n
2180 <cfile> file name under the cursor
2181 <afile> autocmd file name
2182 <abuf> autocmd buffer number (as a String!)
2183 <amatch> autocmd matched name
2184 <sfile> sourced script file name
2185 <cword> word under the cursor
2186 <cWORD> WORD under the cursor
2187 <client> the {clientid} of the last received
2188 message |server2client()|
2189 Modifiers:
2190 :p expand to full path
2191 :h head (last path component removed)
2192 :t tail (last path component only)
2193 :r root (one extension removed)
2194 :e extension only
2195
2196 Example: >
2197 :let &tags = expand("%:p:h") . "/tags"
2198< Note that when expanding a string that starts with '%', '#' or
2199 '<', any following text is ignored. This does NOT work: >
2200 :let doesntwork = expand("%:h.bak")
2201< Use this: >
2202 :let doeswork = expand("%:h") . ".bak"
2203< Also note that expanding "<cfile>" and others only returns the
2204 referenced file name without further expansion. If "<cfile>"
2205 is "~/.cshrc", you need to do another expand() to have the
2206 "~/" expanded into the path of the home directory: >
2207 :echo expand(expand("<cfile>"))
2208<
2209 There cannot be white space between the variables and the
2210 following modifier. The |fnamemodify()| function can be used
2211 to modify normal file names.
2212
2213 When using '%' or '#', and the current or alternate file name
2214 is not defined, an empty string is used. Using "%:p" in a
2215 buffer with no name, results in the current directory, with a
2216 '/' added.
2217
2218 When {expr} does not start with '%', '#' or '<', it is
2219 expanded like a file name is expanded on the command line.
2220 'suffixes' and 'wildignore' are used, unless the optional
2221 {flag} argument is given and it is non-zero. Names for
2222 non-existing files are included.
2223
2224 Expand() can also be used to expand variables and environment
2225 variables that are only known in a shell. But this can be
2226 slow, because a shell must be started. See |expr-env-expand|.
2227 The expanded variable is still handled like a list of file
2228 names. When an environment variable cannot be expanded, it is
2229 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2230 "$FOOBAR".
2231
2232 See |glob()| for finding existing files. See |system()| for
2233 getting the raw output of an external command.
2234
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002235extend({expr1}, {expr2} [, {expr3}]) *extend()*
2236 {expr1} and {expr2} must be both Lists or both Dictionaries.
2237
2238 If they are Lists: Append {expr2} to {expr1}.
2239 If {expr3} is given insert the items of {expr2} before item
2240 {expr3} in {expr1}. When {expr3} is zero insert before the
2241 first item. When {expr3} is equal to len({expr1}) then
2242 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002243 Examples: >
2244 :echo sort(extend(mylist, [7, 5]))
2245 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002246< Use |add()| to concatenate one item to a list. To concatenate
2247 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002248 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002249<
2250 If they are Dictionaries:
2251 Add all entries from {expr2} to {expr1}.
2252 If a key exists in both {expr1} and {expr2} then {expr3} is
2253 used to decide what to do:
2254 {expr3} = "keep": keep the value of {expr1}
2255 {expr3} = "force": use the value of {expr2}
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00002256 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002257 When {expr3} is omitted then "force" is assumed.
2258
2259 {expr1} is changed when {expr2} is not empty. If necessary
2260 make a copy of {expr1} first.
2261 {expr2} remains unchanged.
2262 Returns {expr1}.
2263
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002264
Bram Moolenaar071d4272004-06-13 20:20:40 +00002265filereadable({file}) *filereadable()*
2266 The result is a Number, which is TRUE when a file with the
2267 name {file} exists, and can be read. If {file} doesn't exist,
2268 or is a directory, the result is FALSE. {file} is any
2269 expression, which is used as a String.
2270 *file_readable()*
2271 Obsolete name: file_readable().
2272
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002273
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002274filter({expr}, {string}) *filter()*
2275 {expr} must be a List or a Dictionary.
2276 For each item in {expr} evaluate {string} and when the result
2277 is zero remove the item from the List or Dictionary.
2278 Inside {string} |v:val| has the value of the current item.
2279 For a Dictionary |v:key| has the key of the current item.
2280 Examples: >
2281 :call filter(mylist, 'v:val !~ "OLD"')
2282< Removes the items where "OLD" appears. >
2283 :call filter(mydict, 'v:key >= 8')
2284< Removes the items with a key below 8. >
2285 :call filter(var, 0)
Bram Moolenaard8b02732005-01-14 21:48:43 +00002286< Removes all the items, thus clears the List or Dictionary.
2287
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002288 Note that {string} is the result of expression and is then
2289 used as an expression again. Often it is good to use a
2290 |literal-string| to avoid having to double backslashes.
2291
2292 The operation is done in-place. If you want a List or
2293 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00002294 :let l = filter(copy(mylist), '& =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002295
2296< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002297
2298
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002299finddir({name}[, {path}[, {count}]]) *finddir()*
2300 Find directory {name} in {path}.
2301 If {path} is omitted or empty then 'path' is used.
2302 If the optional {count} is given, find {count}'s occurrence of
2303 {name} in {path}.
2304 This is quite similar to the ex-command |:find|.
2305 When the found directory is below the current directory a
2306 relative path is returned. Otherwise a full path is returned.
2307 Example: >
2308 :echo findfile("tags.vim", ".;")
2309< Searches from the current directory upwards until it finds
2310 the file "tags.vim".
2311 {only available when compiled with the +file_in_path feature}
2312
2313findfile({name}[, {path}[, {count}]]) *findfile()*
2314 Just like |finddir()|, but find a file instead of a directory.
2315
Bram Moolenaar071d4272004-06-13 20:20:40 +00002316filewritable({file}) *filewritable()*
2317 The result is a Number, which is 1 when a file with the
2318 name {file} exists, and can be written. If {file} doesn't
2319 exist, or is not writable, the result is 0. If (file) is a
2320 directory, and we can write to it, the result is 2.
2321
2322fnamemodify({fname}, {mods}) *fnamemodify()*
2323 Modify file name {fname} according to {mods}. {mods} is a
2324 string of characters like it is used for file names on the
2325 command line. See |filename-modifiers|.
2326 Example: >
2327 :echo fnamemodify("main.c", ":p:h")
2328< results in: >
2329 /home/mool/vim/vim/src
2330< Note: Environment variables and "~" don't work in {fname}, use
2331 |expand()| first then.
2332
2333foldclosed({lnum}) *foldclosed()*
2334 The result is a Number. If the line {lnum} is in a closed
2335 fold, the result is the number of the first line in that fold.
2336 If the line {lnum} is not in a closed fold, -1 is returned.
2337
2338foldclosedend({lnum}) *foldclosedend()*
2339 The result is a Number. If the line {lnum} is in a closed
2340 fold, the result is the number of the last line in that fold.
2341 If the line {lnum} is not in a closed fold, -1 is returned.
2342
2343foldlevel({lnum}) *foldlevel()*
2344 The result is a Number, which is the foldlevel of line {lnum}
2345 in the current buffer. For nested folds the deepest level is
2346 returned. If there is no fold at line {lnum}, zero is
2347 returned. It doesn't matter if the folds are open or closed.
2348 When used while updating folds (from 'foldexpr') -1 is
2349 returned for lines where folds are still to be updated and the
2350 foldlevel is unknown. As a special case the level of the
2351 previous line is usually available.
2352
2353 *foldtext()*
2354foldtext() Returns a String, to be displayed for a closed fold. This is
2355 the default function used for the 'foldtext' option and should
2356 only be called from evaluating 'foldtext'. It uses the
2357 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2358 The returned string looks like this: >
2359 +-- 45 lines: abcdef
2360< The number of dashes depends on the foldlevel. The "45" is
2361 the number of lines in the fold. "abcdef" is the text in the
2362 first non-blank line of the fold. Leading white space, "//"
2363 or "/*" and the text from the 'foldmarker' and 'commentstring'
2364 options is removed.
2365 {not available when compiled without the |+folding| feature}
2366
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002367foldtextresult({lnum}) *foldtextresult()*
2368 Returns the text that is displayed for the closed fold at line
2369 {lnum}. Evaluates 'foldtext' in the appropriate context.
2370 When there is no closed fold at {lnum} an empty string is
2371 returned.
2372 {lnum} is used like with |getline()|. Thus "." is the current
2373 line, "'m" mark m, etc.
2374 Useful when exporting folded text, e.g., to HTML.
2375 {not available when compiled without the |+folding| feature}
2376
Bram Moolenaar071d4272004-06-13 20:20:40 +00002377 *foreground()*
2378foreground() Move the Vim window to the foreground. Useful when sent from
2379 a client to a Vim server. |remote_send()|
2380 On Win32 systems this might not work, the OS does not always
2381 allow a window to bring itself to the foreground. Use
2382 |remote_foreground()| instead.
2383 {only in the Win32, Athena, Motif and GTK GUI versions and the
2384 Win32 console version}
2385
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002386
Bram Moolenaar13065c42005-01-08 16:08:21 +00002387function({name}) *function()* *E700*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002388 Return a Funcref variable that refers to function {name}.
2389 {name} can be a user defined function or an internal function.
2390
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002391
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002392garbagecollect() *garbagecollect()*
2393 Cleanup unused Lists and Dictionaries that have circular
2394 references. There is hardly ever a need to invoke this
2395 function, as it is automatically done when Vim runs out of
2396 memory or is waiting for the user to press a key after
2397 'updatetime'. Items without circular references are always
2398 freed when they become unused.
2399 This is useful if you have deleted a very big List and/or
2400 Dictionary with circular references in a script that runs for
2401 a long time.
2402
Bram Moolenaar677ee682005-01-27 14:41:15 +00002403get({list}, {idx} [, {default}]) *get()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002404 Get item {idx} from List {list}. When this item is not
2405 available return {default}. Return zero when {default} is
2406 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002407get({dict}, {key} [, {default}])
2408 Get item with key {key} from Dictionary {dict}. When this
2409 item is not available return {default}. Return zero when
2410 {default} is omitted.
2411
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002412
2413getbufvar({expr}, {varname}) *getbufvar()*
2414 The result is the value of option or local buffer variable
2415 {varname} in buffer {expr}. Note that the name without "b:"
2416 must be used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002417 This also works for a global or buffer-local option, but it
2418 doesn't work for a global variable, window-local variable or
2419 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002420 For the use of {expr}, see |bufname()| above.
2421 When the buffer or variable doesn't exist an empty string is
2422 returned, there is no error message.
2423 Examples: >
2424 :let bufmodified = getbufvar(1, "&mod")
2425 :echo "todo myvar = " . getbufvar("todo", "myvar")
2426<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002427getchar([expr]) *getchar()*
2428 Get a single character from the user. If it is an 8-bit
2429 character, the result is a number. Otherwise a String is
2430 returned with the encoded character. For a special key it's a
2431 sequence of bytes starting with 0x80 (decimal: 128).
2432 If [expr] is omitted, wait until a character is available.
2433 If [expr] is 0, only get a character when one is available.
2434 If [expr] is 1, only check if a character is available, it is
2435 not consumed. If a normal character is
2436 available, it is returned, otherwise a
2437 non-zero value is returned.
2438 If a normal character available, it is returned as a Number.
2439 Use nr2char() to convert it to a String.
2440 The returned value is zero if no character is available.
2441 The returned value is a string of characters for special keys
2442 and when a modifier (shift, control, alt) was used.
2443 There is no prompt, you will somehow have to make clear to the
2444 user that a character has to be typed.
2445 There is no mapping for the character.
2446 Key codes are replaced, thus when the user presses the <Del>
2447 key you get the code for the <Del> key, not the raw character
2448 sequence. Examples: >
2449 getchar() == "\<Del>"
2450 getchar() == "\<S-Left>"
2451< This example redefines "f" to ignore case: >
2452 :nmap f :call FindChar()<CR>
2453 :function FindChar()
2454 : let c = nr2char(getchar())
2455 : while col('.') < col('$') - 1
2456 : normal l
2457 : if getline('.')[col('.') - 1] ==? c
2458 : break
2459 : endif
2460 : endwhile
2461 :endfunction
2462
2463getcharmod() *getcharmod()*
2464 The result is a Number which is the state of the modifiers for
2465 the last obtained character with getchar() or in another way.
2466 These values are added together:
2467 2 shift
2468 4 control
2469 8 alt (meta)
2470 16 mouse double click
2471 32 mouse triple click
2472 64 mouse quadruple click
2473 128 Macintosh only: command
2474 Only the modifiers that have not been included in the
2475 character itself are obtained. Thus Shift-a results in "A"
2476 with no modifier.
2477
Bram Moolenaar071d4272004-06-13 20:20:40 +00002478getcmdline() *getcmdline()*
2479 Return the current command-line. Only works when the command
2480 line is being edited, thus requires use of |c_CTRL-\_e| or
2481 |c_CTRL-R_=|.
2482 Example: >
2483 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
2484< Also see |getcmdpos()| and |setcmdpos()|.
2485
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002486getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002487 Return the position of the cursor in the command line as a
2488 byte count. The first column is 1.
2489 Only works when editing the command line, thus requires use of
2490 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
2491 Also see |setcmdpos()| and |getcmdline()|.
2492
2493 *getcwd()*
2494getcwd() The result is a String, which is the name of the current
2495 working directory.
2496
2497getfsize({fname}) *getfsize()*
2498 The result is a Number, which is the size in bytes of the
2499 given file {fname}.
2500 If {fname} is a directory, 0 is returned.
2501 If the file {fname} can't be found, -1 is returned.
2502
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002503getfontname([{name}]) *getfontname()*
2504 Without an argument returns the name of the normal font being
2505 used. Like what is used for the Normal highlight group
2506 |hl-Normal|.
2507 With an argument a check is done whether {name} is a valid
2508 font name. If not then an empty string is returned.
2509 Otherwise the actual font name is returned, or {name} if the
2510 GUI does not support obtaining the real name.
2511 Only works when the GUI is running, thus not you your vimrc or
2512 Note that the GTK 2 GUI accepts any font name, thus checking
2513 for a valid name does not work.
2514 gvimrc file. Use the |GUIEnter| autocommand to use this
2515 function just after the GUI has started.
2516
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002517getfperm({fname}) *getfperm()*
2518 The result is a String, which is the read, write, and execute
2519 permissions of the given file {fname}.
2520 If {fname} does not exist or its directory cannot be read, an
2521 empty string is returned.
2522 The result is of the form "rwxrwxrwx", where each group of
2523 "rwx" flags represent, in turn, the permissions of the owner
2524 of the file, the group the file belongs to, and other users.
2525 If a user does not have a given permission the flag for this
2526 is replaced with the string "-". Example: >
2527 :echo getfperm("/etc/passwd")
2528< This will hopefully (from a security point of view) display
2529 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00002530
Bram Moolenaar071d4272004-06-13 20:20:40 +00002531getftime({fname}) *getftime()*
2532 The result is a Number, which is the last modification time of
2533 the given file {fname}. The value is measured as seconds
2534 since 1st Jan 1970, and may be passed to strftime(). See also
2535 |localtime()| and |strftime()|.
2536 If the file {fname} can't be found -1 is returned.
2537
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002538getftype({fname}) *getftype()*
2539 The result is a String, which is a description of the kind of
2540 file of the given file {fname}.
2541 If {fname} does not exist an empty string is returned.
2542 Here is a table over different kinds of files and their
2543 results:
2544 Normal file "file"
2545 Directory "dir"
2546 Symbolic link "link"
2547 Block device "bdev"
2548 Character device "cdev"
2549 Socket "socket"
2550 FIFO "fifo"
2551 All other "other"
2552 Example: >
2553 getftype("/home")
2554< Note that a type such as "link" will only be returned on
2555 systems that support it. On some systems only "dir" and
2556 "file" are returned.
2557
Bram Moolenaar071d4272004-06-13 20:20:40 +00002558 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002559getline({lnum} [, {end}])
2560 Without {end} the result is a String, which is line {lnum}
2561 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002562 getline(1)
2563< When {lnum} is a String that doesn't start with a
2564 digit, line() is called to translate the String into a Number.
2565 To get the line under the cursor: >
2566 getline(".")
2567< When {lnum} is smaller than 1 or bigger than the number of
2568 lines in the buffer, an empty string is returned.
2569
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002570 When {end} is given the result is a List where each item is a
2571 line from the current buffer in the range {lnum} to {end},
2572 including line {end}.
2573 {end} is used in the same way as {lnum}.
2574 Non-existing lines are silently omitted.
2575 When {end} is before {lnum} an error is given.
2576 Example: >
2577 :let start = line('.')
2578 :let end = search("^$") - 1
2579 :let lines = getline(start, end)
2580
2581
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002582getqflist() *getqflist()*
2583 Returns a list with all the current quickfix errors. Each
2584 list item is a dictionary with these entries:
2585 bufnr number of buffer that has the file name, use
2586 bufname() to get the name
2587 lnum line number in the buffer (first line is 1)
2588 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00002589 vcol non-zero: "col" is visual column
2590 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002591 nr error number
2592 text description of the error
2593 type type of the error, 'E', '1', etc.
2594 valid non-zero: recognized error message
2595
2596 Useful application: Find pattern matches in multiple files and
2597 do something with them: >
2598 :vimgrep /theword/jg *.c
2599 :for d in getqflist()
2600 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
2601 :endfor
2602
2603
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002604getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002605 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002606 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002607 :let cliptext = getreg('*')
2608< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002609 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002610 getreg('=', 1) returns the expression itself, so that it can
2611 be restored with |setreg()|. For other registers the extra
2612 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002613 If {regname} is not specified, |v:register| is used.
2614
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002615
Bram Moolenaar071d4272004-06-13 20:20:40 +00002616getregtype([{regname}]) *getregtype()*
2617 The result is a String, which is type of register {regname}.
2618 The value will be one of:
2619 "v" for |characterwise| text
2620 "V" for |linewise| text
2621 "<CTRL-V>{width}" for |blockwise-visual| text
2622 0 for an empty or unknown register
2623 <CTRL-V> is one character with value 0x16.
2624 If {regname} is not specified, |v:register| is used.
2625
2626 *getwinposx()*
2627getwinposx() The result is a Number, which is the X coordinate in pixels of
2628 the left hand side of the GUI Vim window. The result will be
2629 -1 if the information is not available.
2630
2631 *getwinposy()*
2632getwinposy() The result is a Number, which is the Y coordinate in pixels of
2633 the top of the GUI Vim window. The result will be -1 if the
2634 information is not available.
2635
2636getwinvar({nr}, {varname}) *getwinvar()*
2637 The result is the value of option or local window variable
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002638 {varname} in window {nr}. When {nr} is zero the current
2639 window is used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002640 This also works for a global option, buffer-local option and
2641 window-local option, but it doesn't work for a global variable
2642 or buffer-local variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002643 Note that the name without "w:" must be used.
2644 Examples: >
2645 :let list_is_on = getwinvar(2, '&list')
2646 :echo "myvar = " . getwinvar(1, 'myvar')
2647<
2648 *glob()*
2649glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2650 When there are several matches, they are separated by <NL>
2651 characters.
2652 If the expansion fails, the result is an empty string.
2653 A name for a non-existing file is not included.
2654
2655 For most systems backticks can be used to get files names from
2656 any external command. Example: >
2657 :let tagfiles = glob("`find . -name tags -print`")
2658 :let &tags = substitute(tagfiles, "\n", ",", "g")
2659< The result of the program inside the backticks should be one
2660 item per line. Spaces inside an item are allowed.
2661
2662 See |expand()| for expanding special Vim variables. See
2663 |system()| for getting the raw output of an external command.
2664
2665globpath({path}, {expr}) *globpath()*
2666 Perform glob() on all directories in {path} and concatenate
2667 the results. Example: >
2668 :echo globpath(&rtp, "syntax/c.vim")
2669< {path} is a comma-separated list of directory names. Each
2670 directory name is prepended to {expr} and expanded like with
2671 glob(). A path separator is inserted when needed.
2672 To add a comma inside a directory name escape it with a
2673 backslash. Note that on MS-Windows a directory may have a
2674 trailing backslash, remove it if you put a comma after it.
2675 If the expansion fails for one of the directories, there is no
2676 error message.
2677 The 'wildignore' option applies: Names matching one of the
2678 patterns in 'wildignore' will be skipped.
2679
2680 *has()*
2681has({feature}) The result is a Number, which is 1 if the feature {feature} is
2682 supported, zero otherwise. The {feature} argument is a
2683 string. See |feature-list| below.
2684 Also see |exists()|.
2685
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002686
2687has_key({dict}, {key}) *has_key()*
2688 The result is a Number, which is 1 if Dictionary {dict} has an
2689 entry with key {key}. Zero otherwise.
2690
2691
Bram Moolenaar071d4272004-06-13 20:20:40 +00002692hasmapto({what} [, {mode}]) *hasmapto()*
2693 The result is a Number, which is 1 if there is a mapping that
2694 contains {what} in somewhere in the rhs (what it is mapped to)
2695 and this mapping exists in one of the modes indicated by
2696 {mode}.
2697 Both the global mappings and the mappings local to the current
2698 buffer are checked for a match.
2699 If no matching mapping is found 0 is returned.
2700 The following characters are recognized in {mode}:
2701 n Normal mode
2702 v Visual mode
2703 o Operator-pending mode
2704 i Insert mode
2705 l Language-Argument ("r", "f", "t", etc.)
2706 c Command-line mode
2707 When {mode} is omitted, "nvo" is used.
2708
2709 This function is useful to check if a mapping already exists
2710 to a function in a Vim script. Example: >
2711 :if !hasmapto('\ABCdoit')
2712 : map <Leader>d \ABCdoit
2713 :endif
2714< This installs the mapping to "\ABCdoit" only if there isn't
2715 already a mapping to "\ABCdoit".
2716
2717histadd({history}, {item}) *histadd()*
2718 Add the String {item} to the history {history} which can be
2719 one of: *hist-names*
2720 "cmd" or ":" command line history
2721 "search" or "/" search pattern history
2722 "expr" or "=" typed expression history
2723 "input" or "@" input line history
2724 If {item} does already exist in the history, it will be
2725 shifted to become the newest entry.
2726 The result is a Number: 1 if the operation was successful,
2727 otherwise 0 is returned.
2728
2729 Example: >
2730 :call histadd("input", strftime("%Y %b %d"))
2731 :let date=input("Enter date: ")
2732< This function is not available in the |sandbox|.
2733
2734histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002735 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002736 for the possible values of {history}.
2737
2738 If the parameter {item} is given as String, this is seen
2739 as regular expression. All entries matching that expression
2740 will be removed from the history (if there are any).
2741 Upper/lowercase must match, unless "\c" is used |/\c|.
2742 If {item} is a Number, it will be interpreted as index, see
2743 |:history-indexing|. The respective entry will be removed
2744 if it exists.
2745
2746 The result is a Number: 1 for a successful operation,
2747 otherwise 0 is returned.
2748
2749 Examples:
2750 Clear expression register history: >
2751 :call histdel("expr")
2752<
2753 Remove all entries starting with "*" from the search history: >
2754 :call histdel("/", '^\*')
2755<
2756 The following three are equivalent: >
2757 :call histdel("search", histnr("search"))
2758 :call histdel("search", -1)
2759 :call histdel("search", '^'.histget("search", -1).'$')
2760<
2761 To delete the last search pattern and use the last-but-one for
2762 the "n" command and 'hlsearch': >
2763 :call histdel("search", -1)
2764 :let @/ = histget("search", -1)
2765
2766histget({history} [, {index}]) *histget()*
2767 The result is a String, the entry with Number {index} from
2768 {history}. See |hist-names| for the possible values of
2769 {history}, and |:history-indexing| for {index}. If there is
2770 no such entry, an empty String is returned. When {index} is
2771 omitted, the most recent item from the history is used.
2772
2773 Examples:
2774 Redo the second last search from history. >
2775 :execute '/' . histget("search", -2)
2776
2777< Define an Ex command ":H {num}" that supports re-execution of
2778 the {num}th entry from the output of |:history|. >
2779 :command -nargs=1 H execute histget("cmd", 0+<args>)
2780<
2781histnr({history}) *histnr()*
2782 The result is the Number of the current entry in {history}.
2783 See |hist-names| for the possible values of {history}.
2784 If an error occurred, -1 is returned.
2785
2786 Example: >
2787 :let inp_index = histnr("expr")
2788<
2789hlexists({name}) *hlexists()*
2790 The result is a Number, which is non-zero if a highlight group
2791 called {name} exists. This is when the group has been
2792 defined in some way. Not necessarily when highlighting has
2793 been defined for it, it may also have been used for a syntax
2794 item.
2795 *highlight_exists()*
2796 Obsolete name: highlight_exists().
2797
2798 *hlID()*
2799hlID({name}) The result is a Number, which is the ID of the highlight group
2800 with name {name}. When the highlight group doesn't exist,
2801 zero is returned.
2802 This can be used to retrieve information about the highlight
2803 group. For example, to get the background color of the
2804 "Comment" group: >
2805 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
2806< *highlightID()*
2807 Obsolete name: highlightID().
2808
2809hostname() *hostname()*
2810 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002811 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00002812 256 characters long are truncated.
2813
2814iconv({expr}, {from}, {to}) *iconv()*
2815 The result is a String, which is the text {expr} converted
2816 from encoding {from} to encoding {to}.
2817 When the conversion fails an empty string is returned.
2818 The encoding names are whatever the iconv() library function
2819 can accept, see ":!man 3 iconv".
2820 Most conversions require Vim to be compiled with the |+iconv|
2821 feature. Otherwise only UTF-8 to latin1 conversion and back
2822 can be done.
2823 This can be used to display messages with special characters,
2824 no matter what 'encoding' is set to. Write the message in
2825 UTF-8 and use: >
2826 echo iconv(utf8_str, "utf-8", &enc)
2827< Note that Vim uses UTF-8 for all Unicode encodings, conversion
2828 from/to UCS-2 is automatically changed to use UTF-8. You
2829 cannot use UCS-2 in a string anyway, because of the NUL bytes.
2830 {only available when compiled with the +multi_byte feature}
2831
2832 *indent()*
2833indent({lnum}) The result is a Number, which is indent of line {lnum} in the
2834 current buffer. The indent is counted in spaces, the value
2835 of 'tabstop' is relevant. {lnum} is used just like in
2836 |getline()|.
2837 When {lnum} is invalid -1 is returned.
2838
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002839
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002840index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002841 Return the lowest index in List {list} where the item has a
2842 value equal to {expr}.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002843 If {start} is given then start looking at the item with index
2844 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002845 When {ic} is given and it is non-zero, ignore case. Otherwise
2846 case must match.
2847 -1 is returned when {expr} is not found in {list}.
2848 Example: >
2849 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002850 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002851
2852
Bram Moolenaar071d4272004-06-13 20:20:40 +00002853input({prompt} [, {text}]) *input()*
2854 The result is a String, which is whatever the user typed on
2855 the command-line. The parameter is either a prompt string, or
2856 a blank string (for no prompt). A '\n' can be used in the
2857 prompt to start a new line. The highlighting set with
2858 |:echohl| is used for the prompt. The input is entered just
2859 like a command-line, with the same editing commands and
2860 mappings. There is a separate history for lines typed for
2861 input().
2862 If the optional {text} is present, this is used for the
2863 default reply, as if the user typed this.
2864 NOTE: This must not be used in a startup file, for the
2865 versions that only run in GUI mode (e.g., the Win32 GUI).
2866 Note: When input() is called from within a mapping it will
2867 consume remaining characters from that mapping, because a
2868 mapping is handled like the characters were typed.
2869 Use |inputsave()| before input() and |inputrestore()|
2870 after input() to avoid that. Another solution is to avoid
2871 that further characters follow in the mapping, e.g., by using
2872 |:execute| or |:normal|.
2873
2874 Example: >
2875 :if input("Coffee or beer? ") == "beer"
2876 : echo "Cheers!"
2877 :endif
2878< Example with default text: >
2879 :let color = input("Color? ", "white")
2880< Example with a mapping: >
2881 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
2882 :function GetFoo()
2883 : call inputsave()
2884 : let g:Foo = input("enter search pattern: ")
2885 : call inputrestore()
2886 :endfunction
2887
2888inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
2889 Like input(), but when the GUI is running and text dialogs are
2890 supported, a dialog window pops up to input the text.
2891 Example: >
2892 :let n = inputdialog("value for shiftwidth", &sw)
2893 :if n != ""
2894 : let &sw = n
2895 :endif
2896< When the dialog is cancelled {cancelreturn} is returned. When
2897 omitted an empty string is returned.
2898 Hitting <Enter> works like pressing the OK button. Hitting
2899 <Esc> works like pressing the Cancel button.
2900
2901inputrestore() *inputrestore()*
2902 Restore typeahead that was saved with a previous inputsave().
2903 Should be called the same number of times inputsave() is
2904 called. Calling it more often is harmless though.
2905 Returns 1 when there is nothing to restore, 0 otherwise.
2906
2907inputsave() *inputsave()*
2908 Preserve typeahead (also from mappings) and clear it, so that
2909 a following prompt gets input from the user. Should be
2910 followed by a matching inputrestore() after the prompt. Can
2911 be used several times, in which case there must be just as
2912 many inputrestore() calls.
2913 Returns 1 when out of memory, 0 otherwise.
2914
2915inputsecret({prompt} [, {text}]) *inputsecret()*
2916 This function acts much like the |input()| function with but
2917 two exceptions:
2918 a) the user's response will be displayed as a sequence of
2919 asterisks ("*") thereby keeping the entry secret, and
2920 b) the user's response will not be recorded on the input
2921 |history| stack.
2922 The result is a String, which is whatever the user actually
2923 typed on the command-line in response to the issued prompt.
2924
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002925insert({list}, {item} [, {idx}]) *insert()*
2926 Insert {item} at the start of List {list}.
2927 If {idx} is specified insert {item} before the item with index
2928 {idx}. If {idx} is zero it goes before the first item, just
2929 like omitting {idx}. A negative {idx} is also possible, see
2930 |list-index|. -1 inserts just before the last item.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002931 Returns the resulting List. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002932 :let mylist = insert([2, 3, 5], 1)
2933 :call insert(mylist, 4, -1)
2934 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002935< The last example can be done simpler with |add()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002936 Note that when {item} is a List it is inserted as a single
2937 item. Use |extend()| to concatenate Lists.
2938
Bram Moolenaar071d4272004-06-13 20:20:40 +00002939isdirectory({directory}) *isdirectory()*
2940 The result is a Number, which is non-zero when a directory
2941 with the name {directory} exists. If {directory} doesn't
2942 exist, or isn't a directory, the result is FALSE. {directory}
2943 is any expression, which is used as a String.
2944
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00002945islocked({expr}) *islocked()*
2946 The result is a Number, which is non-zero when {expr} is the
2947 name of a locked variable.
2948 {expr} must be the name of a variable, List item or Dictionary
2949 entry, not the variable itself! Example: >
2950 :let alist = [0, ['a', 'b'], 2, 3]
2951 :lockvar 1 alist
2952 :echo islocked('alist') " 1
2953 :echo islocked('alist[1]') " 0
2954
2955< When {expr} is a variable that does not exist you get an error
2956 message. Use |exists()| to check for existance.
2957
Bram Moolenaar677ee682005-01-27 14:41:15 +00002958items({dict}) *items()*
2959 Return a List with all the key-value pairs of {dict}. Each
2960 List item is a list with two items: the key of a {dict} entry
2961 and the value of this entry. The List is in arbitrary order.
2962
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002963
2964join({list} [, {sep}]) *join()*
2965 Join the items in {list} together into one String.
2966 When {sep} is specified it is put in between the items. If
2967 {sep} is omitted a single space is used.
2968 Note that {sep} is not added at the end. You might want to
2969 add it there too: >
2970 let lines = join(mylist, "\n") . "\n"
2971< String items are used as-is. Lists and Dictionaries are
2972 converted into a string like with |string()|.
2973 The opposite function is |split()|.
2974
Bram Moolenaard8b02732005-01-14 21:48:43 +00002975keys({dict}) *keys()*
2976 Return a List with all the keys of {dict}. The List is in
2977 arbitrary order.
2978
Bram Moolenaar13065c42005-01-08 16:08:21 +00002979 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002980len({expr}) The result is a Number, which is the length of the argument.
2981 When {expr} is a String or a Number the length in bytes is
2982 used, as with |strlen()|.
2983 When {expr} is a List the number of items in the List is
2984 returned.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002985 When {expr} is a Dictionary the number of entries in the
2986 Dictionary is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002987 Otherwise an error is given.
2988
Bram Moolenaar071d4272004-06-13 20:20:40 +00002989 *libcall()* *E364* *E368*
2990libcall({libname}, {funcname}, {argument})
2991 Call function {funcname} in the run-time library {libname}
2992 with single argument {argument}.
2993 This is useful to call functions in a library that you
2994 especially made to be used with Vim. Since only one argument
2995 is possible, calling standard library functions is rather
2996 limited.
2997 The result is the String returned by the function. If the
2998 function returns NULL, this will appear as an empty string ""
2999 to Vim.
3000 If the function returns a number, use libcallnr()!
3001 If {argument} is a number, it is passed to the function as an
3002 int; if {argument} is a string, it is passed as a
3003 null-terminated string.
3004 This function will fail in |restricted-mode|.
3005
3006 libcall() allows you to write your own 'plug-in' extensions to
3007 Vim without having to recompile the program. It is NOT a
3008 means to call system functions! If you try to do so Vim will
3009 very probably crash.
3010
3011 For Win32, the functions you write must be placed in a DLL
3012 and use the normal C calling convention (NOT Pascal which is
3013 used in Windows System DLLs). The function must take exactly
3014 one parameter, either a character pointer or a long integer,
3015 and must return a character pointer or NULL. The character
3016 pointer returned must point to memory that will remain valid
3017 after the function has returned (e.g. in static data in the
3018 DLL). If it points to allocated memory, that memory will
3019 leak away. Using a static buffer in the function should work,
3020 it's then freed when the DLL is unloaded.
3021
3022 WARNING: If the function returns a non-valid pointer, Vim may
3023 crash! This also happens if the function returns a number,
3024 because Vim thinks it's a pointer.
3025 For Win32 systems, {libname} should be the filename of the DLL
3026 without the ".DLL" suffix. A full path is only required if
3027 the DLL is not in the usual places.
3028 For Unix: When compiling your own plugins, remember that the
3029 object code must be compiled as position-independent ('PIC').
3030 {only in Win32 on some Unix versions, when the |+libcall|
3031 feature is present}
3032 Examples: >
3033 :echo libcall("libc.so", "getenv", "HOME")
3034 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3035<
3036 *libcallnr()*
3037libcallnr({libname}, {funcname}, {argument})
3038 Just like libcall(), but used for a function that returns an
3039 int instead of a string.
3040 {only in Win32 on some Unix versions, when the |+libcall|
3041 feature is present}
3042 Example (not very useful...): >
3043 :call libcallnr("libc.so", "printf", "Hello World!\n")
3044 :call libcallnr("libc.so", "sleep", 10)
3045<
3046 *line()*
3047line({expr}) The result is a Number, which is the line number of the file
3048 position given with {expr}. The accepted positions are:
3049 . the cursor position
3050 $ the last line in the current buffer
3051 'x position of mark x (if the mark is not set, 0 is
3052 returned)
3053 Note that only marks in the current file can be used.
3054 Examples: >
3055 line(".") line number of the cursor
3056 line("'t") line number of mark t
3057 line("'" . marker) line number of mark marker
3058< *last-position-jump*
3059 This autocommand jumps to the last known position in a file
3060 just after opening it, if the '" mark is set: >
3061 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003062
Bram Moolenaar071d4272004-06-13 20:20:40 +00003063line2byte({lnum}) *line2byte()*
3064 Return the byte count from the start of the buffer for line
3065 {lnum}. This includes the end-of-line character, depending on
3066 the 'fileformat' option for the current buffer. The first
3067 line returns 1.
3068 This can also be used to get the byte count for the line just
3069 below the last line: >
3070 line2byte(line("$") + 1)
3071< This is the file size plus one.
3072 When {lnum} is invalid, or the |+byte_offset| feature has been
3073 disabled at compile time, -1 is returned.
3074 Also see |byte2line()|, |go| and |:goto|.
3075
3076lispindent({lnum}) *lispindent()*
3077 Get the amount of indent for line {lnum} according the lisp
3078 indenting rules, as with 'lisp'.
3079 The indent is counted in spaces, the value of 'tabstop' is
3080 relevant. {lnum} is used just like in |getline()|.
3081 When {lnum} is invalid or Vim was not compiled the
3082 |+lispindent| feature, -1 is returned.
3083
3084localtime() *localtime()*
3085 Return the current time, measured as seconds since 1st Jan
3086 1970. See also |strftime()| and |getftime()|.
3087
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003088
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003089map({expr}, {string}) *map()*
3090 {expr} must be a List or a Dictionary.
3091 Replace each item in {expr} with the result of evaluating
3092 {string}.
3093 Inside {string} |v:val| has the value of the current item.
3094 For a Dictionary |v:key| has the key of the current item.
3095 Example: >
3096 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003097< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003098
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003099 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003100 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003101 |literal-string| to avoid having to double backslashes. You
3102 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003103
3104 The operation is done in-place. If you want a List or
3105 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003106 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003107
3108< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003109
3110
Bram Moolenaar071d4272004-06-13 20:20:40 +00003111maparg({name}[, {mode}]) *maparg()*
3112 Return the rhs of mapping {name} in mode {mode}. When there
3113 is no mapping for {name}, an empty String is returned.
3114 These characters can be used for {mode}:
3115 "n" Normal
3116 "v" Visual
3117 "o" Operator-pending
3118 "i" Insert
3119 "c" Cmd-line
3120 "l" langmap |language-mapping|
3121 "" Normal, Visual and Operator-pending
3122 When {mode} is omitted, the modes from "" are used.
3123 The {name} can have special key names, like in the ":map"
3124 command. The returned String has special characters
3125 translated like in the output of the ":map" command listing.
3126 The mappings local to the current buffer are checked first,
3127 then the global mappings.
3128
3129mapcheck({name}[, {mode}]) *mapcheck()*
3130 Check if there is a mapping that matches with {name} in mode
3131 {mode}. See |maparg()| for {mode} and special names in
3132 {name}.
3133 A match happens with a mapping that starts with {name} and
3134 with a mapping which is equal to the start of {name}.
3135
3136 matches mapping "a" "ab" "abc" ~
3137 mapcheck("a") yes yes yes
3138 mapcheck("abc") yes yes yes
3139 mapcheck("ax") yes no no
3140 mapcheck("b") no no no
3141
3142 The difference with maparg() is that mapcheck() finds a
3143 mapping that matches with {name}, while maparg() only finds a
3144 mapping for {name} exactly.
3145 When there is no mapping that starts with {name}, an empty
3146 String is returned. If there is one, the rhs of that mapping
3147 is returned. If there are several mappings that start with
3148 {name}, the rhs of one of them is returned.
3149 The mappings local to the current buffer are checked first,
3150 then the global mappings.
3151 This function can be used to check if a mapping can be added
3152 without being ambiguous. Example: >
3153 :if mapcheck("_vv") == ""
3154 : map _vv :set guifont=7x13<CR>
3155 :endif
3156< This avoids adding the "_vv" mapping when there already is a
3157 mapping for "_v" or for "_vvv".
3158
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003159match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003160 When {expr} is a List then this returns the index of the first
3161 item where {pat} matches. Each item is used as a String,
3162 Lists and Dictionaries are used as echoed.
3163 Otherwise, {expr} is used as a String. The result is a
3164 Number, which gives the index (byte offset) in {expr} where
3165 {pat} matches.
3166 A match at the first character or List item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003167 If there is no match -1 is returned.
3168 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003169 :echo match("testing", "ing") " results in 4
3170 :echo match([1, 'x'], '\a') " results in 2
3171< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00003172 *strpbrk()*
3173 Vim doesn't have a strpbrk() function. But you can do: >
3174 :let sepidx = match(line, '[.,;: \t]')
3175< *strcasestr()*
3176 Vim doesn't have a strcasestr() function. But you can add
3177 "\c" to the pattern to ignore case: >
3178 :let idx = match(haystack, '\cneedle')
3179<
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003180 When {count} is given use the {count}'th match. When a match
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003181 is found in a String the search for the next one starts on
3182 character further. Thus this example results in 1: >
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003183 echo match("testing", "..", 0, 2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003184< In a List the search continues in the next item.
3185
3186 If {start} is given, the search starts from byte index
3187 {start} in a String or item {start} in a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003188 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003189 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003190 :echo match("testing", "ing", 2)
3191< result is again "4". >
3192 :echo match("testing", "ing", 4)
3193< result is again "4". >
3194 :echo match("testing", "t", 2)
3195< result is "3".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003196 For a String, if {start} < 0, it will be set to 0. For a list
3197 the index is counted from the end.
3198 If {start} is out of range (> strlen({expr} for a String or
3199 > len({expr} for a List) -1 is returned.
3200
Bram Moolenaar071d4272004-06-13 20:20:40 +00003201 See |pattern| for the patterns that are accepted.
3202 The 'ignorecase' option is used to set the ignore-caseness of
3203 the pattern. 'smartcase' is NOT used. The matching is always
3204 done like 'magic' is set and 'cpoptions' is empty.
3205
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003206matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003207 Same as match(), but return the index of first character after
3208 the match. Example: >
3209 :echo matchend("testing", "ing")
3210< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00003211 *strspn()* *strcspn()*
3212 Vim doesn't have a strspn() or strcspn() function, but you can
3213 do it with matchend(): >
3214 :let span = matchend(line, '[a-zA-Z]')
3215 :let span = matchend(line, '[^a-zA-Z]')
3216< Except that -1 is returned when there are no matches.
3217
Bram Moolenaar071d4272004-06-13 20:20:40 +00003218 The {start}, if given, has the same meaning as for match(). >
3219 :echo matchend("testing", "ing", 2)
3220< results in "7". >
3221 :echo matchend("testing", "ing", 5)
3222< result is "-1".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003223 When {expr} is a List the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003224
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003225matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
3226 Same as match(), but return a List. The first item in the
3227 list is the matched string, same as what matchstr() would
3228 return. Following items are submatches, like "\1", "\2", etc.
3229 in |:substitute|.
3230 When there is no match an empty list is returned.
3231
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003232matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003233 Same as match(), but return the matched string. Example: >
3234 :echo matchstr("testing", "ing")
3235< results in "ing".
3236 When there is no match "" is returned.
3237 The {start}, if given, has the same meaning as for match(). >
3238 :echo matchstr("testing", "ing", 2)
3239< results in "ing". >
3240 :echo matchstr("testing", "ing", 5)
3241< result is "".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003242 When {expr} is a List then the matching item is returned.
3243 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003245 *max()*
3246max({list}) Return the maximum value of all items in {list}.
3247 If {list} is not a list or one of the items in {list} cannot
3248 be used as a Number this results in an error.
3249 An empty List results in zero.
3250
3251 *min()*
3252min({list}) Return the minumum value of all items in {list}.
3253 If {list} is not a list or one of the items in {list} cannot
3254 be used as a Number this results in an error.
3255 An empty List results in zero.
3256
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003257 *mkdir()* *E749*
3258mkdir({name} [, {path} [, {prot}]])
3259 Create directory {name}.
3260 If {path} is "p" then intermediate directories are created as
3261 necessary. Otherwise it must be "".
3262 If {prot} is given it is used to set the protection bits of
3263 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3264 the user readable for others). Use 0700 to make it unreadable
3265 for others.
3266 This function is not available in the |sandbox|.
3267 Not available on all systems. To check use: >
3268 :if exists("*mkdir")
3269<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003270 *mode()*
3271mode() Return a string that indicates the current mode:
3272 n Normal
3273 v Visual by character
3274 V Visual by line
3275 CTRL-V Visual blockwise
3276 s Select by character
3277 S Select by line
3278 CTRL-S Select blockwise
3279 i Insert
3280 R Replace
3281 c Command-line
3282 r Hit-enter prompt
3283 This is useful in the 'statusline' option. In most other
3284 places it always returns "c" or "n".
3285
3286nextnonblank({lnum}) *nextnonblank()*
3287 Return the line number of the first line at or below {lnum}
3288 that is not blank. Example: >
3289 if getline(nextnonblank(1)) =~ "Java"
3290< When {lnum} is invalid or there is no non-blank line at or
3291 below it, zero is returned.
3292 See also |prevnonblank()|.
3293
3294nr2char({expr}) *nr2char()*
3295 Return a string with a single character, which has the number
3296 value {expr}. Examples: >
3297 nr2char(64) returns "@"
3298 nr2char(32) returns " "
3299< The current 'encoding' is used. Example for "utf-8": >
3300 nr2char(300) returns I with bow character
3301< Note that a NUL character in the file is specified with
3302 nr2char(10), because NULs are represented with newline
3303 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003304 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003305
3306prevnonblank({lnum}) *prevnonblank()*
3307 Return the line number of the first line at or above {lnum}
3308 that is not blank. Example: >
3309 let ind = indent(prevnonblank(v:lnum - 1))
3310< When {lnum} is invalid or there is no non-blank line at or
3311 above it, zero is returned.
3312 Also see |nextnonblank()|.
3313
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003314 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003315range({expr} [, {max} [, {stride}]]) *range()*
3316 Returns a List with Numbers:
3317 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3318 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3319 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3320 {max}] (increasing {expr} with {stride} each time, not
3321 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00003322 When the maximum is one before the start the result is an
3323 empty list. When the maximum is more than one before the
3324 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003325 Examples: >
3326 range(4) " [0, 1, 2, 3]
3327 range(2, 4) " [2, 3, 4]
3328 range(2, 9, 3) " [2, 5, 8]
3329 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00003330 range(0) " []
3331 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00003332<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003333 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003334readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003335 Read file {fname} and return a List, each line of the file as
3336 an item. Lines broken at NL characters. Macintosh files
3337 separated with CR will result in a single long line (unless a
3338 NL appears somewhere).
3339 When {binary} is equal to "b" binary mode is used:
3340 - When the last line ends in a NL an extra empty list item is
3341 added.
3342 - No CR characters are removed.
3343 Otherwise:
3344 - CR characters that appear before a NL are removed.
3345 - Whether the last line ends in a NL or not does not matter.
3346 All NUL characters are replaced with a NL character.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003347 When {max} is given this specifies the maximum number of lines
3348 to be read. Useful if you only want to check the first ten
3349 lines of a file: >
3350 :for line in readfile(fname, '', 10)
3351 : if line =~ 'Date' | echo line | endif
3352 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00003353< When {max} is negative -{max} lines from the end of the file
3354 are returned, or as many as there are.
3355 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003356 Note that without {max} the whole file is read into memory.
3357 Also note that there is no recognition of encoding. Read a
3358 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003359 When the file can't be opened an error message is given and
3360 the result is an empty list.
3361 Also see |writefile()|.
3362
Bram Moolenaar071d4272004-06-13 20:20:40 +00003363 *remote_expr()* *E449*
3364remote_expr({server}, {string} [, {idvar}])
3365 Send the {string} to {server}. The string is sent as an
3366 expression and the result is returned after evaluation.
3367 If {idvar} is present, it is taken as the name of a
3368 variable and a {serverid} for later use with
3369 remote_read() is stored there.
3370 See also |clientserver| |RemoteReply|.
3371 This function is not available in the |sandbox|.
3372 {only available when compiled with the |+clientserver| feature}
3373 Note: Any errors will cause a local error message to be issued
3374 and the result will be the empty string.
3375 Examples: >
3376 :echo remote_expr("gvim", "2+2")
3377 :echo remote_expr("gvim1", "b:current_syntax")
3378<
3379
3380remote_foreground({server}) *remote_foreground()*
3381 Move the Vim server with the name {server} to the foreground.
3382 This works like: >
3383 remote_expr({server}, "foreground()")
3384< Except that on Win32 systems the client does the work, to work
3385 around the problem that the OS doesn't always allow the server
3386 to bring itself to the foreground.
3387 This function is not available in the |sandbox|.
3388 {only in the Win32, Athena, Motif and GTK GUI versions and the
3389 Win32 console version}
3390
3391
3392remote_peek({serverid} [, {retvar}]) *remote_peek()*
3393 Returns a positive number if there are available strings
3394 from {serverid}. Copies any reply string into the variable
3395 {retvar} if specified. {retvar} must be a string with the
3396 name of a variable.
3397 Returns zero if none are available.
3398 Returns -1 if something is wrong.
3399 See also |clientserver|.
3400 This function is not available in the |sandbox|.
3401 {only available when compiled with the |+clientserver| feature}
3402 Examples: >
3403 :let repl = ""
3404 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3405
3406remote_read({serverid}) *remote_read()*
3407 Return the oldest available reply from {serverid} and consume
3408 it. It blocks until a reply is available.
3409 See also |clientserver|.
3410 This function is not available in the |sandbox|.
3411 {only available when compiled with the |+clientserver| feature}
3412 Example: >
3413 :echo remote_read(id)
3414<
3415 *remote_send()* *E241*
3416remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003417 Send the {string} to {server}. The string is sent as input
3418 keys and the function returns immediately. At the Vim server
3419 the keys are not mapped |:map|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003420 If {idvar} is present, it is taken as the name of a
3421 variable and a {serverid} for later use with
3422 remote_read() is stored there.
3423 See also |clientserver| |RemoteReply|.
3424 This function is not available in the |sandbox|.
3425 {only available when compiled with the |+clientserver| feature}
3426 Note: Any errors will be reported in the server and may mess
3427 up the display.
3428 Examples: >
3429 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3430 \ remote_read(serverid)
3431
3432 :autocmd NONE RemoteReply *
3433 \ echo remote_read(expand("<amatch>"))
3434 :echo remote_send("gvim", ":sleep 10 | echo ".
3435 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003436<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003437remove({list}, {idx} [, {end}]) *remove()*
3438 Without {end}: Remove the item at {idx} from List {list} and
3439 return it.
3440 With {end}: Remove items from {idx} to {end} (inclusive) and
3441 return a list with these items. When {idx} points to the same
3442 item as {end} a list with one item is returned. When {end}
3443 points to an item before {idx} this is an error.
3444 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003445 Example: >
3446 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003447 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00003448remove({dict}, {key})
3449 Remove the entry from {dict} with key {key}. Example: >
3450 :echo "removed " . remove(dict, "one")
3451< If there is no {key} in {dict} this is an error.
3452
3453 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003454
Bram Moolenaar071d4272004-06-13 20:20:40 +00003455rename({from}, {to}) *rename()*
3456 Rename the file by the name {from} to the name {to}. This
3457 should also work to move files across file systems. The
3458 result is a Number, which is 0 if the file was renamed
3459 successfully, and non-zero when the renaming failed.
3460 This function is not available in the |sandbox|.
3461
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003462repeat({expr}, {count}) *repeat()*
3463 Repeat {expr} {count} times and return the concatenated
3464 result. Example: >
3465 :let seperator = repeat('-', 80)
3466< When {count} is zero or negative the result is empty.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003467 When {expr} is a List the result is {expr} concatenated
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003468 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003469 :let longlist = repeat(['a', 'b'], 3)
3470< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003471
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003472
Bram Moolenaar071d4272004-06-13 20:20:40 +00003473resolve({filename}) *resolve()* *E655*
3474 On MS-Windows, when {filename} is a shortcut (a .lnk file),
3475 returns the path the shortcut points to in a simplified form.
3476 On Unix, repeat resolving symbolic links in all path
3477 components of {filename} and return the simplified result.
3478 To cope with link cycles, resolving of symbolic links is
3479 stopped after 100 iterations.
3480 On other systems, return the simplified {filename}.
3481 The simplification step is done as by |simplify()|.
3482 resolve() keeps a leading path component specifying the
3483 current directory (provided the result is still a relative
3484 path name) and also keeps a trailing path separator.
3485
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003486 *reverse()*
3487reverse({list}) Reverse the order of items in {list} in-place. Returns
3488 {list}.
3489 If you want a list to remain unmodified make a copy first: >
3490 :let revlist = reverse(copy(mylist))
3491
Bram Moolenaar071d4272004-06-13 20:20:40 +00003492search({pattern} [, {flags}]) *search()*
3493 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003494 cursor position (you can use |cursor()| to set it).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003495 {flags} is a String, which can contain these character flags:
3496 'b' search backward instead of forward
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003497 'n' do Not move the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003498 'w' wrap around the end of the file
3499 'W' don't wrap around the end of the file
3500 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
3501
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003502 When a match has been found its line number is returned.
3503 The cursor will be positioned at the match, unless the 'n'
3504 flag is used).
3505 If there is no match a 0 is returned and the cursor doesn't
3506 move. No error message is given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003507
3508 Example (goes over all files in the argument list): >
3509 :let n = 1
3510 :while n <= argc() " loop over all files in arglist
3511 : exe "argument " . n
3512 : " start at the last char in the file and wrap for the
3513 : " first search to find match at start of file
3514 : normal G$
3515 : let flags = "w"
3516 : while search("foo", flags) > 0
3517 : s/foo/bar/g
3518 : let flags = "W"
3519 : endwhile
3520 : update " write the file if modified
3521 : let n = n + 1
3522 :endwhile
3523<
3524 *searchpair()*
3525searchpair({start}, {middle}, {end} [, {flags} [, {skip}]])
3526 Search for the match of a nested start-end pair. This can be
3527 used to find the "endif" that matches an "if", while other
3528 if/endif pairs in between are ignored.
3529 The search starts at the cursor. If a match is found, the
3530 cursor is positioned at it and the line number is returned.
3531 If no match is found 0 or -1 is returned and the cursor
3532 doesn't move. No error message is given.
3533
3534 {start}, {middle} and {end} are patterns, see |pattern|. They
3535 must not contain \( \) pairs. Use of \%( \) is allowed. When
3536 {middle} is not empty, it is found when searching from either
3537 direction, but only when not in a nested start-end pair. A
3538 typical use is: >
3539 searchpair('\<if\>', '\<else\>', '\<endif\>')
3540< By leaving {middle} empty the "else" is skipped.
3541
3542 {flags} are used like with |search()|. Additionally:
3543 'n' do Not move the cursor
3544 'r' Repeat until no more matches found; will find the
3545 outer pair
3546 'm' return number of Matches instead of line number with
3547 the match; will only be > 1 when 'r' is used.
3548
3549 When a match for {start}, {middle} or {end} is found, the
3550 {skip} expression is evaluated with the cursor positioned on
3551 the start of the match. It should return non-zero if this
3552 match is to be skipped. E.g., because it is inside a comment
3553 or a string.
3554 When {skip} is omitted or empty, every match is accepted.
3555 When evaluating {skip} causes an error the search is aborted
3556 and -1 returned.
3557
3558 The value of 'ignorecase' is used. 'magic' is ignored, the
3559 patterns are used like it's on.
3560
3561 The search starts exactly at the cursor. A match with
3562 {start}, {middle} or {end} at the next character, in the
3563 direction of searching, is the first one found. Example: >
3564 if 1
3565 if 2
3566 endif 2
3567 endif 1
3568< When starting at the "if 2", with the cursor on the "i", and
3569 searching forwards, the "endif 2" is found. When starting on
3570 the character just before the "if 2", the "endif 1" will be
3571 found. That's because the "if 2" will be found first, and
3572 then this is considered to be a nested if/endif from "if 2" to
3573 "endif 2".
3574 When searching backwards and {end} is more than one character,
3575 it may be useful to put "\zs" at the end of the pattern, so
3576 that when the cursor is inside a match with the end it finds
3577 the matching start.
3578
3579 Example, to find the "endif" command in a Vim script: >
3580
3581 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
3582 \ 'getline(".") =~ "^\\s*\""')
3583
3584< The cursor must be at or after the "if" for which a match is
3585 to be found. Note that single-quote strings are used to avoid
3586 having to double the backslashes. The skip expression only
3587 catches comments at the start of a line, not after a command.
3588 Also, a word "en" or "if" halfway a line is considered a
3589 match.
3590 Another example, to search for the matching "{" of a "}": >
3591
3592 :echo searchpair('{', '', '}', 'bW')
3593
3594< This works when the cursor is at or before the "}" for which a
3595 match is to be found. To reject matches that syntax
3596 highlighting recognized as strings: >
3597
3598 :echo searchpair('{', '', '}', 'bW',
3599 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
3600<
3601server2client( {clientid}, {string}) *server2client()*
3602 Send a reply string to {clientid}. The most recent {clientid}
3603 that sent a string can be retrieved with expand("<client>").
3604 {only available when compiled with the |+clientserver| feature}
3605 Note:
3606 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003607 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003608 before calling any commands that waits for input.
3609 See also |clientserver|.
3610 Example: >
3611 :echo server2client(expand("<client>"), "HELLO")
3612<
3613serverlist() *serverlist()*
3614 Return a list of available server names, one per line.
3615 When there are no servers or the information is not available
3616 an empty string is returned. See also |clientserver|.
3617 {only available when compiled with the |+clientserver| feature}
3618 Example: >
3619 :echo serverlist()
3620<
3621setbufvar({expr}, {varname}, {val}) *setbufvar()*
3622 Set option or local variable {varname} in buffer {expr} to
3623 {val}.
3624 This also works for a global or local window option, but it
3625 doesn't work for a global or local window variable.
3626 For a local window option the global value is unchanged.
3627 For the use of {expr}, see |bufname()| above.
3628 Note that the variable name without "b:" must be used.
3629 Examples: >
3630 :call setbufvar(1, "&mod", 1)
3631 :call setbufvar("todo", "myvar", "foobar")
3632< This function is not available in the |sandbox|.
3633
3634setcmdpos({pos}) *setcmdpos()*
3635 Set the cursor position in the command line to byte position
3636 {pos}. The first position is 1.
3637 Use |getcmdpos()| to obtain the current position.
3638 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00003639 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
3640 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
3641 set after the command line is set to the expression. For
3642 |c_CTRL-R_=| it is set after evaluating the expression but
3643 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003644 When the number is too big the cursor is put at the end of the
3645 line. A number smaller than one has undefined results.
3646 Returns 0 when successful, 1 when not editing the command
3647 line.
3648
3649setline({lnum}, {line}) *setline()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003650 Set line {lnum} of the current buffer to {line}.
3651 {lnum} is used like with |getline()|.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003652 When {lnum} is just below the last line the {line} will be
3653 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003654 If this succeeds, 0 is returned. If this fails (most likely
3655 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003656 :call setline(5, strftime("%c"))
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003657< When {line} is a List then line {lnum} and following lines
3658 will be set to the items in the list. Example: >
3659 :call setline(5, ['aaa', 'bbb', 'ccc'])
3660< This is equivalent to: >
3661 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
3662 : call setline(n, l)
3663 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003664< Note: The '[ and '] marks are not set.
3665
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003666
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003667setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003668 Creates a quickfix list using the items in {list}. Each item
3669 in {list} is a dictionary. Non-dictionary items in {list} are
3670 ignored. Each dictionary item can contain the following
3671 entries:
3672
3673 filename name of a file
3674 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003675 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003676 col column number
3677 vcol when non-zero: "col" is visual column
3678 when zero: "col" is byte index
3679 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003680 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003681 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003682
Bram Moolenaar582fd852005-03-28 20:58:01 +00003683 The "col", "vcol", "nr", "type" and "text" entries are
3684 optional. Either "lnum" or "pattern" entry can be used to
3685 locate a matching error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003686 If the "filename" entry is not present or neither the "lnum"
3687 or "pattern" entries are present, then the item will not be
3688 handled as an error line.
3689 If both "pattern" and "lnum" are present then "pattern" will
3690 be used.
3691
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003692 If {action} is set to 'a', then the items from {list} are
3693 added to the existing quickfix list. If there is no existing
3694 list, then a new list is created. If {action} is set to 'r',
3695 then the items from the current quickfix list are replaced
3696 with the items from {list}. If {action} is not present or is
3697 set to ' ', then a new list is created.
3698
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003699 Returns zero for success, -1 for failure.
3700
3701 This function can be used to create a quickfix list
3702 independent of the 'errorformat' setting. Use a command like
3703 ":cc 1" to jump to the first position.
3704
3705
Bram Moolenaar071d4272004-06-13 20:20:40 +00003706 *setreg()*
3707setreg({regname}, {value} [,{options}])
3708 Set the register {regname} to {value}.
3709 If {options} contains "a" or {regname} is upper case,
3710 then the value is appended.
3711 {options} can also contains a register type specification:
3712 "c" or "v" |characterwise| mode
3713 "l" or "V" |linewise| mode
3714 "b" or "<CTRL-V>" |blockwise-visual| mode
3715 If a number immediately follows "b" or "<CTRL-V>" then this is
3716 used as the width of the selection - if it is not specified
3717 then the width of the block is set to the number of characters
3718 in the longest line (counting a <TAB> as 1 character).
3719
3720 If {options} contains no register settings, then the default
3721 is to use character mode unless {value} ends in a <NL>.
3722 Setting the '=' register is not possible.
3723 Returns zero for success, non-zero for failure.
3724
3725 Examples: >
3726 :call setreg(v:register, @*)
3727 :call setreg('*', @%, 'ac')
3728 :call setreg('a', "1\n2\n3", 'b5')
3729
3730< This example shows using the functions to save and restore a
3731 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003732 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003733 :let var_amode = getregtype('a')
3734 ....
3735 :call setreg('a', var_a, var_amode)
3736
3737< You can also change the type of a register by appending
3738 nothing: >
3739 :call setreg('a', '', 'al')
3740
3741setwinvar({nr}, {varname}, {val}) *setwinvar()*
3742 Set option or local variable {varname} in window {nr} to
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00003743 {val}. When {nr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003744 This also works for a global or local buffer option, but it
3745 doesn't work for a global or local buffer variable.
3746 For a local buffer option the global value is unchanged.
3747 Note that the variable name without "w:" must be used.
3748 Examples: >
3749 :call setwinvar(1, "&list", 0)
3750 :call setwinvar(2, "myvar", "foobar")
3751< This function is not available in the |sandbox|.
3752
3753simplify({filename}) *simplify()*
3754 Simplify the file name as much as possible without changing
3755 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
3756 Unix) are not resolved. If the first path component in
3757 {filename} designates the current directory, this will be
3758 valid for the result as well. A trailing path separator is
3759 not removed either.
3760 Example: >
3761 simplify("./dir/.././/file/") == "./file/"
3762< Note: The combination "dir/.." is only removed if "dir" is
3763 a searchable directory or does not exist. On Unix, it is also
3764 removed when "dir" is a symbolic link within the same
3765 directory. In order to resolve all the involved symbolic
3766 links before simplifying the path name, use |resolve()|.
3767
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003768
Bram Moolenaar13065c42005-01-08 16:08:21 +00003769sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003770 Sort the items in {list} in-place. Returns {list}. If you
3771 want a list to remain unmodified make a copy first: >
3772 :let sortedlist = sort(copy(mylist))
3773< Uses the string representation of each item to sort on.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003774 Numbers sort after Strings, Lists after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003775 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003776 When {func} is given and it is one then case is ignored.
3777 When {func} is a Funcref or a function name, this function is
3778 called to compare items. The function is invoked with two
3779 items as argument and must return zero if they are equal, 1 if
3780 the first one sorts after the second one, -1 if the first one
3781 sorts before the second one. Example: >
3782 func MyCompare(i1, i2)
3783 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
3784 endfunc
3785 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003786<
3787
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00003788 *soundfold()*
3789soundfold({word})
3790 Return the sound-folded equivalent of {word}. Uses the first
3791 language in 'spellang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00003792 soundfolding. 'spell' must be set. When no sound folding is
3793 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00003794 This can be used for making spelling suggestions. Note that
3795 the method can be quite slow.
3796
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003797 *spellbadword()*
3798spellbadword() Return the badly spelled word under or after the cursor.
3799 The cursor is advanced to the start of the bad word.
3800 When no bad word is found in the cursor line an empty String
3801 is returned and the cursor doesn't move.
3802
3803 *spellsuggest()*
3804spellsuggest({word} [, {max}])
3805 Return a List with spelling suggestions to replace {word}.
3806 When {max} is given up to this number of suggestions are
3807 returned. Otherwise up to 25 suggestions are returned.
3808
3809 {word} can be a badly spelled word followed by other text.
3810 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00003811 suggestions also include the following text, thus you can
3812 replace a line.
3813
3814 {word} may also be a good word. Similar words will then be
3815 returned. {word} itself is also included, most likely as the
3816 first entry, thus this can be used to check spelling.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003817
3818 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00003819 'spell' option must be set and the values of 'spelllang' and
3820 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003821
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003822
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003823split({expr} [, {pattern} [, {keepempty}]]) *split()*
3824 Make a List out of {expr}. When {pattern} is omitted or empty
3825 each white-separated sequence of characters becomes an item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003826 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003827 removing the matched characters.
3828 When the first or last item is empty it is omitted, unless the
3829 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00003830 Other empty items are kept when {pattern} matches at least one
3831 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003832 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003833 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003834< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003835 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00003836< If you want to keep the separator you can also use '\zs': >
3837 :echo split('abc:def:ghi', ':\zs')
3838< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003839 Splitting a table where the first element can be empty: >
3840 :let items = split(line, ':', 1)
3841< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003842
3843
Bram Moolenaar071d4272004-06-13 20:20:40 +00003844strftime({format} [, {time}]) *strftime()*
3845 The result is a String, which is a formatted date and time, as
3846 specified by the {format} string. The given {time} is used,
3847 or the current time if no time is given. The accepted
3848 {format} depends on your system, thus this is not portable!
3849 See the manual page of the C function strftime() for the
3850 format. The maximum length of the result is 80 characters.
3851 See also |localtime()| and |getftime()|.
3852 The language can be changed with the |:language| command.
3853 Examples: >
3854 :echo strftime("%c") Sun Apr 27 11:49:23 1997
3855 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
3856 :echo strftime("%y%m%d %T") 970427 11:53:55
3857 :echo strftime("%H:%M") 11:55
3858 :echo strftime("%c", getftime("file.c"))
3859 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003860< Not available on all systems. To check use: >
3861 :if exists("*strftime")
3862
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003863stridx({haystack}, {needle} [, {start}]) *stridx()*
3864 The result is a Number, which gives the byte index in
3865 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003866 If {start} is specified, the search starts at index {start}.
3867 This can be used to find a second match: >
3868 :let comma1 = stridx(line, ",")
3869 :let comma2 = stridx(line, ",", comma1 + 1)
3870< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003871 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003872 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003873 See also |strridx()|.
3874 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003875 :echo stridx("An Example", "Example") 3
3876 :echo stridx("Starting point", "Start") 0
3877 :echo stridx("Starting point", "start") -1
Bram Moolenaar05159a02005-02-26 23:04:13 +00003878< *strstr()* *strchr()*
3879 stridx() works similar to the C function strstr(). When used
3880 with a single character it works similar to strchr().
3881
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003882 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003883string({expr}) Return {expr} converted to a String. If {expr} is a Number,
3884 String or a composition of them, then the result can be parsed
3885 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003886 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00003887 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003888 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00003889 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003890 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00003891 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00003892 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003893
Bram Moolenaar071d4272004-06-13 20:20:40 +00003894 *strlen()*
3895strlen({expr}) The result is a Number, which is the length of the String
3896 {expr} in bytes. If you want to count the number of
3897 multi-byte characters use something like this: >
3898
3899 :let len = strlen(substitute(str, ".", "x", "g"))
3900
3901< Composing characters are not counted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003902 If the argument is a Number it is first converted to a String.
3903 For other types an error is given.
3904 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003905
3906strpart({src}, {start}[, {len}]) *strpart()*
3907 The result is a String, which is part of {src}, starting from
3908 byte {start}, with the length {len}.
3909 When non-existing bytes are included, this doesn't result in
3910 an error, the bytes are simply omitted.
3911 If {len} is missing, the copy continues from {start} till the
3912 end of the {src}. >
3913 strpart("abcdefg", 3, 2) == "de"
3914 strpart("abcdefg", -2, 4) == "ab"
3915 strpart("abcdefg", 5, 4) == "fg"
3916 strpart("abcdefg", 3) == "defg"
3917< Note: To get the first character, {start} must be 0. For
3918 example, to get three bytes under and after the cursor: >
3919 strpart(getline(line(".")), col(".") - 1, 3)
3920<
Bram Moolenaar677ee682005-01-27 14:41:15 +00003921strridx({haystack}, {needle} [, {start}]) *strridx()*
3922 The result is a Number, which gives the byte index in
3923 {haystack} of the last occurrence of the String {needle}.
3924 When {start} is specified, matches beyond this index are
3925 ignored. This can be used to find a match before a previous
3926 match: >
3927 :let lastcomma = strridx(line, ",")
3928 :let comma2 = strridx(line, ",", lastcomma - 1)
3929< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003930 For pattern searches use |match()|.
3931 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003932 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003933 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003934 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaar05159a02005-02-26 23:04:13 +00003935< *strrchr()*
3936 When used with a single character it works similar to the C
3937 function strrchr().
3938
Bram Moolenaar071d4272004-06-13 20:20:40 +00003939strtrans({expr}) *strtrans()*
3940 The result is a String, which is {expr} with all unprintable
3941 characters translated into printable characters |'isprint'|.
3942 Like they are shown in a window. Example: >
3943 echo strtrans(@a)
3944< This displays a newline in register a as "^@" instead of
3945 starting a new line.
3946
3947submatch({nr}) *submatch()*
3948 Only for an expression in a |:substitute| command. Returns
3949 the {nr}'th submatch of the matched text. When {nr} is 0
3950 the whole matched text is returned.
3951 Example: >
3952 :s/\d\+/\=submatch(0) + 1/
3953< This finds the first number in the line and adds one to it.
3954 A line break is included as a newline character.
3955
3956substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
3957 The result is a String, which is a copy of {expr}, in which
3958 the first match of {pat} is replaced with {sub}. This works
3959 like the ":substitute" command (without any flags). But the
3960 matching with {pat} is always done like the 'magic' option is
3961 set and 'cpoptions' is empty (to make scripts portable).
3962 See |string-match| for how {pat} is used.
3963 And a "~" in {sub} is not replaced with the previous {sub}.
3964 Note that some codes in {sub} have a special meaning
3965 |sub-replace-special|. For example, to replace something with
3966 "\n" (two characters), use "\\\\n" or '\\n'.
3967 When {pat} does not match in {expr}, {expr} is returned
3968 unmodified.
3969 When {flags} is "g", all matches of {pat} in {expr} are
3970 replaced. Otherwise {flags} should be "".
3971 Example: >
3972 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
3973< This removes the last component of the 'path' option. >
3974 :echo substitute("testing", ".*", "\\U\\0", "")
3975< results in "TESTING".
3976
Bram Moolenaar47136d72004-10-12 20:02:24 +00003977synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003978 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00003979 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003980 The syntax ID can be used with |synIDattr()| and
3981 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaar47136d72004-10-12 20:02:24 +00003982 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaar071d4272004-06-13 20:20:40 +00003983 line.
3984 When {trans} is non-zero, transparent items are reduced to the
3985 item that they reveal. This is useful when wanting to know
3986 the effective color. When {trans} is zero, the transparent
3987 item is returned. This is useful when wanting to know which
3988 syntax item is effective (e.g. inside parens).
3989 Warning: This function can be very slow. Best speed is
3990 obtained by going through the file in forward direction.
3991
3992 Example (echoes the name of the syntax item under the cursor): >
3993 :echo synIDattr(synID(line("."), col("."), 1), "name")
3994<
3995synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
3996 The result is a String, which is the {what} attribute of
3997 syntax ID {synID}. This can be used to obtain information
3998 about a syntax item.
3999 {mode} can be "gui", "cterm" or "term", to get the attributes
4000 for that mode. When {mode} is omitted, or an invalid value is
4001 used, the attributes for the currently active highlighting are
4002 used (GUI, cterm or term).
4003 Use synIDtrans() to follow linked highlight groups.
4004 {what} result
4005 "name" the name of the syntax item
4006 "fg" foreground color (GUI: color name used to set
4007 the color, cterm: color number as a string,
4008 term: empty string)
4009 "bg" background color (like "fg")
4010 "fg#" like "fg", but for the GUI and the GUI is
4011 running the name in "#RRGGBB" form
4012 "bg#" like "fg#" for "bg"
4013 "bold" "1" if bold
4014 "italic" "1" if italic
4015 "reverse" "1" if reverse
4016 "inverse" "1" if inverse (= reverse)
4017 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004018 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00004019
4020 Example (echoes the color of the syntax item under the
4021 cursor): >
4022 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
4023<
4024synIDtrans({synID}) *synIDtrans()*
4025 The result is a Number, which is the translated syntax ID of
4026 {synID}. This is the syntax group ID of what is being used to
4027 highlight the character. Highlight links given with
4028 ":highlight link" are followed.
4029
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004030system({expr} [, {input}]) *system()* *E677*
4031 Get the output of the shell command {expr}.
4032 When {input} is given, this string is written to a file and
4033 passed as stdin to the command. The string is written as-is,
4034 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00004035 yourself. Pipes are not used.
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004036 Note: newlines in {expr} may cause the command to fail. The
4037 characters in 'shellquote' and 'shellxquote' may also cause
4038 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004039 This is not to be used for interactive commands.
4040 The result is a String. Example: >
4041
4042 :let files = system("ls")
4043
4044< To make the result more system-independent, the shell output
4045 is filtered to replace <CR> with <NL> for Macintosh, and
4046 <CR><NL> with <NL> for DOS-like systems.
4047 The command executed is constructed using several options:
4048 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
4049 ({tmp} is an automatically generated file name).
4050 For Unix and OS/2 braces are put around {expr} to allow for
4051 concatenated commands.
4052
4053 The resulting error code can be found in |v:shell_error|.
4054 This function will fail in |restricted-mode|.
4055 Unlike ":!cmd" there is no automatic check for changed files.
4056 Use |:checktime| to force a check.
4057
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004058
4059taglist({expr}) *taglist()*
4060 Returns a list of tags matching the regular expression {expr}.
4061 Each list item is a dictionary with the following entries:
4062 name name of the tag.
4063 filename name of the file where the tag is
4064 defined.
4065 cmd Ex command used to locate the tag in
4066 the file.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004067 kind type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004068 entry depends on the language specific
4069 kind values generated by the ctags
4070 tool.
4071 static a file specific tag. Refer to
4072 |static-tag| for more information.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004073 The "kind" entry is only available when using Exuberant ctags
4074 generated tags file. More entries may be present, depending
4075 on the content of the tags file: access, implementation,
4076 inherits and signature. Refer to the ctags documentation for
4077 information about these fields. For C code the fields
4078 "struct", "class" and "enum" may appear, they give the name of
4079 the entity the tag is contained in.
4080
4081 The ex-command 'cmd' can be either an ex search pattern, a
4082 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004083
4084 If there are no matching tags, then an empty list is returned.
4085
4086 To get an exact tag match, the anchors '^' and '$' should be
4087 used in {expr}. Refer to |tag-regexp| for more information
4088 about the tag search regular expression pattern.
4089
4090 Refer to |'tags'| for information about how the tags file is
4091 located by Vim. Refer to |tags-file-format| for the format of
4092 the tags file generated by the different ctags tools.
4093
4094
Bram Moolenaar071d4272004-06-13 20:20:40 +00004095tempname() *tempname()* *temp-file-name*
4096 The result is a String, which is the name of a file that
4097 doesn't exist. It can be used for a temporary file. The name
4098 is different for at least 26 consecutive calls. Example: >
4099 :let tmpfile = tempname()
4100 :exe "redir > " . tmpfile
4101< For Unix, the file will be in a private directory (only
4102 accessible by the current user) to avoid security problems
4103 (e.g., a symlink attack or other people reading your file).
4104 When Vim exits the directory and all files in it are deleted.
4105 For MS-Windows forward slashes are used when the 'shellslash'
4106 option is set or when 'shellcmdflag' starts with '-'.
4107
4108tolower({expr}) *tolower()*
4109 The result is a copy of the String given, with all uppercase
4110 characters turned into lowercase (just like applying |gu| to
4111 the string).
4112
4113toupper({expr}) *toupper()*
4114 The result is a copy of the String given, with all lowercase
4115 characters turned into uppercase (just like applying |gU| to
4116 the string).
4117
Bram Moolenaar8299df92004-07-10 09:47:34 +00004118tr({src}, {fromstr}, {tostr}) *tr()*
4119 The result is a copy of the {src} string with all characters
4120 which appear in {fromstr} replaced by the character in that
4121 position in the {tostr} string. Thus the first character in
4122 {fromstr} is translated into the first character in {tostr}
4123 and so on. Exactly like the unix "tr" command.
4124 This code also deals with multibyte characters properly.
4125
4126 Examples: >
4127 echo tr("hello there", "ht", "HT")
4128< returns "Hello THere" >
4129 echo tr("<blob>", "<>", "{}")
4130< returns "{blob}"
4131
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004132 *type()*
4133type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00004134 Number: 0
4135 String: 1
4136 Funcref: 2
4137 List: 3
4138 Dictionary: 4
4139 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004140 :if type(myvar) == type(0)
4141 :if type(myvar) == type("")
4142 :if type(myvar) == type(function("tr"))
4143 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00004144 :if type(myvar) == type({})
Bram Moolenaar071d4272004-06-13 20:20:40 +00004145
Bram Moolenaar677ee682005-01-27 14:41:15 +00004146values({dict}) *values()*
4147 Return a List with all the values of {dict}. The List is in
4148 arbitrary order.
4149
4150
Bram Moolenaar071d4272004-06-13 20:20:40 +00004151virtcol({expr}) *virtcol()*
4152 The result is a Number, which is the screen column of the file
4153 position given with {expr}. That is, the last screen position
4154 occupied by the character at that position, when the screen
4155 would be of unlimited width. When there is a <Tab> at the
4156 position, the returned Number will be the column at the end of
4157 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
4158 set to 8, it returns 8.
4159 For the byte position use |col()|.
4160 When Virtual editing is active in the current mode, a position
4161 beyond the end of the line can be returned. |'virtualedit'|
4162 The accepted positions are:
4163 . the cursor position
4164 $ the end of the cursor line (the result is the
4165 number of displayed characters in the cursor line
4166 plus one)
4167 'x position of mark x (if the mark is not set, 0 is
4168 returned)
4169 Note that only marks in the current file can be used.
4170 Examples: >
4171 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
4172 virtcol("$") with text "foo^Lbar", returns 9
4173 virtcol("'t") with text " there", with 't at 'h', returns 6
4174< The first column is 1. 0 is returned for an error.
4175
4176visualmode([expr]) *visualmode()*
4177 The result is a String, which describes the last Visual mode
4178 used. Initially it returns an empty string, but once Visual
4179 mode has been used, it returns "v", "V", or "<CTRL-V>" (a
4180 single CTRL-V character) for character-wise, line-wise, or
4181 block-wise Visual mode respectively.
4182 Example: >
4183 :exe "normal " . visualmode()
4184< This enters the same Visual mode as before. It is also useful
4185 in scripts if you wish to act differently depending on the
4186 Visual mode that was used.
4187
4188 If an expression is supplied that results in a non-zero number
4189 or a non-empty string, then the Visual mode will be cleared
4190 and the old value is returned. Note that " " and "0" are also
4191 non-empty strings, thus cause the mode to be cleared.
4192
4193 *winbufnr()*
4194winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004195 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004196 the buffer in the current window is returned. When window
4197 {nr} doesn't exist, -1 is returned.
4198 Example: >
4199 :echo "The file in the current window is " . bufname(winbufnr(0))
4200<
4201 *wincol()*
4202wincol() The result is a Number, which is the virtual column of the
4203 cursor in the window. This is counting screen cells from the
4204 left side of the window. The leftmost column is one.
4205
4206winheight({nr}) *winheight()*
4207 The result is a Number, which is the height of window {nr}.
4208 When {nr} is zero, the height of the current window is
4209 returned. When window {nr} doesn't exist, -1 is returned.
4210 An existing window always has a height of zero or more.
4211 Examples: >
4212 :echo "The current window has " . winheight(0) . " lines."
4213<
4214 *winline()*
4215winline() The result is a Number, which is the screen line of the cursor
4216 in the window. This is counting screen lines from the top of
4217 the window. The first line is one.
4218
4219 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004220winnr([{arg}]) The result is a Number, which is the number of the current
4221 window. The top window has number 1.
4222 When the optional argument is "$", the number of the
4223 last window is returnd (the window count).
4224 When the optional argument is "#", the number of the last
4225 accessed window is returned (where |CTRL-W_p| goes to).
4226 If there is no previous window 0 is returned.
4227 The number can be used with |CTRL-W_w| and ":wincmd w"
4228 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004229
4230 *winrestcmd()*
4231winrestcmd() Returns a sequence of |:resize| commands that should restore
4232 the current window sizes. Only works properly when no windows
4233 are opened or closed and the current window is unchanged.
4234 Example: >
4235 :let cmd = winrestcmd()
4236 :call MessWithWindowSizes()
4237 :exe cmd
4238
4239winwidth({nr}) *winwidth()*
4240 The result is a Number, which is the width of window {nr}.
4241 When {nr} is zero, the width of the current window is
4242 returned. When window {nr} doesn't exist, -1 is returned.
4243 An existing window always has a width of zero or more.
4244 Examples: >
4245 :echo "The current window has " . winwidth(0) . " columns."
4246 :if winwidth(0) <= 50
4247 : exe "normal 50\<C-W>|"
4248 :endif
4249<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004250 *writefile()*
4251writefile({list}, {fname} [, {binary}])
4252 Write List {list} to file {fname}. Each list item is
4253 separated with a NL. Each list item must be a String or
4254 Number.
4255 When {binary} is equal to "b" binary mode is used: There will
4256 not be a NL after the last list item. An empty item at the
4257 end does cause the last line in the file to end in a NL.
4258 All NL characters are replaced with a NUL character.
4259 Inserting CR characters needs to be done before passing {list}
4260 to writefile().
4261 An existing file is overwritten, if possible.
4262 When the write fails -1 is returned, otherwise 0. There is an
4263 error message if the file can't be created or when writing
4264 fails.
4265 Also see |readfile()|.
4266 To copy a file byte for byte: >
4267 :let fl = readfile("foo", "b")
4268 :call writefile(fl, "foocopy", "b")
4269<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004270
4271 *feature-list*
4272There are three types of features:
42731. Features that are only supported when they have been enabled when Vim
4274 was compiled |+feature-list|. Example: >
4275 :if has("cindent")
42762. Features that are only supported when certain conditions have been met.
4277 Example: >
4278 :if has("gui_running")
4279< *has-patch*
42803. Included patches. First check |v:version| for the version of Vim.
4281 Then the "patch123" feature means that patch 123 has been included for
4282 this version. Example (checking version 6.2.148 or later): >
4283 :if v:version > 602 || v:version == 602 && has("patch148")
4284
4285all_builtin_terms Compiled with all builtin terminals enabled.
4286amiga Amiga version of Vim.
4287arabic Compiled with Arabic support |Arabic|.
4288arp Compiled with ARP support (Amiga).
4289autocmd Compiled with autocommands support.
4290balloon_eval Compiled with |balloon-eval| support.
4291beos BeOS version of Vim.
4292browse Compiled with |:browse| support, and browse() will
4293 work.
4294builtin_terms Compiled with some builtin terminals.
4295byte_offset Compiled with support for 'o' in 'statusline'
4296cindent Compiled with 'cindent' support.
4297clientserver Compiled with remote invocation support |clientserver|.
4298clipboard Compiled with 'clipboard' support.
4299cmdline_compl Compiled with |cmdline-completion| support.
4300cmdline_hist Compiled with |cmdline-history| support.
4301cmdline_info Compiled with 'showcmd' and 'ruler' support.
4302comments Compiled with |'comments'| support.
4303cryptv Compiled with encryption support |encryption|.
4304cscope Compiled with |cscope| support.
4305compatible Compiled to be very Vi compatible.
4306debug Compiled with "DEBUG" defined.
4307dialog_con Compiled with console dialog support.
4308dialog_gui Compiled with GUI dialog support.
4309diff Compiled with |vimdiff| and 'diff' support.
4310digraphs Compiled with support for digraphs.
4311dnd Compiled with support for the "~ register |quote_~|.
4312dos32 32 bits DOS (DJGPP) version of Vim.
4313dos16 16 bits DOS version of Vim.
4314ebcdic Compiled on a machine with ebcdic character set.
4315emacs_tags Compiled with support for Emacs tags.
4316eval Compiled with expression evaluation support. Always
4317 true, of course!
4318ex_extra Compiled with extra Ex commands |+ex_extra|.
4319extra_search Compiled with support for |'incsearch'| and
4320 |'hlsearch'|
4321farsi Compiled with Farsi support |farsi|.
4322file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004323filterpipe When 'shelltemp' is off pipes are used for shell
4324 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00004325find_in_path Compiled with support for include file searches
4326 |+find_in_path|.
4327fname_case Case in file names matters (for Amiga, MS-DOS, and
4328 Windows this is not present).
4329folding Compiled with |folding| support.
4330footer Compiled with GUI footer support. |gui-footer|
4331fork Compiled to use fork()/exec() instead of system().
4332gettext Compiled with message translation |multi-lang|
4333gui Compiled with GUI enabled.
4334gui_athena Compiled with Athena GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004335gui_gtk Compiled with GTK+ GUI (any version).
4336gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar843ee412004-06-30 16:16:41 +00004337gui_kde Compiled with KDE GUI |KVim|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004338gui_mac Compiled with Macintosh GUI.
4339gui_motif Compiled with Motif GUI.
4340gui_photon Compiled with Photon GUI.
4341gui_win32 Compiled with MS Windows Win32 GUI.
4342gui_win32s idem, and Win32s system being used (Windows 3.1)
4343gui_running Vim is running in the GUI, or it will start soon.
4344hangul_input Compiled with Hangul input support. |hangul|
4345iconv Can use iconv() for conversion.
4346insert_expand Compiled with support for CTRL-X expansion commands in
4347 Insert mode.
4348jumplist Compiled with |jumplist| support.
4349keymap Compiled with 'keymap' support.
4350langmap Compiled with 'langmap' support.
4351libcall Compiled with |libcall()| support.
4352linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
4353 support.
4354lispindent Compiled with support for lisp indenting.
4355listcmds Compiled with commands for the buffer list |:files|
4356 and the argument list |arglist|.
4357localmap Compiled with local mappings and abbr. |:map-local|
4358mac Macintosh version of Vim.
4359macunix Macintosh version of Vim, using Unix files (OS-X).
4360menu Compiled with support for |:menu|.
4361mksession Compiled with support for |:mksession|.
4362modify_fname Compiled with file name modifiers. |filename-modifiers|
4363mouse Compiled with support mouse.
4364mouseshape Compiled with support for 'mouseshape'.
4365mouse_dec Compiled with support for Dec terminal mouse.
4366mouse_gpm Compiled with support for gpm (Linux console mouse)
4367mouse_netterm Compiled with support for netterm mouse.
4368mouse_pterm Compiled with support for qnx pterm mouse.
4369mouse_xterm Compiled with support for xterm mouse.
4370multi_byte Compiled with support for editing Korean et al.
4371multi_byte_ime Compiled with support for IME input method.
4372multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00004373mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004374netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00004375netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004376ole Compiled with OLE automation support for Win32.
4377os2 OS/2 version of Vim.
4378osfiletype Compiled with support for osfiletypes |+osfiletype|
4379path_extra Compiled with up/downwards search in 'path' and 'tags'
4380perl Compiled with Perl interface.
4381postscript Compiled with PostScript file printing.
4382printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004383profile Compiled with |:profile| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004384python Compiled with Python interface.
4385qnx QNX version of Vim.
4386quickfix Compiled with |quickfix| support.
4387rightleft Compiled with 'rightleft' support.
4388ruby Compiled with Ruby interface |ruby|.
4389scrollbind Compiled with 'scrollbind' support.
4390showcmd Compiled with 'showcmd' support.
4391signs Compiled with |:sign| support.
4392smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004393sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004394statusline Compiled with support for 'statusline', 'rulerformat'
4395 and special formats of 'titlestring' and 'iconstring'.
4396sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00004397spell Compiled with spell checking support |spell|.
4398syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004399syntax_items There are active syntax highlighting items for the
4400 current buffer.
4401system Compiled to use system() instead of fork()/exec().
4402tag_binary Compiled with binary searching in tags files
4403 |tag-binary-search|.
4404tag_old_static Compiled with support for old static tags
4405 |tag-old-static|.
4406tag_any_white Compiled with support for any white characters in tags
4407 files |tag-any-white|.
4408tcl Compiled with Tcl interface.
4409terminfo Compiled with terminfo instead of termcap.
4410termresponse Compiled with support for |t_RV| and |v:termresponse|.
4411textobjects Compiled with support for |text-objects|.
4412tgetent Compiled with tgetent support, able to use a termcap
4413 or terminfo file.
4414title Compiled with window title support |'title'|.
4415toolbar Compiled with support for |gui-toolbar|.
4416unix Unix version of Vim.
4417user_commands User-defined commands.
4418viminfo Compiled with viminfo support.
4419vim_starting True while initial source'ing takes place.
4420vertsplit Compiled with vertically split windows |:vsplit|.
4421virtualedit Compiled with 'virtualedit' option.
4422visual Compiled with Visual mode.
4423visualextra Compiled with extra Visual mode commands.
4424 |blockwise-operators|.
4425vms VMS version of Vim.
4426vreplace Compiled with |gR| and |gr| commands.
4427wildignore Compiled with 'wildignore' option.
4428wildmenu Compiled with 'wildmenu' option.
4429windows Compiled with support for more than one window.
4430winaltkeys Compiled with 'winaltkeys' option.
4431win16 Win16 version of Vim (MS-Windows 3.1).
4432win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
4433win64 Win64 version of Vim (MS-Windows 64 bit).
4434win32unix Win32 version of Vim, using Unix files (Cygwin)
4435win95 Win32 version for MS-Windows 95/98/ME.
4436writebackup Compiled with 'writebackup' default on.
4437xfontset Compiled with X fontset support |xfontset|.
4438xim Compiled with X input method support |xim|.
4439xsmp Compiled with X session management support.
4440xsmp_interact Compiled with interactive X session management support.
4441xterm_clipboard Compiled with support for xterm clipboard.
4442xterm_save Compiled with support for saving and restoring the
4443 xterm screen.
4444x11 Compiled with X11 support.
4445
4446 *string-match*
4447Matching a pattern in a String
4448
4449A regexp pattern as explained at |pattern| is normally used to find a match in
4450the buffer lines. When a pattern is used to find a match in a String, almost
4451everything works in the same way. The difference is that a String is handled
4452like it is one line. When it contains a "\n" character, this is not seen as a
4453line break for the pattern. It can be matched with a "\n" in the pattern, or
4454with ".". Example: >
4455 :let a = "aaaa\nxxxx"
4456 :echo matchstr(a, "..\n..")
4457 aa
4458 xx
4459 :echo matchstr(a, "a.x")
4460 a
4461 x
4462
4463Don't forget that "^" will only match at the first character of the String and
4464"$" at the last character of the string. They don't match after or before a
4465"\n".
4466
4467==============================================================================
44685. Defining functions *user-functions*
4469
4470New functions can be defined. These can be called just like builtin
4471functions. The function executes a sequence of Ex commands. Normal mode
4472commands can be executed with the |:normal| command.
4473
4474The function name must start with an uppercase letter, to avoid confusion with
4475builtin functions. To prevent from using the same name in different scripts
4476avoid obvious, short names. A good habit is to start the function name with
4477the name of the script, e.g., "HTMLcolor()".
4478
4479It's also possible to use curly braces, see |curly-braces-names|.
4480
4481 *local-function*
4482A function local to a script must start with "s:". A local script function
4483can only be called from within the script and from functions, user commands
4484and autocommands defined in the script. It is also possible to call the
4485function from a mappings defined in the script, but then |<SID>| must be used
4486instead of "s:" when the mapping is expanded outside of the script.
4487
4488 *:fu* *:function* *E128* *E129* *E123*
4489:fu[nction] List all functions and their arguments.
4490
4491:fu[nction] {name} List function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004492 {name} can also be a Dictionary entry that is a
4493 Funcref: >
4494 :function dict.init
4495< *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004496:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004497 Define a new function by the name {name}. The name
4498 must be made of alphanumeric characters and '_', and
4499 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004500
4501 {name} can also be a Dictionary entry that is a
4502 Funcref: >
4503 :function dict.init(arg)
4504< "dict" must be an existing dictionary. The entry
4505 "init" is added if it didn't exist yet. Otherwise [!]
4506 is required to overwrite an existing function. The
4507 result is a |Funcref| to a numbered function. The
4508 function can only be used with a |Funcref| and will be
4509 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004510 *E127* *E122*
4511 When a function by this name already exists and [!] is
4512 not used an error message is given. When [!] is used,
4513 an existing function is silently replaced. Unless it
4514 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004515
4516 For the {arguments} see |function-argument|.
4517
Bram Moolenaar071d4272004-06-13 20:20:40 +00004518 *a:firstline* *a:lastline*
4519 When the [range] argument is added, the function is
4520 expected to take care of a range itself. The range is
4521 passed as "a:firstline" and "a:lastline". If [range]
4522 is excluded, ":{range}call" will call the function for
4523 each line in the range, with the cursor on the start
4524 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004525
Bram Moolenaar071d4272004-06-13 20:20:40 +00004526 When the [abort] argument is added, the function will
4527 abort as soon as an error is detected.
4528 The last used search pattern and the redo command "."
4529 will not be changed by the function.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004530
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004531 When the [dict] argument is added, the function must
4532 be invoked through an entry in a Dictionary. The
4533 local variable "self" will then be set to the
4534 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004535
4536 *:endf* *:endfunction* *E126* *E193*
4537:endf[unction] The end of a function definition. Must be on a line
4538 by its own, without other commands.
4539
4540 *:delf* *:delfunction* *E130* *E131*
4541:delf[unction] {name} Delete function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004542 {name} can also be a Dictionary entry that is a
4543 Funcref: >
4544 :delfunc dict.init
4545< This will remove the "init" entry from "dict". The
4546 function is deleted if there are no more references to
4547 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004548 *:retu* *:return* *E133*
4549:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
4550 evaluated and returned as the result of the function.
4551 If "[expr]" is not given, the number 0 is returned.
4552 When a function ends without an explicit ":return",
4553 the number 0 is returned.
4554 Note that there is no check for unreachable lines,
4555 thus there is no warning if commands follow ":return".
4556
4557 If the ":return" is used after a |:try| but before the
4558 matching |:finally| (if present), the commands
4559 following the ":finally" up to the matching |:endtry|
4560 are executed first. This process applies to all
4561 nested ":try"s inside the function. The function
4562 returns at the outermost ":endtry".
4563
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004564 *function-argument* *a:var*
4565An argument can be defined by giving its name. In the function this can then
4566be used as "a:name" ("a:" for argument).
4567 *a:0* *a:1* *a:000* *E740*
4568Up to 20 arguments can be given, separated by commas. After the named
4569arguments an argument "..." can be specified, which means that more arguments
4570may optionally be following. In the function the extra arguments can be used
4571as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004572can be 0). "a:000" is set to a List that contains these arguments. Note that
4573"a:1" is the same as "a:000[0]".
4574 *E742*
4575The a: scope and the variables in it cannot be changed, they are fixed.
4576However, if a List or Dictionary is used, you can changes their contents.
4577Thus you can pass a List to a function and have the function add an item to
4578it. If you want to make sure the function cannot change a List or Dictionary
4579use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004580
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004581When not using "...", the number of arguments in a function call must be equal
4582to the number of named arguments. When using "...", the number of arguments
4583may be larger.
4584
4585It is also possible to define a function without any arguments. You must
4586still supply the () then. The body of the function follows in the next lines,
4587until the matching |:endfunction|. It is allowed to define another function
4588inside a function body.
4589
4590 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004591Inside a function variables can be used. These are local variables, which
4592will disappear when the function returns. Global variables need to be
4593accessed with "g:".
4594
4595Example: >
4596 :function Table(title, ...)
4597 : echohl Title
4598 : echo a:title
4599 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00004600 : echo a:0 . " items:"
4601 : for s in a:000
4602 : echon ' ' . s
4603 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004604 :endfunction
4605
4606This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00004607 call Table("Table", "line1", "line2")
4608 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004609
4610To return more than one value, pass the name of a global variable: >
4611 :function Compute(n1, n2, divname)
4612 : if a:n2 == 0
4613 : return "fail"
4614 : endif
4615 : let g:{a:divname} = a:n1 / a:n2
4616 : return "ok"
4617 :endfunction
4618
4619This function can then be called with: >
4620 :let success = Compute(13, 1324, "div")
4621 :if success == "ok"
4622 : echo div
4623 :endif
4624
4625An alternative is to return a command that can be executed. This also works
4626with local variables in a calling function. Example: >
4627 :function Foo()
4628 : execute Bar()
4629 : echo "line " . lnum . " column " . col
4630 :endfunction
4631
4632 :function Bar()
4633 : return "let lnum = " . line(".") . " | let col = " . col(".")
4634 :endfunction
4635
4636The names "lnum" and "col" could also be passed as argument to Bar(), to allow
4637the caller to set the names.
4638
4639 *:cal* *:call* *E107*
4640:[range]cal[l] {name}([arguments])
4641 Call a function. The name of the function and its arguments
4642 are as specified with |:function|. Up to 20 arguments can be
4643 used.
4644 Without a range and for functions that accept a range, the
4645 function is called once. When a range is given the cursor is
4646 positioned at the start of the first line before executing the
4647 function.
4648 When a range is given and the function doesn't handle it
4649 itself, the function is executed for each line in the range,
4650 with the cursor in the first column of that line. The cursor
4651 is left at the last line (possibly moved by the last function
4652 call). The arguments are re-evaluated for each line. Thus
4653 this works:
4654 *function-range-example* >
4655 :function Mynumber(arg)
4656 : echo line(".") . " " . a:arg
4657 :endfunction
4658 :1,5call Mynumber(getline("."))
4659<
4660 The "a:firstline" and "a:lastline" are defined anyway, they
4661 can be used to do something different at the start or end of
4662 the range.
4663
4664 Example of a function that handles the range itself: >
4665
4666 :function Cont() range
4667 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
4668 :endfunction
4669 :4,8call Cont()
4670<
4671 This function inserts the continuation character "\" in front
4672 of all the lines in the range, except the first one.
4673
4674 *E132*
4675The recursiveness of user functions is restricted with the |'maxfuncdepth'|
4676option.
4677
Bram Moolenaar7c626922005-02-07 22:01:03 +00004678
4679AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004680 *autoload-functions*
4681When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00004682only when they are used. There are two methods: with an autocommand and with
4683the "autoload" directory in 'runtimepath'.
4684
4685
4686Using an autocommand ~
4687
Bram Moolenaar05159a02005-02-26 23:04:13 +00004688This is introduced in the user manual, section |41.14|.
4689
Bram Moolenaar7c626922005-02-07 22:01:03 +00004690The autocommand is useful if you have a plugin that is a long Vim script file.
4691You can define the autocommand and quickly quit the script with |:finish|.
4692That makes Vim startup faster. The autocommand should then load the same file
4693again, setting a variable to skip the |:finish| command.
4694
4695Use the FuncUndefined autocommand event with a pattern that matches the
4696function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004697
4698 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
4699
4700The file "~/vim/bufnetfuncs.vim" should then define functions that start with
4701"BufNet". Also see |FuncUndefined|.
4702
Bram Moolenaar7c626922005-02-07 22:01:03 +00004703
4704Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004705 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00004706This is introduced in the user manual, section |41.15|.
4707
Bram Moolenaar7c626922005-02-07 22:01:03 +00004708Using a script in the "autoload" directory is simpler, but requires using
4709exactly the right file name. A function that can be autoloaded has a name
4710like this: >
4711
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004712 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004713
4714When such a function is called, and it is not defined yet, Vim will search the
4715"autoload" directories in 'runtimepath' for a script file called
4716"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
4717then define the function like this: >
4718
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004719 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004720 echo "Done!"
4721 endfunction
4722
4723The file name and the name used before the colon in the function must match
4724exactly, and the defined function must have the name exactly as it will be
4725called.
4726
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004727It is possible to use subdirectories. Every # in the function name works like
4728a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00004729
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004730 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004731
4732Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
4733
4734The name before the first colon must be at least two characters long,
4735otherwise it looks like a scope, such as "s:".
4736
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004737This also works when reading a variable that has not been set yet: >
4738
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004739 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004740
4741When assigning a value to such a variable nothing special happens. This can
4742be used to pass settings to the autoload script before it's loaded: >
4743
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004744 :let foo#bar#toggle = 1
4745 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004746
Bram Moolenaar4399ef42005-02-12 14:29:27 +00004747Note that when you make a mistake and call a function that is supposed to be
4748defined in an autoload script, but the script doesn't actually define the
4749function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004750And you will get an error message every time.
4751
4752Also note that if you have two script files, and one calls a function in the
4753other and vise versa, before the used function is defined, it won't work.
4754Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00004755
Bram Moolenaar071d4272004-06-13 20:20:40 +00004756==============================================================================
47576. Curly braces names *curly-braces-names*
4758
4759Wherever you can use a variable, you can use a "curly braces name" variable.
4760This is a regular variable name with one or more expressions wrapped in braces
4761{} like this: >
4762 my_{adjective}_variable
4763
4764When Vim encounters this, it evaluates the expression inside the braces, puts
4765that in place of the expression, and re-interprets the whole as a variable
4766name. So in the above example, if the variable "adjective" was set to
4767"noisy", then the reference would be to "my_noisy_variable", whereas if
4768"adjective" was set to "quiet", then it would be to "my_quiet_variable".
4769
4770One application for this is to create a set of variables governed by an option
4771value. For example, the statement >
4772 echo my_{&background}_message
4773
4774would output the contents of "my_dark_message" or "my_light_message" depending
4775on the current value of 'background'.
4776
4777You can use multiple brace pairs: >
4778 echo my_{adverb}_{adjective}_message
4779..or even nest them: >
4780 echo my_{ad{end_of_word}}_message
4781where "end_of_word" is either "verb" or "jective".
4782
4783However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004784variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004785 :let foo='a + b'
4786 :echo c{foo}d
4787.. since the result of expansion is "ca + bd", which is not a variable name.
4788
4789 *curly-braces-function-names*
4790You can call and define functions by an evaluated name in a similar way.
4791Example: >
4792 :let func_end='whizz'
4793 :call my_func_{func_end}(parameter)
4794
4795This would call the function "my_func_whizz(parameter)".
4796
4797==============================================================================
47987. Commands *expression-commands*
4799
4800:let {var-name} = {expr1} *:let* *E18*
4801 Set internal variable {var-name} to the result of the
4802 expression {expr1}. The variable will get the type
4803 from the {expr}. If {var-name} didn't exist yet, it
4804 is created.
4805
Bram Moolenaar13065c42005-01-08 16:08:21 +00004806:let {var-name}[{idx}] = {expr1} *E689*
4807 Set a list item to the result of the expression
4808 {expr1}. {var-name} must refer to a list and {idx}
4809 must be a valid index in that list. For nested list
4810 the index can be repeated.
4811 This cannot be used to add an item to a list.
4812
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004813 *E711* *E719*
4814:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004815 Set a sequence of items in a List to the result of the
4816 expression {expr1}, which must be a list with the
4817 correct number of items.
4818 {idx1} can be omitted, zero is used instead.
4819 {idx2} can be omitted, meaning the end of the list.
4820 When the selected range of items is partly past the
4821 end of the list, items will be added.
4822
Bram Moolenaar748bf032005-02-02 23:04:36 +00004823 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004824:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
4825:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
4826:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
4827 These fail if {var} was not set yet and when the type
4828 of {var} and {expr1} don't fit the operator.
4829
4830
Bram Moolenaar071d4272004-06-13 20:20:40 +00004831:let ${env-name} = {expr1} *:let-environment* *:let-$*
4832 Set environment variable {env-name} to the result of
4833 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004834:let ${env-name} .= {expr1}
4835 Append {expr1} to the environment variable {env-name}.
4836 If the environment variable didn't exist yet this
4837 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004838
4839:let @{reg-name} = {expr1} *:let-register* *:let-@*
4840 Write the result of the expression {expr1} in register
4841 {reg-name}. {reg-name} must be a single letter, and
4842 must be the name of a writable register (see
4843 |registers|). "@@" can be used for the unnamed
4844 register, "@/" for the search pattern.
4845 If the result of {expr1} ends in a <CR> or <NL>, the
4846 register will be linewise, otherwise it will be set to
4847 characterwise.
4848 This can be used to clear the last search pattern: >
4849 :let @/ = ""
4850< This is different from searching for an empty string,
4851 that would match everywhere.
4852
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004853:let @{reg-name} .= {expr1}
4854 Append {expr1} to register {reg-name}. If the
4855 register was empty it's like setting it to {expr1}.
4856
Bram Moolenaar071d4272004-06-13 20:20:40 +00004857:let &{option-name} = {expr1} *:let-option* *:let-star*
4858 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004859 expression {expr1}. A String or Number value is
4860 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004861 For an option local to a window or buffer the effect
4862 is just like using the |:set| command: both the local
4863 value and the global value is changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004864 Example: >
4865 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004866
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004867:let &{option-name} .= {expr1}
4868 For a string option: Append {expr1} to the value.
4869 Does not insert a comma like |:set+=|.
4870
4871:let &{option-name} += {expr1}
4872:let &{option-name} -= {expr1}
4873 For a number or boolean option: Add or subtract
4874 {expr1}.
4875
Bram Moolenaar071d4272004-06-13 20:20:40 +00004876:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004877:let &l:{option-name} .= {expr1}
4878:let &l:{option-name} += {expr1}
4879:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004880 Like above, but only set the local value of an option
4881 (if there is one). Works like |:setlocal|.
4882
4883:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004884:let &g:{option-name} .= {expr1}
4885:let &g:{option-name} += {expr1}
4886:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004887 Like above, but only set the global value of an option
4888 (if there is one). Works like |:setglobal|.
4889
Bram Moolenaar13065c42005-01-08 16:08:21 +00004890:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004891 {expr1} must evaluate to a List. The first item in
4892 the list is assigned to {name1}, the second item to
4893 {name2}, etc.
4894 The number of names must match the number of items in
4895 the List.
4896 Each name can be one of the items of the ":let"
4897 command as mentioned above.
4898 Example: >
4899 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004900< Detail: {expr1} is evaluated first, then the
4901 assignments are done in sequence. This matters if
4902 {name2} depends on {name1}. Example: >
4903 :let x = [0, 1]
4904 :let i = 0
4905 :let [i, x[i]] = [1, 2]
4906 :echo x
4907< The result is [0, 2].
4908
4909:let [{name1}, {name2}, ...] .= {expr1}
4910:let [{name1}, {name2}, ...] += {expr1}
4911:let [{name1}, {name2}, ...] -= {expr1}
4912 Like above, but append/add/subtract the value for each
4913 List item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004914
4915:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar677ee682005-01-27 14:41:15 +00004916 Like |:let-unpack| above, but the List may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004917 items than there are names. A list of the remaining
4918 items is assigned to {lastname}. If there are no
4919 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004920 Example: >
4921 :let [a, b; rest] = ["aval", "bval", 3, 4]
4922<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004923:let [{name}, ..., ; {lastname}] .= {expr1}
4924:let [{name}, ..., ; {lastname}] += {expr1}
4925:let [{name}, ..., ; {lastname}] -= {expr1}
4926 Like above, but append/add/subtract the value for each
4927 List item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004928 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004929:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00004930 variable names may be given. Special names recognized
4931 here: *E738*
4932 g: global variables.
4933 b: local buffer variables.
4934 w: local window variables.
4935 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004936
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004937:let List the values of all variables. The type of the
4938 variable is indicated before the value:
4939 <nothing> String
4940 # Number
4941 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00004942
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004943
4944:unl[et][!] {name} ... *:unlet* *:unl* *E108*
4945 Remove the internal variable {name}. Several variable
4946 names can be given, they are all removed. The name
4947 may also be a List or Dictionary item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004948 With [!] no error message is given for non-existing
4949 variables.
Bram Moolenaar9cd15162005-01-16 22:02:49 +00004950 One or more items from a List can be removed: >
4951 :unlet list[3] " remove fourth item
4952 :unlet list[3:] " remove fourth item to last
4953< One item from a Dictionary can be removed at a time: >
4954 :unlet dict['two']
4955 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00004956
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004957:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
4958 Lock the internal variable {name}. Locking means that
4959 it can no longer be changed (until it is unlocked).
4960 A locked variable can be deleted: >
4961 :lockvar v
4962 :let v = 'asdf' " fails!
4963 :unlet v
4964< *E741*
4965 If you try to change a locked variable you get an
4966 error message: "E741: Value of {name} is locked"
4967
4968 [depth] is relevant when locking a List or Dictionary.
4969 It specifies how deep the locking goes:
4970 1 Lock the List or Dictionary itself,
4971 cannot add or remove items, but can
4972 still change their values.
4973 2 Also lock the values, cannot change
4974 the items. If an item is a List or
4975 Dictionary, cannot add or remove
4976 items, but can still change the
4977 values.
4978 3 Like 2 but for the List/Dictionary in
4979 the List/Dictionary, one level deeper.
4980 The default [depth] is 2, thus when {name} is a List
4981 or Dictionary the values cannot be changed.
4982 *E743*
4983 For unlimited depth use [!] and omit [depth].
4984 However, there is a maximum depth of 100 to catch
4985 loops.
4986
4987 Note that when two variables refer to the same List
4988 and you lock one of them, the List will also be locked
4989 when used through the other variable. Example: >
4990 :let l = [0, 1, 2, 3]
4991 :let cl = l
4992 :lockvar l
4993 :let cl[1] = 99 " won't work!
4994< You may want to make a copy of a list to avoid this.
4995 See |deepcopy()|.
4996
4997
4998:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
4999 Unlock the internal variable {name}. Does the
5000 opposite of |:lockvar|.
5001
5002
Bram Moolenaar071d4272004-06-13 20:20:40 +00005003:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
5004:en[dif] Execute the commands until the next matching ":else"
5005 or ":endif" if {expr1} evaluates to non-zero.
5006
5007 From Vim version 4.5 until 5.0, every Ex command in
5008 between the ":if" and ":endif" is ignored. These two
5009 commands were just to allow for future expansions in a
5010 backwards compatible way. Nesting was allowed. Note
5011 that any ":else" or ":elseif" was ignored, the "else"
5012 part was not executed either.
5013
5014 You can use this to remain compatible with older
5015 versions: >
5016 :if version >= 500
5017 : version-5-specific-commands
5018 :endif
5019< The commands still need to be parsed to find the
5020 "endif". Sometimes an older Vim has a problem with a
5021 new command. For example, ":silent" is recognized as
5022 a ":substitute" command. In that case ":execute" can
5023 avoid problems: >
5024 :if version >= 600
5025 : execute "silent 1,$delete"
5026 :endif
5027<
5028 NOTE: The ":append" and ":insert" commands don't work
5029 properly in between ":if" and ":endif".
5030
5031 *:else* *:el* *E581* *E583*
5032:el[se] Execute the commands until the next matching ":else"
5033 or ":endif" if they previously were not being
5034 executed.
5035
5036 *:elseif* *:elsei* *E582* *E584*
5037:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
5038 is no extra ":endif".
5039
5040:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005041 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005042:endw[hile] Repeat the commands between ":while" and ":endwhile",
5043 as long as {expr1} evaluates to non-zero.
5044 When an error is detected from a command inside the
5045 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00005046 Example: >
5047 :let lnum = 1
5048 :while lnum <= line("$")
5049 :call FixLine(lnum)
5050 :let lnum = lnum + 1
5051 :endwhile
5052<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005053 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00005054 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005055
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005056:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00005057:endfo[r] *:endfo* *:endfor*
5058 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005059 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005060 value of each item.
5061 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00005062 loop, execution continues after the "endfor".
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005063 Changing {list} affects what items are used. Make a
5064 copy if this is unwanted: >
5065 :for item in copy(mylist)
5066< When not making a copy, Vim stores a reference to the
5067 next item in the list, before executing the commands
5068 with the current item. Thus the current item can be
5069 removed without effect. Removing any later item means
5070 it will not be found. Thus the following example
5071 works (an inefficient way to make a list empty): >
5072 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00005073 :call remove(mylist, 0)
5074 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005075< Note that reordering the list (e.g., with sort() or
5076 reverse()) may have unexpected effects.
5077 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00005078 identical to avoid errors for the type of {var}
5079 changing. Unlet the variable at the end of the loop
5080 to allow multiple item types.
5081
5082:for {var} in {string}
5083:endfo[r] Like ":for" above, but use each character in {string}
5084 as a list item.
5085 Composing characters are used as separate characters.
5086 A Number is first converted to a String.
5087
5088:for [{var1}, {var2}, ...] in {listlist}
5089:endfo[r]
5090 Like ":for" above, but each item in {listlist} must be
5091 a list, of which each item is assigned to {var1},
5092 {var2}, etc. Example: >
5093 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
5094 :echo getline(lnum)[col]
5095 :endfor
5096<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005097 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00005098:con[tinue] When used inside a ":while" or ":for" loop, jumps back
5099 to the start of the loop.
5100 If it is used after a |:try| inside the loop but
5101 before the matching |:finally| (if present), the
5102 commands following the ":finally" up to the matching
5103 |:endtry| are executed first. This process applies to
5104 all nested ":try"s inside the loop. The outermost
5105 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005106
5107 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00005108:brea[k] When used inside a ":while" or ":for" loop, skips to
5109 the command after the matching ":endwhile" or
5110 ":endfor".
5111 If it is used after a |:try| inside the loop but
5112 before the matching |:finally| (if present), the
5113 commands following the ":finally" up to the matching
5114 |:endtry| are executed first. This process applies to
5115 all nested ":try"s inside the loop. The outermost
5116 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005117
5118:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
5119:endt[ry] Change the error handling for the commands between
5120 ":try" and ":endtry" including everything being
5121 executed across ":source" commands, function calls,
5122 or autocommand invocations.
5123
5124 When an error or interrupt is detected and there is
5125 a |:finally| command following, execution continues
5126 after the ":finally". Otherwise, or when the
5127 ":endtry" is reached thereafter, the next
5128 (dynamically) surrounding ":try" is checked for
5129 a corresponding ":finally" etc. Then the script
5130 processing is terminated. (Whether a function
5131 definition has an "abort" argument does not matter.)
5132 Example: >
5133 :try | edit too much | finally | echo "cleanup" | endtry
5134 :echo "impossible" " not reached, script terminated above
5135<
5136 Moreover, an error or interrupt (dynamically) inside
5137 ":try" and ":endtry" is converted to an exception. It
5138 can be caught as if it were thrown by a |:throw|
5139 command (see |:catch|). In this case, the script
5140 processing is not terminated.
5141
5142 The value "Vim:Interrupt" is used for an interrupt
5143 exception. An error in a Vim command is converted
5144 to a value of the form "Vim({command}):{errmsg}",
5145 other errors are converted to a value of the form
5146 "Vim:{errmsg}". {command} is the full command name,
5147 and {errmsg} is the message that is displayed if the
5148 error exception is not caught, always beginning with
5149 the error number.
5150 Examples: >
5151 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
5152 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
5153<
5154 *:cat* *:catch* *E603* *E604* *E605*
5155:cat[ch] /{pattern}/ The following commands until the next ":catch",
5156 |:finally|, or |:endtry| that belongs to the same
5157 |:try| as the ":catch" are executed when an exception
5158 matching {pattern} is being thrown and has not yet
5159 been caught by a previous ":catch". Otherwise, these
5160 commands are skipped.
5161 When {pattern} is omitted all errors are caught.
5162 Examples: >
5163 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
5164 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
5165 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
5166 :catch /^Vim(write):/ " catch all errors in :write
5167 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
5168 :catch /my-exception/ " catch user exception
5169 :catch /.*/ " catch everything
5170 :catch " same as /.*/
5171<
5172 Another character can be used instead of / around the
5173 {pattern}, so long as it does not have a special
5174 meaning (e.g., '|' or '"') and doesn't occur inside
5175 {pattern}.
5176 NOTE: It is not reliable to ":catch" the TEXT of
5177 an error message because it may vary in different
5178 locales.
5179
5180 *:fina* *:finally* *E606* *E607*
5181:fina[lly] The following commands until the matching |:endtry|
5182 are executed whenever the part between the matching
5183 |:try| and the ":finally" is left: either by falling
5184 through to the ":finally" or by a |:continue|,
5185 |:break|, |:finish|, or |:return|, or by an error or
5186 interrupt or exception (see |:throw|).
5187
5188 *:th* *:throw* *E608*
5189:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
5190 If the ":throw" is used after a |:try| but before the
5191 first corresponding |:catch|, commands are skipped
5192 until the first ":catch" matching {expr1} is reached.
5193 If there is no such ":catch" or if the ":throw" is
5194 used after a ":catch" but before the |:finally|, the
5195 commands following the ":finally" (if present) up to
5196 the matching |:endtry| are executed. If the ":throw"
5197 is after the ":finally", commands up to the ":endtry"
5198 are skipped. At the ":endtry", this process applies
5199 again for the next dynamically surrounding ":try"
5200 (which may be found in a calling function or sourcing
5201 script), until a matching ":catch" has been found.
5202 If the exception is not caught, the command processing
5203 is terminated.
5204 Example: >
5205 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
5206<
5207
5208 *:ec* *:echo*
5209:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
5210 first {expr1} starts on a new line.
5211 Also see |:comment|.
5212 Use "\n" to start a new line. Use "\r" to move the
5213 cursor to the first column.
5214 Uses the highlighting set by the |:echohl| command.
5215 Cannot be followed by a comment.
5216 Example: >
5217 :echo "the value of 'shell' is" &shell
5218< A later redraw may make the message disappear again.
5219 To avoid that a command from before the ":echo" causes
5220 a redraw afterwards (redraws are often postponed until
5221 you type something), force a redraw with the |:redraw|
5222 command. Example: >
5223 :new | redraw | echo "there is a new window"
5224<
5225 *:echon*
5226:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
5227 |:comment|.
5228 Uses the highlighting set by the |:echohl| command.
5229 Cannot be followed by a comment.
5230 Example: >
5231 :echon "the value of 'shell' is " &shell
5232<
5233 Note the difference between using ":echo", which is a
5234 Vim command, and ":!echo", which is an external shell
5235 command: >
5236 :!echo % --> filename
5237< The arguments of ":!" are expanded, see |:_%|. >
5238 :!echo "%" --> filename or "filename"
5239< Like the previous example. Whether you see the double
5240 quotes or not depends on your 'shell'. >
5241 :echo % --> nothing
5242< The '%' is an illegal character in an expression. >
5243 :echo "%" --> %
5244< This just echoes the '%' character. >
5245 :echo expand("%") --> filename
5246< This calls the expand() function to expand the '%'.
5247
5248 *:echoh* *:echohl*
5249:echoh[l] {name} Use the highlight group {name} for the following
5250 |:echo|, |:echon| and |:echomsg| commands. Also used
5251 for the |input()| prompt. Example: >
5252 :echohl WarningMsg | echo "Don't panic!" | echohl None
5253< Don't forget to set the group back to "None",
5254 otherwise all following echo's will be highlighted.
5255
5256 *:echom* *:echomsg*
5257:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
5258 message in the |message-history|.
5259 Spaces are placed between the arguments as with the
5260 |:echo| command. But unprintable characters are
5261 displayed, not interpreted.
5262 Uses the highlighting set by the |:echohl| command.
5263 Example: >
5264 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
5265<
5266 *:echoe* *:echoerr*
5267:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
5268 message in the |message-history|. When used in a
5269 script or function the line number will be added.
5270 Spaces are placed between the arguments as with the
5271 :echo command. When used inside a try conditional,
5272 the message is raised as an error exception instead
5273 (see |try-echoerr|).
5274 Example: >
5275 :echoerr "This script just failed!"
5276< If you just want a highlighted message use |:echohl|.
5277 And to get a beep: >
5278 :exe "normal \<Esc>"
5279<
5280 *:exe* *:execute*
5281:exe[cute] {expr1} .. Executes the string that results from the evaluation
5282 of {expr1} as an Ex command. Multiple arguments are
5283 concatenated, with a space in between. {expr1} is
5284 used as the processed command, command line editing
5285 keys are not recognized.
5286 Cannot be followed by a comment.
5287 Examples: >
5288 :execute "buffer " nextbuf
5289 :execute "normal " count . "w"
5290<
5291 ":execute" can be used to append a command to commands
5292 that don't accept a '|'. Example: >
5293 :execute '!ls' | echo "theend"
5294
5295< ":execute" is also a nice way to avoid having to type
5296 control characters in a Vim script for a ":normal"
5297 command: >
5298 :execute "normal ixxx\<Esc>"
5299< This has an <Esc> character, see |expr-string|.
5300
5301 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00005302 you cannot start or end a "while", "for" or "if"
5303 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005304 :execute 'while i > 5'
5305 :execute 'echo "test" | break'
5306<
5307 It is allowed to have a "while" or "if" command
5308 completely in the executed string: >
5309 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
5310<
5311
5312 *:comment*
5313 ":execute", ":echo" and ":echon" cannot be followed by
5314 a comment directly, because they see the '"' as the
5315 start of a string. But, you can use '|' followed by a
5316 comment. Example: >
5317 :echo "foo" | "this is a comment
5318
5319==============================================================================
53208. Exception handling *exception-handling*
5321
5322The Vim script language comprises an exception handling feature. This section
5323explains how it can be used in a Vim script.
5324
5325Exceptions may be raised by Vim on an error or on interrupt, see
5326|catch-errors| and |catch-interrupt|. You can also explicitly throw an
5327exception by using the ":throw" command, see |throw-catch|.
5328
5329
5330TRY CONDITIONALS *try-conditionals*
5331
5332Exceptions can be caught or can cause cleanup code to be executed. You can
5333use a try conditional to specify catch clauses (that catch exceptions) and/or
5334a finally clause (to be executed for cleanup).
5335 A try conditional begins with a |:try| command and ends at the matching
5336|:endtry| command. In between, you can use a |:catch| command to start
5337a catch clause, or a |:finally| command to start a finally clause. There may
5338be none or multiple catch clauses, but there is at most one finally clause,
5339which must not be followed by any catch clauses. The lines before the catch
5340clauses and the finally clause is called a try block. >
5341
5342 :try
5343 : ...
5344 : ... TRY BLOCK
5345 : ...
5346 :catch /{pattern}/
5347 : ...
5348 : ... CATCH CLAUSE
5349 : ...
5350 :catch /{pattern}/
5351 : ...
5352 : ... CATCH CLAUSE
5353 : ...
5354 :finally
5355 : ...
5356 : ... FINALLY CLAUSE
5357 : ...
5358 :endtry
5359
5360The try conditional allows to watch code for exceptions and to take the
5361appropriate actions. Exceptions from the try block may be caught. Exceptions
5362from the try block and also the catch clauses may cause cleanup actions.
5363 When no exception is thrown during execution of the try block, the control
5364is transferred to the finally clause, if present. After its execution, the
5365script continues with the line following the ":endtry".
5366 When an exception occurs during execution of the try block, the remaining
5367lines in the try block are skipped. The exception is matched against the
5368patterns specified as arguments to the ":catch" commands. The catch clause
5369after the first matching ":catch" is taken, other catch clauses are not
5370executed. The catch clause ends when the next ":catch", ":finally", or
5371":endtry" command is reached - whatever is first. Then, the finally clause
5372(if present) is executed. When the ":endtry" is reached, the script execution
5373continues in the following line as usual.
5374 When an exception that does not match any of the patterns specified by the
5375":catch" commands is thrown in the try block, the exception is not caught by
5376that try conditional and none of the catch clauses is executed. Only the
5377finally clause, if present, is taken. The exception pends during execution of
5378the finally clause. It is resumed at the ":endtry", so that commands after
5379the ":endtry" are not executed and the exception might be caught elsewhere,
5380see |try-nesting|.
5381 When during execution of a catch clause another exception is thrown, the
5382remaining lines in that catch clause are not executed. The new exception is
5383not matched against the patterns in any of the ":catch" commands of the same
5384try conditional and none of its catch clauses is taken. If there is, however,
5385a finally clause, it is executed, and the exception pends during its
5386execution. The commands following the ":endtry" are not executed. The new
5387exception might, however, be caught elsewhere, see |try-nesting|.
5388 When during execution of the finally clause (if present) an exception is
5389thrown, the remaining lines in the finally clause are skipped. If the finally
5390clause has been taken because of an exception from the try block or one of the
5391catch clauses, the original (pending) exception is discarded. The commands
5392following the ":endtry" are not executed, and the exception from the finally
5393clause is propagated and can be caught elsewhere, see |try-nesting|.
5394
5395The finally clause is also executed, when a ":break" or ":continue" for
5396a ":while" loop enclosing the complete try conditional is executed from the
5397try block or a catch clause. Or when a ":return" or ":finish" is executed
5398from the try block or a catch clause of a try conditional in a function or
5399sourced script, respectively. The ":break", ":continue", ":return", or
5400":finish" pends during execution of the finally clause and is resumed when the
5401":endtry" is reached. It is, however, discarded when an exception is thrown
5402from the finally clause.
5403 When a ":break" or ":continue" for a ":while" loop enclosing the complete
5404try conditional or when a ":return" or ":finish" is encountered in the finally
5405clause, the rest of the finally clause is skipped, and the ":break",
5406":continue", ":return" or ":finish" is executed as usual. If the finally
5407clause has been taken because of an exception or an earlier ":break",
5408":continue", ":return", or ":finish" from the try block or a catch clause,
5409this pending exception or command is discarded.
5410
5411For examples see |throw-catch| and |try-finally|.
5412
5413
5414NESTING OF TRY CONDITIONALS *try-nesting*
5415
5416Try conditionals can be nested arbitrarily. That is, a complete try
5417conditional can be put into the try block, a catch clause, or the finally
5418clause of another try conditional. If the inner try conditional does not
5419catch an exception thrown in its try block or throws a new exception from one
5420of its catch clauses or its finally clause, the outer try conditional is
5421checked according to the rules above. If the inner try conditional is in the
5422try block of the outer try conditional, its catch clauses are checked, but
5423otherwise only the finally clause is executed. It does not matter for
5424nesting, whether the inner try conditional is directly contained in the outer
5425one, or whether the outer one sources a script or calls a function containing
5426the inner try conditional.
5427
5428When none of the active try conditionals catches an exception, just their
5429finally clauses are executed. Thereafter, the script processing terminates.
5430An error message is displayed in case of an uncaught exception explicitly
5431thrown by a ":throw" command. For uncaught error and interrupt exceptions
5432implicitly raised by Vim, the error message(s) or interrupt message are shown
5433as usual.
5434
5435For examples see |throw-catch|.
5436
5437
5438EXAMINING EXCEPTION HANDLING CODE *except-examine*
5439
5440Exception handling code can get tricky. If you are in doubt what happens, set
5441'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
5442script file. Then you see when an exception is thrown, discarded, caught, or
5443finished. When using a verbosity level of at least 14, things pending in
5444a finally clause are also shown. This information is also given in debug mode
5445(see |debug-scripts|).
5446
5447
5448THROWING AND CATCHING EXCEPTIONS *throw-catch*
5449
5450You can throw any number or string as an exception. Use the |:throw| command
5451and pass the value to be thrown as argument: >
5452 :throw 4711
5453 :throw "string"
5454< *throw-expression*
5455You can also specify an expression argument. The expression is then evaluated
5456first, and the result is thrown: >
5457 :throw 4705 + strlen("string")
5458 :throw strpart("strings", 0, 6)
5459
5460An exception might be thrown during evaluation of the argument of the ":throw"
5461command. Unless it is caught there, the expression evaluation is abandoned.
5462The ":throw" command then does not throw a new exception.
5463 Example: >
5464
5465 :function! Foo(arg)
5466 : try
5467 : throw a:arg
5468 : catch /foo/
5469 : endtry
5470 : return 1
5471 :endfunction
5472 :
5473 :function! Bar()
5474 : echo "in Bar"
5475 : return 4710
5476 :endfunction
5477 :
5478 :throw Foo("arrgh") + Bar()
5479
5480This throws "arrgh", and "in Bar" is not displayed since Bar() is not
5481executed. >
5482 :throw Foo("foo") + Bar()
5483however displays "in Bar" and throws 4711.
5484
5485Any other command that takes an expression as argument might also be
5486abandoned by an (uncaught) exception during the expression evaluation. The
5487exception is then propagated to the caller of the command.
5488 Example: >
5489
5490 :if Foo("arrgh")
5491 : echo "then"
5492 :else
5493 : echo "else"
5494 :endif
5495
5496Here neither of "then" or "else" is displayed.
5497
5498 *catch-order*
5499Exceptions can be caught by a try conditional with one or more |:catch|
5500commands, see |try-conditionals|. The values to be caught by each ":catch"
5501command can be specified as a pattern argument. The subsequent catch clause
5502gets executed when a matching exception is caught.
5503 Example: >
5504
5505 :function! Foo(value)
5506 : try
5507 : throw a:value
5508 : catch /^\d\+$/
5509 : echo "Number thrown"
5510 : catch /.*/
5511 : echo "String thrown"
5512 : endtry
5513 :endfunction
5514 :
5515 :call Foo(0x1267)
5516 :call Foo('string')
5517
5518The first call to Foo() displays "Number thrown", the second "String thrown".
5519An exception is matched against the ":catch" commands in the order they are
5520specified. Only the first match counts. So you should place the more
5521specific ":catch" first. The following order does not make sense: >
5522
5523 : catch /.*/
5524 : echo "String thrown"
5525 : catch /^\d\+$/
5526 : echo "Number thrown"
5527
5528The first ":catch" here matches always, so that the second catch clause is
5529never taken.
5530
5531 *throw-variables*
5532If you catch an exception by a general pattern, you may access the exact value
5533in the variable |v:exception|: >
5534
5535 : catch /^\d\+$/
5536 : echo "Number thrown. Value is" v:exception
5537
5538You may also be interested where an exception was thrown. This is stored in
5539|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
5540exception most recently caught as long it is not finished.
5541 Example: >
5542
5543 :function! Caught()
5544 : if v:exception != ""
5545 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
5546 : else
5547 : echo 'Nothing caught'
5548 : endif
5549 :endfunction
5550 :
5551 :function! Foo()
5552 : try
5553 : try
5554 : try
5555 : throw 4711
5556 : finally
5557 : call Caught()
5558 : endtry
5559 : catch /.*/
5560 : call Caught()
5561 : throw "oops"
5562 : endtry
5563 : catch /.*/
5564 : call Caught()
5565 : finally
5566 : call Caught()
5567 : endtry
5568 :endfunction
5569 :
5570 :call Foo()
5571
5572This displays >
5573
5574 Nothing caught
5575 Caught "4711" in function Foo, line 4
5576 Caught "oops" in function Foo, line 10
5577 Nothing caught
5578
5579A practical example: The following command ":LineNumber" displays the line
5580number in the script or function where it has been used: >
5581
5582 :function! LineNumber()
5583 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
5584 :endfunction
5585 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
5586<
5587 *try-nested*
5588An exception that is not caught by a try conditional can be caught by
5589a surrounding try conditional: >
5590
5591 :try
5592 : try
5593 : throw "foo"
5594 : catch /foobar/
5595 : echo "foobar"
5596 : finally
5597 : echo "inner finally"
5598 : endtry
5599 :catch /foo/
5600 : echo "foo"
5601 :endtry
5602
5603The inner try conditional does not catch the exception, just its finally
5604clause is executed. The exception is then caught by the outer try
5605conditional. The example displays "inner finally" and then "foo".
5606
5607 *throw-from-catch*
5608You can catch an exception and throw a new one to be caught elsewhere from the
5609catch clause: >
5610
5611 :function! Foo()
5612 : throw "foo"
5613 :endfunction
5614 :
5615 :function! Bar()
5616 : try
5617 : call Foo()
5618 : catch /foo/
5619 : echo "Caught foo, throw bar"
5620 : throw "bar"
5621 : endtry
5622 :endfunction
5623 :
5624 :try
5625 : call Bar()
5626 :catch /.*/
5627 : echo "Caught" v:exception
5628 :endtry
5629
5630This displays "Caught foo, throw bar" and then "Caught bar".
5631
5632 *rethrow*
5633There is no real rethrow in the Vim script language, but you may throw
5634"v:exception" instead: >
5635
5636 :function! Bar()
5637 : try
5638 : call Foo()
5639 : catch /.*/
5640 : echo "Rethrow" v:exception
5641 : throw v:exception
5642 : endtry
5643 :endfunction
5644< *try-echoerr*
5645Note that this method cannot be used to "rethrow" Vim error or interrupt
5646exceptions, because it is not possible to fake Vim internal exceptions.
5647Trying so causes an error exception. You should throw your own exception
5648denoting the situation. If you want to cause a Vim error exception containing
5649the original error exception value, you can use the |:echoerr| command: >
5650
5651 :try
5652 : try
5653 : asdf
5654 : catch /.*/
5655 : echoerr v:exception
5656 : endtry
5657 :catch /.*/
5658 : echo v:exception
5659 :endtry
5660
5661This code displays
5662
5663 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
5664
5665
5666CLEANUP CODE *try-finally*
5667
5668Scripts often change global settings and restore them at their end. If the
5669user however interrupts the script by pressing CTRL-C, the settings remain in
5670an inconsistent state. The same may happen to you in the development phase of
5671a script when an error occurs or you explicitly throw an exception without
5672catching it. You can solve these problems by using a try conditional with
5673a finally clause for restoring the settings. Its execution is guaranteed on
5674normal control flow, on error, on an explicit ":throw", and on interrupt.
5675(Note that errors and interrupts from inside the try conditional are converted
5676to exceptions. When not caught, they terminate the script after the finally
5677clause has been executed.)
5678Example: >
5679
5680 :try
5681 : let s:saved_ts = &ts
5682 : set ts=17
5683 :
5684 : " Do the hard work here.
5685 :
5686 :finally
5687 : let &ts = s:saved_ts
5688 : unlet s:saved_ts
5689 :endtry
5690
5691This method should be used locally whenever a function or part of a script
5692changes global settings which need to be restored on failure or normal exit of
5693that function or script part.
5694
5695 *break-finally*
5696Cleanup code works also when the try block or a catch clause is left by
5697a ":continue", ":break", ":return", or ":finish".
5698 Example: >
5699
5700 :let first = 1
5701 :while 1
5702 : try
5703 : if first
5704 : echo "first"
5705 : let first = 0
5706 : continue
5707 : else
5708 : throw "second"
5709 : endif
5710 : catch /.*/
5711 : echo v:exception
5712 : break
5713 : finally
5714 : echo "cleanup"
5715 : endtry
5716 : echo "still in while"
5717 :endwhile
5718 :echo "end"
5719
5720This displays "first", "cleanup", "second", "cleanup", and "end". >
5721
5722 :function! Foo()
5723 : try
5724 : return 4711
5725 : finally
5726 : echo "cleanup\n"
5727 : endtry
5728 : echo "Foo still active"
5729 :endfunction
5730 :
5731 :echo Foo() "returned by Foo"
5732
5733This displays "cleanup" and "4711 returned by Foo". You don't need to add an
5734extra ":return" in the finally clause. (Above all, this would override the
5735return value.)
5736
5737 *except-from-finally*
5738Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
5739a finally clause is possible, but not recommended since it abandons the
5740cleanup actions for the try conditional. But, of course, interrupt and error
5741exceptions might get raised from a finally clause.
5742 Example where an error in the finally clause stops an interrupt from
5743working correctly: >
5744
5745 :try
5746 : try
5747 : echo "Press CTRL-C for interrupt"
5748 : while 1
5749 : endwhile
5750 : finally
5751 : unlet novar
5752 : endtry
5753 :catch /novar/
5754 :endtry
5755 :echo "Script still running"
5756 :sleep 1
5757
5758If you need to put commands that could fail into a finally clause, you should
5759think about catching or ignoring the errors in these commands, see
5760|catch-errors| and |ignore-errors|.
5761
5762
5763CATCHING ERRORS *catch-errors*
5764
5765If you want to catch specific errors, you just have to put the code to be
5766watched in a try block and add a catch clause for the error message. The
5767presence of the try conditional causes all errors to be converted to an
5768exception. No message is displayed and |v:errmsg| is not set then. To find
5769the right pattern for the ":catch" command, you have to know how the format of
5770the error exception is.
5771 Error exceptions have the following format: >
5772
5773 Vim({cmdname}):{errmsg}
5774or >
5775 Vim:{errmsg}
5776
5777{cmdname} is the name of the command that failed; the second form is used when
5778the command name is not known. {errmsg} is the error message usually produced
5779when the error occurs outside try conditionals. It always begins with
5780a capital "E", followed by a two or three-digit error number, a colon, and
5781a space.
5782
5783Examples:
5784
5785The command >
5786 :unlet novar
5787normally produces the error message >
5788 E108: No such variable: "novar"
5789which is converted inside try conditionals to an exception >
5790 Vim(unlet):E108: No such variable: "novar"
5791
5792The command >
5793 :dwim
5794normally produces the error message >
5795 E492: Not an editor command: dwim
5796which is converted inside try conditionals to an exception >
5797 Vim:E492: Not an editor command: dwim
5798
5799You can catch all ":unlet" errors by a >
5800 :catch /^Vim(unlet):/
5801or all errors for misspelled command names by a >
5802 :catch /^Vim:E492:/
5803
5804Some error messages may be produced by different commands: >
5805 :function nofunc
5806and >
5807 :delfunction nofunc
5808both produce the error message >
5809 E128: Function name must start with a capital: nofunc
5810which is converted inside try conditionals to an exception >
5811 Vim(function):E128: Function name must start with a capital: nofunc
5812or >
5813 Vim(delfunction):E128: Function name must start with a capital: nofunc
5814respectively. You can catch the error by its number independently on the
5815command that caused it if you use the following pattern: >
5816 :catch /^Vim(\a\+):E128:/
5817
5818Some commands like >
5819 :let x = novar
5820produce multiple error messages, here: >
5821 E121: Undefined variable: novar
5822 E15: Invalid expression: novar
5823Only the first is used for the exception value, since it is the most specific
5824one (see |except-several-errors|). So you can catch it by >
5825 :catch /^Vim(\a\+):E121:/
5826
5827You can catch all errors related to the name "nofunc" by >
5828 :catch /\<nofunc\>/
5829
5830You can catch all Vim errors in the ":write" and ":read" commands by >
5831 :catch /^Vim(\(write\|read\)):E\d\+:/
5832
5833You can catch all Vim errors by the pattern >
5834 :catch /^Vim\((\a\+)\)\=:E\d\+:/
5835<
5836 *catch-text*
5837NOTE: You should never catch the error message text itself: >
5838 :catch /No such variable/
5839only works in the english locale, but not when the user has selected
5840a different language by the |:language| command. It is however helpful to
5841cite the message text in a comment: >
5842 :catch /^Vim(\a\+):E108:/ " No such variable
5843
5844
5845IGNORING ERRORS *ignore-errors*
5846
5847You can ignore errors in a specific Vim command by catching them locally: >
5848
5849 :try
5850 : write
5851 :catch
5852 :endtry
5853
5854But you are strongly recommended NOT to use this simple form, since it could
5855catch more than you want. With the ":write" command, some autocommands could
5856be executed and cause errors not related to writing, for instance: >
5857
5858 :au BufWritePre * unlet novar
5859
5860There could even be such errors you are not responsible for as a script
5861writer: a user of your script might have defined such autocommands. You would
5862then hide the error from the user.
5863 It is much better to use >
5864
5865 :try
5866 : write
5867 :catch /^Vim(write):/
5868 :endtry
5869
5870which only catches real write errors. So catch only what you'd like to ignore
5871intentionally.
5872
5873For a single command that does not cause execution of autocommands, you could
5874even suppress the conversion of errors to exceptions by the ":silent!"
5875command: >
5876 :silent! nunmap k
5877This works also when a try conditional is active.
5878
5879
5880CATCHING INTERRUPTS *catch-interrupt*
5881
5882When there are active try conditionals, an interrupt (CTRL-C) is converted to
5883the exception "Vim:Interrupt". You can catch it like every exception. The
5884script is not terminated, then.
5885 Example: >
5886
5887 :function! TASK1()
5888 : sleep 10
5889 :endfunction
5890
5891 :function! TASK2()
5892 : sleep 20
5893 :endfunction
5894
5895 :while 1
5896 : let command = input("Type a command: ")
5897 : try
5898 : if command == ""
5899 : continue
5900 : elseif command == "END"
5901 : break
5902 : elseif command == "TASK1"
5903 : call TASK1()
5904 : elseif command == "TASK2"
5905 : call TASK2()
5906 : else
5907 : echo "\nIllegal command:" command
5908 : continue
5909 : endif
5910 : catch /^Vim:Interrupt$/
5911 : echo "\nCommand interrupted"
5912 : " Caught the interrupt. Continue with next prompt.
5913 : endtry
5914 :endwhile
5915
5916You can interrupt a task here by pressing CTRL-C; the script then asks for
5917a new command. If you press CTRL-C at the prompt, the script is terminated.
5918
5919For testing what happens when CTRL-C would be pressed on a specific line in
5920your script, use the debug mode and execute the |>quit| or |>interrupt|
5921command on that line. See |debug-scripts|.
5922
5923
5924CATCHING ALL *catch-all*
5925
5926The commands >
5927
5928 :catch /.*/
5929 :catch //
5930 :catch
5931
5932catch everything, error exceptions, interrupt exceptions and exceptions
5933explicitly thrown by the |:throw| command. This is useful at the top level of
5934a script in order to catch unexpected things.
5935 Example: >
5936
5937 :try
5938 :
5939 : " do the hard work here
5940 :
5941 :catch /MyException/
5942 :
5943 : " handle known problem
5944 :
5945 :catch /^Vim:Interrupt$/
5946 : echo "Script interrupted"
5947 :catch /.*/
5948 : echo "Internal error (" . v:exception . ")"
5949 : echo " - occurred at " . v:throwpoint
5950 :endtry
5951 :" end of script
5952
5953Note: Catching all might catch more things than you want. Thus, you are
5954strongly encouraged to catch only for problems that you can really handle by
5955specifying a pattern argument to the ":catch".
5956 Example: Catching all could make it nearly impossible to interrupt a script
5957by pressing CTRL-C: >
5958
5959 :while 1
5960 : try
5961 : sleep 1
5962 : catch
5963 : endtry
5964 :endwhile
5965
5966
5967EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
5968
5969Exceptions may be used during execution of autocommands. Example: >
5970
5971 :autocmd User x try
5972 :autocmd User x throw "Oops!"
5973 :autocmd User x catch
5974 :autocmd User x echo v:exception
5975 :autocmd User x endtry
5976 :autocmd User x throw "Arrgh!"
5977 :autocmd User x echo "Should not be displayed"
5978 :
5979 :try
5980 : doautocmd User x
5981 :catch
5982 : echo v:exception
5983 :endtry
5984
5985This displays "Oops!" and "Arrgh!".
5986
5987 *except-autocmd-Pre*
5988For some commands, autocommands get executed before the main action of the
5989command takes place. If an exception is thrown and not caught in the sequence
5990of autocommands, the sequence and the command that caused its execution are
5991abandoned and the exception is propagated to the caller of the command.
5992 Example: >
5993
5994 :autocmd BufWritePre * throw "FAIL"
5995 :autocmd BufWritePre * echo "Should not be displayed"
5996 :
5997 :try
5998 : write
5999 :catch
6000 : echo "Caught:" v:exception "from" v:throwpoint
6001 :endtry
6002
6003Here, the ":write" command does not write the file currently being edited (as
6004you can see by checking 'modified'), since the exception from the BufWritePre
6005autocommand abandons the ":write". The exception is then caught and the
6006script displays: >
6007
6008 Caught: FAIL from BufWrite Auto commands for "*"
6009<
6010 *except-autocmd-Post*
6011For some commands, autocommands get executed after the main action of the
6012command has taken place. If this main action fails and the command is inside
6013an active try conditional, the autocommands are skipped and an error exception
6014is thrown that can be caught by the caller of the command.
6015 Example: >
6016
6017 :autocmd BufWritePost * echo "File successfully written!"
6018 :
6019 :try
6020 : write /i/m/p/o/s/s/i/b/l/e
6021 :catch
6022 : echo v:exception
6023 :endtry
6024
6025This just displays: >
6026
6027 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
6028
6029If you really need to execute the autocommands even when the main action
6030fails, trigger the event from the catch clause.
6031 Example: >
6032
6033 :autocmd BufWritePre * set noreadonly
6034 :autocmd BufWritePost * set readonly
6035 :
6036 :try
6037 : write /i/m/p/o/s/s/i/b/l/e
6038 :catch
6039 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
6040 :endtry
6041<
6042You can also use ":silent!": >
6043
6044 :let x = "ok"
6045 :let v:errmsg = ""
6046 :autocmd BufWritePost * if v:errmsg != ""
6047 :autocmd BufWritePost * let x = "after fail"
6048 :autocmd BufWritePost * endif
6049 :try
6050 : silent! write /i/m/p/o/s/s/i/b/l/e
6051 :catch
6052 :endtry
6053 :echo x
6054
6055This displays "after fail".
6056
6057If the main action of the command does not fail, exceptions from the
6058autocommands will be catchable by the caller of the command: >
6059
6060 :autocmd BufWritePost * throw ":-("
6061 :autocmd BufWritePost * echo "Should not be displayed"
6062 :
6063 :try
6064 : write
6065 :catch
6066 : echo v:exception
6067 :endtry
6068<
6069 *except-autocmd-Cmd*
6070For some commands, the normal action can be replaced by a sequence of
6071autocommands. Exceptions from that sequence will be catchable by the caller
6072of the command.
6073 Example: For the ":write" command, the caller cannot know whether the file
6074had actually been written when the exception occurred. You need to tell it in
6075some way. >
6076
6077 :if !exists("cnt")
6078 : let cnt = 0
6079 :
6080 : autocmd BufWriteCmd * if &modified
6081 : autocmd BufWriteCmd * let cnt = cnt + 1
6082 : autocmd BufWriteCmd * if cnt % 3 == 2
6083 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6084 : autocmd BufWriteCmd * endif
6085 : autocmd BufWriteCmd * write | set nomodified
6086 : autocmd BufWriteCmd * if cnt % 3 == 0
6087 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6088 : autocmd BufWriteCmd * endif
6089 : autocmd BufWriteCmd * echo "File successfully written!"
6090 : autocmd BufWriteCmd * endif
6091 :endif
6092 :
6093 :try
6094 : write
6095 :catch /^BufWriteCmdError$/
6096 : if &modified
6097 : echo "Error on writing (file contents not changed)"
6098 : else
6099 : echo "Error after writing"
6100 : endif
6101 :catch /^Vim(write):/
6102 : echo "Error on writing"
6103 :endtry
6104
6105When this script is sourced several times after making changes, it displays
6106first >
6107 File successfully written!
6108then >
6109 Error on writing (file contents not changed)
6110then >
6111 Error after writing
6112etc.
6113
6114 *except-autocmd-ill*
6115You cannot spread a try conditional over autocommands for different events.
6116The following code is ill-formed: >
6117
6118 :autocmd BufWritePre * try
6119 :
6120 :autocmd BufWritePost * catch
6121 :autocmd BufWritePost * echo v:exception
6122 :autocmd BufWritePost * endtry
6123 :
6124 :write
6125
6126
6127EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
6128
6129Some programming languages allow to use hierarchies of exception classes or to
6130pass additional information with the object of an exception class. You can do
6131similar things in Vim.
6132 In order to throw an exception from a hierarchy, just throw the complete
6133class name with the components separated by a colon, for instance throw the
6134string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
6135 When you want to pass additional information with your exception class, add
6136it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
6137for an error when writing "myfile".
6138 With the appropriate patterns in the ":catch" command, you can catch for
6139base classes or derived classes of your hierarchy. Additional information in
6140parentheses can be cut out from |v:exception| with the ":substitute" command.
6141 Example: >
6142
6143 :function! CheckRange(a, func)
6144 : if a:a < 0
6145 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
6146 : endif
6147 :endfunction
6148 :
6149 :function! Add(a, b)
6150 : call CheckRange(a:a, "Add")
6151 : call CheckRange(a:b, "Add")
6152 : let c = a:a + a:b
6153 : if c < 0
6154 : throw "EXCEPT:MATHERR:OVERFLOW"
6155 : endif
6156 : return c
6157 :endfunction
6158 :
6159 :function! Div(a, b)
6160 : call CheckRange(a:a, "Div")
6161 : call CheckRange(a:b, "Div")
6162 : if (a:b == 0)
6163 : throw "EXCEPT:MATHERR:ZERODIV"
6164 : endif
6165 : return a:a / a:b
6166 :endfunction
6167 :
6168 :function! Write(file)
6169 : try
6170 : execute "write" a:file
6171 : catch /^Vim(write):/
6172 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
6173 : endtry
6174 :endfunction
6175 :
6176 :try
6177 :
6178 : " something with arithmetics and I/O
6179 :
6180 :catch /^EXCEPT:MATHERR:RANGE/
6181 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
6182 : echo "Range error in" function
6183 :
6184 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
6185 : echo "Math error"
6186 :
6187 :catch /^EXCEPT:IO/
6188 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
6189 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
6190 : if file !~ '^/'
6191 : let file = dir . "/" . file
6192 : endif
6193 : echo 'I/O error for "' . file . '"'
6194 :
6195 :catch /^EXCEPT/
6196 : echo "Unspecified error"
6197 :
6198 :endtry
6199
6200The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
6201a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
6202exceptions with the "Vim" prefix; they are reserved for Vim.
6203 Vim error exceptions are parameterized with the name of the command that
6204failed, if known. See |catch-errors|.
6205
6206
6207PECULIARITIES
6208 *except-compat*
6209The exception handling concept requires that the command sequence causing the
6210exception is aborted immediately and control is transferred to finally clauses
6211and/or a catch clause.
6212
6213In the Vim script language there are cases where scripts and functions
6214continue after an error: in functions without the "abort" flag or in a command
6215after ":silent!", control flow goes to the following line, and outside
6216functions, control flow goes to the line following the outermost ":endwhile"
6217or ":endif". On the other hand, errors should be catchable as exceptions
6218(thus, requiring the immediate abortion).
6219
6220This problem has been solved by converting errors to exceptions and using
6221immediate abortion (if not suppressed by ":silent!") only when a try
6222conditional is active. This is no restriction since an (error) exception can
6223be caught only from an active try conditional. If you want an immediate
6224termination without catching the error, just use a try conditional without
6225catch clause. (You can cause cleanup code being executed before termination
6226by specifying a finally clause.)
6227
6228When no try conditional is active, the usual abortion and continuation
6229behavior is used instead of immediate abortion. This ensures compatibility of
6230scripts written for Vim 6.1 and earlier.
6231
6232However, when sourcing an existing script that does not use exception handling
6233commands (or when calling one of its functions) from inside an active try
6234conditional of a new script, you might change the control flow of the existing
6235script on error. You get the immediate abortion on error and can catch the
6236error in the new script. If however the sourced script suppresses error
6237messages by using the ":silent!" command (checking for errors by testing
6238|v:errmsg| if appropriate), its execution path is not changed. The error is
6239not converted to an exception. (See |:silent|.) So the only remaining cause
6240where this happens is for scripts that don't care about errors and produce
6241error messages. You probably won't want to use such code from your new
6242scripts.
6243
6244 *except-syntax-err*
6245Syntax errors in the exception handling commands are never caught by any of
6246the ":catch" commands of the try conditional they belong to. Its finally
6247clauses, however, is executed.
6248 Example: >
6249
6250 :try
6251 : try
6252 : throw 4711
6253 : catch /\(/
6254 : echo "in catch with syntax error"
6255 : catch
6256 : echo "inner catch-all"
6257 : finally
6258 : echo "inner finally"
6259 : endtry
6260 :catch
6261 : echo 'outer catch-all caught "' . v:exception . '"'
6262 : finally
6263 : echo "outer finally"
6264 :endtry
6265
6266This displays: >
6267 inner finally
6268 outer catch-all caught "Vim(catch):E54: Unmatched \("
6269 outer finally
6270The original exception is discarded and an error exception is raised, instead.
6271
6272 *except-single-line*
6273The ":try", ":catch", ":finally", and ":endtry" commands can be put on
6274a single line, but then syntax errors may make it difficult to recognize the
6275"catch" line, thus you better avoid this.
6276 Example: >
6277 :try | unlet! foo # | catch | endtry
6278raises an error exception for the trailing characters after the ":unlet!"
6279argument, but does not see the ":catch" and ":endtry" commands, so that the
6280error exception is discarded and the "E488: Trailing characters" message gets
6281displayed.
6282
6283 *except-several-errors*
6284When several errors appear in a single command, the first error message is
6285usually the most specific one and therefor converted to the error exception.
6286 Example: >
6287 echo novar
6288causes >
6289 E121: Undefined variable: novar
6290 E15: Invalid expression: novar
6291The value of the error exception inside try conditionals is: >
6292 Vim(echo):E121: Undefined variable: novar
6293< *except-syntax-error*
6294But when a syntax error is detected after a normal error in the same command,
6295the syntax error is used for the exception being thrown.
6296 Example: >
6297 unlet novar #
6298causes >
6299 E108: No such variable: "novar"
6300 E488: Trailing characters
6301The value of the error exception inside try conditionals is: >
6302 Vim(unlet):E488: Trailing characters
6303This is done because the syntax error might change the execution path in a way
6304not intended by the user. Example: >
6305 try
6306 try | unlet novar # | catch | echo v:exception | endtry
6307 catch /.*/
6308 echo "outer catch:" v:exception
6309 endtry
6310This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
6311a "E600: Missing :endtry" error message is given, see |except-single-line|.
6312
6313==============================================================================
63149. Examples *eval-examples*
6315
6316Printing in Hex ~
6317>
6318 :" The function Nr2Hex() returns the Hex string of a number.
6319 :func Nr2Hex(nr)
6320 : let n = a:nr
6321 : let r = ""
6322 : while n
6323 : let r = '0123456789ABCDEF'[n % 16] . r
6324 : let n = n / 16
6325 : endwhile
6326 : return r
6327 :endfunc
6328
6329 :" The function String2Hex() converts each character in a string to a two
6330 :" character Hex string.
6331 :func String2Hex(str)
6332 : let out = ''
6333 : let ix = 0
6334 : while ix < strlen(a:str)
6335 : let out = out . Nr2Hex(char2nr(a:str[ix]))
6336 : let ix = ix + 1
6337 : endwhile
6338 : return out
6339 :endfunc
6340
6341Example of its use: >
6342 :echo Nr2Hex(32)
6343result: "20" >
6344 :echo String2Hex("32")
6345result: "3332"
6346
6347
6348Sorting lines (by Robert Webb) ~
6349
6350Here is a Vim script to sort lines. Highlight the lines in Vim and type
6351":Sort". This doesn't call any external programs so it'll work on any
6352platform. The function Sort() actually takes the name of a comparison
6353function as its argument, like qsort() does in C. So you could supply it
6354with different comparison functions in order to sort according to date etc.
6355>
6356 :" Function for use with Sort(), to compare two strings.
6357 :func! Strcmp(str1, str2)
6358 : if (a:str1 < a:str2)
6359 : return -1
6360 : elseif (a:str1 > a:str2)
6361 : return 1
6362 : else
6363 : return 0
6364 : endif
6365 :endfunction
6366
6367 :" Sort lines. SortR() is called recursively.
6368 :func! SortR(start, end, cmp)
6369 : if (a:start >= a:end)
6370 : return
6371 : endif
6372 : let partition = a:start - 1
6373 : let middle = partition
6374 : let partStr = getline((a:start + a:end) / 2)
6375 : let i = a:start
6376 : while (i <= a:end)
6377 : let str = getline(i)
6378 : exec "let result = " . a:cmp . "(str, partStr)"
6379 : if (result <= 0)
6380 : " Need to put it before the partition. Swap lines i and partition.
6381 : let partition = partition + 1
6382 : if (result == 0)
6383 : let middle = partition
6384 : endif
6385 : if (i != partition)
6386 : let str2 = getline(partition)
6387 : call setline(i, str2)
6388 : call setline(partition, str)
6389 : endif
6390 : endif
6391 : let i = i + 1
6392 : endwhile
6393
6394 : " Now we have a pointer to the "middle" element, as far as partitioning
6395 : " goes, which could be anywhere before the partition. Make sure it is at
6396 : " the end of the partition.
6397 : if (middle != partition)
6398 : let str = getline(middle)
6399 : let str2 = getline(partition)
6400 : call setline(middle, str2)
6401 : call setline(partition, str)
6402 : endif
6403 : call SortR(a:start, partition - 1, a:cmp)
6404 : call SortR(partition + 1, a:end, a:cmp)
6405 :endfunc
6406
6407 :" To Sort a range of lines, pass the range to Sort() along with the name of a
6408 :" function that will compare two lines.
6409 :func! Sort(cmp) range
6410 : call SortR(a:firstline, a:lastline, a:cmp)
6411 :endfunc
6412
6413 :" :Sort takes a range of lines and sorts them.
6414 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
6415<
6416 *sscanf*
6417There is no sscanf() function in Vim. If you need to extract parts from a
6418line, you can use matchstr() and substitute() to do it. This example shows
6419how to get the file name, line number and column number out of a line like
6420"foobar.txt, 123, 45". >
6421 :" Set up the match bit
6422 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
6423 :"get the part matching the whole expression
6424 :let l = matchstr(line, mx)
6425 :"get each item out of the match
6426 :let file = substitute(l, mx, '\1', '')
6427 :let lnum = substitute(l, mx, '\2', '')
6428 :let col = substitute(l, mx, '\3', '')
6429
6430The input is in the variable "line", the results in the variables "file",
6431"lnum" and "col". (idea from Michael Geddes)
6432
6433==============================================================================
643410. No +eval feature *no-eval-feature*
6435
6436When the |+eval| feature was disabled at compile time, none of the expression
6437evaluation commands are available. To prevent this from causing Vim scripts
6438to generate all kinds of errors, the ":if" and ":endif" commands are still
6439recognized, though the argument of the ":if" and everything between the ":if"
6440and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
6441only if the commands are at the start of the line. The ":else" command is not
6442recognized.
6443
6444Example of how to avoid executing commands when the |+eval| feature is
6445missing: >
6446
6447 :if 1
6448 : echo "Expression evaluation is compiled in"
6449 :else
6450 : echo "You will _never_ see this message"
6451 :endif
6452
6453==============================================================================
645411. The sandbox *eval-sandbox* *sandbox* *E48*
6455
6456The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
6457options are evaluated in a sandbox. This means that you are protected from
6458these expressions having nasty side effects. This gives some safety for when
6459these options are set from a modeline. It is also used when the command from
6460a tags file is executed.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006461The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006462
6463These items are not allowed in the sandbox:
6464 - changing the buffer text
6465 - defining or changing mapping, autocommands, functions, user commands
6466 - setting certain options (see |option-summary|)
6467 - executing a shell command
6468 - reading or writing a file
6469 - jumping to another buffer or editing a file
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006470This is not guaranteed 100% secure, but it should block most attacks.
6471
6472 *:san* *:sandbox*
6473:sandbox {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
6474 option that may have been set from a modeline, e.g.
6475 'foldexpr'.
6476
Bram Moolenaar071d4272004-06-13 20:20:40 +00006477
6478 vim:tw=78:ts=8:ft=help:norl: