blob: 85916e48485aceb1f307b4b8e8f227aa83f1efff [file] [log] [blame]
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00001*eval.txt* For Vim version 7.0aa. Last change: 2005 Jun 27
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
244exception: When comparing a number with a string and the string contains extra
245characters beside the number they are not equal. Example: >
246 echo 4 == "4x"
247< 1 >
248 echo [4] == ["4x"]
249< 0
250
251This is to fix the odd behavior of == that can't be changed for backward
252compatibility reasons.
253
Bram Moolenaar13065c42005-01-08 16:08:21 +0000254
255List unpack ~
256
257To unpack the items in a list to individual variables, put the variables in
258square brackets, like list items: >
259 :let [var1, var2] = mylist
260
261When the number of variables does not match the number of items in the list
262this produces an error. To handle any extra items from the list append ";"
263and a variable name: >
264 :let [var1, var2; rest] = mylist
265
266This works like: >
267 :let var1 = mylist[0]
268 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000269 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000270
271Except that there is no error if there are only two items. "rest" will be an
272empty list then.
273
274
275List modification ~
276 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000277To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000278 :let list[4] = "four"
279 :let listlist[0][3] = item
280
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000281To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000282modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000283 :let list[3:5] = [3, 4, 5]
284
Bram Moolenaar13065c42005-01-08 16:08:21 +0000285Adding and removing items from a list is done with functions. Here are a few
286examples: >
287 :call insert(list, 'a') " prepend item 'a'
288 :call insert(list, 'a', 3) " insert item 'a' before list[3]
289 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000290 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000291 :call extend(list, [1, 2]) " extend the list with two more items
292 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000293 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000294 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000295 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000296 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000297
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000298Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000299 :call sort(list) " sort a list alphabetically
300 :call reverse(list) " reverse the order of items
301
Bram Moolenaar13065c42005-01-08 16:08:21 +0000302
303For loop ~
304
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000305The |:for| loop executes commands for each item in a list. A variable is set
306to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000307 :for item in mylist
308 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000309 :endfor
310
311This works like: >
312 :let index = 0
313 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000314 : let item = mylist[index]
315 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000316 : let index = index + 1
317 :endwhile
318
319Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000320results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000321the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000322
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000323If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000324function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000325
Bram Moolenaar13065c42005-01-08 16:08:21 +0000326Just like the |:let| command, |:for| also accepts a list of variables. This
327requires the argument to be a list of lists. >
328 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
329 : call Doit(lnum, col)
330 :endfor
331
332This works like a |:let| command is done for each list item. Again, the types
333must remain the same to avoid an error.
334
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000335It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000336 :for [i, j; rest] in listlist
337 : call Doit(i, j)
338 : if !empty(rest)
339 : echo "remainder: " . string(rest)
340 : endif
341 :endfor
342
343
344List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000345 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000346Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000347 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000348 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000349 :let l = len(list) " number of items in list
350 :let big = max(list) " maximum value in list
351 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000352 :let xs = count(list, 'x') " count nr of times 'x' appears in list
353 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000354 :let lines = getline(1, 10) " get ten text lines from buffer
355 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000356 :let list = split("a b c") " create list from items in a string
357 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000358 :let s = string(list) " String representation of list
359 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000360
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000361Don't forget that a combination of features can make things simple. For
362example, to add up all the numbers in a list: >
363 :exe 'let sum = ' . join(nrlist, '+')
364
Bram Moolenaar13065c42005-01-08 16:08:21 +0000365
Bram Moolenaard8b02732005-01-14 21:48:43 +00003661.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000367 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000368A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000369entry can be located with the key. The entries are stored without a specific
370ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000371
372
373Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000374 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000375A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000376braces. Each entry has a key and a value, separated by a colon. Each key can
377only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000378 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
379 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000380< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000381A key is always a String. You can use a Number, it will be converted to a
382String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000383entry. Note that the String '04' and the Number 04 are different, since the
384Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000385
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000386A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000387nested Dictionary: >
388 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
389
390An extra comma after the last entry is ignored.
391
392
393Accessing entries ~
394
395The normal way to access an entry is by putting the key in square brackets: >
396 :let val = mydict["one"]
397 :let mydict["four"] = 4
398
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000400
401For keys that consist entirely of letters, digits and underscore the following
402form can be used |expr-entry|: >
403 :let val = mydict.one
404 :let mydict.four = 4
405
406Since an entry can be any type, also a List and a Dictionary, the indexing and
407key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000408 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000409
410
411Dictionary to List conversion ~
412
413You may want to loop over the entries in a dictionary. For this you need to
414turn the Dictionary into a List and pass it to |:for|.
415
416Most often you want to loop over the keys, using the |keys()| function: >
417 :for key in keys(mydict)
418 : echo key . ': ' . mydict[key]
419 :endfor
420
421The List of keys is unsorted. You may want to sort them first: >
422 :for key in sort(keys(mydict))
423
424To loop over the values use the |values()| function: >
425 :for v in values(mydict)
426 : echo "value: " . v
427 :endfor
428
429If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000430a List in which each item is a List with two items, the key and the value: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000431 :for entry in items(mydict)
432 : echo entry[0] . ': ' . entry[1]
433 :endfor
434
435
436Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000437 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000438Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
439Dictionary. Otherwise, assignment results in referring to the same
440Dictionary: >
441 :let onedict = {'a': 1, 'b': 2}
442 :let adict = onedict
443 :let adict['a'] = 11
444 :echo onedict['a']
445 11
446
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000447Two Dictionaries compare equal if all the key-value pairs compare equal. For
448more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000449
450
451Dictionary modification ~
452 *dict-modification*
453To change an already existing entry of a Dictionary, or to add a new entry,
454use |:let| this way: >
455 :let dict[4] = "four"
456 :let dict['one'] = item
457
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000458Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
459Three ways to remove the entry with key "aaa" from dict: >
460 :let i = remove(dict, 'aaa')
461 :unlet dict.aaa
462 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000463
464Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000465 :call extend(adict, bdict)
466This extends adict with all entries from bdict. Duplicate keys cause entries
467in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000468Note that the order of entries in a Dictionary is irrelevant, thus don't
469expect ":echo adict" to show the items from bdict after the older entries in
470adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000471
472Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaare2cc9702005-03-15 22:43:58 +0000473 :call filter(dict 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000474This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000475
476
477Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000478 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000479When a function is defined with the "dict" attribute it can be used in a
480special way with a dictionary. Example: >
481 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000482 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000483 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000484 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
485 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000486
487This is like a method in object oriented programming. The entry in the
488Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
489the function was invoked from.
490
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000491It is also possible to add a function without the "dict" attribute as a
492Funcref to a Dictionary, but the "self" variable is not available then.
493
494 *numbered-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000495To avoid the extra name for the function it can be defined and directly
496assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000497 :let mydict = {'data': [0, 1, 2, 3]}
498 :function mydict.len() dict
499 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000500 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000501 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000502
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000503The function will then get a number and the value of dict.len is a |Funcref|
504that references this function. The function can only be used through a
505|Funcref|. It will automatically be deleted when there is no |Funcref|
506remaining that refers to it.
507
508It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000509
510
511Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000512 *E715*
513Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000514 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
515 :if empty(dict) " TRUE if dict is empty
516 :let l = len(dict) " number of items in dict
517 :let big = max(dict) " maximum value in dict
518 :let small = min(dict) " minimum value in dict
519 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
520 :let s = string(dict) " String representation of dict
521 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000522
523
5241.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000525 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000526If you need to know the type of a variable or expression, use the |type()|
527function.
528
529When the '!' flag is included in the 'viminfo' option, global variables that
530start with an uppercase letter, and don't contain a lowercase letter, are
531stored in the viminfo file |viminfo-file|.
532
533When the 'sessionoptions' option contains "global", global variables that
534start with an uppercase letter and contain at least one lowercase letter are
535stored in the session file |session-file|.
536
537variable name can be stored where ~
538my_var_6 not
539My_Var_6 session file
540MY_VAR_6 viminfo file
541
542
543It's possible to form a variable name with curly braces, see
544|curly-braces-names|.
545
546==============================================================================
5472. Expression syntax *expression-syntax*
548
549Expression syntax summary, from least to most significant:
550
551|expr1| expr2 ? expr1 : expr1 if-then-else
552
553|expr2| expr3 || expr3 .. logical OR
554
555|expr3| expr4 && expr4 .. logical AND
556
557|expr4| expr5 == expr5 equal
558 expr5 != expr5 not equal
559 expr5 > expr5 greater than
560 expr5 >= expr5 greater than or equal
561 expr5 < expr5 smaller than
562 expr5 <= expr5 smaller than or equal
563 expr5 =~ expr5 regexp matches
564 expr5 !~ expr5 regexp doesn't match
565
566 expr5 ==? expr5 equal, ignoring case
567 expr5 ==# expr5 equal, match case
568 etc. As above, append ? for ignoring case, # for
569 matching case
570
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000571 expr5 is expr5 same List instance
572 expr5 isnot expr5 different List instance
573
574|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000575 expr6 - expr6 .. number subtraction
576 expr6 . expr6 .. string concatenation
577
578|expr6| expr7 * expr7 .. number multiplication
579 expr7 / expr7 .. number division
580 expr7 % expr7 .. number modulo
581
582|expr7| ! expr7 logical NOT
583 - expr7 unary minus
584 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000585
Bram Moolenaar071d4272004-06-13 20:20:40 +0000586
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000587|expr8| expr8[expr1] byte of a String or item of a List
588 expr8[expr1 : expr1] substring of a String or sublist of a List
589 expr8.name entry in a Dictionary
590 expr8(expr1, ...) function call with Funcref variable
591
592|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000593 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000594 'string' string constant, ' is doubled
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000595 [expr1, ...] List
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000596 {expr1: expr1, ...} Dictionary
Bram Moolenaar071d4272004-06-13 20:20:40 +0000597 &option option value
598 (expr1) nested expression
599 variable internal variable
600 va{ria}ble internal variable with curly braces
601 $VAR environment variable
602 @r contents of register 'r'
603 function(expr1, ...) function call
604 func{ti}on(expr1, ...) function call with curly braces
605
606
607".." indicates that the operations in this level can be concatenated.
608Example: >
609 &nu || &list && &shell == "csh"
610
611All expressions within one level are parsed from left to right.
612
613
614expr1 *expr1* *E109*
615-----
616
617expr2 ? expr1 : expr1
618
619The expression before the '?' is evaluated to a number. If it evaluates to
620non-zero, the result is the value of the expression between the '?' and ':',
621otherwise the result is the value of the expression after the ':'.
622Example: >
623 :echo lnum == 1 ? "top" : lnum
624
625Since the first expression is an "expr2", it cannot contain another ?:. The
626other two expressions can, thus allow for recursive use of ?:.
627Example: >
628 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
629
630To keep this readable, using |line-continuation| is suggested: >
631 :echo lnum == 1
632 :\ ? "top"
633 :\ : lnum == 1000
634 :\ ? "last"
635 :\ : lnum
636
637
638expr2 and expr3 *expr2* *expr3*
639---------------
640
641 *expr-barbar* *expr-&&*
642The "||" and "&&" operators take one argument on each side. The arguments
643are (converted to) Numbers. The result is:
644
645 input output ~
646n1 n2 n1 || n2 n1 && n2 ~
647zero zero zero zero
648zero non-zero non-zero zero
649non-zero zero non-zero zero
650non-zero non-zero non-zero non-zero
651
652The operators can be concatenated, for example: >
653
654 &nu || &list && &shell == "csh"
655
656Note that "&&" takes precedence over "||", so this has the meaning of: >
657
658 &nu || (&list && &shell == "csh")
659
660Once the result is known, the expression "short-circuits", that is, further
661arguments are not evaluated. This is like what happens in C. For example: >
662
663 let a = 1
664 echo a || b
665
666This is valid even if there is no variable called "b" because "a" is non-zero,
667so the result must be non-zero. Similarly below: >
668
669 echo exists("b") && b == "yes"
670
671This is valid whether "b" has been defined or not. The second clause will
672only be evaluated if "b" has been defined.
673
674
675expr4 *expr4*
676-----
677
678expr5 {cmp} expr5
679
680Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
681if it evaluates to true.
682
683 *expr-==* *expr-!=* *expr->* *expr->=*
684 *expr-<* *expr-<=* *expr-=~* *expr-!~*
685 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
686 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
687 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
688 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000689 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000690 use 'ignorecase' match case ignore case ~
691equal == ==# ==?
692not equal != !=# !=?
693greater than > ># >?
694greater than or equal >= >=# >=?
695smaller than < <# <?
696smaller than or equal <= <=# <=?
697regexp matches =~ =~# =~?
698regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000699same instance is
700different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000701
702Examples:
703"abc" ==# "Abc" evaluates to 0
704"abc" ==? "Abc" evaluates to 1
705"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
706
Bram Moolenaar13065c42005-01-08 16:08:21 +0000707 *E691* *E692*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000708A List can only be compared with a List and only "equal", "not equal" and "is"
709can be used. This compares the values of the list, recursively. Ignoring
710case means case is ignored when comparing item values.
711
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000712 *E735* *E736*
713A Dictionary can only be compared with a Dictionary and only "equal", "not
714equal" and "is" can be used. This compares the key/values of the Dictionary,
715recursively. Ignoring case means case is ignored when comparing item values.
716
Bram Moolenaar13065c42005-01-08 16:08:21 +0000717 *E693* *E694*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000718A Funcref can only be compared with a Funcref and only "equal" and "not equal"
719can be used. Case is never ignored.
720
721When using "is" or "isnot" with a List this checks if the expressions are
722referring to the same List instance. A copy of a List is different from the
723original List. When using "is" without a List it is equivalent to using
724"equal", using "isnot" equivalent to using "not equal". Except that a
725different type means the values are different. "4 == '4'" is true, "4 is '4'"
726is false.
727
Bram Moolenaar071d4272004-06-13 20:20:40 +0000728When comparing a String with a Number, the String is converted to a Number,
729and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
730because 'x' converted to a Number is zero.
731
732When comparing two Strings, this is done with strcmp() or stricmp(). This
733results in the mathematical difference (comparing byte values), not
734necessarily the alphabetical difference in the local language.
735
736When using the operators with a trailing '#", or the short version and
737'ignorecase' is off, the comparing is done with strcmp().
738
739When using the operators with a trailing '?', or the short version and
740'ignorecase' is set, the comparing is done with stricmp().
741
742The "=~" and "!~" operators match the lefthand argument with the righthand
743argument, which is used as a pattern. See |pattern| for what a pattern is.
744This matching is always done like 'magic' was set and 'cpoptions' is empty, no
745matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
746portable. To avoid backslashes in the regexp pattern to be doubled, use a
747single-quote string, see |literal-string|.
748Since a string is considered to be a single line, a multi-line pattern
749(containing \n, backslash-n) will not match. However, a literal NL character
750can be matched like an ordinary character. Examples:
751 "foo\nbar" =~ "\n" evaluates to 1
752 "foo\nbar" =~ "\\n" evaluates to 0
753
754
755expr5 and expr6 *expr5* *expr6*
756---------------
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000757expr6 + expr6 .. Number addition or List concatenation *expr-+*
758expr6 - expr6 .. Number subtraction *expr--*
759expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000760
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000761For Lists only "+" is possible and then both expr6 must be a list. The result
762is a new list with the two lists Concatenated.
763
764expr7 * expr7 .. number multiplication *expr-star*
765expr7 / expr7 .. number division *expr-/*
766expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000767
768For all, except ".", Strings are converted to Numbers.
769
770Note the difference between "+" and ".":
771 "123" + "456" = 579
772 "123" . "456" = "123456"
773
774When the righthand side of '/' is zero, the result is 0x7fffffff.
775When the righthand side of '%' is zero, the result is 0.
776
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000777None of these work for Funcrefs.
778
Bram Moolenaar071d4272004-06-13 20:20:40 +0000779
780expr7 *expr7*
781-----
782! expr7 logical NOT *expr-!*
783- expr7 unary minus *expr-unary--*
784+ expr7 unary plus *expr-unary-+*
785
786For '!' non-zero becomes zero, zero becomes one.
787For '-' the sign of the number is changed.
788For '+' the number is unchanged.
789
790A String will be converted to a Number first.
791
792These three can be repeated and mixed. Examples:
793 !-1 == 0
794 !!8 == 1
795 --9 == 9
796
797
798expr8 *expr8*
799-----
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000800expr8[expr1] item of String or List *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000802If expr8 is a Number or String this results in a String that contains the
803expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000804Number. Note that this doesn't recognize multi-byte encodings.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000805
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000806Index zero gives the first character. This is like it works in C. Careful:
807text column numbers start with one! Example, to get the character under the
808cursor: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000809 :let c = getline(line("."))[col(".") - 1]
810
811If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000812String. A negative index always results in an empty string (reason: backwards
813compatibility). Use [-1:] to get the last byte.
814
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000815If expr8 is a List then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000816for possible index values. If the index is out of range this results in an
817error. Example: >
818 :let item = mylist[-1] " get last item
819
820Generally, if a List index is equal to or higher than the length of the List,
821or more negative than the length of the List, this results in an error.
822
Bram Moolenaard8b02732005-01-14 21:48:43 +0000823
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000824expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000825
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000826If expr8 is a Number or String this results in the substring with the bytes
827from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000828expr1b are used as a Number. Note that this doesn't recognize multi-byte
829encodings.
830
831If expr1a is omitted zero is used. If expr1b is omitted the length of the
832string minus one is used.
833
834A negative number can be used to measure from the end of the string. -1 is
835the last character, -2 the last but one, etc.
836
837If an index goes out of range for the string characters are omitted. If
838expr1b is smaller than expr1a the result is an empty string.
839
840Examples: >
841 :let c = name[-1:] " last byte of a string
842 :let c = name[-2:-2] " last but one byte of a string
843 :let s = line(".")[4:] " from the fifth byte to the end
844 :let s = s[:-3] " remove last two bytes
845
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000846If expr8 is a List this results in a new List with the items indicated by the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000847indexes expr1a and expr1b. This works like with a String, as explained just
848above, except that indexes out of range cause an error. Examples: >
849 :let l = mylist[:3] " first four items
850 :let l = mylist[4:4] " List with one item
851 :let l = mylist[:] " shallow copy of a List
852
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000853Using expr8[expr1] or expr8[expr1a : expr1b] on a Funcref results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854
Bram Moolenaard8b02732005-01-14 21:48:43 +0000855
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000856expr8.name entry in a Dictionary *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000857
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000858If expr8 is a Dictionary and it is followed by a dot, then the following name
859will be used as a key in the Dictionary. This is just like: expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000860
861The name must consist of alphanumeric characters, just like a variable name,
862but it may start with a number. Curly braces cannot be used.
863
864There must not be white space before or after the dot.
865
866Examples: >
867 :let dict = {"one": 1, 2: "two"}
868 :echo dict.one
869 :echo dict .2
870
871Note that the dot is also used for String concatenation. To avoid confusion
872always put spaces around the dot for String concatenation.
873
874
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000875expr8(expr1, ...) Funcref function call
876
877When expr8 is a |Funcref| type variable, invoke the function it refers to.
878
879
880
881 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000882number
883------
884number number constant *expr-number*
885
886Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
887
888
889string *expr-string* *E114*
890------
891"string" string constant *expr-quote*
892
893Note that double quotes are used.
894
895A string constant accepts these special characters:
896\... three-digit octal number (e.g., "\316")
897\.. two-digit octal number (must be followed by non-digit)
898\. one-digit octal number (must be followed by non-digit)
899\x.. byte specified with two hex numbers (e.g., "\x1f")
900\x. byte specified with one hex number (must be followed by non-hex char)
901\X.. same as \x..
902\X. same as \x.
903\u.... character specified with up to 4 hex numbers, stored according to the
904 current value of 'encoding' (e.g., "\u02a4")
905\U.... same as \u....
906\b backspace <BS>
907\e escape <Esc>
908\f formfeed <FF>
909\n newline <NL>
910\r return <CR>
911\t tab <Tab>
912\\ backslash
913\" double quote
914\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
915
916Note that "\000" and "\x00" force the end of the string.
917
918
919literal-string *literal-string* *E115*
920---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000921'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000922
923Note that single quotes are used.
924
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000925This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000926meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000927
928Single quoted strings are useful for patterns, so that backslashes do not need
929to be doubled. These two commands are equivalent: >
930 if a =~ "\\s*"
931 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000932
933
934option *expr-option* *E112* *E113*
935------
936&option option value, local value if possible
937&g:option global option value
938&l:option local option value
939
940Examples: >
941 echo "tabstop is " . &tabstop
942 if &insertmode
943
944Any option name can be used here. See |options|. When using the local value
945and there is no buffer-local or window-local value, the global value is used
946anyway.
947
948
949register *expr-register*
950--------
951@r contents of register 'r'
952
953The result is the contents of the named register, as a single string.
954Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaare7566042005-06-17 22:00:15 +0000955register use @" or @@. See |registers| for an explanation of the available
956registers.
957
958When using the '=' register you get the expression itself, not what it
959evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000960
961
962nesting *expr-nesting* *E110*
963-------
964(expr1) nested expression
965
966
967environment variable *expr-env*
968--------------------
969$VAR environment variable
970
971The String value of any environment variable. When it is not defined, the
972result is an empty string.
973 *expr-env-expand*
974Note that there is a difference between using $VAR directly and using
975expand("$VAR"). Using it directly will only expand environment variables that
976are known inside the current Vim session. Using expand() will first try using
977the environment variables known inside the current Vim session. If that
978fails, a shell will be used to expand the variable. This can be slow, but it
979does expand all variables that the shell knows about. Example: >
980 :echo $version
981 :echo expand("$version")
982The first one probably doesn't echo anything, the second echoes the $version
983variable (if your shell supports it).
984
985
986internal variable *expr-variable*
987-----------------
988variable internal variable
989See below |internal-variables|.
990
991
Bram Moolenaar05159a02005-02-26 23:04:13 +0000992function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000993-------------
994function(expr1, ...) function call
995See below |functions|.
996
997
998==============================================================================
9993. Internal variable *internal-variables* *E121*
1000 *E461*
1001An internal variable name can be made up of letters, digits and '_'. But it
1002cannot start with a digit. It's also possible to use curly braces, see
1003|curly-braces-names|.
1004
1005An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001006An internal variable is explicitly destroyed with the ":unlet" command
1007|:unlet|.
1008Using a name that is not an internal variable or refers to a variable that has
1009been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001010
1011There are several name spaces for variables. Which one is to be used is
1012specified by what is prepended:
1013
1014 (nothing) In a function: local to a function; otherwise: global
1015|buffer-variable| b: Local to the current buffer.
1016|window-variable| w: Local to the current window.
1017|global-variable| g: Global.
1018|local-variable| l: Local to a function.
1019|script-variable| s: Local to a |:source|'ed Vim script.
1020|function-argument| a: Function argument (only inside a function).
1021|vim-variable| v: Global, predefined by Vim.
1022
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001023The scope name by itself can be used as a Dictionary. For example, to delete
1024all script-local variables: >
1025 :for k in keys(s:)
1026 : unlet s:[k]
1027 :endfor
1028<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029 *buffer-variable* *b:var*
1030A variable name that is preceded with "b:" is local to the current buffer.
1031Thus you can have several "b:foo" variables, one for each buffer.
1032This kind of variable is deleted when the buffer is wiped out or deleted with
1033|:bdelete|.
1034
1035One local buffer variable is predefined:
1036 *b:changedtick-variable* *changetick*
1037b:changedtick The total number of changes to the current buffer. It is
1038 incremented for each change. An undo command is also a change
1039 in this case. This can be used to perform an action only when
1040 the buffer has changed. Example: >
1041 :if my_changedtick != b:changedtick
1042 : let my_changedtick = b:changedtick
1043 : call My_Update()
1044 :endif
1045<
1046 *window-variable* *w:var*
1047A variable name that is preceded with "w:" is local to the current window. It
1048is deleted when the window is closed.
1049
1050 *global-variable* *g:var*
1051Inside functions global variables are accessed with "g:". Omitting this will
1052access a variable local to a function. But "g:" can also be used in any other
1053place if you like.
1054
1055 *local-variable* *l:var*
1056Inside functions local variables are accessed without prepending anything.
1057But you can also prepend "l:" if you like.
1058
1059 *script-variable* *s:var*
1060In a Vim script variables starting with "s:" can be used. They cannot be
1061accessed from outside of the scripts, thus are local to the script.
1062
1063They can be used in:
1064- commands executed while the script is sourced
1065- functions defined in the script
1066- autocommands defined in the script
1067- functions and autocommands defined in functions and autocommands which were
1068 defined in the script (recursively)
1069- user defined commands defined in the script
1070Thus not in:
1071- other scripts sourced from this one
1072- mappings
1073- etc.
1074
1075script variables can be used to avoid conflicts with global variable names.
1076Take this example:
1077
1078 let s:counter = 0
1079 function MyCounter()
1080 let s:counter = s:counter + 1
1081 echo s:counter
1082 endfunction
1083 command Tick call MyCounter()
1084
1085You can now invoke "Tick" from any script, and the "s:counter" variable in
1086that script will not be changed, only the "s:counter" in the script where
1087"Tick" was defined is used.
1088
1089Another example that does the same: >
1090
1091 let s:counter = 0
1092 command Tick let s:counter = s:counter + 1 | echo s:counter
1093
1094When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001095script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001096defined.
1097
1098The script variables are also available when a function is defined inside a
1099function that is defined in a script. Example: >
1100
1101 let s:counter = 0
1102 function StartCounting(incr)
1103 if a:incr
1104 function MyCounter()
1105 let s:counter = s:counter + 1
1106 endfunction
1107 else
1108 function MyCounter()
1109 let s:counter = s:counter - 1
1110 endfunction
1111 endif
1112 endfunction
1113
1114This defines the MyCounter() function either for counting up or counting down
1115when calling StartCounting(). It doesn't matter from where StartCounting() is
1116called, the s:counter variable will be accessible in MyCounter().
1117
1118When the same script is sourced again it will use the same script variables.
1119They will remain valid as long as Vim is running. This can be used to
1120maintain a counter: >
1121
1122 if !exists("s:counter")
1123 let s:counter = 1
1124 echo "script executed for the first time"
1125 else
1126 let s:counter = s:counter + 1
1127 echo "script executed " . s:counter . " times now"
1128 endif
1129
1130Note that this means that filetype plugins don't get a different set of script
1131variables for each buffer. Use local buffer variables instead |b:var|.
1132
1133
1134Predefined Vim variables: *vim-variable* *v:var*
1135
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001136 *v:beval_col* *beval_col-variable*
1137v:beval_col The number of the column, over which the mouse pointer is.
1138 This is the byte index in the |v:beval_lnum| line.
1139 Only valid while evaluating the 'balloonexpr' option.
1140
1141 *v:beval_bufnr* *beval_bufnr-variable*
1142v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1143 valid while evaluating the 'balloonexpr' option.
1144
1145 *v:beval_lnum* *beval_lnum-variable*
1146v:beval_lnum The number of the line, over which the mouse pointer is. Only
1147 valid while evaluating the 'balloonexpr' option.
1148
1149 *v:beval_text* *beval_text-variable*
1150v:beval_text The text under or after the mouse pointer. Usually a word as it is
1151 useful for debugging a C program. 'iskeyword' applies, but a
1152 dot and "->" before the position is included. When on a ']'
1153 the text before it is used, including the matching '[' and
1154 word before it. When on a Visual area within one line the
1155 highlighted text is used.
1156 Only valid while evaluating the 'balloonexpr' option.
1157
1158 *v:beval_winnr* *beval_winnr-variable*
1159v:beval_winnr The number of the window, over which the mouse pointer is. Only
1160 valid while evaluating the 'balloonexpr' option.
1161
Bram Moolenaar071d4272004-06-13 20:20:40 +00001162 *v:charconvert_from* *charconvert_from-variable*
1163v:charconvert_from
1164 The name of the character encoding of a file to be converted.
1165 Only valid while evaluating the 'charconvert' option.
1166
1167 *v:charconvert_to* *charconvert_to-variable*
1168v:charconvert_to
1169 The name of the character encoding of a file after conversion.
1170 Only valid while evaluating the 'charconvert' option.
1171
1172 *v:cmdarg* *cmdarg-variable*
1173v:cmdarg This variable is used for two purposes:
1174 1. The extra arguments given to a file read/write command.
1175 Currently these are "++enc=" and "++ff=". This variable is
1176 set before an autocommand event for a file read/write
1177 command is triggered. There is a leading space to make it
1178 possible to append this variable directly after the
1179 read/write command. Note: The "+cmd" argument isn't
1180 included here, because it will be executed anyway.
1181 2. When printing a PostScript file with ":hardcopy" this is
1182 the argument for the ":hardcopy" command. This can be used
1183 in 'printexpr'.
1184
1185 *v:cmdbang* *cmdbang-variable*
1186v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1187 was used the value is 1, otherwise it is 0. Note that this
1188 can only be used in autocommands. For user commands |<bang>|
1189 can be used.
1190
1191 *v:count* *count-variable*
1192v:count The count given for the last Normal mode command. Can be used
1193 to get the count before a mapping. Read-only. Example: >
1194 :map _x :<C-U>echo "the count is " . v:count<CR>
1195< Note: The <C-U> is required to remove the line range that you
1196 get when typing ':' after a count.
1197 "count" also works, for backwards compatibility.
1198
1199 *v:count1* *count1-variable*
1200v:count1 Just like "v:count", but defaults to one when no count is
1201 used.
1202
1203 *v:ctype* *ctype-variable*
1204v:ctype The current locale setting for characters of the runtime
1205 environment. This allows Vim scripts to be aware of the
1206 current locale encoding. Technical: it's the value of
1207 LC_CTYPE. When not using a locale the value is "C".
1208 This variable can not be set directly, use the |:language|
1209 command.
1210 See |multi-lang|.
1211
1212 *v:dying* *dying-variable*
1213v:dying Normally zero. When a deadly signal is caught it's set to
1214 one. When multiple signals are caught the number increases.
1215 Can be used in an autocommand to check if Vim didn't
1216 terminate normally. {only works on Unix}
1217 Example: >
1218 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1219<
1220 *v:errmsg* *errmsg-variable*
1221v:errmsg Last given error message. It's allowed to set this variable.
1222 Example: >
1223 :let v:errmsg = ""
1224 :silent! next
1225 :if v:errmsg != ""
1226 : ... handle error
1227< "errmsg" also works, for backwards compatibility.
1228
1229 *v:exception* *exception-variable*
1230v:exception The value of the exception most recently caught and not
1231 finished. See also |v:throwpoint| and |throw-variables|.
1232 Example: >
1233 :try
1234 : throw "oops"
1235 :catch /.*/
1236 : echo "caught" v:exception
1237 :endtry
1238< Output: "caught oops".
1239
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001240 *v:fcs_reason* *fcs_reason-variable*
1241v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1242 Can be used in an autocommand to decide what to do and/or what
1243 to set v:fcs_choice to. Possible values:
1244 deleted file no longer exists
1245 conflict file contents, mode or timestamp was
1246 changed and buffer is modified
1247 changed file contents has changed
1248 mode mode of file changed
1249 time only file timestamp changed
1250
1251 *v:fcs_choice* *fcs_choice-variable*
1252v:fcs_choice What should happen after a |FileChangedShell| event was
1253 triggered. Can be used in an autocommand to tell Vim what to
1254 do with the affected buffer:
1255 reload Reload the buffer (does not work if
1256 the file was deleted).
1257 ask Ask the user what to do, as if there
1258 was no autocommand. Except that when
1259 only the timestamp changed nothing
1260 will happen.
1261 <empty> Nothing, the autocommand should do
1262 everything that needs to be done.
1263 The default is empty. If another (invalid) value is used then
1264 Vim behaves like it is empty, there is no warning message.
1265
Bram Moolenaar071d4272004-06-13 20:20:40 +00001266 *v:fname_in* *fname_in-variable*
1267v:fname_in The name of the input file. Only valid while evaluating:
1268 option used for ~
1269 'charconvert' file to be converted
1270 'diffexpr' original file
1271 'patchexpr' original file
1272 'printexpr' file to be printed
1273
1274 *v:fname_out* *fname_out-variable*
1275v:fname_out The name of the output file. Only valid while
1276 evaluating:
1277 option used for ~
1278 'charconvert' resulting converted file (*)
1279 'diffexpr' output of diff
1280 'patchexpr' resulting patched file
1281 (*) When doing conversion for a write command (e.g., ":w
1282 file") it will be equal to v:fname_in. When doing conversion
1283 for a read command (e.g., ":e file") it will be a temporary
1284 file and different from v:fname_in.
1285
1286 *v:fname_new* *fname_new-variable*
1287v:fname_new The name of the new version of the file. Only valid while
1288 evaluating 'diffexpr'.
1289
1290 *v:fname_diff* *fname_diff-variable*
1291v:fname_diff The name of the diff (patch) file. Only valid while
1292 evaluating 'patchexpr'.
1293
1294 *v:folddashes* *folddashes-variable*
1295v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1296 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001297 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001298
1299 *v:foldlevel* *foldlevel-variable*
1300v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001301 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001302
1303 *v:foldend* *foldend-variable*
1304v:foldend Used for 'foldtext': last line of closed 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:foldstart* *foldstart-variable*
1308v:foldstart Used for 'foldtext': first line 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
Bram Moolenaar843ee412004-06-30 16:16:41 +00001311 *v:insertmode* *insertmode-variable*
1312v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1313 events. Values:
1314 i Insert mode
1315 r Replace mode
1316 v Virtual Replace mode
1317
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001318 *v:key* *key-variable*
1319v:key Key of the current item of a Dictionary. Only valid while
1320 evaluating the expression used with |map()| and |filter()|.
1321 Read-only.
1322
Bram Moolenaar071d4272004-06-13 20:20:40 +00001323 *v:lang* *lang-variable*
1324v:lang The current locale setting for messages of the runtime
1325 environment. This allows Vim scripts to be aware of the
1326 current language. Technical: it's the value of LC_MESSAGES.
1327 The value is system dependent.
1328 This variable can not be set directly, use the |:language|
1329 command.
1330 It can be different from |v:ctype| when messages are desired
1331 in a different language than what is used for character
1332 encoding. See |multi-lang|.
1333
1334 *v:lc_time* *lc_time-variable*
1335v:lc_time The current locale setting for time messages of the runtime
1336 environment. This allows Vim scripts to be aware of the
1337 current language. Technical: it's the value of LC_TIME.
1338 This variable can not be set directly, use the |:language|
1339 command. See |multi-lang|.
1340
1341 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001342v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1343 expressions. Only valid while one of these expressions is
1344 being evaluated. Read-only when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001345
1346 *v:prevcount* *prevcount-variable*
1347v:prevcount The count given for the last but one Normal mode command.
1348 This is the v:count value of the previous command. Useful if
1349 you want to cancel Visual mode and then use the count. >
1350 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1351< Read-only.
1352
Bram Moolenaar05159a02005-02-26 23:04:13 +00001353 *v:profiling* *profiling-variable*
1354v:profiling Normally zero. Set to one after using ":profile start".
1355 See |profiling|.
1356
Bram Moolenaar071d4272004-06-13 20:20:40 +00001357 *v:progname* *progname-variable*
1358v:progname Contains the name (with path removed) with which Vim was
1359 invoked. Allows you to do special initialisations for "view",
1360 "evim" etc., or any other name you might symlink to Vim.
1361 Read-only.
1362
1363 *v:register* *register-variable*
1364v:register The name of the register supplied to the last normal mode
1365 command. Empty if none were supplied. |getreg()| |setreg()|
1366
1367 *v:servername* *servername-variable*
1368v:servername The resulting registered |x11-clientserver| name if any.
1369 Read-only.
1370
1371 *v:shell_error* *shell_error-variable*
1372v:shell_error Result of the last shell command. When non-zero, the last
1373 shell command had an error. When zero, there was no problem.
1374 This only works when the shell returns the error code to Vim.
1375 The value -1 is often used when the command could not be
1376 executed. Read-only.
1377 Example: >
1378 :!mv foo bar
1379 :if v:shell_error
1380 : echo 'could not rename "foo" to "bar"!'
1381 :endif
1382< "shell_error" also works, for backwards compatibility.
1383
1384 *v:statusmsg* *statusmsg-variable*
1385v:statusmsg Last given status message. It's allowed to set this variable.
1386
1387 *v:termresponse* *termresponse-variable*
1388v:termresponse The escape sequence returned by the terminal for the |t_RV|
1389 termcap entry. It is set when Vim receives an escape sequence
1390 that starts with ESC [ or CSI and ends in a 'c', with only
1391 digits, ';' and '.' in between.
1392 When this option is set, the TermResponse autocommand event is
1393 fired, so that you can react to the response from the
1394 terminal.
1395 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1396 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1397 patch level (since this was introduced in patch 95, it's
1398 always 95 or bigger). Pc is always zero.
1399 {only when compiled with |+termresponse| feature}
1400
1401 *v:this_session* *this_session-variable*
1402v:this_session Full filename of the last loaded or saved session file. See
1403 |:mksession|. It is allowed to set this variable. When no
1404 session file has been saved, this variable is empty.
1405 "this_session" also works, for backwards compatibility.
1406
1407 *v:throwpoint* *throwpoint-variable*
1408v:throwpoint The point where the exception most recently caught and not
1409 finished was thrown. Not set when commands are typed. See
1410 also |v:exception| and |throw-variables|.
1411 Example: >
1412 :try
1413 : throw "oops"
1414 :catch /.*/
1415 : echo "Exception from" v:throwpoint
1416 :endtry
1417< Output: "Exception from test.vim, line 2"
1418
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001419 *v:val* *val-variable*
1420v:val Value of the current item of a List or Dictionary. Only valid
1421 while evaluating the expression used with |map()| and
1422 |filter()|. Read-only.
1423
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424 *v:version* *version-variable*
1425v:version Version number of Vim: Major version number times 100 plus
1426 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1427 is 501. Read-only. "version" also works, for backwards
1428 compatibility.
1429 Use |has()| to check if a certain patch was included, e.g.: >
1430 if has("patch123")
1431< Note that patch numbers are specific to the version, thus both
1432 version 5.0 and 5.1 may have a patch 123, but these are
1433 completely different.
1434
1435 *v:warningmsg* *warningmsg-variable*
1436v:warningmsg Last given warning message. It's allowed to set this variable.
1437
1438==============================================================================
14394. Builtin Functions *functions*
1440
1441See |function-list| for a list grouped by what the function is used for.
1442
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001443(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001444
1445USAGE RESULT DESCRIPTION ~
1446
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001447add( {list}, {item}) List append {item} to List {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001448append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001449append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001450argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001451argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452argv( {nr}) String {nr} entry of the argument list
1453browse( {save}, {title}, {initdir}, {default})
1454 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001455browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001456bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001457buflisted( {expr}) Number TRUE if buffer {expr} is listed
1458bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459bufname( {expr}) String Name of the buffer {expr}
1460bufnr( {expr}) Number Number of the buffer {expr}
1461bufwinnr( {expr}) Number window number of buffer {expr}
1462byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001463byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001464call( {func}, {arglist} [, {dict}])
1465 any call {func} with arguments {arglist}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001466char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001467cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001468col( {expr}) Number column nr of cursor or mark
1469confirm( {msg} [, {choices} [, {default} [, {type}]]])
1470 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001471copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001472count( {list}, {expr} [, {start} [, {ic}]])
1473 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001474cscope_connection( [{num} , {dbpath} [, {prepend}]])
1475 Number checks existence of cscope connection
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001476cursor( {lnum}, {col}) Number position cursor at {lnum}, {col}
1477deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001478delete( {fname}) Number delete file {fname}
1479did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001480diff_filler( {lnum}) Number diff filler lines about {lnum}
1481diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001482empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001483escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001484eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001485eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001486executable( {expr}) Number 1 if executable {expr} exists
1487exists( {expr}) Number TRUE if {expr} exists
1488expand( {expr}) String expand special keywords in {expr}
1489filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001490filter( {expr}, {string}) List/Dict remove items from {expr} where
1491 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001492finddir( {name}[, {path}[, {count}]])
1493 String Find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001494findfile( {name}[, {path}[, {count}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001495 String Find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001496filewritable( {file}) Number TRUE if {file} is a writable file
1497fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001498foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1499foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001500foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001501foldtext( ) String line displayed for closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +00001502foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001503function( {name}) Funcref reference to function {name}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001504get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001505get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001506getchar( [expr]) Number get one character from the user
1507getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001508getbufvar( {expr}, {varname}) variable {varname} in buffer {expr}
1509getcmdline() String return the current command-line
1510getcmdpos() Number return cursor position in command-line
1511getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001512getfperm( {fname}) String file permissions of file {fname}
1513getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001514getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001516getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001517getline( {lnum}) String line {lnum} of current buffer
1518getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001519getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001520getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001521getregtype( [{regname}]) String type of register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001522getwinposx() Number X coord in pixels of GUI Vim window
1523getwinposy() Number Y coord in pixels of GUI Vim window
1524getwinvar( {nr}, {varname}) variable {varname} in window {nr}
1525glob( {expr}) String expand file wildcards in {expr}
1526globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1527has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001528has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001529hasmapto( {what} [, {mode}]) Number TRUE if mapping to {what} exists
1530histadd( {history},{item}) String add an item to a history
1531histdel( {history} [, {item}]) String remove an item from a history
1532histget( {history} [, {index}]) String get the item {index} from a history
1533histnr( {history}) Number highest index of a history
1534hlexists( {name}) Number TRUE if highlight group {name} exists
1535hlID( {name}) Number syntax ID of highlight group {name}
1536hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001537iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1538indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001539index( {list}, {expr} [, {start} [, {ic}]])
1540 Number index in {list} where {expr} appears
Bram Moolenaar071d4272004-06-13 20:20:40 +00001541input( {prompt} [, {text}]) String get input from the user
1542inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001543inputrestore() Number restore typeahead
1544inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001545inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001546insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001547isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001548islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar677ee682005-01-27 14:41:15 +00001549items( {dict}) List List of key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001550join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaard8b02732005-01-14 21:48:43 +00001551keys( {dict}) List List of keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001552len( {expr}) Number the length of {expr}
1553libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001554libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1555line( {expr}) Number line nr of cursor, last line or mark
1556line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001557lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001559map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560maparg( {name}[, {mode}]) String rhs of mapping {name} in mode {mode}
1561mapcheck( {name}[, {mode}]) String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001562match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001563 Number position where {pat} matches in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001564matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001565 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001566matchlist( {expr}, {pat}[, {start}[, {count}]])
1567 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001568matchstr( {expr}, {pat}[, {start}[, {count}]])
1569 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001570max({list}) Number maximum value of items in {list}
1571min({list}) Number minumum value of items in {list}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001572mkdir({name} [, {path} [, {prot}]])
1573 Number create directory {name}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001574mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001575nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1576nr2char( {expr}) String single char with ASCII value {expr}
1577prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001578range( {expr} [, {max} [, {stride}]])
1579 List items from {expr} to {max}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001580readfile({fname} [, {binary} [, {max}]])
1581 List get list of lines from file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001582remote_expr( {server}, {string} [, {idvar}])
1583 String send expression
1584remote_foreground( {server}) Number bring Vim server to the foreground
1585remote_peek( {serverid} [, {retvar}])
1586 Number check for reply string
1587remote_read( {serverid}) String read reply string
1588remote_send( {server}, {string} [, {idvar}])
1589 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001590remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001591remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001592rename( {from}, {to}) Number rename (move) file from {from} to {to}
1593repeat( {expr}, {count}) String repeat {expr} {count} times
1594resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001595reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001596search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001597searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001598 Number search for other end of start/end pair
Bram Moolenaar071d4272004-06-13 20:20:40 +00001599server2client( {clientid}, {string})
1600 Number send reply string
1601serverlist() String get a list of available servers
1602setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1603setcmdpos( {pos}) Number set cursor position in command-line
1604setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar35c54e52005-05-20 21:25:31 +00001605setqflist( {list}[, {action}]) Number set list of quickfix items using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001606setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001607setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001608simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001609sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001610spellbadword() String badly spelled word at cursor
1611spellsuggest({word} [, {max}]) List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001612split( {expr} [, {pat} [, {keepempty}]])
1613 List make List from {pat} separated {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001614strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001615stridx( {haystack}, {needle}[, {start}])
1616 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001617string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001618strlen( {expr}) Number length of the String {expr}
1619strpart( {src}, {start}[, {len}])
1620 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001621strridx( {haystack}, {needle} [, {start}])
1622 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001624submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001625substitute( {expr}, {pat}, {sub}, {flags})
1626 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001627synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001628synIDattr( {synID}, {what} [, {mode}])
1629 String attribute {what} of syntax ID {synID}
1630synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001631system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001632taglist({expr}) List list of tags matching {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001633tempname() String name for a temporary file
1634tolower( {expr}) String the String {expr} switched to lowercase
1635toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001636tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1637 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001638type( {name}) Number type of variable {name}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001639values( {dict}) List List of values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640virtcol( {expr}) Number screen column of cursor or mark
1641visualmode( [expr]) String last visual mode used
1642winbufnr( {nr}) Number buffer number of window {nr}
1643wincol() Number window column of the cursor
1644winheight( {nr}) Number height of window {nr}
1645winline() Number window line of the cursor
1646winnr() Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001647winrestcmd() String returns command to restore window sizes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001648winwidth( {nr}) Number width of window {nr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001649writefile({list}, {fname} [, {binary}])
1650 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001651
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001652add({list}, {expr}) *add()*
1653 Append the item {expr} to List {list}. Returns the resulting
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001654 List. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001655 :let alist = add([1, 2, 3], item)
1656 :call add(mylist, "woodstock")
1657< Note that when {expr} is a List it is appended as a single
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001658 item. Use |extend()| to concatenate Lists.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001659 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001660
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001661
1662append({lnum}, {expr}) *append()*
Bram Moolenaar748bf032005-02-02 23:04:36 +00001663 When {expr} is a List: Append each item of the List as a text
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001664 line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00001665 Otherwise append {expr} as one text line below line {lnum} in
1666 the current buffer.
1667 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001668 Returns 1 for failure ({lnum} out of range or out of memory),
1669 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001670 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001671 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001672<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001673 *argc()*
1674argc() The result is the number of files in the argument list of the
1675 current window. See |arglist|.
1676
1677 *argidx()*
1678argidx() The result is the current index in the argument list. 0 is
1679 the first file. argc() - 1 is the last one. See |arglist|.
1680
1681 *argv()*
1682argv({nr}) The result is the {nr}th file in the argument list of the
1683 current window. See |arglist|. "argv(0)" is the first one.
1684 Example: >
1685 :let i = 0
1686 :while i < argc()
1687 : let f = escape(argv(i), '. ')
1688 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1689 : let i = i + 1
1690 :endwhile
1691<
1692 *browse()*
1693browse({save}, {title}, {initdir}, {default})
1694 Put up a file requester. This only works when "has("browse")"
1695 returns non-zero (only in some GUI versions).
1696 The input fields are:
1697 {save} when non-zero, select file to write
1698 {title} title for the requester
1699 {initdir} directory to start browsing in
1700 {default} default file name
1701 When the "Cancel" button is hit, something went wrong, or
1702 browsing is not possible, an empty string is returned.
1703
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001704 *browsedir()*
1705browsedir({title}, {initdir})
1706 Put up a directory requester. This only works when
1707 "has("browse")" returns non-zero (only in some GUI versions).
1708 On systems where a directory browser is not supported a file
1709 browser is used. In that case: select a file in the directory
1710 to be used.
1711 The input fields are:
1712 {title} title for the requester
1713 {initdir} directory to start browsing in
1714 When the "Cancel" button is hit, something went wrong, or
1715 browsing is not possible, an empty string is returned.
1716
Bram Moolenaar071d4272004-06-13 20:20:40 +00001717bufexists({expr}) *bufexists()*
1718 The result is a Number, which is non-zero if a buffer called
1719 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001720 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001721 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001722 exactly. The name can be:
1723 - Relative to the current directory.
1724 - A full path.
1725 - The name of a buffer with 'filetype' set to "nofile".
1726 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727 Unlisted buffers will be found.
1728 Note that help files are listed by their short name in the
1729 output of |:buffers|, but bufexists() requires using their
1730 long name to be able to find them.
1731 Use "bufexists(0)" to test for the existence of an alternate
1732 file name.
1733 *buffer_exists()*
1734 Obsolete name: buffer_exists().
1735
1736buflisted({expr}) *buflisted()*
1737 The result is a Number, which is non-zero if a buffer called
1738 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001739 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001740
1741bufloaded({expr}) *bufloaded()*
1742 The result is a Number, which is non-zero if a buffer called
1743 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001744 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001745
1746bufname({expr}) *bufname()*
1747 The result is the name of a buffer, as it is displayed by the
1748 ":ls" command.
1749 If {expr} is a Number, that buffer number's name is given.
1750 Number zero is the alternate buffer for the current window.
1751 If {expr} is a String, it is used as a |file-pattern| to match
1752 with the buffer names. This is always done like 'magic' is
1753 set and 'cpoptions' is empty. When there is more than one
1754 match an empty string is returned.
1755 "" or "%" can be used for the current buffer, "#" for the
1756 alternate buffer.
1757 A full match is preferred, otherwise a match at the start, end
1758 or middle of the buffer name is accepted.
1759 Listed buffers are found first. If there is a single match
1760 with a listed buffer, that one is returned. Next unlisted
1761 buffers are searched for.
1762 If the {expr} is a String, but you want to use it as a buffer
1763 number, force it to be a Number by adding zero to it: >
1764 :echo bufname("3" + 0)
1765< If the buffer doesn't exist, or doesn't have a name, an empty
1766 string is returned. >
1767 bufname("#") alternate buffer name
1768 bufname(3) name of buffer 3
1769 bufname("%") name of current buffer
1770 bufname("file2") name of buffer where "file2" matches.
1771< *buffer_name()*
1772 Obsolete name: buffer_name().
1773
1774 *bufnr()*
1775bufnr({expr}) The result is the number of a buffer, as it is displayed by
1776 the ":ls" command. For the use of {expr}, see |bufname()|
1777 above. If the buffer doesn't exist, -1 is returned.
1778 bufnr("$") is the last buffer: >
1779 :let last_buffer = bufnr("$")
1780< The result is a Number, which is the highest buffer number
1781 of existing buffers. Note that not all buffers with a smaller
1782 number necessarily exist, because ":bwipeout" may have removed
1783 them. Use bufexists() to test for the existence of a buffer.
1784 *buffer_number()*
1785 Obsolete name: buffer_number().
1786 *last_buffer_nr()*
1787 Obsolete name for bufnr("$"): last_buffer_nr().
1788
1789bufwinnr({expr}) *bufwinnr()*
1790 The result is a Number, which is the number of the first
1791 window associated with buffer {expr}. For the use of {expr},
1792 see |bufname()| above. If buffer {expr} doesn't exist or
1793 there is no such window, -1 is returned. Example: >
1794
1795 echo "A window containing buffer 1 is " . (bufwinnr(1))
1796
1797< The number can be used with |CTRL-W_w| and ":wincmd w"
1798 |:wincmd|.
1799
1800
1801byte2line({byte}) *byte2line()*
1802 Return the line number that contains the character at byte
1803 count {byte} in the current buffer. This includes the
1804 end-of-line character, depending on the 'fileformat' option
1805 for the current buffer. The first character has byte count
1806 one.
1807 Also see |line2byte()|, |go| and |:goto|.
1808 {not available when compiled without the |+byte_offset|
1809 feature}
1810
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001811byteidx({expr}, {nr}) *byteidx()*
1812 Return byte index of the {nr}'th character in the string
1813 {expr}. Use zero for the first character, it returns zero.
1814 This function is only useful when there are multibyte
1815 characters, otherwise the returned value is equal to {nr}.
1816 Composing characters are counted as a separate character.
1817 Example : >
1818 echo matchstr(str, ".", byteidx(str, 3))
1819< will display the fourth character. Another way to do the
1820 same: >
1821 let s = strpart(str, byteidx(str, 3))
1822 echo strpart(s, 0, byteidx(s, 1))
1823< If there are less than {nr} characters -1 is returned.
1824 If there are exactly {nr} characters the length of the string
1825 is returned.
1826
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001827call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001828 Call function {func} with the items in List {arglist} as
1829 arguments.
1830 {func} can either be a Funcref or the name of a function.
1831 a:firstline and a:lastline are set to the cursor line.
1832 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001833 {dict} is for functions with the "dict" attribute. It will be
1834 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001835
Bram Moolenaar071d4272004-06-13 20:20:40 +00001836char2nr({expr}) *char2nr()*
1837 Return number value of the first char in {expr}. Examples: >
1838 char2nr(" ") returns 32
1839 char2nr("ABC") returns 65
1840< The current 'encoding' is used. Example for "utf-8": >
1841 char2nr("á") returns 225
1842 char2nr("á"[0]) returns 195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001843< nr2char() does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001844
1845cindent({lnum}) *cindent()*
1846 Get the amount of indent for line {lnum} according the C
1847 indenting rules, as with 'cindent'.
1848 The indent is counted in spaces, the value of 'tabstop' is
1849 relevant. {lnum} is used just like in |getline()|.
1850 When {lnum} is invalid or Vim was not compiled the |+cindent|
1851 feature, -1 is returned.
1852
1853 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001854col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001855 position given with {expr}. The accepted positions are:
1856 . the cursor position
1857 $ the end of the cursor line (the result is the
1858 number of characters in the cursor line plus one)
1859 'x position of mark x (if the mark is not set, 0 is
1860 returned)
1861 For the screen column position use |virtcol()|.
1862 Note that only marks in the current file can be used.
1863 Examples: >
1864 col(".") column of cursor
1865 col("$") length of cursor line plus one
1866 col("'t") column of mark t
1867 col("'" . markname) column of mark markname
1868< The first column is 1. 0 is returned for an error.
1869 For the cursor position, when 'virtualedit' is active, the
1870 column is one higher if the cursor is after the end of the
1871 line. This can be used to obtain the column in Insert mode: >
1872 :imap <F2> <C-O>:let save_ve = &ve<CR>
1873 \<C-O>:set ve=all<CR>
1874 \<C-O>:echo col(".") . "\n" <Bar>
1875 \let &ve = save_ve<CR>
1876<
1877 *confirm()*
1878confirm({msg} [, {choices} [, {default} [, {type}]]])
1879 Confirm() offers the user a dialog, from which a choice can be
1880 made. It returns the number of the choice. For the first
1881 choice this is 1.
1882 Note: confirm() is only supported when compiled with dialog
1883 support, see |+dialog_con| and |+dialog_gui|.
1884 {msg} is displayed in a |dialog| with {choices} as the
1885 alternatives. When {choices} is missing or empty, "&OK" is
1886 used (and translated).
1887 {msg} is a String, use '\n' to include a newline. Only on
1888 some systems the string is wrapped when it doesn't fit.
1889 {choices} is a String, with the individual choices separated
1890 by '\n', e.g. >
1891 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1892< The letter after the '&' is the shortcut key for that choice.
1893 Thus you can type 'c' to select "Cancel". The shortcut does
1894 not need to be the first letter: >
1895 confirm("file has been modified", "&Save\nSave &All")
1896< For the console, the first letter of each choice is used as
1897 the default shortcut key.
1898 The optional {default} argument is the number of the choice
1899 that is made if the user hits <CR>. Use 1 to make the first
1900 choice the default one. Use 0 to not set a default. If
1901 {default} is omitted, 1 is used.
1902 The optional {type} argument gives the type of dialog. This
1903 is only used for the icon of the Win32 GUI. It can be one of
1904 these values: "Error", "Question", "Info", "Warning" or
1905 "Generic". Only the first character is relevant. When {type}
1906 is omitted, "Generic" is used.
1907 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1908 or another valid interrupt key, confirm() returns 0.
1909
1910 An example: >
1911 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1912 :if choice == 0
1913 : echo "make up your mind!"
1914 :elseif choice == 3
1915 : echo "tasteful"
1916 :else
1917 : echo "I prefer bananas myself."
1918 :endif
1919< In a GUI dialog, buttons are used. The layout of the buttons
1920 depends on the 'v' flag in 'guioptions'. If it is included,
1921 the buttons are always put vertically. Otherwise, confirm()
1922 tries to put the buttons in one horizontal line. If they
1923 don't fit, a vertical layout is used anyway. For some systems
1924 the horizontal layout is always used.
1925
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001926 *copy()*
1927copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1928 different from using {expr} directly.
1929 When {expr} is a List a shallow copy is created. This means
1930 that the original List can be changed without changing the
1931 copy, and vise versa. But the items are identical, thus
1932 changing an item changes the contents of both Lists. Also see
1933 |deepcopy()|.
1934
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001935count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001936 Return the number of times an item with value {expr} appears
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001937 in List or Dictionary {comp}.
1938 If {start} is given then start with the item with this index.
1939 {start} can only be used with a List.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001940 When {ic} is given and it's non-zero then case is ignored.
1941
1942
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943 *cscope_connection()*
1944cscope_connection([{num} , {dbpath} [, {prepend}]])
1945 Checks for the existence of a |cscope| connection. If no
1946 parameters are specified, then the function returns:
1947 0, if cscope was not available (not compiled in), or
1948 if there are no cscope connections;
1949 1, if there is at least one cscope connection.
1950
1951 If parameters are specified, then the value of {num}
1952 determines how existence of a cscope connection is checked:
1953
1954 {num} Description of existence check
1955 ----- ------------------------------
1956 0 Same as no parameters (e.g., "cscope_connection()").
1957 1 Ignore {prepend}, and use partial string matches for
1958 {dbpath}.
1959 2 Ignore {prepend}, and use exact string matches for
1960 {dbpath}.
1961 3 Use {prepend}, use partial string matches for both
1962 {dbpath} and {prepend}.
1963 4 Use {prepend}, use exact string matches for both
1964 {dbpath} and {prepend}.
1965
1966 Note: All string comparisons are case sensitive!
1967
1968 Examples. Suppose we had the following (from ":cs show"): >
1969
1970 # pid database name prepend path
1971 0 27664 cscope.out /usr/local
1972<
1973 Invocation Return Val ~
1974 ---------- ---------- >
1975 cscope_connection() 1
1976 cscope_connection(1, "out") 1
1977 cscope_connection(2, "out") 0
1978 cscope_connection(3, "out") 0
1979 cscope_connection(3, "out", "local") 1
1980 cscope_connection(4, "out") 0
1981 cscope_connection(4, "out", "local") 0
1982 cscope_connection(4, "cscope.out", "/usr/local") 1
1983<
1984cursor({lnum}, {col}) *cursor()*
1985 Positions the cursor at the column {col} in the line {lnum}.
1986 Does not change the jumplist.
1987 If {lnum} is greater than the number of lines in the buffer,
1988 the cursor will be positioned at the last line in the buffer.
1989 If {lnum} is zero, the cursor will stay in the current line.
1990 If {col} is greater than the number of characters in the line,
1991 the cursor will be positioned at the last character in the
1992 line.
1993 If {col} is zero, the cursor will stay in the current column.
1994
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001995
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001996deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001997 Make a copy of {expr}. For Numbers and Strings this isn't
1998 different from using {expr} directly.
1999 When {expr} is a List a full copy is created. This means
2000 that the original List can be changed without changing the
2001 copy, and vise versa. When an item is a List, a copy for it
2002 is made, recursively. Thus changing an item in the copy does
2003 not change the contents of the original List.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002004 When {noref} is omitted or zero a contained List or Dictionary
2005 is only copied once. All references point to this single
2006 copy. With {noref} set to 1 every occurrence of a List or
2007 Dictionary results in a new copy. This also means that a
2008 cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002009 *E724*
2010 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002011 that refers back to a higher level making a deep copy with
2012 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002013 Also see |copy()|.
2014
2015delete({fname}) *delete()*
2016 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002017 which is 0 if the file was deleted successfully, and non-zero
2018 when the deletion failed.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002019 Use |remove()| to delete an item from a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002020
2021 *did_filetype()*
2022did_filetype() Returns non-zero when autocommands are being executed and the
2023 FileType event has been triggered at least once. Can be used
2024 to avoid triggering the FileType event again in the scripts
2025 that detect the file type. |FileType|
2026 When editing another file, the counter is reset, thus this
2027 really checks if the FileType event has been triggered for the
2028 current buffer. This allows an autocommand that starts
2029 editing another buffer to set 'filetype' and load a syntax
2030 file.
2031
Bram Moolenaar47136d72004-10-12 20:02:24 +00002032diff_filler({lnum}) *diff_filler()*
2033 Returns the number of filler lines above line {lnum}.
2034 These are the lines that were inserted at this point in
2035 another diff'ed window. These filler lines are shown in the
2036 display but don't exist in the buffer.
2037 {lnum} is used like with |getline()|. Thus "." is the current
2038 line, "'m" mark m, etc.
2039 Returns 0 if the current window is not in diff mode.
2040
2041diff_hlID({lnum}, {col}) *diff_hlID()*
2042 Returns the highlight ID for diff mode at line {lnum} column
2043 {col} (byte index). When the current line does not have a
2044 diff change zero is returned.
2045 {lnum} is used like with |getline()|. Thus "." is the current
2046 line, "'m" mark m, etc.
2047 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2048 line.
2049 The highlight ID can be used with |synIDattr()| to obtain
2050 syntax information about the highlighting.
2051
Bram Moolenaar13065c42005-01-08 16:08:21 +00002052empty({expr}) *empty()*
2053 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002054 A List or Dictionary is empty when it does not have any items.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002055 A Number is empty when its value is zero.
2056 For a long List this is much faster then comparing the length
2057 with zero.
2058
Bram Moolenaar071d4272004-06-13 20:20:40 +00002059escape({string}, {chars}) *escape()*
2060 Escape the characters in {chars} that occur in {string} with a
2061 backslash. Example: >
2062 :echo escape('c:\program files\vim', ' \')
2063< results in: >
2064 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002065
2066< *eval()*
2067eval({string}) Evaluate {string} and return the result. Especially useful to
2068 turn the result of |string()| back into the original value.
2069 This works for Numbers, Strings and composites of them.
2070 Also works for Funcrefs that refer to existing functions.
2071
Bram Moolenaar071d4272004-06-13 20:20:40 +00002072eventhandler() *eventhandler()*
2073 Returns 1 when inside an event handler. That is that Vim got
2074 interrupted while waiting for the user to type a character,
2075 e.g., when dropping a file on Vim. This means interactive
2076 commands cannot be used. Otherwise zero is returned.
2077
2078executable({expr}) *executable()*
2079 This function checks if an executable with the name {expr}
2080 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002081 arguments.
2082 executable() uses the value of $PATH and/or the normal
2083 searchpath for programs. *PATHEXT*
2084 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2085 optionally be included. Then the extensions in $PATHEXT are
2086 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2087 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2088 used. A dot by itself can be used in $PATHEXT to try using
2089 the name without an extension. When 'shell' looks like a
2090 Unix shell, then the name is also tried without adding an
2091 extension.
2092 On MS-DOS and MS-Windows it only checks if the file exists and
2093 is not a directory, not if it's really executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002094 The result is a Number:
2095 1 exists
2096 0 does not exist
2097 -1 not implemented on this system
2098
2099 *exists()*
2100exists({expr}) The result is a Number, which is non-zero if {expr} is
2101 defined, zero otherwise. The {expr} argument is a string,
2102 which contains one of these:
2103 &option-name Vim option (only checks if it exists,
2104 not if it really works)
2105 +option-name Vim option that works.
2106 $ENVNAME environment variable (could also be
2107 done by comparing with an empty
2108 string)
2109 *funcname built-in function (see |functions|)
2110 or user defined function (see
2111 |user-functions|).
2112 varname internal variable (see
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002113 |internal-variables|). Also works
2114 for |curly-braces-names|, Dictionary
2115 entries, List items, etc. Beware that
2116 this may cause functions to be
2117 invoked cause an error message for an
2118 invalid expression.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002119 :cmdname Ex command: built-in command, user
2120 command or command modifier |:command|.
2121 Returns:
2122 1 for match with start of a command
2123 2 full match with a command
2124 3 matches several user commands
2125 To check for a supported command
2126 always check the return value to be 2.
2127 #event autocommand defined for this event
2128 #event#pattern autocommand defined for this event and
2129 pattern (the pattern is taken
2130 literally and compared to the
2131 autocommand patterns character by
2132 character)
2133 For checking for a supported feature use |has()|.
2134
2135 Examples: >
2136 exists("&shortname")
2137 exists("$HOSTNAME")
2138 exists("*strftime")
2139 exists("*s:MyFunc")
2140 exists("bufcount")
2141 exists(":Make")
2142 exists("#CursorHold");
2143 exists("#BufReadPre#*.gz")
2144< There must be no space between the symbol (&/$/*/#) and the
2145 name.
2146 Note that the argument must be a string, not the name of the
2147 variable itself! For example: >
2148 exists(bufcount)
2149< This doesn't check for existence of the "bufcount" variable,
2150 but gets the contents of "bufcount", and checks if that
2151 exists.
2152
2153expand({expr} [, {flag}]) *expand()*
2154 Expand wildcards and the following special keywords in {expr}.
2155 The result is a String.
2156
2157 When there are several matches, they are separated by <NL>
2158 characters. [Note: in version 5.0 a space was used, which
2159 caused problems when a file name contains a space]
2160
2161 If the expansion fails, the result is an empty string. A name
2162 for a non-existing file is not included.
2163
2164 When {expr} starts with '%', '#' or '<', the expansion is done
2165 like for the |cmdline-special| variables with their associated
2166 modifiers. Here is a short overview:
2167
2168 % current file name
2169 # alternate file name
2170 #n alternate file name n
2171 <cfile> file name under the cursor
2172 <afile> autocmd file name
2173 <abuf> autocmd buffer number (as a String!)
2174 <amatch> autocmd matched name
2175 <sfile> sourced script file name
2176 <cword> word under the cursor
2177 <cWORD> WORD under the cursor
2178 <client> the {clientid} of the last received
2179 message |server2client()|
2180 Modifiers:
2181 :p expand to full path
2182 :h head (last path component removed)
2183 :t tail (last path component only)
2184 :r root (one extension removed)
2185 :e extension only
2186
2187 Example: >
2188 :let &tags = expand("%:p:h") . "/tags"
2189< Note that when expanding a string that starts with '%', '#' or
2190 '<', any following text is ignored. This does NOT work: >
2191 :let doesntwork = expand("%:h.bak")
2192< Use this: >
2193 :let doeswork = expand("%:h") . ".bak"
2194< Also note that expanding "<cfile>" and others only returns the
2195 referenced file name without further expansion. If "<cfile>"
2196 is "~/.cshrc", you need to do another expand() to have the
2197 "~/" expanded into the path of the home directory: >
2198 :echo expand(expand("<cfile>"))
2199<
2200 There cannot be white space between the variables and the
2201 following modifier. The |fnamemodify()| function can be used
2202 to modify normal file names.
2203
2204 When using '%' or '#', and the current or alternate file name
2205 is not defined, an empty string is used. Using "%:p" in a
2206 buffer with no name, results in the current directory, with a
2207 '/' added.
2208
2209 When {expr} does not start with '%', '#' or '<', it is
2210 expanded like a file name is expanded on the command line.
2211 'suffixes' and 'wildignore' are used, unless the optional
2212 {flag} argument is given and it is non-zero. Names for
2213 non-existing files are included.
2214
2215 Expand() can also be used to expand variables and environment
2216 variables that are only known in a shell. But this can be
2217 slow, because a shell must be started. See |expr-env-expand|.
2218 The expanded variable is still handled like a list of file
2219 names. When an environment variable cannot be expanded, it is
2220 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2221 "$FOOBAR".
2222
2223 See |glob()| for finding existing files. See |system()| for
2224 getting the raw output of an external command.
2225
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002226extend({expr1}, {expr2} [, {expr3}]) *extend()*
2227 {expr1} and {expr2} must be both Lists or both Dictionaries.
2228
2229 If they are Lists: Append {expr2} to {expr1}.
2230 If {expr3} is given insert the items of {expr2} before item
2231 {expr3} in {expr1}. When {expr3} is zero insert before the
2232 first item. When {expr3} is equal to len({expr1}) then
2233 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002234 Examples: >
2235 :echo sort(extend(mylist, [7, 5]))
2236 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002237< Use |add()| to concatenate one item to a list. To concatenate
2238 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002239 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002240<
2241 If they are Dictionaries:
2242 Add all entries from {expr2} to {expr1}.
2243 If a key exists in both {expr1} and {expr2} then {expr3} is
2244 used to decide what to do:
2245 {expr3} = "keep": keep the value of {expr1}
2246 {expr3} = "force": use the value of {expr2}
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00002247 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002248 When {expr3} is omitted then "force" is assumed.
2249
2250 {expr1} is changed when {expr2} is not empty. If necessary
2251 make a copy of {expr1} first.
2252 {expr2} remains unchanged.
2253 Returns {expr1}.
2254
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002255
Bram Moolenaar071d4272004-06-13 20:20:40 +00002256filereadable({file}) *filereadable()*
2257 The result is a Number, which is TRUE when a file with the
2258 name {file} exists, and can be read. If {file} doesn't exist,
2259 or is a directory, the result is FALSE. {file} is any
2260 expression, which is used as a String.
2261 *file_readable()*
2262 Obsolete name: file_readable().
2263
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002264
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002265filter({expr}, {string}) *filter()*
2266 {expr} must be a List or a Dictionary.
2267 For each item in {expr} evaluate {string} and when the result
2268 is zero remove the item from the List or Dictionary.
2269 Inside {string} |v:val| has the value of the current item.
2270 For a Dictionary |v:key| has the key of the current item.
2271 Examples: >
2272 :call filter(mylist, 'v:val !~ "OLD"')
2273< Removes the items where "OLD" appears. >
2274 :call filter(mydict, 'v:key >= 8')
2275< Removes the items with a key below 8. >
2276 :call filter(var, 0)
Bram Moolenaard8b02732005-01-14 21:48:43 +00002277< Removes all the items, thus clears the List or Dictionary.
2278
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002279 Note that {string} is the result of expression and is then
2280 used as an expression again. Often it is good to use a
2281 |literal-string| to avoid having to double backslashes.
2282
2283 The operation is done in-place. If you want a List or
2284 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00002285 :let l = filter(copy(mylist), '& =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002286
2287< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002288
2289
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002290finddir({name}[, {path}[, {count}]]) *finddir()*
2291 Find directory {name} in {path}.
2292 If {path} is omitted or empty then 'path' is used.
2293 If the optional {count} is given, find {count}'s occurrence of
2294 {name} in {path}.
2295 This is quite similar to the ex-command |:find|.
2296 When the found directory is below the current directory a
2297 relative path is returned. Otherwise a full path is returned.
2298 Example: >
2299 :echo findfile("tags.vim", ".;")
2300< Searches from the current directory upwards until it finds
2301 the file "tags.vim".
2302 {only available when compiled with the +file_in_path feature}
2303
2304findfile({name}[, {path}[, {count}]]) *findfile()*
2305 Just like |finddir()|, but find a file instead of a directory.
2306
Bram Moolenaar071d4272004-06-13 20:20:40 +00002307filewritable({file}) *filewritable()*
2308 The result is a Number, which is 1 when a file with the
2309 name {file} exists, and can be written. If {file} doesn't
2310 exist, or is not writable, the result is 0. If (file) is a
2311 directory, and we can write to it, the result is 2.
2312
2313fnamemodify({fname}, {mods}) *fnamemodify()*
2314 Modify file name {fname} according to {mods}. {mods} is a
2315 string of characters like it is used for file names on the
2316 command line. See |filename-modifiers|.
2317 Example: >
2318 :echo fnamemodify("main.c", ":p:h")
2319< results in: >
2320 /home/mool/vim/vim/src
2321< Note: Environment variables and "~" don't work in {fname}, use
2322 |expand()| first then.
2323
2324foldclosed({lnum}) *foldclosed()*
2325 The result is a Number. If the line {lnum} is in a closed
2326 fold, the result is the number of the first line in that fold.
2327 If the line {lnum} is not in a closed fold, -1 is returned.
2328
2329foldclosedend({lnum}) *foldclosedend()*
2330 The result is a Number. If the line {lnum} is in a closed
2331 fold, the result is the number of the last line in that fold.
2332 If the line {lnum} is not in a closed fold, -1 is returned.
2333
2334foldlevel({lnum}) *foldlevel()*
2335 The result is a Number, which is the foldlevel of line {lnum}
2336 in the current buffer. For nested folds the deepest level is
2337 returned. If there is no fold at line {lnum}, zero is
2338 returned. It doesn't matter if the folds are open or closed.
2339 When used while updating folds (from 'foldexpr') -1 is
2340 returned for lines where folds are still to be updated and the
2341 foldlevel is unknown. As a special case the level of the
2342 previous line is usually available.
2343
2344 *foldtext()*
2345foldtext() Returns a String, to be displayed for a closed fold. This is
2346 the default function used for the 'foldtext' option and should
2347 only be called from evaluating 'foldtext'. It uses the
2348 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2349 The returned string looks like this: >
2350 +-- 45 lines: abcdef
2351< The number of dashes depends on the foldlevel. The "45" is
2352 the number of lines in the fold. "abcdef" is the text in the
2353 first non-blank line of the fold. Leading white space, "//"
2354 or "/*" and the text from the 'foldmarker' and 'commentstring'
2355 options is removed.
2356 {not available when compiled without the |+folding| feature}
2357
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002358foldtextresult({lnum}) *foldtextresult()*
2359 Returns the text that is displayed for the closed fold at line
2360 {lnum}. Evaluates 'foldtext' in the appropriate context.
2361 When there is no closed fold at {lnum} an empty string is
2362 returned.
2363 {lnum} is used like with |getline()|. Thus "." is the current
2364 line, "'m" mark m, etc.
2365 Useful when exporting folded text, e.g., to HTML.
2366 {not available when compiled without the |+folding| feature}
2367
Bram Moolenaar071d4272004-06-13 20:20:40 +00002368 *foreground()*
2369foreground() Move the Vim window to the foreground. Useful when sent from
2370 a client to a Vim server. |remote_send()|
2371 On Win32 systems this might not work, the OS does not always
2372 allow a window to bring itself to the foreground. Use
2373 |remote_foreground()| instead.
2374 {only in the Win32, Athena, Motif and GTK GUI versions and the
2375 Win32 console version}
2376
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002377
Bram Moolenaar13065c42005-01-08 16:08:21 +00002378function({name}) *function()* *E700*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002379 Return a Funcref variable that refers to function {name}.
2380 {name} can be a user defined function or an internal function.
2381
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002382
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002383garbagecollect() *garbagecollect()*
2384 Cleanup unused Lists and Dictionaries that have circular
2385 references. There is hardly ever a need to invoke this
2386 function, as it is automatically done when Vim runs out of
2387 memory or is waiting for the user to press a key after
2388 'updatetime'. Items without circular references are always
2389 freed when they become unused.
2390 This is useful if you have deleted a very big List and/or
2391 Dictionary with circular references in a script that runs for
2392 a long time.
2393
Bram Moolenaar677ee682005-01-27 14:41:15 +00002394get({list}, {idx} [, {default}]) *get()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002395 Get item {idx} from List {list}. When this item is not
2396 available return {default}. Return zero when {default} is
2397 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002398get({dict}, {key} [, {default}])
2399 Get item with key {key} from Dictionary {dict}. When this
2400 item is not available return {default}. Return zero when
2401 {default} is omitted.
2402
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002403
2404getbufvar({expr}, {varname}) *getbufvar()*
2405 The result is the value of option or local buffer variable
2406 {varname} in buffer {expr}. Note that the name without "b:"
2407 must be used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002408 This also works for a global or buffer-local option, but it
2409 doesn't work for a global variable, window-local variable or
2410 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002411 For the use of {expr}, see |bufname()| above.
2412 When the buffer or variable doesn't exist an empty string is
2413 returned, there is no error message.
2414 Examples: >
2415 :let bufmodified = getbufvar(1, "&mod")
2416 :echo "todo myvar = " . getbufvar("todo", "myvar")
2417<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002418getchar([expr]) *getchar()*
2419 Get a single character from the user. If it is an 8-bit
2420 character, the result is a number. Otherwise a String is
2421 returned with the encoded character. For a special key it's a
2422 sequence of bytes starting with 0x80 (decimal: 128).
2423 If [expr] is omitted, wait until a character is available.
2424 If [expr] is 0, only get a character when one is available.
2425 If [expr] is 1, only check if a character is available, it is
2426 not consumed. If a normal character is
2427 available, it is returned, otherwise a
2428 non-zero value is returned.
2429 If a normal character available, it is returned as a Number.
2430 Use nr2char() to convert it to a String.
2431 The returned value is zero if no character is available.
2432 The returned value is a string of characters for special keys
2433 and when a modifier (shift, control, alt) was used.
2434 There is no prompt, you will somehow have to make clear to the
2435 user that a character has to be typed.
2436 There is no mapping for the character.
2437 Key codes are replaced, thus when the user presses the <Del>
2438 key you get the code for the <Del> key, not the raw character
2439 sequence. Examples: >
2440 getchar() == "\<Del>"
2441 getchar() == "\<S-Left>"
2442< This example redefines "f" to ignore case: >
2443 :nmap f :call FindChar()<CR>
2444 :function FindChar()
2445 : let c = nr2char(getchar())
2446 : while col('.') < col('$') - 1
2447 : normal l
2448 : if getline('.')[col('.') - 1] ==? c
2449 : break
2450 : endif
2451 : endwhile
2452 :endfunction
2453
2454getcharmod() *getcharmod()*
2455 The result is a Number which is the state of the modifiers for
2456 the last obtained character with getchar() or in another way.
2457 These values are added together:
2458 2 shift
2459 4 control
2460 8 alt (meta)
2461 16 mouse double click
2462 32 mouse triple click
2463 64 mouse quadruple click
2464 128 Macintosh only: command
2465 Only the modifiers that have not been included in the
2466 character itself are obtained. Thus Shift-a results in "A"
2467 with no modifier.
2468
Bram Moolenaar071d4272004-06-13 20:20:40 +00002469getcmdline() *getcmdline()*
2470 Return the current command-line. Only works when the command
2471 line is being edited, thus requires use of |c_CTRL-\_e| or
2472 |c_CTRL-R_=|.
2473 Example: >
2474 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
2475< Also see |getcmdpos()| and |setcmdpos()|.
2476
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002477getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002478 Return the position of the cursor in the command line as a
2479 byte count. The first column is 1.
2480 Only works when editing the command line, thus requires use of
2481 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
2482 Also see |setcmdpos()| and |getcmdline()|.
2483
2484 *getcwd()*
2485getcwd() The result is a String, which is the name of the current
2486 working directory.
2487
2488getfsize({fname}) *getfsize()*
2489 The result is a Number, which is the size in bytes of the
2490 given file {fname}.
2491 If {fname} is a directory, 0 is returned.
2492 If the file {fname} can't be found, -1 is returned.
2493
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002494getfontname([{name}]) *getfontname()*
2495 Without an argument returns the name of the normal font being
2496 used. Like what is used for the Normal highlight group
2497 |hl-Normal|.
2498 With an argument a check is done whether {name} is a valid
2499 font name. If not then an empty string is returned.
2500 Otherwise the actual font name is returned, or {name} if the
2501 GUI does not support obtaining the real name.
2502 Only works when the GUI is running, thus not you your vimrc or
2503 Note that the GTK 2 GUI accepts any font name, thus checking
2504 for a valid name does not work.
2505 gvimrc file. Use the |GUIEnter| autocommand to use this
2506 function just after the GUI has started.
2507
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002508getfperm({fname}) *getfperm()*
2509 The result is a String, which is the read, write, and execute
2510 permissions of the given file {fname}.
2511 If {fname} does not exist or its directory cannot be read, an
2512 empty string is returned.
2513 The result is of the form "rwxrwxrwx", where each group of
2514 "rwx" flags represent, in turn, the permissions of the owner
2515 of the file, the group the file belongs to, and other users.
2516 If a user does not have a given permission the flag for this
2517 is replaced with the string "-". Example: >
2518 :echo getfperm("/etc/passwd")
2519< This will hopefully (from a security point of view) display
2520 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00002521
Bram Moolenaar071d4272004-06-13 20:20:40 +00002522getftime({fname}) *getftime()*
2523 The result is a Number, which is the last modification time of
2524 the given file {fname}. The value is measured as seconds
2525 since 1st Jan 1970, and may be passed to strftime(). See also
2526 |localtime()| and |strftime()|.
2527 If the file {fname} can't be found -1 is returned.
2528
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002529getftype({fname}) *getftype()*
2530 The result is a String, which is a description of the kind of
2531 file of the given file {fname}.
2532 If {fname} does not exist an empty string is returned.
2533 Here is a table over different kinds of files and their
2534 results:
2535 Normal file "file"
2536 Directory "dir"
2537 Symbolic link "link"
2538 Block device "bdev"
2539 Character device "cdev"
2540 Socket "socket"
2541 FIFO "fifo"
2542 All other "other"
2543 Example: >
2544 getftype("/home")
2545< Note that a type such as "link" will only be returned on
2546 systems that support it. On some systems only "dir" and
2547 "file" are returned.
2548
Bram Moolenaar071d4272004-06-13 20:20:40 +00002549 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002550getline({lnum} [, {end}])
2551 Without {end} the result is a String, which is line {lnum}
2552 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002553 getline(1)
2554< When {lnum} is a String that doesn't start with a
2555 digit, line() is called to translate the String into a Number.
2556 To get the line under the cursor: >
2557 getline(".")
2558< When {lnum} is smaller than 1 or bigger than the number of
2559 lines in the buffer, an empty string is returned.
2560
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002561 When {end} is given the result is a List where each item is a
2562 line from the current buffer in the range {lnum} to {end},
2563 including line {end}.
2564 {end} is used in the same way as {lnum}.
2565 Non-existing lines are silently omitted.
2566 When {end} is before {lnum} an error is given.
2567 Example: >
2568 :let start = line('.')
2569 :let end = search("^$") - 1
2570 :let lines = getline(start, end)
2571
2572
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002573getqflist() *getqflist()*
2574 Returns a list with all the current quickfix errors. Each
2575 list item is a dictionary with these entries:
2576 bufnr number of buffer that has the file name, use
2577 bufname() to get the name
2578 lnum line number in the buffer (first line is 1)
2579 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00002580 vcol non-zero: "col" is visual column
2581 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002582 nr error number
2583 text description of the error
2584 type type of the error, 'E', '1', etc.
2585 valid non-zero: recognized error message
2586
2587 Useful application: Find pattern matches in multiple files and
2588 do something with them: >
2589 :vimgrep /theword/jg *.c
2590 :for d in getqflist()
2591 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
2592 :endfor
2593
2594
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002595getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002596 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002597 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002598 :let cliptext = getreg('*')
2599< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002600 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002601 getreg('=', 1) returns the expression itself, so that it can
2602 be restored with |setreg()|. For other registers the extra
2603 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002604 If {regname} is not specified, |v:register| is used.
2605
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002606
Bram Moolenaar071d4272004-06-13 20:20:40 +00002607getregtype([{regname}]) *getregtype()*
2608 The result is a String, which is type of register {regname}.
2609 The value will be one of:
2610 "v" for |characterwise| text
2611 "V" for |linewise| text
2612 "<CTRL-V>{width}" for |blockwise-visual| text
2613 0 for an empty or unknown register
2614 <CTRL-V> is one character with value 0x16.
2615 If {regname} is not specified, |v:register| is used.
2616
2617 *getwinposx()*
2618getwinposx() The result is a Number, which is the X coordinate in pixels of
2619 the left hand side of the GUI Vim window. The result will be
2620 -1 if the information is not available.
2621
2622 *getwinposy()*
2623getwinposy() The result is a Number, which is the Y coordinate in pixels of
2624 the top of the GUI Vim window. The result will be -1 if the
2625 information is not available.
2626
2627getwinvar({nr}, {varname}) *getwinvar()*
2628 The result is the value of option or local window variable
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002629 {varname} in window {nr}. When {nr} is zero the current
2630 window is used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002631 This also works for a global option, buffer-local option and
2632 window-local option, but it doesn't work for a global variable
2633 or buffer-local variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002634 Note that the name without "w:" must be used.
2635 Examples: >
2636 :let list_is_on = getwinvar(2, '&list')
2637 :echo "myvar = " . getwinvar(1, 'myvar')
2638<
2639 *glob()*
2640glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2641 When there are several matches, they are separated by <NL>
2642 characters.
2643 If the expansion fails, the result is an empty string.
2644 A name for a non-existing file is not included.
2645
2646 For most systems backticks can be used to get files names from
2647 any external command. Example: >
2648 :let tagfiles = glob("`find . -name tags -print`")
2649 :let &tags = substitute(tagfiles, "\n", ",", "g")
2650< The result of the program inside the backticks should be one
2651 item per line. Spaces inside an item are allowed.
2652
2653 See |expand()| for expanding special Vim variables. See
2654 |system()| for getting the raw output of an external command.
2655
2656globpath({path}, {expr}) *globpath()*
2657 Perform glob() on all directories in {path} and concatenate
2658 the results. Example: >
2659 :echo globpath(&rtp, "syntax/c.vim")
2660< {path} is a comma-separated list of directory names. Each
2661 directory name is prepended to {expr} and expanded like with
2662 glob(). A path separator is inserted when needed.
2663 To add a comma inside a directory name escape it with a
2664 backslash. Note that on MS-Windows a directory may have a
2665 trailing backslash, remove it if you put a comma after it.
2666 If the expansion fails for one of the directories, there is no
2667 error message.
2668 The 'wildignore' option applies: Names matching one of the
2669 patterns in 'wildignore' will be skipped.
2670
2671 *has()*
2672has({feature}) The result is a Number, which is 1 if the feature {feature} is
2673 supported, zero otherwise. The {feature} argument is a
2674 string. See |feature-list| below.
2675 Also see |exists()|.
2676
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002677
2678has_key({dict}, {key}) *has_key()*
2679 The result is a Number, which is 1 if Dictionary {dict} has an
2680 entry with key {key}. Zero otherwise.
2681
2682
Bram Moolenaar071d4272004-06-13 20:20:40 +00002683hasmapto({what} [, {mode}]) *hasmapto()*
2684 The result is a Number, which is 1 if there is a mapping that
2685 contains {what} in somewhere in the rhs (what it is mapped to)
2686 and this mapping exists in one of the modes indicated by
2687 {mode}.
2688 Both the global mappings and the mappings local to the current
2689 buffer are checked for a match.
2690 If no matching mapping is found 0 is returned.
2691 The following characters are recognized in {mode}:
2692 n Normal mode
2693 v Visual mode
2694 o Operator-pending mode
2695 i Insert mode
2696 l Language-Argument ("r", "f", "t", etc.)
2697 c Command-line mode
2698 When {mode} is omitted, "nvo" is used.
2699
2700 This function is useful to check if a mapping already exists
2701 to a function in a Vim script. Example: >
2702 :if !hasmapto('\ABCdoit')
2703 : map <Leader>d \ABCdoit
2704 :endif
2705< This installs the mapping to "\ABCdoit" only if there isn't
2706 already a mapping to "\ABCdoit".
2707
2708histadd({history}, {item}) *histadd()*
2709 Add the String {item} to the history {history} which can be
2710 one of: *hist-names*
2711 "cmd" or ":" command line history
2712 "search" or "/" search pattern history
2713 "expr" or "=" typed expression history
2714 "input" or "@" input line history
2715 If {item} does already exist in the history, it will be
2716 shifted to become the newest entry.
2717 The result is a Number: 1 if the operation was successful,
2718 otherwise 0 is returned.
2719
2720 Example: >
2721 :call histadd("input", strftime("%Y %b %d"))
2722 :let date=input("Enter date: ")
2723< This function is not available in the |sandbox|.
2724
2725histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002726 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002727 for the possible values of {history}.
2728
2729 If the parameter {item} is given as String, this is seen
2730 as regular expression. All entries matching that expression
2731 will be removed from the history (if there are any).
2732 Upper/lowercase must match, unless "\c" is used |/\c|.
2733 If {item} is a Number, it will be interpreted as index, see
2734 |:history-indexing|. The respective entry will be removed
2735 if it exists.
2736
2737 The result is a Number: 1 for a successful operation,
2738 otherwise 0 is returned.
2739
2740 Examples:
2741 Clear expression register history: >
2742 :call histdel("expr")
2743<
2744 Remove all entries starting with "*" from the search history: >
2745 :call histdel("/", '^\*')
2746<
2747 The following three are equivalent: >
2748 :call histdel("search", histnr("search"))
2749 :call histdel("search", -1)
2750 :call histdel("search", '^'.histget("search", -1).'$')
2751<
2752 To delete the last search pattern and use the last-but-one for
2753 the "n" command and 'hlsearch': >
2754 :call histdel("search", -1)
2755 :let @/ = histget("search", -1)
2756
2757histget({history} [, {index}]) *histget()*
2758 The result is a String, the entry with Number {index} from
2759 {history}. See |hist-names| for the possible values of
2760 {history}, and |:history-indexing| for {index}. If there is
2761 no such entry, an empty String is returned. When {index} is
2762 omitted, the most recent item from the history is used.
2763
2764 Examples:
2765 Redo the second last search from history. >
2766 :execute '/' . histget("search", -2)
2767
2768< Define an Ex command ":H {num}" that supports re-execution of
2769 the {num}th entry from the output of |:history|. >
2770 :command -nargs=1 H execute histget("cmd", 0+<args>)
2771<
2772histnr({history}) *histnr()*
2773 The result is the Number of the current entry in {history}.
2774 See |hist-names| for the possible values of {history}.
2775 If an error occurred, -1 is returned.
2776
2777 Example: >
2778 :let inp_index = histnr("expr")
2779<
2780hlexists({name}) *hlexists()*
2781 The result is a Number, which is non-zero if a highlight group
2782 called {name} exists. This is when the group has been
2783 defined in some way. Not necessarily when highlighting has
2784 been defined for it, it may also have been used for a syntax
2785 item.
2786 *highlight_exists()*
2787 Obsolete name: highlight_exists().
2788
2789 *hlID()*
2790hlID({name}) The result is a Number, which is the ID of the highlight group
2791 with name {name}. When the highlight group doesn't exist,
2792 zero is returned.
2793 This can be used to retrieve information about the highlight
2794 group. For example, to get the background color of the
2795 "Comment" group: >
2796 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
2797< *highlightID()*
2798 Obsolete name: highlightID().
2799
2800hostname() *hostname()*
2801 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002802 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00002803 256 characters long are truncated.
2804
2805iconv({expr}, {from}, {to}) *iconv()*
2806 The result is a String, which is the text {expr} converted
2807 from encoding {from} to encoding {to}.
2808 When the conversion fails an empty string is returned.
2809 The encoding names are whatever the iconv() library function
2810 can accept, see ":!man 3 iconv".
2811 Most conversions require Vim to be compiled with the |+iconv|
2812 feature. Otherwise only UTF-8 to latin1 conversion and back
2813 can be done.
2814 This can be used to display messages with special characters,
2815 no matter what 'encoding' is set to. Write the message in
2816 UTF-8 and use: >
2817 echo iconv(utf8_str, "utf-8", &enc)
2818< Note that Vim uses UTF-8 for all Unicode encodings, conversion
2819 from/to UCS-2 is automatically changed to use UTF-8. You
2820 cannot use UCS-2 in a string anyway, because of the NUL bytes.
2821 {only available when compiled with the +multi_byte feature}
2822
2823 *indent()*
2824indent({lnum}) The result is a Number, which is indent of line {lnum} in the
2825 current buffer. The indent is counted in spaces, the value
2826 of 'tabstop' is relevant. {lnum} is used just like in
2827 |getline()|.
2828 When {lnum} is invalid -1 is returned.
2829
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002830
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002831index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002832 Return the lowest index in List {list} where the item has a
2833 value equal to {expr}.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002834 If {start} is given then start looking at the item with index
2835 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002836 When {ic} is given and it is non-zero, ignore case. Otherwise
2837 case must match.
2838 -1 is returned when {expr} is not found in {list}.
2839 Example: >
2840 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002841 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002842
2843
Bram Moolenaar071d4272004-06-13 20:20:40 +00002844input({prompt} [, {text}]) *input()*
2845 The result is a String, which is whatever the user typed on
2846 the command-line. The parameter is either a prompt string, or
2847 a blank string (for no prompt). A '\n' can be used in the
2848 prompt to start a new line. The highlighting set with
2849 |:echohl| is used for the prompt. The input is entered just
2850 like a command-line, with the same editing commands and
2851 mappings. There is a separate history for lines typed for
2852 input().
2853 If the optional {text} is present, this is used for the
2854 default reply, as if the user typed this.
2855 NOTE: This must not be used in a startup file, for the
2856 versions that only run in GUI mode (e.g., the Win32 GUI).
2857 Note: When input() is called from within a mapping it will
2858 consume remaining characters from that mapping, because a
2859 mapping is handled like the characters were typed.
2860 Use |inputsave()| before input() and |inputrestore()|
2861 after input() to avoid that. Another solution is to avoid
2862 that further characters follow in the mapping, e.g., by using
2863 |:execute| or |:normal|.
2864
2865 Example: >
2866 :if input("Coffee or beer? ") == "beer"
2867 : echo "Cheers!"
2868 :endif
2869< Example with default text: >
2870 :let color = input("Color? ", "white")
2871< Example with a mapping: >
2872 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
2873 :function GetFoo()
2874 : call inputsave()
2875 : let g:Foo = input("enter search pattern: ")
2876 : call inputrestore()
2877 :endfunction
2878
2879inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
2880 Like input(), but when the GUI is running and text dialogs are
2881 supported, a dialog window pops up to input the text.
2882 Example: >
2883 :let n = inputdialog("value for shiftwidth", &sw)
2884 :if n != ""
2885 : let &sw = n
2886 :endif
2887< When the dialog is cancelled {cancelreturn} is returned. When
2888 omitted an empty string is returned.
2889 Hitting <Enter> works like pressing the OK button. Hitting
2890 <Esc> works like pressing the Cancel button.
2891
2892inputrestore() *inputrestore()*
2893 Restore typeahead that was saved with a previous inputsave().
2894 Should be called the same number of times inputsave() is
2895 called. Calling it more often is harmless though.
2896 Returns 1 when there is nothing to restore, 0 otherwise.
2897
2898inputsave() *inputsave()*
2899 Preserve typeahead (also from mappings) and clear it, so that
2900 a following prompt gets input from the user. Should be
2901 followed by a matching inputrestore() after the prompt. Can
2902 be used several times, in which case there must be just as
2903 many inputrestore() calls.
2904 Returns 1 when out of memory, 0 otherwise.
2905
2906inputsecret({prompt} [, {text}]) *inputsecret()*
2907 This function acts much like the |input()| function with but
2908 two exceptions:
2909 a) the user's response will be displayed as a sequence of
2910 asterisks ("*") thereby keeping the entry secret, and
2911 b) the user's response will not be recorded on the input
2912 |history| stack.
2913 The result is a String, which is whatever the user actually
2914 typed on the command-line in response to the issued prompt.
2915
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002916insert({list}, {item} [, {idx}]) *insert()*
2917 Insert {item} at the start of List {list}.
2918 If {idx} is specified insert {item} before the item with index
2919 {idx}. If {idx} is zero it goes before the first item, just
2920 like omitting {idx}. A negative {idx} is also possible, see
2921 |list-index|. -1 inserts just before the last item.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002922 Returns the resulting List. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002923 :let mylist = insert([2, 3, 5], 1)
2924 :call insert(mylist, 4, -1)
2925 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002926< The last example can be done simpler with |add()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002927 Note that when {item} is a List it is inserted as a single
2928 item. Use |extend()| to concatenate Lists.
2929
Bram Moolenaar071d4272004-06-13 20:20:40 +00002930isdirectory({directory}) *isdirectory()*
2931 The result is a Number, which is non-zero when a directory
2932 with the name {directory} exists. If {directory} doesn't
2933 exist, or isn't a directory, the result is FALSE. {directory}
2934 is any expression, which is used as a String.
2935
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00002936islocked({expr}) *islocked()*
2937 The result is a Number, which is non-zero when {expr} is the
2938 name of a locked variable.
2939 {expr} must be the name of a variable, List item or Dictionary
2940 entry, not the variable itself! Example: >
2941 :let alist = [0, ['a', 'b'], 2, 3]
2942 :lockvar 1 alist
2943 :echo islocked('alist') " 1
2944 :echo islocked('alist[1]') " 0
2945
2946< When {expr} is a variable that does not exist you get an error
2947 message. Use |exists()| to check for existance.
2948
Bram Moolenaar677ee682005-01-27 14:41:15 +00002949items({dict}) *items()*
2950 Return a List with all the key-value pairs of {dict}. Each
2951 List item is a list with two items: the key of a {dict} entry
2952 and the value of this entry. The List is in arbitrary order.
2953
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002954
2955join({list} [, {sep}]) *join()*
2956 Join the items in {list} together into one String.
2957 When {sep} is specified it is put in between the items. If
2958 {sep} is omitted a single space is used.
2959 Note that {sep} is not added at the end. You might want to
2960 add it there too: >
2961 let lines = join(mylist, "\n") . "\n"
2962< String items are used as-is. Lists and Dictionaries are
2963 converted into a string like with |string()|.
2964 The opposite function is |split()|.
2965
Bram Moolenaard8b02732005-01-14 21:48:43 +00002966keys({dict}) *keys()*
2967 Return a List with all the keys of {dict}. The List is in
2968 arbitrary order.
2969
Bram Moolenaar13065c42005-01-08 16:08:21 +00002970 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002971len({expr}) The result is a Number, which is the length of the argument.
2972 When {expr} is a String or a Number the length in bytes is
2973 used, as with |strlen()|.
2974 When {expr} is a List the number of items in the List is
2975 returned.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002976 When {expr} is a Dictionary the number of entries in the
2977 Dictionary is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002978 Otherwise an error is given.
2979
Bram Moolenaar071d4272004-06-13 20:20:40 +00002980 *libcall()* *E364* *E368*
2981libcall({libname}, {funcname}, {argument})
2982 Call function {funcname} in the run-time library {libname}
2983 with single argument {argument}.
2984 This is useful to call functions in a library that you
2985 especially made to be used with Vim. Since only one argument
2986 is possible, calling standard library functions is rather
2987 limited.
2988 The result is the String returned by the function. If the
2989 function returns NULL, this will appear as an empty string ""
2990 to Vim.
2991 If the function returns a number, use libcallnr()!
2992 If {argument} is a number, it is passed to the function as an
2993 int; if {argument} is a string, it is passed as a
2994 null-terminated string.
2995 This function will fail in |restricted-mode|.
2996
2997 libcall() allows you to write your own 'plug-in' extensions to
2998 Vim without having to recompile the program. It is NOT a
2999 means to call system functions! If you try to do so Vim will
3000 very probably crash.
3001
3002 For Win32, the functions you write must be placed in a DLL
3003 and use the normal C calling convention (NOT Pascal which is
3004 used in Windows System DLLs). The function must take exactly
3005 one parameter, either a character pointer or a long integer,
3006 and must return a character pointer or NULL. The character
3007 pointer returned must point to memory that will remain valid
3008 after the function has returned (e.g. in static data in the
3009 DLL). If it points to allocated memory, that memory will
3010 leak away. Using a static buffer in the function should work,
3011 it's then freed when the DLL is unloaded.
3012
3013 WARNING: If the function returns a non-valid pointer, Vim may
3014 crash! This also happens if the function returns a number,
3015 because Vim thinks it's a pointer.
3016 For Win32 systems, {libname} should be the filename of the DLL
3017 without the ".DLL" suffix. A full path is only required if
3018 the DLL is not in the usual places.
3019 For Unix: When compiling your own plugins, remember that the
3020 object code must be compiled as position-independent ('PIC').
3021 {only in Win32 on some Unix versions, when the |+libcall|
3022 feature is present}
3023 Examples: >
3024 :echo libcall("libc.so", "getenv", "HOME")
3025 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3026<
3027 *libcallnr()*
3028libcallnr({libname}, {funcname}, {argument})
3029 Just like libcall(), but used for a function that returns an
3030 int instead of a string.
3031 {only in Win32 on some Unix versions, when the |+libcall|
3032 feature is present}
3033 Example (not very useful...): >
3034 :call libcallnr("libc.so", "printf", "Hello World!\n")
3035 :call libcallnr("libc.so", "sleep", 10)
3036<
3037 *line()*
3038line({expr}) The result is a Number, which is the line number of the file
3039 position given with {expr}. The accepted positions are:
3040 . the cursor position
3041 $ the last line in the current buffer
3042 'x position of mark x (if the mark is not set, 0 is
3043 returned)
3044 Note that only marks in the current file can be used.
3045 Examples: >
3046 line(".") line number of the cursor
3047 line("'t") line number of mark t
3048 line("'" . marker) line number of mark marker
3049< *last-position-jump*
3050 This autocommand jumps to the last known position in a file
3051 just after opening it, if the '" mark is set: >
3052 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003053
Bram Moolenaar071d4272004-06-13 20:20:40 +00003054line2byte({lnum}) *line2byte()*
3055 Return the byte count from the start of the buffer for line
3056 {lnum}. This includes the end-of-line character, depending on
3057 the 'fileformat' option for the current buffer. The first
3058 line returns 1.
3059 This can also be used to get the byte count for the line just
3060 below the last line: >
3061 line2byte(line("$") + 1)
3062< This is the file size plus one.
3063 When {lnum} is invalid, or the |+byte_offset| feature has been
3064 disabled at compile time, -1 is returned.
3065 Also see |byte2line()|, |go| and |:goto|.
3066
3067lispindent({lnum}) *lispindent()*
3068 Get the amount of indent for line {lnum} according the lisp
3069 indenting rules, as with 'lisp'.
3070 The indent is counted in spaces, the value of 'tabstop' is
3071 relevant. {lnum} is used just like in |getline()|.
3072 When {lnum} is invalid or Vim was not compiled the
3073 |+lispindent| feature, -1 is returned.
3074
3075localtime() *localtime()*
3076 Return the current time, measured as seconds since 1st Jan
3077 1970. See also |strftime()| and |getftime()|.
3078
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003079
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003080map({expr}, {string}) *map()*
3081 {expr} must be a List or a Dictionary.
3082 Replace each item in {expr} with the result of evaluating
3083 {string}.
3084 Inside {string} |v:val| has the value of the current item.
3085 For a Dictionary |v:key| has the key of the current item.
3086 Example: >
3087 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003088< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003089
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003090 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003091 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003092 |literal-string| to avoid having to double backslashes. You
3093 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003094
3095 The operation is done in-place. If you want a List or
3096 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003097 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003098
3099< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003100
3101
Bram Moolenaar071d4272004-06-13 20:20:40 +00003102maparg({name}[, {mode}]) *maparg()*
3103 Return the rhs of mapping {name} in mode {mode}. When there
3104 is no mapping for {name}, an empty String is returned.
3105 These characters can be used for {mode}:
3106 "n" Normal
3107 "v" Visual
3108 "o" Operator-pending
3109 "i" Insert
3110 "c" Cmd-line
3111 "l" langmap |language-mapping|
3112 "" Normal, Visual and Operator-pending
3113 When {mode} is omitted, the modes from "" are used.
3114 The {name} can have special key names, like in the ":map"
3115 command. The returned String has special characters
3116 translated like in the output of the ":map" command listing.
3117 The mappings local to the current buffer are checked first,
3118 then the global mappings.
3119
3120mapcheck({name}[, {mode}]) *mapcheck()*
3121 Check if there is a mapping that matches with {name} in mode
3122 {mode}. See |maparg()| for {mode} and special names in
3123 {name}.
3124 A match happens with a mapping that starts with {name} and
3125 with a mapping which is equal to the start of {name}.
3126
3127 matches mapping "a" "ab" "abc" ~
3128 mapcheck("a") yes yes yes
3129 mapcheck("abc") yes yes yes
3130 mapcheck("ax") yes no no
3131 mapcheck("b") no no no
3132
3133 The difference with maparg() is that mapcheck() finds a
3134 mapping that matches with {name}, while maparg() only finds a
3135 mapping for {name} exactly.
3136 When there is no mapping that starts with {name}, an empty
3137 String is returned. If there is one, the rhs of that mapping
3138 is returned. If there are several mappings that start with
3139 {name}, the rhs of one of them is returned.
3140 The mappings local to the current buffer are checked first,
3141 then the global mappings.
3142 This function can be used to check if a mapping can be added
3143 without being ambiguous. Example: >
3144 :if mapcheck("_vv") == ""
3145 : map _vv :set guifont=7x13<CR>
3146 :endif
3147< This avoids adding the "_vv" mapping when there already is a
3148 mapping for "_v" or for "_vvv".
3149
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003150match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003151 When {expr} is a List then this returns the index of the first
3152 item where {pat} matches. Each item is used as a String,
3153 Lists and Dictionaries are used as echoed.
3154 Otherwise, {expr} is used as a String. The result is a
3155 Number, which gives the index (byte offset) in {expr} where
3156 {pat} matches.
3157 A match at the first character or List item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003158 If there is no match -1 is returned.
3159 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003160 :echo match("testing", "ing") " results in 4
3161 :echo match([1, 'x'], '\a') " results in 2
3162< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00003163 *strpbrk()*
3164 Vim doesn't have a strpbrk() function. But you can do: >
3165 :let sepidx = match(line, '[.,;: \t]')
3166< *strcasestr()*
3167 Vim doesn't have a strcasestr() function. But you can add
3168 "\c" to the pattern to ignore case: >
3169 :let idx = match(haystack, '\cneedle')
3170<
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003171 When {count} is given use the {count}'th match. When a match
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003172 is found in a String the search for the next one starts on
3173 character further. Thus this example results in 1: >
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003174 echo match("testing", "..", 0, 2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003175< In a List the search continues in the next item.
3176
3177 If {start} is given, the search starts from byte index
3178 {start} in a String or item {start} in a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003179 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003180 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003181 :echo match("testing", "ing", 2)
3182< result is again "4". >
3183 :echo match("testing", "ing", 4)
3184< result is again "4". >
3185 :echo match("testing", "t", 2)
3186< result is "3".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003187 For a String, if {start} < 0, it will be set to 0. For a list
3188 the index is counted from the end.
3189 If {start} is out of range (> strlen({expr} for a String or
3190 > len({expr} for a List) -1 is returned.
3191
Bram Moolenaar071d4272004-06-13 20:20:40 +00003192 See |pattern| for the patterns that are accepted.
3193 The 'ignorecase' option is used to set the ignore-caseness of
3194 the pattern. 'smartcase' is NOT used. The matching is always
3195 done like 'magic' is set and 'cpoptions' is empty.
3196
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003197matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003198 Same as match(), but return the index of first character after
3199 the match. Example: >
3200 :echo matchend("testing", "ing")
3201< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00003202 *strspn()* *strcspn()*
3203 Vim doesn't have a strspn() or strcspn() function, but you can
3204 do it with matchend(): >
3205 :let span = matchend(line, '[a-zA-Z]')
3206 :let span = matchend(line, '[^a-zA-Z]')
3207< Except that -1 is returned when there are no matches.
3208
Bram Moolenaar071d4272004-06-13 20:20:40 +00003209 The {start}, if given, has the same meaning as for match(). >
3210 :echo matchend("testing", "ing", 2)
3211< results in "7". >
3212 :echo matchend("testing", "ing", 5)
3213< result is "-1".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003214 When {expr} is a List the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003215
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003216matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
3217 Same as match(), but return a List. The first item in the
3218 list is the matched string, same as what matchstr() would
3219 return. Following items are submatches, like "\1", "\2", etc.
3220 in |:substitute|.
3221 When there is no match an empty list is returned.
3222
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003223matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003224 Same as match(), but return the matched string. Example: >
3225 :echo matchstr("testing", "ing")
3226< results in "ing".
3227 When there is no match "" is returned.
3228 The {start}, if given, has the same meaning as for match(). >
3229 :echo matchstr("testing", "ing", 2)
3230< results in "ing". >
3231 :echo matchstr("testing", "ing", 5)
3232< result is "".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003233 When {expr} is a List then the matching item is returned.
3234 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003235
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003236 *max()*
3237max({list}) Return the maximum value of all items in {list}.
3238 If {list} is not a list or one of the items in {list} cannot
3239 be used as a Number this results in an error.
3240 An empty List results in zero.
3241
3242 *min()*
3243min({list}) Return the minumum value of all items in {list}.
3244 If {list} is not a list or one of the items in {list} cannot
3245 be used as a Number this results in an error.
3246 An empty List results in zero.
3247
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003248 *mkdir()* *E749*
3249mkdir({name} [, {path} [, {prot}]])
3250 Create directory {name}.
3251 If {path} is "p" then intermediate directories are created as
3252 necessary. Otherwise it must be "".
3253 If {prot} is given it is used to set the protection bits of
3254 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3255 the user readable for others). Use 0700 to make it unreadable
3256 for others.
3257 This function is not available in the |sandbox|.
3258 Not available on all systems. To check use: >
3259 :if exists("*mkdir")
3260<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003261 *mode()*
3262mode() Return a string that indicates the current mode:
3263 n Normal
3264 v Visual by character
3265 V Visual by line
3266 CTRL-V Visual blockwise
3267 s Select by character
3268 S Select by line
3269 CTRL-S Select blockwise
3270 i Insert
3271 R Replace
3272 c Command-line
3273 r Hit-enter prompt
3274 This is useful in the 'statusline' option. In most other
3275 places it always returns "c" or "n".
3276
3277nextnonblank({lnum}) *nextnonblank()*
3278 Return the line number of the first line at or below {lnum}
3279 that is not blank. Example: >
3280 if getline(nextnonblank(1)) =~ "Java"
3281< When {lnum} is invalid or there is no non-blank line at or
3282 below it, zero is returned.
3283 See also |prevnonblank()|.
3284
3285nr2char({expr}) *nr2char()*
3286 Return a string with a single character, which has the number
3287 value {expr}. Examples: >
3288 nr2char(64) returns "@"
3289 nr2char(32) returns " "
3290< The current 'encoding' is used. Example for "utf-8": >
3291 nr2char(300) returns I with bow character
3292< Note that a NUL character in the file is specified with
3293 nr2char(10), because NULs are represented with newline
3294 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003295 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003296
3297prevnonblank({lnum}) *prevnonblank()*
3298 Return the line number of the first line at or above {lnum}
3299 that is not blank. Example: >
3300 let ind = indent(prevnonblank(v:lnum - 1))
3301< When {lnum} is invalid or there is no non-blank line at or
3302 above it, zero is returned.
3303 Also see |nextnonblank()|.
3304
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003305 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003306range({expr} [, {max} [, {stride}]]) *range()*
3307 Returns a List with Numbers:
3308 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3309 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3310 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3311 {max}] (increasing {expr} with {stride} each time, not
3312 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00003313 When the maximum is one before the start the result is an
3314 empty list. When the maximum is more than one before the
3315 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003316 Examples: >
3317 range(4) " [0, 1, 2, 3]
3318 range(2, 4) " [2, 3, 4]
3319 range(2, 9, 3) " [2, 5, 8]
3320 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00003321 range(0) " []
3322 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00003323<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003324 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003325readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003326 Read file {fname} and return a List, each line of the file as
3327 an item. Lines broken at NL characters. Macintosh files
3328 separated with CR will result in a single long line (unless a
3329 NL appears somewhere).
3330 When {binary} is equal to "b" binary mode is used:
3331 - When the last line ends in a NL an extra empty list item is
3332 added.
3333 - No CR characters are removed.
3334 Otherwise:
3335 - CR characters that appear before a NL are removed.
3336 - Whether the last line ends in a NL or not does not matter.
3337 All NUL characters are replaced with a NL character.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003338 When {max} is given this specifies the maximum number of lines
3339 to be read. Useful if you only want to check the first ten
3340 lines of a file: >
3341 :for line in readfile(fname, '', 10)
3342 : if line =~ 'Date' | echo line | endif
3343 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00003344< When {max} is negative -{max} lines from the end of the file
3345 are returned, or as many as there are.
3346 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003347 Note that without {max} the whole file is read into memory.
3348 Also note that there is no recognition of encoding. Read a
3349 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003350 When the file can't be opened an error message is given and
3351 the result is an empty list.
3352 Also see |writefile()|.
3353
Bram Moolenaar071d4272004-06-13 20:20:40 +00003354 *remote_expr()* *E449*
3355remote_expr({server}, {string} [, {idvar}])
3356 Send the {string} to {server}. The string is sent as an
3357 expression and the result is returned after evaluation.
3358 If {idvar} is present, it is taken as the name of a
3359 variable and a {serverid} for later use with
3360 remote_read() is stored there.
3361 See also |clientserver| |RemoteReply|.
3362 This function is not available in the |sandbox|.
3363 {only available when compiled with the |+clientserver| feature}
3364 Note: Any errors will cause a local error message to be issued
3365 and the result will be the empty string.
3366 Examples: >
3367 :echo remote_expr("gvim", "2+2")
3368 :echo remote_expr("gvim1", "b:current_syntax")
3369<
3370
3371remote_foreground({server}) *remote_foreground()*
3372 Move the Vim server with the name {server} to the foreground.
3373 This works like: >
3374 remote_expr({server}, "foreground()")
3375< Except that on Win32 systems the client does the work, to work
3376 around the problem that the OS doesn't always allow the server
3377 to bring itself to the foreground.
3378 This function is not available in the |sandbox|.
3379 {only in the Win32, Athena, Motif and GTK GUI versions and the
3380 Win32 console version}
3381
3382
3383remote_peek({serverid} [, {retvar}]) *remote_peek()*
3384 Returns a positive number if there are available strings
3385 from {serverid}. Copies any reply string into the variable
3386 {retvar} if specified. {retvar} must be a string with the
3387 name of a variable.
3388 Returns zero if none are available.
3389 Returns -1 if something is wrong.
3390 See also |clientserver|.
3391 This function is not available in the |sandbox|.
3392 {only available when compiled with the |+clientserver| feature}
3393 Examples: >
3394 :let repl = ""
3395 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3396
3397remote_read({serverid}) *remote_read()*
3398 Return the oldest available reply from {serverid} and consume
3399 it. It blocks until a reply is available.
3400 See also |clientserver|.
3401 This function is not available in the |sandbox|.
3402 {only available when compiled with the |+clientserver| feature}
3403 Example: >
3404 :echo remote_read(id)
3405<
3406 *remote_send()* *E241*
3407remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003408 Send the {string} to {server}. The string is sent as input
3409 keys and the function returns immediately. At the Vim server
3410 the keys are not mapped |:map|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003411 If {idvar} is present, it is taken as the name of a
3412 variable and a {serverid} for later use with
3413 remote_read() is stored there.
3414 See also |clientserver| |RemoteReply|.
3415 This function is not available in the |sandbox|.
3416 {only available when compiled with the |+clientserver| feature}
3417 Note: Any errors will be reported in the server and may mess
3418 up the display.
3419 Examples: >
3420 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3421 \ remote_read(serverid)
3422
3423 :autocmd NONE RemoteReply *
3424 \ echo remote_read(expand("<amatch>"))
3425 :echo remote_send("gvim", ":sleep 10 | echo ".
3426 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003427<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003428remove({list}, {idx} [, {end}]) *remove()*
3429 Without {end}: Remove the item at {idx} from List {list} and
3430 return it.
3431 With {end}: Remove items from {idx} to {end} (inclusive) and
3432 return a list with these items. When {idx} points to the same
3433 item as {end} a list with one item is returned. When {end}
3434 points to an item before {idx} this is an error.
3435 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003436 Example: >
3437 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003438 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00003439remove({dict}, {key})
3440 Remove the entry from {dict} with key {key}. Example: >
3441 :echo "removed " . remove(dict, "one")
3442< If there is no {key} in {dict} this is an error.
3443
3444 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003445
Bram Moolenaar071d4272004-06-13 20:20:40 +00003446rename({from}, {to}) *rename()*
3447 Rename the file by the name {from} to the name {to}. This
3448 should also work to move files across file systems. The
3449 result is a Number, which is 0 if the file was renamed
3450 successfully, and non-zero when the renaming failed.
3451 This function is not available in the |sandbox|.
3452
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003453repeat({expr}, {count}) *repeat()*
3454 Repeat {expr} {count} times and return the concatenated
3455 result. Example: >
3456 :let seperator = repeat('-', 80)
3457< When {count} is zero or negative the result is empty.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003458 When {expr} is a List the result is {expr} concatenated
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003459 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003460 :let longlist = repeat(['a', 'b'], 3)
3461< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003462
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003463
Bram Moolenaar071d4272004-06-13 20:20:40 +00003464resolve({filename}) *resolve()* *E655*
3465 On MS-Windows, when {filename} is a shortcut (a .lnk file),
3466 returns the path the shortcut points to in a simplified form.
3467 On Unix, repeat resolving symbolic links in all path
3468 components of {filename} and return the simplified result.
3469 To cope with link cycles, resolving of symbolic links is
3470 stopped after 100 iterations.
3471 On other systems, return the simplified {filename}.
3472 The simplification step is done as by |simplify()|.
3473 resolve() keeps a leading path component specifying the
3474 current directory (provided the result is still a relative
3475 path name) and also keeps a trailing path separator.
3476
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003477 *reverse()*
3478reverse({list}) Reverse the order of items in {list} in-place. Returns
3479 {list}.
3480 If you want a list to remain unmodified make a copy first: >
3481 :let revlist = reverse(copy(mylist))
3482
Bram Moolenaar071d4272004-06-13 20:20:40 +00003483search({pattern} [, {flags}]) *search()*
3484 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003485 cursor position (you can use |cursor()| to set it).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003486 {flags} is a String, which can contain these character flags:
3487 'b' search backward instead of forward
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003488 'n' do Not move the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003489 'w' wrap around the end of the file
3490 'W' don't wrap around the end of the file
3491 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
3492
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003493 When a match has been found its line number is returned.
3494 The cursor will be positioned at the match, unless the 'n'
3495 flag is used).
3496 If there is no match a 0 is returned and the cursor doesn't
3497 move. No error message is given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003498
3499 Example (goes over all files in the argument list): >
3500 :let n = 1
3501 :while n <= argc() " loop over all files in arglist
3502 : exe "argument " . n
3503 : " start at the last char in the file and wrap for the
3504 : " first search to find match at start of file
3505 : normal G$
3506 : let flags = "w"
3507 : while search("foo", flags) > 0
3508 : s/foo/bar/g
3509 : let flags = "W"
3510 : endwhile
3511 : update " write the file if modified
3512 : let n = n + 1
3513 :endwhile
3514<
3515 *searchpair()*
3516searchpair({start}, {middle}, {end} [, {flags} [, {skip}]])
3517 Search for the match of a nested start-end pair. This can be
3518 used to find the "endif" that matches an "if", while other
3519 if/endif pairs in between are ignored.
3520 The search starts at the cursor. If a match is found, the
3521 cursor is positioned at it and the line number is returned.
3522 If no match is found 0 or -1 is returned and the cursor
3523 doesn't move. No error message is given.
3524
3525 {start}, {middle} and {end} are patterns, see |pattern|. They
3526 must not contain \( \) pairs. Use of \%( \) is allowed. When
3527 {middle} is not empty, it is found when searching from either
3528 direction, but only when not in a nested start-end pair. A
3529 typical use is: >
3530 searchpair('\<if\>', '\<else\>', '\<endif\>')
3531< By leaving {middle} empty the "else" is skipped.
3532
3533 {flags} are used like with |search()|. Additionally:
3534 'n' do Not move the cursor
3535 'r' Repeat until no more matches found; will find the
3536 outer pair
3537 'm' return number of Matches instead of line number with
3538 the match; will only be > 1 when 'r' is used.
3539
3540 When a match for {start}, {middle} or {end} is found, the
3541 {skip} expression is evaluated with the cursor positioned on
3542 the start of the match. It should return non-zero if this
3543 match is to be skipped. E.g., because it is inside a comment
3544 or a string.
3545 When {skip} is omitted or empty, every match is accepted.
3546 When evaluating {skip} causes an error the search is aborted
3547 and -1 returned.
3548
3549 The value of 'ignorecase' is used. 'magic' is ignored, the
3550 patterns are used like it's on.
3551
3552 The search starts exactly at the cursor. A match with
3553 {start}, {middle} or {end} at the next character, in the
3554 direction of searching, is the first one found. Example: >
3555 if 1
3556 if 2
3557 endif 2
3558 endif 1
3559< When starting at the "if 2", with the cursor on the "i", and
3560 searching forwards, the "endif 2" is found. When starting on
3561 the character just before the "if 2", the "endif 1" will be
3562 found. That's because the "if 2" will be found first, and
3563 then this is considered to be a nested if/endif from "if 2" to
3564 "endif 2".
3565 When searching backwards and {end} is more than one character,
3566 it may be useful to put "\zs" at the end of the pattern, so
3567 that when the cursor is inside a match with the end it finds
3568 the matching start.
3569
3570 Example, to find the "endif" command in a Vim script: >
3571
3572 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
3573 \ 'getline(".") =~ "^\\s*\""')
3574
3575< The cursor must be at or after the "if" for which a match is
3576 to be found. Note that single-quote strings are used to avoid
3577 having to double the backslashes. The skip expression only
3578 catches comments at the start of a line, not after a command.
3579 Also, a word "en" or "if" halfway a line is considered a
3580 match.
3581 Another example, to search for the matching "{" of a "}": >
3582
3583 :echo searchpair('{', '', '}', 'bW')
3584
3585< This works when the cursor is at or before the "}" for which a
3586 match is to be found. To reject matches that syntax
3587 highlighting recognized as strings: >
3588
3589 :echo searchpair('{', '', '}', 'bW',
3590 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
3591<
3592server2client( {clientid}, {string}) *server2client()*
3593 Send a reply string to {clientid}. The most recent {clientid}
3594 that sent a string can be retrieved with expand("<client>").
3595 {only available when compiled with the |+clientserver| feature}
3596 Note:
3597 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003598 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003599 before calling any commands that waits for input.
3600 See also |clientserver|.
3601 Example: >
3602 :echo server2client(expand("<client>"), "HELLO")
3603<
3604serverlist() *serverlist()*
3605 Return a list of available server names, one per line.
3606 When there are no servers or the information is not available
3607 an empty string is returned. See also |clientserver|.
3608 {only available when compiled with the |+clientserver| feature}
3609 Example: >
3610 :echo serverlist()
3611<
3612setbufvar({expr}, {varname}, {val}) *setbufvar()*
3613 Set option or local variable {varname} in buffer {expr} to
3614 {val}.
3615 This also works for a global or local window option, but it
3616 doesn't work for a global or local window variable.
3617 For a local window option the global value is unchanged.
3618 For the use of {expr}, see |bufname()| above.
3619 Note that the variable name without "b:" must be used.
3620 Examples: >
3621 :call setbufvar(1, "&mod", 1)
3622 :call setbufvar("todo", "myvar", "foobar")
3623< This function is not available in the |sandbox|.
3624
3625setcmdpos({pos}) *setcmdpos()*
3626 Set the cursor position in the command line to byte position
3627 {pos}. The first position is 1.
3628 Use |getcmdpos()| to obtain the current position.
3629 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00003630 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
3631 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
3632 set after the command line is set to the expression. For
3633 |c_CTRL-R_=| it is set after evaluating the expression but
3634 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003635 When the number is too big the cursor is put at the end of the
3636 line. A number smaller than one has undefined results.
3637 Returns 0 when successful, 1 when not editing the command
3638 line.
3639
3640setline({lnum}, {line}) *setline()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003641 Set line {lnum} of the current buffer to {line}.
3642 {lnum} is used like with |getline()|.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003643 When {lnum} is just below the last line the {line} will be
3644 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003645 If this succeeds, 0 is returned. If this fails (most likely
3646 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003647 :call setline(5, strftime("%c"))
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003648< When {line} is a List then line {lnum} and following lines
3649 will be set to the items in the list. Example: >
3650 :call setline(5, ['aaa', 'bbb', 'ccc'])
3651< This is equivalent to: >
3652 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
3653 : call setline(n, l)
3654 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003655< Note: The '[ and '] marks are not set.
3656
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003657
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003658setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003659 Creates a quickfix list using the items in {list}. Each item
3660 in {list} is a dictionary. Non-dictionary items in {list} are
3661 ignored. Each dictionary item can contain the following
3662 entries:
3663
3664 filename name of a file
3665 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003666 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003667 col column number
3668 vcol when non-zero: "col" is visual column
3669 when zero: "col" is byte index
3670 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003671 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00003672 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003673
Bram Moolenaar582fd852005-03-28 20:58:01 +00003674 The "col", "vcol", "nr", "type" and "text" entries are
3675 optional. Either "lnum" or "pattern" entry can be used to
3676 locate a matching error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003677 If the "filename" entry is not present or neither the "lnum"
3678 or "pattern" entries are present, then the item will not be
3679 handled as an error line.
3680 If both "pattern" and "lnum" are present then "pattern" will
3681 be used.
3682
Bram Moolenaar35c54e52005-05-20 21:25:31 +00003683 If {action} is set to 'a', then the items from {list} are
3684 added to the existing quickfix list. If there is no existing
3685 list, then a new list is created. If {action} is set to 'r',
3686 then the items from the current quickfix list are replaced
3687 with the items from {list}. If {action} is not present or is
3688 set to ' ', then a new list is created.
3689
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003690 Returns zero for success, -1 for failure.
3691
3692 This function can be used to create a quickfix list
3693 independent of the 'errorformat' setting. Use a command like
3694 ":cc 1" to jump to the first position.
3695
3696
Bram Moolenaar071d4272004-06-13 20:20:40 +00003697 *setreg()*
3698setreg({regname}, {value} [,{options}])
3699 Set the register {regname} to {value}.
3700 If {options} contains "a" or {regname} is upper case,
3701 then the value is appended.
3702 {options} can also contains a register type specification:
3703 "c" or "v" |characterwise| mode
3704 "l" or "V" |linewise| mode
3705 "b" or "<CTRL-V>" |blockwise-visual| mode
3706 If a number immediately follows "b" or "<CTRL-V>" then this is
3707 used as the width of the selection - if it is not specified
3708 then the width of the block is set to the number of characters
3709 in the longest line (counting a <TAB> as 1 character).
3710
3711 If {options} contains no register settings, then the default
3712 is to use character mode unless {value} ends in a <NL>.
3713 Setting the '=' register is not possible.
3714 Returns zero for success, non-zero for failure.
3715
3716 Examples: >
3717 :call setreg(v:register, @*)
3718 :call setreg('*', @%, 'ac')
3719 :call setreg('a', "1\n2\n3", 'b5')
3720
3721< This example shows using the functions to save and restore a
3722 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003723 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003724 :let var_amode = getregtype('a')
3725 ....
3726 :call setreg('a', var_a, var_amode)
3727
3728< You can also change the type of a register by appending
3729 nothing: >
3730 :call setreg('a', '', 'al')
3731
3732setwinvar({nr}, {varname}, {val}) *setwinvar()*
3733 Set option or local variable {varname} in window {nr} to
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00003734 {val}. When {nr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003735 This also works for a global or local buffer option, but it
3736 doesn't work for a global or local buffer variable.
3737 For a local buffer option the global value is unchanged.
3738 Note that the variable name without "w:" must be used.
3739 Examples: >
3740 :call setwinvar(1, "&list", 0)
3741 :call setwinvar(2, "myvar", "foobar")
3742< This function is not available in the |sandbox|.
3743
3744simplify({filename}) *simplify()*
3745 Simplify the file name as much as possible without changing
3746 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
3747 Unix) are not resolved. If the first path component in
3748 {filename} designates the current directory, this will be
3749 valid for the result as well. A trailing path separator is
3750 not removed either.
3751 Example: >
3752 simplify("./dir/.././/file/") == "./file/"
3753< Note: The combination "dir/.." is only removed if "dir" is
3754 a searchable directory or does not exist. On Unix, it is also
3755 removed when "dir" is a symbolic link within the same
3756 directory. In order to resolve all the involved symbolic
3757 links before simplifying the path name, use |resolve()|.
3758
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003759
Bram Moolenaar13065c42005-01-08 16:08:21 +00003760sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003761 Sort the items in {list} in-place. Returns {list}. If you
3762 want a list to remain unmodified make a copy first: >
3763 :let sortedlist = sort(copy(mylist))
3764< Uses the string representation of each item to sort on.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003765 Numbers sort after Strings, Lists after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003766 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003767 When {func} is given and it is one then case is ignored.
3768 When {func} is a Funcref or a function name, this function is
3769 called to compare items. The function is invoked with two
3770 items as argument and must return zero if they are equal, 1 if
3771 the first one sorts after the second one, -1 if the first one
3772 sorts before the second one. Example: >
3773 func MyCompare(i1, i2)
3774 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
3775 endfunc
3776 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003777<
3778
3779 *spellbadword()*
3780spellbadword() Return the badly spelled word under or after the cursor.
3781 The cursor is advanced to the start of the bad word.
3782 When no bad word is found in the cursor line an empty String
3783 is returned and the cursor doesn't move.
3784
3785 *spellsuggest()*
3786spellsuggest({word} [, {max}])
3787 Return a List with spelling suggestions to replace {word}.
3788 When {max} is given up to this number of suggestions are
3789 returned. Otherwise up to 25 suggestions are returned.
3790
3791 {word} can be a badly spelled word followed by other text.
3792 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00003793 suggestions also include the following text, thus you can
3794 replace a line.
3795
3796 {word} may also be a good word. Similar words will then be
3797 returned. {word} itself is also included, most likely as the
3798 first entry, thus this can be used to check spelling.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003799
3800 The spelling information for the current window is used. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00003801 'spell' option must be set and the value of 'spelllang' is
3802 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00003803
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003804
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003805split({expr} [, {pattern} [, {keepempty}]]) *split()*
3806 Make a List out of {expr}. When {pattern} is omitted or empty
3807 each white-separated sequence of characters becomes an item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003808 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003809 removing the matched characters.
3810 When the first or last item is empty it is omitted, unless the
3811 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00003812 Other empty items are kept when {pattern} matches at least one
3813 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003814 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003815 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003816< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003817 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00003818< If you want to keep the separator you can also use '\zs': >
3819 :echo split('abc:def:ghi', ':\zs')
3820< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003821 Splitting a table where the first element can be empty: >
3822 :let items = split(line, ':', 1)
3823< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003824
3825
Bram Moolenaar071d4272004-06-13 20:20:40 +00003826strftime({format} [, {time}]) *strftime()*
3827 The result is a String, which is a formatted date and time, as
3828 specified by the {format} string. The given {time} is used,
3829 or the current time if no time is given. The accepted
3830 {format} depends on your system, thus this is not portable!
3831 See the manual page of the C function strftime() for the
3832 format. The maximum length of the result is 80 characters.
3833 See also |localtime()| and |getftime()|.
3834 The language can be changed with the |:language| command.
3835 Examples: >
3836 :echo strftime("%c") Sun Apr 27 11:49:23 1997
3837 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
3838 :echo strftime("%y%m%d %T") 970427 11:53:55
3839 :echo strftime("%H:%M") 11:55
3840 :echo strftime("%c", getftime("file.c"))
3841 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003842< Not available on all systems. To check use: >
3843 :if exists("*strftime")
3844
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003845stridx({haystack}, {needle} [, {start}]) *stridx()*
3846 The result is a Number, which gives the byte index in
3847 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003848 If {start} is specified, the search starts at index {start}.
3849 This can be used to find a second match: >
3850 :let comma1 = stridx(line, ",")
3851 :let comma2 = stridx(line, ",", comma1 + 1)
3852< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003853 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003854 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003855 See also |strridx()|.
3856 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003857 :echo stridx("An Example", "Example") 3
3858 :echo stridx("Starting point", "Start") 0
3859 :echo stridx("Starting point", "start") -1
Bram Moolenaar05159a02005-02-26 23:04:13 +00003860< *strstr()* *strchr()*
3861 stridx() works similar to the C function strstr(). When used
3862 with a single character it works similar to strchr().
3863
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003864 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003865string({expr}) Return {expr} converted to a String. If {expr} is a Number,
3866 String or a composition of them, then the result can be parsed
3867 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003868 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00003869 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003870 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00003871 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003872 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00003873 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00003874 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003875
Bram Moolenaar071d4272004-06-13 20:20:40 +00003876 *strlen()*
3877strlen({expr}) The result is a Number, which is the length of the String
3878 {expr} in bytes. If you want to count the number of
3879 multi-byte characters use something like this: >
3880
3881 :let len = strlen(substitute(str, ".", "x", "g"))
3882
3883< Composing characters are not counted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003884 If the argument is a Number it is first converted to a String.
3885 For other types an error is given.
3886 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003887
3888strpart({src}, {start}[, {len}]) *strpart()*
3889 The result is a String, which is part of {src}, starting from
3890 byte {start}, with the length {len}.
3891 When non-existing bytes are included, this doesn't result in
3892 an error, the bytes are simply omitted.
3893 If {len} is missing, the copy continues from {start} till the
3894 end of the {src}. >
3895 strpart("abcdefg", 3, 2) == "de"
3896 strpart("abcdefg", -2, 4) == "ab"
3897 strpart("abcdefg", 5, 4) == "fg"
3898 strpart("abcdefg", 3) == "defg"
3899< Note: To get the first character, {start} must be 0. For
3900 example, to get three bytes under and after the cursor: >
3901 strpart(getline(line(".")), col(".") - 1, 3)
3902<
Bram Moolenaar677ee682005-01-27 14:41:15 +00003903strridx({haystack}, {needle} [, {start}]) *strridx()*
3904 The result is a Number, which gives the byte index in
3905 {haystack} of the last occurrence of the String {needle}.
3906 When {start} is specified, matches beyond this index are
3907 ignored. This can be used to find a match before a previous
3908 match: >
3909 :let lastcomma = strridx(line, ",")
3910 :let comma2 = strridx(line, ",", lastcomma - 1)
3911< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003912 For pattern searches use |match()|.
3913 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003914 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003915 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003916 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaar05159a02005-02-26 23:04:13 +00003917< *strrchr()*
3918 When used with a single character it works similar to the C
3919 function strrchr().
3920
Bram Moolenaar071d4272004-06-13 20:20:40 +00003921strtrans({expr}) *strtrans()*
3922 The result is a String, which is {expr} with all unprintable
3923 characters translated into printable characters |'isprint'|.
3924 Like they are shown in a window. Example: >
3925 echo strtrans(@a)
3926< This displays a newline in register a as "^@" instead of
3927 starting a new line.
3928
3929submatch({nr}) *submatch()*
3930 Only for an expression in a |:substitute| command. Returns
3931 the {nr}'th submatch of the matched text. When {nr} is 0
3932 the whole matched text is returned.
3933 Example: >
3934 :s/\d\+/\=submatch(0) + 1/
3935< This finds the first number in the line and adds one to it.
3936 A line break is included as a newline character.
3937
3938substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
3939 The result is a String, which is a copy of {expr}, in which
3940 the first match of {pat} is replaced with {sub}. This works
3941 like the ":substitute" command (without any flags). But the
3942 matching with {pat} is always done like the 'magic' option is
3943 set and 'cpoptions' is empty (to make scripts portable).
3944 See |string-match| for how {pat} is used.
3945 And a "~" in {sub} is not replaced with the previous {sub}.
3946 Note that some codes in {sub} have a special meaning
3947 |sub-replace-special|. For example, to replace something with
3948 "\n" (two characters), use "\\\\n" or '\\n'.
3949 When {pat} does not match in {expr}, {expr} is returned
3950 unmodified.
3951 When {flags} is "g", all matches of {pat} in {expr} are
3952 replaced. Otherwise {flags} should be "".
3953 Example: >
3954 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
3955< This removes the last component of the 'path' option. >
3956 :echo substitute("testing", ".*", "\\U\\0", "")
3957< results in "TESTING".
3958
Bram Moolenaar47136d72004-10-12 20:02:24 +00003959synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003960 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00003961 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003962 The syntax ID can be used with |synIDattr()| and
3963 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaar47136d72004-10-12 20:02:24 +00003964 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaar071d4272004-06-13 20:20:40 +00003965 line.
3966 When {trans} is non-zero, transparent items are reduced to the
3967 item that they reveal. This is useful when wanting to know
3968 the effective color. When {trans} is zero, the transparent
3969 item is returned. This is useful when wanting to know which
3970 syntax item is effective (e.g. inside parens).
3971 Warning: This function can be very slow. Best speed is
3972 obtained by going through the file in forward direction.
3973
3974 Example (echoes the name of the syntax item under the cursor): >
3975 :echo synIDattr(synID(line("."), col("."), 1), "name")
3976<
3977synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
3978 The result is a String, which is the {what} attribute of
3979 syntax ID {synID}. This can be used to obtain information
3980 about a syntax item.
3981 {mode} can be "gui", "cterm" or "term", to get the attributes
3982 for that mode. When {mode} is omitted, or an invalid value is
3983 used, the attributes for the currently active highlighting are
3984 used (GUI, cterm or term).
3985 Use synIDtrans() to follow linked highlight groups.
3986 {what} result
3987 "name" the name of the syntax item
3988 "fg" foreground color (GUI: color name used to set
3989 the color, cterm: color number as a string,
3990 term: empty string)
3991 "bg" background color (like "fg")
3992 "fg#" like "fg", but for the GUI and the GUI is
3993 running the name in "#RRGGBB" form
3994 "bg#" like "fg#" for "bg"
3995 "bold" "1" if bold
3996 "italic" "1" if italic
3997 "reverse" "1" if reverse
3998 "inverse" "1" if inverse (= reverse)
3999 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004000 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00004001
4002 Example (echoes the color of the syntax item under the
4003 cursor): >
4004 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
4005<
4006synIDtrans({synID}) *synIDtrans()*
4007 The result is a Number, which is the translated syntax ID of
4008 {synID}. This is the syntax group ID of what is being used to
4009 highlight the character. Highlight links given with
4010 ":highlight link" are followed.
4011
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004012system({expr} [, {input}]) *system()* *E677*
4013 Get the output of the shell command {expr}.
4014 When {input} is given, this string is written to a file and
4015 passed as stdin to the command. The string is written as-is,
4016 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00004017 yourself. Pipes are not used.
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004018 Note: newlines in {expr} may cause the command to fail. The
4019 characters in 'shellquote' and 'shellxquote' may also cause
4020 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004021 This is not to be used for interactive commands.
4022 The result is a String. Example: >
4023
4024 :let files = system("ls")
4025
4026< To make the result more system-independent, the shell output
4027 is filtered to replace <CR> with <NL> for Macintosh, and
4028 <CR><NL> with <NL> for DOS-like systems.
4029 The command executed is constructed using several options:
4030 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
4031 ({tmp} is an automatically generated file name).
4032 For Unix and OS/2 braces are put around {expr} to allow for
4033 concatenated commands.
4034
4035 The resulting error code can be found in |v:shell_error|.
4036 This function will fail in |restricted-mode|.
4037 Unlike ":!cmd" there is no automatic check for changed files.
4038 Use |:checktime| to force a check.
4039
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004040
4041taglist({expr}) *taglist()*
4042 Returns a list of tags matching the regular expression {expr}.
4043 Each list item is a dictionary with the following entries:
4044 name name of the tag.
4045 filename name of the file where the tag is
4046 defined.
4047 cmd Ex command used to locate the tag in
4048 the file.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004049 kind type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004050 entry depends on the language specific
4051 kind values generated by the ctags
4052 tool.
4053 static a file specific tag. Refer to
4054 |static-tag| for more information.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004055 The "kind" entry is only available when using Exuberant ctags
4056 generated tags file. More entries may be present, depending
4057 on the content of the tags file: access, implementation,
4058 inherits and signature. Refer to the ctags documentation for
4059 information about these fields. For C code the fields
4060 "struct", "class" and "enum" may appear, they give the name of
4061 the entity the tag is contained in.
4062
4063 The ex-command 'cmd' can be either an ex search pattern, a
4064 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004065
4066 If there are no matching tags, then an empty list is returned.
4067
4068 To get an exact tag match, the anchors '^' and '$' should be
4069 used in {expr}. Refer to |tag-regexp| for more information
4070 about the tag search regular expression pattern.
4071
4072 Refer to |'tags'| for information about how the tags file is
4073 located by Vim. Refer to |tags-file-format| for the format of
4074 the tags file generated by the different ctags tools.
4075
4076
Bram Moolenaar071d4272004-06-13 20:20:40 +00004077tempname() *tempname()* *temp-file-name*
4078 The result is a String, which is the name of a file that
4079 doesn't exist. It can be used for a temporary file. The name
4080 is different for at least 26 consecutive calls. Example: >
4081 :let tmpfile = tempname()
4082 :exe "redir > " . tmpfile
4083< For Unix, the file will be in a private directory (only
4084 accessible by the current user) to avoid security problems
4085 (e.g., a symlink attack or other people reading your file).
4086 When Vim exits the directory and all files in it are deleted.
4087 For MS-Windows forward slashes are used when the 'shellslash'
4088 option is set or when 'shellcmdflag' starts with '-'.
4089
4090tolower({expr}) *tolower()*
4091 The result is a copy of the String given, with all uppercase
4092 characters turned into lowercase (just like applying |gu| to
4093 the string).
4094
4095toupper({expr}) *toupper()*
4096 The result is a copy of the String given, with all lowercase
4097 characters turned into uppercase (just like applying |gU| to
4098 the string).
4099
Bram Moolenaar8299df92004-07-10 09:47:34 +00004100tr({src}, {fromstr}, {tostr}) *tr()*
4101 The result is a copy of the {src} string with all characters
4102 which appear in {fromstr} replaced by the character in that
4103 position in the {tostr} string. Thus the first character in
4104 {fromstr} is translated into the first character in {tostr}
4105 and so on. Exactly like the unix "tr" command.
4106 This code also deals with multibyte characters properly.
4107
4108 Examples: >
4109 echo tr("hello there", "ht", "HT")
4110< returns "Hello THere" >
4111 echo tr("<blob>", "<>", "{}")
4112< returns "{blob}"
4113
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004114 *type()*
4115type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00004116 Number: 0
4117 String: 1
4118 Funcref: 2
4119 List: 3
4120 Dictionary: 4
4121 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004122 :if type(myvar) == type(0)
4123 :if type(myvar) == type("")
4124 :if type(myvar) == type(function("tr"))
4125 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00004126 :if type(myvar) == type({})
Bram Moolenaar071d4272004-06-13 20:20:40 +00004127
Bram Moolenaar677ee682005-01-27 14:41:15 +00004128values({dict}) *values()*
4129 Return a List with all the values of {dict}. The List is in
4130 arbitrary order.
4131
4132
Bram Moolenaar071d4272004-06-13 20:20:40 +00004133virtcol({expr}) *virtcol()*
4134 The result is a Number, which is the screen column of the file
4135 position given with {expr}. That is, the last screen position
4136 occupied by the character at that position, when the screen
4137 would be of unlimited width. When there is a <Tab> at the
4138 position, the returned Number will be the column at the end of
4139 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
4140 set to 8, it returns 8.
4141 For the byte position use |col()|.
4142 When Virtual editing is active in the current mode, a position
4143 beyond the end of the line can be returned. |'virtualedit'|
4144 The accepted positions are:
4145 . the cursor position
4146 $ the end of the cursor line (the result is the
4147 number of displayed characters in the cursor line
4148 plus one)
4149 'x position of mark x (if the mark is not set, 0 is
4150 returned)
4151 Note that only marks in the current file can be used.
4152 Examples: >
4153 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
4154 virtcol("$") with text "foo^Lbar", returns 9
4155 virtcol("'t") with text " there", with 't at 'h', returns 6
4156< The first column is 1. 0 is returned for an error.
4157
4158visualmode([expr]) *visualmode()*
4159 The result is a String, which describes the last Visual mode
4160 used. Initially it returns an empty string, but once Visual
4161 mode has been used, it returns "v", "V", or "<CTRL-V>" (a
4162 single CTRL-V character) for character-wise, line-wise, or
4163 block-wise Visual mode respectively.
4164 Example: >
4165 :exe "normal " . visualmode()
4166< This enters the same Visual mode as before. It is also useful
4167 in scripts if you wish to act differently depending on the
4168 Visual mode that was used.
4169
4170 If an expression is supplied that results in a non-zero number
4171 or a non-empty string, then the Visual mode will be cleared
4172 and the old value is returned. Note that " " and "0" are also
4173 non-empty strings, thus cause the mode to be cleared.
4174
4175 *winbufnr()*
4176winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004177 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004178 the buffer in the current window is returned. When window
4179 {nr} doesn't exist, -1 is returned.
4180 Example: >
4181 :echo "The file in the current window is " . bufname(winbufnr(0))
4182<
4183 *wincol()*
4184wincol() The result is a Number, which is the virtual column of the
4185 cursor in the window. This is counting screen cells from the
4186 left side of the window. The leftmost column is one.
4187
4188winheight({nr}) *winheight()*
4189 The result is a Number, which is the height of window {nr}.
4190 When {nr} is zero, the height of the current window is
4191 returned. When window {nr} doesn't exist, -1 is returned.
4192 An existing window always has a height of zero or more.
4193 Examples: >
4194 :echo "The current window has " . winheight(0) . " lines."
4195<
4196 *winline()*
4197winline() The result is a Number, which is the screen line of the cursor
4198 in the window. This is counting screen lines from the top of
4199 the window. The first line is one.
4200
4201 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004202winnr([{arg}]) The result is a Number, which is the number of the current
4203 window. The top window has number 1.
4204 When the optional argument is "$", the number of the
4205 last window is returnd (the window count).
4206 When the optional argument is "#", the number of the last
4207 accessed window is returned (where |CTRL-W_p| goes to).
4208 If there is no previous window 0 is returned.
4209 The number can be used with |CTRL-W_w| and ":wincmd w"
4210 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004211
4212 *winrestcmd()*
4213winrestcmd() Returns a sequence of |:resize| commands that should restore
4214 the current window sizes. Only works properly when no windows
4215 are opened or closed and the current window is unchanged.
4216 Example: >
4217 :let cmd = winrestcmd()
4218 :call MessWithWindowSizes()
4219 :exe cmd
4220
4221winwidth({nr}) *winwidth()*
4222 The result is a Number, which is the width of window {nr}.
4223 When {nr} is zero, the width of the current window is
4224 returned. When window {nr} doesn't exist, -1 is returned.
4225 An existing window always has a width of zero or more.
4226 Examples: >
4227 :echo "The current window has " . winwidth(0) . " columns."
4228 :if winwidth(0) <= 50
4229 : exe "normal 50\<C-W>|"
4230 :endif
4231<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004232 *writefile()*
4233writefile({list}, {fname} [, {binary}])
4234 Write List {list} to file {fname}. Each list item is
4235 separated with a NL. Each list item must be a String or
4236 Number.
4237 When {binary} is equal to "b" binary mode is used: There will
4238 not be a NL after the last list item. An empty item at the
4239 end does cause the last line in the file to end in a NL.
4240 All NL characters are replaced with a NUL character.
4241 Inserting CR characters needs to be done before passing {list}
4242 to writefile().
4243 An existing file is overwritten, if possible.
4244 When the write fails -1 is returned, otherwise 0. There is an
4245 error message if the file can't be created or when writing
4246 fails.
4247 Also see |readfile()|.
4248 To copy a file byte for byte: >
4249 :let fl = readfile("foo", "b")
4250 :call writefile(fl, "foocopy", "b")
4251<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004252
4253 *feature-list*
4254There are three types of features:
42551. Features that are only supported when they have been enabled when Vim
4256 was compiled |+feature-list|. Example: >
4257 :if has("cindent")
42582. Features that are only supported when certain conditions have been met.
4259 Example: >
4260 :if has("gui_running")
4261< *has-patch*
42623. Included patches. First check |v:version| for the version of Vim.
4263 Then the "patch123" feature means that patch 123 has been included for
4264 this version. Example (checking version 6.2.148 or later): >
4265 :if v:version > 602 || v:version == 602 && has("patch148")
4266
4267all_builtin_terms Compiled with all builtin terminals enabled.
4268amiga Amiga version of Vim.
4269arabic Compiled with Arabic support |Arabic|.
4270arp Compiled with ARP support (Amiga).
4271autocmd Compiled with autocommands support.
4272balloon_eval Compiled with |balloon-eval| support.
4273beos BeOS version of Vim.
4274browse Compiled with |:browse| support, and browse() will
4275 work.
4276builtin_terms Compiled with some builtin terminals.
4277byte_offset Compiled with support for 'o' in 'statusline'
4278cindent Compiled with 'cindent' support.
4279clientserver Compiled with remote invocation support |clientserver|.
4280clipboard Compiled with 'clipboard' support.
4281cmdline_compl Compiled with |cmdline-completion| support.
4282cmdline_hist Compiled with |cmdline-history| support.
4283cmdline_info Compiled with 'showcmd' and 'ruler' support.
4284comments Compiled with |'comments'| support.
4285cryptv Compiled with encryption support |encryption|.
4286cscope Compiled with |cscope| support.
4287compatible Compiled to be very Vi compatible.
4288debug Compiled with "DEBUG" defined.
4289dialog_con Compiled with console dialog support.
4290dialog_gui Compiled with GUI dialog support.
4291diff Compiled with |vimdiff| and 'diff' support.
4292digraphs Compiled with support for digraphs.
4293dnd Compiled with support for the "~ register |quote_~|.
4294dos32 32 bits DOS (DJGPP) version of Vim.
4295dos16 16 bits DOS version of Vim.
4296ebcdic Compiled on a machine with ebcdic character set.
4297emacs_tags Compiled with support for Emacs tags.
4298eval Compiled with expression evaluation support. Always
4299 true, of course!
4300ex_extra Compiled with extra Ex commands |+ex_extra|.
4301extra_search Compiled with support for |'incsearch'| and
4302 |'hlsearch'|
4303farsi Compiled with Farsi support |farsi|.
4304file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004305filterpipe When 'shelltemp' is off pipes are used for shell
4306 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00004307find_in_path Compiled with support for include file searches
4308 |+find_in_path|.
4309fname_case Case in file names matters (for Amiga, MS-DOS, and
4310 Windows this is not present).
4311folding Compiled with |folding| support.
4312footer Compiled with GUI footer support. |gui-footer|
4313fork Compiled to use fork()/exec() instead of system().
4314gettext Compiled with message translation |multi-lang|
4315gui Compiled with GUI enabled.
4316gui_athena Compiled with Athena GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004317gui_gtk Compiled with GTK+ GUI (any version).
4318gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar843ee412004-06-30 16:16:41 +00004319gui_kde Compiled with KDE GUI |KVim|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004320gui_mac Compiled with Macintosh GUI.
4321gui_motif Compiled with Motif GUI.
4322gui_photon Compiled with Photon GUI.
4323gui_win32 Compiled with MS Windows Win32 GUI.
4324gui_win32s idem, and Win32s system being used (Windows 3.1)
4325gui_running Vim is running in the GUI, or it will start soon.
4326hangul_input Compiled with Hangul input support. |hangul|
4327iconv Can use iconv() for conversion.
4328insert_expand Compiled with support for CTRL-X expansion commands in
4329 Insert mode.
4330jumplist Compiled with |jumplist| support.
4331keymap Compiled with 'keymap' support.
4332langmap Compiled with 'langmap' support.
4333libcall Compiled with |libcall()| support.
4334linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
4335 support.
4336lispindent Compiled with support for lisp indenting.
4337listcmds Compiled with commands for the buffer list |:files|
4338 and the argument list |arglist|.
4339localmap Compiled with local mappings and abbr. |:map-local|
4340mac Macintosh version of Vim.
4341macunix Macintosh version of Vim, using Unix files (OS-X).
4342menu Compiled with support for |:menu|.
4343mksession Compiled with support for |:mksession|.
4344modify_fname Compiled with file name modifiers. |filename-modifiers|
4345mouse Compiled with support mouse.
4346mouseshape Compiled with support for 'mouseshape'.
4347mouse_dec Compiled with support for Dec terminal mouse.
4348mouse_gpm Compiled with support for gpm (Linux console mouse)
4349mouse_netterm Compiled with support for netterm mouse.
4350mouse_pterm Compiled with support for qnx pterm mouse.
4351mouse_xterm Compiled with support for xterm mouse.
4352multi_byte Compiled with support for editing Korean et al.
4353multi_byte_ime Compiled with support for IME input method.
4354multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00004355mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004356netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00004357netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004358ole Compiled with OLE automation support for Win32.
4359os2 OS/2 version of Vim.
4360osfiletype Compiled with support for osfiletypes |+osfiletype|
4361path_extra Compiled with up/downwards search in 'path' and 'tags'
4362perl Compiled with Perl interface.
4363postscript Compiled with PostScript file printing.
4364printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004365profile Compiled with |:profile| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004366python Compiled with Python interface.
4367qnx QNX version of Vim.
4368quickfix Compiled with |quickfix| support.
4369rightleft Compiled with 'rightleft' support.
4370ruby Compiled with Ruby interface |ruby|.
4371scrollbind Compiled with 'scrollbind' support.
4372showcmd Compiled with 'showcmd' support.
4373signs Compiled with |:sign| support.
4374smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004375sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004376statusline Compiled with support for 'statusline', 'rulerformat'
4377 and special formats of 'titlestring' and 'iconstring'.
4378sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00004379spell Compiled with spell checking support |spell|.
4380syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004381syntax_items There are active syntax highlighting items for the
4382 current buffer.
4383system Compiled to use system() instead of fork()/exec().
4384tag_binary Compiled with binary searching in tags files
4385 |tag-binary-search|.
4386tag_old_static Compiled with support for old static tags
4387 |tag-old-static|.
4388tag_any_white Compiled with support for any white characters in tags
4389 files |tag-any-white|.
4390tcl Compiled with Tcl interface.
4391terminfo Compiled with terminfo instead of termcap.
4392termresponse Compiled with support for |t_RV| and |v:termresponse|.
4393textobjects Compiled with support for |text-objects|.
4394tgetent Compiled with tgetent support, able to use a termcap
4395 or terminfo file.
4396title Compiled with window title support |'title'|.
4397toolbar Compiled with support for |gui-toolbar|.
4398unix Unix version of Vim.
4399user_commands User-defined commands.
4400viminfo Compiled with viminfo support.
4401vim_starting True while initial source'ing takes place.
4402vertsplit Compiled with vertically split windows |:vsplit|.
4403virtualedit Compiled with 'virtualedit' option.
4404visual Compiled with Visual mode.
4405visualextra Compiled with extra Visual mode commands.
4406 |blockwise-operators|.
4407vms VMS version of Vim.
4408vreplace Compiled with |gR| and |gr| commands.
4409wildignore Compiled with 'wildignore' option.
4410wildmenu Compiled with 'wildmenu' option.
4411windows Compiled with support for more than one window.
4412winaltkeys Compiled with 'winaltkeys' option.
4413win16 Win16 version of Vim (MS-Windows 3.1).
4414win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
4415win64 Win64 version of Vim (MS-Windows 64 bit).
4416win32unix Win32 version of Vim, using Unix files (Cygwin)
4417win95 Win32 version for MS-Windows 95/98/ME.
4418writebackup Compiled with 'writebackup' default on.
4419xfontset Compiled with X fontset support |xfontset|.
4420xim Compiled with X input method support |xim|.
4421xsmp Compiled with X session management support.
4422xsmp_interact Compiled with interactive X session management support.
4423xterm_clipboard Compiled with support for xterm clipboard.
4424xterm_save Compiled with support for saving and restoring the
4425 xterm screen.
4426x11 Compiled with X11 support.
4427
4428 *string-match*
4429Matching a pattern in a String
4430
4431A regexp pattern as explained at |pattern| is normally used to find a match in
4432the buffer lines. When a pattern is used to find a match in a String, almost
4433everything works in the same way. The difference is that a String is handled
4434like it is one line. When it contains a "\n" character, this is not seen as a
4435line break for the pattern. It can be matched with a "\n" in the pattern, or
4436with ".". Example: >
4437 :let a = "aaaa\nxxxx"
4438 :echo matchstr(a, "..\n..")
4439 aa
4440 xx
4441 :echo matchstr(a, "a.x")
4442 a
4443 x
4444
4445Don't forget that "^" will only match at the first character of the String and
4446"$" at the last character of the string. They don't match after or before a
4447"\n".
4448
4449==============================================================================
44505. Defining functions *user-functions*
4451
4452New functions can be defined. These can be called just like builtin
4453functions. The function executes a sequence of Ex commands. Normal mode
4454commands can be executed with the |:normal| command.
4455
4456The function name must start with an uppercase letter, to avoid confusion with
4457builtin functions. To prevent from using the same name in different scripts
4458avoid obvious, short names. A good habit is to start the function name with
4459the name of the script, e.g., "HTMLcolor()".
4460
4461It's also possible to use curly braces, see |curly-braces-names|.
4462
4463 *local-function*
4464A function local to a script must start with "s:". A local script function
4465can only be called from within the script and from functions, user commands
4466and autocommands defined in the script. It is also possible to call the
4467function from a mappings defined in the script, but then |<SID>| must be used
4468instead of "s:" when the mapping is expanded outside of the script.
4469
4470 *:fu* *:function* *E128* *E129* *E123*
4471:fu[nction] List all functions and their arguments.
4472
4473:fu[nction] {name} List function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004474 {name} can also be a Dictionary entry that is a
4475 Funcref: >
4476 :function dict.init
4477< *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004478:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004479 Define a new function by the name {name}. The name
4480 must be made of alphanumeric characters and '_', and
4481 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004482
4483 {name} can also be a Dictionary entry that is a
4484 Funcref: >
4485 :function dict.init(arg)
4486< "dict" must be an existing dictionary. The entry
4487 "init" is added if it didn't exist yet. Otherwise [!]
4488 is required to overwrite an existing function. The
4489 result is a |Funcref| to a numbered function. The
4490 function can only be used with a |Funcref| and will be
4491 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004492 *E127* *E122*
4493 When a function by this name already exists and [!] is
4494 not used an error message is given. When [!] is used,
4495 an existing function is silently replaced. Unless it
4496 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004497
4498 For the {arguments} see |function-argument|.
4499
Bram Moolenaar071d4272004-06-13 20:20:40 +00004500 *a:firstline* *a:lastline*
4501 When the [range] argument is added, the function is
4502 expected to take care of a range itself. The range is
4503 passed as "a:firstline" and "a:lastline". If [range]
4504 is excluded, ":{range}call" will call the function for
4505 each line in the range, with the cursor on the start
4506 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004507
Bram Moolenaar071d4272004-06-13 20:20:40 +00004508 When the [abort] argument is added, the function will
4509 abort as soon as an error is detected.
4510 The last used search pattern and the redo command "."
4511 will not be changed by the function.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004512
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004513 When the [dict] argument is added, the function must
4514 be invoked through an entry in a Dictionary. The
4515 local variable "self" will then be set to the
4516 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004517
4518 *:endf* *:endfunction* *E126* *E193*
4519:endf[unction] The end of a function definition. Must be on a line
4520 by its own, without other commands.
4521
4522 *:delf* *:delfunction* *E130* *E131*
4523:delf[unction] {name} Delete function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004524 {name} can also be a Dictionary entry that is a
4525 Funcref: >
4526 :delfunc dict.init
4527< This will remove the "init" entry from "dict". The
4528 function is deleted if there are no more references to
4529 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004530 *:retu* *:return* *E133*
4531:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
4532 evaluated and returned as the result of the function.
4533 If "[expr]" is not given, the number 0 is returned.
4534 When a function ends without an explicit ":return",
4535 the number 0 is returned.
4536 Note that there is no check for unreachable lines,
4537 thus there is no warning if commands follow ":return".
4538
4539 If the ":return" is used after a |:try| but before the
4540 matching |:finally| (if present), the commands
4541 following the ":finally" up to the matching |:endtry|
4542 are executed first. This process applies to all
4543 nested ":try"s inside the function. The function
4544 returns at the outermost ":endtry".
4545
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004546 *function-argument* *a:var*
4547An argument can be defined by giving its name. In the function this can then
4548be used as "a:name" ("a:" for argument).
4549 *a:0* *a:1* *a:000* *E740*
4550Up to 20 arguments can be given, separated by commas. After the named
4551arguments an argument "..." can be specified, which means that more arguments
4552may optionally be following. In the function the extra arguments can be used
4553as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004554can be 0). "a:000" is set to a List that contains these arguments. Note that
4555"a:1" is the same as "a:000[0]".
4556 *E742*
4557The a: scope and the variables in it cannot be changed, they are fixed.
4558However, if a List or Dictionary is used, you can changes their contents.
4559Thus you can pass a List to a function and have the function add an item to
4560it. If you want to make sure the function cannot change a List or Dictionary
4561use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004562
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004563When not using "...", the number of arguments in a function call must be equal
4564to the number of named arguments. When using "...", the number of arguments
4565may be larger.
4566
4567It is also possible to define a function without any arguments. You must
4568still supply the () then. The body of the function follows in the next lines,
4569until the matching |:endfunction|. It is allowed to define another function
4570inside a function body.
4571
4572 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004573Inside a function variables can be used. These are local variables, which
4574will disappear when the function returns. Global variables need to be
4575accessed with "g:".
4576
4577Example: >
4578 :function Table(title, ...)
4579 : echohl Title
4580 : echo a:title
4581 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00004582 : echo a:0 . " items:"
4583 : for s in a:000
4584 : echon ' ' . s
4585 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004586 :endfunction
4587
4588This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00004589 call Table("Table", "line1", "line2")
4590 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004591
4592To return more than one value, pass the name of a global variable: >
4593 :function Compute(n1, n2, divname)
4594 : if a:n2 == 0
4595 : return "fail"
4596 : endif
4597 : let g:{a:divname} = a:n1 / a:n2
4598 : return "ok"
4599 :endfunction
4600
4601This function can then be called with: >
4602 :let success = Compute(13, 1324, "div")
4603 :if success == "ok"
4604 : echo div
4605 :endif
4606
4607An alternative is to return a command that can be executed. This also works
4608with local variables in a calling function. Example: >
4609 :function Foo()
4610 : execute Bar()
4611 : echo "line " . lnum . " column " . col
4612 :endfunction
4613
4614 :function Bar()
4615 : return "let lnum = " . line(".") . " | let col = " . col(".")
4616 :endfunction
4617
4618The names "lnum" and "col" could also be passed as argument to Bar(), to allow
4619the caller to set the names.
4620
4621 *:cal* *:call* *E107*
4622:[range]cal[l] {name}([arguments])
4623 Call a function. The name of the function and its arguments
4624 are as specified with |:function|. Up to 20 arguments can be
4625 used.
4626 Without a range and for functions that accept a range, the
4627 function is called once. When a range is given the cursor is
4628 positioned at the start of the first line before executing the
4629 function.
4630 When a range is given and the function doesn't handle it
4631 itself, the function is executed for each line in the range,
4632 with the cursor in the first column of that line. The cursor
4633 is left at the last line (possibly moved by the last function
4634 call). The arguments are re-evaluated for each line. Thus
4635 this works:
4636 *function-range-example* >
4637 :function Mynumber(arg)
4638 : echo line(".") . " " . a:arg
4639 :endfunction
4640 :1,5call Mynumber(getline("."))
4641<
4642 The "a:firstline" and "a:lastline" are defined anyway, they
4643 can be used to do something different at the start or end of
4644 the range.
4645
4646 Example of a function that handles the range itself: >
4647
4648 :function Cont() range
4649 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
4650 :endfunction
4651 :4,8call Cont()
4652<
4653 This function inserts the continuation character "\" in front
4654 of all the lines in the range, except the first one.
4655
4656 *E132*
4657The recursiveness of user functions is restricted with the |'maxfuncdepth'|
4658option.
4659
Bram Moolenaar7c626922005-02-07 22:01:03 +00004660
4661AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004662 *autoload-functions*
4663When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00004664only when they are used. There are two methods: with an autocommand and with
4665the "autoload" directory in 'runtimepath'.
4666
4667
4668Using an autocommand ~
4669
Bram Moolenaar05159a02005-02-26 23:04:13 +00004670This is introduced in the user manual, section |41.14|.
4671
Bram Moolenaar7c626922005-02-07 22:01:03 +00004672The autocommand is useful if you have a plugin that is a long Vim script file.
4673You can define the autocommand and quickly quit the script with |:finish|.
4674That makes Vim startup faster. The autocommand should then load the same file
4675again, setting a variable to skip the |:finish| command.
4676
4677Use the FuncUndefined autocommand event with a pattern that matches the
4678function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004679
4680 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
4681
4682The file "~/vim/bufnetfuncs.vim" should then define functions that start with
4683"BufNet". Also see |FuncUndefined|.
4684
Bram Moolenaar7c626922005-02-07 22:01:03 +00004685
4686Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004687 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00004688This is introduced in the user manual, section |41.15|.
4689
Bram Moolenaar7c626922005-02-07 22:01:03 +00004690Using a script in the "autoload" directory is simpler, but requires using
4691exactly the right file name. A function that can be autoloaded has a name
4692like this: >
4693
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004694 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004695
4696When such a function is called, and it is not defined yet, Vim will search the
4697"autoload" directories in 'runtimepath' for a script file called
4698"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
4699then define the function like this: >
4700
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004701 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004702 echo "Done!"
4703 endfunction
4704
4705The file name and the name used before the colon in the function must match
4706exactly, and the defined function must have the name exactly as it will be
4707called.
4708
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004709It is possible to use subdirectories. Every # in the function name works like
4710a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00004711
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004712 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00004713
4714Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
4715
4716The name before the first colon must be at least two characters long,
4717otherwise it looks like a scope, such as "s:".
4718
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004719This also works when reading a variable that has not been set yet: >
4720
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004721 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004722
4723When assigning a value to such a variable nothing special happens. This can
4724be used to pass settings to the autoload script before it's loaded: >
4725
Bram Moolenaara7fc0102005-05-18 22:17:12 +00004726 :let foo#bar#toggle = 1
4727 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004728
Bram Moolenaar4399ef42005-02-12 14:29:27 +00004729Note that when you make a mistake and call a function that is supposed to be
4730defined in an autoload script, but the script doesn't actually define the
4731function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004732And you will get an error message every time.
4733
4734Also note that if you have two script files, and one calls a function in the
4735other and vise versa, before the used function is defined, it won't work.
4736Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00004737
Bram Moolenaar071d4272004-06-13 20:20:40 +00004738==============================================================================
47396. Curly braces names *curly-braces-names*
4740
4741Wherever you can use a variable, you can use a "curly braces name" variable.
4742This is a regular variable name with one or more expressions wrapped in braces
4743{} like this: >
4744 my_{adjective}_variable
4745
4746When Vim encounters this, it evaluates the expression inside the braces, puts
4747that in place of the expression, and re-interprets the whole as a variable
4748name. So in the above example, if the variable "adjective" was set to
4749"noisy", then the reference would be to "my_noisy_variable", whereas if
4750"adjective" was set to "quiet", then it would be to "my_quiet_variable".
4751
4752One application for this is to create a set of variables governed by an option
4753value. For example, the statement >
4754 echo my_{&background}_message
4755
4756would output the contents of "my_dark_message" or "my_light_message" depending
4757on the current value of 'background'.
4758
4759You can use multiple brace pairs: >
4760 echo my_{adverb}_{adjective}_message
4761..or even nest them: >
4762 echo my_{ad{end_of_word}}_message
4763where "end_of_word" is either "verb" or "jective".
4764
4765However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004766variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004767 :let foo='a + b'
4768 :echo c{foo}d
4769.. since the result of expansion is "ca + bd", which is not a variable name.
4770
4771 *curly-braces-function-names*
4772You can call and define functions by an evaluated name in a similar way.
4773Example: >
4774 :let func_end='whizz'
4775 :call my_func_{func_end}(parameter)
4776
4777This would call the function "my_func_whizz(parameter)".
4778
4779==============================================================================
47807. Commands *expression-commands*
4781
4782:let {var-name} = {expr1} *:let* *E18*
4783 Set internal variable {var-name} to the result of the
4784 expression {expr1}. The variable will get the type
4785 from the {expr}. If {var-name} didn't exist yet, it
4786 is created.
4787
Bram Moolenaar13065c42005-01-08 16:08:21 +00004788:let {var-name}[{idx}] = {expr1} *E689*
4789 Set a list item to the result of the expression
4790 {expr1}. {var-name} must refer to a list and {idx}
4791 must be a valid index in that list. For nested list
4792 the index can be repeated.
4793 This cannot be used to add an item to a list.
4794
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004795 *E711* *E719*
4796:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004797 Set a sequence of items in a List to the result of the
4798 expression {expr1}, which must be a list with the
4799 correct number of items.
4800 {idx1} can be omitted, zero is used instead.
4801 {idx2} can be omitted, meaning the end of the list.
4802 When the selected range of items is partly past the
4803 end of the list, items will be added.
4804
Bram Moolenaar748bf032005-02-02 23:04:36 +00004805 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004806:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
4807:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
4808:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
4809 These fail if {var} was not set yet and when the type
4810 of {var} and {expr1} don't fit the operator.
4811
4812
Bram Moolenaar071d4272004-06-13 20:20:40 +00004813:let ${env-name} = {expr1} *:let-environment* *:let-$*
4814 Set environment variable {env-name} to the result of
4815 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004816:let ${env-name} .= {expr1}
4817 Append {expr1} to the environment variable {env-name}.
4818 If the environment variable didn't exist yet this
4819 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004820
4821:let @{reg-name} = {expr1} *:let-register* *:let-@*
4822 Write the result of the expression {expr1} in register
4823 {reg-name}. {reg-name} must be a single letter, and
4824 must be the name of a writable register (see
4825 |registers|). "@@" can be used for the unnamed
4826 register, "@/" for the search pattern.
4827 If the result of {expr1} ends in a <CR> or <NL>, the
4828 register will be linewise, otherwise it will be set to
4829 characterwise.
4830 This can be used to clear the last search pattern: >
4831 :let @/ = ""
4832< This is different from searching for an empty string,
4833 that would match everywhere.
4834
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004835:let @{reg-name} .= {expr1}
4836 Append {expr1} to register {reg-name}. If the
4837 register was empty it's like setting it to {expr1}.
4838
Bram Moolenaar071d4272004-06-13 20:20:40 +00004839:let &{option-name} = {expr1} *:let-option* *:let-star*
4840 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004841 expression {expr1}. A String or Number value is
4842 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004843 For an option local to a window or buffer the effect
4844 is just like using the |:set| command: both the local
4845 value and the global value is changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004846 Example: >
4847 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004848
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004849:let &{option-name} .= {expr1}
4850 For a string option: Append {expr1} to the value.
4851 Does not insert a comma like |:set+=|.
4852
4853:let &{option-name} += {expr1}
4854:let &{option-name} -= {expr1}
4855 For a number or boolean option: Add or subtract
4856 {expr1}.
4857
Bram Moolenaar071d4272004-06-13 20:20:40 +00004858:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004859:let &l:{option-name} .= {expr1}
4860:let &l:{option-name} += {expr1}
4861:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004862 Like above, but only set the local value of an option
4863 (if there is one). Works like |:setlocal|.
4864
4865:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004866:let &g:{option-name} .= {expr1}
4867:let &g:{option-name} += {expr1}
4868:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004869 Like above, but only set the global value of an option
4870 (if there is one). Works like |:setglobal|.
4871
Bram Moolenaar13065c42005-01-08 16:08:21 +00004872:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004873 {expr1} must evaluate to a List. The first item in
4874 the list is assigned to {name1}, the second item to
4875 {name2}, etc.
4876 The number of names must match the number of items in
4877 the List.
4878 Each name can be one of the items of the ":let"
4879 command as mentioned above.
4880 Example: >
4881 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004882< Detail: {expr1} is evaluated first, then the
4883 assignments are done in sequence. This matters if
4884 {name2} depends on {name1}. Example: >
4885 :let x = [0, 1]
4886 :let i = 0
4887 :let [i, x[i]] = [1, 2]
4888 :echo x
4889< The result is [0, 2].
4890
4891:let [{name1}, {name2}, ...] .= {expr1}
4892:let [{name1}, {name2}, ...] += {expr1}
4893:let [{name1}, {name2}, ...] -= {expr1}
4894 Like above, but append/add/subtract the value for each
4895 List item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004896
4897:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar677ee682005-01-27 14:41:15 +00004898 Like |:let-unpack| above, but the List may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004899 items than there are names. A list of the remaining
4900 items is assigned to {lastname}. If there are no
4901 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004902 Example: >
4903 :let [a, b; rest] = ["aval", "bval", 3, 4]
4904<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004905:let [{name}, ..., ; {lastname}] .= {expr1}
4906:let [{name}, ..., ; {lastname}] += {expr1}
4907:let [{name}, ..., ; {lastname}] -= {expr1}
4908 Like above, but append/add/subtract the value for each
4909 List item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004910 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004911:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00004912 variable names may be given. Special names recognized
4913 here: *E738*
4914 g: global variables.
4915 b: local buffer variables.
4916 w: local window variables.
4917 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004918
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004919:let List the values of all variables. The type of the
4920 variable is indicated before the value:
4921 <nothing> String
4922 # Number
4923 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00004924
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004925
4926:unl[et][!] {name} ... *:unlet* *:unl* *E108*
4927 Remove the internal variable {name}. Several variable
4928 names can be given, they are all removed. The name
4929 may also be a List or Dictionary item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004930 With [!] no error message is given for non-existing
4931 variables.
Bram Moolenaar9cd15162005-01-16 22:02:49 +00004932 One or more items from a List can be removed: >
4933 :unlet list[3] " remove fourth item
4934 :unlet list[3:] " remove fourth item to last
4935< One item from a Dictionary can be removed at a time: >
4936 :unlet dict['two']
4937 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00004938
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004939:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
4940 Lock the internal variable {name}. Locking means that
4941 it can no longer be changed (until it is unlocked).
4942 A locked variable can be deleted: >
4943 :lockvar v
4944 :let v = 'asdf' " fails!
4945 :unlet v
4946< *E741*
4947 If you try to change a locked variable you get an
4948 error message: "E741: Value of {name} is locked"
4949
4950 [depth] is relevant when locking a List or Dictionary.
4951 It specifies how deep the locking goes:
4952 1 Lock the List or Dictionary itself,
4953 cannot add or remove items, but can
4954 still change their values.
4955 2 Also lock the values, cannot change
4956 the items. If an item is a List or
4957 Dictionary, cannot add or remove
4958 items, but can still change the
4959 values.
4960 3 Like 2 but for the List/Dictionary in
4961 the List/Dictionary, one level deeper.
4962 The default [depth] is 2, thus when {name} is a List
4963 or Dictionary the values cannot be changed.
4964 *E743*
4965 For unlimited depth use [!] and omit [depth].
4966 However, there is a maximum depth of 100 to catch
4967 loops.
4968
4969 Note that when two variables refer to the same List
4970 and you lock one of them, the List will also be locked
4971 when used through the other variable. Example: >
4972 :let l = [0, 1, 2, 3]
4973 :let cl = l
4974 :lockvar l
4975 :let cl[1] = 99 " won't work!
4976< You may want to make a copy of a list to avoid this.
4977 See |deepcopy()|.
4978
4979
4980:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
4981 Unlock the internal variable {name}. Does the
4982 opposite of |:lockvar|.
4983
4984
Bram Moolenaar071d4272004-06-13 20:20:40 +00004985:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
4986:en[dif] Execute the commands until the next matching ":else"
4987 or ":endif" if {expr1} evaluates to non-zero.
4988
4989 From Vim version 4.5 until 5.0, every Ex command in
4990 between the ":if" and ":endif" is ignored. These two
4991 commands were just to allow for future expansions in a
4992 backwards compatible way. Nesting was allowed. Note
4993 that any ":else" or ":elseif" was ignored, the "else"
4994 part was not executed either.
4995
4996 You can use this to remain compatible with older
4997 versions: >
4998 :if version >= 500
4999 : version-5-specific-commands
5000 :endif
5001< The commands still need to be parsed to find the
5002 "endif". Sometimes an older Vim has a problem with a
5003 new command. For example, ":silent" is recognized as
5004 a ":substitute" command. In that case ":execute" can
5005 avoid problems: >
5006 :if version >= 600
5007 : execute "silent 1,$delete"
5008 :endif
5009<
5010 NOTE: The ":append" and ":insert" commands don't work
5011 properly in between ":if" and ":endif".
5012
5013 *:else* *:el* *E581* *E583*
5014:el[se] Execute the commands until the next matching ":else"
5015 or ":endif" if they previously were not being
5016 executed.
5017
5018 *:elseif* *:elsei* *E582* *E584*
5019:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
5020 is no extra ":endif".
5021
5022:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005023 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005024:endw[hile] Repeat the commands between ":while" and ":endwhile",
5025 as long as {expr1} evaluates to non-zero.
5026 When an error is detected from a command inside the
5027 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00005028 Example: >
5029 :let lnum = 1
5030 :while lnum <= line("$")
5031 :call FixLine(lnum)
5032 :let lnum = lnum + 1
5033 :endwhile
5034<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005035 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00005036 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005037
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005038:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00005039:endfo[r] *:endfo* *:endfor*
5040 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005041 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005042 value of each item.
5043 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00005044 loop, execution continues after the "endfor".
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005045 Changing {list} affects what items are used. Make a
5046 copy if this is unwanted: >
5047 :for item in copy(mylist)
5048< When not making a copy, Vim stores a reference to the
5049 next item in the list, before executing the commands
5050 with the current item. Thus the current item can be
5051 removed without effect. Removing any later item means
5052 it will not be found. Thus the following example
5053 works (an inefficient way to make a list empty): >
5054 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00005055 :call remove(mylist, 0)
5056 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005057< Note that reordering the list (e.g., with sort() or
5058 reverse()) may have unexpected effects.
5059 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00005060 identical to avoid errors for the type of {var}
5061 changing. Unlet the variable at the end of the loop
5062 to allow multiple item types.
5063
5064:for {var} in {string}
5065:endfo[r] Like ":for" above, but use each character in {string}
5066 as a list item.
5067 Composing characters are used as separate characters.
5068 A Number is first converted to a String.
5069
5070:for [{var1}, {var2}, ...] in {listlist}
5071:endfo[r]
5072 Like ":for" above, but each item in {listlist} must be
5073 a list, of which each item is assigned to {var1},
5074 {var2}, etc. Example: >
5075 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
5076 :echo getline(lnum)[col]
5077 :endfor
5078<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005079 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00005080:con[tinue] When used inside a ":while" or ":for" loop, jumps back
5081 to the start of the loop.
5082 If it is used after a |:try| inside the loop but
5083 before the matching |:finally| (if present), the
5084 commands following the ":finally" up to the matching
5085 |:endtry| are executed first. This process applies to
5086 all nested ":try"s inside the loop. The outermost
5087 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005088
5089 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00005090:brea[k] When used inside a ":while" or ":for" loop, skips to
5091 the command after the matching ":endwhile" or
5092 ":endfor".
5093 If it is used after a |:try| inside the loop but
5094 before the matching |:finally| (if present), the
5095 commands following the ":finally" up to the matching
5096 |:endtry| are executed first. This process applies to
5097 all nested ":try"s inside the loop. The outermost
5098 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005099
5100:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
5101:endt[ry] Change the error handling for the commands between
5102 ":try" and ":endtry" including everything being
5103 executed across ":source" commands, function calls,
5104 or autocommand invocations.
5105
5106 When an error or interrupt is detected and there is
5107 a |:finally| command following, execution continues
5108 after the ":finally". Otherwise, or when the
5109 ":endtry" is reached thereafter, the next
5110 (dynamically) surrounding ":try" is checked for
5111 a corresponding ":finally" etc. Then the script
5112 processing is terminated. (Whether a function
5113 definition has an "abort" argument does not matter.)
5114 Example: >
5115 :try | edit too much | finally | echo "cleanup" | endtry
5116 :echo "impossible" " not reached, script terminated above
5117<
5118 Moreover, an error or interrupt (dynamically) inside
5119 ":try" and ":endtry" is converted to an exception. It
5120 can be caught as if it were thrown by a |:throw|
5121 command (see |:catch|). In this case, the script
5122 processing is not terminated.
5123
5124 The value "Vim:Interrupt" is used for an interrupt
5125 exception. An error in a Vim command is converted
5126 to a value of the form "Vim({command}):{errmsg}",
5127 other errors are converted to a value of the form
5128 "Vim:{errmsg}". {command} is the full command name,
5129 and {errmsg} is the message that is displayed if the
5130 error exception is not caught, always beginning with
5131 the error number.
5132 Examples: >
5133 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
5134 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
5135<
5136 *:cat* *:catch* *E603* *E604* *E605*
5137:cat[ch] /{pattern}/ The following commands until the next ":catch",
5138 |:finally|, or |:endtry| that belongs to the same
5139 |:try| as the ":catch" are executed when an exception
5140 matching {pattern} is being thrown and has not yet
5141 been caught by a previous ":catch". Otherwise, these
5142 commands are skipped.
5143 When {pattern} is omitted all errors are caught.
5144 Examples: >
5145 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
5146 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
5147 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
5148 :catch /^Vim(write):/ " catch all errors in :write
5149 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
5150 :catch /my-exception/ " catch user exception
5151 :catch /.*/ " catch everything
5152 :catch " same as /.*/
5153<
5154 Another character can be used instead of / around the
5155 {pattern}, so long as it does not have a special
5156 meaning (e.g., '|' or '"') and doesn't occur inside
5157 {pattern}.
5158 NOTE: It is not reliable to ":catch" the TEXT of
5159 an error message because it may vary in different
5160 locales.
5161
5162 *:fina* *:finally* *E606* *E607*
5163:fina[lly] The following commands until the matching |:endtry|
5164 are executed whenever the part between the matching
5165 |:try| and the ":finally" is left: either by falling
5166 through to the ":finally" or by a |:continue|,
5167 |:break|, |:finish|, or |:return|, or by an error or
5168 interrupt or exception (see |:throw|).
5169
5170 *:th* *:throw* *E608*
5171:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
5172 If the ":throw" is used after a |:try| but before the
5173 first corresponding |:catch|, commands are skipped
5174 until the first ":catch" matching {expr1} is reached.
5175 If there is no such ":catch" or if the ":throw" is
5176 used after a ":catch" but before the |:finally|, the
5177 commands following the ":finally" (if present) up to
5178 the matching |:endtry| are executed. If the ":throw"
5179 is after the ":finally", commands up to the ":endtry"
5180 are skipped. At the ":endtry", this process applies
5181 again for the next dynamically surrounding ":try"
5182 (which may be found in a calling function or sourcing
5183 script), until a matching ":catch" has been found.
5184 If the exception is not caught, the command processing
5185 is terminated.
5186 Example: >
5187 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
5188<
5189
5190 *:ec* *:echo*
5191:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
5192 first {expr1} starts on a new line.
5193 Also see |:comment|.
5194 Use "\n" to start a new line. Use "\r" to move the
5195 cursor to the first column.
5196 Uses the highlighting set by the |:echohl| command.
5197 Cannot be followed by a comment.
5198 Example: >
5199 :echo "the value of 'shell' is" &shell
5200< A later redraw may make the message disappear again.
5201 To avoid that a command from before the ":echo" causes
5202 a redraw afterwards (redraws are often postponed until
5203 you type something), force a redraw with the |:redraw|
5204 command. Example: >
5205 :new | redraw | echo "there is a new window"
5206<
5207 *:echon*
5208:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
5209 |:comment|.
5210 Uses the highlighting set by the |:echohl| command.
5211 Cannot be followed by a comment.
5212 Example: >
5213 :echon "the value of 'shell' is " &shell
5214<
5215 Note the difference between using ":echo", which is a
5216 Vim command, and ":!echo", which is an external shell
5217 command: >
5218 :!echo % --> filename
5219< The arguments of ":!" are expanded, see |:_%|. >
5220 :!echo "%" --> filename or "filename"
5221< Like the previous example. Whether you see the double
5222 quotes or not depends on your 'shell'. >
5223 :echo % --> nothing
5224< The '%' is an illegal character in an expression. >
5225 :echo "%" --> %
5226< This just echoes the '%' character. >
5227 :echo expand("%") --> filename
5228< This calls the expand() function to expand the '%'.
5229
5230 *:echoh* *:echohl*
5231:echoh[l] {name} Use the highlight group {name} for the following
5232 |:echo|, |:echon| and |:echomsg| commands. Also used
5233 for the |input()| prompt. Example: >
5234 :echohl WarningMsg | echo "Don't panic!" | echohl None
5235< Don't forget to set the group back to "None",
5236 otherwise all following echo's will be highlighted.
5237
5238 *:echom* *:echomsg*
5239:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
5240 message in the |message-history|.
5241 Spaces are placed between the arguments as with the
5242 |:echo| command. But unprintable characters are
5243 displayed, not interpreted.
5244 Uses the highlighting set by the |:echohl| command.
5245 Example: >
5246 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
5247<
5248 *:echoe* *:echoerr*
5249:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
5250 message in the |message-history|. When used in a
5251 script or function the line number will be added.
5252 Spaces are placed between the arguments as with the
5253 :echo command. When used inside a try conditional,
5254 the message is raised as an error exception instead
5255 (see |try-echoerr|).
5256 Example: >
5257 :echoerr "This script just failed!"
5258< If you just want a highlighted message use |:echohl|.
5259 And to get a beep: >
5260 :exe "normal \<Esc>"
5261<
5262 *:exe* *:execute*
5263:exe[cute] {expr1} .. Executes the string that results from the evaluation
5264 of {expr1} as an Ex command. Multiple arguments are
5265 concatenated, with a space in between. {expr1} is
5266 used as the processed command, command line editing
5267 keys are not recognized.
5268 Cannot be followed by a comment.
5269 Examples: >
5270 :execute "buffer " nextbuf
5271 :execute "normal " count . "w"
5272<
5273 ":execute" can be used to append a command to commands
5274 that don't accept a '|'. Example: >
5275 :execute '!ls' | echo "theend"
5276
5277< ":execute" is also a nice way to avoid having to type
5278 control characters in a Vim script for a ":normal"
5279 command: >
5280 :execute "normal ixxx\<Esc>"
5281< This has an <Esc> character, see |expr-string|.
5282
5283 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00005284 you cannot start or end a "while", "for" or "if"
5285 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005286 :execute 'while i > 5'
5287 :execute 'echo "test" | break'
5288<
5289 It is allowed to have a "while" or "if" command
5290 completely in the executed string: >
5291 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
5292<
5293
5294 *:comment*
5295 ":execute", ":echo" and ":echon" cannot be followed by
5296 a comment directly, because they see the '"' as the
5297 start of a string. But, you can use '|' followed by a
5298 comment. Example: >
5299 :echo "foo" | "this is a comment
5300
5301==============================================================================
53028. Exception handling *exception-handling*
5303
5304The Vim script language comprises an exception handling feature. This section
5305explains how it can be used in a Vim script.
5306
5307Exceptions may be raised by Vim on an error or on interrupt, see
5308|catch-errors| and |catch-interrupt|. You can also explicitly throw an
5309exception by using the ":throw" command, see |throw-catch|.
5310
5311
5312TRY CONDITIONALS *try-conditionals*
5313
5314Exceptions can be caught or can cause cleanup code to be executed. You can
5315use a try conditional to specify catch clauses (that catch exceptions) and/or
5316a finally clause (to be executed for cleanup).
5317 A try conditional begins with a |:try| command and ends at the matching
5318|:endtry| command. In between, you can use a |:catch| command to start
5319a catch clause, or a |:finally| command to start a finally clause. There may
5320be none or multiple catch clauses, but there is at most one finally clause,
5321which must not be followed by any catch clauses. The lines before the catch
5322clauses and the finally clause is called a try block. >
5323
5324 :try
5325 : ...
5326 : ... TRY BLOCK
5327 : ...
5328 :catch /{pattern}/
5329 : ...
5330 : ... CATCH CLAUSE
5331 : ...
5332 :catch /{pattern}/
5333 : ...
5334 : ... CATCH CLAUSE
5335 : ...
5336 :finally
5337 : ...
5338 : ... FINALLY CLAUSE
5339 : ...
5340 :endtry
5341
5342The try conditional allows to watch code for exceptions and to take the
5343appropriate actions. Exceptions from the try block may be caught. Exceptions
5344from the try block and also the catch clauses may cause cleanup actions.
5345 When no exception is thrown during execution of the try block, the control
5346is transferred to the finally clause, if present. After its execution, the
5347script continues with the line following the ":endtry".
5348 When an exception occurs during execution of the try block, the remaining
5349lines in the try block are skipped. The exception is matched against the
5350patterns specified as arguments to the ":catch" commands. The catch clause
5351after the first matching ":catch" is taken, other catch clauses are not
5352executed. The catch clause ends when the next ":catch", ":finally", or
5353":endtry" command is reached - whatever is first. Then, the finally clause
5354(if present) is executed. When the ":endtry" is reached, the script execution
5355continues in the following line as usual.
5356 When an exception that does not match any of the patterns specified by the
5357":catch" commands is thrown in the try block, the exception is not caught by
5358that try conditional and none of the catch clauses is executed. Only the
5359finally clause, if present, is taken. The exception pends during execution of
5360the finally clause. It is resumed at the ":endtry", so that commands after
5361the ":endtry" are not executed and the exception might be caught elsewhere,
5362see |try-nesting|.
5363 When during execution of a catch clause another exception is thrown, the
5364remaining lines in that catch clause are not executed. The new exception is
5365not matched against the patterns in any of the ":catch" commands of the same
5366try conditional and none of its catch clauses is taken. If there is, however,
5367a finally clause, it is executed, and the exception pends during its
5368execution. The commands following the ":endtry" are not executed. The new
5369exception might, however, be caught elsewhere, see |try-nesting|.
5370 When during execution of the finally clause (if present) an exception is
5371thrown, the remaining lines in the finally clause are skipped. If the finally
5372clause has been taken because of an exception from the try block or one of the
5373catch clauses, the original (pending) exception is discarded. The commands
5374following the ":endtry" are not executed, and the exception from the finally
5375clause is propagated and can be caught elsewhere, see |try-nesting|.
5376
5377The finally clause is also executed, when a ":break" or ":continue" for
5378a ":while" loop enclosing the complete try conditional is executed from the
5379try block or a catch clause. Or when a ":return" or ":finish" is executed
5380from the try block or a catch clause of a try conditional in a function or
5381sourced script, respectively. The ":break", ":continue", ":return", or
5382":finish" pends during execution of the finally clause and is resumed when the
5383":endtry" is reached. It is, however, discarded when an exception is thrown
5384from the finally clause.
5385 When a ":break" or ":continue" for a ":while" loop enclosing the complete
5386try conditional or when a ":return" or ":finish" is encountered in the finally
5387clause, the rest of the finally clause is skipped, and the ":break",
5388":continue", ":return" or ":finish" is executed as usual. If the finally
5389clause has been taken because of an exception or an earlier ":break",
5390":continue", ":return", or ":finish" from the try block or a catch clause,
5391this pending exception or command is discarded.
5392
5393For examples see |throw-catch| and |try-finally|.
5394
5395
5396NESTING OF TRY CONDITIONALS *try-nesting*
5397
5398Try conditionals can be nested arbitrarily. That is, a complete try
5399conditional can be put into the try block, a catch clause, or the finally
5400clause of another try conditional. If the inner try conditional does not
5401catch an exception thrown in its try block or throws a new exception from one
5402of its catch clauses or its finally clause, the outer try conditional is
5403checked according to the rules above. If the inner try conditional is in the
5404try block of the outer try conditional, its catch clauses are checked, but
5405otherwise only the finally clause is executed. It does not matter for
5406nesting, whether the inner try conditional is directly contained in the outer
5407one, or whether the outer one sources a script or calls a function containing
5408the inner try conditional.
5409
5410When none of the active try conditionals catches an exception, just their
5411finally clauses are executed. Thereafter, the script processing terminates.
5412An error message is displayed in case of an uncaught exception explicitly
5413thrown by a ":throw" command. For uncaught error and interrupt exceptions
5414implicitly raised by Vim, the error message(s) or interrupt message are shown
5415as usual.
5416
5417For examples see |throw-catch|.
5418
5419
5420EXAMINING EXCEPTION HANDLING CODE *except-examine*
5421
5422Exception handling code can get tricky. If you are in doubt what happens, set
5423'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
5424script file. Then you see when an exception is thrown, discarded, caught, or
5425finished. When using a verbosity level of at least 14, things pending in
5426a finally clause are also shown. This information is also given in debug mode
5427(see |debug-scripts|).
5428
5429
5430THROWING AND CATCHING EXCEPTIONS *throw-catch*
5431
5432You can throw any number or string as an exception. Use the |:throw| command
5433and pass the value to be thrown as argument: >
5434 :throw 4711
5435 :throw "string"
5436< *throw-expression*
5437You can also specify an expression argument. The expression is then evaluated
5438first, and the result is thrown: >
5439 :throw 4705 + strlen("string")
5440 :throw strpart("strings", 0, 6)
5441
5442An exception might be thrown during evaluation of the argument of the ":throw"
5443command. Unless it is caught there, the expression evaluation is abandoned.
5444The ":throw" command then does not throw a new exception.
5445 Example: >
5446
5447 :function! Foo(arg)
5448 : try
5449 : throw a:arg
5450 : catch /foo/
5451 : endtry
5452 : return 1
5453 :endfunction
5454 :
5455 :function! Bar()
5456 : echo "in Bar"
5457 : return 4710
5458 :endfunction
5459 :
5460 :throw Foo("arrgh") + Bar()
5461
5462This throws "arrgh", and "in Bar" is not displayed since Bar() is not
5463executed. >
5464 :throw Foo("foo") + Bar()
5465however displays "in Bar" and throws 4711.
5466
5467Any other command that takes an expression as argument might also be
5468abandoned by an (uncaught) exception during the expression evaluation. The
5469exception is then propagated to the caller of the command.
5470 Example: >
5471
5472 :if Foo("arrgh")
5473 : echo "then"
5474 :else
5475 : echo "else"
5476 :endif
5477
5478Here neither of "then" or "else" is displayed.
5479
5480 *catch-order*
5481Exceptions can be caught by a try conditional with one or more |:catch|
5482commands, see |try-conditionals|. The values to be caught by each ":catch"
5483command can be specified as a pattern argument. The subsequent catch clause
5484gets executed when a matching exception is caught.
5485 Example: >
5486
5487 :function! Foo(value)
5488 : try
5489 : throw a:value
5490 : catch /^\d\+$/
5491 : echo "Number thrown"
5492 : catch /.*/
5493 : echo "String thrown"
5494 : endtry
5495 :endfunction
5496 :
5497 :call Foo(0x1267)
5498 :call Foo('string')
5499
5500The first call to Foo() displays "Number thrown", the second "String thrown".
5501An exception is matched against the ":catch" commands in the order they are
5502specified. Only the first match counts. So you should place the more
5503specific ":catch" first. The following order does not make sense: >
5504
5505 : catch /.*/
5506 : echo "String thrown"
5507 : catch /^\d\+$/
5508 : echo "Number thrown"
5509
5510The first ":catch" here matches always, so that the second catch clause is
5511never taken.
5512
5513 *throw-variables*
5514If you catch an exception by a general pattern, you may access the exact value
5515in the variable |v:exception|: >
5516
5517 : catch /^\d\+$/
5518 : echo "Number thrown. Value is" v:exception
5519
5520You may also be interested where an exception was thrown. This is stored in
5521|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
5522exception most recently caught as long it is not finished.
5523 Example: >
5524
5525 :function! Caught()
5526 : if v:exception != ""
5527 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
5528 : else
5529 : echo 'Nothing caught'
5530 : endif
5531 :endfunction
5532 :
5533 :function! Foo()
5534 : try
5535 : try
5536 : try
5537 : throw 4711
5538 : finally
5539 : call Caught()
5540 : endtry
5541 : catch /.*/
5542 : call Caught()
5543 : throw "oops"
5544 : endtry
5545 : catch /.*/
5546 : call Caught()
5547 : finally
5548 : call Caught()
5549 : endtry
5550 :endfunction
5551 :
5552 :call Foo()
5553
5554This displays >
5555
5556 Nothing caught
5557 Caught "4711" in function Foo, line 4
5558 Caught "oops" in function Foo, line 10
5559 Nothing caught
5560
5561A practical example: The following command ":LineNumber" displays the line
5562number in the script or function where it has been used: >
5563
5564 :function! LineNumber()
5565 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
5566 :endfunction
5567 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
5568<
5569 *try-nested*
5570An exception that is not caught by a try conditional can be caught by
5571a surrounding try conditional: >
5572
5573 :try
5574 : try
5575 : throw "foo"
5576 : catch /foobar/
5577 : echo "foobar"
5578 : finally
5579 : echo "inner finally"
5580 : endtry
5581 :catch /foo/
5582 : echo "foo"
5583 :endtry
5584
5585The inner try conditional does not catch the exception, just its finally
5586clause is executed. The exception is then caught by the outer try
5587conditional. The example displays "inner finally" and then "foo".
5588
5589 *throw-from-catch*
5590You can catch an exception and throw a new one to be caught elsewhere from the
5591catch clause: >
5592
5593 :function! Foo()
5594 : throw "foo"
5595 :endfunction
5596 :
5597 :function! Bar()
5598 : try
5599 : call Foo()
5600 : catch /foo/
5601 : echo "Caught foo, throw bar"
5602 : throw "bar"
5603 : endtry
5604 :endfunction
5605 :
5606 :try
5607 : call Bar()
5608 :catch /.*/
5609 : echo "Caught" v:exception
5610 :endtry
5611
5612This displays "Caught foo, throw bar" and then "Caught bar".
5613
5614 *rethrow*
5615There is no real rethrow in the Vim script language, but you may throw
5616"v:exception" instead: >
5617
5618 :function! Bar()
5619 : try
5620 : call Foo()
5621 : catch /.*/
5622 : echo "Rethrow" v:exception
5623 : throw v:exception
5624 : endtry
5625 :endfunction
5626< *try-echoerr*
5627Note that this method cannot be used to "rethrow" Vim error or interrupt
5628exceptions, because it is not possible to fake Vim internal exceptions.
5629Trying so causes an error exception. You should throw your own exception
5630denoting the situation. If you want to cause a Vim error exception containing
5631the original error exception value, you can use the |:echoerr| command: >
5632
5633 :try
5634 : try
5635 : asdf
5636 : catch /.*/
5637 : echoerr v:exception
5638 : endtry
5639 :catch /.*/
5640 : echo v:exception
5641 :endtry
5642
5643This code displays
5644
5645 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
5646
5647
5648CLEANUP CODE *try-finally*
5649
5650Scripts often change global settings and restore them at their end. If the
5651user however interrupts the script by pressing CTRL-C, the settings remain in
5652an inconsistent state. The same may happen to you in the development phase of
5653a script when an error occurs or you explicitly throw an exception without
5654catching it. You can solve these problems by using a try conditional with
5655a finally clause for restoring the settings. Its execution is guaranteed on
5656normal control flow, on error, on an explicit ":throw", and on interrupt.
5657(Note that errors and interrupts from inside the try conditional are converted
5658to exceptions. When not caught, they terminate the script after the finally
5659clause has been executed.)
5660Example: >
5661
5662 :try
5663 : let s:saved_ts = &ts
5664 : set ts=17
5665 :
5666 : " Do the hard work here.
5667 :
5668 :finally
5669 : let &ts = s:saved_ts
5670 : unlet s:saved_ts
5671 :endtry
5672
5673This method should be used locally whenever a function or part of a script
5674changes global settings which need to be restored on failure or normal exit of
5675that function or script part.
5676
5677 *break-finally*
5678Cleanup code works also when the try block or a catch clause is left by
5679a ":continue", ":break", ":return", or ":finish".
5680 Example: >
5681
5682 :let first = 1
5683 :while 1
5684 : try
5685 : if first
5686 : echo "first"
5687 : let first = 0
5688 : continue
5689 : else
5690 : throw "second"
5691 : endif
5692 : catch /.*/
5693 : echo v:exception
5694 : break
5695 : finally
5696 : echo "cleanup"
5697 : endtry
5698 : echo "still in while"
5699 :endwhile
5700 :echo "end"
5701
5702This displays "first", "cleanup", "second", "cleanup", and "end". >
5703
5704 :function! Foo()
5705 : try
5706 : return 4711
5707 : finally
5708 : echo "cleanup\n"
5709 : endtry
5710 : echo "Foo still active"
5711 :endfunction
5712 :
5713 :echo Foo() "returned by Foo"
5714
5715This displays "cleanup" and "4711 returned by Foo". You don't need to add an
5716extra ":return" in the finally clause. (Above all, this would override the
5717return value.)
5718
5719 *except-from-finally*
5720Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
5721a finally clause is possible, but not recommended since it abandons the
5722cleanup actions for the try conditional. But, of course, interrupt and error
5723exceptions might get raised from a finally clause.
5724 Example where an error in the finally clause stops an interrupt from
5725working correctly: >
5726
5727 :try
5728 : try
5729 : echo "Press CTRL-C for interrupt"
5730 : while 1
5731 : endwhile
5732 : finally
5733 : unlet novar
5734 : endtry
5735 :catch /novar/
5736 :endtry
5737 :echo "Script still running"
5738 :sleep 1
5739
5740If you need to put commands that could fail into a finally clause, you should
5741think about catching or ignoring the errors in these commands, see
5742|catch-errors| and |ignore-errors|.
5743
5744
5745CATCHING ERRORS *catch-errors*
5746
5747If you want to catch specific errors, you just have to put the code to be
5748watched in a try block and add a catch clause for the error message. The
5749presence of the try conditional causes all errors to be converted to an
5750exception. No message is displayed and |v:errmsg| is not set then. To find
5751the right pattern for the ":catch" command, you have to know how the format of
5752the error exception is.
5753 Error exceptions have the following format: >
5754
5755 Vim({cmdname}):{errmsg}
5756or >
5757 Vim:{errmsg}
5758
5759{cmdname} is the name of the command that failed; the second form is used when
5760the command name is not known. {errmsg} is the error message usually produced
5761when the error occurs outside try conditionals. It always begins with
5762a capital "E", followed by a two or three-digit error number, a colon, and
5763a space.
5764
5765Examples:
5766
5767The command >
5768 :unlet novar
5769normally produces the error message >
5770 E108: No such variable: "novar"
5771which is converted inside try conditionals to an exception >
5772 Vim(unlet):E108: No such variable: "novar"
5773
5774The command >
5775 :dwim
5776normally produces the error message >
5777 E492: Not an editor command: dwim
5778which is converted inside try conditionals to an exception >
5779 Vim:E492: Not an editor command: dwim
5780
5781You can catch all ":unlet" errors by a >
5782 :catch /^Vim(unlet):/
5783or all errors for misspelled command names by a >
5784 :catch /^Vim:E492:/
5785
5786Some error messages may be produced by different commands: >
5787 :function nofunc
5788and >
5789 :delfunction nofunc
5790both produce the error message >
5791 E128: Function name must start with a capital: nofunc
5792which is converted inside try conditionals to an exception >
5793 Vim(function):E128: Function name must start with a capital: nofunc
5794or >
5795 Vim(delfunction):E128: Function name must start with a capital: nofunc
5796respectively. You can catch the error by its number independently on the
5797command that caused it if you use the following pattern: >
5798 :catch /^Vim(\a\+):E128:/
5799
5800Some commands like >
5801 :let x = novar
5802produce multiple error messages, here: >
5803 E121: Undefined variable: novar
5804 E15: Invalid expression: novar
5805Only the first is used for the exception value, since it is the most specific
5806one (see |except-several-errors|). So you can catch it by >
5807 :catch /^Vim(\a\+):E121:/
5808
5809You can catch all errors related to the name "nofunc" by >
5810 :catch /\<nofunc\>/
5811
5812You can catch all Vim errors in the ":write" and ":read" commands by >
5813 :catch /^Vim(\(write\|read\)):E\d\+:/
5814
5815You can catch all Vim errors by the pattern >
5816 :catch /^Vim\((\a\+)\)\=:E\d\+:/
5817<
5818 *catch-text*
5819NOTE: You should never catch the error message text itself: >
5820 :catch /No such variable/
5821only works in the english locale, but not when the user has selected
5822a different language by the |:language| command. It is however helpful to
5823cite the message text in a comment: >
5824 :catch /^Vim(\a\+):E108:/ " No such variable
5825
5826
5827IGNORING ERRORS *ignore-errors*
5828
5829You can ignore errors in a specific Vim command by catching them locally: >
5830
5831 :try
5832 : write
5833 :catch
5834 :endtry
5835
5836But you are strongly recommended NOT to use this simple form, since it could
5837catch more than you want. With the ":write" command, some autocommands could
5838be executed and cause errors not related to writing, for instance: >
5839
5840 :au BufWritePre * unlet novar
5841
5842There could even be such errors you are not responsible for as a script
5843writer: a user of your script might have defined such autocommands. You would
5844then hide the error from the user.
5845 It is much better to use >
5846
5847 :try
5848 : write
5849 :catch /^Vim(write):/
5850 :endtry
5851
5852which only catches real write errors. So catch only what you'd like to ignore
5853intentionally.
5854
5855For a single command that does not cause execution of autocommands, you could
5856even suppress the conversion of errors to exceptions by the ":silent!"
5857command: >
5858 :silent! nunmap k
5859This works also when a try conditional is active.
5860
5861
5862CATCHING INTERRUPTS *catch-interrupt*
5863
5864When there are active try conditionals, an interrupt (CTRL-C) is converted to
5865the exception "Vim:Interrupt". You can catch it like every exception. The
5866script is not terminated, then.
5867 Example: >
5868
5869 :function! TASK1()
5870 : sleep 10
5871 :endfunction
5872
5873 :function! TASK2()
5874 : sleep 20
5875 :endfunction
5876
5877 :while 1
5878 : let command = input("Type a command: ")
5879 : try
5880 : if command == ""
5881 : continue
5882 : elseif command == "END"
5883 : break
5884 : elseif command == "TASK1"
5885 : call TASK1()
5886 : elseif command == "TASK2"
5887 : call TASK2()
5888 : else
5889 : echo "\nIllegal command:" command
5890 : continue
5891 : endif
5892 : catch /^Vim:Interrupt$/
5893 : echo "\nCommand interrupted"
5894 : " Caught the interrupt. Continue with next prompt.
5895 : endtry
5896 :endwhile
5897
5898You can interrupt a task here by pressing CTRL-C; the script then asks for
5899a new command. If you press CTRL-C at the prompt, the script is terminated.
5900
5901For testing what happens when CTRL-C would be pressed on a specific line in
5902your script, use the debug mode and execute the |>quit| or |>interrupt|
5903command on that line. See |debug-scripts|.
5904
5905
5906CATCHING ALL *catch-all*
5907
5908The commands >
5909
5910 :catch /.*/
5911 :catch //
5912 :catch
5913
5914catch everything, error exceptions, interrupt exceptions and exceptions
5915explicitly thrown by the |:throw| command. This is useful at the top level of
5916a script in order to catch unexpected things.
5917 Example: >
5918
5919 :try
5920 :
5921 : " do the hard work here
5922 :
5923 :catch /MyException/
5924 :
5925 : " handle known problem
5926 :
5927 :catch /^Vim:Interrupt$/
5928 : echo "Script interrupted"
5929 :catch /.*/
5930 : echo "Internal error (" . v:exception . ")"
5931 : echo " - occurred at " . v:throwpoint
5932 :endtry
5933 :" end of script
5934
5935Note: Catching all might catch more things than you want. Thus, you are
5936strongly encouraged to catch only for problems that you can really handle by
5937specifying a pattern argument to the ":catch".
5938 Example: Catching all could make it nearly impossible to interrupt a script
5939by pressing CTRL-C: >
5940
5941 :while 1
5942 : try
5943 : sleep 1
5944 : catch
5945 : endtry
5946 :endwhile
5947
5948
5949EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
5950
5951Exceptions may be used during execution of autocommands. Example: >
5952
5953 :autocmd User x try
5954 :autocmd User x throw "Oops!"
5955 :autocmd User x catch
5956 :autocmd User x echo v:exception
5957 :autocmd User x endtry
5958 :autocmd User x throw "Arrgh!"
5959 :autocmd User x echo "Should not be displayed"
5960 :
5961 :try
5962 : doautocmd User x
5963 :catch
5964 : echo v:exception
5965 :endtry
5966
5967This displays "Oops!" and "Arrgh!".
5968
5969 *except-autocmd-Pre*
5970For some commands, autocommands get executed before the main action of the
5971command takes place. If an exception is thrown and not caught in the sequence
5972of autocommands, the sequence and the command that caused its execution are
5973abandoned and the exception is propagated to the caller of the command.
5974 Example: >
5975
5976 :autocmd BufWritePre * throw "FAIL"
5977 :autocmd BufWritePre * echo "Should not be displayed"
5978 :
5979 :try
5980 : write
5981 :catch
5982 : echo "Caught:" v:exception "from" v:throwpoint
5983 :endtry
5984
5985Here, the ":write" command does not write the file currently being edited (as
5986you can see by checking 'modified'), since the exception from the BufWritePre
5987autocommand abandons the ":write". The exception is then caught and the
5988script displays: >
5989
5990 Caught: FAIL from BufWrite Auto commands for "*"
5991<
5992 *except-autocmd-Post*
5993For some commands, autocommands get executed after the main action of the
5994command has taken place. If this main action fails and the command is inside
5995an active try conditional, the autocommands are skipped and an error exception
5996is thrown that can be caught by the caller of the command.
5997 Example: >
5998
5999 :autocmd BufWritePost * echo "File successfully written!"
6000 :
6001 :try
6002 : write /i/m/p/o/s/s/i/b/l/e
6003 :catch
6004 : echo v:exception
6005 :endtry
6006
6007This just displays: >
6008
6009 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
6010
6011If you really need to execute the autocommands even when the main action
6012fails, trigger the event from the catch clause.
6013 Example: >
6014
6015 :autocmd BufWritePre * set noreadonly
6016 :autocmd BufWritePost * set readonly
6017 :
6018 :try
6019 : write /i/m/p/o/s/s/i/b/l/e
6020 :catch
6021 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
6022 :endtry
6023<
6024You can also use ":silent!": >
6025
6026 :let x = "ok"
6027 :let v:errmsg = ""
6028 :autocmd BufWritePost * if v:errmsg != ""
6029 :autocmd BufWritePost * let x = "after fail"
6030 :autocmd BufWritePost * endif
6031 :try
6032 : silent! write /i/m/p/o/s/s/i/b/l/e
6033 :catch
6034 :endtry
6035 :echo x
6036
6037This displays "after fail".
6038
6039If the main action of the command does not fail, exceptions from the
6040autocommands will be catchable by the caller of the command: >
6041
6042 :autocmd BufWritePost * throw ":-("
6043 :autocmd BufWritePost * echo "Should not be displayed"
6044 :
6045 :try
6046 : write
6047 :catch
6048 : echo v:exception
6049 :endtry
6050<
6051 *except-autocmd-Cmd*
6052For some commands, the normal action can be replaced by a sequence of
6053autocommands. Exceptions from that sequence will be catchable by the caller
6054of the command.
6055 Example: For the ":write" command, the caller cannot know whether the file
6056had actually been written when the exception occurred. You need to tell it in
6057some way. >
6058
6059 :if !exists("cnt")
6060 : let cnt = 0
6061 :
6062 : autocmd BufWriteCmd * if &modified
6063 : autocmd BufWriteCmd * let cnt = cnt + 1
6064 : autocmd BufWriteCmd * if cnt % 3 == 2
6065 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6066 : autocmd BufWriteCmd * endif
6067 : autocmd BufWriteCmd * write | set nomodified
6068 : autocmd BufWriteCmd * if cnt % 3 == 0
6069 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6070 : autocmd BufWriteCmd * endif
6071 : autocmd BufWriteCmd * echo "File successfully written!"
6072 : autocmd BufWriteCmd * endif
6073 :endif
6074 :
6075 :try
6076 : write
6077 :catch /^BufWriteCmdError$/
6078 : if &modified
6079 : echo "Error on writing (file contents not changed)"
6080 : else
6081 : echo "Error after writing"
6082 : endif
6083 :catch /^Vim(write):/
6084 : echo "Error on writing"
6085 :endtry
6086
6087When this script is sourced several times after making changes, it displays
6088first >
6089 File successfully written!
6090then >
6091 Error on writing (file contents not changed)
6092then >
6093 Error after writing
6094etc.
6095
6096 *except-autocmd-ill*
6097You cannot spread a try conditional over autocommands for different events.
6098The following code is ill-formed: >
6099
6100 :autocmd BufWritePre * try
6101 :
6102 :autocmd BufWritePost * catch
6103 :autocmd BufWritePost * echo v:exception
6104 :autocmd BufWritePost * endtry
6105 :
6106 :write
6107
6108
6109EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
6110
6111Some programming languages allow to use hierarchies of exception classes or to
6112pass additional information with the object of an exception class. You can do
6113similar things in Vim.
6114 In order to throw an exception from a hierarchy, just throw the complete
6115class name with the components separated by a colon, for instance throw the
6116string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
6117 When you want to pass additional information with your exception class, add
6118it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
6119for an error when writing "myfile".
6120 With the appropriate patterns in the ":catch" command, you can catch for
6121base classes or derived classes of your hierarchy. Additional information in
6122parentheses can be cut out from |v:exception| with the ":substitute" command.
6123 Example: >
6124
6125 :function! CheckRange(a, func)
6126 : if a:a < 0
6127 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
6128 : endif
6129 :endfunction
6130 :
6131 :function! Add(a, b)
6132 : call CheckRange(a:a, "Add")
6133 : call CheckRange(a:b, "Add")
6134 : let c = a:a + a:b
6135 : if c < 0
6136 : throw "EXCEPT:MATHERR:OVERFLOW"
6137 : endif
6138 : return c
6139 :endfunction
6140 :
6141 :function! Div(a, b)
6142 : call CheckRange(a:a, "Div")
6143 : call CheckRange(a:b, "Div")
6144 : if (a:b == 0)
6145 : throw "EXCEPT:MATHERR:ZERODIV"
6146 : endif
6147 : return a:a / a:b
6148 :endfunction
6149 :
6150 :function! Write(file)
6151 : try
6152 : execute "write" a:file
6153 : catch /^Vim(write):/
6154 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
6155 : endtry
6156 :endfunction
6157 :
6158 :try
6159 :
6160 : " something with arithmetics and I/O
6161 :
6162 :catch /^EXCEPT:MATHERR:RANGE/
6163 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
6164 : echo "Range error in" function
6165 :
6166 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
6167 : echo "Math error"
6168 :
6169 :catch /^EXCEPT:IO/
6170 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
6171 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
6172 : if file !~ '^/'
6173 : let file = dir . "/" . file
6174 : endif
6175 : echo 'I/O error for "' . file . '"'
6176 :
6177 :catch /^EXCEPT/
6178 : echo "Unspecified error"
6179 :
6180 :endtry
6181
6182The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
6183a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
6184exceptions with the "Vim" prefix; they are reserved for Vim.
6185 Vim error exceptions are parameterized with the name of the command that
6186failed, if known. See |catch-errors|.
6187
6188
6189PECULIARITIES
6190 *except-compat*
6191The exception handling concept requires that the command sequence causing the
6192exception is aborted immediately and control is transferred to finally clauses
6193and/or a catch clause.
6194
6195In the Vim script language there are cases where scripts and functions
6196continue after an error: in functions without the "abort" flag or in a command
6197after ":silent!", control flow goes to the following line, and outside
6198functions, control flow goes to the line following the outermost ":endwhile"
6199or ":endif". On the other hand, errors should be catchable as exceptions
6200(thus, requiring the immediate abortion).
6201
6202This problem has been solved by converting errors to exceptions and using
6203immediate abortion (if not suppressed by ":silent!") only when a try
6204conditional is active. This is no restriction since an (error) exception can
6205be caught only from an active try conditional. If you want an immediate
6206termination without catching the error, just use a try conditional without
6207catch clause. (You can cause cleanup code being executed before termination
6208by specifying a finally clause.)
6209
6210When no try conditional is active, the usual abortion and continuation
6211behavior is used instead of immediate abortion. This ensures compatibility of
6212scripts written for Vim 6.1 and earlier.
6213
6214However, when sourcing an existing script that does not use exception handling
6215commands (or when calling one of its functions) from inside an active try
6216conditional of a new script, you might change the control flow of the existing
6217script on error. You get the immediate abortion on error and can catch the
6218error in the new script. If however the sourced script suppresses error
6219messages by using the ":silent!" command (checking for errors by testing
6220|v:errmsg| if appropriate), its execution path is not changed. The error is
6221not converted to an exception. (See |:silent|.) So the only remaining cause
6222where this happens is for scripts that don't care about errors and produce
6223error messages. You probably won't want to use such code from your new
6224scripts.
6225
6226 *except-syntax-err*
6227Syntax errors in the exception handling commands are never caught by any of
6228the ":catch" commands of the try conditional they belong to. Its finally
6229clauses, however, is executed.
6230 Example: >
6231
6232 :try
6233 : try
6234 : throw 4711
6235 : catch /\(/
6236 : echo "in catch with syntax error"
6237 : catch
6238 : echo "inner catch-all"
6239 : finally
6240 : echo "inner finally"
6241 : endtry
6242 :catch
6243 : echo 'outer catch-all caught "' . v:exception . '"'
6244 : finally
6245 : echo "outer finally"
6246 :endtry
6247
6248This displays: >
6249 inner finally
6250 outer catch-all caught "Vim(catch):E54: Unmatched \("
6251 outer finally
6252The original exception is discarded and an error exception is raised, instead.
6253
6254 *except-single-line*
6255The ":try", ":catch", ":finally", and ":endtry" commands can be put on
6256a single line, but then syntax errors may make it difficult to recognize the
6257"catch" line, thus you better avoid this.
6258 Example: >
6259 :try | unlet! foo # | catch | endtry
6260raises an error exception for the trailing characters after the ":unlet!"
6261argument, but does not see the ":catch" and ":endtry" commands, so that the
6262error exception is discarded and the "E488: Trailing characters" message gets
6263displayed.
6264
6265 *except-several-errors*
6266When several errors appear in a single command, the first error message is
6267usually the most specific one and therefor converted to the error exception.
6268 Example: >
6269 echo novar
6270causes >
6271 E121: Undefined variable: novar
6272 E15: Invalid expression: novar
6273The value of the error exception inside try conditionals is: >
6274 Vim(echo):E121: Undefined variable: novar
6275< *except-syntax-error*
6276But when a syntax error is detected after a normal error in the same command,
6277the syntax error is used for the exception being thrown.
6278 Example: >
6279 unlet novar #
6280causes >
6281 E108: No such variable: "novar"
6282 E488: Trailing characters
6283The value of the error exception inside try conditionals is: >
6284 Vim(unlet):E488: Trailing characters
6285This is done because the syntax error might change the execution path in a way
6286not intended by the user. Example: >
6287 try
6288 try | unlet novar # | catch | echo v:exception | endtry
6289 catch /.*/
6290 echo "outer catch:" v:exception
6291 endtry
6292This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
6293a "E600: Missing :endtry" error message is given, see |except-single-line|.
6294
6295==============================================================================
62969. Examples *eval-examples*
6297
6298Printing in Hex ~
6299>
6300 :" The function Nr2Hex() returns the Hex string of a number.
6301 :func Nr2Hex(nr)
6302 : let n = a:nr
6303 : let r = ""
6304 : while n
6305 : let r = '0123456789ABCDEF'[n % 16] . r
6306 : let n = n / 16
6307 : endwhile
6308 : return r
6309 :endfunc
6310
6311 :" The function String2Hex() converts each character in a string to a two
6312 :" character Hex string.
6313 :func String2Hex(str)
6314 : let out = ''
6315 : let ix = 0
6316 : while ix < strlen(a:str)
6317 : let out = out . Nr2Hex(char2nr(a:str[ix]))
6318 : let ix = ix + 1
6319 : endwhile
6320 : return out
6321 :endfunc
6322
6323Example of its use: >
6324 :echo Nr2Hex(32)
6325result: "20" >
6326 :echo String2Hex("32")
6327result: "3332"
6328
6329
6330Sorting lines (by Robert Webb) ~
6331
6332Here is a Vim script to sort lines. Highlight the lines in Vim and type
6333":Sort". This doesn't call any external programs so it'll work on any
6334platform. The function Sort() actually takes the name of a comparison
6335function as its argument, like qsort() does in C. So you could supply it
6336with different comparison functions in order to sort according to date etc.
6337>
6338 :" Function for use with Sort(), to compare two strings.
6339 :func! Strcmp(str1, str2)
6340 : if (a:str1 < a:str2)
6341 : return -1
6342 : elseif (a:str1 > a:str2)
6343 : return 1
6344 : else
6345 : return 0
6346 : endif
6347 :endfunction
6348
6349 :" Sort lines. SortR() is called recursively.
6350 :func! SortR(start, end, cmp)
6351 : if (a:start >= a:end)
6352 : return
6353 : endif
6354 : let partition = a:start - 1
6355 : let middle = partition
6356 : let partStr = getline((a:start + a:end) / 2)
6357 : let i = a:start
6358 : while (i <= a:end)
6359 : let str = getline(i)
6360 : exec "let result = " . a:cmp . "(str, partStr)"
6361 : if (result <= 0)
6362 : " Need to put it before the partition. Swap lines i and partition.
6363 : let partition = partition + 1
6364 : if (result == 0)
6365 : let middle = partition
6366 : endif
6367 : if (i != partition)
6368 : let str2 = getline(partition)
6369 : call setline(i, str2)
6370 : call setline(partition, str)
6371 : endif
6372 : endif
6373 : let i = i + 1
6374 : endwhile
6375
6376 : " Now we have a pointer to the "middle" element, as far as partitioning
6377 : " goes, which could be anywhere before the partition. Make sure it is at
6378 : " the end of the partition.
6379 : if (middle != partition)
6380 : let str = getline(middle)
6381 : let str2 = getline(partition)
6382 : call setline(middle, str2)
6383 : call setline(partition, str)
6384 : endif
6385 : call SortR(a:start, partition - 1, a:cmp)
6386 : call SortR(partition + 1, a:end, a:cmp)
6387 :endfunc
6388
6389 :" To Sort a range of lines, pass the range to Sort() along with the name of a
6390 :" function that will compare two lines.
6391 :func! Sort(cmp) range
6392 : call SortR(a:firstline, a:lastline, a:cmp)
6393 :endfunc
6394
6395 :" :Sort takes a range of lines and sorts them.
6396 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
6397<
6398 *sscanf*
6399There is no sscanf() function in Vim. If you need to extract parts from a
6400line, you can use matchstr() and substitute() to do it. This example shows
6401how to get the file name, line number and column number out of a line like
6402"foobar.txt, 123, 45". >
6403 :" Set up the match bit
6404 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
6405 :"get the part matching the whole expression
6406 :let l = matchstr(line, mx)
6407 :"get each item out of the match
6408 :let file = substitute(l, mx, '\1', '')
6409 :let lnum = substitute(l, mx, '\2', '')
6410 :let col = substitute(l, mx, '\3', '')
6411
6412The input is in the variable "line", the results in the variables "file",
6413"lnum" and "col". (idea from Michael Geddes)
6414
6415==============================================================================
641610. No +eval feature *no-eval-feature*
6417
6418When the |+eval| feature was disabled at compile time, none of the expression
6419evaluation commands are available. To prevent this from causing Vim scripts
6420to generate all kinds of errors, the ":if" and ":endif" commands are still
6421recognized, though the argument of the ":if" and everything between the ":if"
6422and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
6423only if the commands are at the start of the line. The ":else" command is not
6424recognized.
6425
6426Example of how to avoid executing commands when the |+eval| feature is
6427missing: >
6428
6429 :if 1
6430 : echo "Expression evaluation is compiled in"
6431 :else
6432 : echo "You will _never_ see this message"
6433 :endif
6434
6435==============================================================================
643611. The sandbox *eval-sandbox* *sandbox* *E48*
6437
6438The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
6439options are evaluated in a sandbox. This means that you are protected from
6440these expressions having nasty side effects. This gives some safety for when
6441these options are set from a modeline. It is also used when the command from
6442a tags file is executed.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006443The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006444
6445These items are not allowed in the sandbox:
6446 - changing the buffer text
6447 - defining or changing mapping, autocommands, functions, user commands
6448 - setting certain options (see |option-summary|)
6449 - executing a shell command
6450 - reading or writing a file
6451 - jumping to another buffer or editing a file
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00006452This is not guaranteed 100% secure, but it should block most attacks.
6453
6454 *:san* *:sandbox*
6455:sandbox {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
6456 option that may have been set from a modeline, e.g.
6457 'foldexpr'.
6458
Bram Moolenaar071d4272004-06-13 20:20:40 +00006459
6460 vim:tw=78:ts=8:ft=help:norl: