blob: 81463b4e6286737126c7d82e09e51fbe4628e645 [file] [log] [blame]
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001*eval.txt* For Vim version 7.0c. Last change: 2006 Mar 29
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 Moolenaarb71eaae2006-01-20 23:10:18 +00003112. Textlock |textlock|
Bram Moolenaar071d4272004-06-13 20:20:40 +000032
33{Vi does not have any of these commands}
34
35==============================================================================
361. Variables *variables*
37
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000039 *E712*
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000040There are five types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000041
Bram Moolenaard8b02732005-01-14 21:48:43 +000042Number A 32 bit signed number.
43 Examples: -123 0x10 0177
44
45String A NUL terminated string of 8-bit unsigned characters (bytes).
46 Examples: "ab\txx\"--" 'x-z''a,c'
47
48Funcref A reference to a function |Funcref|.
49 Example: function("strlen")
50
51List An ordered sequence of items |List|.
52 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000053
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000054Dictionary An associative, unordered array: Each entry has a key and a
55 value. |Dictionary|
56 Example: {'blue': "#0000ff", 'red': "#ff0000"}
57
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000058The Number and String types are converted automatically, depending on how they
59are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
61Conversion from a Number to a String is by making the ASCII representation of
62the Number. Examples: >
63 Number 123 --> String "123"
64 Number 0 --> String "0"
65 Number -1 --> String "-1"
66
67Conversion from a String to a Number is done by converting the first digits
68to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
69the String doesn't start with digits, the result is zero. Examples: >
70 String "456" --> Number 456
71 String "6bar" --> Number 6
72 String "foo" --> Number 0
73 String "0xf1" --> Number 241
74 String "0100" --> Number 64
75 String "-8" --> Number -8
76 String "+8" --> Number 0
77
78To force conversion from String to Number, add zero to it: >
79 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000080< 64 ~
81
82To avoid a leading zero to cause octal conversion, or for using a different
83base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000084
85For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
86
87Note that in the command >
88 :if "foo"
89"foo" is converted to 0, which means FALSE. To test for a non-empty string,
90use strlen(): >
91 :if strlen("foo")
Bram Moolenaar748bf032005-02-02 23:04:36 +000092< *E745* *E728* *E703* *E729* *E730* *E731*
93List, Dictionary and Funcref types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000094
Bram Moolenaar13065c42005-01-08 16:08:21 +000095 *E706*
96You will get an error if you try to change the type of a variable. You need
97to |:unlet| it first to avoid this error. String and Number are considered
Bram Moolenaard8b02732005-01-14 21:48:43 +000098equivalent though. Consider this sequence of commands: >
Bram Moolenaar13065c42005-01-08 16:08:21 +000099 :let l = "string"
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000100 :let l = 44 " changes type from String to Number
Bram Moolenaar13065c42005-01-08 16:08:21 +0000101 :let l = [1, 2, 3] " error!
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000102
Bram Moolenaar13065c42005-01-08 16:08:21 +0000103
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001041.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000105 *Funcref* *E695* *E718*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000106A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000107in an expression in the place of a function name, before the parenthesis
108around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000109
110 :let Fn = function("MyFunc")
111 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000112< *E704* *E705* *E707*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000113A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot
114have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000115
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000116A special case is defining a function and directly assigning its Funcref to a
117Dictionary entry. Example: >
118 :function dict.init() dict
119 : let self.val = 0
120 :endfunction
121
122The key of the Dictionary can start with a lower case letter. The actual
123function name is not used here. Also see |numbered-function|.
124
125A Funcref can also be used with the |:call| command: >
126 :call Fn()
127 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000128
129The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000130 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000131
132You can use |call()| to invoke a Funcref and use a list variable for the
133arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000134 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000135
136
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001371.3 Lists ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000138 *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000139A List is an ordered sequence of items. An item can be of any type. Items
140can be accessed by their index number. Items can be added and removed at any
141position in the sequence.
142
Bram Moolenaar13065c42005-01-08 16:08:21 +0000143
144List creation ~
145 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000146A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000147Examples: >
148 :let mylist = [1, two, 3, "four"]
149 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000150
151An item can be any expression. Using a List for an item creates a
Bram Moolenaar13065c42005-01-08 16:08:21 +0000152nested List: >
153 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000154
155An extra comma after the last item is ignored.
156
Bram Moolenaar13065c42005-01-08 16:08:21 +0000157
158List index ~
159 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000160An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000161after the List. Indexes are zero-based, thus the first item has index zero. >
162 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000163 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000164
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000165When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000166 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000167<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000168A negative index is counted from the end. Index -1 refers to the last item in
169the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000170 :let last = mylist[-1] " get the last item: "four"
171
Bram Moolenaar13065c42005-01-08 16:08:21 +0000172To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000173is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174 :echo get(mylist, idx)
175 :echo get(mylist, idx, "NONE")
176
177
178List concatenation ~
179
180Two lists can be concatenated with the "+" operator: >
181 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000182 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000183
184To prepend or append an item turn the item into a list by putting [] around
185it. To change a list in-place see |list-modification| below.
186
187
188Sublist ~
189
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000190A part of the List can be obtained by specifying the first and last index,
191separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000192 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000193
194Omitting the first index is similar to zero. Omitting the last index is
195similar to -1. The difference is that there is no error if the items are not
196available. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000197 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
198 :let shortlist = mylist[2:2] " List with one item: [3]
199 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000200
Bram Moolenaard8b02732005-01-14 21:48:43 +0000201The second index can be just before the first index. In that case the result
202is an empty list. If the second index is lower, this results in an error. >
203 :echo mylist[2:1] " result: []
204 :echo mylist[2:0] " error!
205
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000206NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
207using a single letter variable before the ":". Insert a space when needed:
208mylist[s : e].
209
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000210
Bram Moolenaar13065c42005-01-08 16:08:21 +0000211List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000212 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000213When variable "aa" is a list and you assign it to another variable "bb", both
214variables refer to the same list. Thus changing the list "aa" will also
215change "bb": >
216 :let aa = [1, 2, 3]
217 :let bb = aa
218 :call add(aa, 4)
219 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000220< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000221
222Making a copy of a list is done with the |copy()| function. Using [:] also
223works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000224a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000225 :let aa = [[1, 'a'], 2, 3]
226 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000227 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228 :let aa[0][1] = 'aaa'
229 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000230< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000232< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000233
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000234To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000235copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000236
237The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000238List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000239the same value. >
240 :let alist = [1, 2, 3]
241 :let blist = [1, 2, 3]
242 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000243< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000244 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000245< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000246
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000247Note about comparing lists: Two lists are considered equal if they have the
248same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000249exception: When comparing a number with a string they are considered
250different. There is no automatic type conversion, as with using "==" on
251variables. Example: >
252 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000253< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000254 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000255< 0
256
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000257Thus comparing Lists is more strict than comparing numbers and strings. You
258can compare simple values this way too by putting them in a string: >
259
260 :let a = 5
261 :let b = "5"
262 echo a == b
263< 1 >
264 echo [a] == [b]
265< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000266
Bram Moolenaar13065c42005-01-08 16:08:21 +0000267
268List unpack ~
269
270To unpack the items in a list to individual variables, put the variables in
271square brackets, like list items: >
272 :let [var1, var2] = mylist
273
274When the number of variables does not match the number of items in the list
275this produces an error. To handle any extra items from the list append ";"
276and a variable name: >
277 :let [var1, var2; rest] = mylist
278
279This works like: >
280 :let var1 = mylist[0]
281 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000282 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000283
284Except that there is no error if there are only two items. "rest" will be an
285empty list then.
286
287
288List modification ~
289 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000290To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000291 :let list[4] = "four"
292 :let listlist[0][3] = item
293
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000294To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000295modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000296 :let list[3:5] = [3, 4, 5]
297
Bram Moolenaar13065c42005-01-08 16:08:21 +0000298Adding and removing items from a list is done with functions. Here are a few
299examples: >
300 :call insert(list, 'a') " prepend item 'a'
301 :call insert(list, 'a', 3) " insert item 'a' before list[3]
302 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000303 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000304 :call extend(list, [1, 2]) " extend the list with two more items
305 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000306 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000307 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000308 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000309 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000310
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000311Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000312 :call sort(list) " sort a list alphabetically
313 :call reverse(list) " reverse the order of items
314
Bram Moolenaar13065c42005-01-08 16:08:21 +0000315
316For loop ~
317
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000318The |:for| loop executes commands for each item in a list. A variable is set
319to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000320 :for item in mylist
321 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000322 :endfor
323
324This works like: >
325 :let index = 0
326 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000327 : let item = mylist[index]
328 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000329 : let index = index + 1
330 :endwhile
331
332Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000333results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000334the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000335
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000336If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000337function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000338
Bram Moolenaar13065c42005-01-08 16:08:21 +0000339Just like the |:let| command, |:for| also accepts a list of variables. This
340requires the argument to be a list of lists. >
341 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
342 : call Doit(lnum, col)
343 :endfor
344
345This works like a |:let| command is done for each list item. Again, the types
346must remain the same to avoid an error.
347
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000348It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000349 :for [i, j; rest] in listlist
350 : call Doit(i, j)
351 : if !empty(rest)
352 : echo "remainder: " . string(rest)
353 : endif
354 :endfor
355
356
357List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000358 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000359Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000360 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000361 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000362 :let l = len(list) " number of items in list
363 :let big = max(list) " maximum value in list
364 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000365 :let xs = count(list, 'x') " count nr of times 'x' appears in list
366 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000367 :let lines = getline(1, 10) " get ten text lines from buffer
368 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000369 :let list = split("a b c") " create list from items in a string
370 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000371 :let s = string(list) " String representation of list
372 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000373
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000374Don't forget that a combination of features can make things simple. For
375example, to add up all the numbers in a list: >
376 :exe 'let sum = ' . join(nrlist, '+')
377
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378
Bram Moolenaard8b02732005-01-14 21:48:43 +00003791.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000380 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000381A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000382entry can be located with the key. The entries are stored without a specific
383ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000384
385
386Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000387 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000388A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000389braces. Each entry has a key and a value, separated by a colon. Each key can
390only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000391 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
392 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000393< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000394A key is always a String. You can use a Number, it will be converted to a
395String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000396entry. Note that the String '04' and the Number 04 are different, since the
397Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000398
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000400nested Dictionary: >
401 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
402
403An extra comma after the last entry is ignored.
404
405
406Accessing entries ~
407
408The normal way to access an entry is by putting the key in square brackets: >
409 :let val = mydict["one"]
410 :let mydict["four"] = 4
411
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000412You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000413
414For keys that consist entirely of letters, digits and underscore the following
415form can be used |expr-entry|: >
416 :let val = mydict.one
417 :let mydict.four = 4
418
419Since an entry can be any type, also a List and a Dictionary, the indexing and
420key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000421 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000422
423
424Dictionary to List conversion ~
425
426You may want to loop over the entries in a dictionary. For this you need to
427turn the Dictionary into a List and pass it to |:for|.
428
429Most often you want to loop over the keys, using the |keys()| function: >
430 :for key in keys(mydict)
431 : echo key . ': ' . mydict[key]
432 :endfor
433
434The List of keys is unsorted. You may want to sort them first: >
435 :for key in sort(keys(mydict))
436
437To loop over the values use the |values()| function: >
438 :for v in values(mydict)
439 : echo "value: " . v
440 :endfor
441
442If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000443a List in which each item is a List with two items, the key and the value: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000444 :for entry in items(mydict)
445 : echo entry[0] . ': ' . entry[1]
446 :endfor
447
448
449Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000450 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000451Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
452Dictionary. Otherwise, assignment results in referring to the same
453Dictionary: >
454 :let onedict = {'a': 1, 'b': 2}
455 :let adict = onedict
456 :let adict['a'] = 11
457 :echo onedict['a']
458 11
459
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000460Two Dictionaries compare equal if all the key-value pairs compare equal. For
461more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000462
463
464Dictionary modification ~
465 *dict-modification*
466To change an already existing entry of a Dictionary, or to add a new entry,
467use |:let| this way: >
468 :let dict[4] = "four"
469 :let dict['one'] = item
470
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000471Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
472Three ways to remove the entry with key "aaa" from dict: >
473 :let i = remove(dict, 'aaa')
474 :unlet dict.aaa
475 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000476
477Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000478 :call extend(adict, bdict)
479This extends adict with all entries from bdict. Duplicate keys cause entries
480in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000481Note that the order of entries in a Dictionary is irrelevant, thus don't
482expect ":echo adict" to show the items from bdict after the older entries in
483adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000484
485Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaare2cc9702005-03-15 22:43:58 +0000486 :call filter(dict 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000487This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000488
489
490Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000491 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000492When a function is defined with the "dict" attribute it can be used in a
493special way with a dictionary. Example: >
494 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000495 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000496 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000497 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
498 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000499
500This is like a method in object oriented programming. The entry in the
501Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
502the function was invoked from.
503
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000504It is also possible to add a function without the "dict" attribute as a
505Funcref to a Dictionary, but the "self" variable is not available then.
506
507 *numbered-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000508To avoid the extra name for the function it can be defined and directly
509assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000510 :let mydict = {'data': [0, 1, 2, 3]}
511 :function mydict.len() dict
512 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000513 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000514 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000515
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000516The function will then get a number and the value of dict.len is a |Funcref|
517that references this function. The function can only be used through a
518|Funcref|. It will automatically be deleted when there is no |Funcref|
519remaining that refers to it.
520
521It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000522
523
524Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000525 *E715*
526Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000527 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
528 :if empty(dict) " TRUE if dict is empty
529 :let l = len(dict) " number of items in dict
530 :let big = max(dict) " maximum value in dict
531 :let small = min(dict) " minimum value in dict
532 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
533 :let s = string(dict) " String representation of dict
534 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000535
536
5371.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000538 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000539If you need to know the type of a variable or expression, use the |type()|
540function.
541
542When the '!' flag is included in the 'viminfo' option, global variables that
543start with an uppercase letter, and don't contain a lowercase letter, are
544stored in the viminfo file |viminfo-file|.
545
546When the 'sessionoptions' option contains "global", global variables that
547start with an uppercase letter and contain at least one lowercase letter are
548stored in the session file |session-file|.
549
550variable name can be stored where ~
551my_var_6 not
552My_Var_6 session file
553MY_VAR_6 viminfo file
554
555
556It's possible to form a variable name with curly braces, see
557|curly-braces-names|.
558
559==============================================================================
5602. Expression syntax *expression-syntax*
561
562Expression syntax summary, from least to most significant:
563
564|expr1| expr2 ? expr1 : expr1 if-then-else
565
566|expr2| expr3 || expr3 .. logical OR
567
568|expr3| expr4 && expr4 .. logical AND
569
570|expr4| expr5 == expr5 equal
571 expr5 != expr5 not equal
572 expr5 > expr5 greater than
573 expr5 >= expr5 greater than or equal
574 expr5 < expr5 smaller than
575 expr5 <= expr5 smaller than or equal
576 expr5 =~ expr5 regexp matches
577 expr5 !~ expr5 regexp doesn't match
578
579 expr5 ==? expr5 equal, ignoring case
580 expr5 ==# expr5 equal, match case
581 etc. As above, append ? for ignoring case, # for
582 matching case
583
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000584 expr5 is expr5 same |List| instance
585 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000586
587|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000588 expr6 - expr6 .. number subtraction
589 expr6 . expr6 .. string concatenation
590
591|expr6| expr7 * expr7 .. number multiplication
592 expr7 / expr7 .. number division
593 expr7 % expr7 .. number modulo
594
595|expr7| ! expr7 logical NOT
596 - expr7 unary minus
597 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000598
Bram Moolenaar071d4272004-06-13 20:20:40 +0000599
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000600|expr8| expr8[expr1] byte of a String or item of a |List|
601 expr8[expr1 : expr1] substring of a String or sublist of a |List|
602 expr8.name entry in a |Dictionary|
603 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000604
605|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000606 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000607 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000608 [expr1, ...] |List|
609 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000610 &option option value
611 (expr1) nested expression
612 variable internal variable
613 va{ria}ble internal variable with curly braces
614 $VAR environment variable
615 @r contents of register 'r'
616 function(expr1, ...) function call
617 func{ti}on(expr1, ...) function call with curly braces
618
619
620".." indicates that the operations in this level can be concatenated.
621Example: >
622 &nu || &list && &shell == "csh"
623
624All expressions within one level are parsed from left to right.
625
626
627expr1 *expr1* *E109*
628-----
629
630expr2 ? expr1 : expr1
631
632The expression before the '?' is evaluated to a number. If it evaluates to
633non-zero, the result is the value of the expression between the '?' and ':',
634otherwise the result is the value of the expression after the ':'.
635Example: >
636 :echo lnum == 1 ? "top" : lnum
637
638Since the first expression is an "expr2", it cannot contain another ?:. The
639other two expressions can, thus allow for recursive use of ?:.
640Example: >
641 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
642
643To keep this readable, using |line-continuation| is suggested: >
644 :echo lnum == 1
645 :\ ? "top"
646 :\ : lnum == 1000
647 :\ ? "last"
648 :\ : lnum
649
650
651expr2 and expr3 *expr2* *expr3*
652---------------
653
654 *expr-barbar* *expr-&&*
655The "||" and "&&" operators take one argument on each side. The arguments
656are (converted to) Numbers. The result is:
657
658 input output ~
659n1 n2 n1 || n2 n1 && n2 ~
660zero zero zero zero
661zero non-zero non-zero zero
662non-zero zero non-zero zero
663non-zero non-zero non-zero non-zero
664
665The operators can be concatenated, for example: >
666
667 &nu || &list && &shell == "csh"
668
669Note that "&&" takes precedence over "||", so this has the meaning of: >
670
671 &nu || (&list && &shell == "csh")
672
673Once the result is known, the expression "short-circuits", that is, further
674arguments are not evaluated. This is like what happens in C. For example: >
675
676 let a = 1
677 echo a || b
678
679This is valid even if there is no variable called "b" because "a" is non-zero,
680so the result must be non-zero. Similarly below: >
681
682 echo exists("b") && b == "yes"
683
684This is valid whether "b" has been defined or not. The second clause will
685only be evaluated if "b" has been defined.
686
687
688expr4 *expr4*
689-----
690
691expr5 {cmp} expr5
692
693Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
694if it evaluates to true.
695
696 *expr-==* *expr-!=* *expr->* *expr->=*
697 *expr-<* *expr-<=* *expr-=~* *expr-!~*
698 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
699 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
700 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
701 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000702 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000703 use 'ignorecase' match case ignore case ~
704equal == ==# ==?
705not equal != !=# !=?
706greater than > ># >?
707greater than or equal >= >=# >=?
708smaller than < <# <?
709smaller than or equal <= <=# <=?
710regexp matches =~ =~# =~?
711regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000712same instance is
713different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000714
715Examples:
716"abc" ==# "Abc" evaluates to 0
717"abc" ==? "Abc" evaluates to 1
718"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
719
Bram Moolenaar13065c42005-01-08 16:08:21 +0000720 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000721A |List| can only be compared with a |List| and only "equal", "not equal" and
722"is" can be used. This compares the values of the list, recursively.
723Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000724
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000725 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000726A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
727equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000728recursively. Ignoring case means case is ignored when comparing item values.
729
Bram Moolenaar13065c42005-01-08 16:08:21 +0000730 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000731A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
732equal" can be used. Case is never ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000733
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000734When using "is" or "isnot" with a |List| this checks if the expressions are
735referring to the same |List| instance. A copy of a |List| is different from
736the original |List|. When using "is" without a |List| it is equivalent to
737using "equal", using "isnot" equivalent to using "not equal". Except that a
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000738different type means the values are different. "4 == '4'" is true, "4 is '4'"
739is false.
740
Bram Moolenaar071d4272004-06-13 20:20:40 +0000741When comparing a String with a Number, the String is converted to a Number,
742and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
743because 'x' converted to a Number is zero.
744
745When comparing two Strings, this is done with strcmp() or stricmp(). This
746results in the mathematical difference (comparing byte values), not
747necessarily the alphabetical difference in the local language.
748
749When using the operators with a trailing '#", or the short version and
750'ignorecase' is off, the comparing is done with strcmp().
751
752When using the operators with a trailing '?', or the short version and
753'ignorecase' is set, the comparing is done with stricmp().
754
755The "=~" and "!~" operators match the lefthand argument with the righthand
756argument, which is used as a pattern. See |pattern| for what a pattern is.
757This matching is always done like 'magic' was set and 'cpoptions' is empty, no
758matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
759portable. To avoid backslashes in the regexp pattern to be doubled, use a
760single-quote string, see |literal-string|.
761Since a string is considered to be a single line, a multi-line pattern
762(containing \n, backslash-n) will not match. However, a literal NL character
763can be matched like an ordinary character. Examples:
764 "foo\nbar" =~ "\n" evaluates to 1
765 "foo\nbar" =~ "\\n" evaluates to 0
766
767
768expr5 and expr6 *expr5* *expr6*
769---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000770expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000771expr6 - expr6 .. Number subtraction *expr--*
772expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000774For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000775result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000776
777expr7 * expr7 .. number multiplication *expr-star*
778expr7 / expr7 .. number division *expr-/*
779expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000780
781For all, except ".", Strings are converted to Numbers.
782
783Note the difference between "+" and ".":
784 "123" + "456" = 579
785 "123" . "456" = "123456"
786
787When the righthand side of '/' is zero, the result is 0x7fffffff.
788When the righthand side of '%' is zero, the result is 0.
789
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000790None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000791
Bram Moolenaar071d4272004-06-13 20:20:40 +0000792
793expr7 *expr7*
794-----
795! expr7 logical NOT *expr-!*
796- expr7 unary minus *expr-unary--*
797+ expr7 unary plus *expr-unary-+*
798
799For '!' non-zero becomes zero, zero becomes one.
800For '-' the sign of the number is changed.
801For '+' the number is unchanged.
802
803A String will be converted to a Number first.
804
805These three can be repeated and mixed. Examples:
806 !-1 == 0
807 !!8 == 1
808 --9 == 9
809
810
811expr8 *expr8*
812-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000813expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000814
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000815If expr8 is a Number or String this results in a String that contains the
816expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000817Number. Note that this doesn't recognize multi-byte encodings.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000819Index zero gives the first character. This is like it works in C. Careful:
820text column numbers start with one! Example, to get the character under the
821cursor: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822 :let c = getline(line("."))[col(".") - 1]
823
824If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000825String. A negative index always results in an empty string (reason: backwards
826compatibility). Use [-1:] to get the last byte.
827
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000828If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000829for possible index values. If the index is out of range this results in an
830error. Example: >
831 :let item = mylist[-1] " get last item
832
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000833Generally, if a |List| index is equal to or higher than the length of the
834|List|, or more negative than the length of the |List|, this results in an
835error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000836
Bram Moolenaard8b02732005-01-14 21:48:43 +0000837
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000838expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000839
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000840If expr8 is a Number or String this results in the substring with the bytes
841from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000842expr1b are used as a Number. Note that this doesn't recognize multi-byte
843encodings.
844
845If expr1a is omitted zero is used. If expr1b is omitted the length of the
846string minus one is used.
847
848A negative number can be used to measure from the end of the string. -1 is
849the last character, -2 the last but one, etc.
850
851If an index goes out of range for the string characters are omitted. If
852expr1b is smaller than expr1a the result is an empty string.
853
854Examples: >
855 :let c = name[-1:] " last byte of a string
856 :let c = name[-2:-2] " last but one byte of a string
857 :let s = line(".")[4:] " from the fifth byte to the end
858 :let s = s[:-3] " remove last two bytes
859
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000860If expr8 is a |List| this results in a new |List| with the items indicated by
861the indexes expr1a and expr1b. This works like with a String, as explained
862just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000863 :let l = mylist[:3] " first four items
864 :let l = mylist[4:4] " List with one item
865 :let l = mylist[:] " shallow copy of a List
866
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000867Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
868error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000869
Bram Moolenaard8b02732005-01-14 21:48:43 +0000870
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000871expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000872
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000873If expr8 is a |Dictionary| and it is followed by a dot, then the following
874name will be used as a key in the |Dictionary|. This is just like:
875expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000876
877The name must consist of alphanumeric characters, just like a variable name,
878but it may start with a number. Curly braces cannot be used.
879
880There must not be white space before or after the dot.
881
882Examples: >
883 :let dict = {"one": 1, 2: "two"}
884 :echo dict.one
885 :echo dict .2
886
887Note that the dot is also used for String concatenation. To avoid confusion
888always put spaces around the dot for String concatenation.
889
890
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000891expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000892
893When expr8 is a |Funcref| type variable, invoke the function it refers to.
894
895
896
897 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000898number
899------
900number number constant *expr-number*
901
902Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
903
904
905string *expr-string* *E114*
906------
907"string" string constant *expr-quote*
908
909Note that double quotes are used.
910
911A string constant accepts these special characters:
912\... three-digit octal number (e.g., "\316")
913\.. two-digit octal number (must be followed by non-digit)
914\. one-digit octal number (must be followed by non-digit)
915\x.. byte specified with two hex numbers (e.g., "\x1f")
916\x. byte specified with one hex number (must be followed by non-hex char)
917\X.. same as \x..
918\X. same as \x.
919\u.... character specified with up to 4 hex numbers, stored according to the
920 current value of 'encoding' (e.g., "\u02a4")
921\U.... same as \u....
922\b backspace <BS>
923\e escape <Esc>
924\f formfeed <FF>
925\n newline <NL>
926\r return <CR>
927\t tab <Tab>
928\\ backslash
929\" double quote
930\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
931
932Note that "\000" and "\x00" force the end of the string.
933
934
935literal-string *literal-string* *E115*
936---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000937'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000938
939Note that single quotes are used.
940
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000941This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000942meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000943
944Single quoted strings are useful for patterns, so that backslashes do not need
945to be doubled. These two commands are equivalent: >
946 if a =~ "\\s*"
947 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000948
949
950option *expr-option* *E112* *E113*
951------
952&option option value, local value if possible
953&g:option global option value
954&l:option local option value
955
956Examples: >
957 echo "tabstop is " . &tabstop
958 if &insertmode
959
960Any option name can be used here. See |options|. When using the local value
961and there is no buffer-local or window-local value, the global value is used
962anyway.
963
964
965register *expr-register*
966--------
967@r contents of register 'r'
968
969The result is the contents of the named register, as a single string.
970Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaare7566042005-06-17 22:00:15 +0000971register use @" or @@. See |registers| for an explanation of the available
972registers.
973
974When using the '=' register you get the expression itself, not what it
975evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000976
977
978nesting *expr-nesting* *E110*
979-------
980(expr1) nested expression
981
982
983environment variable *expr-env*
984--------------------
985$VAR environment variable
986
987The String value of any environment variable. When it is not defined, the
988result is an empty string.
989 *expr-env-expand*
990Note that there is a difference between using $VAR directly and using
991expand("$VAR"). Using it directly will only expand environment variables that
992are known inside the current Vim session. Using expand() will first try using
993the environment variables known inside the current Vim session. If that
994fails, a shell will be used to expand the variable. This can be slow, but it
995does expand all variables that the shell knows about. Example: >
996 :echo $version
997 :echo expand("$version")
998The first one probably doesn't echo anything, the second echoes the $version
999variable (if your shell supports it).
1000
1001
1002internal variable *expr-variable*
1003-----------------
1004variable internal variable
1005See below |internal-variables|.
1006
1007
Bram Moolenaar05159a02005-02-26 23:04:13 +00001008function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001009-------------
1010function(expr1, ...) function call
1011See below |functions|.
1012
1013
1014==============================================================================
10153. Internal variable *internal-variables* *E121*
1016 *E461*
1017An internal variable name can be made up of letters, digits and '_'. But it
1018cannot start with a digit. It's also possible to use curly braces, see
1019|curly-braces-names|.
1020
1021An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001022An internal variable is explicitly destroyed with the ":unlet" command
1023|:unlet|.
1024Using a name that is not an internal variable or refers to a variable that has
1025been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001026
1027There are several name spaces for variables. Which one is to be used is
1028specified by what is prepended:
1029
1030 (nothing) In a function: local to a function; otherwise: global
1031|buffer-variable| b: Local to the current buffer.
1032|window-variable| w: Local to the current window.
1033|global-variable| g: Global.
1034|local-variable| l: Local to a function.
1035|script-variable| s: Local to a |:source|'ed Vim script.
1036|function-argument| a: Function argument (only inside a function).
1037|vim-variable| v: Global, predefined by Vim.
1038
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001039The scope name by itself can be used as a |Dictionary|. For example, to
1040delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001041 :for k in keys(s:)
1042 : unlet s:[k]
1043 :endfor
1044<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001045 *buffer-variable* *b:var*
1046A variable name that is preceded with "b:" is local to the current buffer.
1047Thus you can have several "b:foo" variables, one for each buffer.
1048This kind of variable is deleted when the buffer is wiped out or deleted with
1049|:bdelete|.
1050
1051One local buffer variable is predefined:
1052 *b:changedtick-variable* *changetick*
1053b:changedtick The total number of changes to the current buffer. It is
1054 incremented for each change. An undo command is also a change
1055 in this case. This can be used to perform an action only when
1056 the buffer has changed. Example: >
1057 :if my_changedtick != b:changedtick
1058 : let my_changedtick = b:changedtick
1059 : call My_Update()
1060 :endif
1061<
1062 *window-variable* *w:var*
1063A variable name that is preceded with "w:" is local to the current window. It
1064is deleted when the window is closed.
1065
1066 *global-variable* *g:var*
1067Inside functions global variables are accessed with "g:". Omitting this will
1068access a variable local to a function. But "g:" can also be used in any other
1069place if you like.
1070
1071 *local-variable* *l:var*
1072Inside functions local variables are accessed without prepending anything.
1073But you can also prepend "l:" if you like.
1074
1075 *script-variable* *s:var*
1076In a Vim script variables starting with "s:" can be used. They cannot be
1077accessed from outside of the scripts, thus are local to the script.
1078
1079They can be used in:
1080- commands executed while the script is sourced
1081- functions defined in the script
1082- autocommands defined in the script
1083- functions and autocommands defined in functions and autocommands which were
1084 defined in the script (recursively)
1085- user defined commands defined in the script
1086Thus not in:
1087- other scripts sourced from this one
1088- mappings
1089- etc.
1090
1091script variables can be used to avoid conflicts with global variable names.
1092Take this example:
1093
1094 let s:counter = 0
1095 function MyCounter()
1096 let s:counter = s:counter + 1
1097 echo s:counter
1098 endfunction
1099 command Tick call MyCounter()
1100
1101You can now invoke "Tick" from any script, and the "s:counter" variable in
1102that script will not be changed, only the "s:counter" in the script where
1103"Tick" was defined is used.
1104
1105Another example that does the same: >
1106
1107 let s:counter = 0
1108 command Tick let s:counter = s:counter + 1 | echo s:counter
1109
1110When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001111script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001112defined.
1113
1114The script variables are also available when a function is defined inside a
1115function that is defined in a script. Example: >
1116
1117 let s:counter = 0
1118 function StartCounting(incr)
1119 if a:incr
1120 function MyCounter()
1121 let s:counter = s:counter + 1
1122 endfunction
1123 else
1124 function MyCounter()
1125 let s:counter = s:counter - 1
1126 endfunction
1127 endif
1128 endfunction
1129
1130This defines the MyCounter() function either for counting up or counting down
1131when calling StartCounting(). It doesn't matter from where StartCounting() is
1132called, the s:counter variable will be accessible in MyCounter().
1133
1134When the same script is sourced again it will use the same script variables.
1135They will remain valid as long as Vim is running. This can be used to
1136maintain a counter: >
1137
1138 if !exists("s:counter")
1139 let s:counter = 1
1140 echo "script executed for the first time"
1141 else
1142 let s:counter = s:counter + 1
1143 echo "script executed " . s:counter . " times now"
1144 endif
1145
1146Note that this means that filetype plugins don't get a different set of script
1147variables for each buffer. Use local buffer variables instead |b:var|.
1148
1149
1150Predefined Vim variables: *vim-variable* *v:var*
1151
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001152 *v:beval_col* *beval_col-variable*
1153v:beval_col The number of the column, over which the mouse pointer is.
1154 This is the byte index in the |v:beval_lnum| line.
1155 Only valid while evaluating the 'balloonexpr' option.
1156
1157 *v:beval_bufnr* *beval_bufnr-variable*
1158v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1159 valid while evaluating the 'balloonexpr' option.
1160
1161 *v:beval_lnum* *beval_lnum-variable*
1162v:beval_lnum The number of the line, over which the mouse pointer is. Only
1163 valid while evaluating the 'balloonexpr' option.
1164
1165 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001166v:beval_text The text under or after the mouse pointer. Usually a word as
1167 it is useful for debugging a C program. 'iskeyword' applies,
1168 but a dot and "->" before the position is included. When on a
1169 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001170 word before it. When on a Visual area within one line the
1171 highlighted text is used.
1172 Only valid while evaluating the 'balloonexpr' option.
1173
1174 *v:beval_winnr* *beval_winnr-variable*
1175v:beval_winnr The number of the window, over which the mouse pointer is. Only
1176 valid while evaluating the 'balloonexpr' option.
1177
Bram Moolenaar071d4272004-06-13 20:20:40 +00001178 *v:charconvert_from* *charconvert_from-variable*
1179v:charconvert_from
1180 The name of the character encoding of a file to be converted.
1181 Only valid while evaluating the 'charconvert' option.
1182
1183 *v:charconvert_to* *charconvert_to-variable*
1184v:charconvert_to
1185 The name of the character encoding of a file after conversion.
1186 Only valid while evaluating the 'charconvert' option.
1187
1188 *v:cmdarg* *cmdarg-variable*
1189v:cmdarg This variable is used for two purposes:
1190 1. The extra arguments given to a file read/write command.
1191 Currently these are "++enc=" and "++ff=". This variable is
1192 set before an autocommand event for a file read/write
1193 command is triggered. There is a leading space to make it
1194 possible to append this variable directly after the
1195 read/write command. Note: The "+cmd" argument isn't
1196 included here, because it will be executed anyway.
1197 2. When printing a PostScript file with ":hardcopy" this is
1198 the argument for the ":hardcopy" command. This can be used
1199 in 'printexpr'.
1200
1201 *v:cmdbang* *cmdbang-variable*
1202v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1203 was used the value is 1, otherwise it is 0. Note that this
1204 can only be used in autocommands. For user commands |<bang>|
1205 can be used.
1206
1207 *v:count* *count-variable*
1208v:count The count given for the last Normal mode command. Can be used
1209 to get the count before a mapping. Read-only. Example: >
1210 :map _x :<C-U>echo "the count is " . v:count<CR>
1211< Note: The <C-U> is required to remove the line range that you
1212 get when typing ':' after a count.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001213 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001214 "count" also works, for backwards compatibility.
1215
1216 *v:count1* *count1-variable*
1217v:count1 Just like "v:count", but defaults to one when no count is
1218 used.
1219
1220 *v:ctype* *ctype-variable*
1221v:ctype The current locale setting for characters of the runtime
1222 environment. This allows Vim scripts to be aware of the
1223 current locale encoding. Technical: it's the value of
1224 LC_CTYPE. When not using a locale the value is "C".
1225 This variable can not be set directly, use the |:language|
1226 command.
1227 See |multi-lang|.
1228
1229 *v:dying* *dying-variable*
1230v:dying Normally zero. When a deadly signal is caught it's set to
1231 one. When multiple signals are caught the number increases.
1232 Can be used in an autocommand to check if Vim didn't
1233 terminate normally. {only works on Unix}
1234 Example: >
1235 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1236<
1237 *v:errmsg* *errmsg-variable*
1238v:errmsg Last given error message. It's allowed to set this variable.
1239 Example: >
1240 :let v:errmsg = ""
1241 :silent! next
1242 :if v:errmsg != ""
1243 : ... handle error
1244< "errmsg" also works, for backwards compatibility.
1245
1246 *v:exception* *exception-variable*
1247v:exception The value of the exception most recently caught and not
1248 finished. See also |v:throwpoint| and |throw-variables|.
1249 Example: >
1250 :try
1251 : throw "oops"
1252 :catch /.*/
1253 : echo "caught" v:exception
1254 :endtry
1255< Output: "caught oops".
1256
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001257 *v:fcs_reason* *fcs_reason-variable*
1258v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1259 Can be used in an autocommand to decide what to do and/or what
1260 to set v:fcs_choice to. Possible values:
1261 deleted file no longer exists
1262 conflict file contents, mode or timestamp was
1263 changed and buffer is modified
1264 changed file contents has changed
1265 mode mode of file changed
1266 time only file timestamp changed
1267
1268 *v:fcs_choice* *fcs_choice-variable*
1269v:fcs_choice What should happen after a |FileChangedShell| event was
1270 triggered. Can be used in an autocommand to tell Vim what to
1271 do with the affected buffer:
1272 reload Reload the buffer (does not work if
1273 the file was deleted).
1274 ask Ask the user what to do, as if there
1275 was no autocommand. Except that when
1276 only the timestamp changed nothing
1277 will happen.
1278 <empty> Nothing, the autocommand should do
1279 everything that needs to be done.
1280 The default is empty. If another (invalid) value is used then
1281 Vim behaves like it is empty, there is no warning message.
1282
Bram Moolenaar071d4272004-06-13 20:20:40 +00001283 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001284v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001285 option used for ~
1286 'charconvert' file to be converted
1287 'diffexpr' original file
1288 'patchexpr' original file
1289 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001290 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001291
1292 *v:fname_out* *fname_out-variable*
1293v:fname_out The name of the output file. Only valid while
1294 evaluating:
1295 option used for ~
1296 'charconvert' resulting converted file (*)
1297 'diffexpr' output of diff
1298 'patchexpr' resulting patched file
1299 (*) When doing conversion for a write command (e.g., ":w
1300 file") it will be equal to v:fname_in. When doing conversion
1301 for a read command (e.g., ":e file") it will be a temporary
1302 file and different from v:fname_in.
1303
1304 *v:fname_new* *fname_new-variable*
1305v:fname_new The name of the new version of the file. Only valid while
1306 evaluating 'diffexpr'.
1307
1308 *v:fname_diff* *fname_diff-variable*
1309v:fname_diff The name of the diff (patch) file. Only valid while
1310 evaluating 'patchexpr'.
1311
1312 *v:folddashes* *folddashes-variable*
1313v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1314 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001315 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001316
1317 *v:foldlevel* *foldlevel-variable*
1318v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001319 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001320
1321 *v:foldend* *foldend-variable*
1322v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001323 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001324
1325 *v:foldstart* *foldstart-variable*
1326v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001327 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001328
Bram Moolenaar843ee412004-06-30 16:16:41 +00001329 *v:insertmode* *insertmode-variable*
1330v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1331 events. Values:
1332 i Insert mode
1333 r Replace mode
1334 v Virtual Replace mode
1335
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001336 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001337v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001338 evaluating the expression used with |map()| and |filter()|.
1339 Read-only.
1340
Bram Moolenaar071d4272004-06-13 20:20:40 +00001341 *v:lang* *lang-variable*
1342v:lang The current locale setting for messages of the runtime
1343 environment. This allows Vim scripts to be aware of the
1344 current language. Technical: it's the value of LC_MESSAGES.
1345 The value is system dependent.
1346 This variable can not be set directly, use the |:language|
1347 command.
1348 It can be different from |v:ctype| when messages are desired
1349 in a different language than what is used for character
1350 encoding. See |multi-lang|.
1351
1352 *v:lc_time* *lc_time-variable*
1353v:lc_time The current locale setting for time messages of the runtime
1354 environment. This allows Vim scripts to be aware of the
1355 current language. Technical: it's the value of LC_TIME.
1356 This variable can not be set directly, use the |:language|
1357 command. See |multi-lang|.
1358
1359 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001360v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00001361 expressions, tab page number for 'guitablabel'. Only valid
1362 while one of these expressions is being evaluated. Read-only
1363 when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001364
1365 *v:prevcount* *prevcount-variable*
1366v:prevcount The count given for the last but one Normal mode command.
1367 This is the v:count value of the previous command. Useful if
1368 you want to cancel Visual mode and then use the count. >
1369 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1370< Read-only.
1371
Bram Moolenaar05159a02005-02-26 23:04:13 +00001372 *v:profiling* *profiling-variable*
1373v:profiling Normally zero. Set to one after using ":profile start".
1374 See |profiling|.
1375
Bram Moolenaar071d4272004-06-13 20:20:40 +00001376 *v:progname* *progname-variable*
1377v:progname Contains the name (with path removed) with which Vim was
1378 invoked. Allows you to do special initialisations for "view",
1379 "evim" etc., or any other name you might symlink to Vim.
1380 Read-only.
1381
1382 *v:register* *register-variable*
1383v:register The name of the register supplied to the last normal mode
1384 command. Empty if none were supplied. |getreg()| |setreg()|
1385
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001386 *v:scrollstart* *scrollstart-variable*
1387v:scrollstart String describing the script or function that caused the
1388 screen to scroll up. It's only set when it is empty, thus the
1389 first reason is remembered. It is set to "Unknown" for a
1390 typed command.
1391 This can be used to find out why your script causes the
1392 hit-enter prompt.
1393
Bram Moolenaar071d4272004-06-13 20:20:40 +00001394 *v:servername* *servername-variable*
1395v:servername The resulting registered |x11-clientserver| name if any.
1396 Read-only.
1397
1398 *v:shell_error* *shell_error-variable*
1399v:shell_error Result of the last shell command. When non-zero, the last
1400 shell command had an error. When zero, there was no problem.
1401 This only works when the shell returns the error code to Vim.
1402 The value -1 is often used when the command could not be
1403 executed. Read-only.
1404 Example: >
1405 :!mv foo bar
1406 :if v:shell_error
1407 : echo 'could not rename "foo" to "bar"!'
1408 :endif
1409< "shell_error" also works, for backwards compatibility.
1410
1411 *v:statusmsg* *statusmsg-variable*
1412v:statusmsg Last given status message. It's allowed to set this variable.
1413
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001414 *v:swapname* *swapname-variable*
1415v:swapname Only valid when executing |SwapExists| autocommands: Name of
1416 the swap file found. Read-only.
1417
1418 *v:swapchoice* *swapchoice-variable*
1419v:swapchoice |SwapExists| autocommands can set this to the selected choice
1420 for handling an existing swap file:
1421 'o' Open read-only
1422 'e' Edit anyway
1423 'r' Recover
1424 'd' Delete swapfile
1425 'q' Quit
1426 'a' Abort
1427 The value should be a single-character string. An empty value
1428 results in the user being asked, as would happen when there is
1429 no SwapExists autocommand. The default is empty.
1430
Bram Moolenaarb3480382005-12-11 21:33:32 +00001431 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001432v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001433 opened. Can be used for a |SwapExists| autocommand to have
1434 another Vim open the file and jump to the right place. For
1435 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001436 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001437
Bram Moolenaar071d4272004-06-13 20:20:40 +00001438 *v:termresponse* *termresponse-variable*
1439v:termresponse The escape sequence returned by the terminal for the |t_RV|
1440 termcap entry. It is set when Vim receives an escape sequence
1441 that starts with ESC [ or CSI and ends in a 'c', with only
1442 digits, ';' and '.' in between.
1443 When this option is set, the TermResponse autocommand event is
1444 fired, so that you can react to the response from the
1445 terminal.
1446 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1447 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1448 patch level (since this was introduced in patch 95, it's
1449 always 95 or bigger). Pc is always zero.
1450 {only when compiled with |+termresponse| feature}
1451
1452 *v:this_session* *this_session-variable*
1453v:this_session Full filename of the last loaded or saved session file. See
1454 |:mksession|. It is allowed to set this variable. When no
1455 session file has been saved, this variable is empty.
1456 "this_session" also works, for backwards compatibility.
1457
1458 *v:throwpoint* *throwpoint-variable*
1459v:throwpoint The point where the exception most recently caught and not
1460 finished was thrown. Not set when commands are typed. See
1461 also |v:exception| and |throw-variables|.
1462 Example: >
1463 :try
1464 : throw "oops"
1465 :catch /.*/
1466 : echo "Exception from" v:throwpoint
1467 :endtry
1468< Output: "Exception from test.vim, line 2"
1469
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001470 *v:val* *val-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001471v:val Value of the current item of a |List| or |Dictionary|. Only
1472 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001473 |filter()|. Read-only.
1474
Bram Moolenaar071d4272004-06-13 20:20:40 +00001475 *v:version* *version-variable*
1476v:version Version number of Vim: Major version number times 100 plus
1477 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1478 is 501. Read-only. "version" also works, for backwards
1479 compatibility.
1480 Use |has()| to check if a certain patch was included, e.g.: >
1481 if has("patch123")
1482< Note that patch numbers are specific to the version, thus both
1483 version 5.0 and 5.1 may have a patch 123, but these are
1484 completely different.
1485
1486 *v:warningmsg* *warningmsg-variable*
1487v:warningmsg Last given warning message. It's allowed to set this variable.
1488
1489==============================================================================
14904. Builtin Functions *functions*
1491
1492See |function-list| for a list grouped by what the function is used for.
1493
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001494(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001495
1496USAGE RESULT DESCRIPTION ~
1497
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001498add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001499append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001500append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001502argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001503argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001504argv( ) List the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001505browse( {save}, {title}, {initdir}, {default})
1506 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001507browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001508bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001509buflisted( {expr}) Number TRUE if buffer {expr} is listed
1510bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511bufname( {expr}) String Name of the buffer {expr}
1512bufnr( {expr}) Number Number of the buffer {expr}
1513bufwinnr( {expr}) Number window number of buffer {expr}
1514byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001515byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001516call( {func}, {arglist} [, {dict}])
1517 any call {func} with arguments {arglist}
Bram Moolenaarca003e12006-03-17 23:19:38 +00001518changenr() Number current change number
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001520cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001521col( {expr}) Number column nr of cursor or mark
Bram Moolenaara94bc432006-03-10 21:42:59 +00001522complete({startcol}, {matches}) String set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001523complete_add( {expr}) Number add completion match
1524complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525confirm( {msg} [, {choices} [, {default} [, {type}]]])
1526 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001527copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001528count( {list}, {expr} [, {start} [, {ic}]])
1529 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001530cscope_connection( [{num} , {dbpath} [, {prepend}]])
1531 Number checks existence of cscope connection
Bram Moolenaar0b238792006-03-02 22:49:12 +00001532cursor( {lnum}, {col} [, {coladd}])
1533 Number move cursor to {lnum}, {col}, {coladd}
1534cursor( {list}) Number move cursor to position in {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001535deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001536delete( {fname}) Number delete file {fname}
1537did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001538diff_filler( {lnum}) Number diff filler lines about {lnum}
1539diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001540empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001541escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001542eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001543eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001544executable( {expr}) Number 1 if executable {expr} exists
1545exists( {expr}) Number TRUE if {expr} exists
1546expand( {expr}) String expand special keywords in {expr}
1547filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001548filter( {expr}, {string}) List/Dict remove items from {expr} where
1549 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001550finddir( {name}[, {path}[, {count}]])
1551 String Find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001552findfile( {name}[, {path}[, {count}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001553 String Find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001554filewritable( {file}) Number TRUE if {file} is a writable file
1555fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001556foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1557foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001559foldtext( ) String line displayed for closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001561function( {name}) Funcref reference to function {name}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001562get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001563get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001564getbufline( {expr}, {lnum} [, {end}])
1565 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001566getchar( [expr]) Number get one character from the user
1567getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001568getbufvar( {expr}, {varname}) variable {varname} in buffer {expr}
1569getcmdline() String return the current command-line
1570getcmdpos() Number return cursor position in command-line
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001571getcmdtype() String return the current command-line type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001572getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001573getfperm( {fname}) String file permissions of file {fname}
1574getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001575getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001576getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001577getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001578getline( {lnum}) String line {lnum} of current buffer
1579getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001580getloclist({nr}) List list of location list items
Bram Moolenaar0b238792006-03-02 22:49:12 +00001581getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001582getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001583getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001584getregtype( [{regname}]) String type of register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001585getwinposx() Number X coord in pixels of GUI Vim window
1586getwinposy() Number Y coord in pixels of GUI Vim window
1587getwinvar( {nr}, {varname}) variable {varname} in window {nr}
1588glob( {expr}) String expand file wildcards in {expr}
1589globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1590has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001591has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001592hasmapto( {what} [, {mode} [, {abbr}]])
1593 Number TRUE if mapping to {what} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00001594histadd( {history},{item}) String add an item to a history
1595histdel( {history} [, {item}]) String remove an item from a history
1596histget( {history} [, {index}]) String get the item {index} from a history
1597histnr( {history}) Number highest index of a history
1598hlexists( {name}) Number TRUE if highlight group {name} exists
1599hlID( {name}) Number syntax ID of highlight group {name}
1600hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001601iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1602indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001603index( {list}, {expr} [, {start} [, {ic}]])
1604 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001605input( {prompt} [, {text} [, {completion}]])
1606 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001607inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001608inputrestore() Number restore typeahead
1609inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001610inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001611insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001612isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001613islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001614items( {dict}) List key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001615join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001616keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001617len( {expr}) Number the length of {expr}
1618libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001619libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1620line( {expr}) Number line nr of cursor, last line or mark
1621line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001622lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001624map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001625maparg( {name}[, {mode} [, {abbr}]])
1626 String rhs of mapping {name} in mode {mode}
1627mapcheck( {name}[, {mode} [, {abbr}]])
1628 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001629match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001630 Number position where {pat} matches in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001631matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001632 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001633matchlist( {expr}, {pat}[, {start}[, {count}]])
1634 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001635matchstr( {expr}, {pat}[, {start}[, {count}]])
1636 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001637max({list}) Number maximum value of items in {list}
1638min({list}) Number minumum value of items in {list}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001639mkdir({name} [, {path} [, {prot}]])
1640 Number create directory {name}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001641mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001642nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1643nr2char( {expr}) String single char with ASCII value {expr}
1644prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001645printf( {fmt}, {expr1}...) String format text
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001646pumvisible() Number whether popup menu is visible
Bram Moolenaard8b02732005-01-14 21:48:43 +00001647range( {expr} [, {max} [, {stride}]])
1648 List items from {expr} to {max}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001649readfile({fname} [, {binary} [, {max}]])
1650 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001651reltime( [{start} [, {end}]]) List get time value
1652reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653remote_expr( {server}, {string} [, {idvar}])
1654 String send expression
1655remote_foreground( {server}) Number bring Vim server to the foreground
1656remote_peek( {serverid} [, {retvar}])
1657 Number check for reply string
1658remote_read( {serverid}) String read reply string
1659remote_send( {server}, {string} [, {idvar}])
1660 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001661remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001662remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001663rename( {from}, {to}) Number rename (move) file from {from} to {to}
1664repeat( {expr}, {count}) String repeat {expr} {count} times
1665resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001666reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001667search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001668searchdecl({name} [, {global} [, {thisblock}]])
1669 Number search for variable declaration
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001670searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001671 Number search for other end of start/end pair
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001672searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001673 List search for other end of start/end pair
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001674searchpos( {pattern} [, {flags} [, {stopline}]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001675 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001676server2client( {clientid}, {string})
1677 Number send reply string
1678serverlist() String get a list of available servers
1679setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1680setcmdpos( {pos}) Number set cursor position in command-line
1681setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001682setloclist( {nr}, {list}[, {action}])
1683 Number modify location list using {list}
1684setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001685setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001686setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001687simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001688sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001689soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001690spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00001691spellsuggest( {word} [, {max} [, {capital}]])
1692 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001693split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001694 List make |List| from {pat} separated {expr}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001695str2nr( {expr} [, {base}]) Number convert string to number
Bram Moolenaar071d4272004-06-13 20:20:40 +00001696strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001697stridx( {haystack}, {needle}[, {start}])
1698 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001699string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001700strlen( {expr}) Number length of the String {expr}
1701strpart( {src}, {start}[, {len}])
1702 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001703strridx( {haystack}, {needle} [, {start}])
1704 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001705strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001706submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001707substitute( {expr}, {pat}, {sub}, {flags})
1708 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001709synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001710synIDattr( {synID}, {what} [, {mode}])
1711 String attribute {what} of syntax ID {synID}
1712synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001713system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001714tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1715tabpagenr( [{arg}]) Number number of current or last tab page
1716tabpagewinnr( {tabarg}[, {arg}])
1717 Number number of current window in tab page
1718taglist( {expr}) List list of tags matching {expr}
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00001719tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001720tempname() String name for a temporary file
1721tolower( {expr}) String the String {expr} switched to lowercase
1722toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001723tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1724 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001725type( {name}) Number type of variable {name}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001726values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727virtcol( {expr}) Number screen column of cursor or mark
1728visualmode( [expr]) String last visual mode used
1729winbufnr( {nr}) Number buffer number of window {nr}
1730wincol() Number window column of the cursor
1731winheight( {nr}) Number height of window {nr}
1732winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00001733winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001734winrestcmd() String returns command to restore window sizes
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00001735winrestview({dict}) None restore view of current window
1736winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00001737winwidth( {nr}) Number width of window {nr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001738writefile({list}, {fname} [, {binary}])
1739 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001740
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001741add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001742 Append the item {expr} to |List| {list}. Returns the
1743 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001744 :let alist = add([1, 2, 3], item)
1745 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001746< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001747 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001748 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001749
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001750
1751append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001752 When {expr} is a |List|: Append each item of the |List| as a
1753 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00001754 Otherwise append {expr} as one text line below line {lnum} in
1755 the current buffer.
1756 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001757 Returns 1 for failure ({lnum} out of range or out of memory),
1758 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001759 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001760 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001761<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001762 *argc()*
1763argc() The result is the number of files in the argument list of the
1764 current window. See |arglist|.
1765
1766 *argidx()*
1767argidx() The result is the current index in the argument list. 0 is
1768 the first file. argc() - 1 is the last one. See |arglist|.
1769
1770 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001771argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001772 current window. See |arglist|. "argv(0)" is the first one.
1773 Example: >
1774 :let i = 0
1775 :while i < argc()
1776 : let f = escape(argv(i), '. ')
1777 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1778 : let i = i + 1
1779 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001780< Without the {nr} argument a |List| with the whole |arglist| is
1781 returned.
1782
Bram Moolenaar071d4272004-06-13 20:20:40 +00001783 *browse()*
1784browse({save}, {title}, {initdir}, {default})
1785 Put up a file requester. This only works when "has("browse")"
1786 returns non-zero (only in some GUI versions).
1787 The input fields are:
1788 {save} when non-zero, select file to write
1789 {title} title for the requester
1790 {initdir} directory to start browsing in
1791 {default} default file name
1792 When the "Cancel" button is hit, something went wrong, or
1793 browsing is not possible, an empty string is returned.
1794
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001795 *browsedir()*
1796browsedir({title}, {initdir})
1797 Put up a directory requester. This only works when
1798 "has("browse")" returns non-zero (only in some GUI versions).
1799 On systems where a directory browser is not supported a file
1800 browser is used. In that case: select a file in the directory
1801 to be used.
1802 The input fields are:
1803 {title} title for the requester
1804 {initdir} directory to start browsing in
1805 When the "Cancel" button is hit, something went wrong, or
1806 browsing is not possible, an empty string is returned.
1807
Bram Moolenaar071d4272004-06-13 20:20:40 +00001808bufexists({expr}) *bufexists()*
1809 The result is a Number, which is non-zero if a buffer called
1810 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001811 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001812 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001813 exactly. The name can be:
1814 - Relative to the current directory.
1815 - A full path.
1816 - The name of a buffer with 'filetype' set to "nofile".
1817 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001818 Unlisted buffers will be found.
1819 Note that help files are listed by their short name in the
1820 output of |:buffers|, but bufexists() requires using their
1821 long name to be able to find them.
1822 Use "bufexists(0)" to test for the existence of an alternate
1823 file name.
1824 *buffer_exists()*
1825 Obsolete name: buffer_exists().
1826
1827buflisted({expr}) *buflisted()*
1828 The result is a Number, which is non-zero if a buffer called
1829 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001830 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001831
1832bufloaded({expr}) *bufloaded()*
1833 The result is a Number, which is non-zero if a buffer called
1834 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001835 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001836
1837bufname({expr}) *bufname()*
1838 The result is the name of a buffer, as it is displayed by the
1839 ":ls" command.
1840 If {expr} is a Number, that buffer number's name is given.
1841 Number zero is the alternate buffer for the current window.
1842 If {expr} is a String, it is used as a |file-pattern| to match
1843 with the buffer names. This is always done like 'magic' is
1844 set and 'cpoptions' is empty. When there is more than one
1845 match an empty string is returned.
1846 "" or "%" can be used for the current buffer, "#" for the
1847 alternate buffer.
1848 A full match is preferred, otherwise a match at the start, end
1849 or middle of the buffer name is accepted.
1850 Listed buffers are found first. If there is a single match
1851 with a listed buffer, that one is returned. Next unlisted
1852 buffers are searched for.
1853 If the {expr} is a String, but you want to use it as a buffer
1854 number, force it to be a Number by adding zero to it: >
1855 :echo bufname("3" + 0)
1856< If the buffer doesn't exist, or doesn't have a name, an empty
1857 string is returned. >
1858 bufname("#") alternate buffer name
1859 bufname(3) name of buffer 3
1860 bufname("%") name of current buffer
1861 bufname("file2") name of buffer where "file2" matches.
1862< *buffer_name()*
1863 Obsolete name: buffer_name().
1864
1865 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001866bufnr({expr} [, {create}])
1867 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00001868 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001869 above.
1870 If the buffer doesn't exist, -1 is returned. Or, if the
1871 {create} argument is present and not zero, a new, unlisted,
1872 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001873 bufnr("$") is the last buffer: >
1874 :let last_buffer = bufnr("$")
1875< The result is a Number, which is the highest buffer number
1876 of existing buffers. Note that not all buffers with a smaller
1877 number necessarily exist, because ":bwipeout" may have removed
1878 them. Use bufexists() to test for the existence of a buffer.
1879 *buffer_number()*
1880 Obsolete name: buffer_number().
1881 *last_buffer_nr()*
1882 Obsolete name for bufnr("$"): last_buffer_nr().
1883
1884bufwinnr({expr}) *bufwinnr()*
1885 The result is a Number, which is the number of the first
1886 window associated with buffer {expr}. For the use of {expr},
1887 see |bufname()| above. If buffer {expr} doesn't exist or
1888 there is no such window, -1 is returned. Example: >
1889
1890 echo "A window containing buffer 1 is " . (bufwinnr(1))
1891
1892< The number can be used with |CTRL-W_w| and ":wincmd w"
1893 |:wincmd|.
1894
1895
1896byte2line({byte}) *byte2line()*
1897 Return the line number that contains the character at byte
1898 count {byte} in the current buffer. This includes the
1899 end-of-line character, depending on the 'fileformat' option
1900 for the current buffer. The first character has byte count
1901 one.
1902 Also see |line2byte()|, |go| and |:goto|.
1903 {not available when compiled without the |+byte_offset|
1904 feature}
1905
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001906byteidx({expr}, {nr}) *byteidx()*
1907 Return byte index of the {nr}'th character in the string
1908 {expr}. Use zero for the first character, it returns zero.
1909 This function is only useful when there are multibyte
1910 characters, otherwise the returned value is equal to {nr}.
1911 Composing characters are counted as a separate character.
1912 Example : >
1913 echo matchstr(str, ".", byteidx(str, 3))
1914< will display the fourth character. Another way to do the
1915 same: >
1916 let s = strpart(str, byteidx(str, 3))
1917 echo strpart(s, 0, byteidx(s, 1))
1918< If there are less than {nr} characters -1 is returned.
1919 If there are exactly {nr} characters the length of the string
1920 is returned.
1921
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001922call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001923 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001924 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001925 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001926 a:firstline and a:lastline are set to the cursor line.
1927 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001928 {dict} is for functions with the "dict" attribute. It will be
1929 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001930
Bram Moolenaarca003e12006-03-17 23:19:38 +00001931changenr() *changenr()*
1932 Return the number of the most recent change. This is the same
1933 number as what is displayed with |:undolist| and can be used
1934 with the |:undo| command.
1935 When a change was made it is the number of that change. After
1936 redo it is the number of the redone change. After undo it is
1937 one less than the number of the undone change.
1938
Bram Moolenaar071d4272004-06-13 20:20:40 +00001939char2nr({expr}) *char2nr()*
1940 Return number value of the first char in {expr}. Examples: >
1941 char2nr(" ") returns 32
1942 char2nr("ABC") returns 65
1943< The current 'encoding' is used. Example for "utf-8": >
Bram Moolenaar98692072006-02-04 00:57:42 +00001944 char2nr("?") returns 225
1945 char2nr("?"[0]) returns 195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001946< nr2char() does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001947
1948cindent({lnum}) *cindent()*
1949 Get the amount of indent for line {lnum} according the C
1950 indenting rules, as with 'cindent'.
1951 The indent is counted in spaces, the value of 'tabstop' is
1952 relevant. {lnum} is used just like in |getline()|.
1953 When {lnum} is invalid or Vim was not compiled the |+cindent|
1954 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00001955 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001956
1957 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001958col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001959 position given with {expr}. The accepted positions are:
1960 . the cursor position
1961 $ the end of the cursor line (the result is the
1962 number of characters in the cursor line plus one)
1963 'x position of mark x (if the mark is not set, 0 is
1964 returned)
Bram Moolenaar0b238792006-03-02 22:49:12 +00001965 To get the line number use |col()|. To get both use
1966 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001967 For the screen column position use |virtcol()|.
1968 Note that only marks in the current file can be used.
1969 Examples: >
1970 col(".") column of cursor
1971 col("$") length of cursor line plus one
1972 col("'t") column of mark t
1973 col("'" . markname) column of mark markname
1974< The first column is 1. 0 is returned for an error.
1975 For the cursor position, when 'virtualedit' is active, the
1976 column is one higher if the cursor is after the end of the
1977 line. This can be used to obtain the column in Insert mode: >
1978 :imap <F2> <C-O>:let save_ve = &ve<CR>
1979 \<C-O>:set ve=all<CR>
1980 \<C-O>:echo col(".") . "\n" <Bar>
1981 \let &ve = save_ve<CR>
1982<
Bram Moolenaar572cb562005-08-05 21:35:02 +00001983
Bram Moolenaara94bc432006-03-10 21:42:59 +00001984complete({startcol}, {matches}) *complete()* *E785*
1985 Set the matches for Insert mode completion.
1986 Can only be used in Insert mode. You need to use a mapping
1987 with an expression argument |:map-<expr>| or CTRL-R =
1988 |i_CTRL-R|. It does not work after CTRL-O.
1989 {startcol} is the byte offset in the line where the completed
1990 text start. The text up to the cursor is the original text
1991 that will be replaced by the matches. Use col('.') for an
1992 empty string. "col('.') - 1" will replace one character by a
1993 match.
1994 {matches} must be a |List|. Each |List| item is one match.
1995 See |complete-items| for the kind of items that are possible.
1996 Note that the after calling this function you need to avoid
1997 inserting anything that would completion to stop.
1998 The match can be selected with CTRL-N and CTRL-P as usual with
1999 Insert mode completion. The popup menu will appear if
2000 specified, see |ins-completion-menu|.
2001 Example: >
2002 inoremap <expr> <F5> ListMonths()
2003
2004 func! ListMonths()
2005 call complete(col('.'), ['January', 'February', 'March',
2006 \ 'April', 'May', 'June', 'July', 'August', 'September',
2007 \ 'October', 'November', 'December'])
2008 return ''
2009 endfunc
2010< This isn't very useful, but it shows how it works. Note that
2011 an empty string is returned to avoid a zero being inserted.
2012
Bram Moolenaar572cb562005-08-05 21:35:02 +00002013complete_add({expr}) *complete_add()*
2014 Add {expr} to the list of matches. Only to be used by the
2015 function specified with the 'completefunc' option.
2016 Returns 0 for failure (empty string or out of memory),
2017 1 when the match was added, 2 when the match was already in
2018 the list.
Bram Moolenaar39f05632006-03-19 22:15:26 +00002019 See |complete-functions| for an explanation of {expr}. It is
2020 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002021
2022complete_check() *complete_check()*
2023 Check for a key typed while looking for completion matches.
2024 This is to be used when looking for matches takes some time.
2025 Returns non-zero when searching for matches is to be aborted,
2026 zero otherwise.
2027 Only to be used by the function specified with the
2028 'completefunc' option.
2029
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030 *confirm()*
2031confirm({msg} [, {choices} [, {default} [, {type}]]])
2032 Confirm() offers the user a dialog, from which a choice can be
2033 made. It returns the number of the choice. For the first
2034 choice this is 1.
2035 Note: confirm() is only supported when compiled with dialog
2036 support, see |+dialog_con| and |+dialog_gui|.
2037 {msg} is displayed in a |dialog| with {choices} as the
2038 alternatives. When {choices} is missing or empty, "&OK" is
2039 used (and translated).
2040 {msg} is a String, use '\n' to include a newline. Only on
2041 some systems the string is wrapped when it doesn't fit.
2042 {choices} is a String, with the individual choices separated
2043 by '\n', e.g. >
2044 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2045< The letter after the '&' is the shortcut key for that choice.
2046 Thus you can type 'c' to select "Cancel". The shortcut does
2047 not need to be the first letter: >
2048 confirm("file has been modified", "&Save\nSave &All")
2049< For the console, the first letter of each choice is used as
2050 the default shortcut key.
2051 The optional {default} argument is the number of the choice
2052 that is made if the user hits <CR>. Use 1 to make the first
2053 choice the default one. Use 0 to not set a default. If
2054 {default} is omitted, 1 is used.
2055 The optional {type} argument gives the type of dialog. This
2056 is only used for the icon of the Win32 GUI. It can be one of
2057 these values: "Error", "Question", "Info", "Warning" or
2058 "Generic". Only the first character is relevant. When {type}
2059 is omitted, "Generic" is used.
2060 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2061 or another valid interrupt key, confirm() returns 0.
2062
2063 An example: >
2064 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2065 :if choice == 0
2066 : echo "make up your mind!"
2067 :elseif choice == 3
2068 : echo "tasteful"
2069 :else
2070 : echo "I prefer bananas myself."
2071 :endif
2072< In a GUI dialog, buttons are used. The layout of the buttons
2073 depends on the 'v' flag in 'guioptions'. If it is included,
2074 the buttons are always put vertically. Otherwise, confirm()
2075 tries to put the buttons in one horizontal line. If they
2076 don't fit, a vertical layout is used anyway. For some systems
2077 the horizontal layout is always used.
2078
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002079 *copy()*
2080copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
2081 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002082 When {expr} is a |List| a shallow copy is created. This means
2083 that the original |List| can be changed without changing the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002084 copy, and vise versa. But the items are identical, thus
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002085 changing an item changes the contents of both |Lists|. Also
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002086 see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002087
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002088count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002089 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002090 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002091 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002092 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002093 When {ic} is given and it's non-zero then case is ignored.
2094
2095
Bram Moolenaar071d4272004-06-13 20:20:40 +00002096 *cscope_connection()*
2097cscope_connection([{num} , {dbpath} [, {prepend}]])
2098 Checks for the existence of a |cscope| connection. If no
2099 parameters are specified, then the function returns:
2100 0, if cscope was not available (not compiled in), or
2101 if there are no cscope connections;
2102 1, if there is at least one cscope connection.
2103
2104 If parameters are specified, then the value of {num}
2105 determines how existence of a cscope connection is checked:
2106
2107 {num} Description of existence check
2108 ----- ------------------------------
2109 0 Same as no parameters (e.g., "cscope_connection()").
2110 1 Ignore {prepend}, and use partial string matches for
2111 {dbpath}.
2112 2 Ignore {prepend}, and use exact string matches for
2113 {dbpath}.
2114 3 Use {prepend}, use partial string matches for both
2115 {dbpath} and {prepend}.
2116 4 Use {prepend}, use exact string matches for both
2117 {dbpath} and {prepend}.
2118
2119 Note: All string comparisons are case sensitive!
2120
2121 Examples. Suppose we had the following (from ":cs show"): >
2122
2123 # pid database name prepend path
2124 0 27664 cscope.out /usr/local
2125<
2126 Invocation Return Val ~
2127 ---------- ---------- >
2128 cscope_connection() 1
2129 cscope_connection(1, "out") 1
2130 cscope_connection(2, "out") 0
2131 cscope_connection(3, "out") 0
2132 cscope_connection(3, "out", "local") 1
2133 cscope_connection(4, "out") 0
2134 cscope_connection(4, "out", "local") 0
2135 cscope_connection(4, "cscope.out", "/usr/local") 1
2136<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002137cursor({lnum}, {col} [, {off}]) *cursor()*
2138cursor({list})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002139 Positions the cursor at the column {col} in the line {lnum}.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002140 The first column is one.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002141 When there is one argument {list} this is used as a |List|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002142 with two or three items {lnum}, {col} and {off}. This is like
2143 the return value of |getpos()|, but without the first item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002144 Does not change the jumplist.
2145 If {lnum} is greater than the number of lines in the buffer,
2146 the cursor will be positioned at the last line in the buffer.
2147 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002148 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002149 the cursor will be positioned at the last character in the
2150 line.
2151 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002152 When 'virtualedit' is used {off} specifies the offset in
2153 screen columns from the start of the character. E.g., a
2154 position within a Tab or after the last character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002155
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002156
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002157deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002158 Make a copy of {expr}. For Numbers and Strings this isn't
2159 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002160 When {expr} is a |List| a full copy is created. This means
2161 that the original |List| can be changed without changing the
2162 copy, and vise versa. When an item is a |List|, a copy for it
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002163 is made, recursively. Thus changing an item in the copy does
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002164 not change the contents of the original |List|.
2165 When {noref} is omitted or zero a contained |List| or
2166 |Dictionary| is only copied once. All references point to
2167 this single copy. With {noref} set to 1 every occurrence of a
2168 |List| or |Dictionary| results in a new copy. This also means
2169 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002170 *E724*
2171 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002172 that refers back to a higher level making a deep copy with
2173 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002174 Also see |copy()|.
2175
2176delete({fname}) *delete()*
2177 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002178 which is 0 if the file was deleted successfully, and non-zero
2179 when the deletion failed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002180 Use |remove()| to delete an item from a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002181
2182 *did_filetype()*
2183did_filetype() Returns non-zero when autocommands are being executed and the
2184 FileType event has been triggered at least once. Can be used
2185 to avoid triggering the FileType event again in the scripts
2186 that detect the file type. |FileType|
2187 When editing another file, the counter is reset, thus this
2188 really checks if the FileType event has been triggered for the
2189 current buffer. This allows an autocommand that starts
2190 editing another buffer to set 'filetype' and load a syntax
2191 file.
2192
Bram Moolenaar47136d72004-10-12 20:02:24 +00002193diff_filler({lnum}) *diff_filler()*
2194 Returns the number of filler lines above line {lnum}.
2195 These are the lines that were inserted at this point in
2196 another diff'ed window. These filler lines are shown in the
2197 display but don't exist in the buffer.
2198 {lnum} is used like with |getline()|. Thus "." is the current
2199 line, "'m" mark m, etc.
2200 Returns 0 if the current window is not in diff mode.
2201
2202diff_hlID({lnum}, {col}) *diff_hlID()*
2203 Returns the highlight ID for diff mode at line {lnum} column
2204 {col} (byte index). When the current line does not have a
2205 diff change zero is returned.
2206 {lnum} is used like with |getline()|. Thus "." is the current
2207 line, "'m" mark m, etc.
2208 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2209 line.
2210 The highlight ID can be used with |synIDattr()| to obtain
2211 syntax information about the highlighting.
2212
Bram Moolenaar13065c42005-01-08 16:08:21 +00002213empty({expr}) *empty()*
2214 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002215 A |List| or |Dictionary| is empty when it does not have any
2216 items. A Number is empty when its value is zero.
2217 For a long |List| this is much faster then comparing the
2218 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002219
Bram Moolenaar071d4272004-06-13 20:20:40 +00002220escape({string}, {chars}) *escape()*
2221 Escape the characters in {chars} that occur in {string} with a
2222 backslash. Example: >
2223 :echo escape('c:\program files\vim', ' \')
2224< results in: >
2225 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002226
2227< *eval()*
2228eval({string}) Evaluate {string} and return the result. Especially useful to
2229 turn the result of |string()| back into the original value.
2230 This works for Numbers, Strings and composites of them.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002231 Also works for |Funcref|s that refer to existing functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002232
Bram Moolenaar071d4272004-06-13 20:20:40 +00002233eventhandler() *eventhandler()*
2234 Returns 1 when inside an event handler. That is that Vim got
2235 interrupted while waiting for the user to type a character,
2236 e.g., when dropping a file on Vim. This means interactive
2237 commands cannot be used. Otherwise zero is returned.
2238
2239executable({expr}) *executable()*
2240 This function checks if an executable with the name {expr}
2241 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002242 arguments.
2243 executable() uses the value of $PATH and/or the normal
2244 searchpath for programs. *PATHEXT*
2245 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2246 optionally be included. Then the extensions in $PATHEXT are
2247 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2248 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2249 used. A dot by itself can be used in $PATHEXT to try using
2250 the name without an extension. When 'shell' looks like a
2251 Unix shell, then the name is also tried without adding an
2252 extension.
2253 On MS-DOS and MS-Windows it only checks if the file exists and
2254 is not a directory, not if it's really executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002255 The result is a Number:
2256 1 exists
2257 0 does not exist
2258 -1 not implemented on this system
2259
2260 *exists()*
2261exists({expr}) The result is a Number, which is non-zero if {expr} is
2262 defined, zero otherwise. The {expr} argument is a string,
2263 which contains one of these:
2264 &option-name Vim option (only checks if it exists,
2265 not if it really works)
2266 +option-name Vim option that works.
2267 $ENVNAME environment variable (could also be
2268 done by comparing with an empty
2269 string)
2270 *funcname built-in function (see |functions|)
2271 or user defined function (see
2272 |user-functions|).
2273 varname internal variable (see
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002274 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002275 for |curly-braces-names|, |Dictionary|
2276 entries, |List| items, etc. Beware
2277 that this may cause functions to be
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002278 invoked cause an error message for an
2279 invalid expression.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002280 :cmdname Ex command: built-in command, user
2281 command or command modifier |:command|.
2282 Returns:
2283 1 for match with start of a command
2284 2 full match with a command
2285 3 matches several user commands
2286 To check for a supported command
2287 always check the return value to be 2.
2288 #event autocommand defined for this event
2289 #event#pattern autocommand defined for this event and
2290 pattern (the pattern is taken
2291 literally and compared to the
2292 autocommand patterns character by
2293 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002294 #group autocommand group exists
2295 #group#event autocommand defined for this group and
2296 event.
2297 #group#event#pattern
2298 autocommand defined for this group,
2299 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002300 ##event autocommand for this event is
2301 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002302 For checking for a supported feature use |has()|.
2303
2304 Examples: >
2305 exists("&shortname")
2306 exists("$HOSTNAME")
2307 exists("*strftime")
2308 exists("*s:MyFunc")
2309 exists("bufcount")
2310 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002311 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002312 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002313 exists("#filetypeindent")
2314 exists("#filetypeindent#FileType")
2315 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002316 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002317< There must be no space between the symbol (&/$/*/#) and the
2318 name.
2319 Note that the argument must be a string, not the name of the
2320 variable itself! For example: >
2321 exists(bufcount)
2322< This doesn't check for existence of the "bufcount" variable,
2323 but gets the contents of "bufcount", and checks if that
2324 exists.
2325
2326expand({expr} [, {flag}]) *expand()*
2327 Expand wildcards and the following special keywords in {expr}.
2328 The result is a String.
2329
2330 When there are several matches, they are separated by <NL>
2331 characters. [Note: in version 5.0 a space was used, which
2332 caused problems when a file name contains a space]
2333
2334 If the expansion fails, the result is an empty string. A name
2335 for a non-existing file is not included.
2336
2337 When {expr} starts with '%', '#' or '<', the expansion is done
2338 like for the |cmdline-special| variables with their associated
2339 modifiers. Here is a short overview:
2340
2341 % current file name
2342 # alternate file name
2343 #n alternate file name n
2344 <cfile> file name under the cursor
2345 <afile> autocmd file name
2346 <abuf> autocmd buffer number (as a String!)
2347 <amatch> autocmd matched name
2348 <sfile> sourced script file name
2349 <cword> word under the cursor
2350 <cWORD> WORD under the cursor
2351 <client> the {clientid} of the last received
2352 message |server2client()|
2353 Modifiers:
2354 :p expand to full path
2355 :h head (last path component removed)
2356 :t tail (last path component only)
2357 :r root (one extension removed)
2358 :e extension only
2359
2360 Example: >
2361 :let &tags = expand("%:p:h") . "/tags"
2362< Note that when expanding a string that starts with '%', '#' or
2363 '<', any following text is ignored. This does NOT work: >
2364 :let doesntwork = expand("%:h.bak")
2365< Use this: >
2366 :let doeswork = expand("%:h") . ".bak"
2367< Also note that expanding "<cfile>" and others only returns the
2368 referenced file name without further expansion. If "<cfile>"
2369 is "~/.cshrc", you need to do another expand() to have the
2370 "~/" expanded into the path of the home directory: >
2371 :echo expand(expand("<cfile>"))
2372<
2373 There cannot be white space between the variables and the
2374 following modifier. The |fnamemodify()| function can be used
2375 to modify normal file names.
2376
2377 When using '%' or '#', and the current or alternate file name
2378 is not defined, an empty string is used. Using "%:p" in a
2379 buffer with no name, results in the current directory, with a
2380 '/' added.
2381
2382 When {expr} does not start with '%', '#' or '<', it is
2383 expanded like a file name is expanded on the command line.
2384 'suffixes' and 'wildignore' are used, unless the optional
2385 {flag} argument is given and it is non-zero. Names for
Bram Moolenaar02743632005-07-25 20:42:36 +00002386 non-existing files are included. The "**" item can be used to
2387 search in a directory tree. For example, to find all "README"
2388 files in the current directory and below: >
2389 :echo expand("**/README")
2390<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002391 Expand() can also be used to expand variables and environment
2392 variables that are only known in a shell. But this can be
2393 slow, because a shell must be started. See |expr-env-expand|.
2394 The expanded variable is still handled like a list of file
2395 names. When an environment variable cannot be expanded, it is
2396 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2397 "$FOOBAR".
2398
2399 See |glob()| for finding existing files. See |system()| for
2400 getting the raw output of an external command.
2401
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002402extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002403 {expr1} and {expr2} must be both |Lists| or both
2404 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002405
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002406 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002407 If {expr3} is given insert the items of {expr2} before item
2408 {expr3} in {expr1}. When {expr3} is zero insert before the
2409 first item. When {expr3} is equal to len({expr1}) then
2410 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002411 Examples: >
2412 :echo sort(extend(mylist, [7, 5]))
2413 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002414< Use |add()| to concatenate one item to a list. To concatenate
2415 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002416 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002417<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002418 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002419 Add all entries from {expr2} to {expr1}.
2420 If a key exists in both {expr1} and {expr2} then {expr3} is
2421 used to decide what to do:
2422 {expr3} = "keep": keep the value of {expr1}
2423 {expr3} = "force": use the value of {expr2}
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00002424 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002425 When {expr3} is omitted then "force" is assumed.
2426
2427 {expr1} is changed when {expr2} is not empty. If necessary
2428 make a copy of {expr1} first.
2429 {expr2} remains unchanged.
2430 Returns {expr1}.
2431
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002432
Bram Moolenaar071d4272004-06-13 20:20:40 +00002433filereadable({file}) *filereadable()*
2434 The result is a Number, which is TRUE when a file with the
2435 name {file} exists, and can be read. If {file} doesn't exist,
2436 or is a directory, the result is FALSE. {file} is any
2437 expression, which is used as a String.
2438 *file_readable()*
2439 Obsolete name: file_readable().
2440
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002441
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002442filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002443 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002444 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002445 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002446 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002447 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002448 Examples: >
2449 :call filter(mylist, 'v:val !~ "OLD"')
2450< Removes the items where "OLD" appears. >
2451 :call filter(mydict, 'v:key >= 8')
2452< Removes the items with a key below 8. >
2453 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002454< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002455
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002456 Note that {string} is the result of expression and is then
2457 used as an expression again. Often it is good to use a
2458 |literal-string| to avoid having to double backslashes.
2459
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002460 The operation is done in-place. If you want a |List| or
2461 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00002462 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002463
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002464< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00002465 When an error is encountered while evaluating {string} no
2466 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002467
2468
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002469finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002470 Find directory {name} in {path}. Returns the path of the
2471 first found match. When the found directory is below the
2472 current directory a relative path is returned. Otherwise a
2473 full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002474 If {path} is omitted or empty then 'path' is used.
2475 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002476 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00002477 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002478 This is quite similar to the ex-command |:find|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002479 {only available when compiled with the +file_in_path feature}
2480
2481findfile({name}[, {path}[, {count}]]) *findfile()*
2482 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002483 Uses 'suffixesadd'.
2484 Example: >
2485 :echo findfile("tags.vim", ".;")
2486< Searches from the current directory upwards until it finds
2487 the file "tags.vim".
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002488
Bram Moolenaar071d4272004-06-13 20:20:40 +00002489filewritable({file}) *filewritable()*
2490 The result is a Number, which is 1 when a file with the
2491 name {file} exists, and can be written. If {file} doesn't
2492 exist, or is not writable, the result is 0. If (file) is a
2493 directory, and we can write to it, the result is 2.
2494
2495fnamemodify({fname}, {mods}) *fnamemodify()*
2496 Modify file name {fname} according to {mods}. {mods} is a
2497 string of characters like it is used for file names on the
2498 command line. See |filename-modifiers|.
2499 Example: >
2500 :echo fnamemodify("main.c", ":p:h")
2501< results in: >
2502 /home/mool/vim/vim/src
2503< Note: Environment variables and "~" don't work in {fname}, use
2504 |expand()| first then.
2505
2506foldclosed({lnum}) *foldclosed()*
2507 The result is a Number. If the line {lnum} is in a closed
2508 fold, the result is the number of the first line in that fold.
2509 If the line {lnum} is not in a closed fold, -1 is returned.
2510
2511foldclosedend({lnum}) *foldclosedend()*
2512 The result is a Number. If the line {lnum} is in a closed
2513 fold, the result is the number of the last line in that fold.
2514 If the line {lnum} is not in a closed fold, -1 is returned.
2515
2516foldlevel({lnum}) *foldlevel()*
2517 The result is a Number, which is the foldlevel of line {lnum}
2518 in the current buffer. For nested folds the deepest level is
2519 returned. If there is no fold at line {lnum}, zero is
2520 returned. It doesn't matter if the folds are open or closed.
2521 When used while updating folds (from 'foldexpr') -1 is
2522 returned for lines where folds are still to be updated and the
2523 foldlevel is unknown. As a special case the level of the
2524 previous line is usually available.
2525
2526 *foldtext()*
2527foldtext() Returns a String, to be displayed for a closed fold. This is
2528 the default function used for the 'foldtext' option and should
2529 only be called from evaluating 'foldtext'. It uses the
2530 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2531 The returned string looks like this: >
2532 +-- 45 lines: abcdef
2533< The number of dashes depends on the foldlevel. The "45" is
2534 the number of lines in the fold. "abcdef" is the text in the
2535 first non-blank line of the fold. Leading white space, "//"
2536 or "/*" and the text from the 'foldmarker' and 'commentstring'
2537 options is removed.
2538 {not available when compiled without the |+folding| feature}
2539
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002540foldtextresult({lnum}) *foldtextresult()*
2541 Returns the text that is displayed for the closed fold at line
2542 {lnum}. Evaluates 'foldtext' in the appropriate context.
2543 When there is no closed fold at {lnum} an empty string is
2544 returned.
2545 {lnum} is used like with |getline()|. Thus "." is the current
2546 line, "'m" mark m, etc.
2547 Useful when exporting folded text, e.g., to HTML.
2548 {not available when compiled without the |+folding| feature}
2549
Bram Moolenaar071d4272004-06-13 20:20:40 +00002550 *foreground()*
2551foreground() Move the Vim window to the foreground. Useful when sent from
2552 a client to a Vim server. |remote_send()|
2553 On Win32 systems this might not work, the OS does not always
2554 allow a window to bring itself to the foreground. Use
2555 |remote_foreground()| instead.
2556 {only in the Win32, Athena, Motif and GTK GUI versions and the
2557 Win32 console version}
2558
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002559
Bram Moolenaar13065c42005-01-08 16:08:21 +00002560function({name}) *function()* *E700*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002561 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002562 {name} can be a user defined function or an internal function.
2563
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002564
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002565garbagecollect() *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002566 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002567 references. There is hardly ever a need to invoke this
2568 function, as it is automatically done when Vim runs out of
2569 memory or is waiting for the user to press a key after
2570 'updatetime'. Items without circular references are always
2571 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002572 This is useful if you have deleted a very big |List| and/or
2573 |Dictionary| with circular references in a script that runs
2574 for a long time.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002575
Bram Moolenaar677ee682005-01-27 14:41:15 +00002576get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002577 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002578 available return {default}. Return zero when {default} is
2579 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002580get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002581 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002582 item is not available return {default}. Return zero when
2583 {default} is omitted.
2584
Bram Moolenaar45360022005-07-21 21:08:21 +00002585 *getbufline()*
2586getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002587 Return a |List| with the lines starting from {lnum} to {end}
2588 (inclusive) in the buffer {expr}. If {end} is omitted, a
2589 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002590
2591 For the use of {expr}, see |bufname()| above.
2592
Bram Moolenaar661b1822005-07-28 22:36:45 +00002593 For {lnum} and {end} "$" can be used for the last line of the
2594 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00002595
2596 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002597 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002598
2599 When {end} is greater than the number of lines in the buffer,
2600 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002601 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00002602 returned.
2603
Bram Moolenaar661b1822005-07-28 22:36:45 +00002604 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002605 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002606
2607 Example: >
2608 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002609
2610getbufvar({expr}, {varname}) *getbufvar()*
2611 The result is the value of option or local buffer variable
2612 {varname} in buffer {expr}. Note that the name without "b:"
2613 must be used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002614 This also works for a global or buffer-local option, but it
2615 doesn't work for a global variable, window-local variable or
2616 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002617 For the use of {expr}, see |bufname()| above.
2618 When the buffer or variable doesn't exist an empty string is
2619 returned, there is no error message.
2620 Examples: >
2621 :let bufmodified = getbufvar(1, "&mod")
2622 :echo "todo myvar = " . getbufvar("todo", "myvar")
2623<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002624getchar([expr]) *getchar()*
2625 Get a single character from the user. If it is an 8-bit
2626 character, the result is a number. Otherwise a String is
2627 returned with the encoded character. For a special key it's a
2628 sequence of bytes starting with 0x80 (decimal: 128).
2629 If [expr] is omitted, wait until a character is available.
2630 If [expr] is 0, only get a character when one is available.
2631 If [expr] is 1, only check if a character is available, it is
2632 not consumed. If a normal character is
2633 available, it is returned, otherwise a
2634 non-zero value is returned.
2635 If a normal character available, it is returned as a Number.
2636 Use nr2char() to convert it to a String.
2637 The returned value is zero if no character is available.
2638 The returned value is a string of characters for special keys
2639 and when a modifier (shift, control, alt) was used.
2640 There is no prompt, you will somehow have to make clear to the
2641 user that a character has to be typed.
2642 There is no mapping for the character.
2643 Key codes are replaced, thus when the user presses the <Del>
2644 key you get the code for the <Del> key, not the raw character
2645 sequence. Examples: >
2646 getchar() == "\<Del>"
2647 getchar() == "\<S-Left>"
2648< This example redefines "f" to ignore case: >
2649 :nmap f :call FindChar()<CR>
2650 :function FindChar()
2651 : let c = nr2char(getchar())
2652 : while col('.') < col('$') - 1
2653 : normal l
2654 : if getline('.')[col('.') - 1] ==? c
2655 : break
2656 : endif
2657 : endwhile
2658 :endfunction
2659
2660getcharmod() *getcharmod()*
2661 The result is a Number which is the state of the modifiers for
2662 the last obtained character with getchar() or in another way.
2663 These values are added together:
2664 2 shift
2665 4 control
2666 8 alt (meta)
2667 16 mouse double click
2668 32 mouse triple click
2669 64 mouse quadruple click
2670 128 Macintosh only: command
2671 Only the modifiers that have not been included in the
2672 character itself are obtained. Thus Shift-a results in "A"
2673 with no modifier.
2674
Bram Moolenaar071d4272004-06-13 20:20:40 +00002675getcmdline() *getcmdline()*
2676 Return the current command-line. Only works when the command
2677 line is being edited, thus requires use of |c_CTRL-\_e| or
2678 |c_CTRL-R_=|.
2679 Example: >
2680 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002681< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002682
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002683getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002684 Return the position of the cursor in the command line as a
2685 byte count. The first column is 1.
2686 Only works when editing the command line, thus requires use of
2687 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002688 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
2689
2690getcmdtype() *getcmdtype()*
2691 Return the current command-line type. Possible return values
2692 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00002693 : normal Ex command
2694 > debug mode command |debug-mode|
2695 / forward search command
2696 ? backward search command
2697 @ |input()| command
2698 - |:insert| or |:append| command
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002699 Only works when editing the command line, thus requires use of
2700 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
2701 otherwise.
2702 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002703
2704 *getcwd()*
2705getcwd() The result is a String, which is the name of the current
2706 working directory.
2707
2708getfsize({fname}) *getfsize()*
2709 The result is a Number, which is the size in bytes of the
2710 given file {fname}.
2711 If {fname} is a directory, 0 is returned.
2712 If the file {fname} can't be found, -1 is returned.
2713
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002714getfontname([{name}]) *getfontname()*
2715 Without an argument returns the name of the normal font being
2716 used. Like what is used for the Normal highlight group
2717 |hl-Normal|.
2718 With an argument a check is done whether {name} is a valid
2719 font name. If not then an empty string is returned.
2720 Otherwise the actual font name is returned, or {name} if the
2721 GUI does not support obtaining the real name.
2722 Only works when the GUI is running, thus not you your vimrc or
2723 Note that the GTK 2 GUI accepts any font name, thus checking
2724 for a valid name does not work.
2725 gvimrc file. Use the |GUIEnter| autocommand to use this
2726 function just after the GUI has started.
2727
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002728getfperm({fname}) *getfperm()*
2729 The result is a String, which is the read, write, and execute
2730 permissions of the given file {fname}.
2731 If {fname} does not exist or its directory cannot be read, an
2732 empty string is returned.
2733 The result is of the form "rwxrwxrwx", where each group of
2734 "rwx" flags represent, in turn, the permissions of the owner
2735 of the file, the group the file belongs to, and other users.
2736 If a user does not have a given permission the flag for this
2737 is replaced with the string "-". Example: >
2738 :echo getfperm("/etc/passwd")
2739< This will hopefully (from a security point of view) display
2740 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00002741
Bram Moolenaar071d4272004-06-13 20:20:40 +00002742getftime({fname}) *getftime()*
2743 The result is a Number, which is the last modification time of
2744 the given file {fname}. The value is measured as seconds
2745 since 1st Jan 1970, and may be passed to strftime(). See also
2746 |localtime()| and |strftime()|.
2747 If the file {fname} can't be found -1 is returned.
2748
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002749getftype({fname}) *getftype()*
2750 The result is a String, which is a description of the kind of
2751 file of the given file {fname}.
2752 If {fname} does not exist an empty string is returned.
2753 Here is a table over different kinds of files and their
2754 results:
2755 Normal file "file"
2756 Directory "dir"
2757 Symbolic link "link"
2758 Block device "bdev"
2759 Character device "cdev"
2760 Socket "socket"
2761 FIFO "fifo"
2762 All other "other"
2763 Example: >
2764 getftype("/home")
2765< Note that a type such as "link" will only be returned on
2766 systems that support it. On some systems only "dir" and
2767 "file" are returned.
2768
Bram Moolenaar071d4272004-06-13 20:20:40 +00002769 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002770getline({lnum} [, {end}])
2771 Without {end} the result is a String, which is line {lnum}
2772 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002773 getline(1)
2774< When {lnum} is a String that doesn't start with a
2775 digit, line() is called to translate the String into a Number.
2776 To get the line under the cursor: >
2777 getline(".")
2778< When {lnum} is smaller than 1 or bigger than the number of
2779 lines in the buffer, an empty string is returned.
2780
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002781 When {end} is given the result is a |List| where each item is
2782 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002783 including line {end}.
2784 {end} is used in the same way as {lnum}.
2785 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002786 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002787 Example: >
2788 :let start = line('.')
2789 :let end = search("^$") - 1
2790 :let lines = getline(start, end)
2791
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002792getloclist({nr}) *getloclist()*
2793 Returns a list with all the entries in the location list for
2794 window {nr}. When {nr} is zero the current window is used.
2795 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00002796 returned. For an invalid window number {nr}, an empty list is
2797 returned. Otherwise, same as getqflist().
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002798
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002799getqflist() *getqflist()*
2800 Returns a list with all the current quickfix errors. Each
2801 list item is a dictionary with these entries:
2802 bufnr number of buffer that has the file name, use
2803 bufname() to get the name
2804 lnum line number in the buffer (first line is 1)
2805 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00002806 vcol non-zero: "col" is visual column
2807 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002808 nr error number
2809 text description of the error
2810 type type of the error, 'E', '1', etc.
2811 valid non-zero: recognized error message
2812
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00002813 When there is no error list or it's empty an empty list is
2814 returned.
2815
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002816 Useful application: Find pattern matches in multiple files and
2817 do something with them: >
2818 :vimgrep /theword/jg *.c
2819 :for d in getqflist()
2820 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
2821 :endfor
2822
2823
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002824getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002825 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002826 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002827 :let cliptext = getreg('*')
2828< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002829 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002830 getreg('=', 1) returns the expression itself, so that it can
2831 be restored with |setreg()|. For other registers the extra
2832 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002833 If {regname} is not specified, |v:register| is used.
2834
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002835
Bram Moolenaar071d4272004-06-13 20:20:40 +00002836getregtype([{regname}]) *getregtype()*
2837 The result is a String, which is type of register {regname}.
2838 The value will be one of:
2839 "v" for |characterwise| text
2840 "V" for |linewise| text
2841 "<CTRL-V>{width}" for |blockwise-visual| text
2842 0 for an empty or unknown register
2843 <CTRL-V> is one character with value 0x16.
2844 If {regname} is not specified, |v:register| is used.
2845
2846 *getwinposx()*
2847getwinposx() The result is a Number, which is the X coordinate in pixels of
2848 the left hand side of the GUI Vim window. The result will be
2849 -1 if the information is not available.
2850
2851 *getwinposy()*
2852getwinposy() The result is a Number, which is the Y coordinate in pixels of
2853 the top of the GUI Vim window. The result will be -1 if the
2854 information is not available.
2855
2856getwinvar({nr}, {varname}) *getwinvar()*
2857 The result is the value of option or local window variable
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002858 {varname} in window {nr}. When {nr} is zero the current
2859 window is used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002860 This also works for a global option, buffer-local option and
2861 window-local option, but it doesn't work for a global variable
2862 or buffer-local variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002863 Note that the name without "w:" must be used.
2864 Examples: >
2865 :let list_is_on = getwinvar(2, '&list')
2866 :echo "myvar = " . getwinvar(1, 'myvar')
2867<
2868 *glob()*
2869glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2870 When there are several matches, they are separated by <NL>
2871 characters.
2872 If the expansion fails, the result is an empty string.
2873 A name for a non-existing file is not included.
2874
2875 For most systems backticks can be used to get files names from
2876 any external command. Example: >
2877 :let tagfiles = glob("`find . -name tags -print`")
2878 :let &tags = substitute(tagfiles, "\n", ",", "g")
2879< The result of the program inside the backticks should be one
2880 item per line. Spaces inside an item are allowed.
2881
2882 See |expand()| for expanding special Vim variables. See
2883 |system()| for getting the raw output of an external command.
2884
2885globpath({path}, {expr}) *globpath()*
2886 Perform glob() on all directories in {path} and concatenate
2887 the results. Example: >
2888 :echo globpath(&rtp, "syntax/c.vim")
2889< {path} is a comma-separated list of directory names. Each
2890 directory name is prepended to {expr} and expanded like with
2891 glob(). A path separator is inserted when needed.
2892 To add a comma inside a directory name escape it with a
2893 backslash. Note that on MS-Windows a directory may have a
2894 trailing backslash, remove it if you put a comma after it.
2895 If the expansion fails for one of the directories, there is no
2896 error message.
2897 The 'wildignore' option applies: Names matching one of the
2898 patterns in 'wildignore' will be skipped.
2899
Bram Moolenaar02743632005-07-25 20:42:36 +00002900 The "**" item can be used to search in a directory tree.
2901 For example, to find all "README.txt" files in the directories
2902 in 'runtimepath' and below: >
2903 :echo globpath(&rtp, "**/README.txt")
2904<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002905 *has()*
2906has({feature}) The result is a Number, which is 1 if the feature {feature} is
2907 supported, zero otherwise. The {feature} argument is a
2908 string. See |feature-list| below.
2909 Also see |exists()|.
2910
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002911
2912has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002913 The result is a Number, which is 1 if |Dictionary| {dict} has
2914 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002915
2916
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002917hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002918 The result is a Number, which is 1 if there is a mapping that
2919 contains {what} in somewhere in the rhs (what it is mapped to)
2920 and this mapping exists in one of the modes indicated by
2921 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002922 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00002923 instead of mappings. Don't forget to specify Insert and/or
2924 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002925 Both the global mappings and the mappings local to the current
2926 buffer are checked for a match.
2927 If no matching mapping is found 0 is returned.
2928 The following characters are recognized in {mode}:
2929 n Normal mode
2930 v Visual mode
2931 o Operator-pending mode
2932 i Insert mode
2933 l Language-Argument ("r", "f", "t", etc.)
2934 c Command-line mode
2935 When {mode} is omitted, "nvo" is used.
2936
2937 This function is useful to check if a mapping already exists
2938 to a function in a Vim script. Example: >
2939 :if !hasmapto('\ABCdoit')
2940 : map <Leader>d \ABCdoit
2941 :endif
2942< This installs the mapping to "\ABCdoit" only if there isn't
2943 already a mapping to "\ABCdoit".
2944
2945histadd({history}, {item}) *histadd()*
2946 Add the String {item} to the history {history} which can be
2947 one of: *hist-names*
2948 "cmd" or ":" command line history
2949 "search" or "/" search pattern history
2950 "expr" or "=" typed expression history
2951 "input" or "@" input line history
2952 If {item} does already exist in the history, it will be
2953 shifted to become the newest entry.
2954 The result is a Number: 1 if the operation was successful,
2955 otherwise 0 is returned.
2956
2957 Example: >
2958 :call histadd("input", strftime("%Y %b %d"))
2959 :let date=input("Enter date: ")
2960< This function is not available in the |sandbox|.
2961
2962histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002963 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002964 for the possible values of {history}.
2965
2966 If the parameter {item} is given as String, this is seen
2967 as regular expression. All entries matching that expression
2968 will be removed from the history (if there are any).
2969 Upper/lowercase must match, unless "\c" is used |/\c|.
2970 If {item} is a Number, it will be interpreted as index, see
2971 |:history-indexing|. The respective entry will be removed
2972 if it exists.
2973
2974 The result is a Number: 1 for a successful operation,
2975 otherwise 0 is returned.
2976
2977 Examples:
2978 Clear expression register history: >
2979 :call histdel("expr")
2980<
2981 Remove all entries starting with "*" from the search history: >
2982 :call histdel("/", '^\*')
2983<
2984 The following three are equivalent: >
2985 :call histdel("search", histnr("search"))
2986 :call histdel("search", -1)
2987 :call histdel("search", '^'.histget("search", -1).'$')
2988<
2989 To delete the last search pattern and use the last-but-one for
2990 the "n" command and 'hlsearch': >
2991 :call histdel("search", -1)
2992 :let @/ = histget("search", -1)
2993
2994histget({history} [, {index}]) *histget()*
2995 The result is a String, the entry with Number {index} from
2996 {history}. See |hist-names| for the possible values of
2997 {history}, and |:history-indexing| for {index}. If there is
2998 no such entry, an empty String is returned. When {index} is
2999 omitted, the most recent item from the history is used.
3000
3001 Examples:
3002 Redo the second last search from history. >
3003 :execute '/' . histget("search", -2)
3004
3005< Define an Ex command ":H {num}" that supports re-execution of
3006 the {num}th entry from the output of |:history|. >
3007 :command -nargs=1 H execute histget("cmd", 0+<args>)
3008<
3009histnr({history}) *histnr()*
3010 The result is the Number of the current entry in {history}.
3011 See |hist-names| for the possible values of {history}.
3012 If an error occurred, -1 is returned.
3013
3014 Example: >
3015 :let inp_index = histnr("expr")
3016<
3017hlexists({name}) *hlexists()*
3018 The result is a Number, which is non-zero if a highlight group
3019 called {name} exists. This is when the group has been
3020 defined in some way. Not necessarily when highlighting has
3021 been defined for it, it may also have been used for a syntax
3022 item.
3023 *highlight_exists()*
3024 Obsolete name: highlight_exists().
3025
3026 *hlID()*
3027hlID({name}) The result is a Number, which is the ID of the highlight group
3028 with name {name}. When the highlight group doesn't exist,
3029 zero is returned.
3030 This can be used to retrieve information about the highlight
3031 group. For example, to get the background color of the
3032 "Comment" group: >
3033 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3034< *highlightID()*
3035 Obsolete name: highlightID().
3036
3037hostname() *hostname()*
3038 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003039 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00003040 256 characters long are truncated.
3041
3042iconv({expr}, {from}, {to}) *iconv()*
3043 The result is a String, which is the text {expr} converted
3044 from encoding {from} to encoding {to}.
3045 When the conversion fails an empty string is returned.
3046 The encoding names are whatever the iconv() library function
3047 can accept, see ":!man 3 iconv".
3048 Most conversions require Vim to be compiled with the |+iconv|
3049 feature. Otherwise only UTF-8 to latin1 conversion and back
3050 can be done.
3051 This can be used to display messages with special characters,
3052 no matter what 'encoding' is set to. Write the message in
3053 UTF-8 and use: >
3054 echo iconv(utf8_str, "utf-8", &enc)
3055< Note that Vim uses UTF-8 for all Unicode encodings, conversion
3056 from/to UCS-2 is automatically changed to use UTF-8. You
3057 cannot use UCS-2 in a string anyway, because of the NUL bytes.
3058 {only available when compiled with the +multi_byte feature}
3059
3060 *indent()*
3061indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3062 current buffer. The indent is counted in spaces, the value
3063 of 'tabstop' is relevant. {lnum} is used just like in
3064 |getline()|.
3065 When {lnum} is invalid -1 is returned.
3066
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003067
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003068index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003069 Return the lowest index in |List| {list} where the item has a
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003070 value equal to {expr}.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003071 If {start} is given then start looking at the item with index
3072 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003073 When {ic} is given and it is non-zero, ignore case. Otherwise
3074 case must match.
3075 -1 is returned when {expr} is not found in {list}.
3076 Example: >
3077 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003078 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003079
3080
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003081input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003082 The result is a String, which is whatever the user typed on
3083 the command-line. The parameter is either a prompt string, or
3084 a blank string (for no prompt). A '\n' can be used in the
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003085 prompt to start a new line.
3086 The highlighting set with |:echohl| is used for the prompt.
3087 The input is entered just like a command-line, with the same
3088 editing commands and mappings. There is a separate history
3089 for lines typed for input().
3090 Example: >
3091 :if input("Coffee or beer? ") == "beer"
3092 : echo "Cheers!"
3093 :endif
3094<
Bram Moolenaar1e015462005-09-25 22:16:38 +00003095 If the optional {text} is present and not empty, this is used
3096 for the default reply, as if the user typed this. Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003097 :let color = input("Color? ", "white")
3098
3099< The optional {completion} argument specifies the type of
3100 completion supported for the input. Without it completion is
3101 not performed. The supported completion types are the same as
3102 that can be supplied to a user-defined command using the
3103 "-complete=" argument. Refer to |:command-completion| for
3104 more information. Example: >
3105 let fname = input("File: ", "", "file")
3106<
3107 NOTE: This function must not be used in a startup file, for
3108 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003109 Note: When input() is called from within a mapping it will
3110 consume remaining characters from that mapping, because a
3111 mapping is handled like the characters were typed.
3112 Use |inputsave()| before input() and |inputrestore()|
3113 after input() to avoid that. Another solution is to avoid
3114 that further characters follow in the mapping, e.g., by using
3115 |:execute| or |:normal|.
3116
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003117 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003118 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3119 :function GetFoo()
3120 : call inputsave()
3121 : let g:Foo = input("enter search pattern: ")
3122 : call inputrestore()
3123 :endfunction
3124
3125inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3126 Like input(), but when the GUI is running and text dialogs are
3127 supported, a dialog window pops up to input the text.
3128 Example: >
3129 :let n = inputdialog("value for shiftwidth", &sw)
3130 :if n != ""
3131 : let &sw = n
3132 :endif
3133< When the dialog is cancelled {cancelreturn} is returned. When
3134 omitted an empty string is returned.
3135 Hitting <Enter> works like pressing the OK button. Hitting
3136 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003137 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003138
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003139inputlist({textlist}) *inputlist()*
3140 {textlist} must be a list of strings. This list is displayed,
3141 one string per line. The user will be prompted to enter a
3142 number, which is returned.
3143 The user can also select an item by clicking on it with the
3144 mouse. For the first string 0 is returned. When clicking
3145 above the first item a negative number is returned. When
3146 clicking on the prompt one more than the length of {textlist}
3147 is returned.
3148 Make sure {textlist} has less then 'lines' entries, otherwise
3149 it won't work. It's a good idea to put the entry number at
3150 the start of the string. Example: >
3151 let color = inputlist(['Select color:', '1. red',
3152 \ '2. green', '3. blue'])
3153
Bram Moolenaar071d4272004-06-13 20:20:40 +00003154inputrestore() *inputrestore()*
3155 Restore typeahead that was saved with a previous inputsave().
3156 Should be called the same number of times inputsave() is
3157 called. Calling it more often is harmless though.
3158 Returns 1 when there is nothing to restore, 0 otherwise.
3159
3160inputsave() *inputsave()*
3161 Preserve typeahead (also from mappings) and clear it, so that
3162 a following prompt gets input from the user. Should be
3163 followed by a matching inputrestore() after the prompt. Can
3164 be used several times, in which case there must be just as
3165 many inputrestore() calls.
3166 Returns 1 when out of memory, 0 otherwise.
3167
3168inputsecret({prompt} [, {text}]) *inputsecret()*
3169 This function acts much like the |input()| function with but
3170 two exceptions:
3171 a) the user's response will be displayed as a sequence of
3172 asterisks ("*") thereby keeping the entry secret, and
3173 b) the user's response will not be recorded on the input
3174 |history| stack.
3175 The result is a String, which is whatever the user actually
3176 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003177 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003178
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003179insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003180 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003181 If {idx} is specified insert {item} before the item with index
3182 {idx}. If {idx} is zero it goes before the first item, just
3183 like omitting {idx}. A negative {idx} is also possible, see
3184 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003185 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003186 :let mylist = insert([2, 3, 5], 1)
3187 :call insert(mylist, 4, -1)
3188 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003189< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003190 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003191 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003192
Bram Moolenaar071d4272004-06-13 20:20:40 +00003193isdirectory({directory}) *isdirectory()*
3194 The result is a Number, which is non-zero when a directory
3195 with the name {directory} exists. If {directory} doesn't
3196 exist, or isn't a directory, the result is FALSE. {directory}
3197 is any expression, which is used as a String.
3198
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003199islocked({expr}) *islocked()*
3200 The result is a Number, which is non-zero when {expr} is the
3201 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003202 {expr} must be the name of a variable, |List| item or
3203 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003204 :let alist = [0, ['a', 'b'], 2, 3]
3205 :lockvar 1 alist
3206 :echo islocked('alist') " 1
3207 :echo islocked('alist[1]') " 0
3208
3209< When {expr} is a variable that does not exist you get an error
3210 message. Use |exists()| to check for existance.
3211
Bram Moolenaar677ee682005-01-27 14:41:15 +00003212items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003213 Return a |List| with all the key-value pairs of {dict}. Each
3214 |List| item is a list with two items: the key of a {dict}
3215 entry and the value of this entry. The |List| is in arbitrary
3216 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003217
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003218
3219join({list} [, {sep}]) *join()*
3220 Join the items in {list} together into one String.
3221 When {sep} is specified it is put in between the items. If
3222 {sep} is omitted a single space is used.
3223 Note that {sep} is not added at the end. You might want to
3224 add it there too: >
3225 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003226< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003227 converted into a string like with |string()|.
3228 The opposite function is |split()|.
3229
Bram Moolenaard8b02732005-01-14 21:48:43 +00003230keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003231 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00003232 arbitrary order.
3233
Bram Moolenaar13065c42005-01-08 16:08:21 +00003234 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003235len({expr}) The result is a Number, which is the length of the argument.
3236 When {expr} is a String or a Number the length in bytes is
3237 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003238 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003239 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003240 When {expr} is a |Dictionary| the number of entries in the
3241 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003242 Otherwise an error is given.
3243
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244 *libcall()* *E364* *E368*
3245libcall({libname}, {funcname}, {argument})
3246 Call function {funcname} in the run-time library {libname}
3247 with single argument {argument}.
3248 This is useful to call functions in a library that you
3249 especially made to be used with Vim. Since only one argument
3250 is possible, calling standard library functions is rather
3251 limited.
3252 The result is the String returned by the function. If the
3253 function returns NULL, this will appear as an empty string ""
3254 to Vim.
3255 If the function returns a number, use libcallnr()!
3256 If {argument} is a number, it is passed to the function as an
3257 int; if {argument} is a string, it is passed as a
3258 null-terminated string.
3259 This function will fail in |restricted-mode|.
3260
3261 libcall() allows you to write your own 'plug-in' extensions to
3262 Vim without having to recompile the program. It is NOT a
3263 means to call system functions! If you try to do so Vim will
3264 very probably crash.
3265
3266 For Win32, the functions you write must be placed in a DLL
3267 and use the normal C calling convention (NOT Pascal which is
3268 used in Windows System DLLs). The function must take exactly
3269 one parameter, either a character pointer or a long integer,
3270 and must return a character pointer or NULL. The character
3271 pointer returned must point to memory that will remain valid
3272 after the function has returned (e.g. in static data in the
3273 DLL). If it points to allocated memory, that memory will
3274 leak away. Using a static buffer in the function should work,
3275 it's then freed when the DLL is unloaded.
3276
3277 WARNING: If the function returns a non-valid pointer, Vim may
3278 crash! This also happens if the function returns a number,
3279 because Vim thinks it's a pointer.
3280 For Win32 systems, {libname} should be the filename of the DLL
3281 without the ".DLL" suffix. A full path is only required if
3282 the DLL is not in the usual places.
3283 For Unix: When compiling your own plugins, remember that the
3284 object code must be compiled as position-independent ('PIC').
3285 {only in Win32 on some Unix versions, when the |+libcall|
3286 feature is present}
3287 Examples: >
3288 :echo libcall("libc.so", "getenv", "HOME")
3289 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3290<
3291 *libcallnr()*
3292libcallnr({libname}, {funcname}, {argument})
3293 Just like libcall(), but used for a function that returns an
3294 int instead of a string.
3295 {only in Win32 on some Unix versions, when the |+libcall|
3296 feature is present}
3297 Example (not very useful...): >
3298 :call libcallnr("libc.so", "printf", "Hello World!\n")
3299 :call libcallnr("libc.so", "sleep", 10)
3300<
3301 *line()*
3302line({expr}) The result is a Number, which is the line number of the file
3303 position given with {expr}. The accepted positions are:
3304 . the cursor position
3305 $ the last line in the current buffer
3306 'x position of mark x (if the mark is not set, 0 is
3307 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00003308 w0 first line visible in current window
3309 w$ last line visible in current window
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003310 Note that a mark in another file can be used.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003311 To get the column number use |col()|. To get both use
3312 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003313 Examples: >
3314 line(".") line number of the cursor
3315 line("'t") line number of mark t
3316 line("'" . marker) line number of mark marker
3317< *last-position-jump*
3318 This autocommand jumps to the last known position in a file
3319 just after opening it, if the '" mark is set: >
3320 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003321
Bram Moolenaar071d4272004-06-13 20:20:40 +00003322line2byte({lnum}) *line2byte()*
3323 Return the byte count from the start of the buffer for line
3324 {lnum}. This includes the end-of-line character, depending on
3325 the 'fileformat' option for the current buffer. The first
3326 line returns 1.
3327 This can also be used to get the byte count for the line just
3328 below the last line: >
3329 line2byte(line("$") + 1)
3330< This is the file size plus one.
3331 When {lnum} is invalid, or the |+byte_offset| feature has been
3332 disabled at compile time, -1 is returned.
3333 Also see |byte2line()|, |go| and |:goto|.
3334
3335lispindent({lnum}) *lispindent()*
3336 Get the amount of indent for line {lnum} according the lisp
3337 indenting rules, as with 'lisp'.
3338 The indent is counted in spaces, the value of 'tabstop' is
3339 relevant. {lnum} is used just like in |getline()|.
3340 When {lnum} is invalid or Vim was not compiled the
3341 |+lispindent| feature, -1 is returned.
3342
3343localtime() *localtime()*
3344 Return the current time, measured as seconds since 1st Jan
3345 1970. See also |strftime()| and |getftime()|.
3346
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003347
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003348map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003349 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003350 Replace each item in {expr} with the result of evaluating
3351 {string}.
3352 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003353 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003354 Example: >
3355 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003356< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003357
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003358 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003359 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003360 |literal-string| to avoid having to double backslashes. You
3361 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003362
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003363 The operation is done in-place. If you want a |List| or
3364 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003365 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003366
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003367< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003368 When an error is encountered while evaluating {string} no
3369 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003370
3371
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003372maparg({name}[, {mode} [, {abbr}]]) *maparg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003373 Return the rhs of mapping {name} in mode {mode}. When there
3374 is no mapping for {name}, an empty String is returned.
Bram Moolenaard12f5c12006-01-25 22:10:52 +00003375 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003376 "n" Normal
3377 "v" Visual
3378 "o" Operator-pending
3379 "i" Insert
3380 "c" Cmd-line
3381 "l" langmap |language-mapping|
3382 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00003383 When {mode} is omitted, the modes for "" are used.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003384 When {abbr} is there and it is non-zero use abbreviations
3385 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003386 The {name} can have special key names, like in the ":map"
3387 command. The returned String has special characters
3388 translated like in the output of the ":map" command listing.
3389 The mappings local to the current buffer are checked first,
3390 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00003391 This function can be used to map a key even when it's already
3392 mapped, and have it do the original mapping too. Sketch: >
3393 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
3394
Bram Moolenaar071d4272004-06-13 20:20:40 +00003395
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003396mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003397 Check if there is a mapping that matches with {name} in mode
3398 {mode}. See |maparg()| for {mode} and special names in
3399 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003400 When {abbr} is there and it is non-zero use abbreviations
3401 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003402 A match happens with a mapping that starts with {name} and
3403 with a mapping which is equal to the start of {name}.
3404
3405 matches mapping "a" "ab" "abc" ~
3406 mapcheck("a") yes yes yes
3407 mapcheck("abc") yes yes yes
3408 mapcheck("ax") yes no no
3409 mapcheck("b") no no no
3410
3411 The difference with maparg() is that mapcheck() finds a
3412 mapping that matches with {name}, while maparg() only finds a
3413 mapping for {name} exactly.
3414 When there is no mapping that starts with {name}, an empty
3415 String is returned. If there is one, the rhs of that mapping
3416 is returned. If there are several mappings that start with
3417 {name}, the rhs of one of them is returned.
3418 The mappings local to the current buffer are checked first,
3419 then the global mappings.
3420 This function can be used to check if a mapping can be added
3421 without being ambiguous. Example: >
3422 :if mapcheck("_vv") == ""
3423 : map _vv :set guifont=7x13<CR>
3424 :endif
3425< This avoids adding the "_vv" mapping when there already is a
3426 mapping for "_v" or for "_vvv".
3427
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003428match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003429 When {expr} is a |List| then this returns the index of the
3430 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003431 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003432 Otherwise, {expr} is used as a String. The result is a
3433 Number, which gives the index (byte offset) in {expr} where
3434 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003435 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003436 If there is no match -1 is returned.
3437 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003438 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00003439 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003440< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00003441 *strpbrk()*
3442 Vim doesn't have a strpbrk() function. But you can do: >
3443 :let sepidx = match(line, '[.,;: \t]')
3444< *strcasestr()*
3445 Vim doesn't have a strcasestr() function. But you can add
3446 "\c" to the pattern to ignore case: >
3447 :let idx = match(haystack, '\cneedle')
3448<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003449 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003450 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003451 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003452 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003453 :echo match("testing", "ing", 2)
3454< result is again "4". >
3455 :echo match("testing", "ing", 4)
3456< result is again "4". >
3457 :echo match("testing", "t", 2)
3458< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003459 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00003460 {start} bytes later, thus "^" will match at {start}. Except
3461 when {count} is given, then it's like matches before the
3462 {start} byte are ignored (this is a bit complicated to keep it
3463 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003464 For a String, if {start} < 0, it will be set to 0. For a list
3465 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00003466 If {start} is out of range ({start} > strlen({expr}) for a
3467 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003468
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003469 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00003470 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003471 character further. Thus this example results in 1: >
3472 echo match("testing", "..", 0, 2)
3473< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003474 Note that when {count} is added the way {start} works changes,
3475 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003476
Bram Moolenaar071d4272004-06-13 20:20:40 +00003477 See |pattern| for the patterns that are accepted.
3478 The 'ignorecase' option is used to set the ignore-caseness of
3479 the pattern. 'smartcase' is NOT used. The matching is always
3480 done like 'magic' is set and 'cpoptions' is empty.
3481
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003482matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003483 Same as match(), but return the index of first character after
3484 the match. Example: >
3485 :echo matchend("testing", "ing")
3486< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00003487 *strspn()* *strcspn()*
3488 Vim doesn't have a strspn() or strcspn() function, but you can
3489 do it with matchend(): >
3490 :let span = matchend(line, '[a-zA-Z]')
3491 :let span = matchend(line, '[^a-zA-Z]')
3492< Except that -1 is returned when there are no matches.
3493
Bram Moolenaar071d4272004-06-13 20:20:40 +00003494 The {start}, if given, has the same meaning as for match(). >
3495 :echo matchend("testing", "ing", 2)
3496< results in "7". >
3497 :echo matchend("testing", "ing", 5)
3498< result is "-1".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003499 When {expr} is a |List| the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003500
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003501matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003502 Same as match(), but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003503 list is the matched string, same as what matchstr() would
3504 return. Following items are submatches, like "\1", "\2", etc.
3505 in |:substitute|.
3506 When there is no match an empty list is returned.
3507
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003508matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003509 Same as match(), but return the matched string. Example: >
3510 :echo matchstr("testing", "ing")
3511< results in "ing".
3512 When there is no match "" is returned.
3513 The {start}, if given, has the same meaning as for match(). >
3514 :echo matchstr("testing", "ing", 2)
3515< results in "ing". >
3516 :echo matchstr("testing", "ing", 5)
3517< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003518 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003519 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003520
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003521 *max()*
3522max({list}) Return the maximum value of all items in {list}.
3523 If {list} is not a list or one of the items in {list} cannot
3524 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003525 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003526
3527 *min()*
3528min({list}) Return the minumum value of all items in {list}.
3529 If {list} is not a list or one of the items in {list} cannot
3530 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003531 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003532
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003533 *mkdir()* *E749*
3534mkdir({name} [, {path} [, {prot}]])
3535 Create directory {name}.
3536 If {path} is "p" then intermediate directories are created as
3537 necessary. Otherwise it must be "".
3538 If {prot} is given it is used to set the protection bits of
3539 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3540 the user readable for others). Use 0700 to make it unreadable
3541 for others.
3542 This function is not available in the |sandbox|.
3543 Not available on all systems. To check use: >
3544 :if exists("*mkdir")
3545<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003546 *mode()*
3547mode() Return a string that indicates the current mode:
3548 n Normal
3549 v Visual by character
3550 V Visual by line
3551 CTRL-V Visual blockwise
3552 s Select by character
3553 S Select by line
3554 CTRL-S Select blockwise
3555 i Insert
3556 R Replace
3557 c Command-line
3558 r Hit-enter prompt
3559 This is useful in the 'statusline' option. In most other
3560 places it always returns "c" or "n".
3561
3562nextnonblank({lnum}) *nextnonblank()*
3563 Return the line number of the first line at or below {lnum}
3564 that is not blank. Example: >
3565 if getline(nextnonblank(1)) =~ "Java"
3566< When {lnum} is invalid or there is no non-blank line at or
3567 below it, zero is returned.
3568 See also |prevnonblank()|.
3569
3570nr2char({expr}) *nr2char()*
3571 Return a string with a single character, which has the number
3572 value {expr}. Examples: >
3573 nr2char(64) returns "@"
3574 nr2char(32) returns " "
3575< The current 'encoding' is used. Example for "utf-8": >
3576 nr2char(300) returns I with bow character
3577< Note that a NUL character in the file is specified with
3578 nr2char(10), because NULs are represented with newline
3579 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003580 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003581
Bram Moolenaar0b238792006-03-02 22:49:12 +00003582 *getpos()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003583getpos({expr}) Get the position for {expr}. For possible values of {expr}
3584 see |line()|.
3585 The result is a |List| with four numbers:
3586 [bufnum, lnum, col, off]
3587 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3588 is the buffer number of the mark.
3589 "lnum" and "col" are the position in the buffer. The first
3590 column is 1.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003591 The "off" number is zero, unless 'virtualedit' is used. Then
3592 it is the offset in screen columns from the start of the
3593 character. E.g., a position within a Tab or after the last
3594 character.
3595 This can be used to save and restore the cursor position: >
3596 let save_cursor = getpos(".")
3597 MoveTheCursorAround
Bram Moolenaardb552d602006-03-23 22:59:57 +00003598 call setpos('.', save_cursor)
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003599< Also see |setpos()|.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003600
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003601prevnonblank({lnum}) *prevnonblank()*
3602 Return the line number of the first line at or above {lnum}
3603 that is not blank. Example: >
3604 let ind = indent(prevnonblank(v:lnum - 1))
3605< When {lnum} is invalid or there is no non-blank line at or
3606 above it, zero is returned.
3607 Also see |nextnonblank()|.
3608
3609
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003610printf({fmt}, {expr1} ...) *printf()*
3611 Return a String with {fmt}, where "%" items are replaced by
3612 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003613 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003614< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003615 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003616
3617 Often used items are:
3618 %s string
Bram Moolenaar98692072006-02-04 00:57:42 +00003619 %6s string right-aligned in 6 bytes
3620 %.9s string truncated to 9 bytes
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003621 %c single byte
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003622 %d decimal number
3623 %5d decimal number padded with spaces to 5 characters
3624 %x hex number
3625 %04x hex number padded with zeros to at least 4 characters
3626 %X hex number using upper case letters
3627 %o octal number
Bram Moolenaar98692072006-02-04 00:57:42 +00003628 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003629
3630 Conversion specifications start with '%' and end with the
3631 conversion type. All other characters are copied unchanged to
3632 the result.
3633
3634 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003635 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003636
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003637 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003638
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003639 flags
3640 Zero or more of the following flags:
3641
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003642 # The value should be converted to an "alternate
3643 form". For c, d, and s conversions, this option
3644 has no effect. For o conversions, the precision
3645 of the number is increased to force the first
3646 character of the output string to a zero (except
3647 if a zero value is printed with an explicit
3648 precision of zero).
3649 For x and X conversions, a non-zero result has
3650 the string "0x" (or "0X" for X conversions)
3651 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003652
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003653 0 (zero) Zero padding. For all conversions the converted
3654 value is padded on the left with zeros rather
3655 than blanks. If a precision is given with a
3656 numeric conversion (d, o, x, and X), the 0 flag
3657 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003658
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003659 - A negative field width flag; the converted value
3660 is to be left adjusted on the field boundary.
3661 The converted value is padded on the right with
3662 blanks, rather than on the left with blanks or
3663 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003664
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003665 ' ' (space) A blank should be left before a positive
3666 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003667
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003668 + A sign must always be placed before a number
3669 produced by a signed conversion. A + overrides
3670 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003671
3672 field-width
3673 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00003674 field width. If the converted value has fewer bytes
3675 than the field width, it will be padded with spaces on
3676 the left (or right, if the left-adjustment flag has
3677 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003678
3679 .precision
3680 An optional precision, in the form of a period '.'
3681 followed by an optional digit string. If the digit
3682 string is omitted, the precision is taken as zero.
3683 This gives the minimum number of digits to appear for
3684 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00003685 bytes to be printed from a string for s conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003686
3687 type
3688 A character that specifies the type of conversion to
3689 be applied, see below.
3690
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003691 A field width or precision, or both, may be indicated by an
3692 asterisk '*' instead of a digit string. In this case, a
3693 Number argument supplies the field width or precision. A
3694 negative field width is treated as a left adjustment flag
3695 followed by a positive field width; a negative precision is
3696 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003697 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003698< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003699 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003700
3701 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003702
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003703 doxX The Number argument is converted to signed decimal
3704 (d), unsigned octal (o), or unsigned hexadecimal (x
3705 and X) notation. The letters "abcdef" are used for
3706 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003707 conversions.
3708 The precision, if any, gives the minimum number of
3709 digits that must appear; if the converted value
3710 requires fewer digits, it is padded on the left with
3711 zeros.
3712 In no case does a non-existent or small field width
3713 cause truncation of a numeric field; if the result of
3714 a conversion is wider than the field width, the field
3715 is expanded to contain the conversion result.
3716
3717 c The Number argument is converted to a byte, and the
3718 resulting character is written.
3719
3720 s The text of the String argument is used. If a
3721 precision is specified, no more bytes than the number
3722 specified are used.
3723
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003724 % A '%' is written. No argument is converted. The
3725 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003726
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003727 Each argument can be Number or String and is converted
3728 automatically to fit the conversion specifier. Any other
3729 argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003730
Bram Moolenaar83bab712005-08-01 21:58:57 +00003731 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003732 The number of {exprN} arguments must exactly match the number
3733 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003734 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003735
3736
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003737pumvisible() *pumvisible()*
3738 Returns non-zero when the popup menu is visible, zero
3739 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003740 This can be used to avoid some things that would remove the
3741 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003742
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003743 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003744range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003745 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00003746 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3747 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3748 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3749 {max}] (increasing {expr} with {stride} each time, not
3750 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00003751 When the maximum is one before the start the result is an
3752 empty list. When the maximum is more than one before the
3753 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003754 Examples: >
3755 range(4) " [0, 1, 2, 3]
3756 range(2, 4) " [2, 3, 4]
3757 range(2, 9, 3) " [2, 5, 8]
3758 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00003759 range(0) " []
3760 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00003761<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003762 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003763readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003764 Read file {fname} and return a |List|, each line of the file
3765 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003766 separated with CR will result in a single long line (unless a
3767 NL appears somewhere).
3768 When {binary} is equal to "b" binary mode is used:
3769 - When the last line ends in a NL an extra empty list item is
3770 added.
3771 - No CR characters are removed.
3772 Otherwise:
3773 - CR characters that appear before a NL are removed.
3774 - Whether the last line ends in a NL or not does not matter.
3775 All NUL characters are replaced with a NL character.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003776 When {max} is given this specifies the maximum number of lines
3777 to be read. Useful if you only want to check the first ten
3778 lines of a file: >
3779 :for line in readfile(fname, '', 10)
3780 : if line =~ 'Date' | echo line | endif
3781 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00003782< When {max} is negative -{max} lines from the end of the file
3783 are returned, or as many as there are.
3784 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003785 Note that without {max} the whole file is read into memory.
3786 Also note that there is no recognition of encoding. Read a
3787 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003788 When the file can't be opened an error message is given and
3789 the result is an empty list.
3790 Also see |writefile()|.
3791
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003792reltime([{start} [, {end}]]) *reltime()*
3793 Return an item that represents a time value. The format of
3794 the item depends on the system. It can be passed to
3795 |reltimestr()| to convert it to a string.
3796 Without an argument it returns the current time.
3797 With one argument is returns the time passed since the time
3798 specified in the argument.
3799 With two arguments it returns the time passed betweein {start}
3800 and {end}.
3801 The {start} and {end} arguments must be values returned by
3802 reltime().
3803 {only available when compiled with the +reltime feature}
3804
3805reltimestr({time}) *reltimestr()*
3806 Return a String that represents the time value of {time}.
3807 This is the number of seconds, a dot and the number of
3808 microseconds. Example: >
3809 let start = reltime()
3810 call MyFunction()
3811 echo reltimestr(reltime(start))
3812< Note that overhead for the commands will be added to the time.
3813 The accuracy depends on the system.
3814 Also see |profiling|.
3815 {only available when compiled with the +reltime feature}
3816
Bram Moolenaar071d4272004-06-13 20:20:40 +00003817 *remote_expr()* *E449*
3818remote_expr({server}, {string} [, {idvar}])
3819 Send the {string} to {server}. The string is sent as an
3820 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00003821 The result must be a String or a |List|. A |List| is turned
3822 into a String by joining the items with a line break in
3823 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00003824 If {idvar} is present, it is taken as the name of a
3825 variable and a {serverid} for later use with
3826 remote_read() is stored there.
3827 See also |clientserver| |RemoteReply|.
3828 This function is not available in the |sandbox|.
3829 {only available when compiled with the |+clientserver| feature}
3830 Note: Any errors will cause a local error message to be issued
3831 and the result will be the empty string.
3832 Examples: >
3833 :echo remote_expr("gvim", "2+2")
3834 :echo remote_expr("gvim1", "b:current_syntax")
3835<
3836
3837remote_foreground({server}) *remote_foreground()*
3838 Move the Vim server with the name {server} to the foreground.
3839 This works like: >
3840 remote_expr({server}, "foreground()")
3841< Except that on Win32 systems the client does the work, to work
3842 around the problem that the OS doesn't always allow the server
3843 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00003844 Note: This does not restore the window if it was minimized,
3845 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003846 This function is not available in the |sandbox|.
3847 {only in the Win32, Athena, Motif and GTK GUI versions and the
3848 Win32 console version}
3849
3850
3851remote_peek({serverid} [, {retvar}]) *remote_peek()*
3852 Returns a positive number if there are available strings
3853 from {serverid}. Copies any reply string into the variable
3854 {retvar} if specified. {retvar} must be a string with the
3855 name of a variable.
3856 Returns zero if none are available.
3857 Returns -1 if something is wrong.
3858 See also |clientserver|.
3859 This function is not available in the |sandbox|.
3860 {only available when compiled with the |+clientserver| feature}
3861 Examples: >
3862 :let repl = ""
3863 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3864
3865remote_read({serverid}) *remote_read()*
3866 Return the oldest available reply from {serverid} and consume
3867 it. It blocks until a reply is available.
3868 See also |clientserver|.
3869 This function is not available in the |sandbox|.
3870 {only available when compiled with the |+clientserver| feature}
3871 Example: >
3872 :echo remote_read(id)
3873<
3874 *remote_send()* *E241*
3875remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003876 Send the {string} to {server}. The string is sent as input
3877 keys and the function returns immediately. At the Vim server
3878 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003879 If {idvar} is present, it is taken as the name of a variable
3880 and a {serverid} for later use with remote_read() is stored
3881 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003882 See also |clientserver| |RemoteReply|.
3883 This function is not available in the |sandbox|.
3884 {only available when compiled with the |+clientserver| feature}
3885 Note: Any errors will be reported in the server and may mess
3886 up the display.
3887 Examples: >
3888 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3889 \ remote_read(serverid)
3890
3891 :autocmd NONE RemoteReply *
3892 \ echo remote_read(expand("<amatch>"))
3893 :echo remote_send("gvim", ":sleep 10 | echo ".
3894 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003895<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003896remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003897 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003898 return it.
3899 With {end}: Remove items from {idx} to {end} (inclusive) and
3900 return a list with these items. When {idx} points to the same
3901 item as {end} a list with one item is returned. When {end}
3902 points to an item before {idx} this is an error.
3903 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003904 Example: >
3905 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003906 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00003907remove({dict}, {key})
3908 Remove the entry from {dict} with key {key}. Example: >
3909 :echo "removed " . remove(dict, "one")
3910< If there is no {key} in {dict} this is an error.
3911
3912 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003913
Bram Moolenaar071d4272004-06-13 20:20:40 +00003914rename({from}, {to}) *rename()*
3915 Rename the file by the name {from} to the name {to}. This
3916 should also work to move files across file systems. The
3917 result is a Number, which is 0 if the file was renamed
3918 successfully, and non-zero when the renaming failed.
3919 This function is not available in the |sandbox|.
3920
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003921repeat({expr}, {count}) *repeat()*
3922 Repeat {expr} {count} times and return the concatenated
3923 result. Example: >
3924 :let seperator = repeat('-', 80)
3925< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003926 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003927 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003928 :let longlist = repeat(['a', 'b'], 3)
3929< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003930
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003931
Bram Moolenaar071d4272004-06-13 20:20:40 +00003932resolve({filename}) *resolve()* *E655*
3933 On MS-Windows, when {filename} is a shortcut (a .lnk file),
3934 returns the path the shortcut points to in a simplified form.
3935 On Unix, repeat resolving symbolic links in all path
3936 components of {filename} and return the simplified result.
3937 To cope with link cycles, resolving of symbolic links is
3938 stopped after 100 iterations.
3939 On other systems, return the simplified {filename}.
3940 The simplification step is done as by |simplify()|.
3941 resolve() keeps a leading path component specifying the
3942 current directory (provided the result is still a relative
3943 path name) and also keeps a trailing path separator.
3944
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003945 *reverse()*
3946reverse({list}) Reverse the order of items in {list} in-place. Returns
3947 {list}.
3948 If you want a list to remain unmodified make a copy first: >
3949 :let revlist = reverse(copy(mylist))
3950
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003951search({pattern} [, {flags} [, {stopline}]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003952 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003953 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003954
Bram Moolenaar071d4272004-06-13 20:20:40 +00003955 {flags} is a String, which can contain these character flags:
3956 'b' search backward instead of forward
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003957 'c' accept a match at the cursor position
3958 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003959 'n' do Not move the cursor
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003960 'p' return number of matching sub-pattern (see below)
3961 's' set the ' mark at the previous location of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003962 'w' wrap around the end of the file
3963 'W' don't wrap around the end of the file
3964 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
3965
Bram Moolenaar02743632005-07-25 20:42:36 +00003966 If the 's' flag is supplied, the ' mark is set, only if the
3967 cursor is moved. The 's' flag cannot be combined with the 'n'
3968 flag.
3969
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003970 When the {stopline} argument is given then the search stops
3971 after searching this line. This is useful to restrict the
3972 search to a range of lines. Examples: >
3973 let match = search('(', 'b', line("w0"))
3974 let end = search('END', '', line("w$"))
3975< When {stopline} is used and it is not zero this also implies
3976 that the search does not wrap around the end of the file.
3977
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003978 If there is no match a 0 is returned and the cursor doesn't
3979 move. No error message is given.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00003980 When a match has been found its line number is returned.
3981 *search()-sub-match*
3982 With the 'p' flag the returned value is one more than the
3983 first sub-match in \(\). One if none of them matched but the
3984 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003985 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003986
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003987 The cursor will be positioned at the match, unless the 'n'
3988 flag is used.
3989
Bram Moolenaar071d4272004-06-13 20:20:40 +00003990 Example (goes over all files in the argument list): >
3991 :let n = 1
3992 :while n <= argc() " loop over all files in arglist
3993 : exe "argument " . n
3994 : " start at the last char in the file and wrap for the
3995 : " first search to find match at start of file
3996 : normal G$
3997 : let flags = "w"
3998 : while search("foo", flags) > 0
3999 : s/foo/bar/g
4000 : let flags = "W"
4001 : endwhile
4002 : update " write the file if modified
4003 : let n = n + 1
4004 :endwhile
4005<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004006 Example for using some flags: >
4007 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4008< This will search for the keywords "if", "else", and "endif"
4009 under or after the cursor. Because of the 'p' flag, it
4010 returns 1, 2, or 3 depending on which keyword is found, or 0
4011 if the search fails. With the cursor on the first word of the
4012 line:
4013 if (foo == 0) | let foo = foo + 1 | endif ~
4014 the function returns 1. Without the 'c' flag, the function
4015 finds the "endif" and returns 3. The same thing happens
4016 without the 'e' flag if the cursor is on the "f" of "if".
4017 The 'n' flag tells the function not to move the cursor.
4018
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004019
Bram Moolenaarf75a9632005-09-13 21:20:47 +00004020searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4021 Search for the declaration of {name}.
4022
4023 With a non-zero {global} argument it works like |gD|, find
4024 first match in the file. Otherwise it works like |gd|, find
4025 first match in the function.
4026
4027 With a non-zero {thisblock} argument matches in a {} block
4028 that ends before the cursor position are ignored. Avoids
4029 finding variable declarations only valid in another scope.
4030
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004031 Moves the cursor to the found match.
4032 Returns zero for success, non-zero for failure.
4033 Example: >
4034 if searchdecl('myvar') == 0
4035 echo getline('.')
4036 endif
4037<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004038 *searchpair()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004039searchpair({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004040 Search for the match of a nested start-end pair. This can be
4041 used to find the "endif" that matches an "if", while other
4042 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004043 The search starts at the cursor. The default is to search
4044 forward, include 'b' in {flags} to search backward.
4045 If a match is found, the cursor is positioned at it and the
4046 line number is returned. If no match is found 0 or -1 is
4047 returned and the cursor doesn't move. No error message is
4048 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004049
4050 {start}, {middle} and {end} are patterns, see |pattern|. They
4051 must not contain \( \) pairs. Use of \%( \) is allowed. When
4052 {middle} is not empty, it is found when searching from either
4053 direction, but only when not in a nested start-end pair. A
4054 typical use is: >
4055 searchpair('\<if\>', '\<else\>', '\<endif\>')
4056< By leaving {middle} empty the "else" is skipped.
4057
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004058 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4059 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004060 'r' Repeat until no more matches found; will find the
4061 outer pair
4062 'm' return number of Matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004063 the match; will be > 1 when 'r' is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004064
4065 When a match for {start}, {middle} or {end} is found, the
4066 {skip} expression is evaluated with the cursor positioned on
4067 the start of the match. It should return non-zero if this
4068 match is to be skipped. E.g., because it is inside a comment
4069 or a string.
4070 When {skip} is omitted or empty, every match is accepted.
4071 When evaluating {skip} causes an error the search is aborted
4072 and -1 returned.
4073
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004074 For {stopline} see |search()|.
4075
Bram Moolenaar071d4272004-06-13 20:20:40 +00004076 The value of 'ignorecase' is used. 'magic' is ignored, the
4077 patterns are used like it's on.
4078
4079 The search starts exactly at the cursor. A match with
4080 {start}, {middle} or {end} at the next character, in the
4081 direction of searching, is the first one found. Example: >
4082 if 1
4083 if 2
4084 endif 2
4085 endif 1
4086< When starting at the "if 2", with the cursor on the "i", and
4087 searching forwards, the "endif 2" is found. When starting on
4088 the character just before the "if 2", the "endif 1" will be
4089 found. That's because the "if 2" will be found first, and
4090 then this is considered to be a nested if/endif from "if 2" to
4091 "endif 2".
4092 When searching backwards and {end} is more than one character,
4093 it may be useful to put "\zs" at the end of the pattern, so
4094 that when the cursor is inside a match with the end it finds
4095 the matching start.
4096
4097 Example, to find the "endif" command in a Vim script: >
4098
4099 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4100 \ 'getline(".") =~ "^\\s*\""')
4101
4102< The cursor must be at or after the "if" for which a match is
4103 to be found. Note that single-quote strings are used to avoid
4104 having to double the backslashes. The skip expression only
4105 catches comments at the start of a line, not after a command.
4106 Also, a word "en" or "if" halfway a line is considered a
4107 match.
4108 Another example, to search for the matching "{" of a "}": >
4109
4110 :echo searchpair('{', '', '}', 'bW')
4111
4112< This works when the cursor is at or before the "}" for which a
4113 match is to be found. To reject matches that syntax
4114 highlighting recognized as strings: >
4115
4116 :echo searchpair('{', '', '}', 'bW',
4117 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4118<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004119 *searchpairpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004120searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004121 Same as searchpair(), but returns a |List| with the line and
4122 column position of the match. The first element of the |List|
4123 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004124 the column position of the match. If no match is found,
4125 returns [0, 0].
4126>
4127 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4128<
4129 See |match-parens| for a bigger and more useful example.
4130
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004131searchpos({pattern} [, {flags} [, {stopline}]]) *searchpos()*
4132 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004133 column position of the match. The first element of the |List|
4134 is the line number and the second element is the byte index of
4135 the column position of the match. If no match is found,
4136 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004137 Example: >
4138 :let [lnum, col] = searchpos('mypattern', 'n')
4139
4140< When the 'p' flag is given then there is an extra item with
4141 the sub-pattern match number |search()-sub-match|. Example: >
4142 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4143< In this example "submatch" is 2 when a lowercase letter is
4144 found |/\l|, 3 when an uppercase letter is found |/\u|.
4145
Bram Moolenaar071d4272004-06-13 20:20:40 +00004146server2client( {clientid}, {string}) *server2client()*
4147 Send a reply string to {clientid}. The most recent {clientid}
4148 that sent a string can be retrieved with expand("<client>").
4149 {only available when compiled with the |+clientserver| feature}
4150 Note:
4151 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004152 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004153 before calling any commands that waits for input.
4154 See also |clientserver|.
4155 Example: >
4156 :echo server2client(expand("<client>"), "HELLO")
4157<
4158serverlist() *serverlist()*
4159 Return a list of available server names, one per line.
4160 When there are no servers or the information is not available
4161 an empty string is returned. See also |clientserver|.
4162 {only available when compiled with the |+clientserver| feature}
4163 Example: >
4164 :echo serverlist()
4165<
4166setbufvar({expr}, {varname}, {val}) *setbufvar()*
4167 Set option or local variable {varname} in buffer {expr} to
4168 {val}.
4169 This also works for a global or local window option, but it
4170 doesn't work for a global or local window variable.
4171 For a local window option the global value is unchanged.
4172 For the use of {expr}, see |bufname()| above.
4173 Note that the variable name without "b:" must be used.
4174 Examples: >
4175 :call setbufvar(1, "&mod", 1)
4176 :call setbufvar("todo", "myvar", "foobar")
4177< This function is not available in the |sandbox|.
4178
4179setcmdpos({pos}) *setcmdpos()*
4180 Set the cursor position in the command line to byte position
4181 {pos}. The first position is 1.
4182 Use |getcmdpos()| to obtain the current position.
4183 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00004184 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
4185 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
4186 set after the command line is set to the expression. For
4187 |c_CTRL-R_=| it is set after evaluating the expression but
4188 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004189 When the number is too big the cursor is put at the end of the
4190 line. A number smaller than one has undefined results.
4191 Returns 0 when successful, 1 when not editing the command
4192 line.
4193
4194setline({lnum}, {line}) *setline()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004195 Set line {lnum} of the current buffer to {line}.
4196 {lnum} is used like with |getline()|.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004197 When {lnum} is just below the last line the {line} will be
4198 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004199 If this succeeds, 0 is returned. If this fails (most likely
4200 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004201 :call setline(5, strftime("%c"))
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004202< When {line} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004203 will be set to the items in the list. Example: >
4204 :call setline(5, ['aaa', 'bbb', 'ccc'])
4205< This is equivalent to: >
4206 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
4207 : call setline(n, l)
4208 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004209< Note: The '[ and '] marks are not set.
4210
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004211setloclist({nr}, {list} [, {action}]) *setloclist()*
4212 Create or replace or add to the location list for window {nr}.
4213 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00004214 list window, the displayed location list is modified. For an
4215 invalid window number {nr}, -1 is returned.
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004216 Otherwise, same as setqflist().
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004217
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004218 *setpos()*
4219setpos({expr}, {list})
4220 Set the position for {expr}. Possible values:
4221 . the cursor
4222 'x mark x
4223
4224 {list} must be a |List| with four numbers:
4225 [bufnum, lnum, col, off]
4226
4227 "bufnum" is the buffer number. Zero can be used for the
4228 current buffer. Setting the cursor is only possible for
4229 the current buffer. To set a mark in another buffer you can
4230 use the |bufnr()| function to turn a file name into a buffer
4231 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00004232 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004233
4234 "lnum" and "col" are the position in the buffer. The first
4235 column is 1. Use a zero "lnum" to delete a mark.
4236
4237 The "off" number is only used when 'virtualedit' is set. Then
4238 it is the offset in screen columns from the start of the
4239 character. E.g., a position within a Tab or after the last
4240 character.
4241
4242 Also see |getpos()|
4243
4244
Bram Moolenaar35c54e52005-05-20 21:25:31 +00004245setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004246 Create or replace or add to the quickfix list using the items
4247 in {list}. Each item in {list} is a dictionary.
4248 Non-dictionary items in {list} are ignored. Each dictionary
4249 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004250
4251 filename name of a file
4252 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004253 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00004254 col column number
4255 vcol when non-zero: "col" is visual column
4256 when zero: "col" is byte index
4257 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004258 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00004259 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004260
Bram Moolenaar582fd852005-03-28 20:58:01 +00004261 The "col", "vcol", "nr", "type" and "text" entries are
4262 optional. Either "lnum" or "pattern" entry can be used to
4263 locate a matching error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004264 If the "filename" entry is not present or neither the "lnum"
4265 or "pattern" entries are present, then the item will not be
4266 handled as an error line.
4267 If both "pattern" and "lnum" are present then "pattern" will
4268 be used.
4269
Bram Moolenaar35c54e52005-05-20 21:25:31 +00004270 If {action} is set to 'a', then the items from {list} are
4271 added to the existing quickfix list. If there is no existing
4272 list, then a new list is created. If {action} is set to 'r',
4273 then the items from the current quickfix list are replaced
4274 with the items from {list}. If {action} is not present or is
4275 set to ' ', then a new list is created.
4276
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004277 Returns zero for success, -1 for failure.
4278
4279 This function can be used to create a quickfix list
4280 independent of the 'errorformat' setting. Use a command like
4281 ":cc 1" to jump to the first position.
4282
4283
Bram Moolenaar071d4272004-06-13 20:20:40 +00004284 *setreg()*
4285setreg({regname}, {value} [,{options}])
4286 Set the register {regname} to {value}.
4287 If {options} contains "a" or {regname} is upper case,
4288 then the value is appended.
4289 {options} can also contains a register type specification:
4290 "c" or "v" |characterwise| mode
4291 "l" or "V" |linewise| mode
4292 "b" or "<CTRL-V>" |blockwise-visual| mode
4293 If a number immediately follows "b" or "<CTRL-V>" then this is
4294 used as the width of the selection - if it is not specified
4295 then the width of the block is set to the number of characters
4296 in the longest line (counting a <TAB> as 1 character).
4297
4298 If {options} contains no register settings, then the default
4299 is to use character mode unless {value} ends in a <NL>.
4300 Setting the '=' register is not possible.
4301 Returns zero for success, non-zero for failure.
4302
4303 Examples: >
4304 :call setreg(v:register, @*)
4305 :call setreg('*', @%, 'ac')
4306 :call setreg('a', "1\n2\n3", 'b5')
4307
4308< This example shows using the functions to save and restore a
4309 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004310 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004311 :let var_amode = getregtype('a')
4312 ....
4313 :call setreg('a', var_a, var_amode)
4314
4315< You can also change the type of a register by appending
4316 nothing: >
4317 :call setreg('a', '', 'al')
4318
4319setwinvar({nr}, {varname}, {val}) *setwinvar()*
4320 Set option or local variable {varname} in window {nr} to
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00004321 {val}. When {nr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004322 This also works for a global or local buffer option, but it
4323 doesn't work for a global or local buffer variable.
4324 For a local buffer option the global value is unchanged.
4325 Note that the variable name without "w:" must be used.
4326 Examples: >
4327 :call setwinvar(1, "&list", 0)
4328 :call setwinvar(2, "myvar", "foobar")
4329< This function is not available in the |sandbox|.
4330
4331simplify({filename}) *simplify()*
4332 Simplify the file name as much as possible without changing
4333 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
4334 Unix) are not resolved. If the first path component in
4335 {filename} designates the current directory, this will be
4336 valid for the result as well. A trailing path separator is
4337 not removed either.
4338 Example: >
4339 simplify("./dir/.././/file/") == "./file/"
4340< Note: The combination "dir/.." is only removed if "dir" is
4341 a searchable directory or does not exist. On Unix, it is also
4342 removed when "dir" is a symbolic link within the same
4343 directory. In order to resolve all the involved symbolic
4344 links before simplifying the path name, use |resolve()|.
4345
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004346
Bram Moolenaar13065c42005-01-08 16:08:21 +00004347sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004348 Sort the items in {list} in-place. Returns {list}. If you
4349 want a list to remain unmodified make a copy first: >
4350 :let sortedlist = sort(copy(mylist))
4351< Uses the string representation of each item to sort on.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004352 Numbers sort after Strings, |Lists| after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004353 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004354 When {func} is given and it is one then case is ignored.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004355 When {func} is a |Funcref| or a function name, this function
4356 is called to compare items. The function is invoked with two
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004357 items as argument and must return zero if they are equal, 1 if
4358 the first one sorts after the second one, -1 if the first one
4359 sorts before the second one. Example: >
4360 func MyCompare(i1, i2)
4361 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
4362 endfunc
4363 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004364<
4365
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004366 *soundfold()*
4367soundfold({word})
4368 Return the sound-folded equivalent of {word}. Uses the first
4369 language in 'spellang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004370 soundfolding. 'spell' must be set. When no sound folding is
4371 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004372 This can be used for making spelling suggestions. Note that
4373 the method can be quite slow.
4374
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004375 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00004376spellbadword([{sentence}])
4377 Without argument: The result is the badly spelled word under
4378 or after the cursor. The cursor is moved to the start of the
4379 bad word. When no bad word is found in the cursor line the
4380 result is an empty string and the cursor doesn't move.
4381
4382 With argument: The result is the first word in {sentence} that
4383 is badly spelled. If there are no spelling mistakes the
4384 result is an empty string.
4385
4386 The return value is a list with two items:
4387 - The badly spelled word or an empty string.
4388 - The type of the spelling error:
4389 "bad" spelling mistake
4390 "rare" rare word
4391 "local" word only valid in another region
4392 "caps" word should start with Capital
4393 Example: >
4394 echo spellbadword("the quik brown fox")
4395< ['quik', 'bad'] ~
4396
4397 The spelling information for the current window is used. The
4398 'spell' option must be set and the value of 'spelllang' is
4399 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004400
4401 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004402spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004403 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004404 When {max} is given up to this number of suggestions are
4405 returned. Otherwise up to 25 suggestions are returned.
4406
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004407 When the {capital} argument is given and it's non-zero only
4408 suggestions with a leading capital will be given. Use this
4409 after a match with 'spellcapcheck'.
4410
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004411 {word} can be a badly spelled word followed by other text.
4412 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00004413 suggestions also include the following text, thus you can
4414 replace a line.
4415
4416 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004417 returned. {word} itself is not included in the suggestions,
4418 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004419
4420 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004421 'spell' option must be set and the values of 'spelllang' and
4422 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004423
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004424
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004425split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004426 Make a |List| out of {expr}. When {pattern} is omitted or
4427 empty each white-separated sequence of characters becomes an
4428 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004429 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004430 removing the matched characters.
4431 When the first or last item is empty it is omitted, unless the
4432 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00004433 Other empty items are kept when {pattern} matches at least one
4434 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004435 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004436 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004437< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004438 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00004439< If you want to keep the separator you can also use '\zs': >
4440 :echo split('abc:def:ghi', ':\zs')
4441< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004442 Splitting a table where the first element can be empty: >
4443 :let items = split(line, ':', 1)
4444< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004445
4446
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004447str2nr( {expr} [, {base}]) *str2nr()*
4448 Convert string {expr} to a number.
4449 {base} is the conversion base, it can be 8, 10 or 16.
4450 When {base} is omitted base 10 is used. This also means that
4451 a leading zero doesn't cause octal conversion to be used, as
4452 with the default String to Number conversion.
4453 When {base} is 16 a leading "0x" or "0X" is ignored. With a
4454 different base the result will be zero.
4455 Text after the number is silently ignored.
4456
4457
Bram Moolenaar071d4272004-06-13 20:20:40 +00004458strftime({format} [, {time}]) *strftime()*
4459 The result is a String, which is a formatted date and time, as
4460 specified by the {format} string. The given {time} is used,
4461 or the current time if no time is given. The accepted
4462 {format} depends on your system, thus this is not portable!
4463 See the manual page of the C function strftime() for the
4464 format. The maximum length of the result is 80 characters.
4465 See also |localtime()| and |getftime()|.
4466 The language can be changed with the |:language| command.
4467 Examples: >
4468 :echo strftime("%c") Sun Apr 27 11:49:23 1997
4469 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
4470 :echo strftime("%y%m%d %T") 970427 11:53:55
4471 :echo strftime("%H:%M") 11:55
4472 :echo strftime("%c", getftime("file.c"))
4473 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004474< Not available on all systems. To check use: >
4475 :if exists("*strftime")
4476
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004477stridx({haystack}, {needle} [, {start}]) *stridx()*
4478 The result is a Number, which gives the byte index in
4479 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004480 If {start} is specified, the search starts at index {start}.
4481 This can be used to find a second match: >
4482 :let comma1 = stridx(line, ",")
4483 :let comma2 = stridx(line, ",", comma1 + 1)
4484< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004485 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004486 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004487 See also |strridx()|.
4488 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004489 :echo stridx("An Example", "Example") 3
4490 :echo stridx("Starting point", "Start") 0
4491 :echo stridx("Starting point", "start") -1
Bram Moolenaar05159a02005-02-26 23:04:13 +00004492< *strstr()* *strchr()*
4493 stridx() works similar to the C function strstr(). When used
4494 with a single character it works similar to strchr().
4495
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004496 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004497string({expr}) Return {expr} converted to a String. If {expr} is a Number,
4498 String or a composition of them, then the result can be parsed
4499 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004500 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00004501 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004502 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00004503 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004504 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00004505 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00004506 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004507
Bram Moolenaar071d4272004-06-13 20:20:40 +00004508 *strlen()*
4509strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00004510 {expr} in bytes.
4511 If you want to count the number of multi-byte characters (not
4512 counting composing characters) use something like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004513
4514 :let len = strlen(substitute(str, ".", "x", "g"))
Bram Moolenaare344bea2005-09-01 20:46:49 +00004515<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004516 If the argument is a Number it is first converted to a String.
4517 For other types an error is given.
4518 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004519
4520strpart({src}, {start}[, {len}]) *strpart()*
4521 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00004522 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004523 When non-existing bytes are included, this doesn't result in
4524 an error, the bytes are simply omitted.
4525 If {len} is missing, the copy continues from {start} till the
4526 end of the {src}. >
4527 strpart("abcdefg", 3, 2) == "de"
4528 strpart("abcdefg", -2, 4) == "ab"
4529 strpart("abcdefg", 5, 4) == "fg"
4530 strpart("abcdefg", 3) == "defg"
4531< Note: To get the first character, {start} must be 0. For
4532 example, to get three bytes under and after the cursor: >
4533 strpart(getline(line(".")), col(".") - 1, 3)
4534<
Bram Moolenaar677ee682005-01-27 14:41:15 +00004535strridx({haystack}, {needle} [, {start}]) *strridx()*
4536 The result is a Number, which gives the byte index in
4537 {haystack} of the last occurrence of the String {needle}.
4538 When {start} is specified, matches beyond this index are
4539 ignored. This can be used to find a match before a previous
4540 match: >
4541 :let lastcomma = strridx(line, ",")
4542 :let comma2 = strridx(line, ",", lastcomma - 1)
4543< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004544 For pattern searches use |match()|.
4545 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00004546 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004547 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004548 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaar05159a02005-02-26 23:04:13 +00004549< *strrchr()*
4550 When used with a single character it works similar to the C
4551 function strrchr().
4552
Bram Moolenaar071d4272004-06-13 20:20:40 +00004553strtrans({expr}) *strtrans()*
4554 The result is a String, which is {expr} with all unprintable
4555 characters translated into printable characters |'isprint'|.
4556 Like they are shown in a window. Example: >
4557 echo strtrans(@a)
4558< This displays a newline in register a as "^@" instead of
4559 starting a new line.
4560
4561submatch({nr}) *submatch()*
4562 Only for an expression in a |:substitute| command. Returns
4563 the {nr}'th submatch of the matched text. When {nr} is 0
4564 the whole matched text is returned.
4565 Example: >
4566 :s/\d\+/\=submatch(0) + 1/
4567< This finds the first number in the line and adds one to it.
4568 A line break is included as a newline character.
4569
4570substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
4571 The result is a String, which is a copy of {expr}, in which
4572 the first match of {pat} is replaced with {sub}. This works
4573 like the ":substitute" command (without any flags). But the
4574 matching with {pat} is always done like the 'magic' option is
4575 set and 'cpoptions' is empty (to make scripts portable).
4576 See |string-match| for how {pat} is used.
4577 And a "~" in {sub} is not replaced with the previous {sub}.
4578 Note that some codes in {sub} have a special meaning
4579 |sub-replace-special|. For example, to replace something with
4580 "\n" (two characters), use "\\\\n" or '\\n'.
4581 When {pat} does not match in {expr}, {expr} is returned
4582 unmodified.
4583 When {flags} is "g", all matches of {pat} in {expr} are
4584 replaced. Otherwise {flags} should be "".
4585 Example: >
4586 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
4587< This removes the last component of the 'path' option. >
4588 :echo substitute("testing", ".*", "\\U\\0", "")
4589< results in "TESTING".
4590
Bram Moolenaar47136d72004-10-12 20:02:24 +00004591synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004592 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00004593 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004594 The syntax ID can be used with |synIDattr()| and
4595 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004596
Bram Moolenaar47136d72004-10-12 20:02:24 +00004597 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004598 line. 'synmaxcol' applies, in a longer line zero is returned.
4599
Bram Moolenaar071d4272004-06-13 20:20:40 +00004600 When {trans} is non-zero, transparent items are reduced to the
4601 item that they reveal. This is useful when wanting to know
4602 the effective color. When {trans} is zero, the transparent
4603 item is returned. This is useful when wanting to know which
4604 syntax item is effective (e.g. inside parens).
4605 Warning: This function can be very slow. Best speed is
4606 obtained by going through the file in forward direction.
4607
4608 Example (echoes the name of the syntax item under the cursor): >
4609 :echo synIDattr(synID(line("."), col("."), 1), "name")
4610<
4611synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
4612 The result is a String, which is the {what} attribute of
4613 syntax ID {synID}. This can be used to obtain information
4614 about a syntax item.
4615 {mode} can be "gui", "cterm" or "term", to get the attributes
4616 for that mode. When {mode} is omitted, or an invalid value is
4617 used, the attributes for the currently active highlighting are
4618 used (GUI, cterm or term).
4619 Use synIDtrans() to follow linked highlight groups.
4620 {what} result
4621 "name" the name of the syntax item
4622 "fg" foreground color (GUI: color name used to set
4623 the color, cterm: color number as a string,
4624 term: empty string)
4625 "bg" background color (like "fg")
4626 "fg#" like "fg", but for the GUI and the GUI is
4627 running the name in "#RRGGBB" form
4628 "bg#" like "fg#" for "bg"
4629 "bold" "1" if bold
4630 "italic" "1" if italic
4631 "reverse" "1" if reverse
4632 "inverse" "1" if inverse (= reverse)
4633 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004634 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00004635
4636 Example (echoes the color of the syntax item under the
4637 cursor): >
4638 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
4639<
4640synIDtrans({synID}) *synIDtrans()*
4641 The result is a Number, which is the translated syntax ID of
4642 {synID}. This is the syntax group ID of what is being used to
4643 highlight the character. Highlight links given with
4644 ":highlight link" are followed.
4645
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004646system({expr} [, {input}]) *system()* *E677*
4647 Get the output of the shell command {expr}.
4648 When {input} is given, this string is written to a file and
4649 passed as stdin to the command. The string is written as-is,
4650 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00004651 yourself. Pipes are not used.
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004652 Note: newlines in {expr} may cause the command to fail. The
4653 characters in 'shellquote' and 'shellxquote' may also cause
4654 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004655 This is not to be used for interactive commands.
4656 The result is a String. Example: >
4657
4658 :let files = system("ls")
4659
4660< To make the result more system-independent, the shell output
4661 is filtered to replace <CR> with <NL> for Macintosh, and
4662 <CR><NL> with <NL> for DOS-like systems.
4663 The command executed is constructed using several options:
4664 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
4665 ({tmp} is an automatically generated file name).
4666 For Unix and OS/2 braces are put around {expr} to allow for
4667 concatenated commands.
4668
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004669 The command will be executed in "cooked" mode, so that a
4670 CTRL-C will interrupt the command (on Unix at least).
4671
Bram Moolenaar071d4272004-06-13 20:20:40 +00004672 The resulting error code can be found in |v:shell_error|.
4673 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00004674
4675 Note that any wrong value in the options mentioned above may
4676 make the function fail. It has also been reported to fail
4677 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004678 Unlike ":!cmd" there is no automatic check for changed files.
4679 Use |:checktime| to force a check.
4680
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004681
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004682tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004683 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004684 buffer associated with each window in the current tab page.
4685 {arg} specifies the number of tab page to be used. When
4686 omitted the current tab page is used.
4687 When {arg} is invalid the number zero is returned.
4688 To get a list of all buffers in all tabs use this: >
4689 tablist = []
4690 for i in range(tabpagenr('$'))
4691 call extend(tablist, tabpagebuflist(i + 1))
4692 endfor
4693< Note that a buffer may appear in more than one window.
4694
4695
4696tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00004697 The result is a Number, which is the number of the current
4698 tab page. The first tab page has number 1.
4699 When the optional argument is "$", the number of the last tab
4700 page is returned (the tab page count).
4701 The number can be used with the |:tab| command.
4702
4703
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004704tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
4705 Like |winnr()| but for tab page {arg}.
4706 {tabarg} specifies the number of tab page to be used.
4707 {arg} is used like with |winnr()|:
4708 - When omitted the current window number is returned. This is
4709 the window which will be used when going to this tab page.
4710 - When "$" the number of windows is returned.
4711 - When "#" the previous window nr is returned.
4712 Useful examples: >
4713 tabpagewinnr(1) " current window of tab page 1
4714 tabpagewinnr(4, '$') " number of windows in tab page 4
4715< When {tabarg} is invalid zero is returned.
4716
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00004717 *tagfiles()*
4718tagfiles() Returns a |List| with the file names used to search for tags
4719 for the current buffer. This is the 'tags' option expanded.
4720
4721
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004722taglist({expr}) *taglist()*
4723 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00004724 Each list item is a dictionary with at least the following
4725 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00004726 name Name of the tag.
4727 filename Name of the file where the tag is
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004728 defined.
4729 cmd Ex command used to locate the tag in
4730 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004731 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004732 entry depends on the language specific
4733 kind values generated by the ctags
4734 tool.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004735 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004736 |static-tag| for more information.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004737 The "kind" entry is only available when using Exuberant ctags
4738 generated tags file. More entries may be present, depending
4739 on the content of the tags file: access, implementation,
4740 inherits and signature. Refer to the ctags documentation for
4741 information about these fields. For C code the fields
4742 "struct", "class" and "enum" may appear, they give the name of
4743 the entity the tag is contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004744
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004745 The ex-command 'cmd' can be either an ex search pattern, a
4746 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004747
4748 If there are no matching tags, then an empty list is returned.
4749
4750 To get an exact tag match, the anchors '^' and '$' should be
4751 used in {expr}. Refer to |tag-regexp| for more information
4752 about the tag search regular expression pattern.
4753
4754 Refer to |'tags'| for information about how the tags file is
4755 located by Vim. Refer to |tags-file-format| for the format of
4756 the tags file generated by the different ctags tools.
4757
Bram Moolenaar071d4272004-06-13 20:20:40 +00004758tempname() *tempname()* *temp-file-name*
4759 The result is a String, which is the name of a file that
4760 doesn't exist. It can be used for a temporary file. The name
4761 is different for at least 26 consecutive calls. Example: >
4762 :let tmpfile = tempname()
4763 :exe "redir > " . tmpfile
4764< For Unix, the file will be in a private directory (only
4765 accessible by the current user) to avoid security problems
4766 (e.g., a symlink attack or other people reading your file).
4767 When Vim exits the directory and all files in it are deleted.
4768 For MS-Windows forward slashes are used when the 'shellslash'
4769 option is set or when 'shellcmdflag' starts with '-'.
4770
4771tolower({expr}) *tolower()*
4772 The result is a copy of the String given, with all uppercase
4773 characters turned into lowercase (just like applying |gu| to
4774 the string).
4775
4776toupper({expr}) *toupper()*
4777 The result is a copy of the String given, with all lowercase
4778 characters turned into uppercase (just like applying |gU| to
4779 the string).
4780
Bram Moolenaar8299df92004-07-10 09:47:34 +00004781tr({src}, {fromstr}, {tostr}) *tr()*
4782 The result is a copy of the {src} string with all characters
4783 which appear in {fromstr} replaced by the character in that
4784 position in the {tostr} string. Thus the first character in
4785 {fromstr} is translated into the first character in {tostr}
4786 and so on. Exactly like the unix "tr" command.
4787 This code also deals with multibyte characters properly.
4788
4789 Examples: >
4790 echo tr("hello there", "ht", "HT")
4791< returns "Hello THere" >
4792 echo tr("<blob>", "<>", "{}")
4793< returns "{blob}"
4794
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004795 *type()*
4796type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00004797 Number: 0
4798 String: 1
4799 Funcref: 2
4800 List: 3
4801 Dictionary: 4
4802 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004803 :if type(myvar) == type(0)
4804 :if type(myvar) == type("")
4805 :if type(myvar) == type(function("tr"))
4806 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00004807 :if type(myvar) == type({})
Bram Moolenaar071d4272004-06-13 20:20:40 +00004808
Bram Moolenaar677ee682005-01-27 14:41:15 +00004809values({dict}) *values()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004810 Return a |List| with all the values of {dict}. The |List| is
4811 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004812
4813
Bram Moolenaar071d4272004-06-13 20:20:40 +00004814virtcol({expr}) *virtcol()*
4815 The result is a Number, which is the screen column of the file
4816 position given with {expr}. That is, the last screen position
4817 occupied by the character at that position, when the screen
4818 would be of unlimited width. When there is a <Tab> at the
4819 position, the returned Number will be the column at the end of
4820 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
4821 set to 8, it returns 8.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004822 For the use of {expr} see |col()|. Additionally you can use
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004823 [lnum, col]: a |List| with the line and column number. When
4824 "lnum" or "col" is out of range then virtcol() returns zero.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004825 When 'virtualedit' is used it can be [lnum, col, off], where
4826 "off" is the offset in screen columns from the start of the
4827 character. E.g., a position within a Tab or after the last
4828 character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004829 For the byte position use |col()|.
4830 When Virtual editing is active in the current mode, a position
4831 beyond the end of the line can be returned. |'virtualedit'|
4832 The accepted positions are:
4833 . the cursor position
4834 $ the end of the cursor line (the result is the
4835 number of displayed characters in the cursor line
4836 plus one)
4837 'x position of mark x (if the mark is not set, 0 is
4838 returned)
4839 Note that only marks in the current file can be used.
4840 Examples: >
4841 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
4842 virtcol("$") with text "foo^Lbar", returns 9
4843 virtcol("'t") with text " there", with 't at 'h', returns 6
4844< The first column is 1. 0 is returned for an error.
4845
4846visualmode([expr]) *visualmode()*
4847 The result is a String, which describes the last Visual mode
4848 used. Initially it returns an empty string, but once Visual
4849 mode has been used, it returns "v", "V", or "<CTRL-V>" (a
4850 single CTRL-V character) for character-wise, line-wise, or
4851 block-wise Visual mode respectively.
4852 Example: >
4853 :exe "normal " . visualmode()
4854< This enters the same Visual mode as before. It is also useful
4855 in scripts if you wish to act differently depending on the
4856 Visual mode that was used.
4857
4858 If an expression is supplied that results in a non-zero number
4859 or a non-empty string, then the Visual mode will be cleared
4860 and the old value is returned. Note that " " and "0" are also
4861 non-empty strings, thus cause the mode to be cleared.
4862
4863 *winbufnr()*
4864winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004865 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004866 the buffer in the current window is returned. When window
4867 {nr} doesn't exist, -1 is returned.
4868 Example: >
4869 :echo "The file in the current window is " . bufname(winbufnr(0))
4870<
4871 *wincol()*
4872wincol() The result is a Number, which is the virtual column of the
4873 cursor in the window. This is counting screen cells from the
4874 left side of the window. The leftmost column is one.
4875
4876winheight({nr}) *winheight()*
4877 The result is a Number, which is the height of window {nr}.
4878 When {nr} is zero, the height of the current window is
4879 returned. When window {nr} doesn't exist, -1 is returned.
4880 An existing window always has a height of zero or more.
4881 Examples: >
4882 :echo "The current window has " . winheight(0) . " lines."
4883<
4884 *winline()*
4885winline() The result is a Number, which is the screen line of the cursor
4886 in the window. This is counting screen lines from the top of
4887 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004888 If the cursor was moved the view on the file will be updated
4889 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004890
4891 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004892winnr([{arg}]) The result is a Number, which is the number of the current
4893 window. The top window has number 1.
4894 When the optional argument is "$", the number of the
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00004895 last window is returned (the window count).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004896 When the optional argument is "#", the number of the last
4897 accessed window is returned (where |CTRL-W_p| goes to).
4898 If there is no previous window 0 is returned.
4899 The number can be used with |CTRL-W_w| and ":wincmd w"
4900 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004901
4902 *winrestcmd()*
4903winrestcmd() Returns a sequence of |:resize| commands that should restore
4904 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004905 are opened or closed and the current window and tab page is
4906 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004907 Example: >
4908 :let cmd = winrestcmd()
4909 :call MessWithWindowSizes()
4910 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004911<
4912 *winrestview()*
4913winrestview({dict})
4914 Uses the |Dictionary| returned by |winsaveview()| to restore
4915 the view of the current window.
4916 If you have changed the values the result is unpredictable.
4917 If the window size changed the result won't be the same.
4918
4919 *winsaveview()*
4920winsaveview() Returns a |Dictionary| that contains information to restore
4921 the view of the current window. Use |winrestview()| to
4922 restore the view.
4923 This is useful if you have a mapping that jumps around in the
4924 buffer and you want to go back to the original view.
4925 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00004926 option to temporarily switch off folding, so that folds are
4927 not opened when moving around.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004928 The return value includes:
4929 lnum cursor line number
4930 col cursor column
4931 coladd cursor column offset for 'virtualedit'
4932 curswant column for vertical movement
4933 topline first line in the window
4934 topfill filler lines, only in diff mode
4935 leftcol first column displayed
4936 skipcol columns skipped
4937 Note that no option values are saved.
4938
Bram Moolenaar071d4272004-06-13 20:20:40 +00004939
4940winwidth({nr}) *winwidth()*
4941 The result is a Number, which is the width of window {nr}.
4942 When {nr} is zero, the width of the current window is
4943 returned. When window {nr} doesn't exist, -1 is returned.
4944 An existing window always has a width of zero or more.
4945 Examples: >
4946 :echo "The current window has " . winwidth(0) . " columns."
4947 :if winwidth(0) <= 50
4948 : exe "normal 50\<C-W>|"
4949 :endif
4950<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004951 *writefile()*
4952writefile({list}, {fname} [, {binary}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004953 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004954 separated with a NL. Each list item must be a String or
4955 Number.
4956 When {binary} is equal to "b" binary mode is used: There will
4957 not be a NL after the last list item. An empty item at the
4958 end does cause the last line in the file to end in a NL.
4959 All NL characters are replaced with a NUL character.
4960 Inserting CR characters needs to be done before passing {list}
4961 to writefile().
4962 An existing file is overwritten, if possible.
4963 When the write fails -1 is returned, otherwise 0. There is an
4964 error message if the file can't be created or when writing
4965 fails.
4966 Also see |readfile()|.
4967 To copy a file byte for byte: >
4968 :let fl = readfile("foo", "b")
4969 :call writefile(fl, "foocopy", "b")
4970<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004971
4972 *feature-list*
4973There are three types of features:
49741. Features that are only supported when they have been enabled when Vim
4975 was compiled |+feature-list|. Example: >
4976 :if has("cindent")
49772. Features that are only supported when certain conditions have been met.
4978 Example: >
4979 :if has("gui_running")
4980< *has-patch*
49813. Included patches. First check |v:version| for the version of Vim.
4982 Then the "patch123" feature means that patch 123 has been included for
4983 this version. Example (checking version 6.2.148 or later): >
4984 :if v:version > 602 || v:version == 602 && has("patch148")
4985
4986all_builtin_terms Compiled with all builtin terminals enabled.
4987amiga Amiga version of Vim.
4988arabic Compiled with Arabic support |Arabic|.
4989arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004990autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004991balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00004992balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004993beos BeOS version of Vim.
4994browse Compiled with |:browse| support, and browse() will
4995 work.
4996builtin_terms Compiled with some builtin terminals.
4997byte_offset Compiled with support for 'o' in 'statusline'
4998cindent Compiled with 'cindent' support.
4999clientserver Compiled with remote invocation support |clientserver|.
5000clipboard Compiled with 'clipboard' support.
5001cmdline_compl Compiled with |cmdline-completion| support.
5002cmdline_hist Compiled with |cmdline-history| support.
5003cmdline_info Compiled with 'showcmd' and 'ruler' support.
5004comments Compiled with |'comments'| support.
5005cryptv Compiled with encryption support |encryption|.
5006cscope Compiled with |cscope| support.
5007compatible Compiled to be very Vi compatible.
5008debug Compiled with "DEBUG" defined.
5009dialog_con Compiled with console dialog support.
5010dialog_gui Compiled with GUI dialog support.
5011diff Compiled with |vimdiff| and 'diff' support.
5012digraphs Compiled with support for digraphs.
5013dnd Compiled with support for the "~ register |quote_~|.
5014dos32 32 bits DOS (DJGPP) version of Vim.
5015dos16 16 bits DOS version of Vim.
5016ebcdic Compiled on a machine with ebcdic character set.
5017emacs_tags Compiled with support for Emacs tags.
5018eval Compiled with expression evaluation support. Always
5019 true, of course!
5020ex_extra Compiled with extra Ex commands |+ex_extra|.
5021extra_search Compiled with support for |'incsearch'| and
5022 |'hlsearch'|
5023farsi Compiled with Farsi support |farsi|.
5024file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005025filterpipe When 'shelltemp' is off pipes are used for shell
5026 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00005027find_in_path Compiled with support for include file searches
5028 |+find_in_path|.
5029fname_case Case in file names matters (for Amiga, MS-DOS, and
5030 Windows this is not present).
5031folding Compiled with |folding| support.
5032footer Compiled with GUI footer support. |gui-footer|
5033fork Compiled to use fork()/exec() instead of system().
5034gettext Compiled with message translation |multi-lang|
5035gui Compiled with GUI enabled.
5036gui_athena Compiled with Athena GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005037gui_gtk Compiled with GTK+ GUI (any version).
5038gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar843ee412004-06-30 16:16:41 +00005039gui_kde Compiled with KDE GUI |KVim|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005040gui_mac Compiled with Macintosh GUI.
5041gui_motif Compiled with Motif GUI.
5042gui_photon Compiled with Photon GUI.
5043gui_win32 Compiled with MS Windows Win32 GUI.
5044gui_win32s idem, and Win32s system being used (Windows 3.1)
5045gui_running Vim is running in the GUI, or it will start soon.
5046hangul_input Compiled with Hangul input support. |hangul|
5047iconv Can use iconv() for conversion.
5048insert_expand Compiled with support for CTRL-X expansion commands in
5049 Insert mode.
5050jumplist Compiled with |jumplist| support.
5051keymap Compiled with 'keymap' support.
5052langmap Compiled with 'langmap' support.
5053libcall Compiled with |libcall()| support.
5054linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
5055 support.
5056lispindent Compiled with support for lisp indenting.
5057listcmds Compiled with commands for the buffer list |:files|
5058 and the argument list |arglist|.
5059localmap Compiled with local mappings and abbr. |:map-local|
5060mac Macintosh version of Vim.
5061macunix Macintosh version of Vim, using Unix files (OS-X).
5062menu Compiled with support for |:menu|.
5063mksession Compiled with support for |:mksession|.
5064modify_fname Compiled with file name modifiers. |filename-modifiers|
5065mouse Compiled with support mouse.
5066mouseshape Compiled with support for 'mouseshape'.
5067mouse_dec Compiled with support for Dec terminal mouse.
5068mouse_gpm Compiled with support for gpm (Linux console mouse)
5069mouse_netterm Compiled with support for netterm mouse.
5070mouse_pterm Compiled with support for qnx pterm mouse.
5071mouse_xterm Compiled with support for xterm mouse.
5072multi_byte Compiled with support for editing Korean et al.
5073multi_byte_ime Compiled with support for IME input method.
5074multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005075mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005076netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00005077netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005078ole Compiled with OLE automation support for Win32.
5079os2 OS/2 version of Vim.
5080osfiletype Compiled with support for osfiletypes |+osfiletype|
5081path_extra Compiled with up/downwards search in 'path' and 'tags'
5082perl Compiled with Perl interface.
5083postscript Compiled with PostScript file printing.
5084printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005085profile Compiled with |:profile| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005086python Compiled with Python interface.
5087qnx QNX version of Vim.
5088quickfix Compiled with |quickfix| support.
5089rightleft Compiled with 'rightleft' support.
5090ruby Compiled with Ruby interface |ruby|.
5091scrollbind Compiled with 'scrollbind' support.
5092showcmd Compiled with 'showcmd' support.
5093signs Compiled with |:sign| support.
5094smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00005095sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005096statusline Compiled with support for 'statusline', 'rulerformat'
5097 and special formats of 'titlestring' and 'iconstring'.
5098sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00005099spell Compiled with spell checking support |spell|.
5100syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005101syntax_items There are active syntax highlighting items for the
5102 current buffer.
5103system Compiled to use system() instead of fork()/exec().
5104tag_binary Compiled with binary searching in tags files
5105 |tag-binary-search|.
5106tag_old_static Compiled with support for old static tags
5107 |tag-old-static|.
5108tag_any_white Compiled with support for any white characters in tags
5109 files |tag-any-white|.
5110tcl Compiled with Tcl interface.
5111terminfo Compiled with terminfo instead of termcap.
5112termresponse Compiled with support for |t_RV| and |v:termresponse|.
5113textobjects Compiled with support for |text-objects|.
5114tgetent Compiled with tgetent support, able to use a termcap
5115 or terminfo file.
5116title Compiled with window title support |'title'|.
5117toolbar Compiled with support for |gui-toolbar|.
5118unix Unix version of Vim.
5119user_commands User-defined commands.
5120viminfo Compiled with viminfo support.
5121vim_starting True while initial source'ing takes place.
5122vertsplit Compiled with vertically split windows |:vsplit|.
5123virtualedit Compiled with 'virtualedit' option.
5124visual Compiled with Visual mode.
5125visualextra Compiled with extra Visual mode commands.
5126 |blockwise-operators|.
5127vms VMS version of Vim.
5128vreplace Compiled with |gR| and |gr| commands.
5129wildignore Compiled with 'wildignore' option.
5130wildmenu Compiled with 'wildmenu' option.
5131windows Compiled with support for more than one window.
5132winaltkeys Compiled with 'winaltkeys' option.
5133win16 Win16 version of Vim (MS-Windows 3.1).
5134win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
5135win64 Win64 version of Vim (MS-Windows 64 bit).
5136win32unix Win32 version of Vim, using Unix files (Cygwin)
5137win95 Win32 version for MS-Windows 95/98/ME.
5138writebackup Compiled with 'writebackup' default on.
5139xfontset Compiled with X fontset support |xfontset|.
5140xim Compiled with X input method support |xim|.
5141xsmp Compiled with X session management support.
5142xsmp_interact Compiled with interactive X session management support.
5143xterm_clipboard Compiled with support for xterm clipboard.
5144xterm_save Compiled with support for saving and restoring the
5145 xterm screen.
5146x11 Compiled with X11 support.
5147
5148 *string-match*
5149Matching a pattern in a String
5150
5151A regexp pattern as explained at |pattern| is normally used to find a match in
5152the buffer lines. When a pattern is used to find a match in a String, almost
5153everything works in the same way. The difference is that a String is handled
5154like it is one line. When it contains a "\n" character, this is not seen as a
5155line break for the pattern. It can be matched with a "\n" in the pattern, or
5156with ".". Example: >
5157 :let a = "aaaa\nxxxx"
5158 :echo matchstr(a, "..\n..")
5159 aa
5160 xx
5161 :echo matchstr(a, "a.x")
5162 a
5163 x
5164
5165Don't forget that "^" will only match at the first character of the String and
5166"$" at the last character of the string. They don't match after or before a
5167"\n".
5168
5169==============================================================================
51705. Defining functions *user-functions*
5171
5172New functions can be defined. These can be called just like builtin
5173functions. The function executes a sequence of Ex commands. Normal mode
5174commands can be executed with the |:normal| command.
5175
5176The function name must start with an uppercase letter, to avoid confusion with
5177builtin functions. To prevent from using the same name in different scripts
5178avoid obvious, short names. A good habit is to start the function name with
5179the name of the script, e.g., "HTMLcolor()".
5180
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005181It's also possible to use curly braces, see |curly-braces-names|. And the
5182|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005183
5184 *local-function*
5185A function local to a script must start with "s:". A local script function
5186can only be called from within the script and from functions, user commands
5187and autocommands defined in the script. It is also possible to call the
5188function from a mappings defined in the script, but then |<SID>| must be used
5189instead of "s:" when the mapping is expanded outside of the script.
5190
5191 *:fu* *:function* *E128* *E129* *E123*
5192:fu[nction] List all functions and their arguments.
5193
5194:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005195 {name} can also be a |Dictionary| entry that is a
5196 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005197 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005198
5199:fu[nction] /{pattern} List functions with a name matching {pattern}.
5200 Example that lists all functions ending with "File": >
5201 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00005202<
5203 *:function-verbose*
5204When 'verbose' is non-zero, listing a function will also display where it was
5205last defined. Example: >
5206
5207 :verbose function SetFileTypeSH
5208 function SetFileTypeSH(name)
5209 Last set from /usr/share/vim/vim-7.0/filetype.vim
5210<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005211See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00005212
5213 *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005214:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00005215 Define a new function by the name {name}. The name
5216 must be made of alphanumeric characters and '_', and
5217 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005218
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005219 {name} can also be a |Dictionary| entry that is a
5220 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005221 :function dict.init(arg)
5222< "dict" must be an existing dictionary. The entry
5223 "init" is added if it didn't exist yet. Otherwise [!]
5224 is required to overwrite an existing function. The
5225 result is a |Funcref| to a numbered function. The
5226 function can only be used with a |Funcref| and will be
5227 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005228 *E127* *E122*
5229 When a function by this name already exists and [!] is
5230 not used an error message is given. When [!] is used,
5231 an existing function is silently replaced. Unless it
5232 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005233
5234 For the {arguments} see |function-argument|.
5235
Bram Moolenaar071d4272004-06-13 20:20:40 +00005236 *a:firstline* *a:lastline*
5237 When the [range] argument is added, the function is
5238 expected to take care of a range itself. The range is
5239 passed as "a:firstline" and "a:lastline". If [range]
5240 is excluded, ":{range}call" will call the function for
5241 each line in the range, with the cursor on the start
5242 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005243
Bram Moolenaar071d4272004-06-13 20:20:40 +00005244 When the [abort] argument is added, the function will
5245 abort as soon as an error is detected.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005246
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005247 When the [dict] argument is added, the function must
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005248 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005249 local variable "self" will then be set to the
5250 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005251
Bram Moolenaar98692072006-02-04 00:57:42 +00005252 The last used search pattern and the redo command "."
5253 will not be changed by the function.
5254
Bram Moolenaar071d4272004-06-13 20:20:40 +00005255 *:endf* *:endfunction* *E126* *E193*
5256:endf[unction] The end of a function definition. Must be on a line
5257 by its own, without other commands.
5258
5259 *:delf* *:delfunction* *E130* *E131*
5260:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005261 {name} can also be a |Dictionary| entry that is a
5262 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005263 :delfunc dict.init
5264< This will remove the "init" entry from "dict". The
5265 function is deleted if there are no more references to
5266 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005267 *:retu* *:return* *E133*
5268:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
5269 evaluated and returned as the result of the function.
5270 If "[expr]" is not given, the number 0 is returned.
5271 When a function ends without an explicit ":return",
5272 the number 0 is returned.
5273 Note that there is no check for unreachable lines,
5274 thus there is no warning if commands follow ":return".
5275
5276 If the ":return" is used after a |:try| but before the
5277 matching |:finally| (if present), the commands
5278 following the ":finally" up to the matching |:endtry|
5279 are executed first. This process applies to all
5280 nested ":try"s inside the function. The function
5281 returns at the outermost ":endtry".
5282
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005283 *function-argument* *a:var*
5284An argument can be defined by giving its name. In the function this can then
5285be used as "a:name" ("a:" for argument).
5286 *a:0* *a:1* *a:000* *E740*
5287Up to 20 arguments can be given, separated by commas. After the named
5288arguments an argument "..." can be specified, which means that more arguments
5289may optionally be following. In the function the extra arguments can be used
5290as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005291can be 0). "a:000" is set to a |List| that contains these arguments. Note
5292that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005293 *E742*
5294The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005295However, if a |List| or |Dictionary| is used, you can changes their contents.
5296Thus you can pass a |List| to a function and have the function add an item to
5297it. If you want to make sure the function cannot change a |List| or
5298|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005299
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005300When not using "...", the number of arguments in a function call must be equal
5301to the number of named arguments. When using "...", the number of arguments
5302may be larger.
5303
5304It is also possible to define a function without any arguments. You must
5305still supply the () then. The body of the function follows in the next lines,
5306until the matching |:endfunction|. It is allowed to define another function
5307inside a function body.
5308
5309 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005310Inside a function variables can be used. These are local variables, which
5311will disappear when the function returns. Global variables need to be
5312accessed with "g:".
5313
5314Example: >
5315 :function Table(title, ...)
5316 : echohl Title
5317 : echo a:title
5318 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00005319 : echo a:0 . " items:"
5320 : for s in a:000
5321 : echon ' ' . s
5322 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005323 :endfunction
5324
5325This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00005326 call Table("Table", "line1", "line2")
5327 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005328
5329To return more than one value, pass the name of a global variable: >
5330 :function Compute(n1, n2, divname)
5331 : if a:n2 == 0
5332 : return "fail"
5333 : endif
5334 : let g:{a:divname} = a:n1 / a:n2
5335 : return "ok"
5336 :endfunction
5337
5338This function can then be called with: >
5339 :let success = Compute(13, 1324, "div")
5340 :if success == "ok"
5341 : echo div
5342 :endif
5343
5344An alternative is to return a command that can be executed. This also works
5345with local variables in a calling function. Example: >
5346 :function Foo()
5347 : execute Bar()
5348 : echo "line " . lnum . " column " . col
5349 :endfunction
5350
5351 :function Bar()
5352 : return "let lnum = " . line(".") . " | let col = " . col(".")
5353 :endfunction
5354
5355The names "lnum" and "col" could also be passed as argument to Bar(), to allow
5356the caller to set the names.
5357
Bram Moolenaar39f05632006-03-19 22:15:26 +00005358 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005359:[range]cal[l] {name}([arguments])
5360 Call a function. The name of the function and its arguments
5361 are as specified with |:function|. Up to 20 arguments can be
5362 used.
5363 Without a range and for functions that accept a range, the
5364 function is called once. When a range is given the cursor is
5365 positioned at the start of the first line before executing the
5366 function.
5367 When a range is given and the function doesn't handle it
5368 itself, the function is executed for each line in the range,
5369 with the cursor in the first column of that line. The cursor
5370 is left at the last line (possibly moved by the last function
5371 call). The arguments are re-evaluated for each line. Thus
5372 this works:
5373 *function-range-example* >
5374 :function Mynumber(arg)
5375 : echo line(".") . " " . a:arg
5376 :endfunction
5377 :1,5call Mynumber(getline("."))
5378<
5379 The "a:firstline" and "a:lastline" are defined anyway, they
5380 can be used to do something different at the start or end of
5381 the range.
5382
5383 Example of a function that handles the range itself: >
5384
5385 :function Cont() range
5386 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
5387 :endfunction
5388 :4,8call Cont()
5389<
5390 This function inserts the continuation character "\" in front
5391 of all the lines in the range, except the first one.
5392
5393 *E132*
5394The recursiveness of user functions is restricted with the |'maxfuncdepth'|
5395option.
5396
Bram Moolenaar7c626922005-02-07 22:01:03 +00005397
5398AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005399 *autoload-functions*
5400When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00005401only when they are used. There are two methods: with an autocommand and with
5402the "autoload" directory in 'runtimepath'.
5403
5404
5405Using an autocommand ~
5406
Bram Moolenaar05159a02005-02-26 23:04:13 +00005407This is introduced in the user manual, section |41.14|.
5408
Bram Moolenaar7c626922005-02-07 22:01:03 +00005409The autocommand is useful if you have a plugin that is a long Vim script file.
5410You can define the autocommand and quickly quit the script with |:finish|.
5411That makes Vim startup faster. The autocommand should then load the same file
5412again, setting a variable to skip the |:finish| command.
5413
5414Use the FuncUndefined autocommand event with a pattern that matches the
5415function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005416
5417 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
5418
5419The file "~/vim/bufnetfuncs.vim" should then define functions that start with
5420"BufNet". Also see |FuncUndefined|.
5421
Bram Moolenaar7c626922005-02-07 22:01:03 +00005422
5423Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005424 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005425This is introduced in the user manual, section |41.15|.
5426
Bram Moolenaar7c626922005-02-07 22:01:03 +00005427Using a script in the "autoload" directory is simpler, but requires using
5428exactly the right file name. A function that can be autoloaded has a name
5429like this: >
5430
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005431 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005432
5433When such a function is called, and it is not defined yet, Vim will search the
5434"autoload" directories in 'runtimepath' for a script file called
5435"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
5436then define the function like this: >
5437
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005438 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005439 echo "Done!"
5440 endfunction
5441
Bram Moolenaar60a795a2005-09-16 21:55:43 +00005442The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00005443exactly, and the defined function must have the name exactly as it will be
5444called.
5445
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005446It is possible to use subdirectories. Every # in the function name works like
5447a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00005448
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005449 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005450
5451Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
5452
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005453This also works when reading a variable that has not been set yet: >
5454
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005455 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005456
Bram Moolenaara5792f52005-11-23 21:25:05 +00005457However, when the autoload script was already loaded it won't be loaded again
5458for an unknown variable.
5459
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005460When assigning a value to such a variable nothing special happens. This can
5461be used to pass settings to the autoload script before it's loaded: >
5462
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005463 :let foo#bar#toggle = 1
5464 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005465
Bram Moolenaar4399ef42005-02-12 14:29:27 +00005466Note that when you make a mistake and call a function that is supposed to be
5467defined in an autoload script, but the script doesn't actually define the
5468function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005469And you will get an error message every time.
5470
5471Also note that if you have two script files, and one calls a function in the
5472other and vise versa, before the used function is defined, it won't work.
5473Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00005474
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005475Hint: If you distribute a bunch of scripts you can pack them together with the
5476|vimball| utility. Also read the user manual |distribute-script|.
5477
Bram Moolenaar071d4272004-06-13 20:20:40 +00005478==============================================================================
54796. Curly braces names *curly-braces-names*
5480
5481Wherever you can use a variable, you can use a "curly braces name" variable.
5482This is a regular variable name with one or more expressions wrapped in braces
5483{} like this: >
5484 my_{adjective}_variable
5485
5486When Vim encounters this, it evaluates the expression inside the braces, puts
5487that in place of the expression, and re-interprets the whole as a variable
5488name. So in the above example, if the variable "adjective" was set to
5489"noisy", then the reference would be to "my_noisy_variable", whereas if
5490"adjective" was set to "quiet", then it would be to "my_quiet_variable".
5491
5492One application for this is to create a set of variables governed by an option
5493value. For example, the statement >
5494 echo my_{&background}_message
5495
5496would output the contents of "my_dark_message" or "my_light_message" depending
5497on the current value of 'background'.
5498
5499You can use multiple brace pairs: >
5500 echo my_{adverb}_{adjective}_message
5501..or even nest them: >
5502 echo my_{ad{end_of_word}}_message
5503where "end_of_word" is either "verb" or "jective".
5504
5505However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005506variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005507 :let foo='a + b'
5508 :echo c{foo}d
5509.. since the result of expansion is "ca + bd", which is not a variable name.
5510
5511 *curly-braces-function-names*
5512You can call and define functions by an evaluated name in a similar way.
5513Example: >
5514 :let func_end='whizz'
5515 :call my_func_{func_end}(parameter)
5516
5517This would call the function "my_func_whizz(parameter)".
5518
5519==============================================================================
55207. Commands *expression-commands*
5521
5522:let {var-name} = {expr1} *:let* *E18*
5523 Set internal variable {var-name} to the result of the
5524 expression {expr1}. The variable will get the type
5525 from the {expr}. If {var-name} didn't exist yet, it
5526 is created.
5527
Bram Moolenaar13065c42005-01-08 16:08:21 +00005528:let {var-name}[{idx}] = {expr1} *E689*
5529 Set a list item to the result of the expression
5530 {expr1}. {var-name} must refer to a list and {idx}
5531 must be a valid index in that list. For nested list
5532 the index can be repeated.
5533 This cannot be used to add an item to a list.
5534
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005535 *E711* *E719*
5536:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005537 Set a sequence of items in a |List| to the result of
5538 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005539 correct number of items.
5540 {idx1} can be omitted, zero is used instead.
5541 {idx2} can be omitted, meaning the end of the list.
5542 When the selected range of items is partly past the
5543 end of the list, items will be added.
5544
Bram Moolenaar748bf032005-02-02 23:04:36 +00005545 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005546:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
5547:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
5548:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
5549 These fail if {var} was not set yet and when the type
5550 of {var} and {expr1} don't fit the operator.
5551
5552
Bram Moolenaar071d4272004-06-13 20:20:40 +00005553:let ${env-name} = {expr1} *:let-environment* *:let-$*
5554 Set environment variable {env-name} to the result of
5555 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005556:let ${env-name} .= {expr1}
5557 Append {expr1} to the environment variable {env-name}.
5558 If the environment variable didn't exist yet this
5559 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005560
5561:let @{reg-name} = {expr1} *:let-register* *:let-@*
5562 Write the result of the expression {expr1} in register
5563 {reg-name}. {reg-name} must be a single letter, and
5564 must be the name of a writable register (see
5565 |registers|). "@@" can be used for the unnamed
5566 register, "@/" for the search pattern.
5567 If the result of {expr1} ends in a <CR> or <NL>, the
5568 register will be linewise, otherwise it will be set to
5569 characterwise.
5570 This can be used to clear the last search pattern: >
5571 :let @/ = ""
5572< This is different from searching for an empty string,
5573 that would match everywhere.
5574
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005575:let @{reg-name} .= {expr1}
5576 Append {expr1} to register {reg-name}. If the
5577 register was empty it's like setting it to {expr1}.
5578
Bram Moolenaar071d4272004-06-13 20:20:40 +00005579:let &{option-name} = {expr1} *:let-option* *:let-star*
5580 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005581 expression {expr1}. A String or Number value is
5582 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005583 For an option local to a window or buffer the effect
5584 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00005585 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005586 Example: >
5587 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00005588
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005589:let &{option-name} .= {expr1}
5590 For a string option: Append {expr1} to the value.
5591 Does not insert a comma like |:set+=|.
5592
5593:let &{option-name} += {expr1}
5594:let &{option-name} -= {expr1}
5595 For a number or boolean option: Add or subtract
5596 {expr1}.
5597
Bram Moolenaar071d4272004-06-13 20:20:40 +00005598:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005599:let &l:{option-name} .= {expr1}
5600:let &l:{option-name} += {expr1}
5601:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005602 Like above, but only set the local value of an option
5603 (if there is one). Works like |:setlocal|.
5604
5605:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005606:let &g:{option-name} .= {expr1}
5607:let &g:{option-name} += {expr1}
5608:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005609 Like above, but only set the global value of an option
5610 (if there is one). Works like |:setglobal|.
5611
Bram Moolenaar13065c42005-01-08 16:08:21 +00005612:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005613 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005614 the list is assigned to {name1}, the second item to
5615 {name2}, etc.
5616 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005617 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005618 Each name can be one of the items of the ":let"
5619 command as mentioned above.
5620 Example: >
5621 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005622< Detail: {expr1} is evaluated first, then the
5623 assignments are done in sequence. This matters if
5624 {name2} depends on {name1}. Example: >
5625 :let x = [0, 1]
5626 :let i = 0
5627 :let [i, x[i]] = [1, 2]
5628 :echo x
5629< The result is [0, 2].
5630
5631:let [{name1}, {name2}, ...] .= {expr1}
5632:let [{name1}, {name2}, ...] += {expr1}
5633:let [{name1}, {name2}, ...] -= {expr1}
5634 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005635 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005636
5637:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005638 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005639 items than there are names. A list of the remaining
5640 items is assigned to {lastname}. If there are no
5641 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005642 Example: >
5643 :let [a, b; rest] = ["aval", "bval", 3, 4]
5644<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005645:let [{name}, ..., ; {lastname}] .= {expr1}
5646:let [{name}, ..., ; {lastname}] += {expr1}
5647:let [{name}, ..., ; {lastname}] -= {expr1}
5648 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005649 |List| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005650 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005651:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00005652 variable names may be given. Special names recognized
5653 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00005654 g: global variables
5655 b: local buffer variables
5656 w: local window variables
5657 s: script-local variables
5658 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00005659 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005660
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005661:let List the values of all variables. The type of the
5662 variable is indicated before the value:
5663 <nothing> String
5664 # Number
5665 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00005666
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005667
5668:unl[et][!] {name} ... *:unlet* *:unl* *E108*
5669 Remove the internal variable {name}. Several variable
5670 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005671 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005672 With [!] no error message is given for non-existing
5673 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005674 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00005675 :unlet list[3] " remove fourth item
5676 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005677< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00005678 :unlet dict['two']
5679 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00005680
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005681:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
5682 Lock the internal variable {name}. Locking means that
5683 it can no longer be changed (until it is unlocked).
5684 A locked variable can be deleted: >
5685 :lockvar v
5686 :let v = 'asdf' " fails!
5687 :unlet v
5688< *E741*
5689 If you try to change a locked variable you get an
5690 error message: "E741: Value of {name} is locked"
5691
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005692 [depth] is relevant when locking a |List| or
5693 |Dictionary|. It specifies how deep the locking goes:
5694 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005695 cannot add or remove items, but can
5696 still change their values.
5697 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005698 the items. If an item is a |List| or
5699 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005700 items, but can still change the
5701 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005702 3 Like 2 but for the |List| /
5703 |Dictionary| in the |List| /
5704 |Dictionary|, one level deeper.
5705 The default [depth] is 2, thus when {name} is a |List|
5706 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005707 *E743*
5708 For unlimited depth use [!] and omit [depth].
5709 However, there is a maximum depth of 100 to catch
5710 loops.
5711
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005712 Note that when two variables refer to the same |List|
5713 and you lock one of them, the |List| will also be
5714 locked when used through the other variable. Example:
5715 >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005716 :let l = [0, 1, 2, 3]
5717 :let cl = l
5718 :lockvar l
5719 :let cl[1] = 99 " won't work!
5720< You may want to make a copy of a list to avoid this.
5721 See |deepcopy()|.
5722
5723
5724:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
5725 Unlock the internal variable {name}. Does the
5726 opposite of |:lockvar|.
5727
5728
Bram Moolenaar071d4272004-06-13 20:20:40 +00005729:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
5730:en[dif] Execute the commands until the next matching ":else"
5731 or ":endif" if {expr1} evaluates to non-zero.
5732
5733 From Vim version 4.5 until 5.0, every Ex command in
5734 between the ":if" and ":endif" is ignored. These two
5735 commands were just to allow for future expansions in a
5736 backwards compatible way. Nesting was allowed. Note
5737 that any ":else" or ":elseif" was ignored, the "else"
5738 part was not executed either.
5739
5740 You can use this to remain compatible with older
5741 versions: >
5742 :if version >= 500
5743 : version-5-specific-commands
5744 :endif
5745< The commands still need to be parsed to find the
5746 "endif". Sometimes an older Vim has a problem with a
5747 new command. For example, ":silent" is recognized as
5748 a ":substitute" command. In that case ":execute" can
5749 avoid problems: >
5750 :if version >= 600
5751 : execute "silent 1,$delete"
5752 :endif
5753<
5754 NOTE: The ":append" and ":insert" commands don't work
5755 properly in between ":if" and ":endif".
5756
5757 *:else* *:el* *E581* *E583*
5758:el[se] Execute the commands until the next matching ":else"
5759 or ":endif" if they previously were not being
5760 executed.
5761
5762 *:elseif* *:elsei* *E582* *E584*
5763:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
5764 is no extra ":endif".
5765
5766:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005767 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005768:endw[hile] Repeat the commands between ":while" and ":endwhile",
5769 as long as {expr1} evaluates to non-zero.
5770 When an error is detected from a command inside the
5771 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00005772 Example: >
5773 :let lnum = 1
5774 :while lnum <= line("$")
5775 :call FixLine(lnum)
5776 :let lnum = lnum + 1
5777 :endwhile
5778<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005779 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00005780 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005781
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005782:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00005783:endfo[r] *:endfo* *:endfor*
5784 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005785 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005786 value of each item.
5787 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00005788 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00005789 Changing {list} inside the loop affects what items are
5790 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005791 :for item in copy(mylist)
5792< When not making a copy, Vim stores a reference to the
5793 next item in the list, before executing the commands
5794 with the current item. Thus the current item can be
5795 removed without effect. Removing any later item means
5796 it will not be found. Thus the following example
5797 works (an inefficient way to make a list empty): >
5798 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00005799 :call remove(mylist, 0)
5800 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005801< Note that reordering the list (e.g., with sort() or
5802 reverse()) may have unexpected effects.
5803 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00005804 identical to avoid errors for the type of {var}
5805 changing. Unlet the variable at the end of the loop
5806 to allow multiple item types.
5807
Bram Moolenaar12805862005-01-05 22:16:17 +00005808:for [{var1}, {var2}, ...] in {listlist}
5809:endfo[r]
5810 Like ":for" above, but each item in {listlist} must be
5811 a list, of which each item is assigned to {var1},
5812 {var2}, etc. Example: >
5813 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
5814 :echo getline(lnum)[col]
5815 :endfor
5816<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005817 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00005818:con[tinue] When used inside a ":while" or ":for" loop, jumps back
5819 to the start of the loop.
5820 If it is used after a |:try| inside the loop but
5821 before the matching |:finally| (if present), the
5822 commands following the ":finally" up to the matching
5823 |:endtry| are executed first. This process applies to
5824 all nested ":try"s inside the loop. The outermost
5825 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005826
5827 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00005828:brea[k] When used inside a ":while" or ":for" loop, skips to
5829 the command after the matching ":endwhile" or
5830 ":endfor".
5831 If it is used after a |:try| inside the loop but
5832 before the matching |:finally| (if present), the
5833 commands following the ":finally" up to the matching
5834 |:endtry| are executed first. This process applies to
5835 all nested ":try"s inside the loop. The outermost
5836 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005837
5838:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
5839:endt[ry] Change the error handling for the commands between
5840 ":try" and ":endtry" including everything being
5841 executed across ":source" commands, function calls,
5842 or autocommand invocations.
5843
5844 When an error or interrupt is detected and there is
5845 a |:finally| command following, execution continues
5846 after the ":finally". Otherwise, or when the
5847 ":endtry" is reached thereafter, the next
5848 (dynamically) surrounding ":try" is checked for
5849 a corresponding ":finally" etc. Then the script
5850 processing is terminated. (Whether a function
5851 definition has an "abort" argument does not matter.)
5852 Example: >
5853 :try | edit too much | finally | echo "cleanup" | endtry
5854 :echo "impossible" " not reached, script terminated above
5855<
5856 Moreover, an error or interrupt (dynamically) inside
5857 ":try" and ":endtry" is converted to an exception. It
5858 can be caught as if it were thrown by a |:throw|
5859 command (see |:catch|). In this case, the script
5860 processing is not terminated.
5861
5862 The value "Vim:Interrupt" is used for an interrupt
5863 exception. An error in a Vim command is converted
5864 to a value of the form "Vim({command}):{errmsg}",
5865 other errors are converted to a value of the form
5866 "Vim:{errmsg}". {command} is the full command name,
5867 and {errmsg} is the message that is displayed if the
5868 error exception is not caught, always beginning with
5869 the error number.
5870 Examples: >
5871 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
5872 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
5873<
5874 *:cat* *:catch* *E603* *E604* *E605*
5875:cat[ch] /{pattern}/ The following commands until the next ":catch",
5876 |:finally|, or |:endtry| that belongs to the same
5877 |:try| as the ":catch" are executed when an exception
5878 matching {pattern} is being thrown and has not yet
5879 been caught by a previous ":catch". Otherwise, these
5880 commands are skipped.
5881 When {pattern} is omitted all errors are caught.
5882 Examples: >
5883 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
5884 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
5885 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
5886 :catch /^Vim(write):/ " catch all errors in :write
5887 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
5888 :catch /my-exception/ " catch user exception
5889 :catch /.*/ " catch everything
5890 :catch " same as /.*/
5891<
5892 Another character can be used instead of / around the
5893 {pattern}, so long as it does not have a special
5894 meaning (e.g., '|' or '"') and doesn't occur inside
5895 {pattern}.
5896 NOTE: It is not reliable to ":catch" the TEXT of
5897 an error message because it may vary in different
5898 locales.
5899
5900 *:fina* *:finally* *E606* *E607*
5901:fina[lly] The following commands until the matching |:endtry|
5902 are executed whenever the part between the matching
5903 |:try| and the ":finally" is left: either by falling
5904 through to the ":finally" or by a |:continue|,
5905 |:break|, |:finish|, or |:return|, or by an error or
5906 interrupt or exception (see |:throw|).
5907
5908 *:th* *:throw* *E608*
5909:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
5910 If the ":throw" is used after a |:try| but before the
5911 first corresponding |:catch|, commands are skipped
5912 until the first ":catch" matching {expr1} is reached.
5913 If there is no such ":catch" or if the ":throw" is
5914 used after a ":catch" but before the |:finally|, the
5915 commands following the ":finally" (if present) up to
5916 the matching |:endtry| are executed. If the ":throw"
5917 is after the ":finally", commands up to the ":endtry"
5918 are skipped. At the ":endtry", this process applies
5919 again for the next dynamically surrounding ":try"
5920 (which may be found in a calling function or sourcing
5921 script), until a matching ":catch" has been found.
5922 If the exception is not caught, the command processing
5923 is terminated.
5924 Example: >
5925 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
5926<
5927
5928 *:ec* *:echo*
5929:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
5930 first {expr1} starts on a new line.
5931 Also see |:comment|.
5932 Use "\n" to start a new line. Use "\r" to move the
5933 cursor to the first column.
5934 Uses the highlighting set by the |:echohl| command.
5935 Cannot be followed by a comment.
5936 Example: >
5937 :echo "the value of 'shell' is" &shell
5938< A later redraw may make the message disappear again.
5939 To avoid that a command from before the ":echo" causes
5940 a redraw afterwards (redraws are often postponed until
5941 you type something), force a redraw with the |:redraw|
5942 command. Example: >
5943 :new | redraw | echo "there is a new window"
5944<
5945 *:echon*
5946:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
5947 |:comment|.
5948 Uses the highlighting set by the |:echohl| command.
5949 Cannot be followed by a comment.
5950 Example: >
5951 :echon "the value of 'shell' is " &shell
5952<
5953 Note the difference between using ":echo", which is a
5954 Vim command, and ":!echo", which is an external shell
5955 command: >
5956 :!echo % --> filename
5957< The arguments of ":!" are expanded, see |:_%|. >
5958 :!echo "%" --> filename or "filename"
5959< Like the previous example. Whether you see the double
5960 quotes or not depends on your 'shell'. >
5961 :echo % --> nothing
5962< The '%' is an illegal character in an expression. >
5963 :echo "%" --> %
5964< This just echoes the '%' character. >
5965 :echo expand("%") --> filename
5966< This calls the expand() function to expand the '%'.
5967
5968 *:echoh* *:echohl*
5969:echoh[l] {name} Use the highlight group {name} for the following
5970 |:echo|, |:echon| and |:echomsg| commands. Also used
5971 for the |input()| prompt. Example: >
5972 :echohl WarningMsg | echo "Don't panic!" | echohl None
5973< Don't forget to set the group back to "None",
5974 otherwise all following echo's will be highlighted.
5975
5976 *:echom* *:echomsg*
5977:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
5978 message in the |message-history|.
5979 Spaces are placed between the arguments as with the
5980 |:echo| command. But unprintable characters are
5981 displayed, not interpreted.
5982 Uses the highlighting set by the |:echohl| command.
5983 Example: >
5984 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
5985<
5986 *:echoe* *:echoerr*
5987:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
5988 message in the |message-history|. When used in a
5989 script or function the line number will be added.
5990 Spaces are placed between the arguments as with the
5991 :echo command. When used inside a try conditional,
5992 the message is raised as an error exception instead
5993 (see |try-echoerr|).
5994 Example: >
5995 :echoerr "This script just failed!"
5996< If you just want a highlighted message use |:echohl|.
5997 And to get a beep: >
5998 :exe "normal \<Esc>"
5999<
6000 *:exe* *:execute*
6001:exe[cute] {expr1} .. Executes the string that results from the evaluation
6002 of {expr1} as an Ex command. Multiple arguments are
6003 concatenated, with a space in between. {expr1} is
6004 used as the processed command, command line editing
6005 keys are not recognized.
6006 Cannot be followed by a comment.
6007 Examples: >
6008 :execute "buffer " nextbuf
6009 :execute "normal " count . "w"
6010<
6011 ":execute" can be used to append a command to commands
6012 that don't accept a '|'. Example: >
6013 :execute '!ls' | echo "theend"
6014
6015< ":execute" is also a nice way to avoid having to type
6016 control characters in a Vim script for a ":normal"
6017 command: >
6018 :execute "normal ixxx\<Esc>"
6019< This has an <Esc> character, see |expr-string|.
6020
6021 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00006022 you cannot start or end a "while", "for" or "if"
6023 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006024 :execute 'while i > 5'
6025 :execute 'echo "test" | break'
6026<
6027 It is allowed to have a "while" or "if" command
6028 completely in the executed string: >
6029 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
6030<
6031
6032 *:comment*
6033 ":execute", ":echo" and ":echon" cannot be followed by
6034 a comment directly, because they see the '"' as the
6035 start of a string. But, you can use '|' followed by a
6036 comment. Example: >
6037 :echo "foo" | "this is a comment
6038
6039==============================================================================
60408. Exception handling *exception-handling*
6041
6042The Vim script language comprises an exception handling feature. This section
6043explains how it can be used in a Vim script.
6044
6045Exceptions may be raised by Vim on an error or on interrupt, see
6046|catch-errors| and |catch-interrupt|. You can also explicitly throw an
6047exception by using the ":throw" command, see |throw-catch|.
6048
6049
6050TRY CONDITIONALS *try-conditionals*
6051
6052Exceptions can be caught or can cause cleanup code to be executed. You can
6053use a try conditional to specify catch clauses (that catch exceptions) and/or
6054a finally clause (to be executed for cleanup).
6055 A try conditional begins with a |:try| command and ends at the matching
6056|:endtry| command. In between, you can use a |:catch| command to start
6057a catch clause, or a |:finally| command to start a finally clause. There may
6058be none or multiple catch clauses, but there is at most one finally clause,
6059which must not be followed by any catch clauses. The lines before the catch
6060clauses and the finally clause is called a try block. >
6061
6062 :try
6063 : ...
6064 : ... TRY BLOCK
6065 : ...
6066 :catch /{pattern}/
6067 : ...
6068 : ... CATCH CLAUSE
6069 : ...
6070 :catch /{pattern}/
6071 : ...
6072 : ... CATCH CLAUSE
6073 : ...
6074 :finally
6075 : ...
6076 : ... FINALLY CLAUSE
6077 : ...
6078 :endtry
6079
6080The try conditional allows to watch code for exceptions and to take the
6081appropriate actions. Exceptions from the try block may be caught. Exceptions
6082from the try block and also the catch clauses may cause cleanup actions.
6083 When no exception is thrown during execution of the try block, the control
6084is transferred to the finally clause, if present. After its execution, the
6085script continues with the line following the ":endtry".
6086 When an exception occurs during execution of the try block, the remaining
6087lines in the try block are skipped. The exception is matched against the
6088patterns specified as arguments to the ":catch" commands. The catch clause
6089after the first matching ":catch" is taken, other catch clauses are not
6090executed. The catch clause ends when the next ":catch", ":finally", or
6091":endtry" command is reached - whatever is first. Then, the finally clause
6092(if present) is executed. When the ":endtry" is reached, the script execution
6093continues in the following line as usual.
6094 When an exception that does not match any of the patterns specified by the
6095":catch" commands is thrown in the try block, the exception is not caught by
6096that try conditional and none of the catch clauses is executed. Only the
6097finally clause, if present, is taken. The exception pends during execution of
6098the finally clause. It is resumed at the ":endtry", so that commands after
6099the ":endtry" are not executed and the exception might be caught elsewhere,
6100see |try-nesting|.
6101 When during execution of a catch clause another exception is thrown, the
6102remaining lines in that catch clause are not executed. The new exception is
6103not matched against the patterns in any of the ":catch" commands of the same
6104try conditional and none of its catch clauses is taken. If there is, however,
6105a finally clause, it is executed, and the exception pends during its
6106execution. The commands following the ":endtry" are not executed. The new
6107exception might, however, be caught elsewhere, see |try-nesting|.
6108 When during execution of the finally clause (if present) an exception is
6109thrown, the remaining lines in the finally clause are skipped. If the finally
6110clause has been taken because of an exception from the try block or one of the
6111catch clauses, the original (pending) exception is discarded. The commands
6112following the ":endtry" are not executed, and the exception from the finally
6113clause is propagated and can be caught elsewhere, see |try-nesting|.
6114
6115The finally clause is also executed, when a ":break" or ":continue" for
6116a ":while" loop enclosing the complete try conditional is executed from the
6117try block or a catch clause. Or when a ":return" or ":finish" is executed
6118from the try block or a catch clause of a try conditional in a function or
6119sourced script, respectively. The ":break", ":continue", ":return", or
6120":finish" pends during execution of the finally clause and is resumed when the
6121":endtry" is reached. It is, however, discarded when an exception is thrown
6122from the finally clause.
6123 When a ":break" or ":continue" for a ":while" loop enclosing the complete
6124try conditional or when a ":return" or ":finish" is encountered in the finally
6125clause, the rest of the finally clause is skipped, and the ":break",
6126":continue", ":return" or ":finish" is executed as usual. If the finally
6127clause has been taken because of an exception or an earlier ":break",
6128":continue", ":return", or ":finish" from the try block or a catch clause,
6129this pending exception or command is discarded.
6130
6131For examples see |throw-catch| and |try-finally|.
6132
6133
6134NESTING OF TRY CONDITIONALS *try-nesting*
6135
6136Try conditionals can be nested arbitrarily. That is, a complete try
6137conditional can be put into the try block, a catch clause, or the finally
6138clause of another try conditional. If the inner try conditional does not
6139catch an exception thrown in its try block or throws a new exception from one
6140of its catch clauses or its finally clause, the outer try conditional is
6141checked according to the rules above. If the inner try conditional is in the
6142try block of the outer try conditional, its catch clauses are checked, but
6143otherwise only the finally clause is executed. It does not matter for
6144nesting, whether the inner try conditional is directly contained in the outer
6145one, or whether the outer one sources a script or calls a function containing
6146the inner try conditional.
6147
6148When none of the active try conditionals catches an exception, just their
6149finally clauses are executed. Thereafter, the script processing terminates.
6150An error message is displayed in case of an uncaught exception explicitly
6151thrown by a ":throw" command. For uncaught error and interrupt exceptions
6152implicitly raised by Vim, the error message(s) or interrupt message are shown
6153as usual.
6154
6155For examples see |throw-catch|.
6156
6157
6158EXAMINING EXCEPTION HANDLING CODE *except-examine*
6159
6160Exception handling code can get tricky. If you are in doubt what happens, set
6161'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
6162script file. Then you see when an exception is thrown, discarded, caught, or
6163finished. When using a verbosity level of at least 14, things pending in
6164a finally clause are also shown. This information is also given in debug mode
6165(see |debug-scripts|).
6166
6167
6168THROWING AND CATCHING EXCEPTIONS *throw-catch*
6169
6170You can throw any number or string as an exception. Use the |:throw| command
6171and pass the value to be thrown as argument: >
6172 :throw 4711
6173 :throw "string"
6174< *throw-expression*
6175You can also specify an expression argument. The expression is then evaluated
6176first, and the result is thrown: >
6177 :throw 4705 + strlen("string")
6178 :throw strpart("strings", 0, 6)
6179
6180An exception might be thrown during evaluation of the argument of the ":throw"
6181command. Unless it is caught there, the expression evaluation is abandoned.
6182The ":throw" command then does not throw a new exception.
6183 Example: >
6184
6185 :function! Foo(arg)
6186 : try
6187 : throw a:arg
6188 : catch /foo/
6189 : endtry
6190 : return 1
6191 :endfunction
6192 :
6193 :function! Bar()
6194 : echo "in Bar"
6195 : return 4710
6196 :endfunction
6197 :
6198 :throw Foo("arrgh") + Bar()
6199
6200This throws "arrgh", and "in Bar" is not displayed since Bar() is not
6201executed. >
6202 :throw Foo("foo") + Bar()
6203however displays "in Bar" and throws 4711.
6204
6205Any other command that takes an expression as argument might also be
6206abandoned by an (uncaught) exception during the expression evaluation. The
6207exception is then propagated to the caller of the command.
6208 Example: >
6209
6210 :if Foo("arrgh")
6211 : echo "then"
6212 :else
6213 : echo "else"
6214 :endif
6215
6216Here neither of "then" or "else" is displayed.
6217
6218 *catch-order*
6219Exceptions can be caught by a try conditional with one or more |:catch|
6220commands, see |try-conditionals|. The values to be caught by each ":catch"
6221command can be specified as a pattern argument. The subsequent catch clause
6222gets executed when a matching exception is caught.
6223 Example: >
6224
6225 :function! Foo(value)
6226 : try
6227 : throw a:value
6228 : catch /^\d\+$/
6229 : echo "Number thrown"
6230 : catch /.*/
6231 : echo "String thrown"
6232 : endtry
6233 :endfunction
6234 :
6235 :call Foo(0x1267)
6236 :call Foo('string')
6237
6238The first call to Foo() displays "Number thrown", the second "String thrown".
6239An exception is matched against the ":catch" commands in the order they are
6240specified. Only the first match counts. So you should place the more
6241specific ":catch" first. The following order does not make sense: >
6242
6243 : catch /.*/
6244 : echo "String thrown"
6245 : catch /^\d\+$/
6246 : echo "Number thrown"
6247
6248The first ":catch" here matches always, so that the second catch clause is
6249never taken.
6250
6251 *throw-variables*
6252If you catch an exception by a general pattern, you may access the exact value
6253in the variable |v:exception|: >
6254
6255 : catch /^\d\+$/
6256 : echo "Number thrown. Value is" v:exception
6257
6258You may also be interested where an exception was thrown. This is stored in
6259|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
6260exception most recently caught as long it is not finished.
6261 Example: >
6262
6263 :function! Caught()
6264 : if v:exception != ""
6265 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
6266 : else
6267 : echo 'Nothing caught'
6268 : endif
6269 :endfunction
6270 :
6271 :function! Foo()
6272 : try
6273 : try
6274 : try
6275 : throw 4711
6276 : finally
6277 : call Caught()
6278 : endtry
6279 : catch /.*/
6280 : call Caught()
6281 : throw "oops"
6282 : endtry
6283 : catch /.*/
6284 : call Caught()
6285 : finally
6286 : call Caught()
6287 : endtry
6288 :endfunction
6289 :
6290 :call Foo()
6291
6292This displays >
6293
6294 Nothing caught
6295 Caught "4711" in function Foo, line 4
6296 Caught "oops" in function Foo, line 10
6297 Nothing caught
6298
6299A practical example: The following command ":LineNumber" displays the line
6300number in the script or function where it has been used: >
6301
6302 :function! LineNumber()
6303 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
6304 :endfunction
6305 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
6306<
6307 *try-nested*
6308An exception that is not caught by a try conditional can be caught by
6309a surrounding try conditional: >
6310
6311 :try
6312 : try
6313 : throw "foo"
6314 : catch /foobar/
6315 : echo "foobar"
6316 : finally
6317 : echo "inner finally"
6318 : endtry
6319 :catch /foo/
6320 : echo "foo"
6321 :endtry
6322
6323The inner try conditional does not catch the exception, just its finally
6324clause is executed. The exception is then caught by the outer try
6325conditional. The example displays "inner finally" and then "foo".
6326
6327 *throw-from-catch*
6328You can catch an exception and throw a new one to be caught elsewhere from the
6329catch clause: >
6330
6331 :function! Foo()
6332 : throw "foo"
6333 :endfunction
6334 :
6335 :function! Bar()
6336 : try
6337 : call Foo()
6338 : catch /foo/
6339 : echo "Caught foo, throw bar"
6340 : throw "bar"
6341 : endtry
6342 :endfunction
6343 :
6344 :try
6345 : call Bar()
6346 :catch /.*/
6347 : echo "Caught" v:exception
6348 :endtry
6349
6350This displays "Caught foo, throw bar" and then "Caught bar".
6351
6352 *rethrow*
6353There is no real rethrow in the Vim script language, but you may throw
6354"v:exception" instead: >
6355
6356 :function! Bar()
6357 : try
6358 : call Foo()
6359 : catch /.*/
6360 : echo "Rethrow" v:exception
6361 : throw v:exception
6362 : endtry
6363 :endfunction
6364< *try-echoerr*
6365Note that this method cannot be used to "rethrow" Vim error or interrupt
6366exceptions, because it is not possible to fake Vim internal exceptions.
6367Trying so causes an error exception. You should throw your own exception
6368denoting the situation. If you want to cause a Vim error exception containing
6369the original error exception value, you can use the |:echoerr| command: >
6370
6371 :try
6372 : try
6373 : asdf
6374 : catch /.*/
6375 : echoerr v:exception
6376 : endtry
6377 :catch /.*/
6378 : echo v:exception
6379 :endtry
6380
6381This code displays
6382
6383 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
6384
6385
6386CLEANUP CODE *try-finally*
6387
6388Scripts often change global settings and restore them at their end. If the
6389user however interrupts the script by pressing CTRL-C, the settings remain in
6390an inconsistent state. The same may happen to you in the development phase of
6391a script when an error occurs or you explicitly throw an exception without
6392catching it. You can solve these problems by using a try conditional with
6393a finally clause for restoring the settings. Its execution is guaranteed on
6394normal control flow, on error, on an explicit ":throw", and on interrupt.
6395(Note that errors and interrupts from inside the try conditional are converted
6396to exceptions. When not caught, they terminate the script after the finally
6397clause has been executed.)
6398Example: >
6399
6400 :try
6401 : let s:saved_ts = &ts
6402 : set ts=17
6403 :
6404 : " Do the hard work here.
6405 :
6406 :finally
6407 : let &ts = s:saved_ts
6408 : unlet s:saved_ts
6409 :endtry
6410
6411This method should be used locally whenever a function or part of a script
6412changes global settings which need to be restored on failure or normal exit of
6413that function or script part.
6414
6415 *break-finally*
6416Cleanup code works also when the try block or a catch clause is left by
6417a ":continue", ":break", ":return", or ":finish".
6418 Example: >
6419
6420 :let first = 1
6421 :while 1
6422 : try
6423 : if first
6424 : echo "first"
6425 : let first = 0
6426 : continue
6427 : else
6428 : throw "second"
6429 : endif
6430 : catch /.*/
6431 : echo v:exception
6432 : break
6433 : finally
6434 : echo "cleanup"
6435 : endtry
6436 : echo "still in while"
6437 :endwhile
6438 :echo "end"
6439
6440This displays "first", "cleanup", "second", "cleanup", and "end". >
6441
6442 :function! Foo()
6443 : try
6444 : return 4711
6445 : finally
6446 : echo "cleanup\n"
6447 : endtry
6448 : echo "Foo still active"
6449 :endfunction
6450 :
6451 :echo Foo() "returned by Foo"
6452
6453This displays "cleanup" and "4711 returned by Foo". You don't need to add an
6454extra ":return" in the finally clause. (Above all, this would override the
6455return value.)
6456
6457 *except-from-finally*
6458Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
6459a finally clause is possible, but not recommended since it abandons the
6460cleanup actions for the try conditional. But, of course, interrupt and error
6461exceptions might get raised from a finally clause.
6462 Example where an error in the finally clause stops an interrupt from
6463working correctly: >
6464
6465 :try
6466 : try
6467 : echo "Press CTRL-C for interrupt"
6468 : while 1
6469 : endwhile
6470 : finally
6471 : unlet novar
6472 : endtry
6473 :catch /novar/
6474 :endtry
6475 :echo "Script still running"
6476 :sleep 1
6477
6478If you need to put commands that could fail into a finally clause, you should
6479think about catching or ignoring the errors in these commands, see
6480|catch-errors| and |ignore-errors|.
6481
6482
6483CATCHING ERRORS *catch-errors*
6484
6485If you want to catch specific errors, you just have to put the code to be
6486watched in a try block and add a catch clause for the error message. The
6487presence of the try conditional causes all errors to be converted to an
6488exception. No message is displayed and |v:errmsg| is not set then. To find
6489the right pattern for the ":catch" command, you have to know how the format of
6490the error exception is.
6491 Error exceptions have the following format: >
6492
6493 Vim({cmdname}):{errmsg}
6494or >
6495 Vim:{errmsg}
6496
6497{cmdname} is the name of the command that failed; the second form is used when
6498the command name is not known. {errmsg} is the error message usually produced
6499when the error occurs outside try conditionals. It always begins with
6500a capital "E", followed by a two or three-digit error number, a colon, and
6501a space.
6502
6503Examples:
6504
6505The command >
6506 :unlet novar
6507normally produces the error message >
6508 E108: No such variable: "novar"
6509which is converted inside try conditionals to an exception >
6510 Vim(unlet):E108: No such variable: "novar"
6511
6512The command >
6513 :dwim
6514normally produces the error message >
6515 E492: Not an editor command: dwim
6516which is converted inside try conditionals to an exception >
6517 Vim:E492: Not an editor command: dwim
6518
6519You can catch all ":unlet" errors by a >
6520 :catch /^Vim(unlet):/
6521or all errors for misspelled command names by a >
6522 :catch /^Vim:E492:/
6523
6524Some error messages may be produced by different commands: >
6525 :function nofunc
6526and >
6527 :delfunction nofunc
6528both produce the error message >
6529 E128: Function name must start with a capital: nofunc
6530which is converted inside try conditionals to an exception >
6531 Vim(function):E128: Function name must start with a capital: nofunc
6532or >
6533 Vim(delfunction):E128: Function name must start with a capital: nofunc
6534respectively. You can catch the error by its number independently on the
6535command that caused it if you use the following pattern: >
6536 :catch /^Vim(\a\+):E128:/
6537
6538Some commands like >
6539 :let x = novar
6540produce multiple error messages, here: >
6541 E121: Undefined variable: novar
6542 E15: Invalid expression: novar
6543Only the first is used for the exception value, since it is the most specific
6544one (see |except-several-errors|). So you can catch it by >
6545 :catch /^Vim(\a\+):E121:/
6546
6547You can catch all errors related to the name "nofunc" by >
6548 :catch /\<nofunc\>/
6549
6550You can catch all Vim errors in the ":write" and ":read" commands by >
6551 :catch /^Vim(\(write\|read\)):E\d\+:/
6552
6553You can catch all Vim errors by the pattern >
6554 :catch /^Vim\((\a\+)\)\=:E\d\+:/
6555<
6556 *catch-text*
6557NOTE: You should never catch the error message text itself: >
6558 :catch /No such variable/
6559only works in the english locale, but not when the user has selected
6560a different language by the |:language| command. It is however helpful to
6561cite the message text in a comment: >
6562 :catch /^Vim(\a\+):E108:/ " No such variable
6563
6564
6565IGNORING ERRORS *ignore-errors*
6566
6567You can ignore errors in a specific Vim command by catching them locally: >
6568
6569 :try
6570 : write
6571 :catch
6572 :endtry
6573
6574But you are strongly recommended NOT to use this simple form, since it could
6575catch more than you want. With the ":write" command, some autocommands could
6576be executed and cause errors not related to writing, for instance: >
6577
6578 :au BufWritePre * unlet novar
6579
6580There could even be such errors you are not responsible for as a script
6581writer: a user of your script might have defined such autocommands. You would
6582then hide the error from the user.
6583 It is much better to use >
6584
6585 :try
6586 : write
6587 :catch /^Vim(write):/
6588 :endtry
6589
6590which only catches real write errors. So catch only what you'd like to ignore
6591intentionally.
6592
6593For a single command that does not cause execution of autocommands, you could
6594even suppress the conversion of errors to exceptions by the ":silent!"
6595command: >
6596 :silent! nunmap k
6597This works also when a try conditional is active.
6598
6599
6600CATCHING INTERRUPTS *catch-interrupt*
6601
6602When there are active try conditionals, an interrupt (CTRL-C) is converted to
6603the exception "Vim:Interrupt". You can catch it like every exception. The
6604script is not terminated, then.
6605 Example: >
6606
6607 :function! TASK1()
6608 : sleep 10
6609 :endfunction
6610
6611 :function! TASK2()
6612 : sleep 20
6613 :endfunction
6614
6615 :while 1
6616 : let command = input("Type a command: ")
6617 : try
6618 : if command == ""
6619 : continue
6620 : elseif command == "END"
6621 : break
6622 : elseif command == "TASK1"
6623 : call TASK1()
6624 : elseif command == "TASK2"
6625 : call TASK2()
6626 : else
6627 : echo "\nIllegal command:" command
6628 : continue
6629 : endif
6630 : catch /^Vim:Interrupt$/
6631 : echo "\nCommand interrupted"
6632 : " Caught the interrupt. Continue with next prompt.
6633 : endtry
6634 :endwhile
6635
6636You can interrupt a task here by pressing CTRL-C; the script then asks for
6637a new command. If you press CTRL-C at the prompt, the script is terminated.
6638
6639For testing what happens when CTRL-C would be pressed on a specific line in
6640your script, use the debug mode and execute the |>quit| or |>interrupt|
6641command on that line. See |debug-scripts|.
6642
6643
6644CATCHING ALL *catch-all*
6645
6646The commands >
6647
6648 :catch /.*/
6649 :catch //
6650 :catch
6651
6652catch everything, error exceptions, interrupt exceptions and exceptions
6653explicitly thrown by the |:throw| command. This is useful at the top level of
6654a script in order to catch unexpected things.
6655 Example: >
6656
6657 :try
6658 :
6659 : " do the hard work here
6660 :
6661 :catch /MyException/
6662 :
6663 : " handle known problem
6664 :
6665 :catch /^Vim:Interrupt$/
6666 : echo "Script interrupted"
6667 :catch /.*/
6668 : echo "Internal error (" . v:exception . ")"
6669 : echo " - occurred at " . v:throwpoint
6670 :endtry
6671 :" end of script
6672
6673Note: Catching all might catch more things than you want. Thus, you are
6674strongly encouraged to catch only for problems that you can really handle by
6675specifying a pattern argument to the ":catch".
6676 Example: Catching all could make it nearly impossible to interrupt a script
6677by pressing CTRL-C: >
6678
6679 :while 1
6680 : try
6681 : sleep 1
6682 : catch
6683 : endtry
6684 :endwhile
6685
6686
6687EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
6688
6689Exceptions may be used during execution of autocommands. Example: >
6690
6691 :autocmd User x try
6692 :autocmd User x throw "Oops!"
6693 :autocmd User x catch
6694 :autocmd User x echo v:exception
6695 :autocmd User x endtry
6696 :autocmd User x throw "Arrgh!"
6697 :autocmd User x echo "Should not be displayed"
6698 :
6699 :try
6700 : doautocmd User x
6701 :catch
6702 : echo v:exception
6703 :endtry
6704
6705This displays "Oops!" and "Arrgh!".
6706
6707 *except-autocmd-Pre*
6708For some commands, autocommands get executed before the main action of the
6709command takes place. If an exception is thrown and not caught in the sequence
6710of autocommands, the sequence and the command that caused its execution are
6711abandoned and the exception is propagated to the caller of the command.
6712 Example: >
6713
6714 :autocmd BufWritePre * throw "FAIL"
6715 :autocmd BufWritePre * echo "Should not be displayed"
6716 :
6717 :try
6718 : write
6719 :catch
6720 : echo "Caught:" v:exception "from" v:throwpoint
6721 :endtry
6722
6723Here, the ":write" command does not write the file currently being edited (as
6724you can see by checking 'modified'), since the exception from the BufWritePre
6725autocommand abandons the ":write". The exception is then caught and the
6726script displays: >
6727
6728 Caught: FAIL from BufWrite Auto commands for "*"
6729<
6730 *except-autocmd-Post*
6731For some commands, autocommands get executed after the main action of the
6732command has taken place. If this main action fails and the command is inside
6733an active try conditional, the autocommands are skipped and an error exception
6734is thrown that can be caught by the caller of the command.
6735 Example: >
6736
6737 :autocmd BufWritePost * echo "File successfully written!"
6738 :
6739 :try
6740 : write /i/m/p/o/s/s/i/b/l/e
6741 :catch
6742 : echo v:exception
6743 :endtry
6744
6745This just displays: >
6746
6747 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
6748
6749If you really need to execute the autocommands even when the main action
6750fails, trigger the event from the catch clause.
6751 Example: >
6752
6753 :autocmd BufWritePre * set noreadonly
6754 :autocmd BufWritePost * set readonly
6755 :
6756 :try
6757 : write /i/m/p/o/s/s/i/b/l/e
6758 :catch
6759 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
6760 :endtry
6761<
6762You can also use ":silent!": >
6763
6764 :let x = "ok"
6765 :let v:errmsg = ""
6766 :autocmd BufWritePost * if v:errmsg != ""
6767 :autocmd BufWritePost * let x = "after fail"
6768 :autocmd BufWritePost * endif
6769 :try
6770 : silent! write /i/m/p/o/s/s/i/b/l/e
6771 :catch
6772 :endtry
6773 :echo x
6774
6775This displays "after fail".
6776
6777If the main action of the command does not fail, exceptions from the
6778autocommands will be catchable by the caller of the command: >
6779
6780 :autocmd BufWritePost * throw ":-("
6781 :autocmd BufWritePost * echo "Should not be displayed"
6782 :
6783 :try
6784 : write
6785 :catch
6786 : echo v:exception
6787 :endtry
6788<
6789 *except-autocmd-Cmd*
6790For some commands, the normal action can be replaced by a sequence of
6791autocommands. Exceptions from that sequence will be catchable by the caller
6792of the command.
6793 Example: For the ":write" command, the caller cannot know whether the file
6794had actually been written when the exception occurred. You need to tell it in
6795some way. >
6796
6797 :if !exists("cnt")
6798 : let cnt = 0
6799 :
6800 : autocmd BufWriteCmd * if &modified
6801 : autocmd BufWriteCmd * let cnt = cnt + 1
6802 : autocmd BufWriteCmd * if cnt % 3 == 2
6803 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6804 : autocmd BufWriteCmd * endif
6805 : autocmd BufWriteCmd * write | set nomodified
6806 : autocmd BufWriteCmd * if cnt % 3 == 0
6807 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6808 : autocmd BufWriteCmd * endif
6809 : autocmd BufWriteCmd * echo "File successfully written!"
6810 : autocmd BufWriteCmd * endif
6811 :endif
6812 :
6813 :try
6814 : write
6815 :catch /^BufWriteCmdError$/
6816 : if &modified
6817 : echo "Error on writing (file contents not changed)"
6818 : else
6819 : echo "Error after writing"
6820 : endif
6821 :catch /^Vim(write):/
6822 : echo "Error on writing"
6823 :endtry
6824
6825When this script is sourced several times after making changes, it displays
6826first >
6827 File successfully written!
6828then >
6829 Error on writing (file contents not changed)
6830then >
6831 Error after writing
6832etc.
6833
6834 *except-autocmd-ill*
6835You cannot spread a try conditional over autocommands for different events.
6836The following code is ill-formed: >
6837
6838 :autocmd BufWritePre * try
6839 :
6840 :autocmd BufWritePost * catch
6841 :autocmd BufWritePost * echo v:exception
6842 :autocmd BufWritePost * endtry
6843 :
6844 :write
6845
6846
6847EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
6848
6849Some programming languages allow to use hierarchies of exception classes or to
6850pass additional information with the object of an exception class. You can do
6851similar things in Vim.
6852 In order to throw an exception from a hierarchy, just throw the complete
6853class name with the components separated by a colon, for instance throw the
6854string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
6855 When you want to pass additional information with your exception class, add
6856it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
6857for an error when writing "myfile".
6858 With the appropriate patterns in the ":catch" command, you can catch for
6859base classes or derived classes of your hierarchy. Additional information in
6860parentheses can be cut out from |v:exception| with the ":substitute" command.
6861 Example: >
6862
6863 :function! CheckRange(a, func)
6864 : if a:a < 0
6865 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
6866 : endif
6867 :endfunction
6868 :
6869 :function! Add(a, b)
6870 : call CheckRange(a:a, "Add")
6871 : call CheckRange(a:b, "Add")
6872 : let c = a:a + a:b
6873 : if c < 0
6874 : throw "EXCEPT:MATHERR:OVERFLOW"
6875 : endif
6876 : return c
6877 :endfunction
6878 :
6879 :function! Div(a, b)
6880 : call CheckRange(a:a, "Div")
6881 : call CheckRange(a:b, "Div")
6882 : if (a:b == 0)
6883 : throw "EXCEPT:MATHERR:ZERODIV"
6884 : endif
6885 : return a:a / a:b
6886 :endfunction
6887 :
6888 :function! Write(file)
6889 : try
6890 : execute "write" a:file
6891 : catch /^Vim(write):/
6892 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
6893 : endtry
6894 :endfunction
6895 :
6896 :try
6897 :
6898 : " something with arithmetics and I/O
6899 :
6900 :catch /^EXCEPT:MATHERR:RANGE/
6901 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
6902 : echo "Range error in" function
6903 :
6904 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
6905 : echo "Math error"
6906 :
6907 :catch /^EXCEPT:IO/
6908 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
6909 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
6910 : if file !~ '^/'
6911 : let file = dir . "/" . file
6912 : endif
6913 : echo 'I/O error for "' . file . '"'
6914 :
6915 :catch /^EXCEPT/
6916 : echo "Unspecified error"
6917 :
6918 :endtry
6919
6920The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
6921a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
6922exceptions with the "Vim" prefix; they are reserved for Vim.
6923 Vim error exceptions are parameterized with the name of the command that
6924failed, if known. See |catch-errors|.
6925
6926
6927PECULIARITIES
6928 *except-compat*
6929The exception handling concept requires that the command sequence causing the
6930exception is aborted immediately and control is transferred to finally clauses
6931and/or a catch clause.
6932
6933In the Vim script language there are cases where scripts and functions
6934continue after an error: in functions without the "abort" flag or in a command
6935after ":silent!", control flow goes to the following line, and outside
6936functions, control flow goes to the line following the outermost ":endwhile"
6937or ":endif". On the other hand, errors should be catchable as exceptions
6938(thus, requiring the immediate abortion).
6939
6940This problem has been solved by converting errors to exceptions and using
6941immediate abortion (if not suppressed by ":silent!") only when a try
6942conditional is active. This is no restriction since an (error) exception can
6943be caught only from an active try conditional. If you want an immediate
6944termination without catching the error, just use a try conditional without
6945catch clause. (You can cause cleanup code being executed before termination
6946by specifying a finally clause.)
6947
6948When no try conditional is active, the usual abortion and continuation
6949behavior is used instead of immediate abortion. This ensures compatibility of
6950scripts written for Vim 6.1 and earlier.
6951
6952However, when sourcing an existing script that does not use exception handling
6953commands (or when calling one of its functions) from inside an active try
6954conditional of a new script, you might change the control flow of the existing
6955script on error. You get the immediate abortion on error and can catch the
6956error in the new script. If however the sourced script suppresses error
6957messages by using the ":silent!" command (checking for errors by testing
6958|v:errmsg| if appropriate), its execution path is not changed. The error is
6959not converted to an exception. (See |:silent|.) So the only remaining cause
6960where this happens is for scripts that don't care about errors and produce
6961error messages. You probably won't want to use such code from your new
6962scripts.
6963
6964 *except-syntax-err*
6965Syntax errors in the exception handling commands are never caught by any of
6966the ":catch" commands of the try conditional they belong to. Its finally
6967clauses, however, is executed.
6968 Example: >
6969
6970 :try
6971 : try
6972 : throw 4711
6973 : catch /\(/
6974 : echo "in catch with syntax error"
6975 : catch
6976 : echo "inner catch-all"
6977 : finally
6978 : echo "inner finally"
6979 : endtry
6980 :catch
6981 : echo 'outer catch-all caught "' . v:exception . '"'
6982 : finally
6983 : echo "outer finally"
6984 :endtry
6985
6986This displays: >
6987 inner finally
6988 outer catch-all caught "Vim(catch):E54: Unmatched \("
6989 outer finally
6990The original exception is discarded and an error exception is raised, instead.
6991
6992 *except-single-line*
6993The ":try", ":catch", ":finally", and ":endtry" commands can be put on
6994a single line, but then syntax errors may make it difficult to recognize the
6995"catch" line, thus you better avoid this.
6996 Example: >
6997 :try | unlet! foo # | catch | endtry
6998raises an error exception for the trailing characters after the ":unlet!"
6999argument, but does not see the ":catch" and ":endtry" commands, so that the
7000error exception is discarded and the "E488: Trailing characters" message gets
7001displayed.
7002
7003 *except-several-errors*
7004When several errors appear in a single command, the first error message is
7005usually the most specific one and therefor converted to the error exception.
7006 Example: >
7007 echo novar
7008causes >
7009 E121: Undefined variable: novar
7010 E15: Invalid expression: novar
7011The value of the error exception inside try conditionals is: >
7012 Vim(echo):E121: Undefined variable: novar
7013< *except-syntax-error*
7014But when a syntax error is detected after a normal error in the same command,
7015the syntax error is used for the exception being thrown.
7016 Example: >
7017 unlet novar #
7018causes >
7019 E108: No such variable: "novar"
7020 E488: Trailing characters
7021The value of the error exception inside try conditionals is: >
7022 Vim(unlet):E488: Trailing characters
7023This is done because the syntax error might change the execution path in a way
7024not intended by the user. Example: >
7025 try
7026 try | unlet novar # | catch | echo v:exception | endtry
7027 catch /.*/
7028 echo "outer catch:" v:exception
7029 endtry
7030This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
7031a "E600: Missing :endtry" error message is given, see |except-single-line|.
7032
7033==============================================================================
70349. Examples *eval-examples*
7035
7036Printing in Hex ~
7037>
7038 :" The function Nr2Hex() returns the Hex string of a number.
7039 :func Nr2Hex(nr)
7040 : let n = a:nr
7041 : let r = ""
7042 : while n
7043 : let r = '0123456789ABCDEF'[n % 16] . r
7044 : let n = n / 16
7045 : endwhile
7046 : return r
7047 :endfunc
7048
7049 :" The function String2Hex() converts each character in a string to a two
7050 :" character Hex string.
7051 :func String2Hex(str)
7052 : let out = ''
7053 : let ix = 0
7054 : while ix < strlen(a:str)
7055 : let out = out . Nr2Hex(char2nr(a:str[ix]))
7056 : let ix = ix + 1
7057 : endwhile
7058 : return out
7059 :endfunc
7060
7061Example of its use: >
7062 :echo Nr2Hex(32)
7063result: "20" >
7064 :echo String2Hex("32")
7065result: "3332"
7066
7067
7068Sorting lines (by Robert Webb) ~
7069
7070Here is a Vim script to sort lines. Highlight the lines in Vim and type
7071":Sort". This doesn't call any external programs so it'll work on any
7072platform. The function Sort() actually takes the name of a comparison
7073function as its argument, like qsort() does in C. So you could supply it
7074with different comparison functions in order to sort according to date etc.
7075>
7076 :" Function for use with Sort(), to compare two strings.
7077 :func! Strcmp(str1, str2)
7078 : if (a:str1 < a:str2)
7079 : return -1
7080 : elseif (a:str1 > a:str2)
7081 : return 1
7082 : else
7083 : return 0
7084 : endif
7085 :endfunction
7086
7087 :" Sort lines. SortR() is called recursively.
7088 :func! SortR(start, end, cmp)
7089 : if (a:start >= a:end)
7090 : return
7091 : endif
7092 : let partition = a:start - 1
7093 : let middle = partition
7094 : let partStr = getline((a:start + a:end) / 2)
7095 : let i = a:start
7096 : while (i <= a:end)
7097 : let str = getline(i)
7098 : exec "let result = " . a:cmp . "(str, partStr)"
7099 : if (result <= 0)
7100 : " Need to put it before the partition. Swap lines i and partition.
7101 : let partition = partition + 1
7102 : if (result == 0)
7103 : let middle = partition
7104 : endif
7105 : if (i != partition)
7106 : let str2 = getline(partition)
7107 : call setline(i, str2)
7108 : call setline(partition, str)
7109 : endif
7110 : endif
7111 : let i = i + 1
7112 : endwhile
7113
7114 : " Now we have a pointer to the "middle" element, as far as partitioning
7115 : " goes, which could be anywhere before the partition. Make sure it is at
7116 : " the end of the partition.
7117 : if (middle != partition)
7118 : let str = getline(middle)
7119 : let str2 = getline(partition)
7120 : call setline(middle, str2)
7121 : call setline(partition, str)
7122 : endif
7123 : call SortR(a:start, partition - 1, a:cmp)
7124 : call SortR(partition + 1, a:end, a:cmp)
7125 :endfunc
7126
7127 :" To Sort a range of lines, pass the range to Sort() along with the name of a
7128 :" function that will compare two lines.
7129 :func! Sort(cmp) range
7130 : call SortR(a:firstline, a:lastline, a:cmp)
7131 :endfunc
7132
7133 :" :Sort takes a range of lines and sorts them.
7134 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
7135<
7136 *sscanf*
7137There is no sscanf() function in Vim. If you need to extract parts from a
7138line, you can use matchstr() and substitute() to do it. This example shows
7139how to get the file name, line number and column number out of a line like
7140"foobar.txt, 123, 45". >
7141 :" Set up the match bit
7142 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
7143 :"get the part matching the whole expression
7144 :let l = matchstr(line, mx)
7145 :"get each item out of the match
7146 :let file = substitute(l, mx, '\1', '')
7147 :let lnum = substitute(l, mx, '\2', '')
7148 :let col = substitute(l, mx, '\3', '')
7149
7150The input is in the variable "line", the results in the variables "file",
7151"lnum" and "col". (idea from Michael Geddes)
7152
7153==============================================================================
715410. No +eval feature *no-eval-feature*
7155
7156When the |+eval| feature was disabled at compile time, none of the expression
7157evaluation commands are available. To prevent this from causing Vim scripts
7158to generate all kinds of errors, the ":if" and ":endif" commands are still
7159recognized, though the argument of the ":if" and everything between the ":if"
7160and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
7161only if the commands are at the start of the line. The ":else" command is not
7162recognized.
7163
7164Example of how to avoid executing commands when the |+eval| feature is
7165missing: >
7166
7167 :if 1
7168 : echo "Expression evaluation is compiled in"
7169 :else
7170 : echo "You will _never_ see this message"
7171 :endif
7172
7173==============================================================================
717411. The sandbox *eval-sandbox* *sandbox* *E48*
7175
7176The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
7177options are evaluated in a sandbox. This means that you are protected from
7178these expressions having nasty side effects. This gives some safety for when
7179these options are set from a modeline. It is also used when the command from
Bram Moolenaarebefac62005-12-28 22:39:57 +00007180a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007181The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007182
7183These items are not allowed in the sandbox:
7184 - changing the buffer text
7185 - defining or changing mapping, autocommands, functions, user commands
7186 - setting certain options (see |option-summary|)
7187 - executing a shell command
7188 - reading or writing a file
7189 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00007190 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007191This is not guaranteed 100% secure, but it should block most attacks.
7192
7193 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00007194:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007195 option that may have been set from a modeline, e.g.
7196 'foldexpr'.
7197
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007198 *sandbox-option*
7199A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00007200have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007201restrictive, thus this only happens when the option was set from an insecure
7202location. Insecure in this context are:
7203- sourcing a .vimrc or .exrc in the current directlry
7204- while executing in the sandbox
7205- value coming from a modeline
7206
7207Note that when in the sandbox and saving an option value and restoring it, the
7208option will still be marked as it was set in the sandbox.
7209
7210==============================================================================
721112. Textlock *textlock*
7212
7213In a few situations it is not allowed to change the text in the buffer, jump
7214to another window and some other things that might confuse or break what Vim
7215is currently doing. This mostly applies to things that happen when Vim is
7216actually doing something else. For example, evaluating the 'balloonexpr' may
7217happen any moment the mouse cursor is resting at some position.
7218
7219This is not allowed when the textlock is active:
7220 - changing the buffer text
7221 - jumping to another buffer or window
7222 - editing another file
7223 - closing a window or quitting Vim
7224 - etc.
7225
Bram Moolenaar071d4272004-06-13 20:20:40 +00007226
7227 vim:tw=78:ts=8:ft=help:norl: