blob: caafd75ac65d0b6fa3672704a321b63dc3c8bbd3 [file] [log] [blame]
Bram Moolenaar60a495f2006-10-03 12:44:42 +00001*eval.txt* For Vim version 7.0. Last change: 2006 Sep 22
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 Moolenaar910f66f2006-04-05 20:41:53 +0000113A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
114cannot have 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 Moolenaarf9393ef2006-04-24 19:47:27 +0000152List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000153 :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
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000195similar to -1.
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000196 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
197 :let shortlist = mylist[2:2] " List with one item: [3]
198 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000199
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000200If the first index is beyond the last item of the List or the second item is
201before the first item, the result is an empty list. There is no error
202message.
203
204If the second index is equal to or greater than the length of the list the
205length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000206 :let mylist = [0, 1, 2, 3]
207 :echo mylist[2:8] " result: [2, 3]
208
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000209NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
210using a single letter variable before the ":". Insert a space when needed:
211mylist[s : e].
212
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000213
Bram Moolenaar13065c42005-01-08 16:08:21 +0000214List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000215 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000216When variable "aa" is a list and you assign it to another variable "bb", both
217variables refer to the same list. Thus changing the list "aa" will also
218change "bb": >
219 :let aa = [1, 2, 3]
220 :let bb = aa
221 :call add(aa, 4)
222 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000223< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000224
225Making a copy of a list is done with the |copy()| function. Using [:] also
226works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000227a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228 :let aa = [[1, 'a'], 2, 3]
229 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000230 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231 :let aa[0][1] = 'aaa'
232 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000233< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000234 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000235< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000236
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000237To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000238copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000239
240The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000241List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000242the same value. >
243 :let alist = [1, 2, 3]
244 :let blist = [1, 2, 3]
245 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000246< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000247 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000248< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000250Note about comparing lists: Two lists are considered equal if they have the
251same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000252exception: When comparing a number with a string they are considered
253different. There is no automatic type conversion, as with using "==" on
254variables. Example: >
255 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000256< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000257 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000258< 0
259
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000260Thus comparing Lists is more strict than comparing numbers and strings. You
261can compare simple values this way too by putting them in a string: >
262
263 :let a = 5
264 :let b = "5"
265 echo a == b
266< 1 >
267 echo [a] == [b]
268< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000269
Bram Moolenaar13065c42005-01-08 16:08:21 +0000270
271List unpack ~
272
273To unpack the items in a list to individual variables, put the variables in
274square brackets, like list items: >
275 :let [var1, var2] = mylist
276
277When the number of variables does not match the number of items in the list
278this produces an error. To handle any extra items from the list append ";"
279and a variable name: >
280 :let [var1, var2; rest] = mylist
281
282This works like: >
283 :let var1 = mylist[0]
284 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000285 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000286
287Except that there is no error if there are only two items. "rest" will be an
288empty list then.
289
290
291List modification ~
292 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000293To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000294 :let list[4] = "four"
295 :let listlist[0][3] = item
296
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000297To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000298modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000299 :let list[3:5] = [3, 4, 5]
300
Bram Moolenaar13065c42005-01-08 16:08:21 +0000301Adding and removing items from a list is done with functions. Here are a few
302examples: >
303 :call insert(list, 'a') " prepend item 'a'
304 :call insert(list, 'a', 3) " insert item 'a' before list[3]
305 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000306 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000307 :call extend(list, [1, 2]) " extend the list with two more items
308 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000309 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000310 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000311 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000312 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000313
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000314Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000315 :call sort(list) " sort a list alphabetically
316 :call reverse(list) " reverse the order of items
317
Bram Moolenaar13065c42005-01-08 16:08:21 +0000318
319For loop ~
320
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000321The |:for| loop executes commands for each item in a list. A variable is set
322to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323 :for item in mylist
324 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000325 :endfor
326
327This works like: >
328 :let index = 0
329 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000330 : let item = mylist[index]
331 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000332 : let index = index + 1
333 :endwhile
334
335Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000336results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000337the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000338
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000339If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000340function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000341
Bram Moolenaar13065c42005-01-08 16:08:21 +0000342Just like the |:let| command, |:for| also accepts a list of variables. This
343requires the argument to be a list of lists. >
344 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
345 : call Doit(lnum, col)
346 :endfor
347
348This works like a |:let| command is done for each list item. Again, the types
349must remain the same to avoid an error.
350
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000351It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000352 :for [i, j; rest] in listlist
353 : call Doit(i, j)
354 : if !empty(rest)
355 : echo "remainder: " . string(rest)
356 : endif
357 :endfor
358
359
360List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000361 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000362Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000363 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000364 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000365 :let l = len(list) " number of items in list
366 :let big = max(list) " maximum value in list
367 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000368 :let xs = count(list, 'x') " count nr of times 'x' appears in list
369 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000370 :let lines = getline(1, 10) " get ten text lines from buffer
371 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000372 :let list = split("a b c") " create list from items in a string
373 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000374 :let s = string(list) " String representation of list
375 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000376
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000377Don't forget that a combination of features can make things simple. For
378example, to add up all the numbers in a list: >
379 :exe 'let sum = ' . join(nrlist, '+')
380
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381
Bram Moolenaard8b02732005-01-14 21:48:43 +00003821.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000383 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000384A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000385entry can be located with the key. The entries are stored without a specific
386ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000387
388
389Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000390 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000391A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000392braces. Each entry has a key and a value, separated by a colon. Each key can
393only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000394 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
395 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000396< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000397A key is always a String. You can use a Number, it will be converted to a
398String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399entry. Note that the String '04' and the Number 04 are different, since the
400Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000401
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000402A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000403nested Dictionary: >
404 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
405
406An extra comma after the last entry is ignored.
407
408
409Accessing entries ~
410
411The normal way to access an entry is by putting the key in square brackets: >
412 :let val = mydict["one"]
413 :let mydict["four"] = 4
414
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000415You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000416
417For keys that consist entirely of letters, digits and underscore the following
418form can be used |expr-entry|: >
419 :let val = mydict.one
420 :let mydict.four = 4
421
422Since an entry can be any type, also a List and a Dictionary, the indexing and
423key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000424 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000425
426
427Dictionary to List conversion ~
428
429You may want to loop over the entries in a dictionary. For this you need to
430turn the Dictionary into a List and pass it to |:for|.
431
432Most often you want to loop over the keys, using the |keys()| function: >
433 :for key in keys(mydict)
434 : echo key . ': ' . mydict[key]
435 :endfor
436
437The List of keys is unsorted. You may want to sort them first: >
438 :for key in sort(keys(mydict))
439
440To loop over the values use the |values()| function: >
441 :for v in values(mydict)
442 : echo "value: " . v
443 :endfor
444
445If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000446a List in which each item is a List with two items, the key and the value: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000447 :for entry in items(mydict)
448 : echo entry[0] . ': ' . entry[1]
449 :endfor
450
451
452Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000453 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000454Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
455Dictionary. Otherwise, assignment results in referring to the same
456Dictionary: >
457 :let onedict = {'a': 1, 'b': 2}
458 :let adict = onedict
459 :let adict['a'] = 11
460 :echo onedict['a']
461 11
462
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000463Two Dictionaries compare equal if all the key-value pairs compare equal. For
464more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000465
466
467Dictionary modification ~
468 *dict-modification*
469To change an already existing entry of a Dictionary, or to add a new entry,
470use |:let| this way: >
471 :let dict[4] = "four"
472 :let dict['one'] = item
473
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000474Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
475Three ways to remove the entry with key "aaa" from dict: >
476 :let i = remove(dict, 'aaa')
477 :unlet dict.aaa
478 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479
480Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000481 :call extend(adict, bdict)
482This extends adict with all entries from bdict. Duplicate keys cause entries
483in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000484Note that the order of entries in a Dictionary is irrelevant, thus don't
485expect ":echo adict" to show the items from bdict after the older entries in
486adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000487
488Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaare2cc9702005-03-15 22:43:58 +0000489 :call filter(dict 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000490This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000491
492
493Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000494 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000495When a function is defined with the "dict" attribute it can be used in a
496special way with a dictionary. Example: >
497 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000498 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000499 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000500 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
501 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000502
503This is like a method in object oriented programming. The entry in the
504Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
505the function was invoked from.
506
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000507It is also possible to add a function without the "dict" attribute as a
508Funcref to a Dictionary, but the "self" variable is not available then.
509
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000510 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000511To avoid the extra name for the function it can be defined and directly
512assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000513 :let mydict = {'data': [0, 1, 2, 3]}
514 :function mydict.len() dict
515 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000516 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000517 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000518
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000519The function will then get a number and the value of dict.len is a |Funcref|
520that references this function. The function can only be used through a
521|Funcref|. It will automatically be deleted when there is no |Funcref|
522remaining that refers to it.
523
524It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000525
526
527Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000528 *E715*
529Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000530 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
531 :if empty(dict) " TRUE if dict is empty
532 :let l = len(dict) " number of items in dict
533 :let big = max(dict) " maximum value in dict
534 :let small = min(dict) " minimum value in dict
535 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
536 :let s = string(dict) " String representation of dict
537 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000538
539
5401.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000541 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000542If you need to know the type of a variable or expression, use the |type()|
543function.
544
545When the '!' flag is included in the 'viminfo' option, global variables that
546start with an uppercase letter, and don't contain a lowercase letter, are
547stored in the viminfo file |viminfo-file|.
548
549When the 'sessionoptions' option contains "global", global variables that
550start with an uppercase letter and contain at least one lowercase letter are
551stored in the session file |session-file|.
552
553variable name can be stored where ~
554my_var_6 not
555My_Var_6 session file
556MY_VAR_6 viminfo file
557
558
559It's possible to form a variable name with curly braces, see
560|curly-braces-names|.
561
562==============================================================================
5632. Expression syntax *expression-syntax*
564
565Expression syntax summary, from least to most significant:
566
567|expr1| expr2 ? expr1 : expr1 if-then-else
568
569|expr2| expr3 || expr3 .. logical OR
570
571|expr3| expr4 && expr4 .. logical AND
572
573|expr4| expr5 == expr5 equal
574 expr5 != expr5 not equal
575 expr5 > expr5 greater than
576 expr5 >= expr5 greater than or equal
577 expr5 < expr5 smaller than
578 expr5 <= expr5 smaller than or equal
579 expr5 =~ expr5 regexp matches
580 expr5 !~ expr5 regexp doesn't match
581
582 expr5 ==? expr5 equal, ignoring case
583 expr5 ==# expr5 equal, match case
584 etc. As above, append ? for ignoring case, # for
585 matching case
586
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000587 expr5 is expr5 same |List| instance
588 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000589
590|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000591 expr6 - expr6 .. number subtraction
592 expr6 . expr6 .. string concatenation
593
594|expr6| expr7 * expr7 .. number multiplication
595 expr7 / expr7 .. number division
596 expr7 % expr7 .. number modulo
597
598|expr7| ! expr7 logical NOT
599 - expr7 unary minus
600 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000601
Bram Moolenaar071d4272004-06-13 20:20:40 +0000602
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000603|expr8| expr8[expr1] byte of a String or item of a |List|
604 expr8[expr1 : expr1] substring of a String or sublist of a |List|
605 expr8.name entry in a |Dictionary|
606 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000607
608|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000609 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000610 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000611 [expr1, ...] |List|
612 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000613 &option option value
614 (expr1) nested expression
615 variable internal variable
616 va{ria}ble internal variable with curly braces
617 $VAR environment variable
618 @r contents of register 'r'
619 function(expr1, ...) function call
620 func{ti}on(expr1, ...) function call with curly braces
621
622
623".." indicates that the operations in this level can be concatenated.
624Example: >
625 &nu || &list && &shell == "csh"
626
627All expressions within one level are parsed from left to right.
628
629
630expr1 *expr1* *E109*
631-----
632
633expr2 ? expr1 : expr1
634
635The expression before the '?' is evaluated to a number. If it evaluates to
636non-zero, the result is the value of the expression between the '?' and ':',
637otherwise the result is the value of the expression after the ':'.
638Example: >
639 :echo lnum == 1 ? "top" : lnum
640
641Since the first expression is an "expr2", it cannot contain another ?:. The
642other two expressions can, thus allow for recursive use of ?:.
643Example: >
644 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
645
646To keep this readable, using |line-continuation| is suggested: >
647 :echo lnum == 1
648 :\ ? "top"
649 :\ : lnum == 1000
650 :\ ? "last"
651 :\ : lnum
652
653
654expr2 and expr3 *expr2* *expr3*
655---------------
656
657 *expr-barbar* *expr-&&*
658The "||" and "&&" operators take one argument on each side. The arguments
659are (converted to) Numbers. The result is:
660
661 input output ~
662n1 n2 n1 || n2 n1 && n2 ~
663zero zero zero zero
664zero non-zero non-zero zero
665non-zero zero non-zero zero
666non-zero non-zero non-zero non-zero
667
668The operators can be concatenated, for example: >
669
670 &nu || &list && &shell == "csh"
671
672Note that "&&" takes precedence over "||", so this has the meaning of: >
673
674 &nu || (&list && &shell == "csh")
675
676Once the result is known, the expression "short-circuits", that is, further
677arguments are not evaluated. This is like what happens in C. For example: >
678
679 let a = 1
680 echo a || b
681
682This is valid even if there is no variable called "b" because "a" is non-zero,
683so the result must be non-zero. Similarly below: >
684
685 echo exists("b") && b == "yes"
686
687This is valid whether "b" has been defined or not. The second clause will
688only be evaluated if "b" has been defined.
689
690
691expr4 *expr4*
692-----
693
694expr5 {cmp} expr5
695
696Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
697if it evaluates to true.
698
699 *expr-==* *expr-!=* *expr->* *expr->=*
700 *expr-<* *expr-<=* *expr-=~* *expr-!~*
701 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
702 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
703 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
704 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000705 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000706 use 'ignorecase' match case ignore case ~
707equal == ==# ==?
708not equal != !=# !=?
709greater than > ># >?
710greater than or equal >= >=# >=?
711smaller than < <# <?
712smaller than or equal <= <=# <=?
713regexp matches =~ =~# =~?
714regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000715same instance is
716different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000717
718Examples:
719"abc" ==# "Abc" evaluates to 0
720"abc" ==? "Abc" evaluates to 1
721"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
722
Bram Moolenaar13065c42005-01-08 16:08:21 +0000723 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000724A |List| can only be compared with a |List| and only "equal", "not equal" and
725"is" can be used. This compares the values of the list, recursively.
726Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000727
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000728 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000729A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
730equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000731recursively. Ignoring case means case is ignored when comparing item values.
732
Bram Moolenaar13065c42005-01-08 16:08:21 +0000733 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000734A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
735equal" can be used. Case is never ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000736
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000737When using "is" or "isnot" with a |List| this checks if the expressions are
738referring to the same |List| instance. A copy of a |List| is different from
739the original |List|. When using "is" without a |List| it is equivalent to
740using "equal", using "isnot" equivalent to using "not equal". Except that a
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000741different type means the values are different. "4 == '4'" is true, "4 is '4'"
742is false.
743
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744When comparing a String with a Number, the String is converted to a Number,
745and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
746because 'x' converted to a Number is zero.
747
748When comparing two Strings, this is done with strcmp() or stricmp(). This
749results in the mathematical difference (comparing byte values), not
750necessarily the alphabetical difference in the local language.
751
752When using the operators with a trailing '#", or the short version and
753'ignorecase' is off, the comparing is done with strcmp().
754
755When using the operators with a trailing '?', or the short version and
756'ignorecase' is set, the comparing is done with stricmp().
757
758The "=~" and "!~" operators match the lefthand argument with the righthand
759argument, which is used as a pattern. See |pattern| for what a pattern is.
760This matching is always done like 'magic' was set and 'cpoptions' is empty, no
761matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
762portable. To avoid backslashes in the regexp pattern to be doubled, use a
763single-quote string, see |literal-string|.
764Since a string is considered to be a single line, a multi-line pattern
765(containing \n, backslash-n) will not match. However, a literal NL character
766can be matched like an ordinary character. Examples:
767 "foo\nbar" =~ "\n" evaluates to 1
768 "foo\nbar" =~ "\\n" evaluates to 0
769
770
771expr5 and expr6 *expr5* *expr6*
772---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000773expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000774expr6 - expr6 .. Number subtraction *expr--*
775expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000777For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000778result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000779
780expr7 * expr7 .. number multiplication *expr-star*
781expr7 / expr7 .. number division *expr-/*
782expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000783
784For all, except ".", Strings are converted to Numbers.
785
786Note the difference between "+" and ".":
787 "123" + "456" = 579
788 "123" . "456" = "123456"
789
790When the righthand side of '/' is zero, the result is 0x7fffffff.
791When the righthand side of '%' is zero, the result is 0.
792
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000793None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000794
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795
796expr7 *expr7*
797-----
798! expr7 logical NOT *expr-!*
799- expr7 unary minus *expr-unary--*
800+ expr7 unary plus *expr-unary-+*
801
802For '!' non-zero becomes zero, zero becomes one.
803For '-' the sign of the number is changed.
804For '+' the number is unchanged.
805
806A String will be converted to a Number first.
807
808These three can be repeated and mixed. Examples:
809 !-1 == 0
810 !!8 == 1
811 --9 == 9
812
813
814expr8 *expr8*
815-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000816expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000818If expr8 is a Number or String this results in a String that contains the
819expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000820Number. Note that this doesn't recognize multi-byte encodings.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000821
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000822Index zero gives the first character. This is like it works in C. Careful:
823text column numbers start with one! Example, to get the character under the
824cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000825 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826
827If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000828String. A negative index always results in an empty string (reason: backwards
829compatibility). Use [-1:] to get the last byte.
830
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000831If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000832for possible index values. If the index is out of range this results in an
833error. Example: >
834 :let item = mylist[-1] " get last item
835
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000836Generally, if a |List| index is equal to or higher than the length of the
837|List|, or more negative than the length of the |List|, this results in an
838error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000839
Bram Moolenaard8b02732005-01-14 21:48:43 +0000840
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000841expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000842
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000843If expr8 is a Number or String this results in the substring with the bytes
844from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000845expr1b are used as a Number. Note that this doesn't recognize multi-byte
846encodings.
847
848If expr1a is omitted zero is used. If expr1b is omitted the length of the
849string minus one is used.
850
851A negative number can be used to measure from the end of the string. -1 is
852the last character, -2 the last but one, etc.
853
854If an index goes out of range for the string characters are omitted. If
855expr1b is smaller than expr1a the result is an empty string.
856
857Examples: >
858 :let c = name[-1:] " last byte of a string
859 :let c = name[-2:-2] " last but one byte of a string
860 :let s = line(".")[4:] " from the fifth byte to the end
861 :let s = s[:-3] " remove last two bytes
862
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000863If expr8 is a |List| this results in a new |List| with the items indicated by
864the indexes expr1a and expr1b. This works like with a String, as explained
865just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000866 :let l = mylist[:3] " first four items
867 :let l = mylist[4:4] " List with one item
868 :let l = mylist[:] " shallow copy of a List
869
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000870Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
871error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000872
Bram Moolenaard8b02732005-01-14 21:48:43 +0000873
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000874expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000875
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000876If expr8 is a |Dictionary| and it is followed by a dot, then the following
877name will be used as a key in the |Dictionary|. This is just like:
878expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000879
880The name must consist of alphanumeric characters, just like a variable name,
881but it may start with a number. Curly braces cannot be used.
882
883There must not be white space before or after the dot.
884
885Examples: >
886 :let dict = {"one": 1, 2: "two"}
887 :echo dict.one
888 :echo dict .2
889
890Note that the dot is also used for String concatenation. To avoid confusion
891always put spaces around the dot for String concatenation.
892
893
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000894expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000895
896When expr8 is a |Funcref| type variable, invoke the function it refers to.
897
898
899
900 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000901number
902------
903number number constant *expr-number*
904
905Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
906
907
908string *expr-string* *E114*
909------
910"string" string constant *expr-quote*
911
912Note that double quotes are used.
913
914A string constant accepts these special characters:
915\... three-digit octal number (e.g., "\316")
916\.. two-digit octal number (must be followed by non-digit)
917\. one-digit octal number (must be followed by non-digit)
918\x.. byte specified with two hex numbers (e.g., "\x1f")
919\x. byte specified with one hex number (must be followed by non-hex char)
920\X.. same as \x..
921\X. same as \x.
922\u.... character specified with up to 4 hex numbers, stored according to the
923 current value of 'encoding' (e.g., "\u02a4")
924\U.... same as \u....
925\b backspace <BS>
926\e escape <Esc>
927\f formfeed <FF>
928\n newline <NL>
929\r return <CR>
930\t tab <Tab>
931\\ backslash
932\" double quote
933\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
934
935Note that "\000" and "\x00" force the end of the string.
936
937
938literal-string *literal-string* *E115*
939---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000940'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000941
942Note that single quotes are used.
943
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000944This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000945meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000946
947Single quoted strings are useful for patterns, so that backslashes do not need
948to be doubled. These two commands are equivalent: >
949 if a =~ "\\s*"
950 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000951
952
953option *expr-option* *E112* *E113*
954------
955&option option value, local value if possible
956&g:option global option value
957&l:option local option value
958
959Examples: >
960 echo "tabstop is " . &tabstop
961 if &insertmode
962
963Any option name can be used here. See |options|. When using the local value
964and there is no buffer-local or window-local value, the global value is used
965anyway.
966
967
968register *expr-register*
969--------
970@r contents of register 'r'
971
972The result is the contents of the named register, as a single string.
973Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaare7566042005-06-17 22:00:15 +0000974register use @" or @@. See |registers| for an explanation of the available
975registers.
976
977When using the '=' register you get the expression itself, not what it
978evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000979
980
981nesting *expr-nesting* *E110*
982-------
983(expr1) nested expression
984
985
986environment variable *expr-env*
987--------------------
988$VAR environment variable
989
990The String value of any environment variable. When it is not defined, the
991result is an empty string.
992 *expr-env-expand*
993Note that there is a difference between using $VAR directly and using
994expand("$VAR"). Using it directly will only expand environment variables that
995are known inside the current Vim session. Using expand() will first try using
996the environment variables known inside the current Vim session. If that
997fails, a shell will be used to expand the variable. This can be slow, but it
998does expand all variables that the shell knows about. Example: >
999 :echo $version
1000 :echo expand("$version")
1001The first one probably doesn't echo anything, the second echoes the $version
1002variable (if your shell supports it).
1003
1004
1005internal variable *expr-variable*
1006-----------------
1007variable internal variable
1008See below |internal-variables|.
1009
1010
Bram Moolenaar05159a02005-02-26 23:04:13 +00001011function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001012-------------
1013function(expr1, ...) function call
1014See below |functions|.
1015
1016
1017==============================================================================
10183. Internal variable *internal-variables* *E121*
1019 *E461*
1020An internal variable name can be made up of letters, digits and '_'. But it
1021cannot start with a digit. It's also possible to use curly braces, see
1022|curly-braces-names|.
1023
1024An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001025An internal variable is explicitly destroyed with the ":unlet" command
1026|:unlet|.
1027Using a name that is not an internal variable or refers to a variable that has
1028been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029
1030There are several name spaces for variables. Which one is to be used is
1031specified by what is prepended:
1032
1033 (nothing) In a function: local to a function; otherwise: global
1034|buffer-variable| b: Local to the current buffer.
1035|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001036|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001037|global-variable| g: Global.
1038|local-variable| l: Local to a function.
1039|script-variable| s: Local to a |:source|'ed Vim script.
1040|function-argument| a: Function argument (only inside a function).
1041|vim-variable| v: Global, predefined by Vim.
1042
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001043The scope name by itself can be used as a |Dictionary|. For example, to
1044delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001045 :for k in keys(s:)
1046 : unlet s:[k]
1047 :endfor
1048<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001049 *buffer-variable* *b:var*
1050A variable name that is preceded with "b:" is local to the current buffer.
1051Thus you can have several "b:foo" variables, one for each buffer.
1052This kind of variable is deleted when the buffer is wiped out or deleted with
1053|:bdelete|.
1054
1055One local buffer variable is predefined:
1056 *b:changedtick-variable* *changetick*
1057b:changedtick The total number of changes to the current buffer. It is
1058 incremented for each change. An undo command is also a change
1059 in this case. This can be used to perform an action only when
1060 the buffer has changed. Example: >
1061 :if my_changedtick != b:changedtick
1062 : let my_changedtick = b:changedtick
1063 : call My_Update()
1064 :endif
1065<
1066 *window-variable* *w:var*
1067A variable name that is preceded with "w:" is local to the current window. It
1068is deleted when the window is closed.
1069
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001070 *tabpage-variable* *t:var*
1071A variable name that is preceded with "t:" is local to the current tab page,
1072It is deleted when the tab page is closed. {not available when compiled
1073without the +windows feature}
1074
Bram Moolenaar071d4272004-06-13 20:20:40 +00001075 *global-variable* *g:var*
1076Inside functions global variables are accessed with "g:". Omitting this will
1077access a variable local to a function. But "g:" can also be used in any other
1078place if you like.
1079
1080 *local-variable* *l:var*
1081Inside functions local variables are accessed without prepending anything.
1082But you can also prepend "l:" if you like.
1083
1084 *script-variable* *s:var*
1085In a Vim script variables starting with "s:" can be used. They cannot be
1086accessed from outside of the scripts, thus are local to the script.
1087
1088They can be used in:
1089- commands executed while the script is sourced
1090- functions defined in the script
1091- autocommands defined in the script
1092- functions and autocommands defined in functions and autocommands which were
1093 defined in the script (recursively)
1094- user defined commands defined in the script
1095Thus not in:
1096- other scripts sourced from this one
1097- mappings
1098- etc.
1099
1100script variables can be used to avoid conflicts with global variable names.
1101Take this example:
1102
1103 let s:counter = 0
1104 function MyCounter()
1105 let s:counter = s:counter + 1
1106 echo s:counter
1107 endfunction
1108 command Tick call MyCounter()
1109
1110You can now invoke "Tick" from any script, and the "s:counter" variable in
1111that script will not be changed, only the "s:counter" in the script where
1112"Tick" was defined is used.
1113
1114Another example that does the same: >
1115
1116 let s:counter = 0
1117 command Tick let s:counter = s:counter + 1 | echo s:counter
1118
1119When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001120script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001121defined.
1122
1123The script variables are also available when a function is defined inside a
1124function that is defined in a script. Example: >
1125
1126 let s:counter = 0
1127 function StartCounting(incr)
1128 if a:incr
1129 function MyCounter()
1130 let s:counter = s:counter + 1
1131 endfunction
1132 else
1133 function MyCounter()
1134 let s:counter = s:counter - 1
1135 endfunction
1136 endif
1137 endfunction
1138
1139This defines the MyCounter() function either for counting up or counting down
1140when calling StartCounting(). It doesn't matter from where StartCounting() is
1141called, the s:counter variable will be accessible in MyCounter().
1142
1143When the same script is sourced again it will use the same script variables.
1144They will remain valid as long as Vim is running. This can be used to
1145maintain a counter: >
1146
1147 if !exists("s:counter")
1148 let s:counter = 1
1149 echo "script executed for the first time"
1150 else
1151 let s:counter = s:counter + 1
1152 echo "script executed " . s:counter . " times now"
1153 endif
1154
1155Note that this means that filetype plugins don't get a different set of script
1156variables for each buffer. Use local buffer variables instead |b:var|.
1157
1158
1159Predefined Vim variables: *vim-variable* *v:var*
1160
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001161 *v:beval_col* *beval_col-variable*
1162v:beval_col The number of the column, over which the mouse pointer is.
1163 This is the byte index in the |v:beval_lnum| line.
1164 Only valid while evaluating the 'balloonexpr' option.
1165
1166 *v:beval_bufnr* *beval_bufnr-variable*
1167v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1168 valid while evaluating the 'balloonexpr' option.
1169
1170 *v:beval_lnum* *beval_lnum-variable*
1171v:beval_lnum The number of the line, over which the mouse pointer is. Only
1172 valid while evaluating the 'balloonexpr' option.
1173
1174 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001175v:beval_text The text under or after the mouse pointer. Usually a word as
1176 it is useful for debugging a C program. 'iskeyword' applies,
1177 but a dot and "->" before the position is included. When on a
1178 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001179 word before it. When on a Visual area within one line the
1180 highlighted text is used.
1181 Only valid while evaluating the 'balloonexpr' option.
1182
1183 *v:beval_winnr* *beval_winnr-variable*
1184v:beval_winnr The number of the window, over which the mouse pointer is. Only
1185 valid while evaluating the 'balloonexpr' option.
1186
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001187 *v:char* *char-variable*
1188v:char Argument for evaluating 'formatexpr'.
1189
Bram Moolenaar071d4272004-06-13 20:20:40 +00001190 *v:charconvert_from* *charconvert_from-variable*
1191v:charconvert_from
1192 The name of the character encoding of a file to be converted.
1193 Only valid while evaluating the 'charconvert' option.
1194
1195 *v:charconvert_to* *charconvert_to-variable*
1196v:charconvert_to
1197 The name of the character encoding of a file after conversion.
1198 Only valid while evaluating the 'charconvert' option.
1199
1200 *v:cmdarg* *cmdarg-variable*
1201v:cmdarg This variable is used for two purposes:
1202 1. The extra arguments given to a file read/write command.
1203 Currently these are "++enc=" and "++ff=". This variable is
1204 set before an autocommand event for a file read/write
1205 command is triggered. There is a leading space to make it
1206 possible to append this variable directly after the
1207 read/write command. Note: The "+cmd" argument isn't
1208 included here, because it will be executed anyway.
1209 2. When printing a PostScript file with ":hardcopy" this is
1210 the argument for the ":hardcopy" command. This can be used
1211 in 'printexpr'.
1212
1213 *v:cmdbang* *cmdbang-variable*
1214v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1215 was used the value is 1, otherwise it is 0. Note that this
1216 can only be used in autocommands. For user commands |<bang>|
1217 can be used.
1218
1219 *v:count* *count-variable*
1220v:count The count given for the last Normal mode command. Can be used
1221 to get the count before a mapping. Read-only. Example: >
1222 :map _x :<C-U>echo "the count is " . v:count<CR>
1223< Note: The <C-U> is required to remove the line range that you
1224 get when typing ':' after a count.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001225 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001226 "count" also works, for backwards compatibility.
1227
1228 *v:count1* *count1-variable*
1229v:count1 Just like "v:count", but defaults to one when no count is
1230 used.
1231
1232 *v:ctype* *ctype-variable*
1233v:ctype The current locale setting for characters of the runtime
1234 environment. This allows Vim scripts to be aware of the
1235 current locale encoding. Technical: it's the value of
1236 LC_CTYPE. When not using a locale the value is "C".
1237 This variable can not be set directly, use the |:language|
1238 command.
1239 See |multi-lang|.
1240
1241 *v:dying* *dying-variable*
1242v:dying Normally zero. When a deadly signal is caught it's set to
1243 one. When multiple signals are caught the number increases.
1244 Can be used in an autocommand to check if Vim didn't
1245 terminate normally. {only works on Unix}
1246 Example: >
1247 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1248<
1249 *v:errmsg* *errmsg-variable*
1250v:errmsg Last given error message. It's allowed to set this variable.
1251 Example: >
1252 :let v:errmsg = ""
1253 :silent! next
1254 :if v:errmsg != ""
1255 : ... handle error
1256< "errmsg" also works, for backwards compatibility.
1257
1258 *v:exception* *exception-variable*
1259v:exception The value of the exception most recently caught and not
1260 finished. See also |v:throwpoint| and |throw-variables|.
1261 Example: >
1262 :try
1263 : throw "oops"
1264 :catch /.*/
1265 : echo "caught" v:exception
1266 :endtry
1267< Output: "caught oops".
1268
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001269 *v:fcs_reason* *fcs_reason-variable*
1270v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1271 Can be used in an autocommand to decide what to do and/or what
1272 to set v:fcs_choice to. Possible values:
1273 deleted file no longer exists
1274 conflict file contents, mode or timestamp was
1275 changed and buffer is modified
1276 changed file contents has changed
1277 mode mode of file changed
1278 time only file timestamp changed
1279
1280 *v:fcs_choice* *fcs_choice-variable*
1281v:fcs_choice What should happen after a |FileChangedShell| event was
1282 triggered. Can be used in an autocommand to tell Vim what to
1283 do with the affected buffer:
1284 reload Reload the buffer (does not work if
1285 the file was deleted).
1286 ask Ask the user what to do, as if there
1287 was no autocommand. Except that when
1288 only the timestamp changed nothing
1289 will happen.
1290 <empty> Nothing, the autocommand should do
1291 everything that needs to be done.
1292 The default is empty. If another (invalid) value is used then
1293 Vim behaves like it is empty, there is no warning message.
1294
Bram Moolenaar071d4272004-06-13 20:20:40 +00001295 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001296v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001297 option used for ~
1298 'charconvert' file to be converted
1299 'diffexpr' original file
1300 'patchexpr' original file
1301 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001302 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001303
1304 *v:fname_out* *fname_out-variable*
1305v:fname_out The name of the output file. Only valid while
1306 evaluating:
1307 option used for ~
1308 'charconvert' resulting converted file (*)
1309 'diffexpr' output of diff
1310 'patchexpr' resulting patched file
1311 (*) When doing conversion for a write command (e.g., ":w
1312 file") it will be equal to v:fname_in. When doing conversion
1313 for a read command (e.g., ":e file") it will be a temporary
1314 file and different from v:fname_in.
1315
1316 *v:fname_new* *fname_new-variable*
1317v:fname_new The name of the new version of the file. Only valid while
1318 evaluating 'diffexpr'.
1319
1320 *v:fname_diff* *fname_diff-variable*
1321v:fname_diff The name of the diff (patch) file. Only valid while
1322 evaluating 'patchexpr'.
1323
1324 *v:folddashes* *folddashes-variable*
1325v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1326 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001327 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001328
1329 *v:foldlevel* *foldlevel-variable*
1330v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001331 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001332
1333 *v:foldend* *foldend-variable*
1334v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001335 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001336
1337 *v:foldstart* *foldstart-variable*
1338v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001339 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001340
Bram Moolenaar843ee412004-06-30 16:16:41 +00001341 *v:insertmode* *insertmode-variable*
1342v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1343 events. Values:
1344 i Insert mode
1345 r Replace mode
1346 v Virtual Replace mode
1347
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001348 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001349v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001350 evaluating the expression used with |map()| and |filter()|.
1351 Read-only.
1352
Bram Moolenaar071d4272004-06-13 20:20:40 +00001353 *v:lang* *lang-variable*
1354v:lang The current locale setting for messages of the runtime
1355 environment. This allows Vim scripts to be aware of the
1356 current language. Technical: it's the value of LC_MESSAGES.
1357 The value is system dependent.
1358 This variable can not be set directly, use the |:language|
1359 command.
1360 It can be different from |v:ctype| when messages are desired
1361 in a different language than what is used for character
1362 encoding. See |multi-lang|.
1363
1364 *v:lc_time* *lc_time-variable*
1365v:lc_time The current locale setting for time messages of the runtime
1366 environment. This allows Vim scripts to be aware of the
1367 current language. Technical: it's the value of LC_TIME.
1368 This variable can not be set directly, use the |:language|
1369 command. See |multi-lang|.
1370
1371 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001372v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
Bram Moolenaar57657d82006-04-21 22:12:41 +00001373 expressions, tab page number for 'guitablabel' and
1374 'guitabtooltip'. Only valid while one of these expressions is
1375 being evaluated. Read-only when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001376
1377 *v:prevcount* *prevcount-variable*
1378v:prevcount The count given for the last but one Normal mode command.
1379 This is the v:count value of the previous command. Useful if
1380 you want to cancel Visual mode and then use the count. >
1381 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1382< Read-only.
1383
Bram Moolenaar05159a02005-02-26 23:04:13 +00001384 *v:profiling* *profiling-variable*
1385v:profiling Normally zero. Set to one after using ":profile start".
1386 See |profiling|.
1387
Bram Moolenaar071d4272004-06-13 20:20:40 +00001388 *v:progname* *progname-variable*
1389v:progname Contains the name (with path removed) with which Vim was
1390 invoked. Allows you to do special initialisations for "view",
1391 "evim" etc., or any other name you might symlink to Vim.
1392 Read-only.
1393
1394 *v:register* *register-variable*
1395v:register The name of the register supplied to the last normal mode
1396 command. Empty if none were supplied. |getreg()| |setreg()|
1397
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001398 *v:scrollstart* *scrollstart-variable*
1399v:scrollstart String describing the script or function that caused the
1400 screen to scroll up. It's only set when it is empty, thus the
1401 first reason is remembered. It is set to "Unknown" for a
1402 typed command.
1403 This can be used to find out why your script causes the
1404 hit-enter prompt.
1405
Bram Moolenaar071d4272004-06-13 20:20:40 +00001406 *v:servername* *servername-variable*
1407v:servername The resulting registered |x11-clientserver| name if any.
1408 Read-only.
1409
1410 *v:shell_error* *shell_error-variable*
1411v:shell_error Result of the last shell command. When non-zero, the last
1412 shell command had an error. When zero, there was no problem.
1413 This only works when the shell returns the error code to Vim.
1414 The value -1 is often used when the command could not be
1415 executed. Read-only.
1416 Example: >
1417 :!mv foo bar
1418 :if v:shell_error
1419 : echo 'could not rename "foo" to "bar"!'
1420 :endif
1421< "shell_error" also works, for backwards compatibility.
1422
1423 *v:statusmsg* *statusmsg-variable*
1424v:statusmsg Last given status message. It's allowed to set this variable.
1425
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001426 *v:swapname* *swapname-variable*
1427v:swapname Only valid when executing |SwapExists| autocommands: Name of
1428 the swap file found. Read-only.
1429
1430 *v:swapchoice* *swapchoice-variable*
1431v:swapchoice |SwapExists| autocommands can set this to the selected choice
1432 for handling an existing swap file:
1433 'o' Open read-only
1434 'e' Edit anyway
1435 'r' Recover
1436 'd' Delete swapfile
1437 'q' Quit
1438 'a' Abort
1439 The value should be a single-character string. An empty value
1440 results in the user being asked, as would happen when there is
1441 no SwapExists autocommand. The default is empty.
1442
Bram Moolenaarb3480382005-12-11 21:33:32 +00001443 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001444v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001445 opened. Can be used for a |SwapExists| autocommand to have
1446 another Vim open the file and jump to the right place. For
1447 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001448 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001449
Bram Moolenaar071d4272004-06-13 20:20:40 +00001450 *v:termresponse* *termresponse-variable*
1451v:termresponse The escape sequence returned by the terminal for the |t_RV|
1452 termcap entry. It is set when Vim receives an escape sequence
1453 that starts with ESC [ or CSI and ends in a 'c', with only
1454 digits, ';' and '.' in between.
1455 When this option is set, the TermResponse autocommand event is
1456 fired, so that you can react to the response from the
1457 terminal.
1458 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1459 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1460 patch level (since this was introduced in patch 95, it's
1461 always 95 or bigger). Pc is always zero.
1462 {only when compiled with |+termresponse| feature}
1463
1464 *v:this_session* *this_session-variable*
1465v:this_session Full filename of the last loaded or saved session file. See
1466 |:mksession|. It is allowed to set this variable. When no
1467 session file has been saved, this variable is empty.
1468 "this_session" also works, for backwards compatibility.
1469
1470 *v:throwpoint* *throwpoint-variable*
1471v:throwpoint The point where the exception most recently caught and not
1472 finished was thrown. Not set when commands are typed. See
1473 also |v:exception| and |throw-variables|.
1474 Example: >
1475 :try
1476 : throw "oops"
1477 :catch /.*/
1478 : echo "Exception from" v:throwpoint
1479 :endtry
1480< Output: "Exception from test.vim, line 2"
1481
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001482 *v:val* *val-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001483v:val Value of the current item of a |List| or |Dictionary|. Only
1484 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001485 |filter()|. Read-only.
1486
Bram Moolenaar071d4272004-06-13 20:20:40 +00001487 *v:version* *version-variable*
1488v:version Version number of Vim: Major version number times 100 plus
1489 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1490 is 501. Read-only. "version" also works, for backwards
1491 compatibility.
1492 Use |has()| to check if a certain patch was included, e.g.: >
1493 if has("patch123")
1494< Note that patch numbers are specific to the version, thus both
1495 version 5.0 and 5.1 may have a patch 123, but these are
1496 completely different.
1497
1498 *v:warningmsg* *warningmsg-variable*
1499v:warningmsg Last given warning message. It's allowed to set this variable.
1500
1501==============================================================================
15024. Builtin Functions *functions*
1503
1504See |function-list| for a list grouped by what the function is used for.
1505
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001506(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001507
1508USAGE RESULT DESCRIPTION ~
1509
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001510add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001511append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001512append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001513argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001514argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001516argv( ) List the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001517browse( {save}, {title}, {initdir}, {default})
1518 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001519browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001520bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001521buflisted( {expr}) Number TRUE if buffer {expr} is listed
1522bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523bufname( {expr}) String Name of the buffer {expr}
1524bufnr( {expr}) Number Number of the buffer {expr}
1525bufwinnr( {expr}) Number window number of buffer {expr}
1526byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001527byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001528call( {func}, {arglist} [, {dict}])
1529 any call {func} with arguments {arglist}
Bram Moolenaarca003e12006-03-17 23:19:38 +00001530changenr() Number current change number
Bram Moolenaar071d4272004-06-13 20:20:40 +00001531char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001532cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001533col( {expr}) Number column nr of cursor or mark
Bram Moolenaara94bc432006-03-10 21:42:59 +00001534complete({startcol}, {matches}) String set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001535complete_add( {expr}) Number add completion match
1536complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537confirm( {msg} [, {choices} [, {default} [, {type}]]])
1538 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001539copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001540count( {list}, {expr} [, {start} [, {ic}]])
1541 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001542cscope_connection( [{num} , {dbpath} [, {prepend}]])
1543 Number checks existence of cscope connection
Bram Moolenaar0b238792006-03-02 22:49:12 +00001544cursor( {lnum}, {col} [, {coladd}])
1545 Number move cursor to {lnum}, {col}, {coladd}
1546cursor( {list}) Number move cursor to position in {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001547deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001548delete( {fname}) Number delete file {fname}
1549did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001550diff_filler( {lnum}) Number diff filler lines about {lnum}
1551diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001552empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001553escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001554eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001555eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001556executable( {expr}) Number 1 if executable {expr} exists
1557exists( {expr}) Number TRUE if {expr} exists
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001558extend({expr1}, {expr2} [, {expr3}])
1559 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560expand( {expr}) String expand special keywords in {expr}
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00001561feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001562filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001563filewritable( {file}) Number TRUE if {file} is a writable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001564filter( {expr}, {string}) List/Dict remove items from {expr} where
1565 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001566finddir( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001567 String find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001568findfile( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001569 String find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001570fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001571foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1572foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001573foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001574foldtext( ) String line displayed for closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001575foldtextresult( {lnum}) String text for closed fold at {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001576foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001577function( {name}) Funcref reference to function {name}
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001578garbagecollect() none free memory, breaking cyclic references
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001579get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001580get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001581getbufline( {expr}, {lnum} [, {end}])
1582 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001583getbufvar( {expr}, {varname}) any variable {varname} in buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001584getchar( [expr]) Number get one character from the user
1585getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001586getcmdline() String return the current command-line
1587getcmdpos() Number return cursor position in command-line
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001588getcmdtype() String return the current command-line type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001589getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001590getfperm( {fname}) String file permissions of file {fname}
1591getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001592getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001593getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001594getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001595getline( {lnum}) String line {lnum} of current buffer
1596getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001597getloclist({nr}) List list of location list items
Bram Moolenaar0b238792006-03-02 22:49:12 +00001598getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001599getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001600getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001601getregtype( [{regname}]) String type of register
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001602gettabwinvar( {tabnr}, {winnr}, {name})
1603 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001604getwinposx() Number X coord in pixels of GUI Vim window
1605getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001606getwinvar( {nr}, {varname}) any variable {varname} in window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001607glob( {expr}) String expand file wildcards in {expr}
1608globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1609has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001610has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001611hasmapto( {what} [, {mode} [, {abbr}]])
1612 Number TRUE if mapping to {what} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613histadd( {history},{item}) String add an item to a history
1614histdel( {history} [, {item}]) String remove an item from a history
1615histget( {history} [, {index}]) String get the item {index} from a history
1616histnr( {history}) Number highest index of a history
1617hlexists( {name}) Number TRUE if highlight group {name} exists
1618hlID( {name}) Number syntax ID of highlight group {name}
1619hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001620iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1621indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001622index( {list}, {expr} [, {start} [, {ic}]])
1623 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001624input( {prompt} [, {text} [, {completion}]])
1625 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001626inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001627inputlist( {textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001628inputrestore() Number restore typeahead
1629inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001630inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001631insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001632isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001633islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001634items( {dict}) List key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001635join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001636keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001637len( {expr}) Number the length of {expr}
1638libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001639libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1640line( {expr}) Number line nr of cursor, last line or mark
1641line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001642lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001643localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001644map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001645maparg( {name}[, {mode} [, {abbr}]])
1646 String rhs of mapping {name} in mode {mode}
1647mapcheck( {name}[, {mode} [, {abbr}]])
1648 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001649match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001650 Number position where {pat} matches in {expr}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001651matcharg( {nr}) List arguments of |:match|
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001652matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001654matchlist( {expr}, {pat}[, {start}[, {count}]])
1655 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001656matchstr( {expr}, {pat}[, {start}[, {count}]])
1657 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001658max({list}) Number maximum value of items in {list}
1659min({list}) Number minumum value of items in {list}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001660mkdir({name} [, {path} [, {prot}]])
1661 Number create directory {name}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001662mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001663nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1664nr2char( {expr}) String single char with ASCII value {expr}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001665pathshorten( {expr}) String shorten directory names in a path
Bram Moolenaar071d4272004-06-13 20:20:40 +00001666prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001667printf( {fmt}, {expr1}...) String format text
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001668pumvisible() Number whether popup menu is visible
Bram Moolenaard8b02732005-01-14 21:48:43 +00001669range( {expr} [, {max} [, {stride}]])
1670 List items from {expr} to {max}
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001671readfile({fname} [, {binary} [, {max}]])
1672 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001673reltime( [{start} [, {end}]]) List get time value
1674reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00001675remote_expr( {server}, {string} [, {idvar}])
1676 String send expression
1677remote_foreground( {server}) Number bring Vim server to the foreground
1678remote_peek( {serverid} [, {retvar}])
1679 Number check for reply string
1680remote_read( {serverid}) String read reply string
1681remote_send( {server}, {string} [, {idvar}])
1682 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001683remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001684remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001685rename( {from}, {to}) Number rename (move) file from {from} to {to}
1686repeat( {expr}, {count}) String repeat {expr} {count} times
1687resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001688reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001689search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001690searchdecl({name} [, {global} [, {thisblock}]])
1691 Number search for variable declaration
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001692searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001693 Number search for other end of start/end pair
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001694searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001695 List search for other end of start/end pair
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001696searchpos( {pattern} [, {flags} [, {stopline}]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001697 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001698server2client( {clientid}, {string})
1699 Number send reply string
1700serverlist() String get a list of available servers
1701setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1702setcmdpos( {pos}) Number set cursor position in command-line
1703setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001704setloclist( {nr}, {list}[, {action}])
1705 Number modify location list using {list}
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001706setpos( {expr}, {list}) none set the {expr} position to {list}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001707setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001708setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001709settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1710 {winnr} in tab page {tabnr} to {val}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001711setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaar60a495f2006-10-03 12:44:42 +00001712shellescape( {string}) String escape {string} for use as shell
1713 command argument
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001714simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001715sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001716soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001717spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00001718spellsuggest( {word} [, {max} [, {capital}]])
1719 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001720split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001721 List make |List| from {pat} separated {expr}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001722str2nr( {expr} [, {base}]) Number convert string to number
Bram Moolenaar071d4272004-06-13 20:20:40 +00001723strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001724stridx( {haystack}, {needle}[, {start}])
1725 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001726string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727strlen( {expr}) Number length of the String {expr}
1728strpart( {src}, {start}[, {len}])
1729 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001730strridx( {haystack}, {needle} [, {start}])
1731 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001733submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734substitute( {expr}, {pat}, {sub}, {flags})
1735 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001736synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001737synIDattr( {synID}, {what} [, {mode}])
1738 String attribute {what} of syntax ID {synID}
1739synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001740system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001741tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1742tabpagenr( [{arg}]) Number number of current or last tab page
1743tabpagewinnr( {tabarg}[, {arg}])
1744 Number number of current window in tab page
1745taglist( {expr}) List list of tags matching {expr}
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00001746tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001747tempname() String name for a temporary file
1748tolower( {expr}) String the String {expr} switched to lowercase
1749toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001750tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1751 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001752type( {name}) Number type of variable {name}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001753values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001754virtcol( {expr}) Number screen column of cursor or mark
1755visualmode( [expr]) String last visual mode used
1756winbufnr( {nr}) Number buffer number of window {nr}
1757wincol() Number window column of the cursor
1758winheight( {nr}) Number height of window {nr}
1759winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00001760winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001761winrestcmd() String returns command to restore window sizes
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00001762winrestview({dict}) None restore view of current window
1763winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764winwidth( {nr}) Number width of window {nr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001765writefile({list}, {fname} [, {binary}])
1766 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001767
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001768add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001769 Append the item {expr} to |List| {list}. Returns the
1770 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001771 :let alist = add([1, 2, 3], item)
1772 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001773< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001774 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001775 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001776
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001777
1778append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001779 When {expr} is a |List|: Append each item of the |List| as a
1780 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00001781 Otherwise append {expr} as one text line below line {lnum} in
1782 the current buffer.
1783 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001784 Returns 1 for failure ({lnum} out of range or out of memory),
1785 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001786 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001787 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001788<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001789 *argc()*
1790argc() The result is the number of files in the argument list of the
1791 current window. See |arglist|.
1792
1793 *argidx()*
1794argidx() The result is the current index in the argument list. 0 is
1795 the first file. argc() - 1 is the last one. See |arglist|.
1796
1797 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001798argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001799 current window. See |arglist|. "argv(0)" is the first one.
1800 Example: >
1801 :let i = 0
1802 :while i < argc()
1803 : let f = escape(argv(i), '. ')
1804 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1805 : let i = i + 1
1806 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001807< Without the {nr} argument a |List| with the whole |arglist| is
1808 returned.
1809
Bram Moolenaar071d4272004-06-13 20:20:40 +00001810 *browse()*
1811browse({save}, {title}, {initdir}, {default})
1812 Put up a file requester. This only works when "has("browse")"
1813 returns non-zero (only in some GUI versions).
1814 The input fields are:
1815 {save} when non-zero, select file to write
1816 {title} title for the requester
1817 {initdir} directory to start browsing in
1818 {default} default file name
1819 When the "Cancel" button is hit, something went wrong, or
1820 browsing is not possible, an empty string is returned.
1821
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001822 *browsedir()*
1823browsedir({title}, {initdir})
1824 Put up a directory requester. This only works when
1825 "has("browse")" returns non-zero (only in some GUI versions).
1826 On systems where a directory browser is not supported a file
1827 browser is used. In that case: select a file in the directory
1828 to be used.
1829 The input fields are:
1830 {title} title for the requester
1831 {initdir} directory to start browsing in
1832 When the "Cancel" button is hit, something went wrong, or
1833 browsing is not possible, an empty string is returned.
1834
Bram Moolenaar071d4272004-06-13 20:20:40 +00001835bufexists({expr}) *bufexists()*
1836 The result is a Number, which is non-zero if a buffer called
1837 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001838 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001839 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001840 exactly. The name can be:
1841 - Relative to the current directory.
1842 - A full path.
1843 - The name of a buffer with 'filetype' set to "nofile".
1844 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001845 Unlisted buffers will be found.
1846 Note that help files are listed by their short name in the
1847 output of |:buffers|, but bufexists() requires using their
1848 long name to be able to find them.
1849 Use "bufexists(0)" to test for the existence of an alternate
1850 file name.
1851 *buffer_exists()*
1852 Obsolete name: buffer_exists().
1853
1854buflisted({expr}) *buflisted()*
1855 The result is a Number, which is non-zero if a buffer called
1856 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001857 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001858
1859bufloaded({expr}) *bufloaded()*
1860 The result is a Number, which is non-zero if a buffer called
1861 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001862 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001863
1864bufname({expr}) *bufname()*
1865 The result is the name of a buffer, as it is displayed by the
1866 ":ls" command.
1867 If {expr} is a Number, that buffer number's name is given.
1868 Number zero is the alternate buffer for the current window.
1869 If {expr} is a String, it is used as a |file-pattern| to match
1870 with the buffer names. This is always done like 'magic' is
1871 set and 'cpoptions' is empty. When there is more than one
1872 match an empty string is returned.
1873 "" or "%" can be used for the current buffer, "#" for the
1874 alternate buffer.
1875 A full match is preferred, otherwise a match at the start, end
1876 or middle of the buffer name is accepted.
1877 Listed buffers are found first. If there is a single match
1878 with a listed buffer, that one is returned. Next unlisted
1879 buffers are searched for.
1880 If the {expr} is a String, but you want to use it as a buffer
1881 number, force it to be a Number by adding zero to it: >
1882 :echo bufname("3" + 0)
1883< If the buffer doesn't exist, or doesn't have a name, an empty
1884 string is returned. >
1885 bufname("#") alternate buffer name
1886 bufname(3) name of buffer 3
1887 bufname("%") name of current buffer
1888 bufname("file2") name of buffer where "file2" matches.
1889< *buffer_name()*
1890 Obsolete name: buffer_name().
1891
1892 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001893bufnr({expr} [, {create}])
1894 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00001895 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001896 above.
1897 If the buffer doesn't exist, -1 is returned. Or, if the
1898 {create} argument is present and not zero, a new, unlisted,
1899 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001900 bufnr("$") is the last buffer: >
1901 :let last_buffer = bufnr("$")
1902< The result is a Number, which is the highest buffer number
1903 of existing buffers. Note that not all buffers with a smaller
1904 number necessarily exist, because ":bwipeout" may have removed
1905 them. Use bufexists() to test for the existence of a buffer.
1906 *buffer_number()*
1907 Obsolete name: buffer_number().
1908 *last_buffer_nr()*
1909 Obsolete name for bufnr("$"): last_buffer_nr().
1910
1911bufwinnr({expr}) *bufwinnr()*
1912 The result is a Number, which is the number of the first
1913 window associated with buffer {expr}. For the use of {expr},
1914 see |bufname()| above. If buffer {expr} doesn't exist or
1915 there is no such window, -1 is returned. Example: >
1916
1917 echo "A window containing buffer 1 is " . (bufwinnr(1))
1918
1919< The number can be used with |CTRL-W_w| and ":wincmd w"
1920 |:wincmd|.
1921
1922
1923byte2line({byte}) *byte2line()*
1924 Return the line number that contains the character at byte
1925 count {byte} in the current buffer. This includes the
1926 end-of-line character, depending on the 'fileformat' option
1927 for the current buffer. The first character has byte count
1928 one.
1929 Also see |line2byte()|, |go| and |:goto|.
1930 {not available when compiled without the |+byte_offset|
1931 feature}
1932
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001933byteidx({expr}, {nr}) *byteidx()*
1934 Return byte index of the {nr}'th character in the string
1935 {expr}. Use zero for the first character, it returns zero.
1936 This function is only useful when there are multibyte
1937 characters, otherwise the returned value is equal to {nr}.
1938 Composing characters are counted as a separate character.
1939 Example : >
1940 echo matchstr(str, ".", byteidx(str, 3))
1941< will display the fourth character. Another way to do the
1942 same: >
1943 let s = strpart(str, byteidx(str, 3))
1944 echo strpart(s, 0, byteidx(s, 1))
1945< If there are less than {nr} characters -1 is returned.
1946 If there are exactly {nr} characters the length of the string
1947 is returned.
1948
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001949call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001950 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001951 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001952 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001953 a:firstline and a:lastline are set to the cursor line.
1954 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001955 {dict} is for functions with the "dict" attribute. It will be
1956 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001957
Bram Moolenaarca003e12006-03-17 23:19:38 +00001958changenr() *changenr()*
1959 Return the number of the most recent change. This is the same
1960 number as what is displayed with |:undolist| and can be used
1961 with the |:undo| command.
1962 When a change was made it is the number of that change. After
1963 redo it is the number of the redone change. After undo it is
1964 one less than the number of the undone change.
1965
Bram Moolenaar071d4272004-06-13 20:20:40 +00001966char2nr({expr}) *char2nr()*
1967 Return number value of the first char in {expr}. Examples: >
1968 char2nr(" ") returns 32
1969 char2nr("ABC") returns 65
1970< The current 'encoding' is used. Example for "utf-8": >
Bram Moolenaar98692072006-02-04 00:57:42 +00001971 char2nr("?") returns 225
1972 char2nr("?"[0]) returns 195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001973< nr2char() does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001974
1975cindent({lnum}) *cindent()*
1976 Get the amount of indent for line {lnum} according the C
1977 indenting rules, as with 'cindent'.
1978 The indent is counted in spaces, the value of 'tabstop' is
1979 relevant. {lnum} is used just like in |getline()|.
1980 When {lnum} is invalid or Vim was not compiled the |+cindent|
1981 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00001982 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001983
1984 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001985col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001986 position given with {expr}. The accepted positions are:
1987 . the cursor position
1988 $ the end of the cursor line (the result is the
1989 number of characters in the cursor line plus one)
1990 'x position of mark x (if the mark is not set, 0 is
1991 returned)
Bram Moolenaar0b238792006-03-02 22:49:12 +00001992 To get the line number use |col()|. To get both use
1993 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001994 For the screen column position use |virtcol()|.
1995 Note that only marks in the current file can be used.
1996 Examples: >
1997 col(".") column of cursor
1998 col("$") length of cursor line plus one
1999 col("'t") column of mark t
2000 col("'" . markname) column of mark markname
2001< The first column is 1. 0 is returned for an error.
2002 For the cursor position, when 'virtualedit' is active, the
2003 column is one higher if the cursor is after the end of the
2004 line. This can be used to obtain the column in Insert mode: >
2005 :imap <F2> <C-O>:let save_ve = &ve<CR>
2006 \<C-O>:set ve=all<CR>
2007 \<C-O>:echo col(".") . "\n" <Bar>
2008 \let &ve = save_ve<CR>
2009<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002010
Bram Moolenaara94bc432006-03-10 21:42:59 +00002011complete({startcol}, {matches}) *complete()* *E785*
2012 Set the matches for Insert mode completion.
2013 Can only be used in Insert mode. You need to use a mapping
2014 with an expression argument |:map-<expr>| or CTRL-R =
2015 |i_CTRL-R|. It does not work after CTRL-O.
2016 {startcol} is the byte offset in the line where the completed
2017 text start. The text up to the cursor is the original text
2018 that will be replaced by the matches. Use col('.') for an
2019 empty string. "col('.') - 1" will replace one character by a
2020 match.
2021 {matches} must be a |List|. Each |List| item is one match.
2022 See |complete-items| for the kind of items that are possible.
2023 Note that the after calling this function you need to avoid
2024 inserting anything that would completion to stop.
2025 The match can be selected with CTRL-N and CTRL-P as usual with
2026 Insert mode completion. The popup menu will appear if
2027 specified, see |ins-completion-menu|.
2028 Example: >
2029 inoremap <expr> <F5> ListMonths()
2030
2031 func! ListMonths()
2032 call complete(col('.'), ['January', 'February', 'March',
2033 \ 'April', 'May', 'June', 'July', 'August', 'September',
2034 \ 'October', 'November', 'December'])
2035 return ''
2036 endfunc
2037< This isn't very useful, but it shows how it works. Note that
2038 an empty string is returned to avoid a zero being inserted.
2039
Bram Moolenaar572cb562005-08-05 21:35:02 +00002040complete_add({expr}) *complete_add()*
2041 Add {expr} to the list of matches. Only to be used by the
2042 function specified with the 'completefunc' option.
2043 Returns 0 for failure (empty string or out of memory),
2044 1 when the match was added, 2 when the match was already in
2045 the list.
Bram Moolenaar39f05632006-03-19 22:15:26 +00002046 See |complete-functions| for an explanation of {expr}. It is
2047 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002048
2049complete_check() *complete_check()*
2050 Check for a key typed while looking for completion matches.
2051 This is to be used when looking for matches takes some time.
2052 Returns non-zero when searching for matches is to be aborted,
2053 zero otherwise.
2054 Only to be used by the function specified with the
2055 'completefunc' option.
2056
Bram Moolenaar071d4272004-06-13 20:20:40 +00002057 *confirm()*
2058confirm({msg} [, {choices} [, {default} [, {type}]]])
2059 Confirm() offers the user a dialog, from which a choice can be
2060 made. It returns the number of the choice. For the first
2061 choice this is 1.
2062 Note: confirm() is only supported when compiled with dialog
2063 support, see |+dialog_con| and |+dialog_gui|.
2064 {msg} is displayed in a |dialog| with {choices} as the
2065 alternatives. When {choices} is missing or empty, "&OK" is
2066 used (and translated).
2067 {msg} is a String, use '\n' to include a newline. Only on
2068 some systems the string is wrapped when it doesn't fit.
2069 {choices} is a String, with the individual choices separated
2070 by '\n', e.g. >
2071 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2072< The letter after the '&' is the shortcut key for that choice.
2073 Thus you can type 'c' to select "Cancel". The shortcut does
2074 not need to be the first letter: >
2075 confirm("file has been modified", "&Save\nSave &All")
2076< For the console, the first letter of each choice is used as
2077 the default shortcut key.
2078 The optional {default} argument is the number of the choice
2079 that is made if the user hits <CR>. Use 1 to make the first
2080 choice the default one. Use 0 to not set a default. If
2081 {default} is omitted, 1 is used.
2082 The optional {type} argument gives the type of dialog. This
2083 is only used for the icon of the Win32 GUI. It can be one of
2084 these values: "Error", "Question", "Info", "Warning" or
2085 "Generic". Only the first character is relevant. When {type}
2086 is omitted, "Generic" is used.
2087 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2088 or another valid interrupt key, confirm() returns 0.
2089
2090 An example: >
2091 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2092 :if choice == 0
2093 : echo "make up your mind!"
2094 :elseif choice == 3
2095 : echo "tasteful"
2096 :else
2097 : echo "I prefer bananas myself."
2098 :endif
2099< In a GUI dialog, buttons are used. The layout of the buttons
2100 depends on the 'v' flag in 'guioptions'. If it is included,
2101 the buttons are always put vertically. Otherwise, confirm()
2102 tries to put the buttons in one horizontal line. If they
2103 don't fit, a vertical layout is used anyway. For some systems
2104 the horizontal layout is always used.
2105
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002106 *copy()*
2107copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
2108 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002109 When {expr} is a |List| a shallow copy is created. This means
2110 that the original |List| can be changed without changing the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002111 copy, and vise versa. But the items are identical, thus
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002112 changing an item changes the contents of both |Lists|. Also
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002113 see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002114
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002115count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002116 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002117 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002118 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002119 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002120 When {ic} is given and it's non-zero then case is ignored.
2121
2122
Bram Moolenaar071d4272004-06-13 20:20:40 +00002123 *cscope_connection()*
2124cscope_connection([{num} , {dbpath} [, {prepend}]])
2125 Checks for the existence of a |cscope| connection. If no
2126 parameters are specified, then the function returns:
2127 0, if cscope was not available (not compiled in), or
2128 if there are no cscope connections;
2129 1, if there is at least one cscope connection.
2130
2131 If parameters are specified, then the value of {num}
2132 determines how existence of a cscope connection is checked:
2133
2134 {num} Description of existence check
2135 ----- ------------------------------
2136 0 Same as no parameters (e.g., "cscope_connection()").
2137 1 Ignore {prepend}, and use partial string matches for
2138 {dbpath}.
2139 2 Ignore {prepend}, and use exact string matches for
2140 {dbpath}.
2141 3 Use {prepend}, use partial string matches for both
2142 {dbpath} and {prepend}.
2143 4 Use {prepend}, use exact string matches for both
2144 {dbpath} and {prepend}.
2145
2146 Note: All string comparisons are case sensitive!
2147
2148 Examples. Suppose we had the following (from ":cs show"): >
2149
2150 # pid database name prepend path
2151 0 27664 cscope.out /usr/local
2152<
2153 Invocation Return Val ~
2154 ---------- ---------- >
2155 cscope_connection() 1
2156 cscope_connection(1, "out") 1
2157 cscope_connection(2, "out") 0
2158 cscope_connection(3, "out") 0
2159 cscope_connection(3, "out", "local") 1
2160 cscope_connection(4, "out") 0
2161 cscope_connection(4, "out", "local") 0
2162 cscope_connection(4, "cscope.out", "/usr/local") 1
2163<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002164cursor({lnum}, {col} [, {off}]) *cursor()*
2165cursor({list})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002166 Positions the cursor at the column {col} in the line {lnum}.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002167 The first column is one.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002168 When there is one argument {list} this is used as a |List|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002169 with two or three items {lnum}, {col} and {off}. This is like
2170 the return value of |getpos()|, but without the first item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002171 Does not change the jumplist.
2172 If {lnum} is greater than the number of lines in the buffer,
2173 the cursor will be positioned at the last line in the buffer.
2174 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002175 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002176 the cursor will be positioned at the last character in the
2177 line.
2178 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002179 When 'virtualedit' is used {off} specifies the offset in
2180 screen columns from the start of the character. E.g., a
2181 position within a Tab or after the last character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002182
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002183
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002184deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002185 Make a copy of {expr}. For Numbers and Strings this isn't
2186 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002187 When {expr} is a |List| a full copy is created. This means
2188 that the original |List| can be changed without changing the
2189 copy, and vise versa. When an item is a |List|, a copy for it
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002190 is made, recursively. Thus changing an item in the copy does
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002191 not change the contents of the original |List|.
2192 When {noref} is omitted or zero a contained |List| or
2193 |Dictionary| is only copied once. All references point to
2194 this single copy. With {noref} set to 1 every occurrence of a
2195 |List| or |Dictionary| results in a new copy. This also means
2196 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002197 *E724*
2198 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002199 that refers back to a higher level making a deep copy with
2200 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002201 Also see |copy()|.
2202
2203delete({fname}) *delete()*
2204 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002205 which is 0 if the file was deleted successfully, and non-zero
2206 when the deletion failed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002207 Use |remove()| to delete an item from a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002208
2209 *did_filetype()*
2210did_filetype() Returns non-zero when autocommands are being executed and the
2211 FileType event has been triggered at least once. Can be used
2212 to avoid triggering the FileType event again in the scripts
2213 that detect the file type. |FileType|
2214 When editing another file, the counter is reset, thus this
2215 really checks if the FileType event has been triggered for the
2216 current buffer. This allows an autocommand that starts
2217 editing another buffer to set 'filetype' and load a syntax
2218 file.
2219
Bram Moolenaar47136d72004-10-12 20:02:24 +00002220diff_filler({lnum}) *diff_filler()*
2221 Returns the number of filler lines above line {lnum}.
2222 These are the lines that were inserted at this point in
2223 another diff'ed window. These filler lines are shown in the
2224 display but don't exist in the buffer.
2225 {lnum} is used like with |getline()|. Thus "." is the current
2226 line, "'m" mark m, etc.
2227 Returns 0 if the current window is not in diff mode.
2228
2229diff_hlID({lnum}, {col}) *diff_hlID()*
2230 Returns the highlight ID for diff mode at line {lnum} column
2231 {col} (byte index). When the current line does not have a
2232 diff change zero is returned.
2233 {lnum} is used like with |getline()|. Thus "." is the current
2234 line, "'m" mark m, etc.
2235 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2236 line.
2237 The highlight ID can be used with |synIDattr()| to obtain
2238 syntax information about the highlighting.
2239
Bram Moolenaar13065c42005-01-08 16:08:21 +00002240empty({expr}) *empty()*
2241 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002242 A |List| or |Dictionary| is empty when it does not have any
2243 items. A Number is empty when its value is zero.
2244 For a long |List| this is much faster then comparing the
2245 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002246
Bram Moolenaar071d4272004-06-13 20:20:40 +00002247escape({string}, {chars}) *escape()*
2248 Escape the characters in {chars} that occur in {string} with a
2249 backslash. Example: >
2250 :echo escape('c:\program files\vim', ' \')
2251< results in: >
2252 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002253
2254< *eval()*
2255eval({string}) Evaluate {string} and return the result. Especially useful to
2256 turn the result of |string()| back into the original value.
2257 This works for Numbers, Strings and composites of them.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002258 Also works for |Funcref|s that refer to existing functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002259
Bram Moolenaar071d4272004-06-13 20:20:40 +00002260eventhandler() *eventhandler()*
2261 Returns 1 when inside an event handler. That is that Vim got
2262 interrupted while waiting for the user to type a character,
2263 e.g., when dropping a file on Vim. This means interactive
2264 commands cannot be used. Otherwise zero is returned.
2265
2266executable({expr}) *executable()*
2267 This function checks if an executable with the name {expr}
2268 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002269 arguments.
2270 executable() uses the value of $PATH and/or the normal
2271 searchpath for programs. *PATHEXT*
2272 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2273 optionally be included. Then the extensions in $PATHEXT are
2274 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2275 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2276 used. A dot by itself can be used in $PATHEXT to try using
2277 the name without an extension. When 'shell' looks like a
2278 Unix shell, then the name is also tried without adding an
2279 extension.
2280 On MS-DOS and MS-Windows it only checks if the file exists and
2281 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002282 On MS-Windows an executable in the same directory as Vim is
2283 always found. Since this directory is added to $PATH it
2284 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002285 The result is a Number:
2286 1 exists
2287 0 does not exist
2288 -1 not implemented on this system
2289
2290 *exists()*
2291exists({expr}) The result is a Number, which is non-zero if {expr} is
2292 defined, zero otherwise. The {expr} argument is a string,
2293 which contains one of these:
2294 &option-name Vim option (only checks if it exists,
2295 not if it really works)
2296 +option-name Vim option that works.
2297 $ENVNAME environment variable (could also be
2298 done by comparing with an empty
2299 string)
2300 *funcname built-in function (see |functions|)
2301 or user defined function (see
2302 |user-functions|).
2303 varname internal variable (see
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002304 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002305 for |curly-braces-names|, |Dictionary|
2306 entries, |List| items, etc. Beware
2307 that this may cause functions to be
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002308 invoked cause an error message for an
2309 invalid expression.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002310 :cmdname Ex command: built-in command, user
2311 command or command modifier |:command|.
2312 Returns:
2313 1 for match with start of a command
2314 2 full match with a command
2315 3 matches several user commands
2316 To check for a supported command
2317 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00002318 :2match The |:2match| command.
2319 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002320 #event autocommand defined for this event
2321 #event#pattern autocommand defined for this event and
2322 pattern (the pattern is taken
2323 literally and compared to the
2324 autocommand patterns character by
2325 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002326 #group autocommand group exists
2327 #group#event autocommand defined for this group and
2328 event.
2329 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002330 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002331 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002332 ##event autocommand for this event is
2333 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002334 For checking for a supported feature use |has()|.
2335
2336 Examples: >
2337 exists("&shortname")
2338 exists("$HOSTNAME")
2339 exists("*strftime")
2340 exists("*s:MyFunc")
2341 exists("bufcount")
2342 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002343 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002344 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002345 exists("#filetypeindent")
2346 exists("#filetypeindent#FileType")
2347 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002348 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002349< There must be no space between the symbol (&/$/*/#) and the
2350 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002351 There must be no extra characters after the name, although in
2352 a few cases this is ignored. That may become more strict in
2353 the future, thus don't count on it!
2354 Working example: >
2355 exists(":make")
2356< NOT working example: >
2357 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00002358
2359< Note that the argument must be a string, not the name of the
2360 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002361 exists(bufcount)
2362< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00002363 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002364
2365expand({expr} [, {flag}]) *expand()*
2366 Expand wildcards and the following special keywords in {expr}.
2367 The result is a String.
2368
2369 When there are several matches, they are separated by <NL>
2370 characters. [Note: in version 5.0 a space was used, which
2371 caused problems when a file name contains a space]
2372
2373 If the expansion fails, the result is an empty string. A name
2374 for a non-existing file is not included.
2375
2376 When {expr} starts with '%', '#' or '<', the expansion is done
2377 like for the |cmdline-special| variables with their associated
2378 modifiers. Here is a short overview:
2379
2380 % current file name
2381 # alternate file name
2382 #n alternate file name n
2383 <cfile> file name under the cursor
2384 <afile> autocmd file name
2385 <abuf> autocmd buffer number (as a String!)
2386 <amatch> autocmd matched name
2387 <sfile> sourced script file name
2388 <cword> word under the cursor
2389 <cWORD> WORD under the cursor
2390 <client> the {clientid} of the last received
2391 message |server2client()|
2392 Modifiers:
2393 :p expand to full path
2394 :h head (last path component removed)
2395 :t tail (last path component only)
2396 :r root (one extension removed)
2397 :e extension only
2398
2399 Example: >
2400 :let &tags = expand("%:p:h") . "/tags"
2401< Note that when expanding a string that starts with '%', '#' or
2402 '<', any following text is ignored. This does NOT work: >
2403 :let doesntwork = expand("%:h.bak")
2404< Use this: >
2405 :let doeswork = expand("%:h") . ".bak"
2406< Also note that expanding "<cfile>" and others only returns the
2407 referenced file name without further expansion. If "<cfile>"
2408 is "~/.cshrc", you need to do another expand() to have the
2409 "~/" expanded into the path of the home directory: >
2410 :echo expand(expand("<cfile>"))
2411<
2412 There cannot be white space between the variables and the
2413 following modifier. The |fnamemodify()| function can be used
2414 to modify normal file names.
2415
2416 When using '%' or '#', and the current or alternate file name
2417 is not defined, an empty string is used. Using "%:p" in a
2418 buffer with no name, results in the current directory, with a
2419 '/' added.
2420
2421 When {expr} does not start with '%', '#' or '<', it is
2422 expanded like a file name is expanded on the command line.
2423 'suffixes' and 'wildignore' are used, unless the optional
2424 {flag} argument is given and it is non-zero. Names for
Bram Moolenaar02743632005-07-25 20:42:36 +00002425 non-existing files are included. The "**" item can be used to
2426 search in a directory tree. For example, to find all "README"
2427 files in the current directory and below: >
2428 :echo expand("**/README")
2429<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002430 Expand() can also be used to expand variables and environment
2431 variables that are only known in a shell. But this can be
2432 slow, because a shell must be started. See |expr-env-expand|.
2433 The expanded variable is still handled like a list of file
2434 names. When an environment variable cannot be expanded, it is
2435 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2436 "$FOOBAR".
2437
2438 See |glob()| for finding existing files. See |system()| for
2439 getting the raw output of an external command.
2440
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002441extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002442 {expr1} and {expr2} must be both |Lists| or both
2443 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002444
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002445 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002446 If {expr3} is given insert the items of {expr2} before item
2447 {expr3} in {expr1}. When {expr3} is zero insert before the
2448 first item. When {expr3} is equal to len({expr1}) then
2449 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002450 Examples: >
2451 :echo sort(extend(mylist, [7, 5]))
2452 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002453< Use |add()| to concatenate one item to a list. To concatenate
2454 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002455 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002456<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002457 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002458 Add all entries from {expr2} to {expr1}.
2459 If a key exists in both {expr1} and {expr2} then {expr3} is
2460 used to decide what to do:
2461 {expr3} = "keep": keep the value of {expr1}
2462 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002463 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002464 When {expr3} is omitted then "force" is assumed.
2465
2466 {expr1} is changed when {expr2} is not empty. If necessary
2467 make a copy of {expr1} first.
2468 {expr2} remains unchanged.
2469 Returns {expr1}.
2470
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002471
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002472feedkeys({string} [, {mode}]) *feedkeys()*
2473 Characters in {string} are queued for processing as if they
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00002474 come from a mapping or were typed by user. They are added to
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002475 the end of the typeahead buffer, thus if a mapping is still
2476 being executed these characters come after them.
2477 The function does not wait for processing of keys contained in
2478 {string}.
2479 To include special keys into {string}, use double-quotes
2480 and "\..." notation |expr-quote|. For example,
2481 feedkeys("\<CR>") simulates pressing of the Enter key. But
2482 feedkeys('\<CR>') pushes 5 characters.
2483 If {mode} is absent, keys are remapped.
2484 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00002485 'm' Remap keys. This is default.
2486 'n' Do not remap keys.
2487 't' Handle keys as if typed; otherwise they are handled as
2488 if coming from a mapping. This matters for undo,
2489 opening folds, etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002490 Return value is always 0.
2491
Bram Moolenaar071d4272004-06-13 20:20:40 +00002492filereadable({file}) *filereadable()*
2493 The result is a Number, which is TRUE when a file with the
2494 name {file} exists, and can be read. If {file} doesn't exist,
2495 or is a directory, the result is FALSE. {file} is any
2496 expression, which is used as a String.
2497 *file_readable()*
2498 Obsolete name: file_readable().
2499
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002500
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002501filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002502 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002503 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002504 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002505 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002506 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002507 Examples: >
2508 :call filter(mylist, 'v:val !~ "OLD"')
2509< Removes the items where "OLD" appears. >
2510 :call filter(mydict, 'v:key >= 8')
2511< Removes the items with a key below 8. >
2512 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002513< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002514
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002515 Note that {string} is the result of expression and is then
2516 used as an expression again. Often it is good to use a
2517 |literal-string| to avoid having to double backslashes.
2518
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002519 The operation is done in-place. If you want a |List| or
2520 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00002521 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002522
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002523< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00002524 When an error is encountered while evaluating {string} no
2525 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002526
2527
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002528finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002529 Find directory {name} in {path}. Returns the path of the
2530 first found match. When the found directory is below the
2531 current directory a relative path is returned. Otherwise a
2532 full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002533 If {path} is omitted or empty then 'path' is used.
2534 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002535 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00002536 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002537 This is quite similar to the ex-command |:find|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002538 {only available when compiled with the +file_in_path feature}
2539
2540findfile({name}[, {path}[, {count}]]) *findfile()*
2541 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002542 Uses 'suffixesadd'.
2543 Example: >
2544 :echo findfile("tags.vim", ".;")
2545< Searches from the current directory upwards until it finds
2546 the file "tags.vim".
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002547
Bram Moolenaar071d4272004-06-13 20:20:40 +00002548filewritable({file}) *filewritable()*
2549 The result is a Number, which is 1 when a file with the
2550 name {file} exists, and can be written. If {file} doesn't
2551 exist, or is not writable, the result is 0. If (file) is a
2552 directory, and we can write to it, the result is 2.
2553
2554fnamemodify({fname}, {mods}) *fnamemodify()*
2555 Modify file name {fname} according to {mods}. {mods} is a
2556 string of characters like it is used for file names on the
2557 command line. See |filename-modifiers|.
2558 Example: >
2559 :echo fnamemodify("main.c", ":p:h")
2560< results in: >
2561 /home/mool/vim/vim/src
2562< Note: Environment variables and "~" don't work in {fname}, use
2563 |expand()| first then.
2564
2565foldclosed({lnum}) *foldclosed()*
2566 The result is a Number. If the line {lnum} is in a closed
2567 fold, the result is the number of the first line in that fold.
2568 If the line {lnum} is not in a closed fold, -1 is returned.
2569
2570foldclosedend({lnum}) *foldclosedend()*
2571 The result is a Number. If the line {lnum} is in a closed
2572 fold, the result is the number of the last line in that fold.
2573 If the line {lnum} is not in a closed fold, -1 is returned.
2574
2575foldlevel({lnum}) *foldlevel()*
2576 The result is a Number, which is the foldlevel of line {lnum}
2577 in the current buffer. For nested folds the deepest level is
2578 returned. If there is no fold at line {lnum}, zero is
2579 returned. It doesn't matter if the folds are open or closed.
2580 When used while updating folds (from 'foldexpr') -1 is
2581 returned for lines where folds are still to be updated and the
2582 foldlevel is unknown. As a special case the level of the
2583 previous line is usually available.
2584
2585 *foldtext()*
2586foldtext() Returns a String, to be displayed for a closed fold. This is
2587 the default function used for the 'foldtext' option and should
2588 only be called from evaluating 'foldtext'. It uses the
2589 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2590 The returned string looks like this: >
2591 +-- 45 lines: abcdef
2592< The number of dashes depends on the foldlevel. The "45" is
2593 the number of lines in the fold. "abcdef" is the text in the
2594 first non-blank line of the fold. Leading white space, "//"
2595 or "/*" and the text from the 'foldmarker' and 'commentstring'
2596 options is removed.
2597 {not available when compiled without the |+folding| feature}
2598
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002599foldtextresult({lnum}) *foldtextresult()*
2600 Returns the text that is displayed for the closed fold at line
2601 {lnum}. Evaluates 'foldtext' in the appropriate context.
2602 When there is no closed fold at {lnum} an empty string is
2603 returned.
2604 {lnum} is used like with |getline()|. Thus "." is the current
2605 line, "'m" mark m, etc.
2606 Useful when exporting folded text, e.g., to HTML.
2607 {not available when compiled without the |+folding| feature}
2608
Bram Moolenaar071d4272004-06-13 20:20:40 +00002609 *foreground()*
2610foreground() Move the Vim window to the foreground. Useful when sent from
2611 a client to a Vim server. |remote_send()|
2612 On Win32 systems this might not work, the OS does not always
2613 allow a window to bring itself to the foreground. Use
2614 |remote_foreground()| instead.
2615 {only in the Win32, Athena, Motif and GTK GUI versions and the
2616 Win32 console version}
2617
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002618
Bram Moolenaar13065c42005-01-08 16:08:21 +00002619function({name}) *function()* *E700*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002620 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002621 {name} can be a user defined function or an internal function.
2622
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002623
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002624garbagecollect() *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002625 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002626 references. There is hardly ever a need to invoke this
2627 function, as it is automatically done when Vim runs out of
2628 memory or is waiting for the user to press a key after
2629 'updatetime'. Items without circular references are always
2630 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002631 This is useful if you have deleted a very big |List| and/or
2632 |Dictionary| with circular references in a script that runs
2633 for a long time.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00002634
Bram Moolenaar677ee682005-01-27 14:41:15 +00002635get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002636 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002637 available return {default}. Return zero when {default} is
2638 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002639get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002640 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002641 item is not available return {default}. Return zero when
2642 {default} is omitted.
2643
Bram Moolenaar45360022005-07-21 21:08:21 +00002644 *getbufline()*
2645getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002646 Return a |List| with the lines starting from {lnum} to {end}
2647 (inclusive) in the buffer {expr}. If {end} is omitted, a
2648 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002649
2650 For the use of {expr}, see |bufname()| above.
2651
Bram Moolenaar661b1822005-07-28 22:36:45 +00002652 For {lnum} and {end} "$" can be used for the last line of the
2653 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00002654
2655 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002656 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002657
2658 When {end} is greater than the number of lines in the buffer,
2659 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002660 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00002661 returned.
2662
Bram Moolenaar661b1822005-07-28 22:36:45 +00002663 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002664 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00002665
2666 Example: >
2667 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002668
2669getbufvar({expr}, {varname}) *getbufvar()*
2670 The result is the value of option or local buffer variable
2671 {varname} in buffer {expr}. Note that the name without "b:"
2672 must be used.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00002673 This also works for a global or buffer-local option, but it
2674 doesn't work for a global variable, window-local variable or
2675 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002676 For the use of {expr}, see |bufname()| above.
2677 When the buffer or variable doesn't exist an empty string is
2678 returned, there is no error message.
2679 Examples: >
2680 :let bufmodified = getbufvar(1, "&mod")
2681 :echo "todo myvar = " . getbufvar("todo", "myvar")
2682<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002683getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00002684 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002685 If [expr] is omitted, wait until a character is available.
2686 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002687 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002688 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00002689 not consumed. Return zero if no character available.
2690
2691 Without {expr} and when {expr} is 0 a whole character or
2692 special key is returned. If it is an 8-bit character, the
2693 result is a number. Use nr2char() to convert it to a String.
2694 Otherwise a String is returned with the encoded character.
2695 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00002696 (decimal: 128). This is the same value as the string
2697 "\<Key>", e.g., "\<Left>". The returned value is also a
2698 String when a modifier (shift, control, alt) was used that is
2699 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002700
2701 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00002702 one-byte character it is the character itself as a number.
2703 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002704
Bram Moolenaar071d4272004-06-13 20:20:40 +00002705 There is no prompt, you will somehow have to make clear to the
2706 user that a character has to be typed.
2707 There is no mapping for the character.
2708 Key codes are replaced, thus when the user presses the <Del>
2709 key you get the code for the <Del> key, not the raw character
2710 sequence. Examples: >
2711 getchar() == "\<Del>"
2712 getchar() == "\<S-Left>"
2713< This example redefines "f" to ignore case: >
2714 :nmap f :call FindChar()<CR>
2715 :function FindChar()
2716 : let c = nr2char(getchar())
2717 : while col('.') < col('$') - 1
2718 : normal l
2719 : if getline('.')[col('.') - 1] ==? c
2720 : break
2721 : endif
2722 : endwhile
2723 :endfunction
2724
2725getcharmod() *getcharmod()*
2726 The result is a Number which is the state of the modifiers for
2727 the last obtained character with getchar() or in another way.
2728 These values are added together:
2729 2 shift
2730 4 control
2731 8 alt (meta)
2732 16 mouse double click
2733 32 mouse triple click
2734 64 mouse quadruple click
2735 128 Macintosh only: command
2736 Only the modifiers that have not been included in the
2737 character itself are obtained. Thus Shift-a results in "A"
2738 with no modifier.
2739
Bram Moolenaar071d4272004-06-13 20:20:40 +00002740getcmdline() *getcmdline()*
2741 Return the current command-line. Only works when the command
2742 line is being edited, thus requires use of |c_CTRL-\_e| or
2743 |c_CTRL-R_=|.
2744 Example: >
2745 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002746< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002747
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002748getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002749 Return the position of the cursor in the command line as a
2750 byte count. The first column is 1.
2751 Only works when editing the command line, thus requires use of
2752 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002753 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
2754
2755getcmdtype() *getcmdtype()*
2756 Return the current command-line type. Possible return values
2757 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00002758 : normal Ex command
2759 > debug mode command |debug-mode|
2760 / forward search command
2761 ? backward search command
2762 @ |input()| command
2763 - |:insert| or |:append| command
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002764 Only works when editing the command line, thus requires use of
2765 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
2766 otherwise.
2767 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002768
2769 *getcwd()*
2770getcwd() The result is a String, which is the name of the current
2771 working directory.
2772
2773getfsize({fname}) *getfsize()*
2774 The result is a Number, which is the size in bytes of the
2775 given file {fname}.
2776 If {fname} is a directory, 0 is returned.
2777 If the file {fname} can't be found, -1 is returned.
2778
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002779getfontname([{name}]) *getfontname()*
2780 Without an argument returns the name of the normal font being
2781 used. Like what is used for the Normal highlight group
2782 |hl-Normal|.
2783 With an argument a check is done whether {name} is a valid
2784 font name. If not then an empty string is returned.
2785 Otherwise the actual font name is returned, or {name} if the
2786 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002787 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002788 gvimrc file. Use the |GUIEnter| autocommand to use this
2789 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002790 Note that the GTK 2 GUI accepts any font name, thus checking
2791 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002792
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002793getfperm({fname}) *getfperm()*
2794 The result is a String, which is the read, write, and execute
2795 permissions of the given file {fname}.
2796 If {fname} does not exist or its directory cannot be read, an
2797 empty string is returned.
2798 The result is of the form "rwxrwxrwx", where each group of
2799 "rwx" flags represent, in turn, the permissions of the owner
2800 of the file, the group the file belongs to, and other users.
2801 If a user does not have a given permission the flag for this
2802 is replaced with the string "-". Example: >
2803 :echo getfperm("/etc/passwd")
2804< This will hopefully (from a security point of view) display
2805 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00002806
Bram Moolenaar071d4272004-06-13 20:20:40 +00002807getftime({fname}) *getftime()*
2808 The result is a Number, which is the last modification time of
2809 the given file {fname}. The value is measured as seconds
2810 since 1st Jan 1970, and may be passed to strftime(). See also
2811 |localtime()| and |strftime()|.
2812 If the file {fname} can't be found -1 is returned.
2813
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002814getftype({fname}) *getftype()*
2815 The result is a String, which is a description of the kind of
2816 file of the given file {fname}.
2817 If {fname} does not exist an empty string is returned.
2818 Here is a table over different kinds of files and their
2819 results:
2820 Normal file "file"
2821 Directory "dir"
2822 Symbolic link "link"
2823 Block device "bdev"
2824 Character device "cdev"
2825 Socket "socket"
2826 FIFO "fifo"
2827 All other "other"
2828 Example: >
2829 getftype("/home")
2830< Note that a type such as "link" will only be returned on
2831 systems that support it. On some systems only "dir" and
2832 "file" are returned.
2833
Bram Moolenaar071d4272004-06-13 20:20:40 +00002834 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002835getline({lnum} [, {end}])
2836 Without {end} the result is a String, which is line {lnum}
2837 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002838 getline(1)
2839< When {lnum} is a String that doesn't start with a
2840 digit, line() is called to translate the String into a Number.
2841 To get the line under the cursor: >
2842 getline(".")
2843< When {lnum} is smaller than 1 or bigger than the number of
2844 lines in the buffer, an empty string is returned.
2845
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002846 When {end} is given the result is a |List| where each item is
2847 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002848 including line {end}.
2849 {end} is used in the same way as {lnum}.
2850 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002851 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002852 Example: >
2853 :let start = line('.')
2854 :let end = search("^$") - 1
2855 :let lines = getline(start, end)
2856
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002857getloclist({nr}) *getloclist()*
2858 Returns a list with all the entries in the location list for
2859 window {nr}. When {nr} is zero the current window is used.
2860 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00002861 returned. For an invalid window number {nr}, an empty list is
2862 returned. Otherwise, same as getqflist().
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002863
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002864getqflist() *getqflist()*
2865 Returns a list with all the current quickfix errors. Each
2866 list item is a dictionary with these entries:
2867 bufnr number of buffer that has the file name, use
2868 bufname() to get the name
2869 lnum line number in the buffer (first line is 1)
2870 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00002871 vcol non-zero: "col" is visual column
2872 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002873 nr error number
2874 text description of the error
2875 type type of the error, 'E', '1', etc.
2876 valid non-zero: recognized error message
2877
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00002878 When there is no error list or it's empty an empty list is
2879 returned.
2880
Bram Moolenaar68b76a62005-03-25 21:53:48 +00002881 Useful application: Find pattern matches in multiple files and
2882 do something with them: >
2883 :vimgrep /theword/jg *.c
2884 :for d in getqflist()
2885 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
2886 :endfor
2887
2888
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002889getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002890 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002891 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002892 :let cliptext = getreg('*')
2893< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002894 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002895 getreg('=', 1) returns the expression itself, so that it can
2896 be restored with |setreg()|. For other registers the extra
2897 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002898 If {regname} is not specified, |v:register| is used.
2899
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002900
Bram Moolenaar071d4272004-06-13 20:20:40 +00002901getregtype([{regname}]) *getregtype()*
2902 The result is a String, which is type of register {regname}.
2903 The value will be one of:
2904 "v" for |characterwise| text
2905 "V" for |linewise| text
2906 "<CTRL-V>{width}" for |blockwise-visual| text
2907 0 for an empty or unknown register
2908 <CTRL-V> is one character with value 0x16.
2909 If {regname} is not specified, |v:register| is used.
2910
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002911gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()*
2912 Get the value of an option or local window variable {varname}
2913 in window {winnr} in tab page {tabnr}.
2914 Tabs are numbered starting with one. For the current tabpage
2915 use |getwinvar()|.
2916 When {winnr} is zero the current window is used.
2917 This also works for a global option, buffer-local option and
2918 window-local option, but it doesn't work for a global variable
2919 or buffer-local variable.
2920 Note that the name without "w:" must be used.
2921 Examples: >
2922 :let list_is_on = gettabwinvar(1, 2, '&list')
2923 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
2924
Bram Moolenaar071d4272004-06-13 20:20:40 +00002925 *getwinposx()*
2926getwinposx() The result is a Number, which is the X coordinate in pixels of
2927 the left hand side of the GUI Vim window. The result will be
2928 -1 if the information is not available.
2929
2930 *getwinposy()*
2931getwinposy() The result is a Number, which is the Y coordinate in pixels of
2932 the top of the GUI Vim window. The result will be -1 if the
2933 information is not available.
2934
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002935getwinvar({winnr}, {varname}) *getwinvar()*
2936 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002937 Examples: >
2938 :let list_is_on = getwinvar(2, '&list')
2939 :echo "myvar = " . getwinvar(1, 'myvar')
2940<
2941 *glob()*
2942glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2943 When there are several matches, they are separated by <NL>
2944 characters.
2945 If the expansion fails, the result is an empty string.
2946 A name for a non-existing file is not included.
2947
2948 For most systems backticks can be used to get files names from
2949 any external command. Example: >
2950 :let tagfiles = glob("`find . -name tags -print`")
2951 :let &tags = substitute(tagfiles, "\n", ",", "g")
2952< The result of the program inside the backticks should be one
2953 item per line. Spaces inside an item are allowed.
2954
2955 See |expand()| for expanding special Vim variables. See
2956 |system()| for getting the raw output of an external command.
2957
2958globpath({path}, {expr}) *globpath()*
2959 Perform glob() on all directories in {path} and concatenate
2960 the results. Example: >
2961 :echo globpath(&rtp, "syntax/c.vim")
2962< {path} is a comma-separated list of directory names. Each
2963 directory name is prepended to {expr} and expanded like with
2964 glob(). A path separator is inserted when needed.
2965 To add a comma inside a directory name escape it with a
2966 backslash. Note that on MS-Windows a directory may have a
2967 trailing backslash, remove it if you put a comma after it.
2968 If the expansion fails for one of the directories, there is no
2969 error message.
2970 The 'wildignore' option applies: Names matching one of the
2971 patterns in 'wildignore' will be skipped.
2972
Bram Moolenaar02743632005-07-25 20:42:36 +00002973 The "**" item can be used to search in a directory tree.
2974 For example, to find all "README.txt" files in the directories
2975 in 'runtimepath' and below: >
2976 :echo globpath(&rtp, "**/README.txt")
2977<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002978 *has()*
2979has({feature}) The result is a Number, which is 1 if the feature {feature} is
2980 supported, zero otherwise. The {feature} argument is a
2981 string. See |feature-list| below.
2982 Also see |exists()|.
2983
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002984
2985has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002986 The result is a Number, which is 1 if |Dictionary| {dict} has
2987 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002988
2989
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002990hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002991 The result is a Number, which is 1 if there is a mapping that
2992 contains {what} in somewhere in the rhs (what it is mapped to)
2993 and this mapping exists in one of the modes indicated by
2994 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002995 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00002996 instead of mappings. Don't forget to specify Insert and/or
2997 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002998 Both the global mappings and the mappings local to the current
2999 buffer are checked for a match.
3000 If no matching mapping is found 0 is returned.
3001 The following characters are recognized in {mode}:
3002 n Normal mode
3003 v Visual mode
3004 o Operator-pending mode
3005 i Insert mode
3006 l Language-Argument ("r", "f", "t", etc.)
3007 c Command-line mode
3008 When {mode} is omitted, "nvo" is used.
3009
3010 This function is useful to check if a mapping already exists
3011 to a function in a Vim script. Example: >
3012 :if !hasmapto('\ABCdoit')
3013 : map <Leader>d \ABCdoit
3014 :endif
3015< This installs the mapping to "\ABCdoit" only if there isn't
3016 already a mapping to "\ABCdoit".
3017
3018histadd({history}, {item}) *histadd()*
3019 Add the String {item} to the history {history} which can be
3020 one of: *hist-names*
3021 "cmd" or ":" command line history
3022 "search" or "/" search pattern history
3023 "expr" or "=" typed expression history
3024 "input" or "@" input line history
3025 If {item} does already exist in the history, it will be
3026 shifted to become the newest entry.
3027 The result is a Number: 1 if the operation was successful,
3028 otherwise 0 is returned.
3029
3030 Example: >
3031 :call histadd("input", strftime("%Y %b %d"))
3032 :let date=input("Enter date: ")
3033< This function is not available in the |sandbox|.
3034
3035histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003036 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003037 for the possible values of {history}.
3038
3039 If the parameter {item} is given as String, this is seen
3040 as regular expression. All entries matching that expression
3041 will be removed from the history (if there are any).
3042 Upper/lowercase must match, unless "\c" is used |/\c|.
3043 If {item} is a Number, it will be interpreted as index, see
3044 |:history-indexing|. The respective entry will be removed
3045 if it exists.
3046
3047 The result is a Number: 1 for a successful operation,
3048 otherwise 0 is returned.
3049
3050 Examples:
3051 Clear expression register history: >
3052 :call histdel("expr")
3053<
3054 Remove all entries starting with "*" from the search history: >
3055 :call histdel("/", '^\*')
3056<
3057 The following three are equivalent: >
3058 :call histdel("search", histnr("search"))
3059 :call histdel("search", -1)
3060 :call histdel("search", '^'.histget("search", -1).'$')
3061<
3062 To delete the last search pattern and use the last-but-one for
3063 the "n" command and 'hlsearch': >
3064 :call histdel("search", -1)
3065 :let @/ = histget("search", -1)
3066
3067histget({history} [, {index}]) *histget()*
3068 The result is a String, the entry with Number {index} from
3069 {history}. See |hist-names| for the possible values of
3070 {history}, and |:history-indexing| for {index}. If there is
3071 no such entry, an empty String is returned. When {index} is
3072 omitted, the most recent item from the history is used.
3073
3074 Examples:
3075 Redo the second last search from history. >
3076 :execute '/' . histget("search", -2)
3077
3078< Define an Ex command ":H {num}" that supports re-execution of
3079 the {num}th entry from the output of |:history|. >
3080 :command -nargs=1 H execute histget("cmd", 0+<args>)
3081<
3082histnr({history}) *histnr()*
3083 The result is the Number of the current entry in {history}.
3084 See |hist-names| for the possible values of {history}.
3085 If an error occurred, -1 is returned.
3086
3087 Example: >
3088 :let inp_index = histnr("expr")
3089<
3090hlexists({name}) *hlexists()*
3091 The result is a Number, which is non-zero if a highlight group
3092 called {name} exists. This is when the group has been
3093 defined in some way. Not necessarily when highlighting has
3094 been defined for it, it may also have been used for a syntax
3095 item.
3096 *highlight_exists()*
3097 Obsolete name: highlight_exists().
3098
3099 *hlID()*
3100hlID({name}) The result is a Number, which is the ID of the highlight group
3101 with name {name}. When the highlight group doesn't exist,
3102 zero is returned.
3103 This can be used to retrieve information about the highlight
3104 group. For example, to get the background color of the
3105 "Comment" group: >
3106 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3107< *highlightID()*
3108 Obsolete name: highlightID().
3109
3110hostname() *hostname()*
3111 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003112 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00003113 256 characters long are truncated.
3114
3115iconv({expr}, {from}, {to}) *iconv()*
3116 The result is a String, which is the text {expr} converted
3117 from encoding {from} to encoding {to}.
3118 When the conversion fails an empty string is returned.
3119 The encoding names are whatever the iconv() library function
3120 can accept, see ":!man 3 iconv".
3121 Most conversions require Vim to be compiled with the |+iconv|
3122 feature. Otherwise only UTF-8 to latin1 conversion and back
3123 can be done.
3124 This can be used to display messages with special characters,
3125 no matter what 'encoding' is set to. Write the message in
3126 UTF-8 and use: >
3127 echo iconv(utf8_str, "utf-8", &enc)
3128< Note that Vim uses UTF-8 for all Unicode encodings, conversion
3129 from/to UCS-2 is automatically changed to use UTF-8. You
3130 cannot use UCS-2 in a string anyway, because of the NUL bytes.
3131 {only available when compiled with the +multi_byte feature}
3132
3133 *indent()*
3134indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3135 current buffer. The indent is counted in spaces, the value
3136 of 'tabstop' is relevant. {lnum} is used just like in
3137 |getline()|.
3138 When {lnum} is invalid -1 is returned.
3139
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003140
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003141index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003142 Return the lowest index in |List| {list} where the item has a
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003143 value equal to {expr}.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003144 If {start} is given then start looking at the item with index
3145 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003146 When {ic} is given and it is non-zero, ignore case. Otherwise
3147 case must match.
3148 -1 is returned when {expr} is not found in {list}.
3149 Example: >
3150 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003151 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003152
3153
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003154input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003155 The result is a String, which is whatever the user typed on
3156 the command-line. The parameter is either a prompt string, or
3157 a blank string (for no prompt). A '\n' can be used in the
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003158 prompt to start a new line.
3159 The highlighting set with |:echohl| is used for the prompt.
3160 The input is entered just like a command-line, with the same
3161 editing commands and mappings. There is a separate history
3162 for lines typed for input().
3163 Example: >
3164 :if input("Coffee or beer? ") == "beer"
3165 : echo "Cheers!"
3166 :endif
3167<
Bram Moolenaar1e015462005-09-25 22:16:38 +00003168 If the optional {text} is present and not empty, this is used
3169 for the default reply, as if the user typed this. Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003170 :let color = input("Color? ", "white")
3171
3172< The optional {completion} argument specifies the type of
3173 completion supported for the input. Without it completion is
3174 not performed. The supported completion types are the same as
3175 that can be supplied to a user-defined command using the
3176 "-complete=" argument. Refer to |:command-completion| for
3177 more information. Example: >
3178 let fname = input("File: ", "", "file")
3179<
3180 NOTE: This function must not be used in a startup file, for
3181 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003182 Note: When input() is called from within a mapping it will
3183 consume remaining characters from that mapping, because a
3184 mapping is handled like the characters were typed.
3185 Use |inputsave()| before input() and |inputrestore()|
3186 after input() to avoid that. Another solution is to avoid
3187 that further characters follow in the mapping, e.g., by using
3188 |:execute| or |:normal|.
3189
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003190 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003191 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3192 :function GetFoo()
3193 : call inputsave()
3194 : let g:Foo = input("enter search pattern: ")
3195 : call inputrestore()
3196 :endfunction
3197
3198inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3199 Like input(), but when the GUI is running and text dialogs are
3200 supported, a dialog window pops up to input the text.
3201 Example: >
3202 :let n = inputdialog("value for shiftwidth", &sw)
3203 :if n != ""
3204 : let &sw = n
3205 :endif
3206< When the dialog is cancelled {cancelreturn} is returned. When
3207 omitted an empty string is returned.
3208 Hitting <Enter> works like pressing the OK button. Hitting
3209 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003210 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003211
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003212inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003213 {textlist} must be a |List| of strings. This |List| is
3214 displayed, one string per line. The user will be prompted to
3215 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003216 The user can also select an item by clicking on it with the
3217 mouse. For the first string 0 is returned. When clicking
3218 above the first item a negative number is returned. When
3219 clicking on the prompt one more than the length of {textlist}
3220 is returned.
3221 Make sure {textlist} has less then 'lines' entries, otherwise
3222 it won't work. It's a good idea to put the entry number at
3223 the start of the string. Example: >
3224 let color = inputlist(['Select color:', '1. red',
3225 \ '2. green', '3. blue'])
3226
Bram Moolenaar071d4272004-06-13 20:20:40 +00003227inputrestore() *inputrestore()*
3228 Restore typeahead that was saved with a previous inputsave().
3229 Should be called the same number of times inputsave() is
3230 called. Calling it more often is harmless though.
3231 Returns 1 when there is nothing to restore, 0 otherwise.
3232
3233inputsave() *inputsave()*
3234 Preserve typeahead (also from mappings) and clear it, so that
3235 a following prompt gets input from the user. Should be
3236 followed by a matching inputrestore() after the prompt. Can
3237 be used several times, in which case there must be just as
3238 many inputrestore() calls.
3239 Returns 1 when out of memory, 0 otherwise.
3240
3241inputsecret({prompt} [, {text}]) *inputsecret()*
3242 This function acts much like the |input()| function with but
3243 two exceptions:
3244 a) the user's response will be displayed as a sequence of
3245 asterisks ("*") thereby keeping the entry secret, and
3246 b) the user's response will not be recorded on the input
3247 |history| stack.
3248 The result is a String, which is whatever the user actually
3249 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003250 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003251
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003252insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003253 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003254 If {idx} is specified insert {item} before the item with index
3255 {idx}. If {idx} is zero it goes before the first item, just
3256 like omitting {idx}. A negative {idx} is also possible, see
3257 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003258 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003259 :let mylist = insert([2, 3, 5], 1)
3260 :call insert(mylist, 4, -1)
3261 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003262< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003263 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003264 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003265
Bram Moolenaar071d4272004-06-13 20:20:40 +00003266isdirectory({directory}) *isdirectory()*
3267 The result is a Number, which is non-zero when a directory
3268 with the name {directory} exists. If {directory} doesn't
3269 exist, or isn't a directory, the result is FALSE. {directory}
3270 is any expression, which is used as a String.
3271
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003272islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003273 The result is a Number, which is non-zero when {expr} is the
3274 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003275 {expr} must be the name of a variable, |List| item or
3276 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003277 :let alist = [0, ['a', 'b'], 2, 3]
3278 :lockvar 1 alist
3279 :echo islocked('alist') " 1
3280 :echo islocked('alist[1]') " 0
3281
3282< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003283 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003284
Bram Moolenaar677ee682005-01-27 14:41:15 +00003285items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003286 Return a |List| with all the key-value pairs of {dict}. Each
3287 |List| item is a list with two items: the key of a {dict}
3288 entry and the value of this entry. The |List| is in arbitrary
3289 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003290
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003291
3292join({list} [, {sep}]) *join()*
3293 Join the items in {list} together into one String.
3294 When {sep} is specified it is put in between the items. If
3295 {sep} is omitted a single space is used.
3296 Note that {sep} is not added at the end. You might want to
3297 add it there too: >
3298 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003299< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003300 converted into a string like with |string()|.
3301 The opposite function is |split()|.
3302
Bram Moolenaard8b02732005-01-14 21:48:43 +00003303keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003304 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00003305 arbitrary order.
3306
Bram Moolenaar13065c42005-01-08 16:08:21 +00003307 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003308len({expr}) The result is a Number, which is the length of the argument.
3309 When {expr} is a String or a Number the length in bytes is
3310 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003311 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003312 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003313 When {expr} is a |Dictionary| the number of entries in the
3314 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003315 Otherwise an error is given.
3316
Bram Moolenaar071d4272004-06-13 20:20:40 +00003317 *libcall()* *E364* *E368*
3318libcall({libname}, {funcname}, {argument})
3319 Call function {funcname} in the run-time library {libname}
3320 with single argument {argument}.
3321 This is useful to call functions in a library that you
3322 especially made to be used with Vim. Since only one argument
3323 is possible, calling standard library functions is rather
3324 limited.
3325 The result is the String returned by the function. If the
3326 function returns NULL, this will appear as an empty string ""
3327 to Vim.
3328 If the function returns a number, use libcallnr()!
3329 If {argument} is a number, it is passed to the function as an
3330 int; if {argument} is a string, it is passed as a
3331 null-terminated string.
3332 This function will fail in |restricted-mode|.
3333
3334 libcall() allows you to write your own 'plug-in' extensions to
3335 Vim without having to recompile the program. It is NOT a
3336 means to call system functions! If you try to do so Vim will
3337 very probably crash.
3338
3339 For Win32, the functions you write must be placed in a DLL
3340 and use the normal C calling convention (NOT Pascal which is
3341 used in Windows System DLLs). The function must take exactly
3342 one parameter, either a character pointer or a long integer,
3343 and must return a character pointer or NULL. The character
3344 pointer returned must point to memory that will remain valid
3345 after the function has returned (e.g. in static data in the
3346 DLL). If it points to allocated memory, that memory will
3347 leak away. Using a static buffer in the function should work,
3348 it's then freed when the DLL is unloaded.
3349
3350 WARNING: If the function returns a non-valid pointer, Vim may
3351 crash! This also happens if the function returns a number,
3352 because Vim thinks it's a pointer.
3353 For Win32 systems, {libname} should be the filename of the DLL
3354 without the ".DLL" suffix. A full path is only required if
3355 the DLL is not in the usual places.
3356 For Unix: When compiling your own plugins, remember that the
3357 object code must be compiled as position-independent ('PIC').
3358 {only in Win32 on some Unix versions, when the |+libcall|
3359 feature is present}
3360 Examples: >
3361 :echo libcall("libc.so", "getenv", "HOME")
3362 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3363<
3364 *libcallnr()*
3365libcallnr({libname}, {funcname}, {argument})
3366 Just like libcall(), but used for a function that returns an
3367 int instead of a string.
3368 {only in Win32 on some Unix versions, when the |+libcall|
3369 feature is present}
3370 Example (not very useful...): >
3371 :call libcallnr("libc.so", "printf", "Hello World!\n")
3372 :call libcallnr("libc.so", "sleep", 10)
3373<
3374 *line()*
3375line({expr}) The result is a Number, which is the line number of the file
3376 position given with {expr}. The accepted positions are:
3377 . the cursor position
3378 $ the last line in the current buffer
3379 'x position of mark x (if the mark is not set, 0 is
3380 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00003381 w0 first line visible in current window
3382 w$ last line visible in current window
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003383 Note that a mark in another file can be used.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003384 To get the column number use |col()|. To get both use
3385 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003386 Examples: >
3387 line(".") line number of the cursor
3388 line("'t") line number of mark t
3389 line("'" . marker) line number of mark marker
3390< *last-position-jump*
3391 This autocommand jumps to the last known position in a file
3392 just after opening it, if the '" mark is set: >
3393 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003394
Bram Moolenaar071d4272004-06-13 20:20:40 +00003395line2byte({lnum}) *line2byte()*
3396 Return the byte count from the start of the buffer for line
3397 {lnum}. This includes the end-of-line character, depending on
3398 the 'fileformat' option for the current buffer. The first
3399 line returns 1.
3400 This can also be used to get the byte count for the line just
3401 below the last line: >
3402 line2byte(line("$") + 1)
3403< This is the file size plus one.
3404 When {lnum} is invalid, or the |+byte_offset| feature has been
3405 disabled at compile time, -1 is returned.
3406 Also see |byte2line()|, |go| and |:goto|.
3407
3408lispindent({lnum}) *lispindent()*
3409 Get the amount of indent for line {lnum} according the lisp
3410 indenting rules, as with 'lisp'.
3411 The indent is counted in spaces, the value of 'tabstop' is
3412 relevant. {lnum} is used just like in |getline()|.
3413 When {lnum} is invalid or Vim was not compiled the
3414 |+lispindent| feature, -1 is returned.
3415
3416localtime() *localtime()*
3417 Return the current time, measured as seconds since 1st Jan
3418 1970. See also |strftime()| and |getftime()|.
3419
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003420
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003421map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003422 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003423 Replace each item in {expr} with the result of evaluating
3424 {string}.
3425 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003426 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003427 Example: >
3428 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003429< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003430
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003431 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003432 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003433 |literal-string| to avoid having to double backslashes. You
3434 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003435
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003436 The operation is done in-place. If you want a |List| or
3437 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003438 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003439
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003440< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003441 When an error is encountered while evaluating {string} no
3442 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003443
3444
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003445maparg({name}[, {mode} [, {abbr}]]) *maparg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003446 Return the rhs of mapping {name} in mode {mode}. When there
3447 is no mapping for {name}, an empty String is returned.
Bram Moolenaard12f5c12006-01-25 22:10:52 +00003448 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003449 "n" Normal
3450 "v" Visual
3451 "o" Operator-pending
3452 "i" Insert
3453 "c" Cmd-line
3454 "l" langmap |language-mapping|
3455 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00003456 When {mode} is omitted, the modes for "" are used.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003457 When {abbr} is there and it is non-zero use abbreviations
3458 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003459 The {name} can have special key names, like in the ":map"
3460 command. The returned String has special characters
3461 translated like in the output of the ":map" command listing.
3462 The mappings local to the current buffer are checked first,
3463 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00003464 This function can be used to map a key even when it's already
3465 mapped, and have it do the original mapping too. Sketch: >
3466 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
3467
Bram Moolenaar071d4272004-06-13 20:20:40 +00003468
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003469mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003470 Check if there is a mapping that matches with {name} in mode
3471 {mode}. See |maparg()| for {mode} and special names in
3472 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003473 When {abbr} is there and it is non-zero use abbreviations
3474 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003475 A match happens with a mapping that starts with {name} and
3476 with a mapping which is equal to the start of {name}.
3477
3478 matches mapping "a" "ab" "abc" ~
3479 mapcheck("a") yes yes yes
3480 mapcheck("abc") yes yes yes
3481 mapcheck("ax") yes no no
3482 mapcheck("b") no no no
3483
3484 The difference with maparg() is that mapcheck() finds a
3485 mapping that matches with {name}, while maparg() only finds a
3486 mapping for {name} exactly.
3487 When there is no mapping that starts with {name}, an empty
3488 String is returned. If there is one, the rhs of that mapping
3489 is returned. If there are several mappings that start with
3490 {name}, the rhs of one of them is returned.
3491 The mappings local to the current buffer are checked first,
3492 then the global mappings.
3493 This function can be used to check if a mapping can be added
3494 without being ambiguous. Example: >
3495 :if mapcheck("_vv") == ""
3496 : map _vv :set guifont=7x13<CR>
3497 :endif
3498< This avoids adding the "_vv" mapping when there already is a
3499 mapping for "_v" or for "_vvv".
3500
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003501match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003502 When {expr} is a |List| then this returns the index of the
3503 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003504 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003505 Otherwise, {expr} is used as a String. The result is a
3506 Number, which gives the index (byte offset) in {expr} where
3507 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003508 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003509 If there is no match -1 is returned.
3510 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003511 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00003512 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003513< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00003514 *strpbrk()*
3515 Vim doesn't have a strpbrk() function. But you can do: >
3516 :let sepidx = match(line, '[.,;: \t]')
3517< *strcasestr()*
3518 Vim doesn't have a strcasestr() function. But you can add
3519 "\c" to the pattern to ignore case: >
3520 :let idx = match(haystack, '\cneedle')
3521<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003522 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003523 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003524 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003525 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003526 :echo match("testing", "ing", 2)
3527< result is again "4". >
3528 :echo match("testing", "ing", 4)
3529< result is again "4". >
3530 :echo match("testing", "t", 2)
3531< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003532 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00003533 {start} bytes later, thus "^" will match at {start}. Except
3534 when {count} is given, then it's like matches before the
3535 {start} byte are ignored (this is a bit complicated to keep it
3536 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003537 For a String, if {start} < 0, it will be set to 0. For a list
3538 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00003539 If {start} is out of range ({start} > strlen({expr}) for a
3540 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003541
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003542 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00003543 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003544 character further. Thus this example results in 1: >
3545 echo match("testing", "..", 0, 2)
3546< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003547 Note that when {count} is added the way {start} works changes,
3548 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00003549
Bram Moolenaar071d4272004-06-13 20:20:40 +00003550 See |pattern| for the patterns that are accepted.
3551 The 'ignorecase' option is used to set the ignore-caseness of
3552 the pattern. 'smartcase' is NOT used. The matching is always
3553 done like 'magic' is set and 'cpoptions' is empty.
3554
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003555
3556matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003557 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003558 |:2match| or |:3match| command.
3559 Return a |List| with two elements:
3560 The name of the highlight group used
3561 The pattern used.
3562 When {nr} is not 1, 2 or 3 returns an empty |List|.
3563 When there is no match item set returns ['', ''].
3564 This is usef to save and restore a |:match|.
3565
3566
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003567matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003568 Same as match(), but return the index of first character after
3569 the match. Example: >
3570 :echo matchend("testing", "ing")
3571< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00003572 *strspn()* *strcspn()*
3573 Vim doesn't have a strspn() or strcspn() function, but you can
3574 do it with matchend(): >
3575 :let span = matchend(line, '[a-zA-Z]')
3576 :let span = matchend(line, '[^a-zA-Z]')
3577< Except that -1 is returned when there are no matches.
3578
Bram Moolenaar071d4272004-06-13 20:20:40 +00003579 The {start}, if given, has the same meaning as for match(). >
3580 :echo matchend("testing", "ing", 2)
3581< results in "7". >
3582 :echo matchend("testing", "ing", 5)
3583< result is "-1".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003584 When {expr} is a |List| the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003585
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003586matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003587 Same as match(), but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003588 list is the matched string, same as what matchstr() would
3589 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003590 in |:substitute|. When an optional submatch didn't match an
3591 empty string is used. Example: >
3592 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
3593< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003594 When there is no match an empty list is returned.
3595
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003596matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003597 Same as match(), but return the matched string. Example: >
3598 :echo matchstr("testing", "ing")
3599< results in "ing".
3600 When there is no match "" is returned.
3601 The {start}, if given, has the same meaning as for match(). >
3602 :echo matchstr("testing", "ing", 2)
3603< results in "ing". >
3604 :echo matchstr("testing", "ing", 5)
3605< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003606 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003607 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003608
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003609 *max()*
3610max({list}) Return the maximum value of all items in {list}.
3611 If {list} is not a list or one of the items in {list} cannot
3612 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003613 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003614
3615 *min()*
3616min({list}) Return the minumum value of all items in {list}.
3617 If {list} is not a list or one of the items in {list} cannot
3618 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003619 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003620
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003621 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003622mkdir({name} [, {path} [, {prot}]])
3623 Create directory {name}.
3624 If {path} is "p" then intermediate directories are created as
3625 necessary. Otherwise it must be "".
3626 If {prot} is given it is used to set the protection bits of
3627 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3628 the user readable for others). Use 0700 to make it unreadable
3629 for others.
3630 This function is not available in the |sandbox|.
3631 Not available on all systems. To check use: >
3632 :if exists("*mkdir")
3633<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003634 *mode()*
3635mode() Return a string that indicates the current mode:
3636 n Normal
3637 v Visual by character
3638 V Visual by line
3639 CTRL-V Visual blockwise
3640 s Select by character
3641 S Select by line
3642 CTRL-S Select blockwise
3643 i Insert
3644 R Replace
3645 c Command-line
3646 r Hit-enter prompt
3647 This is useful in the 'statusline' option. In most other
3648 places it always returns "c" or "n".
3649
3650nextnonblank({lnum}) *nextnonblank()*
3651 Return the line number of the first line at or below {lnum}
3652 that is not blank. Example: >
3653 if getline(nextnonblank(1)) =~ "Java"
3654< When {lnum} is invalid or there is no non-blank line at or
3655 below it, zero is returned.
3656 See also |prevnonblank()|.
3657
3658nr2char({expr}) *nr2char()*
3659 Return a string with a single character, which has the number
3660 value {expr}. Examples: >
3661 nr2char(64) returns "@"
3662 nr2char(32) returns " "
3663< The current 'encoding' is used. Example for "utf-8": >
3664 nr2char(300) returns I with bow character
3665< Note that a NUL character in the file is specified with
3666 nr2char(10), because NULs are represented with newline
3667 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003668 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003669
Bram Moolenaar0b238792006-03-02 22:49:12 +00003670 *getpos()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003671getpos({expr}) Get the position for {expr}. For possible values of {expr}
3672 see |line()|.
3673 The result is a |List| with four numbers:
3674 [bufnum, lnum, col, off]
3675 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3676 is the buffer number of the mark.
3677 "lnum" and "col" are the position in the buffer. The first
3678 column is 1.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003679 The "off" number is zero, unless 'virtualedit' is used. Then
3680 it is the offset in screen columns from the start of the
3681 character. E.g., a position within a Tab or after the last
3682 character.
3683 This can be used to save and restore the cursor position: >
3684 let save_cursor = getpos(".")
3685 MoveTheCursorAround
Bram Moolenaardb552d602006-03-23 22:59:57 +00003686 call setpos('.', save_cursor)
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003687< Also see |setpos()|.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003688
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003689pathshorten({expr}) *pathshorten()*
3690 Shorten directory names in the path {expr} and return the
3691 result. The tail, the file name, is kept as-is. The other
3692 components in the path are reduced to single letters. Leading
3693 '~' and '.' characters are kept. Example: >
3694 :echo pathshorten('~/.vim/autoload/myfile.vim')
3695< ~/.v/a/myfile.vim ~
3696 It doesn't matter if the path exists or not.
3697
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003698prevnonblank({lnum}) *prevnonblank()*
3699 Return the line number of the first line at or above {lnum}
3700 that is not blank. Example: >
3701 let ind = indent(prevnonblank(v:lnum - 1))
3702< When {lnum} is invalid or there is no non-blank line at or
3703 above it, zero is returned.
3704 Also see |nextnonblank()|.
3705
3706
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003707printf({fmt}, {expr1} ...) *printf()*
3708 Return a String with {fmt}, where "%" items are replaced by
3709 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003710 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003711< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003712 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003713
3714 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003715 %s string
Bram Moolenaar98692072006-02-04 00:57:42 +00003716 %6s string right-aligned in 6 bytes
3717 %.9s string truncated to 9 bytes
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003718 %c single byte
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003719 %d decimal number
3720 %5d decimal number padded with spaces to 5 characters
3721 %x hex number
3722 %04x hex number padded with zeros to at least 4 characters
3723 %X hex number using upper case letters
3724 %o octal number
Bram Moolenaar98692072006-02-04 00:57:42 +00003725 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003726
3727 Conversion specifications start with '%' and end with the
3728 conversion type. All other characters are copied unchanged to
3729 the result.
3730
3731 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003732 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003733
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003734 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003735
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003736 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003737 Zero or more of the following flags:
3738
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003739 # The value should be converted to an "alternate
3740 form". For c, d, and s conversions, this option
3741 has no effect. For o conversions, the precision
3742 of the number is increased to force the first
3743 character of the output string to a zero (except
3744 if a zero value is printed with an explicit
3745 precision of zero).
3746 For x and X conversions, a non-zero result has
3747 the string "0x" (or "0X" for X conversions)
3748 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003749
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003750 0 (zero) Zero padding. For all conversions the converted
3751 value is padded on the left with zeros rather
3752 than blanks. If a precision is given with a
3753 numeric conversion (d, o, x, and X), the 0 flag
3754 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003755
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003756 - A negative field width flag; the converted value
3757 is to be left adjusted on the field boundary.
3758 The converted value is padded on the right with
3759 blanks, rather than on the left with blanks or
3760 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003761
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003762 ' ' (space) A blank should be left before a positive
3763 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003764
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003765 + A sign must always be placed before a number
3766 produced by a signed conversion. A + overrides
3767 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003768
3769 field-width
3770 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00003771 field width. If the converted value has fewer bytes
3772 than the field width, it will be padded with spaces on
3773 the left (or right, if the left-adjustment flag has
3774 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003775
3776 .precision
3777 An optional precision, in the form of a period '.'
3778 followed by an optional digit string. If the digit
3779 string is omitted, the precision is taken as zero.
3780 This gives the minimum number of digits to appear for
3781 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00003782 bytes to be printed from a string for s conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003783
3784 type
3785 A character that specifies the type of conversion to
3786 be applied, see below.
3787
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003788 A field width or precision, or both, may be indicated by an
3789 asterisk '*' instead of a digit string. In this case, a
3790 Number argument supplies the field width or precision. A
3791 negative field width is treated as a left adjustment flag
3792 followed by a positive field width; a negative precision is
3793 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003794 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003795< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003796 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003797
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003798 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003799
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003800 doxX The Number argument is converted to signed decimal
3801 (d), unsigned octal (o), or unsigned hexadecimal (x
3802 and X) notation. The letters "abcdef" are used for
3803 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003804 conversions.
3805 The precision, if any, gives the minimum number of
3806 digits that must appear; if the converted value
3807 requires fewer digits, it is padded on the left with
3808 zeros.
3809 In no case does a non-existent or small field width
3810 cause truncation of a numeric field; if the result of
3811 a conversion is wider than the field width, the field
3812 is expanded to contain the conversion result.
3813
3814 c The Number argument is converted to a byte, and the
3815 resulting character is written.
3816
3817 s The text of the String argument is used. If a
3818 precision is specified, no more bytes than the number
3819 specified are used.
3820
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003821 % A '%' is written. No argument is converted. The
3822 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003823
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003824 Each argument can be Number or String and is converted
3825 automatically to fit the conversion specifier. Any other
3826 argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003827
Bram Moolenaar83bab712005-08-01 21:58:57 +00003828 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003829 The number of {exprN} arguments must exactly match the number
3830 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00003831 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00003832
3833
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003834pumvisible() *pumvisible()*
3835 Returns non-zero when the popup menu is visible, zero
3836 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003837 This can be used to avoid some things that would remove the
3838 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003839
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003840 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003841range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003842 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00003843 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3844 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3845 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3846 {max}] (increasing {expr} with {stride} each time, not
3847 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00003848 When the maximum is one before the start the result is an
3849 empty list. When the maximum is more than one before the
3850 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003851 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003852 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00003853 range(2, 4) " [2, 3, 4]
3854 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003855 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00003856 range(0) " []
3857 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00003858<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003859 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003860readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003861 Read file {fname} and return a |List|, each line of the file
3862 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003863 separated with CR will result in a single long line (unless a
3864 NL appears somewhere).
3865 When {binary} is equal to "b" binary mode is used:
3866 - When the last line ends in a NL an extra empty list item is
3867 added.
3868 - No CR characters are removed.
3869 Otherwise:
3870 - CR characters that appear before a NL are removed.
3871 - Whether the last line ends in a NL or not does not matter.
3872 All NUL characters are replaced with a NL character.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003873 When {max} is given this specifies the maximum number of lines
3874 to be read. Useful if you only want to check the first ten
3875 lines of a file: >
3876 :for line in readfile(fname, '', 10)
3877 : if line =~ 'Date' | echo line | endif
3878 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00003879< When {max} is negative -{max} lines from the end of the file
3880 are returned, or as many as there are.
3881 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003882 Note that without {max} the whole file is read into memory.
3883 Also note that there is no recognition of encoding. Read a
3884 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003885 When the file can't be opened an error message is given and
3886 the result is an empty list.
3887 Also see |writefile()|.
3888
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003889reltime([{start} [, {end}]]) *reltime()*
3890 Return an item that represents a time value. The format of
3891 the item depends on the system. It can be passed to
3892 |reltimestr()| to convert it to a string.
3893 Without an argument it returns the current time.
3894 With one argument is returns the time passed since the time
3895 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003896 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003897 and {end}.
3898 The {start} and {end} arguments must be values returned by
3899 reltime().
3900 {only available when compiled with the +reltime feature}
3901
3902reltimestr({time}) *reltimestr()*
3903 Return a String that represents the time value of {time}.
3904 This is the number of seconds, a dot and the number of
3905 microseconds. Example: >
3906 let start = reltime()
3907 call MyFunction()
3908 echo reltimestr(reltime(start))
3909< Note that overhead for the commands will be added to the time.
3910 The accuracy depends on the system.
3911 Also see |profiling|.
3912 {only available when compiled with the +reltime feature}
3913
Bram Moolenaar071d4272004-06-13 20:20:40 +00003914 *remote_expr()* *E449*
3915remote_expr({server}, {string} [, {idvar}])
3916 Send the {string} to {server}. The string is sent as an
3917 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00003918 The result must be a String or a |List|. A |List| is turned
3919 into a String by joining the items with a line break in
3920 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00003921 If {idvar} is present, it is taken as the name of a
3922 variable and a {serverid} for later use with
3923 remote_read() is stored there.
3924 See also |clientserver| |RemoteReply|.
3925 This function is not available in the |sandbox|.
3926 {only available when compiled with the |+clientserver| feature}
3927 Note: Any errors will cause a local error message to be issued
3928 and the result will be the empty string.
3929 Examples: >
3930 :echo remote_expr("gvim", "2+2")
3931 :echo remote_expr("gvim1", "b:current_syntax")
3932<
3933
3934remote_foreground({server}) *remote_foreground()*
3935 Move the Vim server with the name {server} to the foreground.
3936 This works like: >
3937 remote_expr({server}, "foreground()")
3938< Except that on Win32 systems the client does the work, to work
3939 around the problem that the OS doesn't always allow the server
3940 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00003941 Note: This does not restore the window if it was minimized,
3942 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003943 This function is not available in the |sandbox|.
3944 {only in the Win32, Athena, Motif and GTK GUI versions and the
3945 Win32 console version}
3946
3947
3948remote_peek({serverid} [, {retvar}]) *remote_peek()*
3949 Returns a positive number if there are available strings
3950 from {serverid}. Copies any reply string into the variable
3951 {retvar} if specified. {retvar} must be a string with the
3952 name of a variable.
3953 Returns zero if none are available.
3954 Returns -1 if something is wrong.
3955 See also |clientserver|.
3956 This function is not available in the |sandbox|.
3957 {only available when compiled with the |+clientserver| feature}
3958 Examples: >
3959 :let repl = ""
3960 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3961
3962remote_read({serverid}) *remote_read()*
3963 Return the oldest available reply from {serverid} and consume
3964 it. It blocks until a reply is available.
3965 See also |clientserver|.
3966 This function is not available in the |sandbox|.
3967 {only available when compiled with the |+clientserver| feature}
3968 Example: >
3969 :echo remote_read(id)
3970<
3971 *remote_send()* *E241*
3972remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003973 Send the {string} to {server}. The string is sent as input
3974 keys and the function returns immediately. At the Vim server
3975 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003976 If {idvar} is present, it is taken as the name of a variable
3977 and a {serverid} for later use with remote_read() is stored
3978 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003979 See also |clientserver| |RemoteReply|.
3980 This function is not available in the |sandbox|.
3981 {only available when compiled with the |+clientserver| feature}
3982 Note: Any errors will be reported in the server and may mess
3983 up the display.
3984 Examples: >
3985 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3986 \ remote_read(serverid)
3987
3988 :autocmd NONE RemoteReply *
3989 \ echo remote_read(expand("<amatch>"))
3990 :echo remote_send("gvim", ":sleep 10 | echo ".
3991 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003992<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003993remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003994 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003995 return it.
3996 With {end}: Remove items from {idx} to {end} (inclusive) and
3997 return a list with these items. When {idx} points to the same
3998 item as {end} a list with one item is returned. When {end}
3999 points to an item before {idx} this is an error.
4000 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004001 Example: >
4002 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004003 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00004004remove({dict}, {key})
4005 Remove the entry from {dict} with key {key}. Example: >
4006 :echo "removed " . remove(dict, "one")
4007< If there is no {key} in {dict} this is an error.
4008
4009 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004010
Bram Moolenaar071d4272004-06-13 20:20:40 +00004011rename({from}, {to}) *rename()*
4012 Rename the file by the name {from} to the name {to}. This
4013 should also work to move files across file systems. The
4014 result is a Number, which is 0 if the file was renamed
4015 successfully, and non-zero when the renaming failed.
4016 This function is not available in the |sandbox|.
4017
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004018repeat({expr}, {count}) *repeat()*
4019 Repeat {expr} {count} times and return the concatenated
4020 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004021 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004022< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004023 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004024 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004025 :let longlist = repeat(['a', 'b'], 3)
4026< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004027
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004028
Bram Moolenaar071d4272004-06-13 20:20:40 +00004029resolve({filename}) *resolve()* *E655*
4030 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4031 returns the path the shortcut points to in a simplified form.
4032 On Unix, repeat resolving symbolic links in all path
4033 components of {filename} and return the simplified result.
4034 To cope with link cycles, resolving of symbolic links is
4035 stopped after 100 iterations.
4036 On other systems, return the simplified {filename}.
4037 The simplification step is done as by |simplify()|.
4038 resolve() keeps a leading path component specifying the
4039 current directory (provided the result is still a relative
4040 path name) and also keeps a trailing path separator.
4041
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004042 *reverse()*
4043reverse({list}) Reverse the order of items in {list} in-place. Returns
4044 {list}.
4045 If you want a list to remain unmodified make a copy first: >
4046 :let revlist = reverse(copy(mylist))
4047
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004048search({pattern} [, {flags} [, {stopline}]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004049 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004050 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004051
Bram Moolenaar071d4272004-06-13 20:20:40 +00004052 {flags} is a String, which can contain these character flags:
4053 'b' search backward instead of forward
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004054 'c' accept a match at the cursor position
4055 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004056 'n' do Not move the cursor
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004057 'p' return number of matching sub-pattern (see below)
4058 's' set the ' mark at the previous location of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004059 'w' wrap around the end of the file
4060 'W' don't wrap around the end of the file
4061 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4062
Bram Moolenaar02743632005-07-25 20:42:36 +00004063 If the 's' flag is supplied, the ' mark is set, only if the
4064 cursor is moved. The 's' flag cannot be combined with the 'n'
4065 flag.
4066
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004067 When the {stopline} argument is given then the search stops
4068 after searching this line. This is useful to restrict the
4069 search to a range of lines. Examples: >
4070 let match = search('(', 'b', line("w0"))
4071 let end = search('END', '', line("w$"))
4072< When {stopline} is used and it is not zero this also implies
4073 that the search does not wrap around the end of the file.
4074
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004075 If there is no match a 0 is returned and the cursor doesn't
4076 move. No error message is given.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004077 When a match has been found its line number is returned.
4078 *search()-sub-match*
4079 With the 'p' flag the returned value is one more than the
4080 first sub-match in \(\). One if none of them matched but the
4081 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004082 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004083
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004084 The cursor will be positioned at the match, unless the 'n'
4085 flag is used.
4086
Bram Moolenaar071d4272004-06-13 20:20:40 +00004087 Example (goes over all files in the argument list): >
4088 :let n = 1
4089 :while n <= argc() " loop over all files in arglist
4090 : exe "argument " . n
4091 : " start at the last char in the file and wrap for the
4092 : " first search to find match at start of file
4093 : normal G$
4094 : let flags = "w"
4095 : while search("foo", flags) > 0
4096 : s/foo/bar/g
4097 : let flags = "W"
4098 : endwhile
4099 : update " write the file if modified
4100 : let n = n + 1
4101 :endwhile
4102<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004103 Example for using some flags: >
4104 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4105< This will search for the keywords "if", "else", and "endif"
4106 under or after the cursor. Because of the 'p' flag, it
4107 returns 1, 2, or 3 depending on which keyword is found, or 0
4108 if the search fails. With the cursor on the first word of the
4109 line:
4110 if (foo == 0) | let foo = foo + 1 | endif ~
4111 the function returns 1. Without the 'c' flag, the function
4112 finds the "endif" and returns 3. The same thing happens
4113 without the 'e' flag if the cursor is on the "f" of "if".
4114 The 'n' flag tells the function not to move the cursor.
4115
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004116
Bram Moolenaarf75a9632005-09-13 21:20:47 +00004117searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4118 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004119
Bram Moolenaarf75a9632005-09-13 21:20:47 +00004120 With a non-zero {global} argument it works like |gD|, find
4121 first match in the file. Otherwise it works like |gd|, find
4122 first match in the function.
4123
4124 With a non-zero {thisblock} argument matches in a {} block
4125 that ends before the cursor position are ignored. Avoids
4126 finding variable declarations only valid in another scope.
4127
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004128 Moves the cursor to the found match.
4129 Returns zero for success, non-zero for failure.
4130 Example: >
4131 if searchdecl('myvar') == 0
4132 echo getline('.')
4133 endif
4134<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004135 *searchpair()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004136searchpair({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004137 Search for the match of a nested start-end pair. This can be
4138 used to find the "endif" that matches an "if", while other
4139 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004140 The search starts at the cursor. The default is to search
4141 forward, include 'b' in {flags} to search backward.
4142 If a match is found, the cursor is positioned at it and the
4143 line number is returned. If no match is found 0 or -1 is
4144 returned and the cursor doesn't move. No error message is
4145 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004146
4147 {start}, {middle} and {end} are patterns, see |pattern|. They
4148 must not contain \( \) pairs. Use of \%( \) is allowed. When
4149 {middle} is not empty, it is found when searching from either
4150 direction, but only when not in a nested start-end pair. A
4151 typical use is: >
4152 searchpair('\<if\>', '\<else\>', '\<endif\>')
4153< By leaving {middle} empty the "else" is skipped.
4154
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004155 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4156 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004157 'r' Repeat until no more matches found; will find the
4158 outer pair
4159 'm' return number of Matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004160 the match; will be > 1 when 'r' is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004161
4162 When a match for {start}, {middle} or {end} is found, the
4163 {skip} expression is evaluated with the cursor positioned on
4164 the start of the match. It should return non-zero if this
4165 match is to be skipped. E.g., because it is inside a comment
4166 or a string.
4167 When {skip} is omitted or empty, every match is accepted.
4168 When evaluating {skip} causes an error the search is aborted
4169 and -1 returned.
4170
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004171 For {stopline} see |search()|.
4172
Bram Moolenaar071d4272004-06-13 20:20:40 +00004173 The value of 'ignorecase' is used. 'magic' is ignored, the
4174 patterns are used like it's on.
4175
4176 The search starts exactly at the cursor. A match with
4177 {start}, {middle} or {end} at the next character, in the
4178 direction of searching, is the first one found. Example: >
4179 if 1
4180 if 2
4181 endif 2
4182 endif 1
4183< When starting at the "if 2", with the cursor on the "i", and
4184 searching forwards, the "endif 2" is found. When starting on
4185 the character just before the "if 2", the "endif 1" will be
4186 found. That's because the "if 2" will be found first, and
4187 then this is considered to be a nested if/endif from "if 2" to
4188 "endif 2".
4189 When searching backwards and {end} is more than one character,
4190 it may be useful to put "\zs" at the end of the pattern, so
4191 that when the cursor is inside a match with the end it finds
4192 the matching start.
4193
4194 Example, to find the "endif" command in a Vim script: >
4195
4196 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4197 \ 'getline(".") =~ "^\\s*\""')
4198
4199< The cursor must be at or after the "if" for which a match is
4200 to be found. Note that single-quote strings are used to avoid
4201 having to double the backslashes. The skip expression only
4202 catches comments at the start of a line, not after a command.
4203 Also, a word "en" or "if" halfway a line is considered a
4204 match.
4205 Another example, to search for the matching "{" of a "}": >
4206
4207 :echo searchpair('{', '', '}', 'bW')
4208
4209< This works when the cursor is at or before the "}" for which a
4210 match is to be found. To reject matches that syntax
4211 highlighting recognized as strings: >
4212
4213 :echo searchpair('{', '', '}', 'bW',
4214 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4215<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004216 *searchpairpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004217searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004218 Same as searchpair(), but returns a |List| with the line and
4219 column position of the match. The first element of the |List|
4220 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004221 the column position of the match. If no match is found,
4222 returns [0, 0].
4223>
4224 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4225<
4226 See |match-parens| for a bigger and more useful example.
4227
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004228searchpos({pattern} [, {flags} [, {stopline}]]) *searchpos()*
4229 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004230 column position of the match. The first element of the |List|
4231 is the line number and the second element is the byte index of
4232 the column position of the match. If no match is found,
4233 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004234 Example: >
4235 :let [lnum, col] = searchpos('mypattern', 'n')
4236
4237< When the 'p' flag is given then there is an extra item with
4238 the sub-pattern match number |search()-sub-match|. Example: >
4239 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4240< In this example "submatch" is 2 when a lowercase letter is
4241 found |/\l|, 3 when an uppercase letter is found |/\u|.
4242
Bram Moolenaar071d4272004-06-13 20:20:40 +00004243server2client( {clientid}, {string}) *server2client()*
4244 Send a reply string to {clientid}. The most recent {clientid}
4245 that sent a string can be retrieved with expand("<client>").
4246 {only available when compiled with the |+clientserver| feature}
4247 Note:
4248 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004249 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004250 before calling any commands that waits for input.
4251 See also |clientserver|.
4252 Example: >
4253 :echo server2client(expand("<client>"), "HELLO")
4254<
4255serverlist() *serverlist()*
4256 Return a list of available server names, one per line.
4257 When there are no servers or the information is not available
4258 an empty string is returned. See also |clientserver|.
4259 {only available when compiled with the |+clientserver| feature}
4260 Example: >
4261 :echo serverlist()
4262<
4263setbufvar({expr}, {varname}, {val}) *setbufvar()*
4264 Set option or local variable {varname} in buffer {expr} to
4265 {val}.
4266 This also works for a global or local window option, but it
4267 doesn't work for a global or local window variable.
4268 For a local window option the global value is unchanged.
4269 For the use of {expr}, see |bufname()| above.
4270 Note that the variable name without "b:" must be used.
4271 Examples: >
4272 :call setbufvar(1, "&mod", 1)
4273 :call setbufvar("todo", "myvar", "foobar")
4274< This function is not available in the |sandbox|.
4275
4276setcmdpos({pos}) *setcmdpos()*
4277 Set the cursor position in the command line to byte position
4278 {pos}. The first position is 1.
4279 Use |getcmdpos()| to obtain the current position.
4280 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00004281 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
4282 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
4283 set after the command line is set to the expression. For
4284 |c_CTRL-R_=| it is set after evaluating the expression but
4285 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004286 When the number is too big the cursor is put at the end of the
4287 line. A number smaller than one has undefined results.
4288 Returns 0 when successful, 1 when not editing the command
4289 line.
4290
4291setline({lnum}, {line}) *setline()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004292 Set line {lnum} of the current buffer to {line}.
4293 {lnum} is used like with |getline()|.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004294 When {lnum} is just below the last line the {line} will be
4295 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004296 If this succeeds, 0 is returned. If this fails (most likely
4297 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004298 :call setline(5, strftime("%c"))
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004299< When {line} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004300 will be set to the items in the list. Example: >
4301 :call setline(5, ['aaa', 'bbb', 'ccc'])
4302< This is equivalent to: >
4303 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
4304 : call setline(n, l)
4305 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004306< Note: The '[ and '] marks are not set.
4307
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004308setloclist({nr}, {list} [, {action}]) *setloclist()*
4309 Create or replace or add to the location list for window {nr}.
4310 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00004311 list window, the displayed location list is modified. For an
4312 invalid window number {nr}, -1 is returned.
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004313 Otherwise, same as setqflist().
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004314
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004315 *setpos()*
4316setpos({expr}, {list})
4317 Set the position for {expr}. Possible values:
4318 . the cursor
4319 'x mark x
4320
4321 {list} must be a |List| with four numbers:
4322 [bufnum, lnum, col, off]
4323
4324 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004325 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004326 the current buffer. To set a mark in another buffer you can
4327 use the |bufnr()| function to turn a file name into a buffer
4328 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00004329 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004330
4331 "lnum" and "col" are the position in the buffer. The first
4332 column is 1. Use a zero "lnum" to delete a mark.
4333
4334 The "off" number is only used when 'virtualedit' is set. Then
4335 it is the offset in screen columns from the start of the
4336 character. E.g., a position within a Tab or after the last
4337 character.
4338
4339 Also see |getpos()|
4340
4341
Bram Moolenaar35c54e52005-05-20 21:25:31 +00004342setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004343 Create or replace or add to the quickfix list using the items
4344 in {list}. Each item in {list} is a dictionary.
4345 Non-dictionary items in {list} are ignored. Each dictionary
4346 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004347
4348 filename name of a file
4349 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004350 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00004351 col column number
4352 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004353 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00004354 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004355 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00004356 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004357
Bram Moolenaar582fd852005-03-28 20:58:01 +00004358 The "col", "vcol", "nr", "type" and "text" entries are
4359 optional. Either "lnum" or "pattern" entry can be used to
4360 locate a matching error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004361 If the "filename" entry is not present or neither the "lnum"
4362 or "pattern" entries are present, then the item will not be
4363 handled as an error line.
4364 If both "pattern" and "lnum" are present then "pattern" will
4365 be used.
4366
Bram Moolenaar35c54e52005-05-20 21:25:31 +00004367 If {action} is set to 'a', then the items from {list} are
4368 added to the existing quickfix list. If there is no existing
4369 list, then a new list is created. If {action} is set to 'r',
4370 then the items from the current quickfix list are replaced
4371 with the items from {list}. If {action} is not present or is
4372 set to ' ', then a new list is created.
4373
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004374 Returns zero for success, -1 for failure.
4375
4376 This function can be used to create a quickfix list
4377 independent of the 'errorformat' setting. Use a command like
4378 ":cc 1" to jump to the first position.
4379
4380
Bram Moolenaar071d4272004-06-13 20:20:40 +00004381 *setreg()*
4382setreg({regname}, {value} [,{options}])
4383 Set the register {regname} to {value}.
4384 If {options} contains "a" or {regname} is upper case,
4385 then the value is appended.
4386 {options} can also contains a register type specification:
4387 "c" or "v" |characterwise| mode
4388 "l" or "V" |linewise| mode
4389 "b" or "<CTRL-V>" |blockwise-visual| mode
4390 If a number immediately follows "b" or "<CTRL-V>" then this is
4391 used as the width of the selection - if it is not specified
4392 then the width of the block is set to the number of characters
4393 in the longest line (counting a <TAB> as 1 character).
4394
4395 If {options} contains no register settings, then the default
4396 is to use character mode unless {value} ends in a <NL>.
4397 Setting the '=' register is not possible.
4398 Returns zero for success, non-zero for failure.
4399
4400 Examples: >
4401 :call setreg(v:register, @*)
4402 :call setreg('*', @%, 'ac')
4403 :call setreg('a', "1\n2\n3", 'b5')
4404
4405< This example shows using the functions to save and restore a
4406 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004407 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004408 :let var_amode = getregtype('a')
4409 ....
4410 :call setreg('a', var_a, var_amode)
4411
4412< You can also change the type of a register by appending
4413 nothing: >
4414 :call setreg('a', '', 'al')
4415
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004416settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
4417 Set option or local variable {varname} in window {winnr} to
4418 {val}.
4419 Tabs are numbered starting with one. For the current tabpage
4420 use |setwinvar()|.
4421 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004422 This also works for a global or local buffer option, but it
4423 doesn't work for a global or local buffer variable.
4424 For a local buffer option the global value is unchanged.
4425 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004426 Vim briefly goes to the tab page {tabnr}, this may trigger
4427 TabLeave and TabEnter autocommands.
4428 Examples: >
4429 :call settabwinvar(1, 1, "&list", 0)
4430 :call settabwinvar(3, 2, "myvar", "foobar")
4431< This function is not available in the |sandbox|.
4432
4433setwinvar({nr}, {varname}, {val}) *setwinvar()*
4434 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004435 Examples: >
4436 :call setwinvar(1, "&list", 0)
4437 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004438
Bram Moolenaar60a495f2006-10-03 12:44:42 +00004439shellescape({string}) *shellescape()*
4440 Escape {string} for use as shell command argument.
4441 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
4442 will enclose {string} double quotes and double all double
4443 quotes within {string}.
4444 For other systems, it will enclose {string} in single quotes
4445 and replace all "'" with "'\''".
4446 Example: >
4447 :echo shellescape('c:\program files\vim')
4448< results in:
4449 "c:\program files\vim" ~
4450 Example usage: >
4451 :call system("chmod +x -- " . shellescape(expand("%")))
4452
4453
Bram Moolenaar071d4272004-06-13 20:20:40 +00004454simplify({filename}) *simplify()*
4455 Simplify the file name as much as possible without changing
4456 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
4457 Unix) are not resolved. If the first path component in
4458 {filename} designates the current directory, this will be
4459 valid for the result as well. A trailing path separator is
4460 not removed either.
4461 Example: >
4462 simplify("./dir/.././/file/") == "./file/"
4463< Note: The combination "dir/.." is only removed if "dir" is
4464 a searchable directory or does not exist. On Unix, it is also
4465 removed when "dir" is a symbolic link within the same
4466 directory. In order to resolve all the involved symbolic
4467 links before simplifying the path name, use |resolve()|.
4468
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004469
Bram Moolenaar13065c42005-01-08 16:08:21 +00004470sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004471 Sort the items in {list} in-place. Returns {list}. If you
4472 want a list to remain unmodified make a copy first: >
4473 :let sortedlist = sort(copy(mylist))
4474< Uses the string representation of each item to sort on.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004475 Numbers sort after Strings, |Lists| after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004476 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004477 When {func} is given and it is one then case is ignored.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004478 When {func} is a |Funcref| or a function name, this function
4479 is called to compare items. The function is invoked with two
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004480 items as argument and must return zero if they are equal, 1 if
4481 the first one sorts after the second one, -1 if the first one
4482 sorts before the second one. Example: >
4483 func MyCompare(i1, i2)
4484 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
4485 endfunc
4486 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004487<
4488
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004489 *soundfold()*
4490soundfold({word})
4491 Return the sound-folded equivalent of {word}. Uses the first
4492 language in 'spellang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004493 soundfolding. 'spell' must be set. When no sound folding is
4494 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00004495 This can be used for making spelling suggestions. Note that
4496 the method can be quite slow.
4497
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004498 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00004499spellbadword([{sentence}])
4500 Without argument: The result is the badly spelled word under
4501 or after the cursor. The cursor is moved to the start of the
4502 bad word. When no bad word is found in the cursor line the
4503 result is an empty string and the cursor doesn't move.
4504
4505 With argument: The result is the first word in {sentence} that
4506 is badly spelled. If there are no spelling mistakes the
4507 result is an empty string.
4508
4509 The return value is a list with two items:
4510 - The badly spelled word or an empty string.
4511 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004512 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00004513 "rare" rare word
4514 "local" word only valid in another region
4515 "caps" word should start with Capital
4516 Example: >
4517 echo spellbadword("the quik brown fox")
4518< ['quik', 'bad'] ~
4519
4520 The spelling information for the current window is used. The
4521 'spell' option must be set and the value of 'spelllang' is
4522 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004523
4524 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004525spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004526 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004527 When {max} is given up to this number of suggestions are
4528 returned. Otherwise up to 25 suggestions are returned.
4529
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004530 When the {capital} argument is given and it's non-zero only
4531 suggestions with a leading capital will be given. Use this
4532 after a match with 'spellcapcheck'.
4533
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004534 {word} can be a badly spelled word followed by other text.
4535 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00004536 suggestions also include the following text, thus you can
4537 replace a line.
4538
4539 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00004540 returned. {word} itself is not included in the suggestions,
4541 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004542
4543 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00004544 'spell' option must be set and the values of 'spelllang' and
4545 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00004546
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004547
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004548split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004549 Make a |List| out of {expr}. When {pattern} is omitted or
4550 empty each white-separated sequence of characters becomes an
4551 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004552 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004553 removing the matched characters.
4554 When the first or last item is empty it is omitted, unless the
4555 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00004556 Other empty items are kept when {pattern} matches at least one
4557 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004558 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004559 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004560< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004561 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00004562< If you want to keep the separator you can also use '\zs': >
4563 :echo split('abc:def:ghi', ':\zs')
4564< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004565 Splitting a table where the first element can be empty: >
4566 :let items = split(line, ':', 1)
4567< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004568
4569
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004570str2nr( {expr} [, {base}]) *str2nr()*
4571 Convert string {expr} to a number.
4572 {base} is the conversion base, it can be 8, 10 or 16.
4573 When {base} is omitted base 10 is used. This also means that
4574 a leading zero doesn't cause octal conversion to be used, as
4575 with the default String to Number conversion.
4576 When {base} is 16 a leading "0x" or "0X" is ignored. With a
4577 different base the result will be zero.
4578 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004579
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004580
Bram Moolenaar071d4272004-06-13 20:20:40 +00004581strftime({format} [, {time}]) *strftime()*
4582 The result is a String, which is a formatted date and time, as
4583 specified by the {format} string. The given {time} is used,
4584 or the current time if no time is given. The accepted
4585 {format} depends on your system, thus this is not portable!
4586 See the manual page of the C function strftime() for the
4587 format. The maximum length of the result is 80 characters.
4588 See also |localtime()| and |getftime()|.
4589 The language can be changed with the |:language| command.
4590 Examples: >
4591 :echo strftime("%c") Sun Apr 27 11:49:23 1997
4592 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
4593 :echo strftime("%y%m%d %T") 970427 11:53:55
4594 :echo strftime("%H:%M") 11:55
4595 :echo strftime("%c", getftime("file.c"))
4596 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004597< Not available on all systems. To check use: >
4598 :if exists("*strftime")
4599
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004600stridx({haystack}, {needle} [, {start}]) *stridx()*
4601 The result is a Number, which gives the byte index in
4602 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004603 If {start} is specified, the search starts at index {start}.
4604 This can be used to find a second match: >
4605 :let comma1 = stridx(line, ",")
4606 :let comma2 = stridx(line, ",", comma1 + 1)
4607< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004608 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004609 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004610 See also |strridx()|.
4611 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004612 :echo stridx("An Example", "Example") 3
4613 :echo stridx("Starting point", "Start") 0
4614 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004615< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00004616 stridx() works similar to the C function strstr(). When used
4617 with a single character it works similar to strchr().
4618
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004619 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004620string({expr}) Return {expr} converted to a String. If {expr} is a Number,
4621 String or a composition of them, then the result can be parsed
4622 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004623 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00004624 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004625 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00004626 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004627 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00004628 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00004629 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004630
Bram Moolenaar071d4272004-06-13 20:20:40 +00004631 *strlen()*
4632strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00004633 {expr} in bytes.
4634 If you want to count the number of multi-byte characters (not
4635 counting composing characters) use something like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004636
4637 :let len = strlen(substitute(str, ".", "x", "g"))
Bram Moolenaare344bea2005-09-01 20:46:49 +00004638<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004639 If the argument is a Number it is first converted to a String.
4640 For other types an error is given.
4641 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004642
4643strpart({src}, {start}[, {len}]) *strpart()*
4644 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00004645 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004646 When non-existing bytes are included, this doesn't result in
4647 an error, the bytes are simply omitted.
4648 If {len} is missing, the copy continues from {start} till the
4649 end of the {src}. >
4650 strpart("abcdefg", 3, 2) == "de"
4651 strpart("abcdefg", -2, 4) == "ab"
4652 strpart("abcdefg", 5, 4) == "fg"
4653 strpart("abcdefg", 3) == "defg"
4654< Note: To get the first character, {start} must be 0. For
4655 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00004656 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004657<
Bram Moolenaar677ee682005-01-27 14:41:15 +00004658strridx({haystack}, {needle} [, {start}]) *strridx()*
4659 The result is a Number, which gives the byte index in
4660 {haystack} of the last occurrence of the String {needle}.
4661 When {start} is specified, matches beyond this index are
4662 ignored. This can be used to find a match before a previous
4663 match: >
4664 :let lastcomma = strridx(line, ",")
4665 :let comma2 = strridx(line, ",", lastcomma - 1)
4666< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004667 For pattern searches use |match()|.
4668 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00004669 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004670 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004671 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004672< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00004673 When used with a single character it works similar to the C
4674 function strrchr().
4675
Bram Moolenaar071d4272004-06-13 20:20:40 +00004676strtrans({expr}) *strtrans()*
4677 The result is a String, which is {expr} with all unprintable
4678 characters translated into printable characters |'isprint'|.
4679 Like they are shown in a window. Example: >
4680 echo strtrans(@a)
4681< This displays a newline in register a as "^@" instead of
4682 starting a new line.
4683
4684submatch({nr}) *submatch()*
4685 Only for an expression in a |:substitute| command. Returns
4686 the {nr}'th submatch of the matched text. When {nr} is 0
4687 the whole matched text is returned.
4688 Example: >
4689 :s/\d\+/\=submatch(0) + 1/
4690< This finds the first number in the line and adds one to it.
4691 A line break is included as a newline character.
4692
4693substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
4694 The result is a String, which is a copy of {expr}, in which
4695 the first match of {pat} is replaced with {sub}. This works
4696 like the ":substitute" command (without any flags). But the
4697 matching with {pat} is always done like the 'magic' option is
4698 set and 'cpoptions' is empty (to make scripts portable).
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004699 'ignorecase' is still relevant.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004700 See |string-match| for how {pat} is used.
4701 And a "~" in {sub} is not replaced with the previous {sub}.
4702 Note that some codes in {sub} have a special meaning
4703 |sub-replace-special|. For example, to replace something with
4704 "\n" (two characters), use "\\\\n" or '\\n'.
4705 When {pat} does not match in {expr}, {expr} is returned
4706 unmodified.
4707 When {flags} is "g", all matches of {pat} in {expr} are
4708 replaced. Otherwise {flags} should be "".
4709 Example: >
4710 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
4711< This removes the last component of the 'path' option. >
4712 :echo substitute("testing", ".*", "\\U\\0", "")
4713< results in "TESTING".
4714
Bram Moolenaar47136d72004-10-12 20:02:24 +00004715synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004716 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00004717 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004718 The syntax ID can be used with |synIDattr()| and
4719 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004720
Bram Moolenaar47136d72004-10-12 20:02:24 +00004721 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00004722 line. 'synmaxcol' applies, in a longer line zero is returned.
4723
Bram Moolenaar071d4272004-06-13 20:20:40 +00004724 When {trans} is non-zero, transparent items are reduced to the
4725 item that they reveal. This is useful when wanting to know
4726 the effective color. When {trans} is zero, the transparent
4727 item is returned. This is useful when wanting to know which
4728 syntax item is effective (e.g. inside parens).
4729 Warning: This function can be very slow. Best speed is
4730 obtained by going through the file in forward direction.
4731
4732 Example (echoes the name of the syntax item under the cursor): >
4733 :echo synIDattr(synID(line("."), col("."), 1), "name")
4734<
4735synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
4736 The result is a String, which is the {what} attribute of
4737 syntax ID {synID}. This can be used to obtain information
4738 about a syntax item.
4739 {mode} can be "gui", "cterm" or "term", to get the attributes
4740 for that mode. When {mode} is omitted, or an invalid value is
4741 used, the attributes for the currently active highlighting are
4742 used (GUI, cterm or term).
4743 Use synIDtrans() to follow linked highlight groups.
4744 {what} result
4745 "name" the name of the syntax item
4746 "fg" foreground color (GUI: color name used to set
4747 the color, cterm: color number as a string,
4748 term: empty string)
4749 "bg" background color (like "fg")
4750 "fg#" like "fg", but for the GUI and the GUI is
4751 running the name in "#RRGGBB" form
4752 "bg#" like "fg#" for "bg"
4753 "bold" "1" if bold
4754 "italic" "1" if italic
4755 "reverse" "1" if reverse
4756 "inverse" "1" if inverse (= reverse)
4757 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004758 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00004759
4760 Example (echoes the color of the syntax item under the
4761 cursor): >
4762 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
4763<
4764synIDtrans({synID}) *synIDtrans()*
4765 The result is a Number, which is the translated syntax ID of
4766 {synID}. This is the syntax group ID of what is being used to
4767 highlight the character. Highlight links given with
4768 ":highlight link" are followed.
4769
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004770system({expr} [, {input}]) *system()* *E677*
4771 Get the output of the shell command {expr}.
4772 When {input} is given, this string is written to a file and
4773 passed as stdin to the command. The string is written as-is,
4774 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00004775 yourself. Pipes are not used.
Bram Moolenaarc0197e22004-09-13 20:26:32 +00004776 Note: newlines in {expr} may cause the command to fail. The
4777 characters in 'shellquote' and 'shellxquote' may also cause
4778 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004779 This is not to be used for interactive commands.
4780 The result is a String. Example: >
4781
4782 :let files = system("ls")
4783
4784< To make the result more system-independent, the shell output
4785 is filtered to replace <CR> with <NL> for Macintosh, and
4786 <CR><NL> with <NL> for DOS-like systems.
4787 The command executed is constructed using several options:
4788 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
4789 ({tmp} is an automatically generated file name).
4790 For Unix and OS/2 braces are put around {expr} to allow for
4791 concatenated commands.
4792
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004793 The command will be executed in "cooked" mode, so that a
4794 CTRL-C will interrupt the command (on Unix at least).
4795
Bram Moolenaar071d4272004-06-13 20:20:40 +00004796 The resulting error code can be found in |v:shell_error|.
4797 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00004798
4799 Note that any wrong value in the options mentioned above may
4800 make the function fail. It has also been reported to fail
4801 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004802 Unlike ":!cmd" there is no automatic check for changed files.
4803 Use |:checktime| to force a check.
4804
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004805
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004806tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004807 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004808 buffer associated with each window in the current tab page.
4809 {arg} specifies the number of tab page to be used. When
4810 omitted the current tab page is used.
4811 When {arg} is invalid the number zero is returned.
4812 To get a list of all buffers in all tabs use this: >
4813 tablist = []
4814 for i in range(tabpagenr('$'))
4815 call extend(tablist, tabpagebuflist(i + 1))
4816 endfor
4817< Note that a buffer may appear in more than one window.
4818
4819
4820tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00004821 The result is a Number, which is the number of the current
4822 tab page. The first tab page has number 1.
4823 When the optional argument is "$", the number of the last tab
4824 page is returned (the tab page count).
4825 The number can be used with the |:tab| command.
4826
4827
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004828tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
4829 Like |winnr()| but for tab page {arg}.
4830 {tabarg} specifies the number of tab page to be used.
4831 {arg} is used like with |winnr()|:
4832 - When omitted the current window number is returned. This is
4833 the window which will be used when going to this tab page.
4834 - When "$" the number of windows is returned.
4835 - When "#" the previous window nr is returned.
4836 Useful examples: >
4837 tabpagewinnr(1) " current window of tab page 1
4838 tabpagewinnr(4, '$') " number of windows in tab page 4
4839< When {tabarg} is invalid zero is returned.
4840
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00004841 *tagfiles()*
4842tagfiles() Returns a |List| with the file names used to search for tags
4843 for the current buffer. This is the 'tags' option expanded.
4844
4845
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004846taglist({expr}) *taglist()*
4847 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00004848 Each list item is a dictionary with at least the following
4849 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00004850 name Name of the tag.
4851 filename Name of the file where the tag is
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004852 defined.
4853 cmd Ex command used to locate the tag in
4854 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004855 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004856 entry depends on the language specific
4857 kind values generated by the ctags
4858 tool.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004859 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004860 |static-tag| for more information.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004861 The "kind" entry is only available when using Exuberant ctags
4862 generated tags file. More entries may be present, depending
4863 on the content of the tags file: access, implementation,
4864 inherits and signature. Refer to the ctags documentation for
4865 information about these fields. For C code the fields
4866 "struct", "class" and "enum" may appear, they give the name of
4867 the entity the tag is contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004868
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004869 The ex-command 'cmd' can be either an ex search pattern, a
4870 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004871
4872 If there are no matching tags, then an empty list is returned.
4873
4874 To get an exact tag match, the anchors '^' and '$' should be
4875 used in {expr}. Refer to |tag-regexp| for more information
4876 about the tag search regular expression pattern.
4877
4878 Refer to |'tags'| for information about how the tags file is
4879 located by Vim. Refer to |tags-file-format| for the format of
4880 the tags file generated by the different ctags tools.
4881
Bram Moolenaar071d4272004-06-13 20:20:40 +00004882tempname() *tempname()* *temp-file-name*
4883 The result is a String, which is the name of a file that
4884 doesn't exist. It can be used for a temporary file. The name
4885 is different for at least 26 consecutive calls. Example: >
4886 :let tmpfile = tempname()
4887 :exe "redir > " . tmpfile
4888< For Unix, the file will be in a private directory (only
4889 accessible by the current user) to avoid security problems
4890 (e.g., a symlink attack or other people reading your file).
4891 When Vim exits the directory and all files in it are deleted.
4892 For MS-Windows forward slashes are used when the 'shellslash'
4893 option is set or when 'shellcmdflag' starts with '-'.
4894
4895tolower({expr}) *tolower()*
4896 The result is a copy of the String given, with all uppercase
4897 characters turned into lowercase (just like applying |gu| to
4898 the string).
4899
4900toupper({expr}) *toupper()*
4901 The result is a copy of the String given, with all lowercase
4902 characters turned into uppercase (just like applying |gU| to
4903 the string).
4904
Bram Moolenaar8299df92004-07-10 09:47:34 +00004905tr({src}, {fromstr}, {tostr}) *tr()*
4906 The result is a copy of the {src} string with all characters
4907 which appear in {fromstr} replaced by the character in that
4908 position in the {tostr} string. Thus the first character in
4909 {fromstr} is translated into the first character in {tostr}
4910 and so on. Exactly like the unix "tr" command.
4911 This code also deals with multibyte characters properly.
4912
4913 Examples: >
4914 echo tr("hello there", "ht", "HT")
4915< returns "Hello THere" >
4916 echo tr("<blob>", "<>", "{}")
4917< returns "{blob}"
4918
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004919 *type()*
4920type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00004921 Number: 0
4922 String: 1
4923 Funcref: 2
4924 List: 3
4925 Dictionary: 4
4926 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004927 :if type(myvar) == type(0)
4928 :if type(myvar) == type("")
4929 :if type(myvar) == type(function("tr"))
4930 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00004931 :if type(myvar) == type({})
Bram Moolenaar071d4272004-06-13 20:20:40 +00004932
Bram Moolenaar677ee682005-01-27 14:41:15 +00004933values({dict}) *values()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004934 Return a |List| with all the values of {dict}. The |List| is
4935 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004936
4937
Bram Moolenaar071d4272004-06-13 20:20:40 +00004938virtcol({expr}) *virtcol()*
4939 The result is a Number, which is the screen column of the file
4940 position given with {expr}. That is, the last screen position
4941 occupied by the character at that position, when the screen
4942 would be of unlimited width. When there is a <Tab> at the
4943 position, the returned Number will be the column at the end of
4944 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
4945 set to 8, it returns 8.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004946 For the use of {expr} see |col()|. Additionally you can use
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004947 [lnum, col]: a |List| with the line and column number. When
4948 "lnum" or "col" is out of range then virtcol() returns zero.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004949 When 'virtualedit' is used it can be [lnum, col, off], where
4950 "off" is the offset in screen columns from the start of the
4951 character. E.g., a position within a Tab or after the last
4952 character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004953 For the byte position use |col()|.
4954 When Virtual editing is active in the current mode, a position
4955 beyond the end of the line can be returned. |'virtualedit'|
4956 The accepted positions are:
4957 . the cursor position
4958 $ the end of the cursor line (the result is the
4959 number of displayed characters in the cursor line
4960 plus one)
4961 'x position of mark x (if the mark is not set, 0 is
4962 returned)
4963 Note that only marks in the current file can be used.
4964 Examples: >
4965 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
4966 virtcol("$") with text "foo^Lbar", returns 9
4967 virtcol("'t") with text " there", with 't at 'h', returns 6
4968< The first column is 1. 0 is returned for an error.
4969
4970visualmode([expr]) *visualmode()*
4971 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004972 used in the current buffer. Initially it returns an empty
4973 string, but once Visual mode has been used, it returns "v",
4974 "V", or "<CTRL-V>" (a single CTRL-V character) for
4975 character-wise, line-wise, or block-wise Visual mode
4976 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004977 Example: >
4978 :exe "normal " . visualmode()
4979< This enters the same Visual mode as before. It is also useful
4980 in scripts if you wish to act differently depending on the
4981 Visual mode that was used.
4982
4983 If an expression is supplied that results in a non-zero number
4984 or a non-empty string, then the Visual mode will be cleared
4985 and the old value is returned. Note that " " and "0" are also
4986 non-empty strings, thus cause the mode to be cleared.
4987
4988 *winbufnr()*
4989winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004990 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004991 the buffer in the current window is returned. When window
4992 {nr} doesn't exist, -1 is returned.
4993 Example: >
4994 :echo "The file in the current window is " . bufname(winbufnr(0))
4995<
4996 *wincol()*
4997wincol() The result is a Number, which is the virtual column of the
4998 cursor in the window. This is counting screen cells from the
4999 left side of the window. The leftmost column is one.
5000
5001winheight({nr}) *winheight()*
5002 The result is a Number, which is the height of window {nr}.
5003 When {nr} is zero, the height of the current window is
5004 returned. When window {nr} doesn't exist, -1 is returned.
5005 An existing window always has a height of zero or more.
5006 Examples: >
5007 :echo "The current window has " . winheight(0) . " lines."
5008<
5009 *winline()*
5010winline() The result is a Number, which is the screen line of the cursor
5011 in the window. This is counting screen lines from the top of
5012 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005013 If the cursor was moved the view on the file will be updated
5014 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005015
5016 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005017winnr([{arg}]) The result is a Number, which is the number of the current
5018 window. The top window has number 1.
5019 When the optional argument is "$", the number of the
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00005020 last window is returned (the window count).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005021 When the optional argument is "#", the number of the last
5022 accessed window is returned (where |CTRL-W_p| goes to).
5023 If there is no previous window 0 is returned.
5024 The number can be used with |CTRL-W_w| and ":wincmd w"
5025 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005026
5027 *winrestcmd()*
5028winrestcmd() Returns a sequence of |:resize| commands that should restore
5029 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005030 are opened or closed and the current window and tab page is
5031 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005032 Example: >
5033 :let cmd = winrestcmd()
5034 :call MessWithWindowSizes()
5035 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005036<
5037 *winrestview()*
5038winrestview({dict})
5039 Uses the |Dictionary| returned by |winsaveview()| to restore
5040 the view of the current window.
5041 If you have changed the values the result is unpredictable.
5042 If the window size changed the result won't be the same.
5043
5044 *winsaveview()*
5045winsaveview() Returns a |Dictionary| that contains information to restore
5046 the view of the current window. Use |winrestview()| to
5047 restore the view.
5048 This is useful if you have a mapping that jumps around in the
5049 buffer and you want to go back to the original view.
5050 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00005051 option to temporarily switch off folding, so that folds are
5052 not opened when moving around.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005053 The return value includes:
5054 lnum cursor line number
5055 col cursor column
5056 coladd cursor column offset for 'virtualedit'
5057 curswant column for vertical movement
5058 topline first line in the window
5059 topfill filler lines, only in diff mode
5060 leftcol first column displayed
5061 skipcol columns skipped
5062 Note that no option values are saved.
5063
Bram Moolenaar071d4272004-06-13 20:20:40 +00005064
5065winwidth({nr}) *winwidth()*
5066 The result is a Number, which is the width of window {nr}.
5067 When {nr} is zero, the width of the current window is
5068 returned. When window {nr} doesn't exist, -1 is returned.
5069 An existing window always has a width of zero or more.
5070 Examples: >
5071 :echo "The current window has " . winwidth(0) . " columns."
5072 :if winwidth(0) <= 50
5073 : exe "normal 50\<C-W>|"
5074 :endif
5075<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005076 *writefile()*
5077writefile({list}, {fname} [, {binary}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005078 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005079 separated with a NL. Each list item must be a String or
5080 Number.
5081 When {binary} is equal to "b" binary mode is used: There will
5082 not be a NL after the last list item. An empty item at the
5083 end does cause the last line in the file to end in a NL.
5084 All NL characters are replaced with a NUL character.
5085 Inserting CR characters needs to be done before passing {list}
5086 to writefile().
5087 An existing file is overwritten, if possible.
5088 When the write fails -1 is returned, otherwise 0. There is an
5089 error message if the file can't be created or when writing
5090 fails.
5091 Also see |readfile()|.
5092 To copy a file byte for byte: >
5093 :let fl = readfile("foo", "b")
5094 :call writefile(fl, "foocopy", "b")
5095<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005096
5097 *feature-list*
5098There are three types of features:
50991. Features that are only supported when they have been enabled when Vim
5100 was compiled |+feature-list|. Example: >
5101 :if has("cindent")
51022. Features that are only supported when certain conditions have been met.
5103 Example: >
5104 :if has("gui_running")
5105< *has-patch*
51063. Included patches. First check |v:version| for the version of Vim.
5107 Then the "patch123" feature means that patch 123 has been included for
5108 this version. Example (checking version 6.2.148 or later): >
5109 :if v:version > 602 || v:version == 602 && has("patch148")
5110
5111all_builtin_terms Compiled with all builtin terminals enabled.
5112amiga Amiga version of Vim.
5113arabic Compiled with Arabic support |Arabic|.
5114arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00005115autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005116balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00005117balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005118beos BeOS version of Vim.
5119browse Compiled with |:browse| support, and browse() will
5120 work.
5121builtin_terms Compiled with some builtin terminals.
5122byte_offset Compiled with support for 'o' in 'statusline'
5123cindent Compiled with 'cindent' support.
5124clientserver Compiled with remote invocation support |clientserver|.
5125clipboard Compiled with 'clipboard' support.
5126cmdline_compl Compiled with |cmdline-completion| support.
5127cmdline_hist Compiled with |cmdline-history| support.
5128cmdline_info Compiled with 'showcmd' and 'ruler' support.
5129comments Compiled with |'comments'| support.
5130cryptv Compiled with encryption support |encryption|.
5131cscope Compiled with |cscope| support.
5132compatible Compiled to be very Vi compatible.
5133debug Compiled with "DEBUG" defined.
5134dialog_con Compiled with console dialog support.
5135dialog_gui Compiled with GUI dialog support.
5136diff Compiled with |vimdiff| and 'diff' support.
5137digraphs Compiled with support for digraphs.
5138dnd Compiled with support for the "~ register |quote_~|.
5139dos32 32 bits DOS (DJGPP) version of Vim.
5140dos16 16 bits DOS version of Vim.
5141ebcdic Compiled on a machine with ebcdic character set.
5142emacs_tags Compiled with support for Emacs tags.
5143eval Compiled with expression evaluation support. Always
5144 true, of course!
5145ex_extra Compiled with extra Ex commands |+ex_extra|.
5146extra_search Compiled with support for |'incsearch'| and
5147 |'hlsearch'|
5148farsi Compiled with Farsi support |farsi|.
5149file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005150filterpipe When 'shelltemp' is off pipes are used for shell
5151 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00005152find_in_path Compiled with support for include file searches
5153 |+find_in_path|.
5154fname_case Case in file names matters (for Amiga, MS-DOS, and
5155 Windows this is not present).
5156folding Compiled with |folding| support.
5157footer Compiled with GUI footer support. |gui-footer|
5158fork Compiled to use fork()/exec() instead of system().
5159gettext Compiled with message translation |multi-lang|
5160gui Compiled with GUI enabled.
5161gui_athena Compiled with Athena GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005162gui_gtk Compiled with GTK+ GUI (any version).
5163gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
5164gui_mac Compiled with Macintosh GUI.
5165gui_motif Compiled with Motif GUI.
5166gui_photon Compiled with Photon GUI.
5167gui_win32 Compiled with MS Windows Win32 GUI.
5168gui_win32s idem, and Win32s system being used (Windows 3.1)
5169gui_running Vim is running in the GUI, or it will start soon.
5170hangul_input Compiled with Hangul input support. |hangul|
5171iconv Can use iconv() for conversion.
5172insert_expand Compiled with support for CTRL-X expansion commands in
5173 Insert mode.
5174jumplist Compiled with |jumplist| support.
5175keymap Compiled with 'keymap' support.
5176langmap Compiled with 'langmap' support.
5177libcall Compiled with |libcall()| support.
5178linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
5179 support.
5180lispindent Compiled with support for lisp indenting.
5181listcmds Compiled with commands for the buffer list |:files|
5182 and the argument list |arglist|.
5183localmap Compiled with local mappings and abbr. |:map-local|
5184mac Macintosh version of Vim.
5185macunix Macintosh version of Vim, using Unix files (OS-X).
5186menu Compiled with support for |:menu|.
5187mksession Compiled with support for |:mksession|.
5188modify_fname Compiled with file name modifiers. |filename-modifiers|
5189mouse Compiled with support mouse.
5190mouseshape Compiled with support for 'mouseshape'.
5191mouse_dec Compiled with support for Dec terminal mouse.
5192mouse_gpm Compiled with support for gpm (Linux console mouse)
5193mouse_netterm Compiled with support for netterm mouse.
5194mouse_pterm Compiled with support for qnx pterm mouse.
5195mouse_xterm Compiled with support for xterm mouse.
5196multi_byte Compiled with support for editing Korean et al.
5197multi_byte_ime Compiled with support for IME input method.
5198multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005199mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005200netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00005201netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005202ole Compiled with OLE automation support for Win32.
5203os2 OS/2 version of Vim.
5204osfiletype Compiled with support for osfiletypes |+osfiletype|
5205path_extra Compiled with up/downwards search in 'path' and 'tags'
5206perl Compiled with Perl interface.
5207postscript Compiled with PostScript file printing.
5208printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005209profile Compiled with |:profile| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005210python Compiled with Python interface.
5211qnx QNX version of Vim.
5212quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00005213reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005214rightleft Compiled with 'rightleft' support.
5215ruby Compiled with Ruby interface |ruby|.
5216scrollbind Compiled with 'scrollbind' support.
5217showcmd Compiled with 'showcmd' support.
5218signs Compiled with |:sign| support.
5219smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00005220sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005221statusline Compiled with support for 'statusline', 'rulerformat'
5222 and special formats of 'titlestring' and 'iconstring'.
5223sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00005224spell Compiled with spell checking support |spell|.
5225syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005226syntax_items There are active syntax highlighting items for the
5227 current buffer.
5228system Compiled to use system() instead of fork()/exec().
5229tag_binary Compiled with binary searching in tags files
5230 |tag-binary-search|.
5231tag_old_static Compiled with support for old static tags
5232 |tag-old-static|.
5233tag_any_white Compiled with support for any white characters in tags
5234 files |tag-any-white|.
5235tcl Compiled with Tcl interface.
5236terminfo Compiled with terminfo instead of termcap.
5237termresponse Compiled with support for |t_RV| and |v:termresponse|.
5238textobjects Compiled with support for |text-objects|.
5239tgetent Compiled with tgetent support, able to use a termcap
5240 or terminfo file.
5241title Compiled with window title support |'title'|.
5242toolbar Compiled with support for |gui-toolbar|.
5243unix Unix version of Vim.
5244user_commands User-defined commands.
5245viminfo Compiled with viminfo support.
5246vim_starting True while initial source'ing takes place.
5247vertsplit Compiled with vertically split windows |:vsplit|.
5248virtualedit Compiled with 'virtualedit' option.
5249visual Compiled with Visual mode.
5250visualextra Compiled with extra Visual mode commands.
5251 |blockwise-operators|.
5252vms VMS version of Vim.
5253vreplace Compiled with |gR| and |gr| commands.
5254wildignore Compiled with 'wildignore' option.
5255wildmenu Compiled with 'wildmenu' option.
5256windows Compiled with support for more than one window.
5257winaltkeys Compiled with 'winaltkeys' option.
5258win16 Win16 version of Vim (MS-Windows 3.1).
5259win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
5260win64 Win64 version of Vim (MS-Windows 64 bit).
5261win32unix Win32 version of Vim, using Unix files (Cygwin)
5262win95 Win32 version for MS-Windows 95/98/ME.
5263writebackup Compiled with 'writebackup' default on.
5264xfontset Compiled with X fontset support |xfontset|.
5265xim Compiled with X input method support |xim|.
5266xsmp Compiled with X session management support.
5267xsmp_interact Compiled with interactive X session management support.
5268xterm_clipboard Compiled with support for xterm clipboard.
5269xterm_save Compiled with support for saving and restoring the
5270 xterm screen.
5271x11 Compiled with X11 support.
5272
5273 *string-match*
5274Matching a pattern in a String
5275
5276A regexp pattern as explained at |pattern| is normally used to find a match in
5277the buffer lines. When a pattern is used to find a match in a String, almost
5278everything works in the same way. The difference is that a String is handled
5279like it is one line. When it contains a "\n" character, this is not seen as a
5280line break for the pattern. It can be matched with a "\n" in the pattern, or
5281with ".". Example: >
5282 :let a = "aaaa\nxxxx"
5283 :echo matchstr(a, "..\n..")
5284 aa
5285 xx
5286 :echo matchstr(a, "a.x")
5287 a
5288 x
5289
5290Don't forget that "^" will only match at the first character of the String and
5291"$" at the last character of the string. They don't match after or before a
5292"\n".
5293
5294==============================================================================
52955. Defining functions *user-functions*
5296
5297New functions can be defined. These can be called just like builtin
5298functions. The function executes a sequence of Ex commands. Normal mode
5299commands can be executed with the |:normal| command.
5300
5301The function name must start with an uppercase letter, to avoid confusion with
5302builtin functions. To prevent from using the same name in different scripts
5303avoid obvious, short names. A good habit is to start the function name with
5304the name of the script, e.g., "HTMLcolor()".
5305
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005306It's also possible to use curly braces, see |curly-braces-names|. And the
5307|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005308
5309 *local-function*
5310A function local to a script must start with "s:". A local script function
5311can only be called from within the script and from functions, user commands
5312and autocommands defined in the script. It is also possible to call the
5313function from a mappings defined in the script, but then |<SID>| must be used
5314instead of "s:" when the mapping is expanded outside of the script.
5315
5316 *:fu* *:function* *E128* *E129* *E123*
5317:fu[nction] List all functions and their arguments.
5318
5319:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005320 {name} can also be a |Dictionary| entry that is a
5321 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005322 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005323
5324:fu[nction] /{pattern} List functions with a name matching {pattern}.
5325 Example that lists all functions ending with "File": >
5326 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00005327<
5328 *:function-verbose*
5329When 'verbose' is non-zero, listing a function will also display where it was
5330last defined. Example: >
5331
5332 :verbose function SetFileTypeSH
5333 function SetFileTypeSH(name)
5334 Last set from /usr/share/vim/vim-7.0/filetype.vim
5335<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005336See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00005337
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005338 *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005339:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00005340 Define a new function by the name {name}. The name
5341 must be made of alphanumeric characters and '_', and
5342 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005343
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005344 {name} can also be a |Dictionary| entry that is a
5345 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005346 :function dict.init(arg)
5347< "dict" must be an existing dictionary. The entry
5348 "init" is added if it didn't exist yet. Otherwise [!]
5349 is required to overwrite an existing function. The
5350 result is a |Funcref| to a numbered function. The
5351 function can only be used with a |Funcref| and will be
5352 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005353 *E127* *E122*
5354 When a function by this name already exists and [!] is
5355 not used an error message is given. When [!] is used,
5356 an existing function is silently replaced. Unless it
5357 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005358
5359 For the {arguments} see |function-argument|.
5360
Bram Moolenaar071d4272004-06-13 20:20:40 +00005361 *a:firstline* *a:lastline*
5362 When the [range] argument is added, the function is
5363 expected to take care of a range itself. The range is
5364 passed as "a:firstline" and "a:lastline". If [range]
5365 is excluded, ":{range}call" will call the function for
5366 each line in the range, with the cursor on the start
5367 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005368
Bram Moolenaar071d4272004-06-13 20:20:40 +00005369 When the [abort] argument is added, the function will
5370 abort as soon as an error is detected.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005371
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005372 When the [dict] argument is added, the function must
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005373 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005374 local variable "self" will then be set to the
5375 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005376
Bram Moolenaar98692072006-02-04 00:57:42 +00005377 The last used search pattern and the redo command "."
5378 will not be changed by the function.
5379
Bram Moolenaar071d4272004-06-13 20:20:40 +00005380 *:endf* *:endfunction* *E126* *E193*
5381:endf[unction] The end of a function definition. Must be on a line
5382 by its own, without other commands.
5383
5384 *:delf* *:delfunction* *E130* *E131*
5385:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005386 {name} can also be a |Dictionary| entry that is a
5387 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005388 :delfunc dict.init
5389< This will remove the "init" entry from "dict". The
5390 function is deleted if there are no more references to
5391 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005392 *:retu* *:return* *E133*
5393:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
5394 evaluated and returned as the result of the function.
5395 If "[expr]" is not given, the number 0 is returned.
5396 When a function ends without an explicit ":return",
5397 the number 0 is returned.
5398 Note that there is no check for unreachable lines,
5399 thus there is no warning if commands follow ":return".
5400
5401 If the ":return" is used after a |:try| but before the
5402 matching |:finally| (if present), the commands
5403 following the ":finally" up to the matching |:endtry|
5404 are executed first. This process applies to all
5405 nested ":try"s inside the function. The function
5406 returns at the outermost ":endtry".
5407
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005408 *function-argument* *a:var*
5409An argument can be defined by giving its name. In the function this can then
5410be used as "a:name" ("a:" for argument).
5411 *a:0* *a:1* *a:000* *E740*
5412Up to 20 arguments can be given, separated by commas. After the named
5413arguments an argument "..." can be specified, which means that more arguments
5414may optionally be following. In the function the extra arguments can be used
5415as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005416can be 0). "a:000" is set to a |List| that contains these arguments. Note
5417that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005418 *E742*
5419The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005420However, if a |List| or |Dictionary| is used, you can changes their contents.
5421Thus you can pass a |List| to a function and have the function add an item to
5422it. If you want to make sure the function cannot change a |List| or
5423|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005424
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005425When not using "...", the number of arguments in a function call must be equal
5426to the number of named arguments. When using "...", the number of arguments
5427may be larger.
5428
5429It is also possible to define a function without any arguments. You must
5430still supply the () then. The body of the function follows in the next lines,
5431until the matching |:endfunction|. It is allowed to define another function
5432inside a function body.
5433
5434 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005435Inside a function variables can be used. These are local variables, which
5436will disappear when the function returns. Global variables need to be
5437accessed with "g:".
5438
5439Example: >
5440 :function Table(title, ...)
5441 : echohl Title
5442 : echo a:title
5443 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00005444 : echo a:0 . " items:"
5445 : for s in a:000
5446 : echon ' ' . s
5447 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005448 :endfunction
5449
5450This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00005451 call Table("Table", "line1", "line2")
5452 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005453
5454To return more than one value, pass the name of a global variable: >
5455 :function Compute(n1, n2, divname)
5456 : if a:n2 == 0
5457 : return "fail"
5458 : endif
5459 : let g:{a:divname} = a:n1 / a:n2
5460 : return "ok"
5461 :endfunction
5462
5463This function can then be called with: >
5464 :let success = Compute(13, 1324, "div")
5465 :if success == "ok"
5466 : echo div
5467 :endif
5468
5469An alternative is to return a command that can be executed. This also works
5470with local variables in a calling function. Example: >
5471 :function Foo()
5472 : execute Bar()
5473 : echo "line " . lnum . " column " . col
5474 :endfunction
5475
5476 :function Bar()
5477 : return "let lnum = " . line(".") . " | let col = " . col(".")
5478 :endfunction
5479
5480The names "lnum" and "col" could also be passed as argument to Bar(), to allow
5481the caller to set the names.
5482
Bram Moolenaar39f05632006-03-19 22:15:26 +00005483 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005484:[range]cal[l] {name}([arguments])
5485 Call a function. The name of the function and its arguments
5486 are as specified with |:function|. Up to 20 arguments can be
5487 used.
5488 Without a range and for functions that accept a range, the
5489 function is called once. When a range is given the cursor is
5490 positioned at the start of the first line before executing the
5491 function.
5492 When a range is given and the function doesn't handle it
5493 itself, the function is executed for each line in the range,
5494 with the cursor in the first column of that line. The cursor
5495 is left at the last line (possibly moved by the last function
5496 call). The arguments are re-evaluated for each line. Thus
5497 this works:
5498 *function-range-example* >
5499 :function Mynumber(arg)
5500 : echo line(".") . " " . a:arg
5501 :endfunction
5502 :1,5call Mynumber(getline("."))
5503<
5504 The "a:firstline" and "a:lastline" are defined anyway, they
5505 can be used to do something different at the start or end of
5506 the range.
5507
5508 Example of a function that handles the range itself: >
5509
5510 :function Cont() range
5511 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
5512 :endfunction
5513 :4,8call Cont()
5514<
5515 This function inserts the continuation character "\" in front
5516 of all the lines in the range, except the first one.
5517
5518 *E132*
5519The recursiveness of user functions is restricted with the |'maxfuncdepth'|
5520option.
5521
Bram Moolenaar7c626922005-02-07 22:01:03 +00005522
5523AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005524 *autoload-functions*
5525When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00005526only when they are used. There are two methods: with an autocommand and with
5527the "autoload" directory in 'runtimepath'.
5528
5529
5530Using an autocommand ~
5531
Bram Moolenaar05159a02005-02-26 23:04:13 +00005532This is introduced in the user manual, section |41.14|.
5533
Bram Moolenaar7c626922005-02-07 22:01:03 +00005534The autocommand is useful if you have a plugin that is a long Vim script file.
5535You can define the autocommand and quickly quit the script with |:finish|.
5536That makes Vim startup faster. The autocommand should then load the same file
5537again, setting a variable to skip the |:finish| command.
5538
5539Use the FuncUndefined autocommand event with a pattern that matches the
5540function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005541
5542 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
5543
5544The file "~/vim/bufnetfuncs.vim" should then define functions that start with
5545"BufNet". Also see |FuncUndefined|.
5546
Bram Moolenaar7c626922005-02-07 22:01:03 +00005547
5548Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005549 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005550This is introduced in the user manual, section |41.15|.
5551
Bram Moolenaar7c626922005-02-07 22:01:03 +00005552Using a script in the "autoload" directory is simpler, but requires using
5553exactly the right file name. A function that can be autoloaded has a name
5554like this: >
5555
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005556 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005557
5558When such a function is called, and it is not defined yet, Vim will search the
5559"autoload" directories in 'runtimepath' for a script file called
5560"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
5561then define the function like this: >
5562
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005563 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005564 echo "Done!"
5565 endfunction
5566
Bram Moolenaar60a795a2005-09-16 21:55:43 +00005567The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00005568exactly, and the defined function must have the name exactly as it will be
5569called.
5570
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005571It is possible to use subdirectories. Every # in the function name works like
5572a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00005573
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005574 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00005575
5576Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
5577
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005578This also works when reading a variable that has not been set yet: >
5579
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005580 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005581
Bram Moolenaara5792f52005-11-23 21:25:05 +00005582However, when the autoload script was already loaded it won't be loaded again
5583for an unknown variable.
5584
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005585When assigning a value to such a variable nothing special happens. This can
5586be used to pass settings to the autoload script before it's loaded: >
5587
Bram Moolenaara7fc0102005-05-18 22:17:12 +00005588 :let foo#bar#toggle = 1
5589 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005590
Bram Moolenaar4399ef42005-02-12 14:29:27 +00005591Note that when you make a mistake and call a function that is supposed to be
5592defined in an autoload script, but the script doesn't actually define the
5593function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005594And you will get an error message every time.
5595
5596Also note that if you have two script files, and one calls a function in the
5597other and vise versa, before the used function is defined, it won't work.
5598Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00005599
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005600Hint: If you distribute a bunch of scripts you can pack them together with the
5601|vimball| utility. Also read the user manual |distribute-script|.
5602
Bram Moolenaar071d4272004-06-13 20:20:40 +00005603==============================================================================
56046. Curly braces names *curly-braces-names*
5605
5606Wherever you can use a variable, you can use a "curly braces name" variable.
5607This is a regular variable name with one or more expressions wrapped in braces
5608{} like this: >
5609 my_{adjective}_variable
5610
5611When Vim encounters this, it evaluates the expression inside the braces, puts
5612that in place of the expression, and re-interprets the whole as a variable
5613name. So in the above example, if the variable "adjective" was set to
5614"noisy", then the reference would be to "my_noisy_variable", whereas if
5615"adjective" was set to "quiet", then it would be to "my_quiet_variable".
5616
5617One application for this is to create a set of variables governed by an option
5618value. For example, the statement >
5619 echo my_{&background}_message
5620
5621would output the contents of "my_dark_message" or "my_light_message" depending
5622on the current value of 'background'.
5623
5624You can use multiple brace pairs: >
5625 echo my_{adverb}_{adjective}_message
5626..or even nest them: >
5627 echo my_{ad{end_of_word}}_message
5628where "end_of_word" is either "verb" or "jective".
5629
5630However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005631variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005632 :let foo='a + b'
5633 :echo c{foo}d
5634.. since the result of expansion is "ca + bd", which is not a variable name.
5635
5636 *curly-braces-function-names*
5637You can call and define functions by an evaluated name in a similar way.
5638Example: >
5639 :let func_end='whizz'
5640 :call my_func_{func_end}(parameter)
5641
5642This would call the function "my_func_whizz(parameter)".
5643
5644==============================================================================
56457. Commands *expression-commands*
5646
5647:let {var-name} = {expr1} *:let* *E18*
5648 Set internal variable {var-name} to the result of the
5649 expression {expr1}. The variable will get the type
5650 from the {expr}. If {var-name} didn't exist yet, it
5651 is created.
5652
Bram Moolenaar13065c42005-01-08 16:08:21 +00005653:let {var-name}[{idx}] = {expr1} *E689*
5654 Set a list item to the result of the expression
5655 {expr1}. {var-name} must refer to a list and {idx}
5656 must be a valid index in that list. For nested list
5657 the index can be repeated.
5658 This cannot be used to add an item to a list.
5659
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005660 *E711* *E719*
5661:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005662 Set a sequence of items in a |List| to the result of
5663 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005664 correct number of items.
5665 {idx1} can be omitted, zero is used instead.
5666 {idx2} can be omitted, meaning the end of the list.
5667 When the selected range of items is partly past the
5668 end of the list, items will be added.
5669
Bram Moolenaar748bf032005-02-02 23:04:36 +00005670 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005671:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
5672:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
5673:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
5674 These fail if {var} was not set yet and when the type
5675 of {var} and {expr1} don't fit the operator.
5676
5677
Bram Moolenaar071d4272004-06-13 20:20:40 +00005678:let ${env-name} = {expr1} *:let-environment* *:let-$*
5679 Set environment variable {env-name} to the result of
5680 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005681:let ${env-name} .= {expr1}
5682 Append {expr1} to the environment variable {env-name}.
5683 If the environment variable didn't exist yet this
5684 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005685
5686:let @{reg-name} = {expr1} *:let-register* *:let-@*
5687 Write the result of the expression {expr1} in register
5688 {reg-name}. {reg-name} must be a single letter, and
5689 must be the name of a writable register (see
5690 |registers|). "@@" can be used for the unnamed
5691 register, "@/" for the search pattern.
5692 If the result of {expr1} ends in a <CR> or <NL>, the
5693 register will be linewise, otherwise it will be set to
5694 characterwise.
5695 This can be used to clear the last search pattern: >
5696 :let @/ = ""
5697< This is different from searching for an empty string,
5698 that would match everywhere.
5699
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005700:let @{reg-name} .= {expr1}
5701 Append {expr1} to register {reg-name}. If the
5702 register was empty it's like setting it to {expr1}.
5703
Bram Moolenaar071d4272004-06-13 20:20:40 +00005704:let &{option-name} = {expr1} *:let-option* *:let-star*
5705 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005706 expression {expr1}. A String or Number value is
5707 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005708 For an option local to a window or buffer the effect
5709 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00005710 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005711 Example: >
5712 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00005713
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005714:let &{option-name} .= {expr1}
5715 For a string option: Append {expr1} to the value.
5716 Does not insert a comma like |:set+=|.
5717
5718:let &{option-name} += {expr1}
5719:let &{option-name} -= {expr1}
5720 For a number or boolean option: Add or subtract
5721 {expr1}.
5722
Bram Moolenaar071d4272004-06-13 20:20:40 +00005723:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005724:let &l:{option-name} .= {expr1}
5725:let &l:{option-name} += {expr1}
5726:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005727 Like above, but only set the local value of an option
5728 (if there is one). Works like |:setlocal|.
5729
5730:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005731:let &g:{option-name} .= {expr1}
5732:let &g:{option-name} += {expr1}
5733:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005734 Like above, but only set the global value of an option
5735 (if there is one). Works like |:setglobal|.
5736
Bram Moolenaar13065c42005-01-08 16:08:21 +00005737:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005738 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005739 the list is assigned to {name1}, the second item to
5740 {name2}, etc.
5741 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005742 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005743 Each name can be one of the items of the ":let"
5744 command as mentioned above.
5745 Example: >
5746 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005747< Detail: {expr1} is evaluated first, then the
5748 assignments are done in sequence. This matters if
5749 {name2} depends on {name1}. Example: >
5750 :let x = [0, 1]
5751 :let i = 0
5752 :let [i, x[i]] = [1, 2]
5753 :echo x
5754< The result is [0, 2].
5755
5756:let [{name1}, {name2}, ...] .= {expr1}
5757:let [{name1}, {name2}, ...] += {expr1}
5758:let [{name1}, {name2}, ...] -= {expr1}
5759 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005760 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005761
5762:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005763 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005764 items than there are names. A list of the remaining
5765 items is assigned to {lastname}. If there are no
5766 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00005767 Example: >
5768 :let [a, b; rest] = ["aval", "bval", 3, 4]
5769<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005770:let [{name}, ..., ; {lastname}] .= {expr1}
5771:let [{name}, ..., ; {lastname}] += {expr1}
5772:let [{name}, ..., ; {lastname}] -= {expr1}
5773 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005774 |List| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005775 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005776:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00005777 variable names may be given. Special names recognized
5778 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00005779 g: global variables
5780 b: local buffer variables
5781 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005782 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00005783 s: script-local variables
5784 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00005785 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005786
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005787:let List the values of all variables. The type of the
5788 variable is indicated before the value:
5789 <nothing> String
5790 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005791 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00005792
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005793
5794:unl[et][!] {name} ... *:unlet* *:unl* *E108*
5795 Remove the internal variable {name}. Several variable
5796 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005797 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005798 With [!] no error message is given for non-existing
5799 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005800 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00005801 :unlet list[3] " remove fourth item
5802 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005803< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00005804 :unlet dict['two']
5805 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00005806
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005807:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
5808 Lock the internal variable {name}. Locking means that
5809 it can no longer be changed (until it is unlocked).
5810 A locked variable can be deleted: >
5811 :lockvar v
5812 :let v = 'asdf' " fails!
5813 :unlet v
5814< *E741*
5815 If you try to change a locked variable you get an
5816 error message: "E741: Value of {name} is locked"
5817
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005818 [depth] is relevant when locking a |List| or
5819 |Dictionary|. It specifies how deep the locking goes:
5820 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005821 cannot add or remove items, but can
5822 still change their values.
5823 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005824 the items. If an item is a |List| or
5825 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005826 items, but can still change the
5827 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005828 3 Like 2 but for the |List| /
5829 |Dictionary| in the |List| /
5830 |Dictionary|, one level deeper.
5831 The default [depth] is 2, thus when {name} is a |List|
5832 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005833 *E743*
5834 For unlimited depth use [!] and omit [depth].
5835 However, there is a maximum depth of 100 to catch
5836 loops.
5837
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005838 Note that when two variables refer to the same |List|
5839 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005840 locked when used through the other variable.
5841 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005842 :let l = [0, 1, 2, 3]
5843 :let cl = l
5844 :lockvar l
5845 :let cl[1] = 99 " won't work!
5846< You may want to make a copy of a list to avoid this.
5847 See |deepcopy()|.
5848
5849
5850:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
5851 Unlock the internal variable {name}. Does the
5852 opposite of |:lockvar|.
5853
5854
Bram Moolenaar071d4272004-06-13 20:20:40 +00005855:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
5856:en[dif] Execute the commands until the next matching ":else"
5857 or ":endif" if {expr1} evaluates to non-zero.
5858
5859 From Vim version 4.5 until 5.0, every Ex command in
5860 between the ":if" and ":endif" is ignored. These two
5861 commands were just to allow for future expansions in a
5862 backwards compatible way. Nesting was allowed. Note
5863 that any ":else" or ":elseif" was ignored, the "else"
5864 part was not executed either.
5865
5866 You can use this to remain compatible with older
5867 versions: >
5868 :if version >= 500
5869 : version-5-specific-commands
5870 :endif
5871< The commands still need to be parsed to find the
5872 "endif". Sometimes an older Vim has a problem with a
5873 new command. For example, ":silent" is recognized as
5874 a ":substitute" command. In that case ":execute" can
5875 avoid problems: >
5876 :if version >= 600
5877 : execute "silent 1,$delete"
5878 :endif
5879<
5880 NOTE: The ":append" and ":insert" commands don't work
5881 properly in between ":if" and ":endif".
5882
5883 *:else* *:el* *E581* *E583*
5884:el[se] Execute the commands until the next matching ":else"
5885 or ":endif" if they previously were not being
5886 executed.
5887
5888 *:elseif* *:elsei* *E582* *E584*
5889:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
5890 is no extra ":endif".
5891
5892:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005893 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005894:endw[hile] Repeat the commands between ":while" and ":endwhile",
5895 as long as {expr1} evaluates to non-zero.
5896 When an error is detected from a command inside the
5897 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00005898 Example: >
5899 :let lnum = 1
5900 :while lnum <= line("$")
5901 :call FixLine(lnum)
5902 :let lnum = lnum + 1
5903 :endwhile
5904<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005905 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00005906 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005907
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005908:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00005909:endfo[r] *:endfo* *:endfor*
5910 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005911 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005912 value of each item.
5913 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00005914 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00005915 Changing {list} inside the loop affects what items are
5916 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005917 :for item in copy(mylist)
5918< When not making a copy, Vim stores a reference to the
5919 next item in the list, before executing the commands
5920 with the current item. Thus the current item can be
5921 removed without effect. Removing any later item means
5922 it will not be found. Thus the following example
5923 works (an inefficient way to make a list empty): >
5924 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00005925 :call remove(mylist, 0)
5926 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005927< Note that reordering the list (e.g., with sort() or
5928 reverse()) may have unexpected effects.
5929 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00005930 identical to avoid errors for the type of {var}
5931 changing. Unlet the variable at the end of the loop
5932 to allow multiple item types.
5933
Bram Moolenaar12805862005-01-05 22:16:17 +00005934:for [{var1}, {var2}, ...] in {listlist}
5935:endfo[r]
5936 Like ":for" above, but each item in {listlist} must be
5937 a list, of which each item is assigned to {var1},
5938 {var2}, etc. Example: >
5939 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
5940 :echo getline(lnum)[col]
5941 :endfor
5942<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005943 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00005944:con[tinue] When used inside a ":while" or ":for" loop, jumps back
5945 to the start of the loop.
5946 If it is used after a |:try| inside the loop but
5947 before the matching |:finally| (if present), the
5948 commands following the ":finally" up to the matching
5949 |:endtry| are executed first. This process applies to
5950 all nested ":try"s inside the loop. The outermost
5951 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005952
5953 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00005954:brea[k] When used inside a ":while" or ":for" loop, skips to
5955 the command after the matching ":endwhile" or
5956 ":endfor".
5957 If it is used after a |:try| inside the loop but
5958 before the matching |:finally| (if present), the
5959 commands following the ":finally" up to the matching
5960 |:endtry| are executed first. This process applies to
5961 all nested ":try"s inside the loop. The outermost
5962 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005963
5964:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
5965:endt[ry] Change the error handling for the commands between
5966 ":try" and ":endtry" including everything being
5967 executed across ":source" commands, function calls,
5968 or autocommand invocations.
5969
5970 When an error or interrupt is detected and there is
5971 a |:finally| command following, execution continues
5972 after the ":finally". Otherwise, or when the
5973 ":endtry" is reached thereafter, the next
5974 (dynamically) surrounding ":try" is checked for
5975 a corresponding ":finally" etc. Then the script
5976 processing is terminated. (Whether a function
5977 definition has an "abort" argument does not matter.)
5978 Example: >
5979 :try | edit too much | finally | echo "cleanup" | endtry
5980 :echo "impossible" " not reached, script terminated above
5981<
5982 Moreover, an error or interrupt (dynamically) inside
5983 ":try" and ":endtry" is converted to an exception. It
5984 can be caught as if it were thrown by a |:throw|
5985 command (see |:catch|). In this case, the script
5986 processing is not terminated.
5987
5988 The value "Vim:Interrupt" is used for an interrupt
5989 exception. An error in a Vim command is converted
5990 to a value of the form "Vim({command}):{errmsg}",
5991 other errors are converted to a value of the form
5992 "Vim:{errmsg}". {command} is the full command name,
5993 and {errmsg} is the message that is displayed if the
5994 error exception is not caught, always beginning with
5995 the error number.
5996 Examples: >
5997 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
5998 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
5999<
6000 *:cat* *:catch* *E603* *E604* *E605*
6001:cat[ch] /{pattern}/ The following commands until the next ":catch",
6002 |:finally|, or |:endtry| that belongs to the same
6003 |:try| as the ":catch" are executed when an exception
6004 matching {pattern} is being thrown and has not yet
6005 been caught by a previous ":catch". Otherwise, these
6006 commands are skipped.
6007 When {pattern} is omitted all errors are caught.
6008 Examples: >
6009 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
6010 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
6011 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
6012 :catch /^Vim(write):/ " catch all errors in :write
6013 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
6014 :catch /my-exception/ " catch user exception
6015 :catch /.*/ " catch everything
6016 :catch " same as /.*/
6017<
6018 Another character can be used instead of / around the
6019 {pattern}, so long as it does not have a special
6020 meaning (e.g., '|' or '"') and doesn't occur inside
6021 {pattern}.
6022 NOTE: It is not reliable to ":catch" the TEXT of
6023 an error message because it may vary in different
6024 locales.
6025
6026 *:fina* *:finally* *E606* *E607*
6027:fina[lly] The following commands until the matching |:endtry|
6028 are executed whenever the part between the matching
6029 |:try| and the ":finally" is left: either by falling
6030 through to the ":finally" or by a |:continue|,
6031 |:break|, |:finish|, or |:return|, or by an error or
6032 interrupt or exception (see |:throw|).
6033
6034 *:th* *:throw* *E608*
6035:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
6036 If the ":throw" is used after a |:try| but before the
6037 first corresponding |:catch|, commands are skipped
6038 until the first ":catch" matching {expr1} is reached.
6039 If there is no such ":catch" or if the ":throw" is
6040 used after a ":catch" but before the |:finally|, the
6041 commands following the ":finally" (if present) up to
6042 the matching |:endtry| are executed. If the ":throw"
6043 is after the ":finally", commands up to the ":endtry"
6044 are skipped. At the ":endtry", this process applies
6045 again for the next dynamically surrounding ":try"
6046 (which may be found in a calling function or sourcing
6047 script), until a matching ":catch" has been found.
6048 If the exception is not caught, the command processing
6049 is terminated.
6050 Example: >
6051 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
6052<
6053
6054 *:ec* *:echo*
6055:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
6056 first {expr1} starts on a new line.
6057 Also see |:comment|.
6058 Use "\n" to start a new line. Use "\r" to move the
6059 cursor to the first column.
6060 Uses the highlighting set by the |:echohl| command.
6061 Cannot be followed by a comment.
6062 Example: >
6063 :echo "the value of 'shell' is" &shell
6064< A later redraw may make the message disappear again.
6065 To avoid that a command from before the ":echo" causes
6066 a redraw afterwards (redraws are often postponed until
6067 you type something), force a redraw with the |:redraw|
6068 command. Example: >
6069 :new | redraw | echo "there is a new window"
6070<
6071 *:echon*
6072:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
6073 |:comment|.
6074 Uses the highlighting set by the |:echohl| command.
6075 Cannot be followed by a comment.
6076 Example: >
6077 :echon "the value of 'shell' is " &shell
6078<
6079 Note the difference between using ":echo", which is a
6080 Vim command, and ":!echo", which is an external shell
6081 command: >
6082 :!echo % --> filename
6083< The arguments of ":!" are expanded, see |:_%|. >
6084 :!echo "%" --> filename or "filename"
6085< Like the previous example. Whether you see the double
6086 quotes or not depends on your 'shell'. >
6087 :echo % --> nothing
6088< The '%' is an illegal character in an expression. >
6089 :echo "%" --> %
6090< This just echoes the '%' character. >
6091 :echo expand("%") --> filename
6092< This calls the expand() function to expand the '%'.
6093
6094 *:echoh* *:echohl*
6095:echoh[l] {name} Use the highlight group {name} for the following
6096 |:echo|, |:echon| and |:echomsg| commands. Also used
6097 for the |input()| prompt. Example: >
6098 :echohl WarningMsg | echo "Don't panic!" | echohl None
6099< Don't forget to set the group back to "None",
6100 otherwise all following echo's will be highlighted.
6101
6102 *:echom* *:echomsg*
6103:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
6104 message in the |message-history|.
6105 Spaces are placed between the arguments as with the
6106 |:echo| command. But unprintable characters are
6107 displayed, not interpreted.
6108 Uses the highlighting set by the |:echohl| command.
6109 Example: >
6110 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
6111<
6112 *:echoe* *:echoerr*
6113:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
6114 message in the |message-history|. When used in a
6115 script or function the line number will be added.
6116 Spaces are placed between the arguments as with the
6117 :echo command. When used inside a try conditional,
6118 the message is raised as an error exception instead
6119 (see |try-echoerr|).
6120 Example: >
6121 :echoerr "This script just failed!"
6122< If you just want a highlighted message use |:echohl|.
6123 And to get a beep: >
6124 :exe "normal \<Esc>"
6125<
6126 *:exe* *:execute*
6127:exe[cute] {expr1} .. Executes the string that results from the evaluation
6128 of {expr1} as an Ex command. Multiple arguments are
6129 concatenated, with a space in between. {expr1} is
6130 used as the processed command, command line editing
6131 keys are not recognized.
6132 Cannot be followed by a comment.
6133 Examples: >
6134 :execute "buffer " nextbuf
6135 :execute "normal " count . "w"
6136<
6137 ":execute" can be used to append a command to commands
6138 that don't accept a '|'. Example: >
6139 :execute '!ls' | echo "theend"
6140
6141< ":execute" is also a nice way to avoid having to type
6142 control characters in a Vim script for a ":normal"
6143 command: >
6144 :execute "normal ixxx\<Esc>"
6145< This has an <Esc> character, see |expr-string|.
6146
6147 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00006148 you cannot start or end a "while", "for" or "if"
6149 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006150 :execute 'while i > 5'
6151 :execute 'echo "test" | break'
6152<
6153 It is allowed to have a "while" or "if" command
6154 completely in the executed string: >
6155 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
6156<
6157
6158 *:comment*
6159 ":execute", ":echo" and ":echon" cannot be followed by
6160 a comment directly, because they see the '"' as the
6161 start of a string. But, you can use '|' followed by a
6162 comment. Example: >
6163 :echo "foo" | "this is a comment
6164
6165==============================================================================
61668. Exception handling *exception-handling*
6167
6168The Vim script language comprises an exception handling feature. This section
6169explains how it can be used in a Vim script.
6170
6171Exceptions may be raised by Vim on an error or on interrupt, see
6172|catch-errors| and |catch-interrupt|. You can also explicitly throw an
6173exception by using the ":throw" command, see |throw-catch|.
6174
6175
6176TRY CONDITIONALS *try-conditionals*
6177
6178Exceptions can be caught or can cause cleanup code to be executed. You can
6179use a try conditional to specify catch clauses (that catch exceptions) and/or
6180a finally clause (to be executed for cleanup).
6181 A try conditional begins with a |:try| command and ends at the matching
6182|:endtry| command. In between, you can use a |:catch| command to start
6183a catch clause, or a |:finally| command to start a finally clause. There may
6184be none or multiple catch clauses, but there is at most one finally clause,
6185which must not be followed by any catch clauses. The lines before the catch
6186clauses and the finally clause is called a try block. >
6187
6188 :try
6189 : ...
6190 : ... TRY BLOCK
6191 : ...
6192 :catch /{pattern}/
6193 : ...
6194 : ... CATCH CLAUSE
6195 : ...
6196 :catch /{pattern}/
6197 : ...
6198 : ... CATCH CLAUSE
6199 : ...
6200 :finally
6201 : ...
6202 : ... FINALLY CLAUSE
6203 : ...
6204 :endtry
6205
6206The try conditional allows to watch code for exceptions and to take the
6207appropriate actions. Exceptions from the try block may be caught. Exceptions
6208from the try block and also the catch clauses may cause cleanup actions.
6209 When no exception is thrown during execution of the try block, the control
6210is transferred to the finally clause, if present. After its execution, the
6211script continues with the line following the ":endtry".
6212 When an exception occurs during execution of the try block, the remaining
6213lines in the try block are skipped. The exception is matched against the
6214patterns specified as arguments to the ":catch" commands. The catch clause
6215after the first matching ":catch" is taken, other catch clauses are not
6216executed. The catch clause ends when the next ":catch", ":finally", or
6217":endtry" command is reached - whatever is first. Then, the finally clause
6218(if present) is executed. When the ":endtry" is reached, the script execution
6219continues in the following line as usual.
6220 When an exception that does not match any of the patterns specified by the
6221":catch" commands is thrown in the try block, the exception is not caught by
6222that try conditional and none of the catch clauses is executed. Only the
6223finally clause, if present, is taken. The exception pends during execution of
6224the finally clause. It is resumed at the ":endtry", so that commands after
6225the ":endtry" are not executed and the exception might be caught elsewhere,
6226see |try-nesting|.
6227 When during execution of a catch clause another exception is thrown, the
6228remaining lines in that catch clause are not executed. The new exception is
6229not matched against the patterns in any of the ":catch" commands of the same
6230try conditional and none of its catch clauses is taken. If there is, however,
6231a finally clause, it is executed, and the exception pends during its
6232execution. The commands following the ":endtry" are not executed. The new
6233exception might, however, be caught elsewhere, see |try-nesting|.
6234 When during execution of the finally clause (if present) an exception is
6235thrown, the remaining lines in the finally clause are skipped. If the finally
6236clause has been taken because of an exception from the try block or one of the
6237catch clauses, the original (pending) exception is discarded. The commands
6238following the ":endtry" are not executed, and the exception from the finally
6239clause is propagated and can be caught elsewhere, see |try-nesting|.
6240
6241The finally clause is also executed, when a ":break" or ":continue" for
6242a ":while" loop enclosing the complete try conditional is executed from the
6243try block or a catch clause. Or when a ":return" or ":finish" is executed
6244from the try block or a catch clause of a try conditional in a function or
6245sourced script, respectively. The ":break", ":continue", ":return", or
6246":finish" pends during execution of the finally clause and is resumed when the
6247":endtry" is reached. It is, however, discarded when an exception is thrown
6248from the finally clause.
6249 When a ":break" or ":continue" for a ":while" loop enclosing the complete
6250try conditional or when a ":return" or ":finish" is encountered in the finally
6251clause, the rest of the finally clause is skipped, and the ":break",
6252":continue", ":return" or ":finish" is executed as usual. If the finally
6253clause has been taken because of an exception or an earlier ":break",
6254":continue", ":return", or ":finish" from the try block or a catch clause,
6255this pending exception or command is discarded.
6256
6257For examples see |throw-catch| and |try-finally|.
6258
6259
6260NESTING OF TRY CONDITIONALS *try-nesting*
6261
6262Try conditionals can be nested arbitrarily. That is, a complete try
6263conditional can be put into the try block, a catch clause, or the finally
6264clause of another try conditional. If the inner try conditional does not
6265catch an exception thrown in its try block or throws a new exception from one
6266of its catch clauses or its finally clause, the outer try conditional is
6267checked according to the rules above. If the inner try conditional is in the
6268try block of the outer try conditional, its catch clauses are checked, but
6269otherwise only the finally clause is executed. It does not matter for
6270nesting, whether the inner try conditional is directly contained in the outer
6271one, or whether the outer one sources a script or calls a function containing
6272the inner try conditional.
6273
6274When none of the active try conditionals catches an exception, just their
6275finally clauses are executed. Thereafter, the script processing terminates.
6276An error message is displayed in case of an uncaught exception explicitly
6277thrown by a ":throw" command. For uncaught error and interrupt exceptions
6278implicitly raised by Vim, the error message(s) or interrupt message are shown
6279as usual.
6280
6281For examples see |throw-catch|.
6282
6283
6284EXAMINING EXCEPTION HANDLING CODE *except-examine*
6285
6286Exception handling code can get tricky. If you are in doubt what happens, set
6287'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
6288script file. Then you see when an exception is thrown, discarded, caught, or
6289finished. When using a verbosity level of at least 14, things pending in
6290a finally clause are also shown. This information is also given in debug mode
6291(see |debug-scripts|).
6292
6293
6294THROWING AND CATCHING EXCEPTIONS *throw-catch*
6295
6296You can throw any number or string as an exception. Use the |:throw| command
6297and pass the value to be thrown as argument: >
6298 :throw 4711
6299 :throw "string"
6300< *throw-expression*
6301You can also specify an expression argument. The expression is then evaluated
6302first, and the result is thrown: >
6303 :throw 4705 + strlen("string")
6304 :throw strpart("strings", 0, 6)
6305
6306An exception might be thrown during evaluation of the argument of the ":throw"
6307command. Unless it is caught there, the expression evaluation is abandoned.
6308The ":throw" command then does not throw a new exception.
6309 Example: >
6310
6311 :function! Foo(arg)
6312 : try
6313 : throw a:arg
6314 : catch /foo/
6315 : endtry
6316 : return 1
6317 :endfunction
6318 :
6319 :function! Bar()
6320 : echo "in Bar"
6321 : return 4710
6322 :endfunction
6323 :
6324 :throw Foo("arrgh") + Bar()
6325
6326This throws "arrgh", and "in Bar" is not displayed since Bar() is not
6327executed. >
6328 :throw Foo("foo") + Bar()
6329however displays "in Bar" and throws 4711.
6330
6331Any other command that takes an expression as argument might also be
6332abandoned by an (uncaught) exception during the expression evaluation. The
6333exception is then propagated to the caller of the command.
6334 Example: >
6335
6336 :if Foo("arrgh")
6337 : echo "then"
6338 :else
6339 : echo "else"
6340 :endif
6341
6342Here neither of "then" or "else" is displayed.
6343
6344 *catch-order*
6345Exceptions can be caught by a try conditional with one or more |:catch|
6346commands, see |try-conditionals|. The values to be caught by each ":catch"
6347command can be specified as a pattern argument. The subsequent catch clause
6348gets executed when a matching exception is caught.
6349 Example: >
6350
6351 :function! Foo(value)
6352 : try
6353 : throw a:value
6354 : catch /^\d\+$/
6355 : echo "Number thrown"
6356 : catch /.*/
6357 : echo "String thrown"
6358 : endtry
6359 :endfunction
6360 :
6361 :call Foo(0x1267)
6362 :call Foo('string')
6363
6364The first call to Foo() displays "Number thrown", the second "String thrown".
6365An exception is matched against the ":catch" commands in the order they are
6366specified. Only the first match counts. So you should place the more
6367specific ":catch" first. The following order does not make sense: >
6368
6369 : catch /.*/
6370 : echo "String thrown"
6371 : catch /^\d\+$/
6372 : echo "Number thrown"
6373
6374The first ":catch" here matches always, so that the second catch clause is
6375never taken.
6376
6377 *throw-variables*
6378If you catch an exception by a general pattern, you may access the exact value
6379in the variable |v:exception|: >
6380
6381 : catch /^\d\+$/
6382 : echo "Number thrown. Value is" v:exception
6383
6384You may also be interested where an exception was thrown. This is stored in
6385|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
6386exception most recently caught as long it is not finished.
6387 Example: >
6388
6389 :function! Caught()
6390 : if v:exception != ""
6391 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
6392 : else
6393 : echo 'Nothing caught'
6394 : endif
6395 :endfunction
6396 :
6397 :function! Foo()
6398 : try
6399 : try
6400 : try
6401 : throw 4711
6402 : finally
6403 : call Caught()
6404 : endtry
6405 : catch /.*/
6406 : call Caught()
6407 : throw "oops"
6408 : endtry
6409 : catch /.*/
6410 : call Caught()
6411 : finally
6412 : call Caught()
6413 : endtry
6414 :endfunction
6415 :
6416 :call Foo()
6417
6418This displays >
6419
6420 Nothing caught
6421 Caught "4711" in function Foo, line 4
6422 Caught "oops" in function Foo, line 10
6423 Nothing caught
6424
6425A practical example: The following command ":LineNumber" displays the line
6426number in the script or function where it has been used: >
6427
6428 :function! LineNumber()
6429 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
6430 :endfunction
6431 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
6432<
6433 *try-nested*
6434An exception that is not caught by a try conditional can be caught by
6435a surrounding try conditional: >
6436
6437 :try
6438 : try
6439 : throw "foo"
6440 : catch /foobar/
6441 : echo "foobar"
6442 : finally
6443 : echo "inner finally"
6444 : endtry
6445 :catch /foo/
6446 : echo "foo"
6447 :endtry
6448
6449The inner try conditional does not catch the exception, just its finally
6450clause is executed. The exception is then caught by the outer try
6451conditional. The example displays "inner finally" and then "foo".
6452
6453 *throw-from-catch*
6454You can catch an exception and throw a new one to be caught elsewhere from the
6455catch clause: >
6456
6457 :function! Foo()
6458 : throw "foo"
6459 :endfunction
6460 :
6461 :function! Bar()
6462 : try
6463 : call Foo()
6464 : catch /foo/
6465 : echo "Caught foo, throw bar"
6466 : throw "bar"
6467 : endtry
6468 :endfunction
6469 :
6470 :try
6471 : call Bar()
6472 :catch /.*/
6473 : echo "Caught" v:exception
6474 :endtry
6475
6476This displays "Caught foo, throw bar" and then "Caught bar".
6477
6478 *rethrow*
6479There is no real rethrow in the Vim script language, but you may throw
6480"v:exception" instead: >
6481
6482 :function! Bar()
6483 : try
6484 : call Foo()
6485 : catch /.*/
6486 : echo "Rethrow" v:exception
6487 : throw v:exception
6488 : endtry
6489 :endfunction
6490< *try-echoerr*
6491Note that this method cannot be used to "rethrow" Vim error or interrupt
6492exceptions, because it is not possible to fake Vim internal exceptions.
6493Trying so causes an error exception. You should throw your own exception
6494denoting the situation. If you want to cause a Vim error exception containing
6495the original error exception value, you can use the |:echoerr| command: >
6496
6497 :try
6498 : try
6499 : asdf
6500 : catch /.*/
6501 : echoerr v:exception
6502 : endtry
6503 :catch /.*/
6504 : echo v:exception
6505 :endtry
6506
6507This code displays
6508
6509 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
6510
6511
6512CLEANUP CODE *try-finally*
6513
6514Scripts often change global settings and restore them at their end. If the
6515user however interrupts the script by pressing CTRL-C, the settings remain in
6516an inconsistent state. The same may happen to you in the development phase of
6517a script when an error occurs or you explicitly throw an exception without
6518catching it. You can solve these problems by using a try conditional with
6519a finally clause for restoring the settings. Its execution is guaranteed on
6520normal control flow, on error, on an explicit ":throw", and on interrupt.
6521(Note that errors and interrupts from inside the try conditional are converted
6522to exceptions. When not caught, they terminate the script after the finally
6523clause has been executed.)
6524Example: >
6525
6526 :try
6527 : let s:saved_ts = &ts
6528 : set ts=17
6529 :
6530 : " Do the hard work here.
6531 :
6532 :finally
6533 : let &ts = s:saved_ts
6534 : unlet s:saved_ts
6535 :endtry
6536
6537This method should be used locally whenever a function or part of a script
6538changes global settings which need to be restored on failure or normal exit of
6539that function or script part.
6540
6541 *break-finally*
6542Cleanup code works also when the try block or a catch clause is left by
6543a ":continue", ":break", ":return", or ":finish".
6544 Example: >
6545
6546 :let first = 1
6547 :while 1
6548 : try
6549 : if first
6550 : echo "first"
6551 : let first = 0
6552 : continue
6553 : else
6554 : throw "second"
6555 : endif
6556 : catch /.*/
6557 : echo v:exception
6558 : break
6559 : finally
6560 : echo "cleanup"
6561 : endtry
6562 : echo "still in while"
6563 :endwhile
6564 :echo "end"
6565
6566This displays "first", "cleanup", "second", "cleanup", and "end". >
6567
6568 :function! Foo()
6569 : try
6570 : return 4711
6571 : finally
6572 : echo "cleanup\n"
6573 : endtry
6574 : echo "Foo still active"
6575 :endfunction
6576 :
6577 :echo Foo() "returned by Foo"
6578
6579This displays "cleanup" and "4711 returned by Foo". You don't need to add an
6580extra ":return" in the finally clause. (Above all, this would override the
6581return value.)
6582
6583 *except-from-finally*
6584Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
6585a finally clause is possible, but not recommended since it abandons the
6586cleanup actions for the try conditional. But, of course, interrupt and error
6587exceptions might get raised from a finally clause.
6588 Example where an error in the finally clause stops an interrupt from
6589working correctly: >
6590
6591 :try
6592 : try
6593 : echo "Press CTRL-C for interrupt"
6594 : while 1
6595 : endwhile
6596 : finally
6597 : unlet novar
6598 : endtry
6599 :catch /novar/
6600 :endtry
6601 :echo "Script still running"
6602 :sleep 1
6603
6604If you need to put commands that could fail into a finally clause, you should
6605think about catching or ignoring the errors in these commands, see
6606|catch-errors| and |ignore-errors|.
6607
6608
6609CATCHING ERRORS *catch-errors*
6610
6611If you want to catch specific errors, you just have to put the code to be
6612watched in a try block and add a catch clause for the error message. The
6613presence of the try conditional causes all errors to be converted to an
6614exception. No message is displayed and |v:errmsg| is not set then. To find
6615the right pattern for the ":catch" command, you have to know how the format of
6616the error exception is.
6617 Error exceptions have the following format: >
6618
6619 Vim({cmdname}):{errmsg}
6620or >
6621 Vim:{errmsg}
6622
6623{cmdname} is the name of the command that failed; the second form is used when
6624the command name is not known. {errmsg} is the error message usually produced
6625when the error occurs outside try conditionals. It always begins with
6626a capital "E", followed by a two or three-digit error number, a colon, and
6627a space.
6628
6629Examples:
6630
6631The command >
6632 :unlet novar
6633normally produces the error message >
6634 E108: No such variable: "novar"
6635which is converted inside try conditionals to an exception >
6636 Vim(unlet):E108: No such variable: "novar"
6637
6638The command >
6639 :dwim
6640normally produces the error message >
6641 E492: Not an editor command: dwim
6642which is converted inside try conditionals to an exception >
6643 Vim:E492: Not an editor command: dwim
6644
6645You can catch all ":unlet" errors by a >
6646 :catch /^Vim(unlet):/
6647or all errors for misspelled command names by a >
6648 :catch /^Vim:E492:/
6649
6650Some error messages may be produced by different commands: >
6651 :function nofunc
6652and >
6653 :delfunction nofunc
6654both produce the error message >
6655 E128: Function name must start with a capital: nofunc
6656which is converted inside try conditionals to an exception >
6657 Vim(function):E128: Function name must start with a capital: nofunc
6658or >
6659 Vim(delfunction):E128: Function name must start with a capital: nofunc
6660respectively. You can catch the error by its number independently on the
6661command that caused it if you use the following pattern: >
6662 :catch /^Vim(\a\+):E128:/
6663
6664Some commands like >
6665 :let x = novar
6666produce multiple error messages, here: >
6667 E121: Undefined variable: novar
6668 E15: Invalid expression: novar
6669Only the first is used for the exception value, since it is the most specific
6670one (see |except-several-errors|). So you can catch it by >
6671 :catch /^Vim(\a\+):E121:/
6672
6673You can catch all errors related to the name "nofunc" by >
6674 :catch /\<nofunc\>/
6675
6676You can catch all Vim errors in the ":write" and ":read" commands by >
6677 :catch /^Vim(\(write\|read\)):E\d\+:/
6678
6679You can catch all Vim errors by the pattern >
6680 :catch /^Vim\((\a\+)\)\=:E\d\+:/
6681<
6682 *catch-text*
6683NOTE: You should never catch the error message text itself: >
6684 :catch /No such variable/
6685only works in the english locale, but not when the user has selected
6686a different language by the |:language| command. It is however helpful to
6687cite the message text in a comment: >
6688 :catch /^Vim(\a\+):E108:/ " No such variable
6689
6690
6691IGNORING ERRORS *ignore-errors*
6692
6693You can ignore errors in a specific Vim command by catching them locally: >
6694
6695 :try
6696 : write
6697 :catch
6698 :endtry
6699
6700But you are strongly recommended NOT to use this simple form, since it could
6701catch more than you want. With the ":write" command, some autocommands could
6702be executed and cause errors not related to writing, for instance: >
6703
6704 :au BufWritePre * unlet novar
6705
6706There could even be such errors you are not responsible for as a script
6707writer: a user of your script might have defined such autocommands. You would
6708then hide the error from the user.
6709 It is much better to use >
6710
6711 :try
6712 : write
6713 :catch /^Vim(write):/
6714 :endtry
6715
6716which only catches real write errors. So catch only what you'd like to ignore
6717intentionally.
6718
6719For a single command that does not cause execution of autocommands, you could
6720even suppress the conversion of errors to exceptions by the ":silent!"
6721command: >
6722 :silent! nunmap k
6723This works also when a try conditional is active.
6724
6725
6726CATCHING INTERRUPTS *catch-interrupt*
6727
6728When there are active try conditionals, an interrupt (CTRL-C) is converted to
6729the exception "Vim:Interrupt". You can catch it like every exception. The
6730script is not terminated, then.
6731 Example: >
6732
6733 :function! TASK1()
6734 : sleep 10
6735 :endfunction
6736
6737 :function! TASK2()
6738 : sleep 20
6739 :endfunction
6740
6741 :while 1
6742 : let command = input("Type a command: ")
6743 : try
6744 : if command == ""
6745 : continue
6746 : elseif command == "END"
6747 : break
6748 : elseif command == "TASK1"
6749 : call TASK1()
6750 : elseif command == "TASK2"
6751 : call TASK2()
6752 : else
6753 : echo "\nIllegal command:" command
6754 : continue
6755 : endif
6756 : catch /^Vim:Interrupt$/
6757 : echo "\nCommand interrupted"
6758 : " Caught the interrupt. Continue with next prompt.
6759 : endtry
6760 :endwhile
6761
6762You can interrupt a task here by pressing CTRL-C; the script then asks for
6763a new command. If you press CTRL-C at the prompt, the script is terminated.
6764
6765For testing what happens when CTRL-C would be pressed on a specific line in
6766your script, use the debug mode and execute the |>quit| or |>interrupt|
6767command on that line. See |debug-scripts|.
6768
6769
6770CATCHING ALL *catch-all*
6771
6772The commands >
6773
6774 :catch /.*/
6775 :catch //
6776 :catch
6777
6778catch everything, error exceptions, interrupt exceptions and exceptions
6779explicitly thrown by the |:throw| command. This is useful at the top level of
6780a script in order to catch unexpected things.
6781 Example: >
6782
6783 :try
6784 :
6785 : " do the hard work here
6786 :
6787 :catch /MyException/
6788 :
6789 : " handle known problem
6790 :
6791 :catch /^Vim:Interrupt$/
6792 : echo "Script interrupted"
6793 :catch /.*/
6794 : echo "Internal error (" . v:exception . ")"
6795 : echo " - occurred at " . v:throwpoint
6796 :endtry
6797 :" end of script
6798
6799Note: Catching all might catch more things than you want. Thus, you are
6800strongly encouraged to catch only for problems that you can really handle by
6801specifying a pattern argument to the ":catch".
6802 Example: Catching all could make it nearly impossible to interrupt a script
6803by pressing CTRL-C: >
6804
6805 :while 1
6806 : try
6807 : sleep 1
6808 : catch
6809 : endtry
6810 :endwhile
6811
6812
6813EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
6814
6815Exceptions may be used during execution of autocommands. Example: >
6816
6817 :autocmd User x try
6818 :autocmd User x throw "Oops!"
6819 :autocmd User x catch
6820 :autocmd User x echo v:exception
6821 :autocmd User x endtry
6822 :autocmd User x throw "Arrgh!"
6823 :autocmd User x echo "Should not be displayed"
6824 :
6825 :try
6826 : doautocmd User x
6827 :catch
6828 : echo v:exception
6829 :endtry
6830
6831This displays "Oops!" and "Arrgh!".
6832
6833 *except-autocmd-Pre*
6834For some commands, autocommands get executed before the main action of the
6835command takes place. If an exception is thrown and not caught in the sequence
6836of autocommands, the sequence and the command that caused its execution are
6837abandoned and the exception is propagated to the caller of the command.
6838 Example: >
6839
6840 :autocmd BufWritePre * throw "FAIL"
6841 :autocmd BufWritePre * echo "Should not be displayed"
6842 :
6843 :try
6844 : write
6845 :catch
6846 : echo "Caught:" v:exception "from" v:throwpoint
6847 :endtry
6848
6849Here, the ":write" command does not write the file currently being edited (as
6850you can see by checking 'modified'), since the exception from the BufWritePre
6851autocommand abandons the ":write". The exception is then caught and the
6852script displays: >
6853
6854 Caught: FAIL from BufWrite Auto commands for "*"
6855<
6856 *except-autocmd-Post*
6857For some commands, autocommands get executed after the main action of the
6858command has taken place. If this main action fails and the command is inside
6859an active try conditional, the autocommands are skipped and an error exception
6860is thrown that can be caught by the caller of the command.
6861 Example: >
6862
6863 :autocmd BufWritePost * echo "File successfully written!"
6864 :
6865 :try
6866 : write /i/m/p/o/s/s/i/b/l/e
6867 :catch
6868 : echo v:exception
6869 :endtry
6870
6871This just displays: >
6872
6873 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
6874
6875If you really need to execute the autocommands even when the main action
6876fails, trigger the event from the catch clause.
6877 Example: >
6878
6879 :autocmd BufWritePre * set noreadonly
6880 :autocmd BufWritePost * set readonly
6881 :
6882 :try
6883 : write /i/m/p/o/s/s/i/b/l/e
6884 :catch
6885 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
6886 :endtry
6887<
6888You can also use ":silent!": >
6889
6890 :let x = "ok"
6891 :let v:errmsg = ""
6892 :autocmd BufWritePost * if v:errmsg != ""
6893 :autocmd BufWritePost * let x = "after fail"
6894 :autocmd BufWritePost * endif
6895 :try
6896 : silent! write /i/m/p/o/s/s/i/b/l/e
6897 :catch
6898 :endtry
6899 :echo x
6900
6901This displays "after fail".
6902
6903If the main action of the command does not fail, exceptions from the
6904autocommands will be catchable by the caller of the command: >
6905
6906 :autocmd BufWritePost * throw ":-("
6907 :autocmd BufWritePost * echo "Should not be displayed"
6908 :
6909 :try
6910 : write
6911 :catch
6912 : echo v:exception
6913 :endtry
6914<
6915 *except-autocmd-Cmd*
6916For some commands, the normal action can be replaced by a sequence of
6917autocommands. Exceptions from that sequence will be catchable by the caller
6918of the command.
6919 Example: For the ":write" command, the caller cannot know whether the file
6920had actually been written when the exception occurred. You need to tell it in
6921some way. >
6922
6923 :if !exists("cnt")
6924 : let cnt = 0
6925 :
6926 : autocmd BufWriteCmd * if &modified
6927 : autocmd BufWriteCmd * let cnt = cnt + 1
6928 : autocmd BufWriteCmd * if cnt % 3 == 2
6929 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6930 : autocmd BufWriteCmd * endif
6931 : autocmd BufWriteCmd * write | set nomodified
6932 : autocmd BufWriteCmd * if cnt % 3 == 0
6933 : autocmd BufWriteCmd * throw "BufWriteCmdError"
6934 : autocmd BufWriteCmd * endif
6935 : autocmd BufWriteCmd * echo "File successfully written!"
6936 : autocmd BufWriteCmd * endif
6937 :endif
6938 :
6939 :try
6940 : write
6941 :catch /^BufWriteCmdError$/
6942 : if &modified
6943 : echo "Error on writing (file contents not changed)"
6944 : else
6945 : echo "Error after writing"
6946 : endif
6947 :catch /^Vim(write):/
6948 : echo "Error on writing"
6949 :endtry
6950
6951When this script is sourced several times after making changes, it displays
6952first >
6953 File successfully written!
6954then >
6955 Error on writing (file contents not changed)
6956then >
6957 Error after writing
6958etc.
6959
6960 *except-autocmd-ill*
6961You cannot spread a try conditional over autocommands for different events.
6962The following code is ill-formed: >
6963
6964 :autocmd BufWritePre * try
6965 :
6966 :autocmd BufWritePost * catch
6967 :autocmd BufWritePost * echo v:exception
6968 :autocmd BufWritePost * endtry
6969 :
6970 :write
6971
6972
6973EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
6974
6975Some programming languages allow to use hierarchies of exception classes or to
6976pass additional information with the object of an exception class. You can do
6977similar things in Vim.
6978 In order to throw an exception from a hierarchy, just throw the complete
6979class name with the components separated by a colon, for instance throw the
6980string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
6981 When you want to pass additional information with your exception class, add
6982it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
6983for an error when writing "myfile".
6984 With the appropriate patterns in the ":catch" command, you can catch for
6985base classes or derived classes of your hierarchy. Additional information in
6986parentheses can be cut out from |v:exception| with the ":substitute" command.
6987 Example: >
6988
6989 :function! CheckRange(a, func)
6990 : if a:a < 0
6991 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
6992 : endif
6993 :endfunction
6994 :
6995 :function! Add(a, b)
6996 : call CheckRange(a:a, "Add")
6997 : call CheckRange(a:b, "Add")
6998 : let c = a:a + a:b
6999 : if c < 0
7000 : throw "EXCEPT:MATHERR:OVERFLOW"
7001 : endif
7002 : return c
7003 :endfunction
7004 :
7005 :function! Div(a, b)
7006 : call CheckRange(a:a, "Div")
7007 : call CheckRange(a:b, "Div")
7008 : if (a:b == 0)
7009 : throw "EXCEPT:MATHERR:ZERODIV"
7010 : endif
7011 : return a:a / a:b
7012 :endfunction
7013 :
7014 :function! Write(file)
7015 : try
7016 : execute "write" a:file
7017 : catch /^Vim(write):/
7018 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
7019 : endtry
7020 :endfunction
7021 :
7022 :try
7023 :
7024 : " something with arithmetics and I/O
7025 :
7026 :catch /^EXCEPT:MATHERR:RANGE/
7027 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
7028 : echo "Range error in" function
7029 :
7030 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
7031 : echo "Math error"
7032 :
7033 :catch /^EXCEPT:IO/
7034 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
7035 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
7036 : if file !~ '^/'
7037 : let file = dir . "/" . file
7038 : endif
7039 : echo 'I/O error for "' . file . '"'
7040 :
7041 :catch /^EXCEPT/
7042 : echo "Unspecified error"
7043 :
7044 :endtry
7045
7046The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
7047a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
7048exceptions with the "Vim" prefix; they are reserved for Vim.
7049 Vim error exceptions are parameterized with the name of the command that
7050failed, if known. See |catch-errors|.
7051
7052
7053PECULIARITIES
7054 *except-compat*
7055The exception handling concept requires that the command sequence causing the
7056exception is aborted immediately and control is transferred to finally clauses
7057and/or a catch clause.
7058
7059In the Vim script language there are cases where scripts and functions
7060continue after an error: in functions without the "abort" flag or in a command
7061after ":silent!", control flow goes to the following line, and outside
7062functions, control flow goes to the line following the outermost ":endwhile"
7063or ":endif". On the other hand, errors should be catchable as exceptions
7064(thus, requiring the immediate abortion).
7065
7066This problem has been solved by converting errors to exceptions and using
7067immediate abortion (if not suppressed by ":silent!") only when a try
7068conditional is active. This is no restriction since an (error) exception can
7069be caught only from an active try conditional. If you want an immediate
7070termination without catching the error, just use a try conditional without
7071catch clause. (You can cause cleanup code being executed before termination
7072by specifying a finally clause.)
7073
7074When no try conditional is active, the usual abortion and continuation
7075behavior is used instead of immediate abortion. This ensures compatibility of
7076scripts written for Vim 6.1 and earlier.
7077
7078However, when sourcing an existing script that does not use exception handling
7079commands (or when calling one of its functions) from inside an active try
7080conditional of a new script, you might change the control flow of the existing
7081script on error. You get the immediate abortion on error and can catch the
7082error in the new script. If however the sourced script suppresses error
7083messages by using the ":silent!" command (checking for errors by testing
7084|v:errmsg| if appropriate), its execution path is not changed. The error is
7085not converted to an exception. (See |:silent|.) So the only remaining cause
7086where this happens is for scripts that don't care about errors and produce
7087error messages. You probably won't want to use such code from your new
7088scripts.
7089
7090 *except-syntax-err*
7091Syntax errors in the exception handling commands are never caught by any of
7092the ":catch" commands of the try conditional they belong to. Its finally
7093clauses, however, is executed.
7094 Example: >
7095
7096 :try
7097 : try
7098 : throw 4711
7099 : catch /\(/
7100 : echo "in catch with syntax error"
7101 : catch
7102 : echo "inner catch-all"
7103 : finally
7104 : echo "inner finally"
7105 : endtry
7106 :catch
7107 : echo 'outer catch-all caught "' . v:exception . '"'
7108 : finally
7109 : echo "outer finally"
7110 :endtry
7111
7112This displays: >
7113 inner finally
7114 outer catch-all caught "Vim(catch):E54: Unmatched \("
7115 outer finally
7116The original exception is discarded and an error exception is raised, instead.
7117
7118 *except-single-line*
7119The ":try", ":catch", ":finally", and ":endtry" commands can be put on
7120a single line, but then syntax errors may make it difficult to recognize the
7121"catch" line, thus you better avoid this.
7122 Example: >
7123 :try | unlet! foo # | catch | endtry
7124raises an error exception for the trailing characters after the ":unlet!"
7125argument, but does not see the ":catch" and ":endtry" commands, so that the
7126error exception is discarded and the "E488: Trailing characters" message gets
7127displayed.
7128
7129 *except-several-errors*
7130When several errors appear in a single command, the first error message is
7131usually the most specific one and therefor converted to the error exception.
7132 Example: >
7133 echo novar
7134causes >
7135 E121: Undefined variable: novar
7136 E15: Invalid expression: novar
7137The value of the error exception inside try conditionals is: >
7138 Vim(echo):E121: Undefined variable: novar
7139< *except-syntax-error*
7140But when a syntax error is detected after a normal error in the same command,
7141the syntax error is used for the exception being thrown.
7142 Example: >
7143 unlet novar #
7144causes >
7145 E108: No such variable: "novar"
7146 E488: Trailing characters
7147The value of the error exception inside try conditionals is: >
7148 Vim(unlet):E488: Trailing characters
7149This is done because the syntax error might change the execution path in a way
7150not intended by the user. Example: >
7151 try
7152 try | unlet novar # | catch | echo v:exception | endtry
7153 catch /.*/
7154 echo "outer catch:" v:exception
7155 endtry
7156This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
7157a "E600: Missing :endtry" error message is given, see |except-single-line|.
7158
7159==============================================================================
71609. Examples *eval-examples*
7161
7162Printing in Hex ~
7163>
7164 :" The function Nr2Hex() returns the Hex string of a number.
7165 :func Nr2Hex(nr)
7166 : let n = a:nr
7167 : let r = ""
7168 : while n
7169 : let r = '0123456789ABCDEF'[n % 16] . r
7170 : let n = n / 16
7171 : endwhile
7172 : return r
7173 :endfunc
7174
7175 :" The function String2Hex() converts each character in a string to a two
7176 :" character Hex string.
7177 :func String2Hex(str)
7178 : let out = ''
7179 : let ix = 0
7180 : while ix < strlen(a:str)
7181 : let out = out . Nr2Hex(char2nr(a:str[ix]))
7182 : let ix = ix + 1
7183 : endwhile
7184 : return out
7185 :endfunc
7186
7187Example of its use: >
7188 :echo Nr2Hex(32)
7189result: "20" >
7190 :echo String2Hex("32")
7191result: "3332"
7192
7193
7194Sorting lines (by Robert Webb) ~
7195
7196Here is a Vim script to sort lines. Highlight the lines in Vim and type
7197":Sort". This doesn't call any external programs so it'll work on any
7198platform. The function Sort() actually takes the name of a comparison
7199function as its argument, like qsort() does in C. So you could supply it
7200with different comparison functions in order to sort according to date etc.
7201>
7202 :" Function for use with Sort(), to compare two strings.
7203 :func! Strcmp(str1, str2)
7204 : if (a:str1 < a:str2)
7205 : return -1
7206 : elseif (a:str1 > a:str2)
7207 : return 1
7208 : else
7209 : return 0
7210 : endif
7211 :endfunction
7212
7213 :" Sort lines. SortR() is called recursively.
7214 :func! SortR(start, end, cmp)
7215 : if (a:start >= a:end)
7216 : return
7217 : endif
7218 : let partition = a:start - 1
7219 : let middle = partition
7220 : let partStr = getline((a:start + a:end) / 2)
7221 : let i = a:start
7222 : while (i <= a:end)
7223 : let str = getline(i)
7224 : exec "let result = " . a:cmp . "(str, partStr)"
7225 : if (result <= 0)
7226 : " Need to put it before the partition. Swap lines i and partition.
7227 : let partition = partition + 1
7228 : if (result == 0)
7229 : let middle = partition
7230 : endif
7231 : if (i != partition)
7232 : let str2 = getline(partition)
7233 : call setline(i, str2)
7234 : call setline(partition, str)
7235 : endif
7236 : endif
7237 : let i = i + 1
7238 : endwhile
7239
7240 : " Now we have a pointer to the "middle" element, as far as partitioning
7241 : " goes, which could be anywhere before the partition. Make sure it is at
7242 : " the end of the partition.
7243 : if (middle != partition)
7244 : let str = getline(middle)
7245 : let str2 = getline(partition)
7246 : call setline(middle, str2)
7247 : call setline(partition, str)
7248 : endif
7249 : call SortR(a:start, partition - 1, a:cmp)
7250 : call SortR(partition + 1, a:end, a:cmp)
7251 :endfunc
7252
7253 :" To Sort a range of lines, pass the range to Sort() along with the name of a
7254 :" function that will compare two lines.
7255 :func! Sort(cmp) range
7256 : call SortR(a:firstline, a:lastline, a:cmp)
7257 :endfunc
7258
7259 :" :Sort takes a range of lines and sorts them.
7260 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
7261<
7262 *sscanf*
7263There is no sscanf() function in Vim. If you need to extract parts from a
7264line, you can use matchstr() and substitute() to do it. This example shows
7265how to get the file name, line number and column number out of a line like
7266"foobar.txt, 123, 45". >
7267 :" Set up the match bit
7268 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
7269 :"get the part matching the whole expression
7270 :let l = matchstr(line, mx)
7271 :"get each item out of the match
7272 :let file = substitute(l, mx, '\1', '')
7273 :let lnum = substitute(l, mx, '\2', '')
7274 :let col = substitute(l, mx, '\3', '')
7275
7276The input is in the variable "line", the results in the variables "file",
7277"lnum" and "col". (idea from Michael Geddes)
7278
7279==============================================================================
728010. No +eval feature *no-eval-feature*
7281
7282When the |+eval| feature was disabled at compile time, none of the expression
7283evaluation commands are available. To prevent this from causing Vim scripts
7284to generate all kinds of errors, the ":if" and ":endif" commands are still
7285recognized, though the argument of the ":if" and everything between the ":if"
7286and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
7287only if the commands are at the start of the line. The ":else" command is not
7288recognized.
7289
7290Example of how to avoid executing commands when the |+eval| feature is
7291missing: >
7292
7293 :if 1
7294 : echo "Expression evaluation is compiled in"
7295 :else
7296 : echo "You will _never_ see this message"
7297 :endif
7298
7299==============================================================================
730011. The sandbox *eval-sandbox* *sandbox* *E48*
7301
7302The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
7303options are evaluated in a sandbox. This means that you are protected from
7304these expressions having nasty side effects. This gives some safety for when
7305these options are set from a modeline. It is also used when the command from
Bram Moolenaarebefac62005-12-28 22:39:57 +00007306a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007307The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007308
7309These items are not allowed in the sandbox:
7310 - changing the buffer text
7311 - defining or changing mapping, autocommands, functions, user commands
7312 - setting certain options (see |option-summary|)
7313 - executing a shell command
7314 - reading or writing a file
7315 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00007316 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007317This is not guaranteed 100% secure, but it should block most attacks.
7318
7319 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00007320:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00007321 option that may have been set from a modeline, e.g.
7322 'foldexpr'.
7323
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007324 *sandbox-option*
7325A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00007326have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007327restrictive, thus this only happens when the option was set from an insecure
7328location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007329- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007330- while executing in the sandbox
7331- value coming from a modeline
7332
7333Note that when in the sandbox and saving an option value and restoring it, the
7334option will still be marked as it was set in the sandbox.
7335
7336==============================================================================
733712. Textlock *textlock*
7338
7339In a few situations it is not allowed to change the text in the buffer, jump
7340to another window and some other things that might confuse or break what Vim
7341is currently doing. This mostly applies to things that happen when Vim is
7342actually doing something else. For example, evaluating the 'balloonexpr' may
7343happen any moment the mouse cursor is resting at some position.
7344
7345This is not allowed when the textlock is active:
7346 - changing the buffer text
7347 - jumping to another buffer or window
7348 - editing another file
7349 - closing a window or quitting Vim
7350 - etc.
7351
Bram Moolenaar071d4272004-06-13 20:20:40 +00007352
7353 vim:tw=78:ts=8:ft=help:norl: